wenshao · wenshao · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 命名约定与模型工具选择」章节。
+
+---
+
 ## 相关资源
 
 ### 扩展开发