「Agent」是过去三年被用得最滥、也最缺精确定义的技术词汇。在讨论具体系统之前,必须先给出本报告的工作定义:
Agent = 以 LLM 为决策内核、以工具为手脚、以循环为骨架、以目标为导向的自主软件系统。 它区别于普通 LLM 应用的关键在于三点:① 模型自己决定下一步调用什么工具(而非人写死的流程);② 执行结果会回流到模型上下文中形成闭环;③ 终止条件由模型或环境判断,而非固定步数。
Anthropic 在其工程博客《Building Effective Agents》中给出的区分被业界广泛引用:Workflow 是「开发者写死流程、LLM 填空」的系统;Agent 则是「开发者给目标和工具,LLM 自己找路径」的系统。本次分析的八个对象恰好横跨这个光谱的两端和中间——LangGraph 允许你把每一步都画成图(强工作流),Pi 则把整个系统压缩成一个自由循环(纯 agent),Claude Code / OpenCode / DeepSeek Harness 位于中间:一个自由循环加上层层安全护栏。
| 对象 | 形态 | 入选理由 |
|---|---|---|
| Claude Code | 闭源商业 CLI | 行业事实标杆。本报告基于 2026 年 3 月经 npm source map 泄露的未混淆 TypeScript 源码快照(约 1900 文件、51 万行),可以逐行剖析一个顶级商业 agent 的真实工程结构——这在过去是不可能的事。 |
| LangChain | 开源框架(Python/JS) | 生态最大、抽象最全的 LLM 应用框架。它定义了 Runnable/LCEL、消息格式、工具协议等大量事实标准,也是争议最多的项目(「过度抽象」批评的典型靶子)。看懂 LangChain 等于看懂这个生态的半部编年史。 |
| LangGraph | 开源编排引擎 | LangChain 家族的核心引擎,把 agent 显式建模为状态机/图。生产级控制力(持久化、断点恢复、human-in-the-loop)的代表,是「确定性工程派」的旗帜。 |
| DeepAgents | 开源通用 agent 参考实现 | LangChain 官方把 Claude Code 式架构(规划工具+虚拟文件系统+子代理)抽象成开箱即用的库,是理解「复杂 agent 该长什么样」的最佳图纸,也是 LangGraph 生态位的最有力示范。 |
| Codex | 开源终端 agent(OpenAI) | Claude Code 的直接竞品与「厂商主动开源」对照样本:Apache-2.0 的 Rust 实现、OS 级沙箱三态审批、CLI+云端+IDE 三形态共用一套内核,代表大厂把 agent 做成开放基础设施的路线。 |
| OpenCode | 开源终端 agent | 对标 Claude Code 的头号开源替代品(Anomaly/SST 系维护),client/server 架构 + 任意模型接入,代表「开源 + 模型无关」路线的最新形态。 |
| Pi | 极简 agent 工具包 | Mario Zechner(libGDX 作者)的「反框架」宣言:统一 LLM API + 几百行 agent loop + 自研 TUI。以惊人的速度收获近十万 star,代表「极简主义」路线对复杂框架的反攻。 |
| DeepSeek Harness | 插件化运行时 | DeepSeek 官方的 agent harness(本报告的分析者本身就运行在其中)。150 个独立插件的微内核 + cordis 插件框架 + 事件溯源会话 + 多层沙箱,代表「平台化 harness」的极致形态,且底层模型适配层直接复用了 Pi 的 pi-ai——本身就是行业融合的活样本。 |
这八个对象覆盖了五种截然不同的架构哲学:
| 维度 | Claude Code | LangChain | LangGraph | DeepAgents | Codex | OpenCode | Pi | DeepSeek Harness |
|---|---|---|---|---|---|---|---|---|
| 一句话定位 | 终端里的软件工程 agent 标杆 | LLM 应用开发全家桶框架 | agent 状态机编排引擎 | Claude Code 架构的官方开源图纸 | OpenAI 开源终端 agent 基础设施 | 开源模型无关终端 agent | 极简 agent 工具包/循环 | 插件化 agent 运行时平台 |
| 语言/运行时 | TypeScript + Bun | Python(另有 JS 版) | Python(另有 JS 版) | Python(另有 JS 版) | Rust + TypeScript(SDK) | TypeScript + Bun | TypeScript | TypeScript + Node |
| UI 形态 | React + Ink 终端 UI | 无(库) | 无(库)+ Studio 可视化 | 无(库) | 终端 TUI + IDE 扩展 + 云端 | TUI/Web/Desktop 多客户端 | 自研 TUI 框架 | Web GUI + headless/TUI |
| Agent 循环 | queryLoop while(true) | v1 create_agent(建在 LangGraph 上) | 图执行 Pregel super-step | create_deep_agent(middleware 套装+图引擎) | Rust 核心 agent loop(turn 制) | session 循环(client/server) | 数百行显式 loop | ReactLoopAgent 插件 |
| 状态管理 | 内存消息数组 + 会话文件 | Runnable 状态透传 | Checkpoint 持久化状态图 | 继承 LangGraph checkpointer | rollout JSONL 会话文件(resume/fork) | 服务端 session 存储 | JSONL 会话文件 | 事件溯源日志(唯一事实源) |
| 扩展机制 | MCP/hooks/plugins/skills/subagents | 包生态/integrations/middleware | 节点/checkpointer/子图 | 自定义工具/子代理/中间件摘装 | MCP 双向/config.toml/profiles/custom prompts | plugins/MCP/自定义 provider | 自定义工具文件/extensions | cordis 插件 patch 叠加 |
| 安全模型 | 五级权限模式+规则+沙箱+hook 拦截 | 交给宿主应用 | interrupt 审批点 | HITL middleware(默认薄弱,需自补) | 三态沙箱+四级审批策略+OS 级强制隔离 | 工具审批+可配置权限 | 极简(yolo 为主,用户自担) | read-only/workspace-write/full-access 三态+ACL 沙箱+审批服务 |
| 适合谁 | 想要开箱即用的最强编码 agent | 要快速集成几百种模型/向量库的应用开发者 | 要可控可恢复长流程的生产系统 | 想基于「标杆骨架」快速二次开发的团队 | OpenAI 生态用户与要 OS 级沙箱硬隔离的团队 | 想用任意模型且要求开源透明 | 想完全理解并拥有每一行代码的人 | 要把 agent 当基础设施长期运营的团队 |
2026 年 3 月 31 日,安全研究员 Chaofan Shou(@Fried_rice)公开指出:Anthropic 发布的 Claude Code npm 包中包含了未清理的 source map(.map 文件),其中引用了托管在 Anthropic R2 存储桶上的未混淆 TypeScript 源码,任何人都可直接下载。本报告分析的正是这份快照的本地镜像:约 1900 个文件、超过 51 万行 TypeScript,运行时为 Bun,终端 UI 用 React + Ink 渲染。这是业界第一次能逐行阅读一个顶级商业 agent 的完整真实实现——其价值不亚于一份公开的课程级教材。
| 顶层目录/文件 | 规模 | 职责 |
|---|---|---|
| main.tsx | 4446 行 | CLI 入口编排(Commander.js 路径分发、全局初始化) |
| query.ts / QueryEngine.ts | 1612 + 1234 行 | Agent 主循环与查询引擎(全系统的发动机) |
| Tool.ts / tools.ts | 754 + 373 行 | 工具接口契约与注册表 |
| tools/ | 184 文件 | 40 余个工具实现(每个工具独立目录:实现+prompt+UI 三件套) |
| components/ + hooks/ + screens/ | 389+104+3 文件 | Ink 终端 UI 组件、React Hooks、全屏界面(REPL/Doctor/Resume) |
| commands/ | 207 文件 | 约 50 个斜杠命令实现 |
| services/ | 130 文件 | MCP、analytics、voice、限流、token 估算等外部服务 |
| utils/ | 564 文件/34 子目录 | permissions、hooks、mcp、sandbox、swarm、memory、skills、todo、messages……几乎每个子系统都有独立目录 |
| bridge/ · coordinator/ · skills/ · plugins/ · memdir/ · buddy/ · voice/ | — | IDE 桥接、多代理协调、技能、插件、记忆目录、终端宠物、语音输入等特色模块 |
Claude Code 是一个单进程 Node/Bun 应用,分层清晰:
entrypoints/cli.tsx ──► main.tsx(命令分发)
│
├── REPL 界面(React Ink 全屏应用,components/screens)
│ │ 用户输入 → processUserInput → 斜杠命令 or 进入查询
│ ▼
├── QueryEngine(会话级引擎:消息数组、interrupt()、getMessages()、setModel())
│ ▼
├── query.ts :: queryLoop —— while(true) 的 agent 主循环
│ │ 组装 system prompt + context → 调 Claude API(流式)
│ │ → 解析 tool_use 块 → 权限检查 canUseTool → 执行工具(可并行)
│ │ → 结果回填 messages → 继续下一轮,直到无 tool_use
│ ▼
└── tools/*(Bash/Edit/Read/Grep/Agent/MCP/Skill…各自带权限校验+UI渲染)
│
└── 子代理 = 又一套完整 QueryEngine 递归嵌套
几个关键的架构事实:
主循环是一个 async generator,签名暴露了它的全部输出类型:
export async function* query(params): AsyncGenerator<
StreamEvent | RequestStartEvent | Message |
TombstoneMessage | ToolUseSummaryMessage,
Terminal>
async function* queryLoop(params, consumedCommandUuids) {
let state: State = {
messages, toolUseContext,
maxOutputTokensOverride,
autoCompactTracking, // 自动上下文压缩跟踪
stopHookActive, // Stop hook 是否已触发(防死循环)
maxOutputTokensRecoveryCount: 0, // 输出截断后的恢复重试计数(上限3次)
hasAttemptedReactiveCompact: false,
turnCount: 1,
pendingToolUseSummary,
transition,
}
const budgetTracker = feature('TOKEN_BUDGET') ? createBudgetTracker() : null
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...) // 记忆预取
while (true) { // ← 整个产品的核心就是这行
// ...组装请求 → 流式调用模型 → 收集 tool_use
// → yieldMissingToolResultBlocks() 补齐缺失结果块
// → streamingToolExecutor 并行执行工具
// → 结果 append 进 messages → continue 或 return Terminal
}
}
值得展开的机制细节:
Tool.ts 定义了每个工具必须实现的完整契约:名称、description、zod input schema、validateInput、checkPermissions(input, ctx): Promise<PermissionResult>、execute、以及专属的 Ink UI 渲染组件与 progress 类型。也就是说,每个工具自带三层:给模型看的说明书(prompt.ts)、给内核看的校验器(permissions/validation)、给人看的可视化(UI.tsx)。新增一个工具 = 新建一个目录放齐三件套,再在 tools.ts 注册表挂载。
| 组别 | 工具 | 要点 |
|---|---|---|
| 文件 | FileRead / FileWrite / FileEdit / Glob / Grep / NotebookEdit | Read 带 imageProcessor(读图)、limits(行数/大小上限)、FileStateCache 记录 mtime 防脏写;Edit 强制先 Read 后改 |
| Shell | Bash / PowerShell / REPL | 双 shell 对称实现;各配 8-10 个安全子模块;REPLTool 可在持久解释器里跑代码 |
| 网络 | WebFetch / WebSearch | WebFetch 有 preapproved 域名白名单 |
| 交互 | AskUserQuestion / Brief(附件上传) / Sleep / SyntheticOutput | 结构化向用户提问;SyntheticOutput 用于协调者合成回复 |
| 任务管理 | TodoWrite / TaskCreate·Get·List·Update·Stop·Output | 两套体系:轻量 todo 列表 + 重型后台任务句柄 |
| 多代理 | Agent / SendMessage / TaskStop / TeamCreate / TeamDelete | 见 2.6 节,Claude Code 最深的水 |
| 规划/隔离 | EnterPlanMode / ExitPlanMode / EnterWorktree / ExitWorktree | 计划模式显式化为工具;worktree 给并行写入做 git 层隔离 |
| 扩展 | Skill / MCPTool / ListMcpResources / ReadMcpResource / McpAuth / ToolSearch / LSP / Config | ToolSearch 支持按需检索海量工具;LSPTool 接语言服务器拿符号定义/引用 |
| 调度/远程 | ScheduleCron(Create/List/Delete) / RemoteTrigger | cron 定时拉起 agent;远程会话触发器 |
最能体现工程密度的是 tools/BashTool/(18 个文件)。执行一条 shell 命令前要穿过:
PowerShellTool 有完全对称的一套(外加 clmTypes.ts 处理 ConstrainedLanguage 模式、gitSafety.ts 拦截危险 git 操作)。Windows PowerShell ConstrainedLanguage 模式的沙箱思路与 DeepSeek Harness 如出一辙——两条产品线在同一平台问题上收敛到了同一答案。
types/permissions.ts 定义了五档对外权限模式(外加两个内部模式):
| 模式 | 语义 | 典型场景 |
|---|---|---|
| default | 写操作/命令逐条询问 | 初次使用、不熟悉的项目 |
| acceptEdits | 自动接受文件编辑,命令仍询问 | 信任度提高后的日常档 |
| plan | 只读研究模式,产出计划等待批准 | 先看后动、大改动前评审 |
| dontAsk | 不再询问(按既定规则自动判定) | 规则完备的自动化流水线 |
| bypassPermissions | 完全跳过询问(YOLO) | 一次性脚本、隔离环境 |
| auto / bubble(内部) | LLM 分类器自动判权 / 气泡式内嵌确认 | 受 feature gate 控制的实验能力(如 TRANSCRIPT_CLASSIFIER) |
权限判断是三层漏斗:规则匹配(allow/deny/ask 规则表,来源含 CLI 参数、settings.json、项目配置、企业管理策略等多个 PermissionRuleSource)→ 工具自检(每个工具的 checkPermissions)→ hook 拦截(PreToolUse hook 可直接 deny 并给模型反馈)。PermissionUpdate 类型还支持「批准时顺手把规则持久化到指定 destination」,即「记住我的选择」。这个体系后来被几乎所有同类产品借鉴。
Claude Code 的多代理体系分四层,一层比一层激进:
coordinator/coordinatorMode.ts 内嵌了一篇千行级的「协调者宪法」系统提示词,其要点极具教学价值:
utils/swarm/(22 个文件)实现了一个真正的「AI 结对编程小队」:leader 通过 TeamCreate 组队,队友可以是进程内 runner 或真实的 tmux/iTerm2 终端窗格(PaneBackendExecutor + TmuxBackend/ITermBackend),各自有独立的 teammate 提示词、模型选择、权限同步(leaderPermissionBridge/permissionSync)、断线重连(reconnection)与窗格布局管理(teammateLayoutManager)。IN_PROCESS_TEAMMATE_ALLOWED_TOOLS 白名单额外开放 TaskCreate/List 等协作工具。这是目前所有编码 agent 中走得最远的「多终端窗口协作」实验。
任务可以托管到云端远距执行(remote/ 目录含 RemoteSessionManager 与 WebSocket 协议),配合 cron 工具实现「睡前派活、早上收 PR」的工作流。
| 机制 | 形态 | 源码证据 |
|---|---|---|
| MCP | 标准协议接入外部工具/资源,带服务器级审批(mcpServerApproval)与 OAuth(McpAuthTool) | services/mcp/*、MCPTool 系列工具 |
| Hooks | 在 PreToolUse/PostToolUse/UserPromptSubmit/Stop/SessionStart… 等事件点执行用户 shell 命令,可阻断/改写流程;支持同步 JSON 响应与异步 hook | types/hooks.ts(zod schema 定义 syncHookResponseSchema:continue/suppressOutput/stopReason…) |
| Plugins | 捆绑分发的能力包(可含命令/工具/hook/MCP 配置),dxt(Desktop Extensions)目录结构 | plugins/builtinPlugins.ts、utils/dxt |
| Skills | SKILL.md 形式的「过程性知识包」,模型按需加载;内置 verify/debug/loop/remember/simplify/skillify/stuck/batch/scheduleRemoteAgents 等官方技能 | skills/loadSkillsDir.ts、skills/bundled/* |
LangChain 由 Harrison Chase 于 2022 年 10 月创建(仓库创建时间 GitHub API 实证 2022-10-17),最初只是「800 行左右的 Python 包」,踩中 ChatGPT 发布前夜的时间窗口后成为 LLM 应用开发的事实标准。截至调研时点实测 144,998 stars / 24,173 forks,仓库简介已改为 "The agent engineering platform"——定位从框架升级为平台。运营主体 LangChain Inc.:种子轮 $10M(Benchmark 领投)、2024 年初 $25M 轮;商业产品为 LangSmith(可观测/评测 SaaS)与 Hub。
0.0.x 时代的心智模型是「五大件」:Model I/O、Retrieval、Chains、Agents、Memory。这套分类如今整体封存于 langchain-classic 包,官方叙事已彻底转向。
| 目录 | PyPI 包 | 内容 |
|---|---|---|
| libs/core | langchain-core (1.6.1) | Runnable/LCEL、消息、模型/工具/向量存储抽象——最小内核,运行时依赖仅 9 项 |
| libs/langchain_v1 | langchain (1.3.17) | v1 真身:create_agent + middleware + init_chat_model |
| libs/langchain | langchain-classic (1.0.8) | 旧版 chains/agents/memory 原样封存 |
| libs/partners/* | langchain-openai 等 ×15+ | 供应商集成包(更多集成外移独立仓) |
| 另有 standard-tests / text-splitters / model-profiles 等支撑包;docs 与 cookbook 已迁出本仓库 | ||
为什么拆?三个历史动因:① 依赖地狱——单包巨石拖进所有集成的传递依赖;② Pydantic v1/v2 危机——核心抽象被上游版本绑架;③ 发布节奏解耦——core 要稳定慢速、partner 要快速独立发版。最戏剧性的细节是 v1 正式化方式:不是在旧包里加兼容层,而是把新代码放进 langchain_v1(构建产物名就叫 langchain),把整个旧世界改名 langchain-classic 另发一个包——比 deprecation warning 更彻底的切割。
| 管道的载体)、RunnableParallel、RunnableLambda。承诺是「写一次组件,自动获得同步/异步/批量/流式四套语义」;测试目录里 test_runnable_events_v1/v2/v3.py 三代事件 API 并存,是演化的活化石。def create_agent(model, tools=None, *, system_prompt=None,
middleware: Sequence[AgentMiddleware] = (),
response_format=None, checkpointer=None, store=None, ...) -> CompiledStateGraph
要点:① 返回值就是 LangGraph 的 CompiledStateGraph——agent 即图,天然继承 checkpoint/interrupt/subgraph 全部能力;② import 区直接引用 langgraph 的 StateGraph/ToolNode/Command/Send,v1 是在 LangGraph 原语之上自建的 ReAct 循环;③ 主包运行时依赖只剩 langchain-core + langgraph + pydantic 三项——「变薄」的最硬证据。
Middleware 洋葱模型取代继承树成为主要扩展轴:AgentMiddleware 提供 before_agent/before_model/wrap_model_call/after_model/after_agent/wrap_tool_call 六大钩子,内置中间件已扩至 30+ 符号——SummarizationMiddleware(超限自动摘要)、HumanInTheLoopMiddleware(工具级人工审批)、TodoListMiddleware、ModelFallback/Retry、PIIMiddleware、ShellToolMiddleware(含 Docker/Host/CodexSandbox 三种执行策略)等。Standard Stream 则把流式输出规范化为 values/updates/messages/custom 四种订阅模式,前端无需为每个 provider 写适配。
清晰的三层契约:langchain-core(零业务最小内核)← langgraph(通用图编排引擎,可脱离 LangChain 使用)← langchain(观点化封装层)。逃生舱常开:任何时候可以拿到底层 CompiledStateGraph 自己改图,或干脆落到 LangGraph/core 裸用。官方还有 deepagents 包作为「复杂 agent 用 LangGraph 组合」的参考实现——规划工具 + 虚拟文件系统 + 子代理生成,把 Claude Code 式架构产品化(详见第五章)。
| 时点 | 版本 | 解决的问题 |
|---|---|---|
| 2022-10 ~ 2023 | 0.0.x | 野蛮生长期:单包巨石、依赖不可控、API 天天变,欠下全部设计债 |
| 2024-01-06 | 0.1.0 | LCEL/Runnable 转正,monorepo 初步成型,第一个稳定锚点 |
| 2024-05-17 | 0.2.0 | 解耦:不再硬依赖 partner 包,安装体积与冲突大幅缓解 |
| 2024-09-13 | 0.3.0 | Pydantic v2 全面迁移,甩掉最大技术债 |
| 2025-08~10 | 1.0 alpha→GA(10-17) | create_agent 唯一入口 + middleware 体系 + classic 分家封存 |
| 2025-11 ~ 今 | 1.1 → 1.3.17 | 中间件持续扩军,与 LangGraph 1.x 协同演进 |
LangChain 的护城河是集成的广度(几十个 partner 包)与抽象的中立性(同一业务代码跨供应商)。但 2023-24 年它也是被骂得最狠的项目:HN《Why we no longer use LangChain for building our AI agents》、《LangChain Is a Black Box》——核心指控是多层包装导致调试困难、简单任务被迫重依赖、抽象泄漏、教程驱动的 API 腐化。v1 的回应策略从源码可直接读出:更薄的默认 agent、更标准的底层(复用 Pydantic/OpenAI schema/LangGraph 语义而不发明私有概念)、扩展点从继承改成组合、旧世界打包封存而非删除。总评:AI 工程领域罕见的「三年三次自我革命」案例(LCEL 化→解耦→agent 重构),包袱之重与纠错幅度之大同样罕见。
mypy strict=true 全量强制 + ruff select=["ALL"];unit/integration 测试目录级分离、pytest-socket 断网跑单测、blockbuster 检测异步阻塞、syrupy 快照、vcrpy 录制回放;46 个 CI workflow;根目录 AGENTS.md/CLAUDE.md 表明其自身开发已深度 AI 协作化。短板:base.py 6700 行的大文件风格仍在;中间件膨胀后概念密度上升,新手曲线并未因 v1 显著变缓。
LangGraph 是 LangChain Inc. 出品的「低层有状态智能体编排框架」(README 自述 Low-level orchestration framework for building stateful agents),与 LangChain 同公司、同生态但可完全独立使用。它解决的核心痛点直指 Pi 哲学的软肋:自由 while-loop 式 agent 无法持久化、无法中断恢复、无法并行汇聚、难以观测。LangGraph 的答案是「显式共享状态 + 图结构 + 检查点」,底层计算模型致敬 Google Pregel 与 Apache Beam(README 致谢一节点名引用)。仓库创建于 2023-08-09,MIT 协议,截至调研时点约 40.5k stars;最新版 1.2.11(2026-08-11),v1.0 于 2025 年 10 月 GA。JS/TS 版本(langgraphjs)由同一团队平行维护。
monorepo 的 libs/ 下共 9 个包,职责切分干净:
| 包 | 内容 |
|---|---|
| libs/langgraph | 核心运行时:graph/state.py(1979行,StateGraph)、pregel/main.py(4365行,Pregel 类)、channels/ 通道原语、func/ 函数式 API、types.py(1025行公共类型) |
| libs/checkpoint(-sqlite/-postgres/-conformance) | 持久化抽象基座 + 官方 SQLite/Postgres 实现 + 第三方一致性测试套件(独立发版) |
| libs/prebuilt | ToolNode、create_react_agent 等预置件 |
| libs/cli / sdk-py / sdk-js | 命令行与访问 LangGraph Server 的双语言 SDK |
langgraph dev)的实际实现依赖两个不在本仓库的闭源 PyPI 包:langgraph-api 与 langgraph-runtime-inmem。这就是「开源框架 + 商业运行时」的 open-core 边界——2025 年后商业侧统一归入 LangSmith 品牌(Deployment / Studio),README 已完成品牌替换。
状态 schema 支持 TypedDict / Pydantic v2 / dataclass;字段用 Annotated[T, reducer_fn] 标注即成为归约通道(BinaryOperatorAggregate),否则是「最后写入胜出」(LastValue)。最常用的 add_messages(graph/message.py:61) 按 ID 合并消息——同 ID 覆盖、否则追加,支持 RemoveMessage 删除。图 API:add_node/add_edge/add_conditional_edges/add_sequence/set_entry_point/compile,编译产物 CompiledStateGraph 还支持运行前动态挂载节点/边(attach_node/attach_edge),这是高层封装动态扩展的基础。
执行遵循 BSP(整体同步并行):每个 super-step 中所有被触发节点并发读取上一轮结束时的通道快照,写出统一提交。channels 全集包括 LastValue、EphemeralValue(当轮有效)、Topic(fan-in 队列)、NamedBarrierValue(命名屏障)等九种;任务粒度的 RetryPolicy/TimeoutPolicy/CachePolicy/TracePolicy 都是一级公民(pregel/types.py)。条件边本质是 Branch 对象,在超步末路由下一批节点。
Send("node", custom_arg) 让条件边向同一节点投递多份互不相同的私有输入——map-reduce 扇出的原语,每个 Send 是独立任务可单独设超时。Command 四字段(update/goto/resume/graph)让节点在返回时同时「写状态+控流转」,Command(graph=PARENT) 可向父图传播——子图嵌套的回程票。
v1 的 HITL 主推方式是一个普通函数调用:interrupt(value) 抛出 GraphInterrupt 异常暂停整图、把 value 送回客户端;恢复必须用 Command(resume=...),且图会从该节点开头重新执行全部逻辑——因此官方反复强调节点逻辑必须幂等,多次 interrupt 按出现顺序匹配恢复值。这比 0.x 时代的声明式中断灵活得多。
以 thread_id(会话)× checkpoint_ns(子图命名空间)× checkpoint_id(时间点)三维定位快照;每步边界自动落盘。任取历史快照即可回放/分叉(time-travel),跨版本快照迁移已内置(_migrate_checkpoint)。第三方实现受 checkpoint-conformance 一致性套件约束。
stream_mode 提供.values/.updates/.messages(token级)/.custom/.checkpoints/.tasks/.debug 七种契约化输出。@entrypoint/@task 函数式 API 则是「同一运行时的命令式语法糖」:task 把普通函数变成持久执行单元,entrypoint 把它们串成线性流程——内部仍编译为 Pregel,共享全部 checkpoint/stream/interrupt 能力。
选图而非自由 loop 的五大理由:状态变更可审计、步边界快照天然获得 durable execution、BSP 给并行确定语义、中断点是语言级原语、结构化图可被 Studio 渲染追溯。社区批评同样锋利:「简单的事情变难了」(简单任务被迫建图)、学习曲线陡(channels/reducer/super-step 心智负担)、Pregel 栈深难调试、open-core 商业闭环引发的「数据是否要进 LangSmith」焦虑;dev.to 上《Why I Stopped Using LangGraph》是弃用声音的代表。官方的回应路径是提供更高层入口(create_agent、Deep Agents)、函数式 API 降低建图成本、免费 dev server 改善 DX、v1 冻结 API 降低升级风险。本质上,LangGraph 是「基础设施派」——赌的是生产级 agent 需要 DB 式的状态可靠性。
类型标注完备(py.typed、泛型贯穿)、测试基建重投入(syrupy 快照、pytest-xdist、抗 flaky 重复测试、checkpoint 契约测试仓)、ruff+ty 入 CI、9 包独立语义化发版、文档三层齐全(概念/API/Academy 课程);根目录 AGENTS.md/CLAUDE.md 显示其自身开发流程已深度 AI 化。隐忧:单文件巨型化(state.py 近 2000 行、pregel/main.py 4300+ 行)、Pregel 类职责过重、CHANGELOG 不入库、闭源 server 使纯开源用户无法完整复刻生产拓扑。
DeepAgents 是 LangChain 官方于 2025 年 7 月推出的开源包(github.com/langchain-ai/deepagents)。Harrison Chase 当时给出的定义是「batteries-included harness」——带全套电池的 agent 挽具。他的观察是:LLM 应用正在分水岭两侧分化——一侧是聊天机器人(一问一答、无状态),另一侧是 deep agents(在长程任务中反复调用 LLM 做决策、持续积累上下文、混合使用各种工具)。问题在于:2025 年中想做后者,要么照着 Claude Code 的行为逆向模仿,要么从零拼装——没有第三条路。DeepAgents 就是那条第三条路:把行业标杆(Claude Code 式)的架构骨架抽象成 pip install 就能用的参考实现。截至调研时点版本 0.6.8,社区报道口径已收获约 27k star(数字待确认),并有 JS 版跟进。
| 组件 | 机制 | 解决什么问题 |
|---|---|---|
| 规划工具 write_todos | 由 TodoListMiddleware 提供:给模型一个结构化的任务清单读写接口,强制其在长任务里先列计划、随做随勾。 | 长任务中途「迷路」——模型在几十步之后忘记最初目标或跳过关键步骤。这是 Claude Code TodoWrite 的直接库化。 |
| 虚拟文件系统 ls / read_file / write_file / edit_file | 一套默认落在内存或本地目录的文件工具(可替换后端),鼓励模型把中间成果写成文件而非全部堆在对话上下文里。 | 上下文有限 vs 任务知识无限的根本矛盾——「外置记忆」。与 Manus 团队公开阐述的「用文件当工作记忆、对 KV cache 友好」思路同源。 |
| 子代理生成 task 工具 | 由 SubAgentsMiddleware 提供(源码注释原话:"Middleware for providing subagents to an agent via a task tool"):主代理可派生携带独立上下文的子代理执行子任务,支持自定义子代理配置。 | 上下文隔离与并行探索——避免一次调研把主对话窗口塞爆。 |
DeepAgents 的实现方式经历了明显的架构迁移:
这个迁移本身就是第三章所说的「v1 中间件化」战略的最佳注脚:DeepAgents 从「一个特殊 agent」变成了「一组可拆装的官方最佳实践中间件」——你既可以整包使用,也可以只摘走它的 FilesystemMiddleware 放进自己的 agent。
适合:研究报告生成、代码库审计、多步信息搜集等「读多写少、步骤深、需要外置笔记」的任务快速起步;也适合作为学习材料——它是目前可读性最好的「复杂 agent 应该长什么样」官方教材。
局限:① 默认权限模型薄弱——没有 Claude Code 式的分级审批,接生产必须自己补 HumanInTheLoopMiddleware 与沙箱策略;② 默认提示词面向通用场景,特定领域需要调教;③ 版本迭代极快(半年内 0.1→0.6+),API 尚未进入 1.0 稳定契约,升级成本需自担。
| 维度 | DeepAgents |
|---|---|
| 主体 / 协议 | LangChain Inc. / MIT 开源 |
| 定位 | 通用「深度 agent」参考实现(batteries-included harness) |
| 底座 | langchain v1 create_agent + LangGraph 图引擎 |
| 核心组件 | write_todos 规划 / 虚拟文件系统 / task 子代理(全部 middleware 化) |
| 继承能力 | checkpoint、流式、interrupt、time-travel(来自 LangGraph) |
| 一句话点评 | Claude Code 的开源「设计图纸」,学架构的最佳起点,上生产还需自补安全件 |
OpenCode 自述为 "The open source coding agent",是终端运行的开源 AI 编程 agent,公认的 Claude Code 开源对标品。主仓库现为 anomalyco/opencode(旧地址 sst/opencode、更早的 opencode-ai/opencode 均重定向),默认分支 dev,MIT 协议。截至调研时点实测 201,411 stars / 26,098 forks,最新版 v1.18.23。
起源故事(传闻逐条核实):项目脱胎于 AWS 开源的 amazon-q-developer-cli(原仓 2025-04-30 创建,早期 Go 实现);2025 年中 SST 团队参与后以 TypeScript 整体重写为 client/server 架构;Charmbracelet 的 Crush 是其 Go 分支独立发展;团队以 Anomaly 公司运营并进入 Y Combinator(中文报道戏称「被拒 9 次后被录取」),一年内做到 800 万用户;融资额二手信源不一致(待确认)。商业模式:核心永久免费 MIT,变现靠 Zen 模型网关订阅 + 企业版/云控制台(monorepo 内有 enterprise/console/identity/containers 私有云栈)+ 与 GitLab 等的渠道合作。代码层与 Vercel 的关系是深度使用 AI SDK(约 20 个 @ai-sdk/* 官方包)+ 生态互推,「Vercel 投资」未获证实。
| 包 | 角色 | 体量实测 |
|---|---|---|
| packages/opencode | 主 agent 服务端(CLI+内核) | 765 文件 / 17.6 MB |
| packages/tui | 终端客户端(OpenTUI/Solid) | 241 文件 |
| packages/app / desktop | Web 客户端(SolidJS) / Electron 42 桌面端(BETA) | 643 / 306 文件 |
| packages/core · llm · plugin · protocol · schema | 领域层 / LLM 封装 / 插件与契约层 | 各百余文件 |
| 全仓 6,528 个文件 / 125MB;.ts 2700 个;测试文件 729 个;Bun workspaces + Turborepo + oxlint + tsgo(微软原生 tsc 移植) | ||
TUI 技术栈之谜的答案:Go+bubbletea(opencode-ai 时代)→ SolidJS 重写 → 现在基于 SST 自研的 OpenTUI 终端渲染框架。当前 TUI 包里大量 context/sdk 导入表明它已是标准 server 客户端而非自带内核——这正是 client/server 架构的胜利。
服务端底座:全面拥抱 Effect TS(effect 4.0-beta + 自家 HttpApi 自动生成 OpenAPI)、Drizzle ORM + SQLite(出现 db.bun.ts/db.node.ts 双轨条件导入——Node 迁移的包层实锤)、mDNS 局域网广播、端口回退。
server.ts 仅 227 行薄壳:node:http 承载 Effect HttpApiApp。关键洞察是「会话是一等公民,客户端只是视图」:TUI、Web、Desktop(Electron)、IDE 插件、ACP 协议(对接 Zed 编辑器)、Slack bot、GitHub Actions agent(github.handler.ts 高达 54KB,在 PR/issue 上自动响应)——全部通过同一套 HTTP+SSE/WS API 连接同一个 server,多端可同时观察同一会话,还带 share 分享链接功能。依赖方向被写进贡献规约:「Schema → Core/Protocol → Server;Client 只许依赖 Schema+Protocol」,协议改动必须重新生成 SDK 且禁止手改生成物。
数据模型三层品牌 ID(SessionID/MessageID/PartID):MessageV2 = Info + Part[],Part 类型涵盖 text/reasoning/tool-state(带 time.compacted 压缩标记)/attachments/subtask;token 用量统计细到 cache read/write 与成本换算(甚至处理 GitHub Copilot 的 totalNanoAiu 计量)。
MCP 基于官方 SDK(除动态工具外,MCP resources 可作为附件注入提示,10MB 上限 + MIME 白名单);LSP 管理语言服务器进程并把诊断暴露给模型;插件系统最激进——插件初始化时直接拿到一个指向本 server 的完整 SDK 客户端,意味着插件能调用全部服务器 API 而不只是被动钩子;另有 custom commands/skills/自定义 agent 与 provider/markdown 声明式扩展/codemode 实验。
| 维度 | OpenCode | Claude Code |
|---|---|---|
| 许可/模型 | MIT 全开源;BYOK 75+ provider、本地模型 | 专有;绑定 Anthropic 模型深度调优 |
| 架构 | client/server 多端共享会话 | 单机 CLI 为主 + IDE 扩展 |
| 价格 | 免费核心;Zen 网关/企业云收费 | 订阅/按量 |
| 差异化亮点 | 分享链接、桌面端、Slack/GitHub CI agent、models.dev 中立目录 | 第一方模型协同、单二进制开箱体验、权限体系成熟度 |
结论:工具语义层几乎逐一对标,真正的分野在开放性与多端协同;代价是 provider 兼容层的碎片化负担与更复杂的技术栈风险(Effect 4 beta、OpenTUI 等前沿依赖)。
类型纪律强(TS strict + Effect Schema 运行时校验双保险);架构治理成熟(依赖方向入规约、生成物禁手改、HTTP 契约测试、自建 http-recorder 录制回放);729 个测试文件。风险点:Effect/OpenTUI 等前沿依赖升级自担;单文件膨胀(provider.ts 2068 行);Session V1/V2 两套 schema 并存显示领域层大迁移仍在途中;日更级发布把稳定性更多押注在 CI 而非版本节律上。代码总量粗估 40–50 万行级。
Codex 是 OpenAI 开源的终端编码 agent,仓库自述 "Lightweight coding agent that runs in your terminal"。截至调研时点实测 118,486 stars / 18,055 forks,Apache-2.0 协议,主语言 Rust(默认分支 main,仓库创建于 2025-04-13)。它在本报告中的特殊意义在于:这是八大对象中唯一一个「厂商主动把王牌客户端完整开源」的样本——而且 OpenAI 在 2026 年 2 月的官方博客《Harness engineering: using Codex in an agent-first world》里亲手把「harness」一词推成行业方法论;2026 年 8 月媒体更是密集以「OpenAI 全面开源 Codex Harness」为题报道其三层集成接口(app-server JSON-RPC 协议、exec-server 远程执行环境、TS/Python SDK 与 MCP 接口)的开放化——严格说仓库自始就是 Apache-2.0,此轮是「把 harness 当基础设施推广」的定调(新发布物细节待确认)。
历史脉络四步走:① 2025-04-16 TypeScript 版 CLI 发布开源,数周冲到数万 star;② 2025-06 宣布用 Rust 重写(codex-rs),理由是零依赖单二进制、可预测性能,以及原生实现 OS 级沙箱需要系统级语言;③ 2025 下半年起扩张为多形态平台(TUI/exec/IDE 扩展/云端 tasks/GitHub code review/SDK);④ 2026 年起以「harness engineering」话语体系输出工程方法。模型线同步演进:GPT-5-Codex(2025-09) → GA(2025-10 DevDay) → GPT-5.1-Codex-Max(2025-11,主打 compaction 长任务) → GPT-5.2-Codex(2025-12)。
monorepo 顶层是 npm 壳包 codex-cli(安装器,真正的二进制来自 release 产物)、Rust 主工作区 codex-rs/、三语言 SDK(typescript/python/python-runtime)、Bazel+Nix 构建定义和给「跑在仓库里的 Codex 自己」看的 AGENTS.md(dogfooding)。codex-rs workspace 实测约 140 个 crate,按职能分组:
| 分组 | 代表 crate | 说明 |
|---|---|---|
| 入口/交互 | cli · tui · exec | 统一 codex 二进制的子命令与两大前端 |
| 内核 | core · protocol · config · state · thread-store · history | 会话状态机、协议类型、配置与持久化 |
| 会话记录 | rollout · rollout-trace | JSONL 会话落盘 + trace 还原器(对话单元/代码单元/压缩折叠) |
| 工具执行 | tools · shell-command · apply-patch · unified_exec · utils/pty | shell/原子补丁/持久进程管理/真 PTY |
| 沙箱安全 | sandboxing · linux-sandbox · windows-sandbox-rs · execpolicy · network-proxy | Seatbelt/Landlock/受限令牌/网络策略代理 |
| MCP 双向 | rmcp-client · codex-mcp · mcp-server · connectors | 既当 MCP 客户端,也把自身暴露为 MCP 服务 |
| 服务门面 | app-server(-protocol v1/v2) · cloud-tasks* · exec-server | IDE/桌面 JSON-RPC 后端、云任务、远程执行环境注册 |
| 扩展/记忆 | ext/{agent,memories,skills,mcp,web-search,…} · skills · hooks | 新一代模块化扩展位、技能包、生命周期钩子 |
有趣的实验痕迹也值得记录:v8-poc(在 agent 里嵌 V8 引擎的概念验证)、code-mode 系列编排实验、external-agent-migration(从他家的会话迁移过来)。
官方安全文档明确两根轴:Sandbox mode 管「技术上能做什么」,Approval policy 管「何时必须问人」。
README 实测的产品清单全部共用 codex-rs 单内核:交互 TUI、codex exec 非交互模式(脚本/CI 友好)、VS Code/Cursor/Windsurf IDE 扩展(走 app-server JSON-RPC)、桌面 App(codex app / ChatGPT 桌面端页签)、云端 Codex Web(容器隔离 tasks 队列)、GitHub @codex code review(PR 自动审查)、TS/Python SDK(本质是 spawn CLI 子进程交换 stdin/stdout JSONL 事件流)、exec-server 远程执行环境(WebSocket/Noise relay 注册,供云端驱动本地进程)。可以概括成一个公式:
一个 Rust 核心 + 三个协议门面(TUI 直连 / app-server JSON-RPC / MCP server)
+ 两个薄 SDK 包装 —— 新能力一次落地全形态生效
配置体系同样围绕单内核:全局 ~/.codex/config.toml + 项目级 .codex/ 目录、[profiles.*] 多档案、model_providers 可接任意 provider(含 ollama/lmstudio 本地 OSS 模型)、features 特性开关(JSON Schema 由 just 命令生成入库防漂移);AGENTS.md 项目指令标准正是 Codex 率先倡导、如今已成跨工具通用惯例。
| 维度 | Codex | Claude Code | OpenCode |
|---|---|---|---|
| 语言/分发 | Rust 单二进制(musl 静态),npm/brew 只是壳 | Bun+Node 单包 | TypeScript(Bun) 多包 |
| 开源深度 | Apache-2.0 全仓含核心与协议 | 专有(源码经泄露才可读) | MIT 全开源 |
| 沙箱 | OS 级强制+默认断网(三平台) | 权限提示为主,OS 沙箱可选 | 依赖进程权限约定 |
| 账号/计费 | ChatGPT 订阅直登 或 API key | Anthropic 账号/API | BYOK 75+ provider |
| MCP | client+server 双向,引擎整体可编程 | client 为主 | client 为主 |
| 多形态 | CLI+IDE+桌面+云+review+SDK+远程执行 | CLI+IDE+SDK+远程 | CLI+Web/桌面/Slack/GH |
| 话语体系 | harness engineering | agentic coding / subagents | open-source 替代 |
差异化总结:Codex 的护城河叙事不在模型单点,而在「OS 强制沙箱 + 订阅直登 + 全形态同内核 + 可嵌入 harness 接口」的组合拳。它与 Claude Code 构成一组镜像——Anthropic 把能力藏在闭源产品里卖体验,OpenAI 把客户端开出来卖模型订阅。
工程质量是八家中最「Rust 原教旨」的:clippy 规则强制 + 自研 argument_comment_lint(位置布尔参数必须带 /*param*/ 注释)+ 禁用 async_trait 改用 RPITIT;Cargo 为主 Bazel 并行的双构建体系(CI 校验 lockfile 漂移);cargo-deny 管供应链;insta 快照测试、集成测试按套件组织、沙箱测试用环境变量自检防嵌套;ConfigToml 变更必须重新生成 JSON Schema 进版本库。隐忧:仓库内文档空心化(sandbox/config 文档只剩指向官网的一行链接)、13.9k 个 open issue 的分诊压力、~140 crate 加双轨构建的新人上手成本、多条实验线并行导致边界不稳(协议文档自称 experimental subject to change without notice)。
Pi 的作者是 Mario Zechner(GitHub: badlogic,博客 mariozechner.at)——游戏开发圈无人不晓的 libGDX 框架作者。他经历过 RoboVM 被卖给 Xamarin 后闭源的痛苦,对「拥有自己工具的全部源码」有执念。2025 年 4 月起他开始逆向 Claude Code(patch 二进制、记录系统提示词演变、抓包分析),并在 11 月 30 日的博文里写下 Pi 的出发点:
"Claude Code has turned into a spaceship with 80% of functionality I have no use for… The system prompt and tools also change on every release… I hate that. Also, it flickers."
「Claude Code 变成了一艘太空船,80% 的功能我用不上……而且每次升级系统提示词和工具都变。我讨厌这样。还有,它闪烁。」——《What I learned building an opinionated and minimal coding agent》
Pi 官方定位是 "AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI",口号是 "Adapt pi to your workflows, not the other way around"(让 pi 适应你的工作流,而不是反过来)。仓库 2025-08-09 建仓,以惊人的速度冲到 97k+ stars;2026 年 4 月 Mario 带 Pi 并入 Armin Ronacher 所在的 Earendil 公司,采用 MIT 核心 + Fair Source 增值 + 专有企业版的三级模式。
| 包 | 职责 | 规模量级 |
|---|---|---|
| @earendil-works/pi-ai | 统一多 provider LLM API(消息/工具/流式/成本) | 177 个 TS 文件(含生成的模型目录) |
| @earendil-works/pi-agent-core | Agent 运行时:797 行的 agent-loop.ts + Agent 类 | 50 个文件 |
| @earendil-works/pi-coding-agent | CLI 产品(read/write/edit/bash 四工具起步) | 206 个 TS 文件 |
| @earendil-works/pi-tui | 自研保留模式终端 UI 框架 | 40 个文件 |
| @earendil-works/pi-telemetry 等 | 遥测契约、protocol/client/server 服务化拆分、evals 评测、SQLite 会话后端 | 支撑包群 |
依赖方向干净得像教科书:tui 与 ai 零内部依赖 → agent-core 只依赖 ai → coding-agent 组装全部。
packages/agent/src/agent-loop.ts 全文 797 行,提供函数式底层 agentLoop() 与有状态 Agent 类两层 API。核心是一个双 while 结构:
// 外层:follow-up 队列处理(agent 本应停止但还有排队消息→继续)
// 内层:有工具调用或有 steering 消息→继续下一轮
每轮:transformContext → convertToLlm(过滤/转换消息,契约规定不得抛异常)
→ streamFn 流式请求 → 按 stopReason 分派
→ 工具执行(默认并行,可声明 sequential;before/afterToolCall 钩子可拦截/改写)
// 亮点:stopReason=="length" 时本批工具调用全部判失败并提示模型重发
// ——防止被截断的参数真的被执行
事件流仅 10 种(agent_start/turn_start/message_*/tool_execution_*/turn_end/agent_end),订阅者按注册顺序 await。steering 机制是产品灵魂:用户中途插话会在当前轮工具执行完后注入下轮上下文(TUI 中 Enter=steering 插话,Alt+Enter=follow-up 排队)。所谓「几百行 while loop」如今长成了 797 行,但相对同类仍是数量级的差距——且每一行用户都可读、可改、可拥有。
pi coding agent 默认只有 read / write / edit / bash 四个工具;支持交互 TUI、-p 单发模式、--mode rpc(严格 JSONL 协议)、SDK 四种形态。会话持久化为可分支的 JSONL 树(每条目带 id/parentId,/tree 浏览、/fork 分叉),压缩有损但完整历史永在文件里。上下文文件走 AGENTS.md 标准(向上遍历目录),SYSTEM.md 可整体替换系统提示词。扩展四件套:单个 TS 文件的 Extension(export default function(pi){...},能替换编辑器、实现 sub-agent 甚至跑 Doom)、SKILL.md 技能、Markdown 提示词模板、热重载主题;分发走 npm/git 的 pi packages。
Mario 对 ink/React 式终端渲染的闪烁忍无可忍,于是自研了保留模式 + 差分渲染的 pi-tui:组件只须实现 render(width): string[] + handleInput + invalidate;两种渲染器分别服务主屏缓冲(保留 scrollback)与备用屏固定视口;全部更新包进 CSI 2026 同步输出实现原子无闪渲染。组件库覆盖编辑器(斜杠补全、长粘贴折叠)、Markdown 渲染、Kitty/iTerm2 图形协议图片、IME 光标定位(解决中日韩候选窗错位)等硬核细节。一个「嫌闪烁就自己写个 TUI 框架」的人,做出来的东西自然不容小觑。
"If I don't need it, it won't be built. And I don't need a lot of things."
「我不需要的东西就不建。而我需要的并不多。」
"Precise control over what goes into the context is what produces better results… Existing harnesses inject things you can't see behind your back."
「精确控制进入上下文的每一行才能产出好结果,尤其是写代码。现有 harness 在你背后注入你看不见的东西。」
"MCP servers aren't composable — results must route through the agent context. Bash and code are naturally composable."
「MCP 不具组合性——结果必须穿过 agent 上下文;而 Bash 和代码天然可组合。」(配套理念:给工具写 README 就是给模型的文档)
"One year in: nobody knows what they're doing yet. We're all throwing spaghetti at the wall and declaring victory while quietly crying about the tech debt our agents create. Anyone claiming to have the answer — don't trust them."
「干这行一年后的总结:还没人知道该怎么做。我们都在往墙上扔面条然后宣布胜利,同时偷偷为 agent 制造的技术债哭泣。谁宣称找到了答案——别信。」
"If you feel we've lost the plot, the fork button on GitHub always works."
「如果你觉得我们跑偏了,GitHub 上的 fork 按钮永远有效。」
约 550 个测试文件(vitest 统一基座,含跨 provider 真机特性测试);Biome lint/format;discriminated union 类型设计 + declaration merging 扩展点;"must not throw or reject" 式契约注释文化。发布工程罕见地认真:Bun 编译独立二进制、SHA256SUMS 发布、依赖精确 pin + min-release-age=2 防供应链投毒、生命周期脚本白名单。治理上甚至以「新贡献者 PR 自动关闭+每日人工复核」对抗 AI 生成的垃圾贡献——这个细节本身就是 2026 年开源生态的时代注脚。总体评价:小核心、厚产品、重测试、强供应链意识,「极简」不是偷懒而是把复杂度精确地放在了值得的地方。
DeepSeek Harness(下称 DSH)是 DeepSeek 官方的 agent harness——一个围绕模型构建的完整运行时平台。与 Claude Code「单体内聚」不同,DSH 把自己拆成了 150 个独立的 npm 插件包(@deepseek-ai/dsh-*),通过 cordis 插件框架(源自 Koishi 生态的服务化插件内核)组合成不同形态的「表面」(surface):dsh web 浏览器 GUI、dsh --profile headless 无头批处理、以及可自建的 TUI 等任意 profile。每个包都发布带中英双语的 README 契约文档,工程纪律罕见地严格。
| 子系统族 | 代表包 | 职责 |
|---|---|---|
| 内核框架 | cordis / cordis-plugin-loader·hmr·timer / cosmokit / schemastery | 服务注册、作用域生命周期、配置校验、热重载 |
| Agent 核心 | dsh-agent-loop / dsh-agent / dsh-agent-presets / dsh-agent-instructions / dsh-persona / dsh-system-prompt | 唯一的具体 ReAct 循环;agent 组合预设;提示词装配注册表 |
| 模型层 | dsh-llm / dsh-llm-deepseek / dsh-llm-pi-ai / dsh-llm-retry / dsh-token-meter | provider 无关的流式调用抽象 + 适配器注册表;直接复用 Pi 的 pi-ai 作为多 provider 统一层 |
| 会话 | dsh-session / session-persistence-jsonl / session-query-sqlite / session-projection / compaction-basic / compaction-tool-result-pruner | 事件溯源日志、JSONL/SQLite 持久化、投影缓存、压缩引擎 |
| 工具集 | tool-bash(-persistent) / tool-pwsh(-persistent) / tool-fs / tool-fs-search / tool-str-replace-editor / tool-web / tool-todo / tool-subagent(+control/report) / tool-goal / tool-workflow / tool-skill / tool-ask-user / tool-jobs / tool-cordis / dsh-tools | 与本文开头描述的工具面一一对应:bash/pwsh 双 shell 持久会话、文件编辑、搜索、子代理、目标、工作流编排…… |
| 安全 | dsh-sandbox / sandbox-local / sandbox-policy / fs-sandbox / fs-observation-policy / sandbox-windows-acl / bash-sandbox / pwsh-sandbox / permission-presets / user-approval / authorization | 三态文件沙箱策略、Windows ACL 受限令牌运行器、审批服务、单调权限护栏 |
| 多代理 | dsh-subagent / subagent-fork-in-process / subagent-spawn-in-process / subagent-in-process-driver / jobs / workflow(+worker-thread) | 一次性/可续聊子代理、后台作业、脚本化多代理编排 |
| 长任务 | dsh-goal / goal-round-driver / schedule / plan-mode | 事件溯源目标系统、自动续跑驱动、定时自动化、计划模式 |
| Web 表面 | dsh-web-app / web-frontend / client-ui-*(30+ 个)/ api-gateway / host-webserver / client-runtime·hmr·modules | 浏览器 GUI 全家桶:会话流、设置面板、目标面板、子代理面板、交付物渲染等 |
| 生态接入 | dsh-mcp-client / skill / skill-filesystem / web-search-deepseek / credentials / settings-file / telemetry-otel | MCP 客户端、SKILL.md 技能、凭据存储、OpenTelemetry 遥测 |
DSH 的启动器 dsh 本身只做一件事:选定 profile 并按序叠加配置层。一个 profile = 一个 dsh.profile 清单(声明 bundles 列表)+ 用户覆盖层 cordis.patch.yml。配置树从空根开始:
空根
└─ bundle 1:dsh-base(模型适配器、默认模型选择、工具、持久化、策略、遥测、子代理 provider)
└─ bundle 2:dsh-web-app 或 dsh-headless(表面层,按需挂载 Web 主机/headless 运行器)
└─ profile 自己的 cordis.patch.yml
└─ $DSH_HOME/cordis.patch.yml(用户级)
└─ --patch 命令行覆盖层
每一层都是对插件行(row)的整体替换式 patch(无深合并——这是明说的取舍:宁可重复声明也不做隐式合并)。--dump-config 可在不启动的情况下检查合成结果。这套「声明式叠加」让同一个内核可以长出完全不同的产品形态,也意味着本报告的分析者本身就是某个 profile 的运行实例。
dsh-agent-loop 的 README 开宗明义:「这是整个 harness 中唯一包含具体循环逻辑的包。其他一切都是针对扩展点的抽象服务或插件——新行为进插件,不进这里」。它的循环是一个名为 ReactLoopAgent(ReAct 循环驱动器)的包内私有实现,对外只暴露契约:
dsh-session 把会话建成append-only 事件日志:LLM 消息历史只是从日志「推导」出的视图(deriveMessages()),上面还维护一层 surface 投影加速推导与压缩。关键设计:
这套设计的回报是:重启恢复、会话分叉、投影查询(SQLite)、审计重放全部免费获得——goal、plan mode、sandbox mode 等所有有状态的子系统都把自己的状态写成一种带类型的日志事件(如 sandbox/mode、plan/mode、goal/change),而不是藏在内存里。「状态即事件」是 DSH 区别于其他五个对象的根本特征。
dsh-system-prompt 是一个「提示词装配注册表」:插件贡献有序 section(order 排序,agent 作用域可遮蔽全局)、动态 context(每次装配时求值并作为带来源的运行时快照写入历史)、工具 schema 提供者、模板变量({{model}}/{{cwd}})。装配经过 system-prompt/assemble 瀑布事件——监听者拥有最终决定权(比如 Code Mode 或结构化输出协议在此注入自己的格式约束)。压缩方面,compaction-basic 实现了教科书级的压缩事务:tokenMeter 计压 → 工具结果修剪 → 选段保留尾部 → 用「重放对话自身前缀」的方式调用摘要(复用 KV cache!)→ 收缩率验证 → 失败重试上界 → 溢出恢复路径单独处理。连摘要调用都会打上 x-deepseek-harness-compact 归因头。
确定性/可控性 ◄──────────────────────────────────────────► 模型自主性
LangGraph LangChain v1 DeepAgents Codex DeepSeek Harness Claude Code/OpenCode Pi
(每步都是图节点)(默认ReAct图+ (三件套预置图,(审批三态+ (自由循环,但一切 (自由循环+层层护栏) (自由循环,
middleware可插) 可摘装重组) OS级沙箱) 状态留痕可审计) 几乎无护栏)
八个对象其实是同一个问题的八个答案:「你愿意把多少控制权交给模型?」LangGraph 把答案压到最低(每一步都要显式声明),Pi 把答案放到最高(模型自己看着办),其余六者在中段各取所需。没有对错,只有场景。
| 维度 | Claude Code | LangChain | LangGraph | DeepAgents | Codex | OpenCode | Pi | DeepSeek Harness |
|---|---|---|---|---|---|---|---|---|
| 产品形态 | 终端 CLI 产品 | Python/JS 框架库 | 编排引擎库(+商业Server) | 通用 agent 参考实现库 | CLI+云任务+IDE 开源全家桶 | CLI+多客户端平台 | 工具包+CLI 产品 | 运行时平台(插件微内核) |
| 代码组织 | 单体应用(~1900文件) | monorepo 分层(core/v1/classic/partners) | monorepo 9 包 | 单包+middleware 群 | Rust workspace(codex-rs)+TS SDK | Bun monorepo 20+包 | monorepo 5 主包 | 150 个独立插件包 |
| 核心循环 | query.ts while(true) async generator | create_agent→LangGraph 图 | Pregel BSP 超步 | create_deep_agent(middleware 套装) | Rust 核心 turn 循环 | SessionPrompt Service(Effect Layer 25 服务) | 双 while agent-loop.ts(797行) | ReactLoopAgent(唯一具体循环,其余皆插件) |
| 语言栈特色 | Bun+React Ink | Pydantic 全家桶 | Pregel/通道原语 | 复用 Pydantic/LangGraph 原语 | Rust+Seatbelt/Landlock 沙箱 | Effect TS+Drizzle+OpenTUI | TypeBox+自研 TUI | cordis 插件框架+schemastery |
| 状态管理 | 内存消息数组+会话文件+墓碑压缩 | 图状态+checkpointer | 通道快照+checkpoint 三维寻址 | 继承 checkpointer+虚拟文件系统外置记忆 | rollout JSONL(resume/fork) | SQLite(Drizzle) Session/Message/Part 表 | JSONL 会话树(可分支) | 事件溯源日志=唯一事实源+投影查询 |
| UI 形态 | Ink 终端 UI(组件140个) | 无(库) | 无(库)+Studio | 无(库) | TUI(TUI-rs)+VS Code 扩展+云端 | TUI/Web/Desktop/IDE/Slack 共享 server | pi-tui 同步差分渲染 | Web GUI(30+客户端插件)/headless/TUI |
| 模型接入 | 仅 Anthropic(深度协同) | 75+ provider(partner 包) | 经 langchain-core 或裸 SDK | 任意 langchain chat model(init_chat_model) | OpenAI 模型为主+OSS 模型接入 | AI SDK+models.dev 目录,BYOK+OAuth | pi-ai 四协议抽象+30余家 | 适配器注册表(DeepSeek 直连+pi-ai 底座) |
| 项目 | 模式分级 | 强制手段 | 审批交互 | 审计 |
|---|---|---|---|---|
| Claude Code | default/acceptEdits/plan/dontAsk/bypassPermissions 五档+内部 auto/bubble | 规则引擎三层漏斗+Bash 命令语义分析+OS 沙箱(可选) | 逐条询问/气泡确认/hook 可拦截 | 诊断日志脱敏+analytics |
| LangChain | 交给宿主应用;HITLMiddleware 提供审批点 | ShellToolMiddleware 的 Docker/Host/CodexSandbox 三策略 | interrupt_on_tool 人工批准 | LangSmith 追踪 |
| LangGraph | 无内置;interrupt() 原语随处可设检查点 | 交给部署环境 | Command(resume) 恢复协议 | checkpoint 全量快照天然可审计 |
| DeepAgents | HITL middleware 可插审批点(默认薄弱) | 需自行接 Docker/沙箱执行策略 | interrupt_on_tool 工具级人工批准 | 依赖 LangSmith/宿主环境 |
| Codex | sandbox_mode 三态(read-only/workspace-write/danger-full-access)+approval_policy 四级语义(untrusted/on-failure/on-request/never,现以 Auto/Read-only/Full Access 预设档呈现) | OS 级强制沙箱:macOS Seatbelt/Linux Landlock+seccomp/Windows 受限令牌(AppContainer) | 逐条审批或全自动,策略写入 config.toml;网络默认关+域名代理策略 | rollout 全量落盘可回放 |
| OpenCode | permission 配置规则+内置 agent 权限合并 | Question 工具交互批准 | PermissionV1 schema | SQLite 全量落库 |
| Pi | 拒绝内置权限弹窗(建议容器化:Gondolin 微VM/Docker/OpenShell) | 外部容器隔离;trust.json 项目信任 | 无(yolo 哲学) | JSONL 全量历史 |
| DSH | read-only/workspace-write/danger-full-access 三态+审批策略预设 | Windows ACL 受限令牌/POSIX landlock+单调 guard 护栏+fs 观察策略 | user-approval 服务(ask/never 等 policy) | sandbox/mode 等全部状态事件化留痕 |
| 项目 | 子代理形态 | 编排方式 | 独门设计 |
|---|---|---|---|
| Claude Code | 递归嵌套 QueryEngine;异步后台代理(工具白名单) | coordinator 宪法提示词+swarm 团队(tmux/iTerm 队友) | continue vs spawn 决策表;验证者新鲜眼睛原则;DreamTask |
| LangChain | deepagents 参考实现(sub-agent spawning) | middleware 编排;TodoListMiddleware 规划 | 把 CC 式架构反哺成官方中间件 |
| DeepAgents | 内置 task 工具派生子代理(支持自定义 subagents 配置) | 主代理自主编排 | 把「规划+文件系统+子代理」做成默认出厂三件套 |
| LangGraph | 子图节点;supervisor/swarm 官方包 | Send 动态扇出+Command(graph=PARENT) 层级回传 | BSP 并行的确定性 fan-in/fan-out 语义 |
| Codex | 单循环无内置 subagents(并行靠多进程与云任务) | —(内核刻意保持简单) | 云端 best-of-n 多方案并行+@codex 自动审 PR |
| OpenCode | Task 工具开子会话(标题前缀 Child session) | server 统一调度;@agent 名直调 | 多客户端同时观察同一会话 |
| Pi | 拒绝内置(扩展可实现) | — | "搞 agent 大军的人没几个真发表过工作成果" |
| DSH | one-shot/continuable 双模+provider 注册表+fork 血缘 | workflow 引擎跑模型写的 JS 编排脚本(pipeline/parallel) | 越权打断防护(人类持久父地址/活体祖先);深度上限;描述符持久化 |
| 项目 | 进程内扩展 | 跨进程协议 | 知识包 | 生态规模感 |
|---|---|---|---|---|
| Claude Code | plugins(dxt)/slash commands/subagent 定义 | MCP+hooks(shell 命令) | Skills(SKILL.md) | 最大商业生态 |
| LangChain | middleware(30+内置) | partner 包生态 | Hub prompt 托管 | 最大集成广度 |
| DeepAgents | middleware 摘装/自定义工具与子代理 | —(库本身即扩展) | 官方示例模板 | LangChain 生态直通车 |
| LangGraph | 自定义节点/checkpointer | Server API+SDK | Studio 模板 | 生产部署生态 |
| Codex | custom prompts/config profiles/exec 模式脚本化 | MCP client+server 双向(codex mcp-server 暴露全组 JSON-RPC) | AGENTS.md 标准发起者之一 | OpenAI 官方+OSS 社区双轮 |
| OpenCode | plugin(拿到全 API 客户端!)/custom provider 运行时 npm 安装 | MCP+ACP(Zed)+LSP | skills/custom commands | 增长最快的开源生态 |
| Pi | 单文件 extension(registerTool/registerCommand/on) | 拒绝 MCP(CLI+README 替代) | SKILL.md+prompt templates+themes | 小而硬核 |
| DSH | cordis 插件 patch 叠加(150包) | MCP client+skill 文件系统 | SKILL.md 标准+persona | 平台级自洽生态 |
| 项目 | 主体 | 开源边界 | 变现 |
|---|---|---|---|
| Claude Code | Anthropic | 专有(SDK 开源);2026-03 source map 泄露成为意外教材 | 订阅/API 计费 |
| LangChain+LangGraph | LangChain Inc. | MIT 框架;闭源 Server(langgraph-api) | LangSmith SaaS+Deployment |
| DeepAgents | LangChain Inc. | MIT 全开源参考实现 | 无独立变现(为生态导流) |
| Codex | OpenAI | Apache-2.0 开源客户端(Rust),2026 年被社区称为「全面开源的 Codex Harness」 | ChatGPT 订阅/API 计费(客户端即入口) |
| OpenCode | Anomaly(YC) | MIT 核心+私有企业云栈 | Zen 网关+企业版 |
| Pi | Earendil(2026-04 并入) | MIT 核心+Fair Source 增值+专有企业版三级 | 企业授权+商标 |
| DSH | DeepSeek | 发行包含完整契约文档 | 服务 DeepSeek 生态 |
值得注意的是open-core 已是绝对主流:八个对象中六个有明确的「免费核心+付费增值」切分线(DeepAgents 为纯开源参考实现;Codex 客户端开源但价值锚定在模型订阅),且切分位置惊人一致——框架/内核开源,运行时/托管/企业管控收费。这印证了 agent 时代的价值分布:代码不值钱,运营和信任才值钱。
综合八个对象的源码证据,本章回答一个实际问题:如果自己动手搭一个 agent,需要哪些部件?哪些坑已经被前人用血泪标好了?
| # | 组件 | 职责与最小实现 | 参考范本 |
|---|---|---|---|
| 1 | Agent 循环 | while(true):组装请求 → 流式调用 → 解析 tool_use → 执行 → 结果回填 → 继续。这是全部魔法的本体,几百行足够。 | pi agent-loop.ts(797行);Claude Code query.ts |
| 2 | 模型接入层 | 统一消息格式与内容块、流式 chunk 协议、AbortSignal 全链路、重试与退避、usage/成本统计。别自己发明——用 pi-ai 或 Vercel AI SDK。 | pi-ai;DSH dsh-llm |
| 3 | 工具系统 | schema 定义(zod/TypeBox)、注册表、权限钩子、并行/互斥调度、结果长度限制、进度上报。 | Claude Code Tool.ts 三件套;DSH tools/pre-execute 流水线 |
| 4 | 上下文管理 | 系统提示词装配器(有序 section)、历史压缩(阈值触发+摘要)、大工具结果修剪、可选长期记忆。 | CC REACTIVE_COMPACT+墓碑化;DSH compaction-basic;memdir |
| 5 | 会话持久化 | 至少 JSONL append-only 日志 + 启动重放恢复;进阶版做事件溯源+投影查询+fork。 | pi 会话树;DSH dsh-session |
| 6 | 权限与安全 | 分级模式(只读/工作区写/全权)、allow/deny/ask 规则、审批 UI、OS 沙箱、审计日志。默认拒绝。 | CC 五档权限;DSH 三态沙箱+ACL |
| 7 | Shell 执行器 | 持久 shell 会话(省启动开销)、超时与后台作业、输出截断、命令安全分析。 | CC BashTool 18 文件纵深防御;DSH tool-bash-persistent |
| 8 | 子代理机制 | 上下文隔离的一次性委托 + 结果回流协议;工具白名单;深度上限。 | CC AgentTool;DSH SubagentRuntime one-shot |
| 9 | 交互层 | 流式渲染、用户打断、中途插话(steering)、结构化提问。 | pi-tui 同步渲染;CC Ink 组件;DSH Web GUI |
| 10 | 可观测与评测 | 结构化 trace、token 计量、把真实任务固化为回归评测集。 | LangSmith;pi evals 包;DSH telemetry-otel |
三个对象的演化史其实给出了同一个暗示:循环本身正在变成商品(LangChain 把 agent 建在 LangGraph 上、DSH 把循环收进唯一的插件、pi 直接开源了循环),真正的价值都在循环之外——上下文工程、安全、持久化、评测。自建时请把钱花在刀刃上。
八个对象给出了同一个信号:agent 循环本身正在变成免费商品。LangChain v1 把 agent 收敛为一个函数(建在 LangGraph 上);pi 把循环开源成 797 行教材;DSH 把循环收进唯一的具体插件;连 OpenCode 都以「open harness」自居。可预期的推论:未来差异化竞争全部发生在循环之外——上下文工程、持久化可靠性、安全治理、评测体系、组织协作。新入局者再做一个「更好的 while 循环」已无意义,要做的是更好的 harness 组件。
2023 年大家谈 prompt engineering,2025 年谈 context engineering,2026 年它已经细分出明确的子领域:
2026 年的产品线同时押注了多代理:Claude Code 的 swarm 队友(tmux/iTerm 真实终端窗格)与 coordinator 宪法、DSH 的 workflow 编排引擎、LangGraph 的 supervisor/swarm 官方包。但 Mario 的冷水值得挂在墙上:「让它们写大量代码一直是灾难配方」。更可能的终局不是 agent 大军,而是小规模分工明确的 agent 团队(协调者-执行者-验证者三角),配合 continue-vs-spawn 这类上下文管理纪律——多智能体的难点从来不是通信协议,而是组织成本与责任边界。A2A 协议进入 Linux Foundation 后,跨厂商 agent 互操作会在 2027 年前后开始标准化试水。
MCP 已赢得「连接标准」之战(本次分析的 agent 中除 Pi 高调拒绝外几乎全部支持),但反叛同样真实:Mario 用数据证明 MCP 工具描述的 token 成本(Playwright MCP 占 Claude 上下文 6.8%),主张 CLI+README 的组合性路线;Anthropic 自己也在用 Skills 承载「过程性知识」。预判格局:MCP = 外设接口(USB),CLI/代码 = 本地总线,Skills = 驱动程序说明书,AGENTS.md = 主板说明书——四者共存而非互替,竞争焦点转向 A2A 式的「agent 与 agent」层。
ReAct 时代靠提示词教会模型用工具;o1/R1 时代推理内化为思考链;下一步是 agentic RL——在真实或仿真环境中用任务成败奖励训练模型的多步决策(SWE-bench 分数的军备竞赛即是缩影)。对 harness 的含义深远:模型的「开箱 agent 能力」越来越强,harness 的护栏价值上升而「教模型做事」的提示词价值下降。Claude Code 泄露源码中那些精巧的提示词工程,五年后可能大半变成模型默认能力——但权限、审计、恢复这些护栏不会过时。
本次研究本身就是证据之一:LangChain 和 LangGraph 仓库根目录都放着 AGENTS.md/CLAUDE.md(它们用自己的框架喂 AI 开发自己);LangChain 用自动关闭 PR 对抗 AI slop 贡献;pi 甚至把「新贡献者审核」做成了每日人工流程。Claude Code 源码泄露事件则揭示了另一个反身性风险:构建产物里的 source map 在 AI 辅助打包流程中更容易被忽视。未来三年,「AI 开发的软件如何被安全地发布与审计」本身会成为一门显学。
以下 12 个问题是按「读完本报告后你最可能想问」整理的,答案全部浓缩自前文各章的源码证据,括号内为详见章节。
四条判断线:① 模型生态——深度绑定 Anthropic 选 Claude Code,深度绑定 OpenAI/ChatGPT 订阅选 Codex;② 开放性——想 BYOK 接任意模型、多端共享会话、可自托管选 OpenCode;③ 掌控力——想读懂并拥有每一行、按自己工作流魔改选 Pi;④ 安全合规——企业环境对沙箱有硬要求的,Codex 的 OS 级强制沙箱与 Claude Code 的五档权限体系最成熟(详见第二、六、七、八章与第十章对比)。
批评主要针对 0.0.x 时代的巨石包与 AgentExecutor 黑盒,而 v1 已经结构性回应:主包只剩三个运行时依赖、create_agent 一个函数替代整个子类动物园、middleware 洋葱模型取代继承树、旧世界封存进 langchain-classic。如果你的核心诉求是快速集成几十家模型/向量库,它仍是首选;如果只要可控编排,可以跳过它直接用 LangGraph(详见第三章)。
两条路:用 LangGraph——checkpointer 三维寻址 + interrupt()/Command(resume) 就是为此而生,代价是接受图心智模型(详见第四章);或选带持久化内核的产品——Codex 的 rollout JSONL 与 thread/resume/fork 协议、DSH 的事件溯源会话都是开箱即用的方案(详见第七、九章)。自建的话,事件溯源是最省心的架构(第十一章军规 14)。
场景化决策:对接外部标准化服务(GitHub、数据库、浏览器)用 MCP,生态成熟、即插即用;高频内部能力优先做成 CLI 工具并配一份好 README——Mario 的实测是 Playwright MCP 的 21 个工具描述吃掉 Claude 上下文约 6.8%,而 Bash+代码天然可组合、零常驻开销(详见第八章)。Codex 则展示了第三种姿态:client+server 双向,把自己的引擎也暴露成 MCP 服务(第七章)。先算 token 账,再定协议。
不是伪需求,但被严重高估了。行业现状是两极并存:Claude Code 做出了 swarm 团队和协调者宪法、DSH 提供工作流引擎,而 Pi 干脆拒绝内置。比较可靠的共识是三点:① 用小规模分工明确的三角结构(调研-实现-验证),不要 agent 大军;② 严格执行 continue vs spawn 决策表与「验证者新鲜眼睛」原则(第二章);③ 并行写操作必须做文件级隔离(worktree 或任务分区)。组织成本才是多智能体的真正瓶颈(第十三章 13.4)。
核心循环的参照物是 Pi 的 agent-loop.ts——797 行(第八章);加上统一模型层可以直接复用 pi-ai。但「能用」和「能上生产」之间隔着第十一章列出的全部护栏:权限、沙箱、持久化、压缩、评测。真实的成本分布是:循环占 5%,循环之外占 95%——这正是各家不约而同把创新重心放在循环之外的原因。
会丢,所以各家都做了保底设计:Pi 的压缩有损但完整历史永远保留在 JSONL 文件里可回查;DSH 对摘要做收缩率验证、失败重试上界和独立的溢出恢复路径;Claude Code 用墓碑化保留「这里曾有内容」的占位提示。实践建议:把「不可丢」的信息外置到文件系统或记忆目录(DeepAgents 的虚拟文件系统思路),让压缩只处理可再生的过程性内容(详见第五、七、八、九章)。
三个层次:AGENTS.md / CLAUDE.md 是项目记忆——给 agent 的项目说明书,前者是 Codex 率先倡导的跨工具通用标准,后者是 Claude Code 的同源实现,多数工具两者通读;SKILL.md 是技能包——按需加载的过程性知识(Anthropic 开放的标准),解决「不用的知识不占上下文」;系统提示词本身则由各家 harness 在装配时生成,用户一般不直接编辑。一句话:项目说明写给所有 agent,技能包按需翻书,系统提示词归厂商管。
四件套:① 默认拒绝——权限从最小集开始,切换必须留痕(第九章的 sandbox/mode 事件范式);② OS 级隔离——至少容器化,预算充足就学 Codex/DSH 上 Seatbelt/Landlock/受限令牌;③ 审批留痕——破坏性操作强制人工确认且全程可审计;④ 供应链加固——依赖 pin 死、min-release-age 缓冲、生命周期脚本白名单(第八章 pi 的清单可直接抄)。提示词层面的「请你小心」不算安全措施。
本报告的源码证据给出的答案是:它们取代的是打字量,不是判断力。最直接的证据是 Claude Code 协调者宪法里那句「验证者要用新鲜的眼睛」和 DeepAgents 局限里「接生产必须自补审批」——行业最好的实践仍然围绕「人类在哪里介入」设计接口。角色正在从写代码转向:写 spec(协调者综合纪律)、做评审(verification agent 无法替代的最终责任)、以及管好这群 agent(harness 工程,详见第七章)。
本报告第二章基于的快照来自 2026 年 3 月经 npm source map 意外公开的内容,镜像仓库以教育与研究目的分发、未主张任何权利。本报告的使用方式是评论与分析(引用架构事实与少量短句),而非再分发代码本体;这属于对已公开材料的研究性使用范畴。同时它也提醒所有厂商:构建产物里的 source map 是真实的数据泄露面,应在 CI 里加检测(第十三章 13.8 的反身性问题)。
分三档:一手实测(GitHub API、PyPI 时间戳、本地源码行数)可信度最高,均标注了实测时点;官方渠道(博客、文档、release notes)次之;二手报道(媒体转述的融资额、用户数)最低——凡是未能一手核实的,正文一律标了「待确认」。所有数字都是 2026 年下半年调研时点的快照,这个领域月度变化极大,引用请注明口径(详见第一章 1.2 与第十五章)。
— 全文完 · 《AI Agent 架构深度研究报告》 · 由 ox-alpha 基于 DeepSeek Harness 生成 —
分析者本身即运行于报告第九章所描述的 DeepSeek Harness 之上——这大概是本报告最独特的「方法论」注脚。