diff --git a/docs/comparison/architecture-deep-dive.md b/docs/comparison/architecture-deep-dive.md index 8084fe32..3ab1558c 100644 --- a/docs/comparison/architecture-deep-dive.md +++ b/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」章节。 diff --git a/docs/comparison/ci-scripting-deep-dive.md b/docs/comparison/ci-scripting-deep-dive.md index 9ba9f3b8..a7aa600a 100644 --- a/docs/comparison/ci-scripting-deep-dive.md +++ b/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 | 来源 | 获取方式 | diff --git a/docs/comparison/context-compression-deep-dive.md b/docs/comparison/context-compression-deep-dive.md index d5a9b43e..4c694946 100644 --- a/docs/comparison/context-compression-deep-dive.md +++ b/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 | 源码文件 | 获取方式 | diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index 5c87f85f..8695c26b 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/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 | 来源 | 获取方式 | diff --git a/docs/comparison/memory-system-deep-dive.md b/docs/comparison/memory-system-deep-dive.md index f49ee283..ac0b6cde 100644 --- a/docs/comparison/memory-system-deep-dive.md +++ b/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 | 来源 | 获取方式 | diff --git a/docs/comparison/multi-agent-deep-dive.md b/docs/comparison/multi-agent-deep-dive.md index 43a982c2..cf8b3417 100644 --- a/docs/comparison/multi-agent-deep-dive.md +++ b/docs/comparison/multi-agent-deep-dive.md @@ -278,16 +278,16 @@ Action → EventStream（发布/订阅总线）→ Runtime → Observation → |------|------|------|------| | **协作分工** | Claude Teammates | 任务并行，效率高 | 协调复杂 | | **竞争选优** | Qwen Arena | 多视角，质量高 | 资源浪费（N 倍成本） | -| **GAN 式评估** | Anthropic Harness（Planner→Generator→Evaluator） | 独立评估，质量可控 | 延迟高，成本高 | +| **独立评估者模式** | Anthropic Harness（Planner→Generator→Evaluator） | 独立评估，质量可控 | 延迟高，成本高 | | **专用委托** | Gemini 5 子代理 | 职责清晰，资源可控 | 灵活性有限 | | **事件解耦** | OpenHands EventStream | 最灵活，异步 | 架构最复杂 | | **流水线** | Aider Architect | 简单高效 | 非并行 | -### GAN 式评估 vs Arena 竞争（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/harness-design-long-running-apps)，2026-03-24） +### 独立评估者模式 vs Arena 竞争（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/harness-design-long-running-apps)，2026-03-24） 两种解决"Agent 自评失败"问题的不同路径： -| 维度 | GAN 式评估（Anthropic Harness） | Arena 竞争（Qwen Code） | +| 维度 | 独立评估者模式（Anthropic Harness） | Arena 竞争（Qwen Code） | |------|-------------------------------|----------------------| | **核心思路** | 1 个 Generator + 1 个独立 Evaluator | N 个 Generator 竞争同一任务 | | **质量保证** | Evaluator 按标准打分，不达标则退回重做 | 用户从 N 个结果中选最优 | @@ -322,7 +322,7 @@ Evaluator（评估） ### 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）。两者互为补充但方案不同。 +> **注**：本节来源与上方 独立评估者模式章节（[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 如何快速了解之前的工作进展？ @@ -379,6 +379,58 @@ Coding Agent（后续每次会话） > **自建 Harness 的完整实现**：如果你从零构建长任务多代理系统（如 Anthropic 的 Harness 方案），可以实现 `claude-progress.txt` + JSON feature list 的完整模式——这是目前最完备的跨会话状态传递方案，但需要自建 Harness 基础设施。现有成品 Agent 的记忆系统（auto-memory、GEMINI.md）是轻量级替代，但缺少 JSON feature list 的"防提前完成"能力。 +### Anthropic 多代理研究系统：90.2% 提升（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/multi-agent-research-system)，2025-06-13） + +> "We found that a multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval." + +**成本模型**： + +> "Agents typically use about 4x more tokens than chat interactions, and multi-agent systems use about 15x more tokens than chats." + +**Token 使用解释了 80% 的性能差异**： + +> "Token usage by itself explains 80% of the variance, with the number of tool calls and the model choice as the two other explanatory factors." + +**工具测试代理**——Agent 自动改进其他 Agent 的工具描述： + +Anthropic 还创建了一个**工具测试代理**——当给定一个有缺陷的 MCP 工具时，它反复尝试使用并重写工具描述来避免失败。这一改进工具描述的过程使后续代理的任务完成时间减少了 40%。 + +### 构建 10 万行编译器：16 个并行 Claude 实例（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/building-c-compiler)，2026-02-05） + +> "Over nearly 2,000 Claude Code sessions and $20,000 in API costs, the agent team produced a 100,000-line compiler that can build Linux 6.9 on x86, ARM, and RISC-V." + +**关键工程经验**： + +| 问题 | 解决方案 | +|------|---------| +| **验证器必须近乎完美** | "Claude will work autonomously to solve whatever problem I give it. So it's important that the task verifier is nearly perfect, otherwise Claude will solve the wrong problem." | +| **上下文窗口污染** | "The test harness should not print thousands of useless bytes. At most, it should print a few lines of output and log all important information to a file." | +| **时间盲** | "Claude can't tell time and, left alone, will happily spend hours running tests instead of making progress." 解决方案：`--fast` 选项运行 1%-10% 随机采样 | + +### 何时该用多代理、何时不该用（来源：[claude.com/blog](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them)，2026-01-23） + +> "Multi-agent systems typically use 3-10x more tokens than single-agent approaches for equivalent tasks." + +Anthropic 在实践中发现，很多团队投入数月构建复杂的多代理架构，最终发现改进单代理的 prompt 就能达到同等效果。 + +**三个适用场景**： + +| 场景 | 说明 | 阈值 | +|------|------|------| +| **上下文污染** | 不同任务的上下文互相干扰降低推理质量 | 上下文接近容量限制 | +| **并行化** | 多代理同时探索更大的搜索空间 | 任务可自然分解为独立子任务 | +| **专业化** | 工具数超过 15-20 导致选择混乱 | 先尝试 Tool Search Tool（可减少 85% token） | + +> "Start with the simplest approach that works, and add complexity only when evidence supports it." + +### GitHub Squad：共享决策文件的协作模式（来源：[GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-squad-runs-coordinated-ai-agents-inside-your-repository/)，2026-03-19） + +> "You aren't splitting one context among four agents, you're replicating repository context across them." + +**Drop-box 模式**：架构决策追加到版本化的 `decisions.md` 文件，提供持久性、可读性和完整的审计跟踪。 + +**强制独立审查**：编排层阻止原始 Agent 修改自己的产出——测试失败时由不同 Agent 提供全新视角。 + ### 隔离策略 | Agent | 隔离方式 | 上下文共享 | diff --git a/docs/comparison/review-command.md b/docs/comparison/review-command.md index a2d565be..1fcdc7fe 100644 --- a/docs/comparison/review-command.md +++ b/docs/comparison/review-command.md @@ -455,6 +455,73 @@ Qoder CLI 是唯一将代码审查和 PR 审查**分为两个独立命令**的 --- +## 十、行业数据与设计哲学 + +### Claude Code /review 的生产效果（来源：[claude.com/blog/code-review](https://claude.com/blog/code-review)，2026-03-09） + +| 维度 | 数据 | +|------|------| +| 部署前 PR 获得实质评论比例 | 16% | +| 部署后 PR 获得实质评论比例 | **54%** | +| 工程师不同意审查结论比例 | **< 1%** | +| 大 PR（1000+ 行）发现率 | 84%，平均 7.5 个问题 | +| 小 PR（< 50 行）发现率 | 31%，平均 0.5 个问题 | +| 单次审查成本 | $15-25，~20 分钟 | + +> Anthropic 明确定位为**"优化深度，比轻量级方案更贵"**——这与 Copilot 的订阅制广度覆盖形成互补。 + +### GitHub Copilot Code Review 的规模数据（来源：[GitHub Blog](https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/)，2026-03） + +| 维度 | 数据 | +|------|------| +| 总审查次数 | **6000 万次**（2025-04 以来 10 倍增长） | +| 占 GitHub 全平台审查比例 | **> 1/5** | +| 使用组织数 | 12,000+ | +| 有可操作反馈的比例 | **71%** | +| 无评论的比例 | **29%**（设计使然） | +| 平均每次审查评论数 | ~5.1 | + +> **"Silence is better than noise"**——GitHub 的核心设计理念是宁可不评论，也不产生噪声。29% 的审查未产生可操作反馈。 + +### 从 prompt 到 agentic：Copilot 审查架构演进（来源：[GitHub Blog](https://github.blog/changelog/2026-03-05-copilot-code-review-now-runs-on-an-agentic-architecture/)，2026-03-05） + +Copilot 代码审查从基于 prompt 的架构重构为**agentic tool-calling 架构**——Agent 主动收集仓库上下文（代码、目录结构、引用）来理解变更如何融入整体架构。升级后正面反馈增加 **8.1%**（来源：[60 Million Copilot Code Reviews](https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/)）。 + +### 学术研究：LLM 审查的可靠性边界 + +| 研究 | 关键发现 | +|------|---------| +| [Evaluating LLMs for Code Review](https://arxiv.org/abs/2505.20206)（Bilkent 大学，2025） | GPT-4o 正确分类代码正确性的准确率为 **68.5%**，Gemini 2.0 Flash 为 **63.9%**。结论："LLMs would be unreliable in a fully automated code review environment." | +| [Rethinking Code Review with LLM](https://arxiv.org/html/2505.16339v1)（WirelessCar，2025） | 开发者反馈："If they're not good enough, you stop reading them...you miss the real issues because you start ignoring the feedback."——**低质量 AI 反馈反而降低审查质量** | +| [CORE: Resolving Code Quality Issues](https://dl.acm.org/doi/10.1145/3643762)（ACM） | 二阶段 proposer+ranker 模式减少 **25.8%** 假阳性——与 Claude Code 的多代理验证异曲同工 | + +### 行业共识：五层信任架构（来源：[Latent Space](https://www.latent.space/p/reviews-dead)） + +核心主张：确定性质量关卡应该是测试套件而非代码审查——将人类监督从下游代码阅读移到上游规格编写。 + +| 层 | 机制 | 说明 | +|---|------|------| +| 1 | 竞争代理 | 多个代理解决同一问题，按测试通过率和 diff 大小排名 | +| 2 | 确定性护栏 | 自定义 linter、类型检查、契约验证——客观通过/失败 | +| 3 | BDD 验收标准 | 人类定义的行为规格 | +| 4 | 权限系统 | 按文件/任务限制代理范围 | +| 5 | 对抗验证 | 编码代理 + 验证代理 + 破坏者代理 | + +**核心转变**：将人类监督从**下游代码阅读**移到**上游规格编写**。 + +### 设计哲学总结 + +| 哲学 | 代表 | 核心信条 | +|------|------|---------| +| **高信号深度** | Claude Code | <1% 工程师不同意率，$15-25/次，多代理验证 | +| **沉默优于噪声** | Copilot CLI | 29% 审查零评论，代码执行验证 | +| **全维度覆盖** | Qwen Code | 4 代理 + 无预设审计，输出 Verdict | +| **CI 优先** | Codex CLI | CLI 子命令，可嵌入管道 | +| **确定性门禁** | Latent Space | 测试套件是真正的质量关卡，LLM 审查是辅助咨询 | +| **分层验证** | 行业共识 | 确定性（测试/lint）+ 概率性（LLM）+ 人类终裁 | + +--- + ## 证据来源 | Agent | 源码获取方式 | 完整性 | diff --git a/docs/comparison/sandbox-security-deep-dive.md b/docs/comparison/sandbox-security-deep-dive.md index 6ec48f93..11be9b86 100644 --- a/docs/comparison/sandbox-security-deep-dive.md +++ b/docs/comparison/sandbox-security-deep-dive.md @@ -302,6 +302,67 @@ Agent 动作 --- +## 沙箱工程深度洞察 + +### Claude Code 沙箱：权限弹窗减少 84%（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-sandboxing)，2025-10-20） + +> "In our internal usage, we've found that sandboxing safely reduces permission prompts by 84%." + +**核心设计原则**——文件系统和网络隔离**缺一不可**： + +> "Effective sandboxing requires both filesystem and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files like SSH keys; without filesystem isolation, a compromised agent could easily escape the sandbox and gain network access." + +**OS 级原语**： + +> "We've built this on top of OS level primitives such as Linux bubblewrap and MacOS seatbelt to enforce these restrictions at the OS level. They cover not just Claude Code's direct interactions, but also any scripts, programs, or subprocesses that are spawned by the command." + +**Web 版 Git 代理**——沙箱环境中的安全 Git 操作： + +> "Claude Code on the web uses a custom proxy service that transparently handles all git interactions. Inside the sandbox, the git client authenticates to this service with a custom-built scoped credential." + +### Auto Mode：AI 分类器自动审批（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-auto-mode)，2026-03-25） + +> "Claude Code users approve 93% of permission prompts. We built classifiers to automate some decisions, increasing safety while reducing approval fatigue." + +**双层防御架构**——Agent 不能说服分类器： + +> "We strip assistant text so the agent can't talk the classifier into making a bad call. The agent could generate persuasive rationalizations, such as 'this is safe because the user implicitly approved it earlier.'" + +**注入攻击的端到端难度**： + +> "For an injection to succeed end-to-end, it must evade detection at the input layer, then steer the agent into emitting a tool call that the transcript classifier independently judges as both safe and aligned with user intent. Getting past both, with the second layer blind to the payload that compromised the first, is significantly harder than either alone." + +**真实事故案例**（Anthropic 内部事故日志）： + +> "Past examples include deleting remote git branches from a misinterpreted instruction, uploading an engineer's GitHub auth token to an internal compute cluster, and attempting migrations against a production database." + +**诚实的漏报率**：auto mode 对真实危险操作的漏报率（false negative rate）为 17%——这是 Anthropic 公开披露的数字，体现了透明度。 + +### Prompt Injection 防御：Agents Rule of Two（来源：[Simon Willison](https://simonwillison.net/2025/Nov/2/new-prompt-injection-papers/)，2025-11-02） + +> "Prompt injection remains an unsolved problem, and attempts to block or filter them have not proven reliable enough to depend on." + +**致命三角（Lethal Trifecta）**——如果 Agent 同时满足以下三条，私有数据就可以被窃取： +1. 访问私有数据 +2. 暴露给不受信任的内容 +3. 能够对外通信 + +**Agents Rule of Two**：系统设计时最多满足上述三条中的两条。 + +> "The current solution is to design systems with this in mind, and the Rule of Two is a solid way to think about that." + +**对 Code Agent 的映射**： + +| Agent | 私有数据访问 | 不受信任内容 | 对外通信 | 防御策略 | +|------|------------|------------|---------|---------| +| **Codex CLI** | ✓（代码） | ✓（用户输入） | **✗（网络沙箱）** | 切断对外通信 | +| **Claude Code** | ✓（代码） | ✓（用户输入） | ✓（MCP/网络） | 双层分类器 + 沙箱 | +| **Gemini CLI** | ✓（代码） | ✓（用户输入） | ✓（MCP） | seccomp + Conseca | + +> Codex CLI 的 OS 级网络隔离是唯一从架构上消除"致命三角"第三条的实现。 + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/comparison/skill-system-deep-dive.md b/docs/comparison/skill-system-deep-dive.md index 6462a151..52a24f4f 100644 --- a/docs/comparison/skill-system-deep-dive.md +++ b/docs/comparison/skill-system-deep-dive.md @@ -322,7 +322,7 @@ Claude Code 插件 Qwen Code / Gemini CLI --- -## 渐进式披露与上下文工程（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)） +## 渐进式披露与上下文工程（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)，2025-09-29） Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一次性灌入全部内容**，而应采用渐进式披露（Progressive Disclosure）——Agent 通过探索逐步发现相关上下文，每次交互产生的上下文为后续决策提供信息。 @@ -360,6 +360,20 @@ Anthropic 在上下文工程实践中发现：**Skill 文档的加载不应一 > **实践建议**：设计 Skill 时，将**元数据层**（frontmatter）、**核心指令**（正文前半段）、**补充文件**（通过工具按需读取）分开。不要把所有信息都塞进 SKILL.md 正文——让 Agent 在执行过程中按需发现。 +### Agent Skills 的三层渐进式加载（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)，2025-10-16） + +Anthropic 将 Skill 比作"一本组织良好的手册——从目录开始，到具体章节，再到详细附录"： + +| 层 | 名称 | 加载条件 | 示例 | +|---|------|---------|------| +| 1 | **元数据层** | 始终加载到系统提示 | SKILL.md 的 YAML frontmatter（name + description） | +| 2 | **内容层** | Skill 变得相关时加载 | SKILL.md 正文（完整指令） | +| 3 | **引用层** | Agent 按需访问 | 捆绑的脚本、配置模板、示例文件 | + +> "Because agents have filesystem and code execution tools, the amount of context that can be bundled into a skill is effectively unbounded." + +这意味着 Skill 的上下文容量**不受 SKILL.md 文件大小限制**——复杂的领域知识可以放在引用文件中，Agent 在执行过程中按需读取。 + --- ## 证据来源 diff --git a/docs/comparison/system-prompt-deep-dive.md b/docs/comparison/system-prompt-deep-dive.md index 2e283d83..ea9400cf 100644 --- a/docs/comparison/system-prompt-deep-dive.md +++ b/docs/comparison/system-prompt-deep-dive.md @@ -258,6 +258,34 @@ FOUND WITHIN CHAT HISTORY" --- +## Cursor：IDE Agent 的系统提示设计（来源：[blog.sshh.io](https://blog.sshh.io/p/how-cursor-ai-ide-works)，2025-03-16） + +Cursor 作为 IDE Agent 的代表，其系统提示设计与 CLI Agent 有本质区别： + +> "The trick to making a good AI IDE is figuring out what the LLM is good at and carefully designing the prompts and tools around their limitations." + +**工具注入方式**——不通过 API tool_use，而是在 prompt prefix 中注入： + +> "Rather than just filling in the assistant text, in the prefix we can prompt 'Say `read_file(path: str)` instead of responding if you need to read a file'." + +**架构**：Cursor 是完整的 VS Code fork（非插件），包含三层：VS Code fork + AI 模型编排层（支持 GPT-4/Claude/cursor-small）+ 上下文感知引擎（embeddings + AST 图谱）。 + +**实际限制**： + +> "The apply-model is slow and error prone when editing extremely large files, break your files to be <500 LoC." + +### CLI Agent vs IDE Agent 系统提示设计差异 + +| 维度 | CLI Agent（Claude Code 等） | IDE Agent（Cursor 等） | +|------|--------------------------|----------------------| +| 工具定义 | API 级 tool_use schema | Prompt 内联文本指令 | +| 上下文来源 | CLAUDE.md + 文件系统探索 | AST 图谱 + embeddings + 打开的文件 | +| 交互模式 | 完整对话历史 | Tab completion + inline diff | +| 安全边界 | 28 BLOCK 规则 + 分类器 | IDE 沙箱 + 用户确认 | +| 系统提示大小 | 大（8 模块，数千 tokens） | 小（聚焦当前编辑上下文） | + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/comparison/telemetry-privacy-deep-dive.md b/docs/comparison/telemetry-privacy-deep-dive.md index e1c54330..e139571c 100644 --- a/docs/comparison/telemetry-privacy-deep-dive.md +++ b/docs/comparison/telemetry-privacy-deep-dive.md @@ -249,6 +249,32 @@ export GOOSE_TELEMETRY_OFF=1 --- +## 隐私设计哲学：ZDR 与无状态架构 + +### Codex CLI 的无状态设计（来源：[OpenAI Blog](https://openai.com/index/unrolling-the-codex-agent-loop/)，2026-01-24） + +Codex CLI 故意不使用 `previous_response_id` 参数，每次请求完全无状态： + +> "Every request is stateless, which is essential for ZDR customers who have opted out of data storage." + +这是**隐私优先的架构决策**——牺牲了会话连续性的便利，换取了数据不被存储的保证。 + +### Anthropic 的质量承诺 + +> "We never reduce model quality due to demand, time of day, or server load." +> — [A postmortem of three recent issues](https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues)（2025-09-17） + +### 隐私 vs 功能的权衡 + +| 隐私策略 | 代表 Agent | 牺牲的功能 | +|---------|-----------|-----------| +| **零遥测** | Kimi CLI、OpenCode | 无使用数据优化产品 | +| **Opt-in 采样** | Aider（10%）、Goose | 大部分用户不贡献数据 | +| **无状态架构** | Codex CLI（ZDR） | 无跨请求会话状态 | +| **默认开启** | Claude Code（782 事件） | 用户可能不知情 | + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/comparison/test-reflection-deep-dive.md b/docs/comparison/test-reflection-deep-dive.md index c1eed864..8d11e3c1 100644 --- a/docs/comparison/test-reflection-deep-dive.md +++ b/docs/comparison/test-reflection-deep-dive.md @@ -251,6 +251,59 @@ AI 编辑 → 实际编译（Copilot） → 测试失败 → 反馈给 LLM（Aid --- +## Agent 评估方法论（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)，2026-01-09） + +Anthropic 总结的 Agent 评估最佳实践，直接影响测试反射循环的设计： + +### 评估结果而非路径 + +> "There is a common instinct to check that agents followed very specific steps like a sequence of tool calls in the right order. We've found this approach too rigid and results in overly brittle tests, as agents regularly find valid approaches that eval designers didn't anticipate." + +**对测试反射循环的启示**：Aider 的反射循环评估**测试是否通过**（结果），而非**修复步骤是否正确**（路径）——这与 Anthropic 的建议一致。 + +### Eval-Driven Development + +> "Build evals to define planned capabilities before agents can fulfill them, then iterate until the agent performs well." + +### 0% 通过率 = 任务有 Bug + +> "With frontier models, a 0% pass rate across many trials (i.e. 0% pass@100) is most often a signal of a broken task, not an incapable agent." + +### 真实案例：评估 Bug 导致 42% → 95% 的跳跃 + +> "Opus 4.5 initially scored 42% on CORE-Bench, until an Anthropic researcher found multiple issues: rigid grading that penalized '96.12' when expecting '96.124991...', ambiguous task specs, and stochastic tasks that were impossible to reproduce exactly. After fixing bugs...Opus 4.5's score jumped to 95%." + +--- + +## 基础设施噪声：基准分数波动 6 个百分点（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/infrastructure-noise)，2026-02-03） + +> "Infrastructure configuration can swing agentic coding benchmarks by several percentage points—sometimes more than the leaderboard gap between top models." + +> "In internal experiments, the gap between the most- and least-resourced setups on Terminal-Bench 2.0 was 6 percentage points (p < 0.01)." + +**对排行榜的启示**： + +> "Until resource methodology is standardized, our data suggests that leaderboard differences below 3 percentage points deserve skepticism until the eval configuration is documented and matched." + +> "A few-point lead might signal a real capability gap—or it might just be a bigger VM." + +--- + +## Think Tool：复杂推理中的暂停思考（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-think-tool)，2025-03-20） + +Think Tool 让 Claude 在工具调用链中**暂停推理**，对测试验证场景有直接价值： + +> "Extended thinking is all about what Claude does before it starts generating a response...The 'think' tool is for Claude, once it starts generating a response, to add a step to stop and think about whether it has all the information it needs to move forward." + +| 场景 | 基线准确率 | Think Tool 准确率 | 提升 | +|------|-----------|-----------------|------| +| 航空客服（Tau-Bench） | 0.370 | 0.570 | **+54%** | +| SWE-bench | 基线 | +1.6% | p < .001 | + +> "The 'think' tool is better suited for when Claude needs to...analyze tool outputs carefully in long chains of tool calls, navigate policy-heavy environments...or make sequential decisions where each step builds on previous ones and mistakes are costly." + +--- + ## 证据来源 | Agent | 来源 | 获取方式 | diff --git a/docs/guides/build-your-own-agent.md b/docs/guides/build-your-own-agent.md index 38fb5ce8..4fc49c7f 100644 --- a/docs/guides/build-your-own-agent.md +++ b/docs/guides/build-your-own-agent.md @@ -48,6 +48,49 @@ > **Anthropic 的 Harness 洞察**（[来源](https://www.anthropic.com/engineering/harness-design-long-running-apps)）："The space of interesting harness combinations doesn't shrink as models improve. Instead, it moves."——**Harness 的价值不会随模型进步消失，只会迁移**。今天需要的 Sprint 分解，明天可能不再需要；但新的 Harness 组件（如 Evaluator 校准、Context Anxiety 管理）会出现。选择"路径 B 成品扩展"不意味着不需要 Harness 思维——而是用 SKILL.md + Hooks 实现轻量级 Harness。 +### Harness Engineering：2026 年的新兴学科 + +> "The primary job of engineering teams is no longer to write code, but to design environments, specify intent, and build feedback loops." +> — [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)，2026-02-11 + +**Harness Engineering** 在 2026 年初由 OpenAI 正式命名，核心主张：**工程师的角色从写代码转变为设计 AI Agent 写代码的环境**。 + +#### OpenAI 的实践数据 + +OpenAI 内部团队用 Codex CLI 构建了一个完整产品——**零行手写代码**，约 100 万行生成代码，~1500 个 PR，平均每工程师每天 **3.5 个 PR**，耗时约为手写的 **1/10**。 + +> "Building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code." + +#### Harness 的五大支柱 + +| 支柱 | 说明 | 对应成品 Agent 实现 | +|------|------|-------------------| +| **文档即系统** | AGENTS.md 作为导航地图，指向 `docs/` 详细文档 | CLAUDE.md / AGENTS.md / GEMINI.md | +| **架构约束** | 严格分层规则，代码只能"向前依赖" | SKILL.md `allowed-tools`、TOML 策略 | +| **反馈循环** | Agent 失败时识别缺失（工具/护栏/文档）并补充 | Hooks（PreToolUse/PostToolUse）、auto-lint | +| **熵管理** | 定期运行"垃圾回收"Agent 清理文档不一致和约束违规 | `/loop`、`/schedule` 定时任务 | +| **渐进自治** | Agent 从辅助到端到端，仅在需要判断时上报人类 | Auto mode（AI 分类器审批） | + +> "When the agent struggles, we treat it as a signal: identify what is missing -- tools, guardrails, documentation -- and feed it back into the repository." + +#### 关键实证发现 + +| 来源 | 发现 | +|------|------| +| [Martin Fowler / Thoughtworks](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)（2026-02-17） | Harness 三要素：上下文工程、架构约束、熵管理 | +| [NxCode](https://www.nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026) | LangChain coding agent 仅修改 Harness（不改模型），Terminal Bench 2.0 从 **52.8% → 66.5%** | +| [Pragmatic Engineer](https://newsletter.pragmaticengineer.com/p/how-codex-is-built)（2026-02-17） | Codex 自身 90%+ 代码由 Codex 生成；工程师角色="Agent 管理者"，同时运行 4-8 个并行 Agent | + +> **核心洞察**：Harness 优化可以在不更换模型的情况下带来显著性能提升（52.8% → 66.5%）。这意味着无论选择哪条路径（SDK 框架 / 成品扩展 / Agent SDK），Harness 设计都是重要的技术投入方向。 + +#### 对三条路径的影响 + +| 路径 | Harness 实现方式 | +|------|----------------| +| **路径 A（SDK 框架）** | 完全自建 Harness（最大灵活性，最高成本）| +| **路径 B（成品扩展）** | 用 AGENTS.md + SKILL.md + Hooks 实现轻量 Harness | +| **路径 C（Agent SDK）** | 继承 Claude/Codex 的 Harness 能力（工具集、权限、压缩）| + --- ## 选择决策树 @@ -381,7 +424,7 @@ for await (const event of thread.runStreamed("运行测试验证")) { --- -## 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)） +## 工具设计原则（来源：[Anthropic Engineering Blog](https://www.anthropic.com/engineering/writing-tools-for-agents)，2025-09-11） 无论选择哪条路径，工具设计都是 Agent 质量的关键。Anthropic 总结了以下经验： @@ -440,6 +483,37 @@ for await (const event of thread.runStreamed("运行测试验证")) { --- +## Agent 工程实践洞察 + +### 反馈循环设计（来源：[Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)，2025-09-29） + +> "Agents often operate in a specific feedback loop: gather context -> take action -> verify work -> repeat." + +**TypeScript 优于 JavaScript 的反馈质量**： + +> "It is usually better to generate TypeScript and lint it than it is to generate pure JavaScript because it provides you with multiple additional layers of feedback." + +**子代理的两个核心价值**： + +> "Subagents are useful for two main reasons. First, they enable parallelization...Second, they help manage context: subagents use their own isolated context windows, and only send relevant information back to the orchestrator." + +### 多代理项目的成本模型（来源：[Building a C Compiler](https://www.anthropic.com/engineering/building-c-compiler)，2026-02-05） + +| 维度 | 数据 | +|------|------| +| 会话数 | ~2,000 次 Claude Code 会话 | +| API 成本 | ~$20,000 | +| 代码量 | 100,000 行 Rust | +| 产出 | 可编译 Linux 6.9（x86/ARM/RISC-V）的 C 编译器 | + +> "Agent teams show the possibility of implementing entire, complex projects autonomously. This allows us, as users of these tools, to become more ambitious with our goals." + +### 多代理系统的经济可行性（来源：[Multi-Agent Research System](https://www.anthropic.com/engineering/multi-agent-research-system)，2025-06-13） + +> "Agents typically use about 4x more tokens than chat interactions, and multi-agent systems use about 15x more tokens than chats. For economic viability, multi-agent systems require tasks where the value of the task is high enough to pay for the increased performance." + +--- + ## 相关资源 ### 扩展开发