AI Agent 架构深度研究报告

基于源码的八大智能体系统剖析:设计哲学 · 核心机制 · 横向对比 · 自建指南 · 历史与趋势
Claude Code(泄露源码) LangChain LangGraph DeepAgents Codex OpenCode Pi DeepSeek Harness

分析方式:本地源码精读(Claude Code 快照 ≈1900 文件 / 51 万行 TypeScript;DeepSeek Harness 已安装发行包 150 个插件包)
远程调研:GitHub 在线阅读(LangChain / LangGraph / DeepAgents / Codex / OpenCode / Pi),未在本地保留任何仓库代码
版本基准:2026 年(各项目 star 数/版本号为调研时点实测快照) · 报告生成日期:2026年8月26日

第一章 · 导言:Agent 到底是什么

「Agent」是过去三年被用得最滥、也最缺精确定义的技术词汇。在讨论具体系统之前,必须先给出本报告的工作定义:

Agent = 以 LLM 为决策内核、以工具为手脚、以循环为骨架、以目标为导向的自主软件系统。 它区别于普通 LLM 应用的关键在于三点:① 模型自己决定下一步调用什么工具(而非人写死的流程);② 执行结果会回流到模型上下文中形成闭环;③ 终止条件由模型或环境判断,而非固定步数。

Anthropic 在其工程博客《Building Effective Agents》中给出的区分被业界广泛引用:Workflow 是「开发者写死流程、LLM 填空」的系统;Agent 则是「开发者给目标和工具,LLM 自己找路径」的系统。本次分析的八个对象恰好横跨这个光谱的两端和中间——LangGraph 允许你把每一步都画成图(强工作流),Pi 则把整个系统压缩成一个自由循环(纯 agent),Claude Code / OpenCode / DeepSeek Harness 位于中间:一个自由循环加上层层安全护栏。

1.1 为什么选这八个对象

对象形态入选理由
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——本身就是行业融合的活样本。

这八个对象覆盖了五种截然不同的架构哲学:

1.2 分析方法与材料边界

诚实性声明 各项目版本迭代极快(周级发版)。本报告所有版本号、star 数、组织归属均标注「截至 2026 年初快照时点」;个别无法从一手来源确认的信息会明确标记「待确认」,绝不冒充确定。

1.3 一张表先看清全局

维度Claude CodeLangChainLangGraphDeepAgentsCodexOpenCodePiDeepSeek Harness
一句话定位终端里的软件工程 agent 标杆LLM 应用开发全家桶框架agent 状态机编排引擎Claude Code 架构的官方开源图纸OpenAI 开源终端 agent 基础设施开源模型无关终端 agent极简 agent 工具包/循环插件化 agent 运行时平台
语言/运行时TypeScript + BunPython(另有 JS 版)Python(另有 JS 版)Python(另有 JS 版)Rust + TypeScript(SDK)TypeScript + BunTypeScriptTypeScript + 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-stepcreate_deep_agent(middleware 套装+图引擎)Rust 核心 agent loop(turn 制)session 循环(client/server)数百行显式 loopReactLoopAgent 插件
状态管理内存消息数组 + 会话文件Runnable 状态透传Checkpoint 持久化状态图继承 LangGraph checkpointerrollout JSONL 会话文件(resume/fork)服务端 session 存储JSONL 会话文件事件溯源日志(唯一事实源)
扩展机制MCP/hooks/plugins/skills/subagents包生态/integrations/middleware节点/checkpointer/子图自定义工具/子代理/中间件摘装MCP 双向/config.toml/profiles/custom promptsplugins/MCP/自定义 provider自定义工具文件/extensionscordis 插件 patch 叠加
安全模型五级权限模式+规则+沙箱+hook 拦截交给宿主应用interrupt 审批点HITL middleware(默认薄弱,需自补)三态沙箱+四级审批策略+OS 级强制隔离工具审批+可配置权限极简(yolo 为主,用户自担)read-only/workspace-write/full-access 三态+ACL 沙箱+审批服务
适合谁想要开箱即用的最强编码 agent要快速集成几百种模型/向量库的应用开发者要可控可恢复长流程的生产系统想基于「标杆骨架」快速二次开发的团队OpenAI 生态用户与要 OS 级沙箱硬隔离的团队想用任意模型且要求开源透明想完全理解并拥有每一行代码的人要把 agent 当基础设施长期运营的团队

第二章 · Claude Code:行业标杆的完整解剖

2.1 源码快照的来历与规模

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.tsx4446 行CLI 入口编排(Commander.js 路径分发、全局初始化)
query.ts / QueryEngine.ts1612 + 1234 行Agent 主循环与查询引擎(全系统的发动机)
Tool.ts / tools.ts754 + 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 的「智能」100% 来自模型,而它的「好用」100% 来自笨拙但严谨的工程——51 万行代码里没有一个「agent 框架」,只有一个 1600 行的 async generator 循环和几十个精心打磨的工具。所谓标杆,就是把每一条边角情况都写成了 if 语句。

2.2 总体架构:单进程富客户端

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 递归嵌套

几个关键的架构事实:

2.3 主循环解剖:query.ts 的状态机

主循环是一个 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
  }
}

值得展开的机制细节:

2.4 工具系统:三件套模式与纵深防御

2.4.1 Tool 接口契约

Tool.ts 定义了每个工具必须实现的完整契约:名称、description、zod input schema、validateInput、checkPermissions(input, ctx): Promise<PermissionResult>、execute、以及专属的 Ink UI 渲染组件与 progress 类型。也就是说,每个工具自带三层:给模型看的说明书(prompt.ts)、给内核看的校验器(permissions/validation)、给人看的可视化(UI.tsx)。新增一个工具 = 新建一个目录放齐三件套,再在 tools.ts 注册表挂载。

2.4.2 全量工具清单(按职能分组)

组别工具要点
文件FileRead / FileWrite / FileEdit / Glob / Grep / NotebookEditRead 带 imageProcessor(读图)、limits(行数/大小上限)、FileStateCache 记录 mtime 防脏写;Edit 强制先 Read 后改
ShellBash / PowerShell / REPL双 shell 对称实现;各配 8-10 个安全子模块;REPLTool 可在持久解释器里跑代码
网络WebFetch / WebSearchWebFetch 有 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 / ConfigToolSearch 支持按需检索海量工具;LSPTool 接语言服务器拿符号定义/引用
调度/远程ScheduleCron(Create/List/Delete) / RemoteTriggercron 定时拉起 agent;远程会话触发器

2.4.3 BashTool:一个工具里的安全宇宙

最能体现工程密度的是 tools/BashTool/(18 个文件)。执行一条 shell 命令前要穿过:

PowerShellTool 有完全对称的一套(外加 clmTypes.ts 处理 ConstrainedLanguage 模式、gitSafety.ts 拦截危险 git 操作)。Windows PowerShell ConstrainedLanguage 模式的沙箱思路与 DeepSeek Harness 如出一辙——两条产品线在同一平台问题上收敛到了同一答案。

