From 5fcc4c99c13161bac6a6fdffb64982f400abc6be Mon Sep 17 00:00:00 2001 From: iven Date: Sat, 11 Apr 2026 16:23:31 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E6=B7=BB=E5=8A=A0=20Skill=20?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E9=93=BE=E8=B7=AF=20+=20MCP=20=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - hands-skills.md 标题改为 Hands + Skills + MCP - 添加 Skill 调用链路说明 (ToolRegistry → AgentLoop → execute_skill) - 添加 MCP 完整架构 (BasicMcpClient → McpToolAdapter → McpToolWrapper → ToolRegistry) - 添加 MCP 桥接机制说明 (Arc 共享 + sync_to_kernel) - 更新关键文件表 (新增 mcp_tool.rs, anthropic.rs, mcp.rs 等) - 更新 index.md 导航树 + log.md 变更记录 --- wiki/hands-skills.md | 79 +++++++++++++++++++++++++++++++++++++++++--- wiki/index.md | 2 +- wiki/log.md | 7 ++++ 3 files changed, 82 insertions(+), 6 deletions(-) diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md index 1464007..0c27f77 100644 --- a/wiki/hands-skills.md +++ b/wiki/hands-skills.md @@ -1,21 +1,22 @@ --- -title: Hands + Skills +title: Hands + Skills + MCP updated: 2026-04-11 status: active -tags: [module, hands, skills] +tags: [module, hands, skills, mcp] --- -# Hands + Skills +# Hands + Skills + MCP > 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[butler]] ## 设计思想 -**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层)** +**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层), MCP = 外部工具协议** - Hands: 浏览器自动化、数据收集、Twitter 操作等 — **执行动作** - Skills: 75 个 SKILL.md 文件 — **语义路由匹配**，增强 LLM 的领域知识 -- 触发: 用户请求 → LLM 判断需要执行 → 选择 Hand/Skill → 执行 +- MCP: Model Context Protocol — **动态外部工具**，运行时发现和调用 +- 触发: 用户请求 → LLM 判断需要执行 → 选择 Hand/Skill/MCP Tool → 执行 ## 代码逻辑 @@ -94,6 +95,68 @@ skills/ 在 kernel 中通过 `SemanticRouterAdapter` 桥接到 `ButlerRouterBackend` trait。 +### Skill 调用链路（LLM Tool Calling） + +``` +Skills 目录 → SkillRegistry 加载 → SkillIndexMiddleware(P200) 注入系统提示 + → LLM 看到 skill_load + execute_skill 工具定义 + → LLM 生成 ToolUse{skill_load} → AgentLoop 执行 → 返回技能详情 + → LLM 生成 ToolUse{execute_skill} → AgentLoop 执行 → KernelSkillExecutor + → Skill 执行结果 → ToolResult → LLM 继续对话 +``` + +关键路径： +- `kernel/mod.rs:create_tool_registry()` 注册 7 个内置工具（含 skill_load, execute_skill） +- `runtime/loop_runner.rs` 检测 `ContentBlock::ToolUse` → 调用 `Tool::execute()` +- `runtime/tool/builtin/execute_skill.rs` → `KernelSkillExecutor::execute_skill()` +- Anthropic Driver: ToolResult 必须用 `ContentBlock::ToolResult{tool_use_id, content}` 格式 + +## MCP (Model Context Protocol) + +### 概述 + +MCP 允许 ZCLAW 在运行时连接外部工具服务器（如 filesystem、database、custom tools），让 LLM 在对话中直接调用这些工具。 + +### 架构 + +``` +前端 UI (MCPServices.tsx) + → mcp-client.ts → Tauri invoke('mcp_start_service', {config}) + → McpManagerState → McpServiceManager → BasicMcpClient (stdio transport) + → MCP Server 进程 → list_tools → 注册 adapters + +LLM 对话调用: + Kernel.create_tool_registry() + → 遍历 mcp_adapters (Arc>>) + → McpToolWrapper 包装为 Tool trait + → 注册到 ToolRegistry → LLM API tool definitions + + LLM 生成 ToolUse{filesystem.read_file} + → AgentLoop → McpToolWrapper.execute() + → McpToolAdapter.execute() → MCP Server → 结果返回 +``` + +### 关键桥接机制 + +`McpManagerState` 和 `Kernel` 共享同一个 `Arc>>`： +- Kernel boot 时，`kernel_init` 将 `McpManagerState.kernel_adapters` Arc 注入到 Kernel +- MCP 服务启动/停止时，`sync_to_kernel()` 更新共享列表 +- `create_tool_registry()` 每次对话时读取最新 adapters + +### MCP Tauri 命令 (4 个) + +| 命令 | 功能 | +|------|------| +| `mcp_start_service` | 启动 MCP 服务 + 发现工具 + 同步到 Kernel | +| `mcp_stop_service` | 停止服务 + 从 Kernel 移除工具 | +| `mcp_list_services` | 列出所有运行中的服务和工具 | +| `mcp_call_tool` | 手动调用 MCP 工具（支持 service_name 精确路由） | + +### 限定名规则 + +MCP 工具在 ToolRegistry 中使用限定名 `service_name.tool_name` 避免冲突。 +例如：`filesystem.read_file`, `database.query`。 + ## 关联模块 - [[chat]] — 消息流中可能触发 Hand/Skill @@ -109,6 +172,12 @@ skills/ | `crates/zclaw-skills/src/` | 技能解析和索引 | | `skills/*/SKILL.md` | 75 个技能定义 | | `hands/*.HAND.toml` | 9 个 Hand 配置 | +| `crates/zclaw-protocols/src/mcp_tool_adapter.rs` | MCP 工具适配器 + 服务管理 | +| `crates/zclaw-protocols/src/mcp.rs` | MCP 协议类型 + BasicMcpClient | +| `crates/zclaw-runtime/src/tool/builtin/mcp_tool.rs` | McpToolWrapper (Tool trait 桥接) | +| `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Driver (含 ToolResult 格式) | | `desktop/src/store/handStore.ts` | 前端 Hand 状态 | | `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 | +| `desktop/src/lib/mcp-client.ts` | 前端 MCP 客户端 | +| `desktop/src-tauri/src/kernel_commands/mcp.rs` | MCP Tauri 命令 (4) + Kernel 桥接 | | `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) | diff --git a/wiki/index.md b/wiki/index.md index ad86db1..c435746 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -56,7 +56,7 @@ ZCLAW │ ├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入 │ -├── [[hands-skills]] Hands(9) + Skills(75) — 自主能力+语义技能路由 +├── [[hands-skills]] Hands(9) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议 │ ├── [[pipeline]] Pipeline DSL — YAML+DAG执行器+17行业模板 │ diff --git a/wiki/log.md b/wiki/log.md index c5ec531..d384ea7 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -9,6 +9,13 @@ tags: [log, history] > Append-only 操作记录。格式: `## [日期] 类型 | 描述` +## [2026-04-11] fix | Skill/MCP 调用链路修复 3 个断点 + +1. Anthropic Driver ToolResult 格式 — ContentBlock 添加 ToolResult 变体, tool_call_id 不再丢弃 +2. 前端 callMcpTool 参数名 — serviceName/toolName/args → service_name/tool_name/arguments +3. MCP 工具桥接 ToolRegistry — McpToolWrapper + Kernel mcp_adapters 共享状态 + 启停同步 +4. Wiki 更新 — hands-skills.md 添加 Skill 调用链路 + MCP 架构文档 + ## [2026-04-11] fix | 发布内测前修复 6 批次 - Batch 1: 新用户 llm_routing 默认改为 relay (SQL + migration)