From e05508bf0982cbc0c9ef9bab443405f90f8709d4 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 16:06:48 +0800 Subject: [PATCH 1/8] Integrate Anthropic blog insights batch 2: 5 docs enhanced - context-compression: Add Context Rot section (attention budget, 3 techniques) - skill-system: Add Progressive Disclosure 3-layer architecture - multi-agent: Add Progress File pattern for cross-session state - build-your-own-agent: Add tool design principles (consolidation, namespacing) - mcp-integration: Add MCP tool design principles (consolidation vs proliferation) Sources: 3 Anthropic Engineering Blog articles with exact quotes Co-Authored-By: Claude Opus 4.6 (1M context) --- .../context-compression-deep-dive.md | 20 +++++++ docs/comparison/mcp-integration-deep-dive.md | 45 +++++++++++++++ docs/comparison/multi-agent-deep-dive.md | 56 ++++++++++++++++++ docs/comparison/skill-system-deep-dive.md | 40 +++++++++++++ docs/guides/build-your-own-agent.md | 57 +++++++++++++++++++ 5 files changed, 218 insertions(+) diff --git a/docs/comparison/context-compression-deep-dive.md b/docs/comparison/context-compression-deep-dive.md index 2e351e3e..eeb335a5 100644 --- a/docs/comparison/context-compression-deep-dive.md +++ b/docs/comparison/context-compression-deep-dive.md @@ -231,6 +231,26 @@ Anthropic 工程团队在长任务 harness 开发中发现：**模型在上下 > **实践建议**：压缩阈值不应只考虑"保留多少上下文"，还应考虑"模型在多少容量下开始焦虑"。不同模型的焦虑阈值不同。 +### "Context Rot"上下文腐烂（来源：[Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)） + +与 Context Anxiety（模型主动提前结束）不同，Context Rot 是**被动的质量退化**： + +> "Every new token introduced depletes this budget by some amount." + +- Transformer 的 **n² 成对 token 关系**导致上下文越大、注意力越分散 +- 类比人类工作记忆——容量有限，信息过多会降低每条信息的处理质量 +- 好的上下文工程是找到"**最小的高信号 token 集**，最大化期望结果的概率" + +**三种对抗 Context Rot 的技术**： + +| 技术 | 说明 | 对应工具实现 | +|------|------|-----------| +| **Compaction** | 原地摘要，保留架构决策/未解决 Bug/实现细节，丢弃冗余工具输出 | Claude Code 三层压缩、Gemini CLI 四阶段 | +| **结构化笔记**（Agentic Memory） | Agent 写外部笔记，需要时拉回。"以最小开销提供持久记忆" | Claude Code auto-memory、Gemini memory_manager | +| **子代理架构** | 委托给专用子代理，返回"浓缩摘要（通常 1,000-2,000 tokens）" | Claude Code Agent 工具、Gemini 5 子代理 | + +> **核心洞察**："Context Anxiety 是模型主动逃避，Context Rot 是被动质量退化——前者可通过模型升级解决（Opus 4.5），后者是 Transformer 架构的固有限制，只能通过上下文工程缓解。" + ### 验证步骤的价值 只有 Gemini CLI 实现了独立验证（Phase 4 Probe）。其他所有工具都信任单次 LLM 输出。这是**成本与质量的核心权衡**——额外一次 LLM 调用的成本 vs 压缩质量提升。 diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index e79b3a8c..eddfe3a5 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/docs/comparison/mcp-integration-deep-dive.md @@ -250,6 +250,51 @@ Copilot CLI 内置 `github-mcp-server`，但**默认不启用所有工具**： --- +## MCP 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)） + +Anthropic 在工具设计实践中发现：**MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高**。 + +> 原文："The Model Context Protocol (MCP) can empower LLM agents with potentially hundreds of tools to solve real-world tasks." + +### 合并优于增殖 + +> 原文："More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." + +**对 MCP 服务器设计的具体影响**： + +| 设计方式 | 工具数量 | Agent 效果 | +|---------|---------|-----------| +| 每个 API 端点一个 MCP 工具 | 多（10-50+） | 工具选择困难，上下文膨胀 | +| 按任务合并为高阶工具 | 少（3-10） | 工具选择准确，token 效率高 | + +示例：与其提供 `get_customer_by_id`、`list_transactions`、`list_notes` 三个工具，不如合并为 `get_customer_context` 一个工具内部调用三个 API。 + +### 命名空间与 MCP 命名约定 + +> 原文："Namespacing tools by service and by resource can help agents select the right tools at the right time." + +这与各 Agent 的 MCP 工具命名约定直接相关： + +| Agent | 命名约定 | 命名空间效果 | +|------|---------|------------| +| **Claude Code** | `mcp__server__tool`（双下划线） | 服务级命名空间清晰 | +| **Gemini CLI** | `mcp_{server}_{tool}`（单下划线） | 服务级命名空间，但与工具名内下划线冲突风险 | +| **Goose** | 标准 MCP 发现 | 无额外命名空间 | + +> 原文关于前缀/后缀的发现："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations."——这意味着 Claude Code 的双下划线 vs Gemini CLI 的单下划线选择**可能对模型的工具选择准确率有实际影响**。 + +### 工具描述的 Prompt 工程 + +MCP 工具的 `description` 字段本质上是面向模型的 prompt——微小改动会导致 Agent 行为的显著变化： + +- 返回**语义信息**（项目名称 `"codeagents"`）而非技术 ID（`"proj_abc123"`） +- 实现**分页和过滤**，避免大量数据灌入上下文 +- 用简洁的描述写清**何时该用**这个工具，而非列出所有参数细节 + +> **实践建议**：设计 MCP 服务器时，先问"工程师能否一眼判断该用哪个工具？"——如果人类分不清，模型更分不清。宁可合并为少量高阶工具，不要创建大量低阶工具。 + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 97a67382..81329c38 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -320,6 +320,62 @@ Evaluator（评估） - 评估标准的措辞会**隐式引导 Generator**（如"museum quality"导致视觉趋同） - **Sprint 分解不是永恒的**——Sprint 最初用于所有模型（含 Opus 4.5），Opus 4.6 的长任务能力提升使得 Sprint 机制可以被完全移除（原文："I removed the sprint construct entirely"） +### Progress File 模式：跨会话状态传递（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/building-effective-agents)） + +Anthropic 在长任务 harness 开发中发现：多代理系统的关键挑战是**跨会话状态传递**——当上下文重置后，新 Agent 如何快速了解之前的工作进展？ + +**解决方案：`claude-progress.txt` + Git 历史** + +``` +Initializer Agent（首次会话） + → 创建 init.sh + → 创建 claude-progress.txt（空进展日志） + → 写入 feature-list.json（200+ 功能点，全部标记 "passes": false） + → 初始 Git commit + +Coding Agent（后续每次会话） + → 读取 claude-progress.txt + git log → 了解当前状态 + → 选择一个 failing 功能点开始工作 + → 完成后更新 claude-progress.txt + git commit + → 修改 feature-list.json 中对应功能的 "passes": true +``` + +> 原文："The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history." + +**为什么用 JSON 而非 Markdown**： + +> 原文："The model is less likely to inappropriately change or overwrite JSON files compared to Markdown files." + +**Feature List 防止提前宣告胜利**： + +```json +{ + "category": "functional", + "description": "New chat button creates a fresh conversation", + "steps": [ + "Navigate to main interface", + "Click the 'New Chat' button", + "Verify a new conversation is created" + ], + "passes": false +} +``` + +> 原文："It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality." + +**各 Agent 的跨会话状态传递实现**： + +| Agent | 状态传递机制 | 等价于 progress file | +|------|------------|-------------------| +| **Claude Code** | auto-memory + `/compact` 摘要 | 部分等价（记忆系统） | +| **Gemini CLI** | memory_manager → GEMINI.md | 部分等价（记忆文件） | +| **Aider** | 递归摘要 `done_messages` | 仅上下文内（非文件） | +| **Goose** | Recipe 配置 | ✗ | +| **OpenHands** | EventStream 持久化 | 部分等价（事件日志） | +| **自建 Harness** | `claude-progress.txt` + JSON feature list | **完整实现** | + +> **实践建议**：如果你在构建长任务多代理系统，务必实现类似 progress file 的机制。现有成品 Agent 的记忆系统（auto-memory、GEMINI.md）是轻量级替代，但缺少 JSON feature list 的"防提前完成"能力。 + ### 隔离策略 | Agent | 隔离方式 | 上下文共享 | diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index a0d84f42..6bc431ef 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -322,6 +322,46 @@ Claude Code 插件 Qwen Code / Gemini CLI --- +## 渐进式披露与上下文工程（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)） + +Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一次性灌入全部内容**，而应采用渐进式披露（Progressive Disclosure）——Agent 通过探索逐步发现相关上下文，每次交互产生的上下文为后续决策提供信息。 + +> 原文："Autonomous navigation enables progressive disclosure—agents incrementally discover relevant context through exploration." + +### 三层上下文策略 + +| 层 | 名称 | 加载时机 | 对应 Skill 实现 | +|---|------|---------|----------------| +| 1 | **预加载上下文** | 会话启动时 | AGENTS.md/CLAUDE.md 注入系统提示 | +| 2 | **即时检索** | 运行时按需 | Skill 通过 `glob`/`grep` 动态发现文件 | +| 3 | **持久化外部记忆** | 跨会话持久 | `NOTES.md`、auto-memory、progress 文件 | + +> 原文："Claude Code employs this hybrid model: CLAUDE.md files upload into context initially, while glob and grep primitives enable just-in-time file navigation." + +### 对 Skill 设计的启示 + +| 原则 | 说明 | 反面案例 | +|------|------|---------| +| **最小高信号 token 集** | Skill 正文只包含当前任务最相关的指令 | 将完整 API 文档塞入 SKILL.md | +| **简洁明确的描述** | `description` 字段用简单语言写清用途 | 模糊描述导致模型选错 Skill | +| **典型示例优于穷举** | 用 2-3 个代表性示例替代所有边界情况 | 列出 20 种输入格式的 Skill | + +> 原文："Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." + +### 各 Agent 的渐进式披露实现 + +| Agent | 预加载 | 即时检索 | 外部记忆 | +|------|--------|---------|---------| +| **Claude Code** | CLAUDE.md + 条件 Skill（`paths` glob） | Agent 工具动态发现 | auto-memory 4 类型 | +| **Gemini CLI** | GEMINI.md + activate_skill | codebase_investigator 只读探索 | memory_manager → GEMINI.md | +| **Qwen Code** | AGENTS.md + 继承 Skill | 继承 Gemini 工具集 | save_memory 工具 | +| **Kimi CLI** | 三层 Skill 发现 | Agent 工具委托 | ✗ | +| **Copilot CLI** | `.agent.yaml` 注入 | explore 代理（只读） | ✗ | + +> **实践建议**：设计 Skill 时，将**元数据层**（frontmatter）、**核心指令**（正文前半段）、**补充文件**（通过工具按需读取）分开。不要把所有信息都塞进 SKILL.md 正文——让 Agent 在执行过程中按需发现。 + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index 34652962..4f92cac8 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -379,6 +379,63 @@ for await (const event of thread.runStreamed("运行测试验证")) { --- +## 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)） + +无论选择哪条路径，工具设计都是 Agent 质量的关键。Anthropic 总结了以下经验： + +### 合并优于增殖 + +> 原文："More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." + +**反面案例**：为每个 API 端点创建独立工具（`list_users`、`list_events`、`create_event`）。 + +**推荐做法**：合并为任务导向的高阶工具（`schedule_event` 一个工具封装多个 API 调用）。 + +``` +✗ 工具增殖（7 个低阶工具） ✓ 工具合并（2 个高阶工具） +├── get_customer_by_id ├── get_customer_context +├── list_transactions │ └── 内部调用 3 个 API +├── list_notes └── search_logs +├── read_logs └── 内部过滤+分页 +├── filter_logs +├── get_customer_details +└── get_customer_history +``` + +### 命名空间策略 + +> 原文："Namespacing tools by service (e.g., `asana_search`, `jira_search`) and by resource (e.g., `asana_projects_search`, `asana_users_search`), can help agents select the right tools at the right time." + +**命名前缀 vs 后缀的选择会影响模型性能**： + +> 原文："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." + +| 命名方式 | 示例 | 适用场景 | +|---------|------|---------| +| 服务前缀 | `github_create_issue` | 同一服务多操作 | +| 资源前缀 | `issues_create`、`issues_list` | 围绕资源 CRUD | +| 动作前缀 | `search_github`、`search_jira` | 跨服务同类操作 | + +### 描述即 Prompt 工程 + +工具描述的微小改动会导致 Agent 行为的显著变化： + +- 返回**高信号语义信息**（项目名称），而非低信号技术标识（UUID） +- 实现分页、过滤和截断，附带有意义的错误消息 +- 用 2-3 个代表性示例替代穷举所有边界情况 + +### 对 SKILL.md / MCP 设计的实际指导 + +| 场景 | 工具增殖 | 工具合并 | +|------|---------|---------| +| MCP 服务器设计 | 每个 API 端点一个 MCP 工具 | 按任务合并，一个工具封装多步 | +| SKILL.md 设计 | 每个子任务一个 Skill | 一个 Skill 编排完整工作流 | +| Hook 设计 | 每个检查一个 Hook | 一个 Hook 脚本执行多项检查 | + +> **与 MCP 的关系**：Anthropic 指出 "MCP can empower LLM agents with potentially hundreds of tools"——但工具数量多不等于质量高。合并和命名空间策略对 MCP 工具同样适用。 + +--- + ## 相关资源 ### 扩展开发 From 00febf5b617b65fc7f955d819afe13537c233cd4 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 16:19:49 +0800 Subject: [PATCH 2/8] Fix 7 issues from Qwen-Code + GLM-5.1 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix "Gemini 5 子代理" ambiguity → "Gemini CLI 5 个子代理" - Weaken "可通过模型升级解决" → "显著缓解" per "largely" - Deduplicate mcp-integration vs build-your-own-agent (keep MCP-specific only) - Remove "自建 Harness" from product comparison table - Add transition sentence before test immutability quote - Fix Qwen Code "继承" → "基于...扩展" Co-Authored-By: Claude Opus 4.6 (1M context) --- .../context-compression-deep-dive.md | 4 +- docs/comparison/mcp-integration-deep-dive.md | 45 +++++-------------- docs/comparison/multi-agent-deep-dive.md | 5 ++- docs/comparison/skill-system-deep-dive.md | 2 +- 4 files changed, 18 insertions(+), 38 deletions(-) diff --git a/docs/comparison/context-compression-deep-dive.md b/docs/comparison/context-compression-deep-dive.md index eeb335a5..7a93740b 100644 --- a/docs/comparison/context-compression-deep-dive.md +++ b/docs/comparison/context-compression-deep-dive.md @@ -247,9 +247,9 @@ Anthropic 工程团队在长任务 harness 开发中发现：**模型在上下 |------|------|-----------| | **Compaction** | 原地摘要，保留架构决策/未解决 Bug/实现细节，丢弃冗余工具输出 | Claude Code 三层压缩、Gemini CLI 四阶段 | | **结构化笔记**（Agentic Memory） | Agent 写外部笔记，需要时拉回。"以最小开销提供持久记忆" | Claude Code auto-memory、Gemini memory_manager | -| **子代理架构** | 委托给专用子代理，返回"浓缩摘要（通常 1,000-2,000 tokens）" | Claude Code Agent 工具、Gemini 5 子代理 | +| **子代理架构** | 委托给专用子代理，返回"浓缩摘要（通常 1,000-2,000 tokens）" | Claude Code Agent 工具、Gemini CLI 5 个子代理 | -> **核心洞察**："Context Anxiety 是模型主动逃避，Context Rot 是被动质量退化——前者可通过模型升级解决（Opus 4.5），后者是 Transformer 架构的固有限制，只能通过上下文工程缓解。" +> **核心洞察**："Context Anxiety 是模型主动逃避，Context Rot 是被动质量退化——前者可通过模型升级显著缓解（Opus 4.5 'largely removed' 此行为，但非完全消除），后者是 Transformer 架构的固有限制，只能通过上下文工程缓解。" ### 验证步骤的价值 diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index eddfe3a5..31f2a4de 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/docs/comparison/mcp-integration-deep-dive.md @@ -252,46 +252,25 @@ Copilot CLI 内置 `github-mcp-server`，但**默认不启用所有工具**： ## MCP 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)） -Anthropic 在工具设计实践中发现：**MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高**。 +Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高。关于通用的工具设计原则（合并优于增殖、命名空间策略、描述即 Prompt 工程），详见 [构建自己的 AI 编程 Agent：工具设计原则](../guides/build-your-own-agent.md#工具设计原则来源anthropic-engineering-blog)。 -> 原文："The Model Context Protocol (MCP) can empower LLM agents with potentially hundreds of tools to solve real-world tasks." +以下聚焦于**MCP 特有的命名约定影响**： -### 合并优于增殖 +### MCP 命名约定与模型工具选择 -> 原文："More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." +> 原文："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." -**对 MCP 服务器设计的具体影响**： +各 Agent 的 MCP 命名约定差异**可能直接影响模型的工具选择准确率**： -| 设计方式 | 工具数量 | Agent 效果 | -|---------|---------|-----------| -| 每个 API 端点一个 MCP 工具 | 多（10-50+） | 工具选择困难，上下文膨胀 | -| 按任务合并为高阶工具 | 少（3-10） | 工具选择准确，token 效率高 | +| Agent | 命名约定 | 分隔符 | 命名空间效果 | +|------|---------|--------|------------| +| **Claude Code** | `mcp__server__tool` | 双下划线 | 服务级命名空间清晰，无歧义 | +| **Gemini CLI** | `mcp_{server}_{tool}` | 单下划线 | 与工具名内下划线冲突风险（如 `mcp_github_create_issue` 的边界在哪？） | +| **Goose** | 标准 MCP 发现 | — | 无额外命名空间 | -示例：与其提供 `get_customer_by_id`、`list_transactions`、`list_notes` 三个工具，不如合并为 `get_customer_context` 一个工具内部调用三个 API。 +Claude Code 选择双下划线可能正是为了避免 Gemini CLI 单下划线方案中服务名/工具名边界模糊的问题。这一设计选择值得 MCP 服务器开发者关注。 -### 命名空间与 MCP 命名约定 - -> 原文："Namespacing tools by service and by resource can help agents select the right tools at the right time." - -这与各 Agent 的 MCP 工具命名约定直接相关： - -| Agent | 命名约定 | 命名空间效果 | -|------|---------|------------| -| **Claude Code** | `mcp__server__tool`（双下划线） | 服务级命名空间清晰 | -| **Gemini CLI** | `mcp_{server}_{tool}`（单下划线） | 服务级命名空间，但与工具名内下划线冲突风险 | -| **Goose** | 标准 MCP 发现 | 无额外命名空间 | - -> 原文关于前缀/后缀的发现："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations."——这意味着 Claude Code 的双下划线 vs Gemini CLI 的单下划线选择**可能对模型的工具选择准确率有实际影响**。 - -### 工具描述的 Prompt 工程 - -MCP 工具的 `description` 字段本质上是面向模型的 prompt——微小改动会导致 Agent 行为的显著变化： - -- 返回**语义信息**（项目名称 `"codeagents"`）而非技术 ID（`"proj_abc123"`） -- 实现**分页和过滤**，避免大量数据灌入上下文 -- 用简洁的描述写清**何时该用**这个工具，而非列出所有参数细节 - -> **实践建议**：设计 MCP 服务器时，先问"工程师能否一眼判断该用哪个工具？"——如果人类分不清，模型更分不清。宁可合并为少量高阶工具，不要创建大量低阶工具。 +> **实践建议**：设计 MCP 服务器时，先问"工程师能否一眼判断该用哪个工具？"——如果人类分不清，模型更分不清。 --- diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 81329c38..459e3d45 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -361,6 +361,8 @@ Coding Agent（后续每次会话） } ``` +此外，Anthropic 还强调了功能测试列表的不可篡改性——防止 Agent 通过删除或修改测试来"伪造"进度： + > 原文："It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality." **各 Agent 的跨会话状态传递实现**： @@ -372,9 +374,8 @@ Coding Agent（后续每次会话） | **Aider** | 递归摘要 `done_messages` | 仅上下文内（非文件） | | **Goose** | Recipe 配置 | ✗ | | **OpenHands** | EventStream 持久化 | 部分等价（事件日志） | -| **自建 Harness** | `claude-progress.txt` + JSON feature list | **完整实现** | -> **实践建议**：如果你在构建长任务多代理系统，务必实现类似 progress file 的机制。现有成品 Agent 的记忆系统（auto-memory、GEMINI.md）是轻量级替代，但缺少 JSON feature list 的"防提前完成"能力。 +> **自建 Harness 的完整实现**：如果你从零构建长任务多代理系统（如 Anthropic 的 Harness 方案），可以实现 `claude-progress.txt` + JSON feature list 的完整模式——这是目前最完备的跨会话状态传递方案，但需要自建 Harness 基础设施。现有成品 Agent 的记忆系统（auto-memory、GEMINI.md）是轻量级替代，但缺少 JSON feature list 的"防提前完成"能力。 ### 隔离策略 diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index 6bc431ef..46a3b65d 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -354,7 +354,7 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 |------|--------|---------|---------| | **Claude Code** | CLAUDE.md + 条件 Skill（`paths` glob） | Agent 工具动态发现 | auto-memory 4 类型 | | **Gemini CLI** | GEMINI.md + activate_skill | codebase_investigator 只读探索 | memory_manager → GEMINI.md | -| **Qwen Code** | AGENTS.md + 继承 Skill | 继承 Gemini 工具集 | save_memory 工具 | +| **Qwen Code** | AGENTS.md + 继承 Skill | 基于 Gemini CLI 工具集扩展（含 save_memory 等独有工具） | save_memory 工具 | | **Kimi CLI** | 三层 Skill 发现 | Agent 工具委托 | ✗ | | **Copilot CLI** | `.agent.yaml` 注入 | explore 代理（只读） | ✗ | From 0bddc8ad5f73a6901f8eb81be671895c5e209f5f Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 16:27:32 +0800 Subject: [PATCH 3/8] Fix 3 issues from Qwen-Code + GLM-5.1 round 2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix skill table: "即时检索" column now describes runtime discovery, not tool origin - Replace fragile Chinese anchor link with plain text reference - Add bidirectional cross-reference between build-your-own-agent and mcp-integration Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/mcp-integration-deep-dive.md | 2 +- docs/comparison/skill-system-deep-dive.md | 2 +- docs/guides/build-your-own-agent.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index 31f2a4de..b45653b8 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/docs/comparison/mcp-integration-deep-dive.md @@ -252,7 +252,7 @@ Copilot CLI 内置 `github-mcp-server`，但**默认不启用所有工具**： ## MCP 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)） -Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高。关于通用的工具设计原则（合并优于增殖、命名空间策略、描述即 Prompt 工程），详见 [构建自己的 AI 编程 Agent：工具设计原则](../guides/build-your-own-agent.md#工具设计原则来源anthropic-engineering-blog)。 +Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高。关于通用的工具设计原则（合并优于增殖、命名空间策略、描述即 Prompt 工程），详见[构建自己的 AI 编程 Agent](../guides/build-your-own-agent.md)中的「工具设计原则」章节。 以下聚焦于**MCP 特有的命名约定影响**： diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index 46a3b65d..36ef2792 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -354,7 +354,7 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 |------|--------|---------|---------| | **Claude Code** | CLAUDE.md + 条件 Skill（`paths` glob） | Agent 工具动态发现 | auto-memory 4 类型 | | **Gemini CLI** | GEMINI.md + activate_skill | codebase_investigator 只读探索 | memory_manager → GEMINI.md | -| **Qwen Code** | AGENTS.md + 继承 Skill | 基于 Gemini CLI 工具集扩展（含 save_memory 等独有工具） | save_memory 工具 | +| **Qwen Code** | AGENTS.md + 继承 Skill | 继承 codebase_investigator 类似机制（glob/grep/read） | save_memory 工具 | | **Kimi CLI** | 三层 Skill 发现 | Agent 工具委托 | ✗ | | **Copilot CLI** | `.agent.yaml` 注入 | explore 代理（只读） | ✗ | diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index 4f92cac8..56360fc8 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -432,7 +432,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { | SKILL.md 设计 | 每个子任务一个 Skill | 一个 Skill 编排完整工作流 | | Hook 设计 | 每个检查一个 Hook | 一个 Hook 脚本执行多项检查 | -> **与 MCP 的关系**：Anthropic 指出 "MCP can empower LLM agents with potentially hundreds of tools"——但工具数量多不等于质量高。合并和命名空间策略对 MCP 工具同样适用。 +> **与 MCP 的关系**：Anthropic 指出 "MCP can empower LLM agents with potentially hundreds of tools"——但工具数量多不等于质量高。合并和命名空间策略对 MCP 工具同样适用。关于 MCP 命名约定（双下划线 vs 单下划线）对各 Agent 工具选择的具体影响，参见 [MCP 集成深度对比](../comparison/mcp-integration-deep-dive.md)中的「MCP 命名约定与模型工具选择」章节。 --- From ed0480fa3829047f96ca613dc4aef73e8ef068f7 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 16:46:07 +0800 Subject: [PATCH 4/8] Fix source URL and 6 inexact quotes from round 4 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - multi-agent: Fix source URL building-effective-agents → effective-harnesses-for-long-running-agents - multi-agent: Restore 3 quotes to exact original text (with full sentence context) - skill-system: Fix 3 quotes to match original text exactly - "naively dropped into context up front" (not "upload into context initially") - "Letting agents navigate..." (not "Autonomous navigation...") - "Good context engineering means finding..." (not "Find...") Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/multi-agent-deep-dive.md | 8 ++++---- docs/comparison/skill-system-deep-dive.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 459e3d45..05f3f304 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -320,7 +320,7 @@ Evaluator（评估） - 评估标准的措辞会**隐式引导 Generator**（如"museum quality"导致视觉趋同） - **Sprint 分解不是永恒的**——Sprint 最初用于所有模型（含 Opus 4.5），Opus 4.6 的长任务能力提升使得 Sprint 机制可以被完全移除（原文："I removed the sprint construct entirely"） -### Progress File 模式：跨会话状态传递（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/building-effective-agents)） +### Progress File 模式：跨会话状态传递（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)） Anthropic 在长任务 harness 开发中发现：多代理系统的关键挑战是**跨会话状态传递**——当上下文重置后，新 Agent 如何快速了解之前的工作进展？ @@ -340,11 +340,11 @@ Coding Agent（后续每次会话） → 修改 feature-list.json 中对应功能的 "passes": true ``` -> 原文："The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history." +> "The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history. Inspiration for these practices came from knowing what effective software engineers do every day." **为什么用 JSON 而非 Markdown**： -> 原文："The model is less likely to inappropriately change or overwrite JSON files compared to Markdown files." +> "After some experimentation, we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files." **Feature List 防止提前宣告胜利**： @@ -363,7 +363,7 @@ Coding Agent（后续每次会话） 此外，Anthropic 还强调了功能测试列表的不可篡改性——防止 Agent 通过删除或修改测试来"伪造"进度： -> 原文："It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality." +> "We use strongly-worded instructions like 'It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.'" **各 Agent 的跨会话状态传递实现**： diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index 36ef2792..e3ef2f21 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -326,7 +326,7 @@ Claude Code 插件 Qwen Code / Gemini CLI Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一次性灌入全部内容**，而应采用渐进式披露（Progressive Disclosure）——Agent 通过探索逐步发现相关上下文，每次交互产生的上下文为后续决策提供信息。 -> 原文："Autonomous navigation enables progressive disclosure—agents incrementally discover relevant context through exploration." +> "Letting agents navigate and retrieve data autonomously also enables progressive disclosure—in other words, allows agents to incrementally discover relevant context through exploration." ### 三层上下文策略 @@ -336,7 +336,7 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 | 2 | **即时检索** | 运行时按需 | Skill 通过 `glob`/`grep` 动态发现文件 | | 3 | **持久化外部记忆** | 跨会话持久 | `NOTES.md`、auto-memory、progress 文件 | -> 原文："Claude Code employs this hybrid model: CLAUDE.md files upload into context initially, while glob and grep primitives enable just-in-time file navigation." +> "Claude Code is an agent that employs this hybrid model: CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time." ### 对 Skill 设计的启示 @@ -346,7 +346,7 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 | **简洁明确的描述** | `description` 字段用简单语言写清用途 | 模糊描述导致模型选错 Skill | | **典型示例优于穷举** | 用 2-3 个代表性示例替代所有边界情况 | 列出 20 种输入格式的 Skill | -> 原文："Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." +> "Good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." ### 各 Agent 的渐进式披露实现 From 7432d62cf4c230de4bc17fba4d03dbcf6b94fa68 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 17:12:46 +0800 Subject: [PATCH 5/8] Fix 5 issues from Qwen-Code + GLM-5.1 round 6 undirected audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - multi-agent: Clarify two Harness blogs are independent articles (different authors/dates/focus) - context-compression: Add Aider/Kimi CLI/Qwen Code to Compaction row (were omitted) - skill-system: Rename column "对应 Skill 实现" → "对应实现机制" (content is not Skill-specific) - skill-system: Move 条件 Skill from "预加载" to "即时检索" column (it's demand-loaded) - build-your-own-agent: Unify blockquote format "原文：" → bare quotes (match other 3 files) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/context-compression-deep-dive.md | 2 +- docs/comparison/multi-agent-deep-dive.md | 4 +++- docs/comparison/skill-system-deep-dive.md | 6 +++--- docs/guides/build-your-own-agent.md | 6 +++--- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/comparison/context-compression-deep-dive.md b/docs/comparison/context-compression-deep-dive.md index 7a93740b..d5a9b43e 100644 --- a/docs/comparison/context-compression-deep-dive.md +++ b/docs/comparison/context-compression-deep-dive.md @@ -245,7 +245,7 @@ Anthropic 工程团队在长任务 harness 开发中发现：**模型在上下 | 技术 | 说明 | 对应工具实现 | |------|------|-----------| -| **Compaction** | 原地摘要，保留架构决策/未解决 Bug/实现细节，丢弃冗余工具输出 | Claude Code 三层压缩、Gemini CLI 四阶段 | +| **Compaction** | 原地摘要，保留架构决策/未解决 Bug/实现细节，丢弃冗余工具输出 | Claude Code 三层压缩、Gemini CLI 四阶段、Aider 递归分割、Kimi CLI SimpleCompaction、Qwen Code 四阶段（继承） | | **结构化笔记**（Agentic Memory） | Agent 写外部笔记，需要时拉回。"以最小开销提供持久记忆" | Claude Code auto-memory、Gemini memory_manager | | **子代理架构** | 委托给专用子代理，返回"浓缩摘要（通常 1,000-2,000 tokens）" | Claude Code Agent 工具、Gemini CLI 5 个子代理 | diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 05f3f304..43a982c2 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -320,7 +320,9 @@ Evaluator（评估） - 评估标准的措辞会**隐式引导 Generator**（如"museum quality"导致视觉趋同） - **Sprint 分解不是永恒的**——Sprint 最初用于所有模型（含 Opus 4.5），Opus 4.6 的长任务能力提升使得 Sprint 机制可以被完全移除（原文："I removed the sprint construct entirely"） -### Progress File 模式：跨会话状态传递（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)） +### Progress File 模式：跨会话状态传递（来源：[Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)，Justin Young，2025-11-26） + +> **注**：本节来源与上方 GAN 式评估章节（[Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps)，Prithvi Rajasekaran，2026-03-24）是**两篇独立文章**。前者聚焦长任务 Agent 的运维实践（Progress File、Feature List、Incremental Commit），后者聚焦多代理评估架构（Planner→Generator→Evaluator）。两者互为补充但方案不同。 Anthropic 在长任务 harness 开发中发现：多代理系统的关键挑战是**跨会话状态传递**——当上下文重置后，新 Agent 如何快速了解之前的工作进展？ diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index e3ef2f21..de5df672 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -330,8 +330,8 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 ### 三层上下文策略 -| 层 | 名称 | 加载时机 | 对应 Skill 实现 | -|---|------|---------|----------------| +| 层 | 名称 | 加载时机 | 对应实现机制 | +|---|------|---------|-------------| | 1 | **预加载上下文** | 会话启动时 | AGENTS.md/CLAUDE.md 注入系统提示 | | 2 | **即时检索** | 运行时按需 | Skill 通过 `glob`/`grep` 动态发现文件 | | 3 | **持久化外部记忆** | 跨会话持久 | `NOTES.md`、auto-memory、progress 文件 | @@ -352,7 +352,7 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 | Agent | 预加载 | 即时检索 | 外部记忆 | |------|--------|---------|---------| -| **Claude Code** | CLAUDE.md + 条件 Skill（`paths` glob） | Agent 工具动态发现 | auto-memory 4 类型 | +| **Claude Code** | CLAUDE.md（无条件） | Agent 工具动态发现 + 条件 Skill（`paths` glob 按需激活） | auto-memory 4 类型 | | **Gemini CLI** | GEMINI.md + activate_skill | codebase_investigator 只读探索 | memory_manager → GEMINI.md | | **Qwen Code** | AGENTS.md + 继承 Skill | 继承 codebase_investigator 类似机制（glob/grep/read） | save_memory 工具 | | **Kimi CLI** | 三层 Skill 发现 | Agent 工具委托 | ✗ | diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index 56360fc8..ec332365 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -385,7 +385,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { ### 合并优于增殖 -> 原文："More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." +> "More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." **反面案例**：为每个 API 端点创建独立工具（`list_users`、`list_events`、`create_event`）。 @@ -404,11 +404,11 @@ for await (const event of thread.runStreamed("运行测试验证")) { ### 命名空间策略 -> 原文："Namespacing tools by service (e.g., `asana_search`, `jira_search`) and by resource (e.g., `asana_projects_search`, `asana_users_search`), can help agents select the right tools at the right time." +> "Namespacing tools by service (e.g., `asana_search`, `jira_search`) and by resource (e.g., `asana_projects_search`, `asana_users_search`), can help agents select the right tools at the right time." **命名前缀 vs 后缀的选择会影响模型性能**： -> 原文："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." +> "We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." | 命名方式 | 示例 | 适用场景 | |---------|------|---------| From de370159497587657d6291cdaad3f1fe76d8137d Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 17:52:14 +0800 Subject: [PATCH 6/8] Fix 4 issues from Qwen-Code + GLM-5.1 round 7 audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - build-your-own-agent: Split combined quote into 2 independent blockquotes - build-your-own-agent + mcp-integration: Add missing "our" in namespacing quote (2 places) - mcp-integration: Add Qwen Code (double underscore) to naming table - fork chose Claude Code convention over Gemini CLI, a notable design decision - mcp-integration: Fix "原文:" prefix → bare quote format (R6 issue #5 residual) - mcp-integration: Fix pre-existing error in overview table and naming comparison table - Qwen Code uses double underscore, not single (verified: 04-tools.md L98) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/mcp-integration-deep-dive.md | 11 ++++++----- docs/guides/build-your-own-agent.md | 6 ++++-- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index b45653b8..5c87f85f 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/docs/comparison/mcp-integration-deep-dive.md @@ -10,7 +10,7 @@ | **Claude Code** | 扩展 | Stdio/SSE/Streamable-HTTP | `mcp__server__tool`（双下划线） | deny→ask→allow 3 层 | ✓ | | **Gemini CLI** | 扩展 | Stdio/SSE | `mcp_{server}_{tool}`（单下划线） | **TOML 通配符 + 正则** | ✓ | | **Kimi CLI** | 扩展 | Stdio/HTTP | 动态注册 | Per-tool 审批 + 超时 | ✓ | -| **Qwen Code** | 扩展 | Stdio/SSE/HTTP | `mcp_{server}_{tool}`（继承） | 继承 Gemini + **运行时启停** | ✓ | +| **Qwen Code** | 扩展 | Stdio/SSE/HTTP | `mcp__serverName__toolName`（双下划线） | 继承 Gemini + **运行时启停** | ✓ | | **Copilot CLI** | 内置 GitHub MCP | 专有 | GitHub 默认子集 | CLI 参数 | ✓ | | **OpenCode** | 扩展 | StreamableHTTP/SSE/Stdio | — | 模式匹配 | ✓ | | **Cline** | 扩展 | — | McpHub 前缀 | WebView 审批 | ✓ | @@ -230,11 +230,11 @@ Copilot CLI 内置 `github-mcp-server`，但**默认不启用所有工具**： |------|---------|------| | **Claude Code** | `mcp__server__tool`（双下划线） | `mcp__github__create_issue` | | **Gemini CLI** | `mcp_{server}_{tool}`（单下划线） | `mcp_github_create_issue` | -| **Qwen Code** | 继承 Gemini（单下划线） | `mcp_github_create_issue` | +| **Qwen Code** | `mcp__serverName__toolName`（双下划线，**未继承 Gemini**） | `mcp__github__create_issue` | | **Goose** | 标准 MCP 发现 | 由 MCP 协议决定 | | **其他** | 未标准化 | — | -> **互操作性问题**：Claude Code 和 Gemini CLI 的命名约定不同（双下划线 vs 单下划线），同一个 MCP 服务器在两个工具中的工具名称不一致。 +> **互操作性问题**：Claude Code/Qwen Code（双下划线）和 Gemini CLI（单下划线）的命名约定不同，同一个 MCP 服务器在不同工具中的工具名称不一致。Qwen Code 虽为 Gemini CLI 分叉，但选择了 Claude Code 的双下划线方案。 --- @@ -258,17 +258,18 @@ Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多 ### MCP 命名约定与模型工具选择 -> 原文："We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." +> "We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on our tool-use evaluations." 各 Agent 的 MCP 命名约定差异**可能直接影响模型的工具选择准确率**： | Agent | 命名约定 | 分隔符 | 命名空间效果 | |------|---------|--------|------------| | **Claude Code** | `mcp__server__tool` | 双下划线 | 服务级命名空间清晰，无歧义 | +| **Qwen Code** | `mcp__serverName__toolName` | 双下划线 | 与 Claude Code 一致（**未继承 Gemini CLI 的单下划线**） | | **Gemini CLI** | `mcp_{server}_{tool}` | 单下划线 | 与工具名内下划线冲突风险（如 `mcp_github_create_issue` 的边界在哪？） | | **Goose** | 标准 MCP 发现 | — | 无额外命名空间 | -Claude Code 选择双下划线可能正是为了避免 Gemini CLI 单下划线方案中服务名/工具名边界模糊的问题。这一设计选择值得 MCP 服务器开发者关注。 +值得注意的是，Qwen Code 虽然是 Gemini CLI 的分叉，但在 MCP 命名约定上选择了 Claude Code 的双下划线方案而非 Gemini CLI 的单下划线——这说明 Qwen Code 团队也认识到了单下划线的边界歧义问题。 > **实践建议**：设计 MCP 服务器时，先问"工程师能否一眼判断该用哪个工具？"——如果人类分不清，模型更分不清。 diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index ec332365..b211e11d 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -385,7 +385,9 @@ for await (const event of thread.runStreamed("运行测试验证")) { ### 合并优于增殖 -> "More tools don't always lead to better outcomes. Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." +> "More tools don't always lead to better outcomes." + +> "Too many tools or overlapping tools can also distract agents from pursuing efficient strategies." **反面案例**：为每个 API 端点创建独立工具（`list_users`、`list_events`、`create_event`）。 @@ -408,7 +410,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { **命名前缀 vs 后缀的选择会影响模型性能**： -> "We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations." +> "We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on our tool-use evaluations." | 命名方式 | 示例 | 适用场景 | |---------|------|---------| From d652f0dc6f58bf6d3a2ee73b153e46c3b2b05bfe Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 18:03:22 +0800 Subject: [PATCH 7/8] Fix 2 minor quote edits from round 8 review - Restore "For example," prefix in namespacing quote - Restore full MCP quote: "The Model Context Protocol (MCP)...to solve real-world tasks." Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/build-your-own-agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index b211e11d..24eb9454 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -406,7 +406,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { ### 命名空间策略 -> "Namespacing tools by service (e.g., `asana_search`, `jira_search`) and by resource (e.g., `asana_projects_search`, `asana_users_search`), can help agents select the right tools at the right time." +> "For example, namespacing tools by service (e.g., `asana_search`, `jira_search`) and by resource (e.g., `asana_projects_search`, `asana_users_search`), can help agents select the right tools at the right time." **命名前缀 vs 后缀的选择会影响模型性能**： @@ -434,7 +434,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { | SKILL.md 设计 | 每个子任务一个 Skill | 一个 Skill 编排完整工作流 | | Hook 设计 | 每个检查一个 Hook | 一个 Hook 脚本执行多项检查 | -> **与 MCP 的关系**：Anthropic 指出 "MCP can empower LLM agents with potentially hundreds of tools"——但工具数量多不等于质量高。合并和命名空间策略对 MCP 工具同样适用。关于 MCP 命名约定（双下划线 vs 单下划线）对各 Agent 工具选择的具体影响，参见 [MCP 集成深度对比](../comparison/mcp-integration-deep-dive.md)中的「MCP 命名约定与模型工具选择」章节。 +> **与 MCP 的关系**：Anthropic 指出 "The Model Context Protocol (MCP) can empower LLM agents with potentially hundreds of tools to solve real-world tasks."——但工具数量多不等于质量高。合并和命名空间策略对 MCP 工具同样适用。关于 MCP 命名约定（双下划线 vs 单下划线）对各 Agent 工具选择的具体影响，参见 [MCP 集成深度对比](../comparison/mcp-integration-deep-dive.md)中的「MCP 命名约定与模型工具选择」章节。 --- From effabb549061445e32924921713e6fa6dffe7e46 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sat, 28 Mar 2026 18:20:57 +0800 Subject: [PATCH 8/8] Fix 2 issues from Qwen-Code + Qwen3.5-Plus review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - skill-system: Fix "静默忽略" → "抛出异常，Skill 不加载" (contradicted code evidence) - build-your-own-agent: Add TypeScript API inference disclaimer for Claude Agent SDK Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/skill-system-deep-dive.md | 2 +- docs/guides/build-your-own-agent.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index de5df672..6462a151 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -138,7 +138,7 @@ if (!frontmatter.description) { | 无 frontmatter 行为 | 空元数据 + 全文作为 prompt | **抛出异常，不加载** | | 设计理念 | 信任模型推断能力 | 依赖 harness 结构化校验 | -> **实际影响**：将 Claude Code 的 Skill 文件直接复制到 Qwen Code 的 `.qwen/skills/` 目录时，如果该 Skill 没有 YAML frontmatter，Claude Code 能正常加载但 Qwen Code 会静默忽略。迁移时需要补充 frontmatter。 +> **实际影响**：将 Claude Code 的 Skill 文件直接复制到 Qwen Code 的 `.qwen/skills/` 目录时，如果该 Skill 没有 YAML frontmatter，Claude Code 能正常加载但 Qwen Code 会**抛出异常，Skill 不加载**。迁移时需要补充 frontmatter。 ### 条件激活（Conditional Skills） diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index 24eb9454..38fb5ce8 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -309,6 +309,8 @@ MCP 协议让编码 Agent 可以调用**任何外部工具**，无需修改 Agen > 包名：`@anthropic-ai/claude-agent-sdk`（[npm](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)、[官方文档](https://platform.claude.com/docs/en/agent-sdk/overview)） +> **注**：以下 TypeScript 示例基于 npm 包导出推断（官方文档目前仅提供 Python 示例），实际 API 可能有差异，使用前请查阅最新官方文档。 + ```bash npm install @anthropic-ai/claude-agent-sdk ```