2.5 权限体系:把「敢不敢让它跑」做成产品

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」,即「记住我的选择」。这个体系后来被几乎所有同类产品借鉴。

2.6 多智能体:从 subagent 到 swarm 团队

Claude Code 的多代理体系分四层,一层比一层激进:

第一层:AgentTool 子代理(最常用)

第二层:协调者模式(Coordinator Mode)

coordinator/coordinatorMode.ts 内嵌了一篇千行级的「协调者宪法」系统提示词,其要点极具教学价值:

第三层:Swarm 队友系统(实验性)

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 中走得最远的「多终端窗口协作」实验。

第四层:RemoteAgentTask / ScheduleCron

任务可以托管到云端远距执行(remote/ 目录含 RemoteSessionManager 与 WebSocket 协议),配合 cron 工具实现「睡前派活、早上收 PR」的工作流。

2.7 上下文工程:51 万行里最见功力的部分

2.8 扩展机制四件套:MCP、Hooks、Plugins、Skills

机制形态源码证据
MCP标准协议接入外部工具/资源,带服务器级审批(mcpServerApproval)与 OAuth(McpAuthTool)services/mcp/*、MCPTool 系列工具
Hooks在 PreToolUse/PostToolUse/UserPromptSubmit/Stop/SessionStart… 等事件点执行用户 shell 命令,可阻断/改写流程;支持同步 JSON 响应与异步 hooktypes/hooks.ts(zod schema 定义 syncHookResponseSchema:continue/suppressOutput/stopReason…)
Plugins捆绑分发的能力包(可含命令/工具/hook/MCP 配置),dxt(Desktop Extensions)目录结构plugins/builtinPlugins.ts、utils/dxt
SkillsSKILL.md 形式的「过程性知识包」,模型按需加载;内置 verify/debug/loop/remember/simplify/skillify/stuck/batch/scheduleRemoteAgents 等官方技能skills/loadSkillsDir.ts、skills/bundled/*

2.9 产品化的魔鬼细节

Voice 语音输入
services/ 下有 voice.ts/voiceStreamSTT/voiceKeyterms——桌面端语音口述需求,关键词触发指令。
Buddy 终端宠物
buddy/companion.ts + CompanionSprite.tsx:一个像素风吉祥物精灵,带自己的 prompt 和通知 hook——严肃工具里的情感化设计。
DreamTask
tasks/DreamTask/DreamTask.ts:空闲时段让 agent「做梦」(自主整理/预演任务)的实验模块。
成本与遥测
cost-tracker 逐 token 记账;analytics 用 GrowthBook/Statsig 门控(tengu_* 事件名),诊断日志强制脱敏(logForDiagnosticsNoPII)。
Vim/键位/主题
vim 模式、keybindings 目录、outputStyles——对终端原住民的尊重做到了肌肉层面。
SDK 化
entrypoints/sdk/ 暴露 controlSchemas/coreSchemas:Claude Code 内核可作为 SDK 被第三方应用嵌入(Claude Agent SDK 的由来)。

2.10 设计哲学总结

  1. 循环至简,护栏至繁:主循环 1600 行写完,「让它安全地狂奔」花了剩下 50 万行。
  2. 一切皆工具,一切皆消息:规划模式是工具、提问是工具、连退出计划模式也是工具;UI 进度也是消息流的一部分。系统的正交性极好。
  3. 权限即产品:五档模式 × 三层漏斗 × hook 拦截 × 沙箱,把企业采购最关心的「可控性」做成了核心卖点。
  4. 上下文是最稀缺资源:预取、压缩、墓碑化、预算记账——所有创新都在跟 token 经济学搏斗。
  5. 提示词即代码:协调者宪法、worker 提示词规范全部版本管理在源码里,提示词工程质量等同于代码质量。
  6. 灰度驱动:feature flag + 实验门控遍布全局,产品在主干上持续滚动进化。

第三章 · LangChain:从「胶水层」到标准化应用框架

3.1 定位与历史背景

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 包,官方叙事已彻底转向。

3.2 Monorepo 结构与拆分逻辑

目录PyPI 包内容
libs/corelangchain-core (1.6.1)Runnable/LCEL、消息、模型/工具/向量存储抽象——最小内核,运行时依赖仅 9 项
libs/langchain_v1langchain (1.3.17)v1 真身:create_agent + middleware + init_chat_model
libs/langchainlangchain-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 更彻底的切割。

3.3 核心抽象源码解析

3.4 v1 的 Agent 重构:create_agent / middleware / Standard Stream

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 写适配。

3.5 与 LangGraph 的分工

清晰的三层契约:langchain-core(零业务最小内核)← langgraph(通用图编排引擎,可脱离 LangChain 使用)← langchain(观点化封装层)。逃生舱常开:任何时候可以拿到底层 CompiledStateGraph 自己改图,或干脆落到 LangGraph/core 裸用。官方还有 deepagents 包作为「复杂 agent 用 LangGraph 组合」的参考实现——规划工具 + 虚拟文件系统 + 子代理生成,把 Claude Code 式架构产品化(详见第五章)。

3.6 版本演进史(PyPI 实测日期)

时点版本解决的问题
2022-10 ~ 20230.0.x野蛮生长期:单包巨石、依赖不可控、API 天天变,欠下全部设计债
2024-01-060.1.0LCEL/Runnable 转正,monorepo 初步成型,第一个稳定锚点
2024-05-170.2.0解耦:不再硬依赖 partner 包,安装体积与冲突大幅缓解
2024-09-130.3.0Pydantic v2 全面迁移,甩掉最大技术债
2025-08~101.0 alpha→GA(10-17)create_agent 唯一入口 + middleware 体系 + classic 分家封存
2025-11 ~ 今1.1 → 1.3.17中间件持续扩军,与 LangGraph 1.x 协同演进

3.7 设计哲学、争议与回应

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 重构),包袱之重与纠错幅度之大同样罕见。

3.8 工程质量评价

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:把 Agent 变成可控状态机

4.1 定位:为「自由循环」补上工程骨架

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)由同一团队平行维护。

4.2 仓库结构与开源/商业边界

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/prebuiltToolNode、create_react_agent 等预置件
libs/cli / sdk-py / sdk-js命令行与访问 LangGraph Server 的双语言 SDK
开源边界的源码证据 langgraph-cli 的 pyproject 中,本地开发服务器(langgraph dev)的实际实现依赖两个不在本仓库的闭源 PyPI 包:langgraph-api 与 langgraph-runtime-inmem。这就是「开源框架 + 商业运行时」的 open-core 边界——2025 年后商业侧统一归入 LangSmith 品牌(Deployment / Studio),README 已完成品牌替换。

4.3 核心机制源码解析

① StateGraph 与 reducer

状态 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),这是高层封装动态扩展的基础。

② Pregel 超步执行

执行遵循 BSP(整体同步并行):每个 super-step 中所有被触发节点并发读取上一轮结束时的通道快照,写出统一提交。channels 全集包括 LastValue、EphemeralValue(当轮有效)、Topic(fan-in 队列)、NamedBarrierValue(命名屏障)等九种;任务粒度的 RetryPolicy/TimeoutPolicy/CachePolicy/TracePolicy 都是一级公民(pregel/types.py)。条件边本质是 Branch 对象,在超步末路由下一批节点。

③ Send 与 Command:动态扇出与双重控制

Send("node", custom_arg) 让条件边向同一节点投递多份互不相同的私有输入——map-reduce 扇出的原语,每个 Send 是独立任务可单独设超时。Command 四字段(update/goto/resume/graph)让节点在返回时同时「写状态+控流转」,Command(graph=PARENT) 可向父图传播——子图嵌套的回程票。

④ interrupt():语言级人机协同

v1 的 HITL 主推方式是一个普通函数调用:interrupt(value) 抛出 GraphInterrupt 异常暂停整图、把 value 送回客户端;恢复必须用 Command(resume=...),且图会从该节点开头重新执行全部逻辑——因此官方反复强调节点逻辑必须幂等,多次 interrupt 按出现顺序匹配恢复值。这比 0.x 时代的声明式中断灵活得多。

⑤ Checkpointer 与 time-travel

以 thread_id(会话)× checkpoint_ns(子图命名空间)× checkpoint_id(时间点)三维定位快照;每步边界自动落盘。任取历史快照即可回放/分叉(time-travel),跨版本快照迁移已内置(_migrate_checkpoint)。第三方实现受 checkpoint-conformance 一致性套件约束。

⑥ 流式七模式与函数式 API

stream_mode 提供.values/.updates/.messages(token级)/.custom/.checkpoints/.tasks/.debug 七种契约化输出。@entrypoint/@task 函数式 API 则是「同一运行时的命令式语法糖」:task 把普通函数变成持久执行单元,entrypoint 把它们串成线性流程——内部仍编译为 Pregel,共享全部 checkpoint/stream/interrupt 能力。

4.4 多智能体与服务化生态

4.5 版本演进时间线

4.6 设计哲学与争议

选图而非自由 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 式的状态可靠性。

4.7 工程质量评价

类型标注完备(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:把 Claude Code 架构抽象成通用库

5.1 定位与由来

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 版跟进。

5.2 核心三板斧:规划 · 虚拟文件系统 · 子代理

组件机制解决什么问题
规划工具
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"):主代理可派生携带独立上下文的子代理执行子任务,支持自定义子代理配置。上下文隔离与并行探索——避免一次调研把主对话窗口塞爆。
为什么偏偏是这三件? 因为它们恰好是 Claude Code、OpenCode、DeepSeek Harness 等先行者共同收敛出的最小公共骨架:规划(对抗遗忘)+ 外置记忆(对抗窗口上限)+ 隔离(对抗上下文污染)。DeepAgents 的价值不在发明,而在证明这套骨架可以被标准化成三个可复用的组件。

5.3 与 LangChain v1 / LangGraph 的关系:从组装到中间件套装

DeepAgents 的实现方式经历了明显的架构迁移:

这个迁移本身就是第三章所说的「v1 中间件化」战略的最佳注脚:DeepAgents 从「一个特殊 agent」变成了「一组可拆装的官方最佳实践中间件」——你既可以整包使用,也可以只摘走它的 FilesystemMiddleware 放进自己的 agent。

5.4 设计启示:与其他七个对象互证

5.5 适用场景与局限

适合:研究报告生成、代码库审计、多步信息搜集等「读多写少、步骤深、需要外置笔记」的任务快速起步;也适合作为学习材料——它是目前可读性最好的「复杂 agent 应该长什么样」官方教材。

局限:① 默认权限模型薄弱——没有 Claude Code 式的分级审批,接生产必须自己补 HumanInTheLoopMiddleware 与沙箱策略;② 默认提示词面向通用场景,特定领域需要调教;③ 版本迭代极快(半年内 0.1→0.6+),API 尚未进入 1.0 稳定契约,升级成本需自担。

5.6 快速速览表

维度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:开源世界的 Claude Code 平替

6.1 定位、起源故事与商业模式

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 投资」未获证实。

6.2 仓库结构与技术栈

包角色体量实测
packages/opencode主 agent 服务端(CLI+内核)765 文件 / 17.6 MB
packages/tui终端客户端(OpenTUI/Solid)241 文件
packages/app / desktopWeb 客户端(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 局域网广播、端口回退。

6.3 Client/Server 架构解析

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 计量)。

6.4 Agent 循环与工具系统

6.5 扩展生态

MCP 基于官方 SDK(除动态工具外,MCP resources 可作为附件注入提示,10MB 上限 + MIME 白名单);LSP 管理语言服务器进程并把诊断暴露给模型;插件系统最激进——插件初始化时直接拿到一个指向本 server 的完整 SDK 客户端,意味着插件能调用全部服务器 API 而不只是被动钩子;另有 custom commands/skills/自定义 agent 与 provider/markdown 声明式扩展/codemode 实验。

6.6 与 Claude Code 对比要点

维度OpenCodeClaude Code
许可/模型MIT 全开源;BYOK 75+ provider、本地模型专有;绑定 Anthropic 模型深度调优
架构client/server 多端共享会话单机 CLI 为主 + IDE 扩展
价格免费核心;Zen 网关/企业云收费订阅/按量
差异化亮点分享链接、桌面端、Slack/GitHub CI agent、models.dev 中立目录第一方模型协同、单二进制开箱体验、权限体系成熟度

结论:工具语义层几乎逐一对标,真正的分野在开放性与多端协同;代价是 provider 兼容层的碎片化负担与更复杂的技术栈风险(Effect 4 beta、OpenTUI 等前沿依赖)。

6.7 版本演进时间线

6.8 工程质量评价

类型纪律强(TS strict + Effect Schema 运行时校验双保险);架构治理成熟(依赖方向入规约、生成物禁手改、HTTP 契约测试、自建 http-recorder 录制回放);729 个测试文件。风险点:Effect/OpenTUI 等前沿依赖升级自担;单文件膨胀(provider.ts 2068 行);Session V1/V2 两套 schema 并存显示领域层大迁移仍在途中;日更级发布把稳定性更多押注在 CI 而非版本节律上。代码总量粗估 40–50 万行级。

第七章 · Codex:OpenAI 的开源 Agent 基础设施

7.1 定位与历史:从终端 CLI 到「全面开源的 Harness」

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)。

7.2 仓库结构:约 140 个 crate 的 Rust 帝国

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-traceJSONL 会话落盘 + trace 还原器(对话单元/代码单元/压缩折叠)
工具执行tools · shell-command · apply-patch · unified_exec · utils/ptyshell/原子补丁/持久进程管理/真 PTY
沙箱安全sandboxing · linux-sandbox · windows-sandbox-rs · execpolicy · network-proxySeatbelt/Landlock/受限令牌/网络策略代理
MCP 双向rmcp-client · codex-mcp · mcp-server · connectors既当 MCP 客户端,也把自身暴露为 MCP 服务
服务门面app-server(-protocol v1/v2) · cloud-tasks* · exec-serverIDE/桌面 JSON-RPC 后端、云任务、远程执行环境注册
扩展/记忆ext/{agent,memories,skills,mcp,web-search,…} · skills · hooks新一代模块化扩展位、技能包、生命周期钩子

有趣的实验痕迹也值得记录:v8-poc(在 agent 里嵌 V8 引擎的概念验证)、code-mode 系列编排实验、external-agent-migration(从他家的会话迁移过来)。

7.3 核心机制:rollout 事件日志与 thread 协议

7.4 安全模型:「沙箱 × 审批」双轴(本报告最硬核的实现)

官方安全文档明确两根轴:Sandbox mode 管「技术上能做什么」,Approval policy 管「何时必须问人」。

为什么说这是「最硬核」 八个对象中,Claude Code 的沙箱是可选组件、Pi 干脆拒绝内置、LangGraph 只给原语——只有 Codex 和 DSH 把 OS 级强制隔离做成了默认出厂设置,且都覆盖三大桌面操作系统。安全不再是「高级功能」而是 harness 的地基,这是 2026 年行业最重要的共识转变。

7.5 产品矩阵:一个内核,八个门面

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 率先倡导、如今已成跨工具通用惯例。

7.6 与 Claude Code / OpenCode 的对比要点

维度CodexClaude CodeOpenCode
语言/分发Rust 单二进制(musl 静态),npm/brew 只是壳Bun+Node 单包TypeScript(Bun) 多包
开源深度Apache-2.0 全仓含核心与协议专有(源码经泄露才可读)MIT 全开源
沙箱OS 级强制+默认断网(三平台)权限提示为主,OS 沙箱可选依赖进程权限约定
账号/计费ChatGPT 订阅直登 或 API keyAnthropic 账号/APIBYOK 75+ provider
MCPclient+server 双向,引擎整体可编程client 为主client 为主
多形态CLI+IDE+桌面+云+review+SDK+远程执行CLI+IDE+SDK+远程CLI+Web/桌面/Slack/GH
话语体系harness engineeringagentic coding / subagentsopen-source 替代

差异化总结:Codex 的护城河叙事不在模型单点,而在「OS 强制沙箱 + 订阅直登 + 全形态同内核 + 可嵌入 harness 接口」的组合拳。它与 Claude Code 构成一组镜像——Anthropic 把能力藏在闭源产品里卖体验,OpenAI 把客户端开出来卖模型订阅。

7.7 版本时间线与工程质量

工程质量是八家中最「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)。

7.8 设计哲学总结

  1. Harness 即产品:模型只是引擎,2026 年值钱的是「主循环+工具+沙箱+上下文管理」这层工程外壳——OpenAI 用一篇博客给整个行业定了调。
  2. 安全默认:默认沙箱、默认断网、破坏性操作必审批;把「敢让它跑」的答案从用户手里拿走,做成出厂设置。
  3. 协议优先:thread/turn 是 RPC、会话是事件日志、SDK 是子进程包装——一切能力皆接口,因此才能一个内核长出八个门面。
  4. 开源即渠道:客户端 Apache-2.0 全开,价值锚定在模型订阅——与 Anthropic 的闭源路线构成 2026 年最耐人寻味的对照组。

第八章 · Pi:极简主义的反叛——Agent 只是一个循环

8.1 作者与理念起源

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 增值 + 专有企业版的三级模式。

8.2 Monorepo 结构:五个主包

包职责规模量级
@earendil-works/pi-ai统一多 provider LLM API(消息/工具/流式/成本)177 个 TS 文件(含生成的模型目录)
@earendil-works/pi-agent-coreAgent 运行时:797 行的 agent-loop.ts + Agent 类50 个文件
@earendil-works/pi-coding-agentCLI 产品(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 组装全部。

8.3 pi-ai:统一模型层的极简答案

8.4 Agent Loop:797 行的全部魔法

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 行,但相对同类仍是数量级的差距——且每一行用户都可读、可改、可拥有。

8.5 产品形态与「反功能清单」

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。

Pi 明确拒绝内置的东西(README Philosophy) No MCP——"Build CLI tools with READMEs… or build an extension that adds MCP support";No sub-agents、No permission popups(建议容器化,官方给出 Gondolin 微 VM/Docker/OpenShell 三方案)、No plan mode、No 内置 todos("They confuse models"——它们会让模型困惑)、No background bash(用 tmux)。每一条拒绝都附带替代方案,这是「有观点的软件」(opinionated software)的标准写法。

8.6 pi-tui:因为「它闪烁」所以自研 UI

Mario 对 ink/React 式终端渲染的闪烁忍无可忍,于是自研了保留模式 + 差分渲染的 pi-tui:组件只须实现 render(width): string[] + handleInput + invalidate;两种渲染器分别服务主屏缓冲(保留 scrollback)与备用屏固定视口;全部更新包进 CSI 2026 同步输出实现原子无闪渲染。组件库覆盖编辑器(斜杠补全、长粘贴折叠)、Markdown 渲染、Kitty/iTerm2 图形协议图片、IME 光标定位(解决中日韩候选窗错位)等硬核细节。一个「嫌闪烁就自己写个 TUI 框架」的人,做出来的东西自然不容小觑。

8.7 时间线与爆火路径

8.8 设计哲学金句集(摘译)

"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 按钮永远有效。」

8.9 工程质量评价

约 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:插件化的全栈 Agent 运行时

9.1 定位:把 Agent 做成「操作系统」

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-meterprovider 无关的流式调用抽象 + 适配器注册表;直接复用 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-otelMCP 客户端、SKILL.md 技能、凭据存储、OpenTelemetry 遥测

9.2 微内核 + Profile 叠加的启动模型

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 的模型适配包 @deepseek-ai/dsh-llm-pi-ai 直接依赖 @earendil-works/pi-ai第八章那个「极简主义」的统一 LLM API 被吸收为 DSH 的多 provider 基座。两条哲学相反的路线在工程上握手:极简派的核心库成为平台派的地基。此外 dsh-base 还内置可选的 Codex 与 Claude Code 子代理 provider——把竞品当作可调度的下游执行器。

9.3 Agent 循环:唯一的具体循环,其余皆插件

dsh-agent-loop 的 README 开宗明义:「这是整个 harness 中唯一包含具体循环逻辑的包。其他一切都是针对扩展点的抽象服务或插件——新行为进插件,不进这里」。它的循环是一个名为 ReactLoopAgent(ReAct 循环驱动器)的包内私有实现,对外只暴露契约:

9.4 事件溯源会话:日志是唯一事实源

dsh-session 把会话建成append-only 事件日志:LLM 消息历史只是从日志「推导」出的视图(deriveMessages()),上面还维护一层 surface 投影加速推导与压缩。关键设计:

这套设计的回报是:重启恢复、会话分叉、投影查询(SQLite)、审计重放全部免费获得——goal、plan mode、sandbox mode 等所有有状态的子系统都把自己的状态写成一种带类型的日志事件(如 sandbox/mode、plan/mode、goal/change),而不是藏在内存里。「状态即事件」是 DSH 区别于其他五个对象的根本特征。

9.5 安全模型:三态沙箱 + 单调权限 + 审批服务

9.6 多代理与编排:subagent / jobs / workflow 三层

9.7 上下文工程:装配瀑布与压缩引擎

dsh-system-prompt 是一个「提示词装配注册表」:插件贡献有序 section(order 排序,agent 作用域可遮蔽全局)、动态 context(每次装配时求值并作为带来源的运行时快照写入历史)、工具 schema 提供者、模板变量({{model}}/{{cwd}})。装配经过 system-prompt/assemble 瀑布事件——监听者拥有最终决定权(比如 Code Mode 或结构化输出协议在此注入自己的格式约束)。压缩方面,compaction-basic 实现了教科书级的压缩事务:tokenMeter 计压 → 工具结果修剪 → 选段保留尾部 → 用「重放对话自身前缀」的方式调用摘要(复用 KV cache!)→ 收缩率验证 → 失败重试上界 → 溢出恢复路径单独处理。连摘要调用都会打上 x-deepseek-harness-compact 归因头。

9.8 设计哲学总结

  1. 微内核至上:唯一的具体循环 + 一切皆插件 + patch 叠加配置,产品=插件的组合而非代码的分叉。
  2. 日志即真相:所有状态都是事件,所有视图都是投影,所有恢复都是重放。复杂度极高,换来的是完美的可观测性与可恢复性。
  3. 契约文化:150 个包每个都有双语 README 写清 Public API、Model Experience(模型看到什么/token 影响/KV cache 影响)、Known Limitations——把「文档即接口测试」推到极致。
  4. 安全纵深:默认最小权限、硬软分离(plan 引导 vs sandbox 强制)、单调护栏、越权即拒绝。
  5. 拥抱生态:底层用 Pi 的 pi-ai,技能用 SKILL.md 标准,扩展走 MCP,甚至能把 Claude Code/Codex 当子代理——没有 NIH 情结。

第十章 · 横向对比:八种哲学,八个答案

10.1 先把光谱画出来:控制权 vs 自由度

确定性/可控性 ◄──────────────────────────────────────────► 模型自主性

 LangGraph      LangChain v1    DeepAgents    Codex         DeepSeek Harness   Claude Code/OpenCode   Pi
(每步都是图节点)(默认ReAct图+   (三件套预置图,(审批三态+    (自由循环,但一切    (自由循环+层层护栏)    (自由循环,
                 middleware可插) 可摘装重组)   OS级沙箱)      状态留痕可审计)                          几乎无护栏)

八个对象其实是同一个问题的八个答案:「你愿意把多少控制权交给模型?」LangGraph 把答案压到最低(每一步都要显式声明),Pi 把答案放到最高(模型自己看着办),其余六者在中段各取所需。没有对错,只有场景。

10.2 架构形态总对比

维度Claude CodeLangChainLangGraphDeepAgentsCodexOpenCodePiDeepSeek Harness
产品形态终端 CLI 产品Python/JS 框架库编排引擎库(+商业Server)通用 agent 参考实现库CLI+云任务+IDE 开源全家桶CLI+多客户端平台工具包+CLI 产品运行时平台(插件微内核)
代码组织单体应用(~1900文件)monorepo 分层(core/v1/classic/partners)monorepo 9 包单包+middleware 群Rust workspace(codex-rs)+TS SDKBun monorepo 20+包monorepo 5 主包150 个独立插件包
核心循环query.ts while(true) async generatorcreate_agent→LangGraph 图Pregel BSP 超步create_deep_agent(middleware 套装)Rust 核心 turn 循环SessionPrompt Service(Effect Layer 25 服务)双 while agent-loop.ts(797行)ReactLoopAgent(唯一具体循环,其余皆插件)
语言栈特色Bun+React InkPydantic 全家桶Pregel/通道原语复用 Pydantic/LangGraph 原语Rust+Seatbelt/Landlock 沙箱Effect TS+Drizzle+OpenTUITypeBox+自研 TUIcordis 插件框架+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 共享 serverpi-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+OAuthpi-ai 四协议抽象+30余家适配器注册表(DeepSeek 直连+pi-ai 底座)

10.3 安全与权限模型对比(差异最大的维度)

项目模式分级强制手段审批交互审计
Claude Codedefault/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 全量快照天然可审计
DeepAgentsHITL middleware 可插审批点(默认薄弱)需自行接 Docker/沙箱执行策略interrupt_on_tool 工具级人工批准依赖 LangSmith/宿主环境
Codexsandbox_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 全量落盘可回放
OpenCodepermission 配置规则+内置 agent 权限合并Question 工具交互批准PermissionV1 schemaSQLite 全量落库
Pi拒绝内置权限弹窗(建议容器化:Gondolin 微VM/Docker/OpenShell)外部容器隔离;trust.json 项目信任无(yolo 哲学)JSONL 全量历史
DSHread-only/workspace-write/danger-full-access 三态+审批策略预设Windows ACL 受限令牌/POSIX landlock+单调 guard 护栏+fs 观察策略user-approval 服务(ask/never 等 policy)sandbox/mode 等全部状态事件化留痕
洞察:安全是「产品信任」的函数,不是「技术先进」的函数 Claude Code/DSH 面向企业采购,安全做成了五层纵深;Pi 面向专家个人,直接把责任交还用户并给出容器方案;Codex 把「OS 级沙箱默认开启」做成出厂设置;LangGraph 只提供原语把问题留给部署者。四种态度都成立,因为它们的用户画像完全不同——自建 agent 时第一件事就是想清楚你的用户是谁。

10.4 多智能体能力对比

项目子代理形态编排方式独门设计
Claude Code递归嵌套 QueryEngine;异步后台代理(工具白名单)coordinator 宪法提示词+swarm 团队(tmux/iTerm 队友)continue vs spawn 决策表;验证者新鲜眼睛原则;DreamTask
LangChaindeepagents 参考实现(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
OpenCodeTask 工具开子会话(标题前缀 Child session)server 统一调度;@agent 名直调多客户端同时观察同一会话
Pi拒绝内置(扩展可实现)—"搞 agent 大军的人没几个真发表过工作成果"
DSHone-shot/continuable 双模+provider 注册表+fork 血缘workflow 引擎跑模型写的 JS 编排脚本(pipeline/parallel)越权打断防护(人类持久父地址/活体祖先);深度上限;描述符持久化

10.5 上下文工程对比

10.6 扩展机制对比

项目进程内扩展跨进程协议知识包生态规模感
Claude Codeplugins(dxt)/slash commands/subagent 定义MCP+hooks(shell 命令)Skills(SKILL.md)最大商业生态
LangChainmiddleware(30+内置)partner 包生态Hub prompt 托管最大集成广度
DeepAgentsmiddleware 摘装/自定义工具与子代理—(库本身即扩展)官方示例模板LangChain 生态直通车
LangGraph自定义节点/checkpointerServer API+SDKStudio 模板生产部署生态
Codexcustom prompts/config profiles/exec 模式脚本化MCP client+server 双向(codex mcp-server 暴露全组 JSON-RPC)AGENTS.md 标准发起者之一OpenAI 官方+OSS 社区双轮
OpenCodeplugin(拿到全 API 客户端!)/custom provider 运行时 npm 安装MCP+ACP(Zed)+LSPskills/custom commands增长最快的开源生态
Pi单文件 extension(registerTool/registerCommand/on)拒绝 MCP(CLI+README 替代)SKILL.md+prompt templates+themes小而硬核
DSHcordis 插件 patch 叠加(150包)MCP client+skill 文件系统SKILL.md 标准+persona平台级自洽生态

10.7 商业模式与治理

项目主体开源边界变现
Claude CodeAnthropic专有(SDK 开源);2026-03 source map 泄露成为意外教材订阅/API 计费
LangChain+LangGraphLangChain Inc.MIT 框架;闭源 Server(langgraph-api)LangSmith SaaS+Deployment
DeepAgentsLangChain Inc.MIT 全开源参考实现无独立变现(为生态导流)
CodexOpenAIApache-2.0 开源客户端(Rust),2026 年被社区称为「全面开源的 Codex Harness」ChatGPT 订阅/API 计费(客户端即入口)
OpenCodeAnomaly(YC)MIT 核心+私有企业云栈Zen 网关+企业版
PiEarendil(2026-04 并入)MIT 核心+Fair Source 增值+专有企业版三级企业授权+商标
DSHDeepSeek发行包含完整契约文档服务 DeepSeek 生态

值得注意的是open-core 已是绝对主流:八个对象中六个有明确的「免费核心+付费增值」切分线(DeepAgents 为纯开源参考实现;Codex 客户端开源但价值锚定在模型订阅),且切分位置惊人一致——框架/内核开源,运行时/托管/企业管控收费。这印证了 agent 时代的价值分布:代码不值钱,运营和信任才值钱。

10.8 一句话总结各自的天命

Claude Code
证明了「护栏工程」本身就是产品力——51万行代码里最值钱的是那套权限系统和协调者宪法。
LangChain
证明了「自我革命」是框架唯一的长生之道——三次推翻自己反而越活越好。
LangGraph
证明了「无聊的可靠性」在生产世界永远有市场——DB 式状态管理赌对了企业需求。
DeepAgents
证明了「标杆可以标准化」——三块中间件就把 Claude Code 的骨架搬进了 pip install。
Codex
证明了「厂商可以把王牌客户端开源」——Rust 单二进制+OS 级沙箱把安全做成了硬通货。
OpenCode
证明了「开放+模型无关」足以撬动 20 万 star——用户怕锁定甚于怕不完美。
Pi
证明了「少即是多」在这个行业依然是稀缺美德——797 行循环撑起了十万 star 的信任。
DeepSeek Harness
证明了「日志即真相」可以撑起整个平台——150 个插件共享一个事实源的工程美学。

第十一章 · 自建 Agent 完全指南:必备组件与二十条军规

综合八个对象的源码证据,本章回答一个实际问题:如果自己动手搭一个 agent,需要哪些部件?哪些坑已经被前人用血泪标好了?

11.1 十大必备组件(缺一不可的程度排序)

#组件职责与最小实现参考范本
1Agent 循环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
7Shell 执行器持久 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

11.2 先想清楚的三条路线之争

路线 A:直接用成熟产品
Claude Code / OpenCode / pi CLI 当黑盒用。适合绝大多数「我要干活」场景。判据:你的差异化不在 agent 本身。
路线 B:框架组合
LangGraph(要可控长流程/断点恢复/HITL)或 LangChain v1 create_agent(要快速集成生态)。代价是学习曲线与抽象税;收益是 checkpoint/stream/interrupt 这些难写的部分别人替你写好了。
路线 C:自建 loop
以 pi 为底本抄一个 800 行循环 + pi-ai 做模型层,按需加护栏。适合 agent 能力本身是你的产品的团队。Mario 的警告依然有效:「谁宣称找到了答案——别信」,但你拥有的每一行代码都是护城河。

三个对象的演化史其实给出了同一个暗示:循环本身正在变成商品(LangChain 把 agent 建在 LangGraph 上、DSH 把循环收进唯一的插件、pi 直接开源了循环),真正的价值都在循环之外——上下文工程、安全、持久化、评测。自建时请把钱花在刀刃上。

11.3 二十条军规(每条都有源码出处的教训)

  1. 先写循环,再谈架构。八个对象没有一个是从「平台」起步的——都是从 while 循环长出来的。警惕第一天就想做通用框架的自己。
  2. 上下文是稀缺资源。往上下文里加任何东西之前问一句:这个 token 值多少钱?(Mario:Playwright MCP 的 21 个工具描述 = Claude 上下文的 6.8%。)
  3. KV cache 就是钱。系统提示词保持字节级稳定、历史 append-only、压缩走「重放原前缀」而不是重新拼装——DSH 甚至把它写进了每个包的 README 章节。乱改 system prompt 一个字节 = 全量缓存失效。
  4. 工具结果必须限长、可修剪、可墓碑化。一条 cat 大文件的输出就能毁掉整个会话。CC 用 TombstoneMessage,DSH 用独立的 tool-result-pruner 插件。
  5. 维护消息序列合法性:tool call/result 必须严格成对。任何中断/异常路径都要补合成错误结果(CC yieldMissingToolResultBlocks),否则下一次 API 调用直接报错。
  6. stopReason=length 时作废整批 tool call(pi):被截断的 JSON 参数执行起来就是事故。
  7. 中止要返回部分结果而非静默丢弃(pi):用户打断时已经生成的文字和已执行的半程工具都要有交代。
  8. 权限默认拒绝,切换必须留痕。DSH 连「沙箱模式变更」都是一条日志事件,重启后靠重放恢复——权限状态不允许藏在内存变量里。
  9. 软引导与硬强制分离:计划模式这类「劝阻」用提示词实现,沙箱/审批才是强制;两者解耦才不会互相污染语义(DSH plan-mode README 明言)。
  10. 子代理提示词必须自包含。「based on your findings」式懒惰转授是多代理系统的头号失败原因(CC 协调者宪法专门列了反例)。
  11. continue vs spawn 要有决策表:上下文重叠度高→continue;验证他人代码→永远新开(避免思维锚定);纠错→continue(错误上下文最宝贵)。(CC 决策表原文值得贴在墙上。)
  12. 验证者要有新鲜的眼睛:实现者自查 ≈ 没有 check。
  13. 并行要有上限和安全分类:默认互斥、声明才可并行、滚动池限流(DSH maxParallelToolCalls 默认 10)。两个工具同时写同一文件不是并行是赌博。
  14. 一切状态进日志:goal、plan、sandbox mode 全部事件化。重启恢复、fork、审计、时间旅行全是免费的副产品(DSH 事件溯源)。
  15. 为幂等而设计:LangGraph 的 interrupt 恢复语义是「从节点开头重新执行」——不幂等的操作(外部付款、随机命名)会在恢复时爆炸。
  16. 系统提示词即代码:版本管理、code review、灰度发布。CC 把协调者宪法写在源码里随包发版;你也应该这样对待自己的提示词。
  17. 成本计量从第一周开始:per-request 归因头、逐 token 记账(CC cost-tracker、DSH token-meter + x-deepseek-harness-compact 归因头)。事后没人算得清谁的循环烧掉了预算。
  18. 评测集先于功能:把真实失败案例固化成 eval 回归用例(pi 有独立 evals 包)。没有评测的 agent 迭代等于蒙眼开船。
  19. MCP 不是免费午餐:每个远程工具的 schema 和描述都常驻上下文;高频内部能力优先做成 CLI + README 文档(给模型的文档),MCP 留给真正需要标准化的外联。
  20. 供应链即攻击面:依赖精确 pin、min-release-age 缓冲、生命周期脚本白名单、签名校验(pi 的做法);agent 能执行命令意味着一次 npm 投毒就是一次主机沦陷。
最后一条元建议 2025-11 Mario 在复盘里写道:行业还没人知道该怎么做,我们都在边哭边还技术债。所以——保持小循环、厚测试、快回滚,把每一个失败案例变成评测用例而不是博客吐槽。这六套源码最大的共同点不是它们做了什么,而是它们都保留了「随时推倒重来」的能力。

第十二章 · Agent 发展简史:从聊天机器人到数字员工

12.1 史前纪元(2017–2022):一切的前提

12.2 寒武纪大爆发(2023):Agent 元年

12.3 沉淀与转折(2024):从 demo 到工程

12.4 产品大爆发(2025):编码 agent 元年

12.5 平台收敛(2026 至今):harness 成为关键词

十年主线的三段论 ① 2022-2023 证明了「LLM 能用工具」(ReAct + function calling);② 2024-2025 证明了「agent 能干活」(编码 agent 的可靠性工程 + 协议标准化);③ 2026 开始回答「谁来运营一支 agent 团队」(harness 平台化 + 治理与安全)。每一段的核心瓶颈都在上移:从能力,到可靠性,到组织。

第十三章 · 未来趋势研判:2026 之后会发生什么

13.1 循环商品化,价值上移到 Harness

八个对象给出了同一个信号:agent 循环本身正在变成免费商品。LangChain v1 把 agent 收敛为一个函数(建在 LangGraph 上);pi 把循环开源成 797 行教材;DSH 把循环收进唯一的具体插件;连 OpenCode 都以「open harness」自居。可预期的推论:未来差异化竞争全部发生在循环之外——上下文工程、持久化可靠性、安全治理、评测体系、组织协作。新入局者再做一个「更好的 while 循环」已无意义,要做的是更好的 harness 组件。

13.2 上下文工程升格为独立学科

2023 年大家谈 prompt engineering,2025 年谈 context engineering,2026 年它已经细分出明确的子领域:

13.3 安全从功能变成采购门槛

13.4 多智能体:从 demo 到组织学

2026 年的产品线同时押注了多代理:Claude Code 的 swarm 队友(tmux/iTerm 真实终端窗格)与 coordinator 宪法、DSH 的 workflow 编排引擎、LangGraph 的 supervisor/swarm 官方包。但 Mario 的冷水值得挂在墙上:「让它们写大量代码一直是灾难配方」。更可能的终局不是 agent 大军,而是小规模分工明确的 agent 团队(协调者-执行者-验证者三角),配合 continue-vs-spawn 这类上下文管理纪律——多智能体的难点从来不是通信协议,而是组织成本与责任边界。A2A 协议进入 Linux Foundation 后,跨厂商 agent 互操作会在 2027 年前后开始标准化试水。

13.5 长时程自治与「后台化」

13.6 协议战争:MCP 的统一与反叛并存

MCP 已赢得「连接标准」之战(本次分析的 agent 中除 Pi 高调拒绝外几乎全部支持),但反叛同样真实:Mario 用数据证明 MCP 工具描述的 token 成本(Playwright MCP 占 Claude 上下文 6.8%),主张 CLI+README 的组合性路线;Anthropic 自己也在用 Skills 承载「过程性知识」。预判格局:MCP = 外设接口(USB),CLI/代码 = 本地总线,Skills = 驱动程序说明书,AGENTS.md = 主板说明书——四者共存而非互替,竞争焦点转向 A2A 式的「agent 与 agent」层。

13.7 模型层:agentic 能力被训练进权重

ReAct 时代靠提示词教会模型用工具;o1/R1 时代推理内化为思考链;下一步是 agentic RL——在真实或仿真环境中用任务成败奖励训练模型的多步决策(SWE-bench 分数的军备竞赛即是缩影)。对 harness 的含义深远:模型的「开箱 agent 能力」越来越强,harness 的护栏价值上升而「教模型做事」的提示词价值下降。Claude Code 泄露源码中那些精巧的提示词工程,五年后可能大半变成模型默认能力——但权限、审计、恢复这些护栏不会过时。

13.8 反身性:agent 正在开发 agent

本次研究本身就是证据之一:LangChain 和 LangGraph 仓库根目录都放着 AGENTS.md/CLAUDE.md(它们用自己的框架喂 AI 开发自己);LangChain 用自动关闭 PR 对抗 AI slop 贡献;pi 甚至把「新贡献者审核」做成了每日人工流程。Claude Code 源码泄露事件则揭示了另一个反身性风险:构建产物里的 source map 在 AI 辅助打包流程中更容易被忽视。未来三年,「AI 开发的软件如何被安全地发布与审计」本身会成为一门显学。

13.9 给从业者的三个下注建议

  1. 押注治理而非能力:模型能力每季度都在涨,而企业的权限/审计/合规需求几乎不变——做 harness 的护城河比做 agent 的护城河深。
  2. 押注上下文经济学:谁能让同样的任务消耗更少的 token(缓存友好架构、精准检索、无损压缩),谁就掌握 agent 时代的成本曲线。
  3. 保持可逆性:八个对象全部保留了「随时推倒重来」的能力(fork 按钮、classic 包、事件溯源重放)。这个领域没有权威,只有还没被证伪的假设——别把任何架构当成信仰。

第十四章 · 常见问题(FAQ)

以下 12 个问题是按「读完本报告后你最可能想问」整理的,答案全部浓缩自前文各章的源码证据,括号内为详见章节。

Q1 · 写代码到底该用哪一个:Claude Code、Codex、OpenCode 还是 Pi?

四条判断线:① 模型生态——深度绑定 Anthropic 选 Claude Code,深度绑定 OpenAI/ChatGPT 订阅选 Codex;② 开放性——想 BYOK 接任意模型、多端共享会话、可自托管选 OpenCode;③ 掌控力——想读懂并拥有每一行、按自己工作流魔改选 Pi;④ 安全合规——企业环境对沙箱有硬要求的,Codex 的 OS 级强制沙箱与 Claude Code 的五档权限体系最成熟(详见第二、六、七、八章与第十章对比)。

Q2 · LangChain 被骂「过度抽象」,2026 年还值得用吗?

批评主要针对 0.0.x 时代的巨石包与 AgentExecutor 黑盒,而 v1 已经结构性回应:主包只剩三个运行时依赖、create_agent 一个函数替代整个子类动物园、middleware 洋葱模型取代继承树、旧世界封存进 langchain-classic。如果你的核心诉求是快速集成几十家模型/向量库,它仍是首选;如果只要可控编排,可以跳过它直接用 LangGraph(详见第三章)。

Q3 · 需要断点恢复、人工审批这类「生产特性」时怎么办?

两条路:用 LangGraph——checkpointer 三维寻址 + interrupt()/Command(resume) 就是为此而生,代价是接受图心智模型(详见第四章);或选带持久化内核的产品——Codex 的 rollout JSONL 与 thread/resume/fork 协议、DSH 的事件溯源会话都是开箱即用的方案(详见第七、九章)。自建的话,事件溯源是最省心的架构(第十一章军规 14)。

Q4 · MCP 到底该不该接?Pi 不是说不用 MCP 也行吗?

场景化决策:对接外部标准化服务(GitHub、数据库、浏览器)用 MCP,生态成熟、即插即用;高频内部能力优先做成 CLI 工具并配一份好 README——Mario 的实测是 Playwright MCP 的 21 个工具描述吃掉 Claude 上下文约 6.8%,而 Bash+代码天然可组合、零常驻开销(详见第八章)。Codex 则展示了第三种姿态:client+server 双向,把自己的引擎也暴露成 MCP 服务(第七章)。先算 token 账,再定协议。

Q5 · 多智能体是不是伪需求?到底该开几个 agent?

不是伪需求,但被严重高估了。行业现状是两极并存:Claude Code 做出了 swarm 团队和协调者宪法、DSH 提供工作流引擎,而 Pi 干脆拒绝内置。比较可靠的共识是三点:① 用小规模分工明确的三角结构(调研-实现-验证),不要 agent 大军;② 严格执行 continue vs spawn 决策表与「验证者新鲜眼睛」原则(第二章);③ 并行写操作必须做文件级隔离(worktree 或任务分区)。组织成本才是多智能体的真正瓶颈(第十三章 13.4)。

Q6 · 自建一个能用的 agent 最少要多少代码?

核心循环的参照物是 Pi 的 agent-loop.ts——797 行(第八章);加上统一模型层可以直接复用 pi-ai。但「能用」和「能上生产」之间隔着第十一章列出的全部护栏:权限、沙箱、持久化、压缩、评测。真实的成本分布是:循环占 5%,循环之外占 95%——这正是各家不约而同把创新重心放在循环之外的原因。

Q7 · 上下文压缩会不会丢掉关键信息?

会丢,所以各家都做了保底设计:Pi 的压缩有损但完整历史永远保留在 JSONL 文件里可回查;DSH 对摘要做收缩率验证、失败重试上界和独立的溢出恢复路径;Claude Code 用墓碑化保留「这里曾有内容」的占位提示。实践建议:把「不可丢」的信息外置到文件系统或记忆目录(DeepAgents 的虚拟文件系统思路),让压缩只处理可再生的过程性内容(详见第五、七、八、九章)。

Q8 · AGENTS.md、CLAUDE.md、SKILL.md 到底是什么关系?

三个层次:AGENTS.md / CLAUDE.md 是项目记忆——给 agent 的项目说明书,前者是 Codex 率先倡导的跨工具通用标准,后者是 Claude Code 的同源实现,多数工具两者通读;SKILL.md 是技能包——按需加载的过程性知识(Anthropic 开放的标准),解决「不用的知识不占上下文」;系统提示词本身则由各家 harness 在装配时生成,用户一般不直接编辑。一句话:项目说明写给所有 agent,技能包按需翻书,系统提示词归厂商管。

Q9 · 安全方面最低限度应该做哪几件事?

四件套:① 默认拒绝——权限从最小集开始,切换必须留痕(第九章的 sandbox/mode 事件范式);② OS 级隔离——至少容器化,预算充足就学 Codex/DSH 上 Seatbelt/Landlock/受限令牌;③ 审批留痕——破坏性操作强制人工确认且全程可审计;④ 供应链加固——依赖 pin 死、min-release-age 缓冲、生命周期脚本白名单(第八章 pi 的清单可直接抄)。提示词层面的「请你小心」不算安全措施。

Q10 · 这些 agent 会取代程序员吗?

本报告的源码证据给出的答案是:它们取代的是打字量,不是判断力。最直接的证据是 Claude Code 协调者宪法里那句「验证者要用新鲜的眼睛」和 DeepAgents 局限里「接生产必须自补审批」——行业最好的实践仍然围绕「人类在哪里介入」设计接口。角色正在从写代码转向:写 spec(协调者综合纪律)、做评审(verification agent 无法替代的最终责任)、以及管好这群 agent(harness 工程,详见第七章)。

Q11 · 用泄露的源码做公开分析,合适吗?

本报告第二章基于的快照来自 2026 年 3 月经 npm source map 意外公开的内容,镜像仓库以教育与研究目的分发、未主张任何权利。本报告的使用方式是评论与分析(引用架构事实与少量短句),而非再分发代码本体;这属于对已公开材料的研究性使用范畴。同时它也提醒所有厂商:构建产物里的 source map 是真实的数据泄露面,应在 CI 里加检测(第十三章 13.8 的反身性问题)。

Q12 · 报告里的 star 数、版本号、融资额都可信吗?

分三档:一手实测(GitHub API、PyPI 时间戳、本地源码行数)可信度最高,均标注了实测时点;官方渠道(博客、文档、release notes)次之;二手报道(媒体转述的融资额、用户数)最低——凡是未能一手核实的,正文一律标了「待确认」。所有数字都是 2026 年下半年调研时点的快照,这个领域月度变化极大,引用请注明口径(详见第一章 1.2 与第十五章)。

第十五章 · 参考资料与来源

15.1 一手源码(本报告的核心证据)

15.2 LangChain / LangGraph

15.3 OpenCode

  • Codex:github.com/openai/codex(codex-rs workspace 源码、docs/config.md 沙箱与审批配置、release 时间线);OpenAI Codex 产品页与 changelog
  • 15.4 Pi

    15.5 协议与行业事件

    数据口径说明 所有 star 数、版本号、用户数均为调研时点(2026 年下半年各子代理实测快照)数据,标注「待确认」处为未能从一手来源核实的二手信息。本报告为技术分析用途,不构成对任何项目的投资或采购建议。

    — 全文完 · 《AI Agent 架构深度研究报告》 · 由 ox-alpha 基于 DeepSeek Harness 生成 —
    分析者本身即运行于报告第九章所描述的 DeepSeek Harness 之上——这大概是本报告最独特的「方法论」注脚。