Integrate 12 deep reference articles into 7 docs (+251 lines)

docs/comparison/architecture-deep-dive.md

@@ -527,3 +527,82 @@ pub struct ModelConfig {
 | **预留空间** | 无 | 无 | 50K tokens | 无 |
 | **LLM 调用** | LiteLLM | @google/genai SDK | kosong (自研) + tenacity | Provider trait |
 | **流式输出** | 默认开启 | 默认流式 | 流式 | Provider 决定 |
+
+---
+
+## 代理循环工程洞察
+
+### Codex CLI 代理循环内部（来源：[OpenAI Engineering Blog](https://openai.com/index/unrolling-the-codex-agent-loop/)，2026-01-24）
+
+> "The agent loop is the core logic in Codex CLI that is responsible for orchestrating the interaction between the user, the model, and the tools the model invokes."
+
+**二次方成本问题**：每次工具调用迭代都追加到 prompt，导致"A single turn can involve many iterations between model inference and tool execution"，发送到 Responses API 的 JSON 量呈二次方增长。
+
+**解决方案——Prompt 缓存使采样变为线性**：通过保持请求间的精确前缀匹配实现缓存命中，"With cache hits, sampling becomes linear rather than quadratic."
+
+**无状态架构（隐私优先）**：Codex CLI 故意不使用 `previous_response_id`，"every request is stateless, which is essential for ZDR customers who have opted out of data storage."
+
+**三类工具的信任边界**：
+
+| 工具来源 | 沙箱 | 信任级别 |
+|---------|------|---------|
+| Codex 内置工具 | OS 级沙箱 | 最高 |
+| API 提供的工具 | 无沙箱 | 中等 |
+| MCP 服务器工具 | **无沙箱**，需自行保障 | 最低 |
+
+> "Other tools from MCP servers are not sandboxed by Codex and must enforce their own guardrails."
+
+### Agent 反馈循环设计原则（来源：[Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)，2025-09-29）
+
+> "The key design principle behind Claude Code is that Claude needs the same tools that programmers use every day."
+
+> "Agents often operate in a specific feedback loop: gather context -> take action -> verify work -> repeat."
+
+**三层验证模式**：
+
+| 层 | 类型 | 示例 |
+|---|------|------|
+| 规则反馈 | 确定性 | 代码 lint、类型检查、测试 |
+| 视觉反馈 | 半确定性 | 截图/渲染比较 |
+| LLM-as-Judge | 概率性 | 另一个模型评估输出质量 |
+
+### Agent 协议全景（来源：[Google Developers Blog](https://developers.googleblog.com/developers-guide-to-ai-agent-protocols/)，2026-03-18）
+
+6 大标准化协议构成分层架构：
+
+| 协议 | 层 | 解决的问题 |
+|------|---|-----------|
+| **MCP** | 数据层 | Agent ↔ 系统/数据库 |
+| **A2A** | Agent 层 | Agent ↔ Agent 互操作 |
+| **UCP** | 商业层 | 标准化交易 |
+| **AP2** | 授权层 | 支付护栏 |
+| **A2UI** | UI 层 | 18 个组件原语的声明式 JSON |
+| **AG-UI** | 流式层 | Agent → 前端的标准化 SSE 事件流 |
+
+> A2A 是 MCP 的补充而非替代——"MCP provides helpful tools and context to agents; A2A lets agents talk to each other as opaque peers."
+
+### Harness Engineering：代理循环之上的环境设计（来源：[OpenAI Blog](https://openai.com/index/harness-engineering/)，2026-02-11）
+
+代理循环是 Agent 的内核，而 **Harness** 是包裹内核的外壳——决定了 Agent 在什么约束下、使用什么文档、通过什么反馈循环来工作。
+
+> "Humans steer. Agents execute."
+
+> "Give Codex a map, not a 1,000-page instruction manual."——AGENTS.md 作为导航地图指向 `docs/` 结构化文档，而非把所有信息塞进一个文件。
+
+**Harness vs 代理循环的关系**：
+
+```
+Harness（环境设计）
+  ├── 文档系统（AGENTS.md → docs/ 结构化文档）
+  ├── 架构约束（分层依赖规则、linter 检查）
+  ├── 反馈循环（测试失败 → Agent 自修复）
+  └── 熵管理（定期清理 Agent）
+      │
+      └── 代理循环（Agent 内核）
+            ├── 系统提示组装
+            ├── LLM API 调用
+            ├── 工具执行 + 权限检查
+            └── 上下文压缩
+```
+
+**关键实证**：LangChain coding agent 仅修改 Harness（不改模型），Terminal Bench 2.0 分数从 52.8% 提升到 66.5%——表明 Harness 优化可以在不更换模型的情况下带来显著性能提升。详见[构建自己的 AI 编程 Agent](../guides/build-your-own-agent.md)中的「Harness Engineering」章节。

docs/comparison/ci-scripting-deep-dive.md

@@ -209,7 +209,7 @@ sweagent run-batch \
 
 ---
 
-## 四、Goose：Recipe 驱动自动化
+## 六、Goose：Recipe 驱动自动化
 
 ```bash
 # 执行 YAML 任务模板
@@ -223,7 +223,7 @@ Recipe 是 Goose 的 CI 等价物——参数化 YAML 模板 + Cron 调度。
 
 ---
 
-## 五、跨 Agent CI 集成模式
+## 七、跨 Agent CI 集成模式
 
 | 模式 | 代表 | 适用场景 |
 |------|------|---------|
@@ -236,6 +236,52 @@ Recipe 是 Goose 的 CI 等价物——参数化 YAML 模板 + Cron 调度。
 
 ---
 
+## 八、企业级部署数据（来源：多渠道综合）
+
+### 行业采用率
+
+| 数据点 | 来源 | 值 |
+|--------|------|-----|
+| 开发者使用/计划使用 AI 工具 | [Panto AI Statistics](https://www.getpanto.ai/blog/ai-coding-assistant-statistics)（2026-03） | **84%** |
+| 每日使用 AI 工具的开发者 | 同上 | **51%** |
+| 每周节省时间 | 同上 | **~3.6 小时/开发者** |
+| 合并代码中 AI 编写的比例 | 同上 | **22%** |
+| 企业应用包含 AI Agent | [Gartner](https://www.gartner.com/en/newsroom/press-releases/2025-08-26-gartner-predicts-40-percent-of-enterprise-apps-will-feature-task-specific-ai-agents-by-2026-up-from-less-than-5-percent-in-2025)（2025-08） | 5%（2025）→ **40%**（2026） |
+
+### 规模化部署建议（来源：[claude.com/blog/scaling-agentic-coding](https://claude.com/blog/scaling-agentic-coding)，2025-10-15）
+
+> "Rather than deploying to everyone at once or creating lengthy pilot phases, successful organizations build expertise incrementally."
+
+> "Start with a pilot group of 20-50 developers who already use AI-assisted tools."
+
+常见失败模式：
+
+> "New users sometimes give agentic tools overly broad tasks without sufficient context, leading to frustrating results."
+
+---
+
+## 九、Agent 基础设施事故：Anthropic 事后分析（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues)，2025-09-17）
+
+Anthropic 公开了三次影响 Claude 质量的基础设施事故，对 Agent 可靠性有重要启示：
+
+**事故 1：上下文窗口路由错误**——请求被错误路由到不正确的服务器配置。
+
+> "At the worst impacted hour on August 31, 16% of Sonnet 4 requests were affected."
+
+**事故 2：输出损坏**——TPU 运行时优化 Bug 导致低概率 token 被赋予高概率。
+
+> "An issue caused by a runtime performance optimization occasionally assigned a high probability to tokens that should rarely be produced."
+
+**关键教训——内部评估未能捕获用户感知到的退化**：
+
+> "The evaluations we ran simply didn't capture the degradation users were reporting, in part because Claude often recovers well from isolated mistakes."
+
+> "Model quality is non-negotiable, so we accepted the minor efficiency impact."
+
+**对 CI/CD Agent 的启示**：Agent 在 CI 中自动运行时，基础设施问题可能导致间歇性失败但不被评估捕获——需要用户级别的质量监控，而非仅依赖自动化评估。
+
+---
+
 ## 证据来源
 
 | Agent | 来源 | 获取方式 |

docs/comparison/context-compression-deep-dive.md

@@ -225,13 +225,13 @@ Anthropic 工程团队在长任务 harness 开发中发现：**模型在上下
 > **Compaction vs Context Reset 的区别**（原文）：Compaction 是"原地摘要，保持连续性"；Context Reset 是"清空重来，代价是需要足够的交接信息让下一个 Agent 接手"。
 
 **这解释了压缩阈值差异的深层原因**：
-- Claude Code 设 ~95% 阈值——Opus 4.5 起 context anxiety 基本消除（"largely removed"），可以安全地晚触发
+- Claude Code 设 ~95% 阈值——如果使用 Opus 4.5+，context anxiety 的影响可能已大幅降低（"largely removed"），使得更晚触发压缩成为可能
 - 如果使用 Sonnet 作为主模型，可能需要更早触发或使用 context reset
 - Gemini CLI 50% 阈值——可能 Gemini 模型也存在类似的 context anxiety
 
 > **实践建议**：压缩阈值不应只考虑"保留多少上下文"，还应考虑"模型在多少容量下开始焦虑"。不同模型的焦虑阈值不同。
 
-### "Context Rot"上下文腐烂（来源：[Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)）
+### "Context Rot"上下文腐烂（来源：[Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)，2025-09-29）
 
 与 Context Anxiety（模型主动提前结束）不同，Context Rot 是**被动的质量退化**：
 
@@ -257,6 +257,32 @@ Anthropic 工程团队在长任务 harness 开发中发现：**模型在上下
 
 ---
 
+## 工具定义膨胀：134K tokens 的教训（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/advanced-tool-use)，2025-11-24）
+
+上下文压缩不仅要处理对话历史——**工具定义本身就是上下文膨胀的主要来源**：
+
+> "At Anthropic, we've seen tool definitions consume 134K tokens before optimization."
+
+### Tool Search Tool：85% token 减少
+
+| 方式 | Token 消耗 | 说明 |
+|------|-----------|------|
+| 传统预加载（50+ MCP 工具） | ~77K tokens | 全部定义一次性灌入 |
+| Tool Search Tool | ~8.7K tokens | 按需发现相关工具 |
+| 减少幅度 | **~85%**（原文数据） | — |
+
+> "Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1% with Tool Search Tool enabled."
+
+### 代码执行模式：98.7% token 减少
+
+更极端的方案——Agent 通过代码直接调用 MCP 工具，中间结果留在执行环境而非进入上下文：
+
+> "This reduces the token usage from 150,000 tokens to 2,000 tokens--a time and cost saving of 98.7%."
+
+**对上下文压缩的启示**：压缩算法优化对话历史只是治标；**从源头减少工具定义和中间结果的 token 消耗**才是治本。Tool Search Tool 和代码执行模式是压缩之外的第二条路径。
+
+---
+
 ## 证据来源
 
 | Agent | 源码文件 | 获取方式 |

docs/comparison/mcp-integration-deep-dive.md

@@ -250,7 +250,7 @@ Copilot CLI 内置 `github-mcp-server`，但**默认不启用所有工具**：
 
 ---
 
-## MCP 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)）
+## MCP 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)，2025-09-11）
 
 Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多不等于质量高。关于通用的工具设计原则（合并优于增殖、命名空间策略、描述即 Prompt 工程），详见[构建自己的 AI 编程 Agent](../guides/build-your-own-agent.md)中的「工具设计原则」章节。
 
@@ -275,6 +275,91 @@ Anthropic 指出 MCP 赋予 Agent 数百个工具的能力，但工具数量多
 
 ---
 
+## Block 的 60+ MCP 服务器设计经验（来源：[Block Engineering Blog](https://engineering.block.xyz/blog/blocks-playbook-for-designing-mcp-servers)，2025-06-16）
+
+Block 基于 60+ MCP 服务器的开发经验，总结了与 Anthropic 互补的实践指南：
+
+> "Unlike traditional API design, tools for LLMs should be designed with usability, context constraints, and language model strengths in mind. It's usually better to start top-down from the workflow that needs to be automated, and work backwards (in as few steps as possible) to define tools that support that flow effectively."
+
+### 核心原则
+
+| 原则 | Block 经验 | 对应 Anthropic 观点 |
+|------|-----------|-------------------|
+| **工具名即 Prompt** | "Tool names, descriptions, and parameters are treated as prompts for the LLM" | 与 Anthropic "工具描述即 Prompt 工程" 一致 |
+| **减少链式调用** | "LLMs are improving at planning but still it's hard for them to chain together 20 tool calls today" | 与 Anthropic "合并优于增殖" 一致 |
+| **可恢复的错误信息** | "Prefer actionable error messages that enable recovery by the agent" | Anthropic 未明确提到，Block 独有经验 |
+| **从工作流倒推** | 从用户任务开始，倒推所需最少工具 | 与 Anthropic "高阶工具" 方向一致 |
+
+---
+
+## MCP 代码执行模式：token 减少 98.7%（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/code-execution-with-mcp)，2025-11-04）
+
+Anthropic 发现当 MCP 工具数量增长时，Agent 可以**通过代码调用工具**而非逐个 tool call，大幅减少 token 消耗：
+
+> "The agent discovers tools by exploring the filesystem [...] This lets the agent load only the definitions it needs for the current task. This reduces the token usage from 150,000 tokens to 2,000 tokens—a time and cost saving of 98.7%."
+
+### 两种模式对比
+
+| 维度 | 传统 tool call | 代码执行模式 |
+|------|--------------|------------|
+| 工具加载 | 全部定义预加载（~150K tokens） | 按需发现（~2K tokens） |
+| 中间结果 | 每步返回 LLM 上下文 | 留在执行环境，仅返回显式 log |
+| 链式调用 | 每步一次 API 往返 | 一段代码完成多步 |
+| Token 节省 | — | **98.7%** |
+
+> "When agents use code execution with MCP, intermediate results stay in the execution environment by default. This way, the agent only sees what you explicitly log or return, meaning data you don't wish to share with the model can flow through your workflow without ever entering the model's context."
+
+**与 Skill 的关联**：代码执行模式可与 SKILL.md 结合——"Adding a SKILL.md file to these saved functions creates a structured skill that models can reference and use."
+
+---
+
+## 高级工具使用：Tool Search Tool + 程序化调用（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/advanced-tool-use)，2025-11-24）
+
+当 MCP 工具库膨胀到 50+ 工具时，Anthropic 的三个高级功能提供了解决方案：
+
+| 功能 | 效果 | 数据 |
+|------|------|------|
+| **Tool Search Tool** | 按需发现工具，替代预加载 | ~77K → ~8.7K tokens（原文称 **85% 减少**） |
+| **Programmatic Tool Calling** | Claude 写代码编排工具调用 | 43.6K → 27.3K tokens（37% 减少） |
+| **Tool Use Examples** | few-shot 示例提升参数处理 | 72% → 90% 准确率（原文数据） |
+
+> "Internal testing showed significant accuracy improvements on MCP evaluations when working with large tool libraries. Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1% with Tool Search Tool enabled."
+
+> "At Anthropic, we've seen tool definitions consume 134K tokens before optimization."
+
+---
+
+## MCP 安全框架（来源：[Block/Goose Blog](https://block.github.io/goose/blog/2025/03/31/securing-mcp/)，2025-03-31）
+
+Block 安全团队（13 位作者）提出的 MCP 安全框架：
+
+**两层通信安全**：Agent ↔ MCP 服务器的通信，以及 MCP 服务器 ↔ 后端系统的通信需要**分别保护**。
+
+**敏感数据风险**：
+
+> "If you expose an MCP interface that returns confidential data like Social Security Numbers [...] then you run the risk of that data being exposed to the underlying LLM provider."
+
+**供应链缓解**：只安装来自可信源且维护良好的 MCP 服务器，实施完整性检查/签名，企业环境使用预验证白名单。
+
+## MCP Sampling：工具描述不够用（来源：[Block/Goose Blog](https://block.github.io/goose/blog/2026/01/15/why-tool-descriptions-arent-enough/)，2026-01-15）
+
+> "Tool descriptions influence how a tool is used. Sampling changes how a tool participates in reasoning."
+
+没有 Sampling 时，工具是消息传递者——获取数据后由 LLM 处理。有 Sampling 时，"the tool gathers its data, then uses the same LLM [...] to ask a targeted question from its own context before returning anything."
+
+## 2026 MCP 路线图（来源：[MCP 官方博客](https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/)，2026-03-09）
+
+四大优先领域：
+
+| 优先级 | 方向 | 关键决策 |
+|--------|------|---------|
+| 传输演进 | **不增加新传输协议**，演进现有协议 | 有状态会话与负载均衡冲突，需解决 |
+| Tasks 原语 | 重试语义 + 过期策略 | 支持长时间运行的任务 |
+| 治理 | 建立贡献者阶梯，Working Groups 获更大自治权 | 当前每个 SEP 都需核心维护者审查 |
+| 企业需求 | 审计、SSO、网关——**作为扩展而非核心规范** | 与优先领域对齐的 SEP 推进最快 |
+
+---
+
 ## 证据来源
 
 | Agent | 来源 | 获取方式 |

docs/comparison/memory-system-deep-dive.md

@@ -304,6 +304,30 @@ files.push(path.join(Global.Path.config, "AGENTS.md"));
 
 ---
 
+## Contextual Retrieval：检索失败率降低 67%（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/contextual-retrieval)，2024-09-19）
+
+Agent 记忆系统的底层技术——如何让检索更准确：
+
+> "Traditional RAG solutions remove context when encoding information, which often results in the system failing to retrieve the relevant information from the knowledge base."
+
+**解决方案**：在嵌入前为每个 chunk 添加上下文前缀：
+
+> "Contextual Retrieval solves this problem by prepending chunk-specific explanatory context to each chunk before embedding ('Contextual Embeddings') and creating the BM25 index ('Contextual BM25')."
+
+| 方案 | 检索失败率 | 降低幅度 |
+|------|-----------|---------|
+| 传统 RAG | 5.7% | — |
+| Contextual Embeddings + BM25 | 2.9% | -49% |
+| + Reranking | **1.9%** | **-67%** |
+
+**小知识库可以跳过 RAG**：
+
+> "If your knowledge base is smaller than 200,000 tokens (about 500 pages of material), you can just include the entire knowledge base in the prompt."
+
+**对 Agent 记忆系统的启示**：Claude Code 的 auto-memory（MEMORY.md < 200 行）和 Gemini CLI 的 GEMINI.md 本质上都是"小知识库直接注入 prompt"的策略——当记忆量小于 200K tokens 时，这比 RAG 更有效。
+
+---
+
 ## 证据来源
 
 | Agent | 来源 | 获取方式 |