118 lines
7.4 KiB
Markdown
118 lines
7.4 KiB
Markdown
---
|
||
version: 2.0
|
||
last-updated: 2026-03-09
|
||
status: design
|
||
---
|
||
|
||
# QimingClaw V2 — 完整体服务方案
|
||
|
||
> 将 QimingClaw 升级为**完整体智能服务平台**，
|
||
> 与 Qiming 服务端（如 `https://testagent.xspaceagi.com`）深度整合，
|
||
> 实现配置同步、技能同步、会话同步、多渠道接入和自我进化。
|
||
|
||
---
|
||
|
||
## 文档索引
|
||
|
||
| # | 文档 | 描述 | 优先级 |
|
||
| --- | ----------------------------------------------------------- | --------------------------------------------------- | ------ |
|
||
| 01 | [总体架构](./01-ARCHITECTURE.md) | 分层架构、与服务器的协同模型、组件关系图 | P0 |
|
||
| 02 | [模型配置](./02-MODEL-CONFIG.md) | BaseURL / API Key / 多 Provider / 与服务器同步 | P0 |
|
||
| 03 | [Skills & MCP 工具管理](./03-SKILLS-MCP.md) | MCP 协议整合、技能 CRUD、冷启动优化、统一工具层 | P0 |
|
||
| 04 | [会话管理与 Chat 流程](./04-SESSION-CHAT.md) | 会话引擎、历史会话管理、与服务器同步 | P0 |
|
||
| 05 | [Channel 多渠道接入](./05-CHANNELS.md) | 飞书 / 钉钉 / Telegram 等渠道网关 | P1 |
|
||
| 06 | [Agent 自我进化架构](./06-SELF-EVOLUTION.md) | Memory、EvoMap、Soul.md 在完整体系中的落地 | P1 |
|
||
| 07 | [知识库 · 工作流 · 插件](./07-KNOWLEDGE-WORKFLOW-PLUGIN.md) | Knowledge/RAG 同步、Workflow 编排同步、Plugin 同步 | P0 |
|
||
| 08 | [Heartbeat 与 Cron 定时任务](./08-SCHEDULER.md) | 心跳检查、定时任务调度、与服务器同步 | P1 |
|
||
| 09 | [GUI Agent 实现](./09-GUI-AGENT-IMPLEMENTATION.md) | 独立 GUI Agent 方案、MCP 集成、跨平台实现 | P0 |
|
||
|
||
---
|
||
|
||
## 核心理念
|
||
|
||
> **配置的域名本身就是一个完整的服务。**
|
||
>
|
||
> 例如 `https://testagent.xspaceagi.com` 是一个已经运行的 Qiming Agent 服务，
|
||
> 拥有完整的 API 体系（模型管理、技能管理、MCP、知识库、工作流、插件、会话、Agent 配置等）。
|
||
> QimingClaw（Electron 客户端）是这个服务的**桌面增强体**——不是替代，而是**协同**。
|
||
|
||
### Space（空间）概念
|
||
|
||
Qiming 服务以 **Space（空间）** 为核心组织单元。一个 Space 下包含：
|
||
|
||
- 智能体 (Agent)、技能 (Skill)、MCP 服务、知识库 (Knowledge)、工作流 (Workflow)、插件 (Plugin)
|
||
- 客户端需要在初始化时确定当前操作的 `spaceId`，后续所有同步以此为上下文
|
||
|
||
### 设计原则
|
||
|
||
1. **服务器为源** — 模型配置、技能、MCP、知识库、工作流等核心数据以服务器为权威来源
|
||
2. **双向同步** — 客户端可离线使用，上线后自动与服务器同步
|
||
3. **桌面增强** — 客户端提供引擎管理、本地代码执行、IM Channel 等服务器不具备的能力
|
||
4. **插件化** — Provider / Channel / Skill 均为可插拔模块
|
||
|
||
---
|
||
|
||
## 与 V1 的关系
|
||
|
||
```
|
||
V1 (当前) V2 (目标)
|
||
───────────────────── ─────────────────────
|
||
Java 后端 + lanproxy ──────→ 直连 Qiming Service（服务器同步）
|
||
ACP SDK 单一引擎 ──────→ 多 Provider + 服务器模型管理
|
||
MCP Proxy (桥接) ──────→ MCP 原生集成 + 服务器 MCP 同步 + 冷启动优化
|
||
独立的会话管理 ──────→ 与服务器会话双向同步
|
||
无 IM 集成 ──────→ 多 Channel 网关
|
||
设计阶段的进化架构 ──────→ 可落地的进化引擎
|
||
无知识库/工作流/插件 ──────→ 与服务器 Knowledge/Workflow/Plugin 同步
|
||
无定时任务 ──────→ Heartbeat 心跳 + Cron 定时任务 + 服务器同步
|
||
```
|
||
|
||
---
|
||
|
||
## 与 Qiming Server 的 API 对接总览
|
||
|
||
| 模块 | 服务器 API | 客户端行为 |
|
||
| ---------- | ----------------------------------------------------------------------------- | -------------------------------------------------- |
|
||
| 模型配置 | `/api/model/save` · `/api/model/list` · `/api/model/test-connectivity` | 从服务器拉取模型列表，客户端可新增并推送 |
|
||
| 技能管理 | `/api/skill/update` · `/api/skill/import` · `/api/skill/export` | 同步技能清单，Agent 学到的技能推送到服务器 |
|
||
| MCP 管理 | `/api/mcp/create` · `/api/mcp/update` · `/api/mcp/list/{spaceId}` | 拉取 MCP 配置并在本地启动，新增 MCP 同步到服务器 |
|
||
| 知识库 | `/api/knowledge/*` · `/api/knowledge/document/*` | 拉取知识库配置与文档，支持 RAG 查询同步 |
|
||
| 工作流 | `/api/workflow/*` · `/api/workflow/node/*` | 拉取工作流定义，本地可视化编辑与同步 |
|
||
| 插件管理 | `/api/plugin/*` · `/api/plugin/http/update` · `/api/plugin/code/update` | 拉取插件列表，HTTP/Code 插件本地调试与同步 |
|
||
| Agent 配置 | `/api/agent/config/{id}` · `/api/agent/component/*` | 拉取 Agent 完整配置（模型/技能/MCP/工作流/知识库） |
|
||
| 会话管理 | `/api/agent/conversation/*` · `/api/computer/chat` · `/api/computer/progress` | 会话和消息双向同步，Chat 直接转发 |
|
||
| 定时任务 | `/api/agent/task/*` · `/api/task/cron/list` | 任务定义双向同步，执行结果推送 |
|
||
|
||
---
|
||
|
||
## Agent 编排能力（服务器侧）
|
||
|
||
Agent 在服务器上的配置包含 **7 大 Tab**，客户端需同步和增强：
|
||
|
||
| Tab | 说明 | V2 对应文档 |
|
||
| ---- | --------------------------------- | ------------------ |
|
||
| 规划 | 系统提示词 / 用户提示词 / AI 优化 | 04-SESSION |
|
||
| 工具 | 插件 / 工作流 / MCP 三大子分类 | 03-SKILLS / 07-KWP |
|
||
| 技能 | 独立技能组件绑定 | 03-SKILLS |
|
||
| 知识 | 知识库 (RAG) 绑定 | 07-KWP |
|
||
| 记忆 | 记忆配置 | 06-EVOLUTION |
|
||
| 对话 | 预览与调试 | 04-SESSION |
|
||
| 界面 | Agent 页面配置 | - |
|
||
|
||
---
|
||
|
||
## 阅读顺序
|
||
|
||
1. **[总体架构](./01-ARCHITECTURE.md)** — 先了解全局分层与服务器协同模型
|
||
2. **[模型配置](./02-MODEL-CONFIG.md)** — 理解 Provider 抽象与服务器同步
|
||
3. **[Skills & MCP](./03-SKILLS-MCP.md)** — 工具层设计、冷启动优化与服务器同步
|
||
4. **[知识库 · 工作流 · 插件](./07-KNOWLEDGE-WORKFLOW-PLUGIN.md)** — 补充工具层
|
||
5. **[会话管理](./04-SESSION-CHAT.md)** — Chat 核心循环与服务器同步
|
||
6. **[Channel](./05-CHANNELS.md)** — 多渠道接入
|
||
7. **[Heartbeat 与 Cron](./08-SCHEDULER.md)** — 心跳检查与定时任务
|
||
8. **[自我进化](./06-SELF-EVOLUTION.md)** — 高阶能力
|
||
|
||
---
|
||
|
||
_本文档由架构维护者负责更新 · 2026-03-09_
|