diff --git a/docs/comparison/context-compression-deep-dive.md b/docs/comparison/context-compression-deep-dive.md index 2e351e3e..d5a9b43e 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 四阶段、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 个子代理 | + +> **核心洞察**："Context Anxiety 是模型主动逃避，Context Rot 是被动质量退化——前者可通过模型升级显著缓解（Opus 4.5 'largely removed' 此行为，但非完全消除），后者是 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..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 的双下划线方案。 --- @@ -250,6 +250,31 @@ 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)中的「工具设计原则」章节。 + +以下聚焦于**MCP 特有的命名约定影响**： + +### MCP 命名约定与模型工具选择 + +> "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 发现 | — | 无额外命名空间 | + +值得注意的是，Qwen Code 虽然是 Gemini CLI 的分叉，但在 MCP 命名约定上选择了 Claude Code 的双下划线方案而非 Gemini CLI 的单下划线——这说明 Qwen Code 团队也认识到了单下划线的边界歧义问题。 + +> **实践建议**：设计 MCP 服务器时，先问"工程师能否一眼判断该用哪个工具？"——如果人类分不清，模型更分不清。 + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 97a67382..43a982c2 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -320,6 +320,65 @@ Evaluator（评估） - 评估标准的措辞会**隐式引导 Generator**（如"museum quality"导致视觉趋同） - **Sprint 分解不是永恒的**——Sprint 最初用于所有模型（含 Opus 4.5），Opus 4.6 的长任务能力提升使得 Sprint 机制可以被完全移除（原文："I removed the sprint construct entirely"） +### 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 如何快速了解之前的工作进展？ + +**解决方案：`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. Inspiration for these practices came from knowing what effective software engineers do every day." + +**为什么用 JSON 而非 Markdown**： + +> "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 防止提前宣告胜利**： + +```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 +} +``` + +此外，Anthropic 还强调了功能测试列表的不可篡改性——防止 Agent 通过删除或修改测试来"伪造"进度： + +> "We use strongly-worded instructions like '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 的完整实现**：如果你从零构建长任务多代理系统（如 Anthropic 的 Harness 方案），可以实现 `claude-progress.txt` + JSON feature list 的完整模式——这是目前最完备的跨会话状态传递方案，但需要自建 Harness 基础设施。现有成品 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..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） @@ -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 通过探索逐步发现相关上下文，每次交互产生的上下文为后续决策提供信息。 + +> "Letting agents navigate and retrieve data autonomously also enables progressive disclosure—in other words, allows agents to incrementally discover relevant context through exploration." + +### 三层上下文策略 + +| 层 | 名称 | 加载时机 | 对应实现机制 | +|---|------|---------|-------------| +| 1 | **预加载上下文** | 会话启动时 | AGENTS.md/CLAUDE.md 注入系统提示 | +| 2 | **即时检索** | 运行时按需 | Skill 通过 `glob`/`grep` 动态发现文件 | +| 3 | **持久化外部记忆** | 跨会话持久 | `NOTES.md`、auto-memory、progress 文件 | + +> "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 设计的启示 + +| 原则 | 说明 | 反面案例 | +|------|------|---------| +| **最小高信号 token 集** | Skill 正文只包含当前任务最相关的指令 | 将完整 API 文档塞入 SKILL.md | +| **简洁明确的描述** | `description` 字段用简单语言写清用途 | 模糊描述导致模型选错 Skill | +| **典型示例优于穷举** | 用 2-3 个代表性示例替代所有边界情况 | 列出 20 种输入格式的 Skill | + +> "Good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." + +### 各 Agent 的渐进式披露实现 + +| Agent | 预加载 | 即时检索 | 外部记忆 | +|------|--------|---------|---------| +| **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 工具委托 | ✗ | +| **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..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 ``` @@ -379,6 +381,65 @@ 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 +``` + +### 命名空间策略 + +> "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 后缀的选择会影响模型性能**： + +> "We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on our 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 指出 "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 命名约定与模型工具选择」章节。 + +--- + ## 相关资源 ### 扩展开发