English | 中文
一份面向 Claude Code（v2.1.88，约 1,900 个 TypeScript 文件、约 512K 行代码）的全面源码级架构分析，附带社区分析精选、面向智能体开发者的设计空间指南，以及跨系统对比。
Tip
TL;DR —— Claude Code 代码库里只有 1.6% 是 AI 决策逻辑；其余 98.4% 都是确定性基础设施——权限门控、上下文管理、工具路由和恢复逻辑。智能体循环本身是一个简单的 while 循环；真正的工程复杂度集中在它周围的各类系统上。本仓库剖析这一架构，并为所有构建 AI 智能体系统的人提炼出可落地的设计指南。
来自我们的论文
论文之外
- 🛰️ Agent 设计空间的新信号
- 🛠️ 构建你自己的 AI 智能体：设计指南
- ⚖️ 跨系统对比：Claude Code vs OpenClaw vs Hermes-Agent
- 🌐 社区项目与研究
- 🚀 其他值得关注的 AI 智能体项目
- 🔖 引用
- 98.4% 基础设施，1.6% AI —— 智能体循环不过是一个 while 循环；真正的工程复杂度集中在权限门控、上下文管理和恢复逻辑上。
- 5 个价值观 → 13 条原则 → 实现 —— 每一条设计决策都能追溯回人类决策权威、安全、可靠性、能力和适应性。
- 深度防御却存在共享故障模式 —— 7 层安全防护，但都共享性能约束；子命令超过 50 个的命令会绕过安全分析。
- 4 个 CVE 暴露了预信任窗口 —— 扩展会在信任对话框出现之前就已执行。
- 横跨各层的 harness 难以被重新实现 —— 循环本身容易复制，但钩子、分类器、压缩和隔离机制则不然。
| 如果你是…… | 从这里开始 | 然后阅读 |
|---|---|---|
| 智能体构建者 | 构建你自己的智能体 | 架构深度剖析 |
| 安全研究员 | 安全与权限 | 架构：安全层 |
| 产品经理 | 关键亮点 | 价值观与原则 |
| 研究人员 | 完整论文 (arXiv) | 社区资源 |
1,884 个文件 · 约 512K 行 · v2.1.88 · 7 个安全层 · 5 个压缩阶段 · 54 个工具 · 27 个钩子事件 · 4 个扩展机制 · 7 个权限模式
Claude Code 回答了每个生产级编码智能体都必须面对的四个设计问题：
| 问题 | Claude Code 的答案 |
|---|---|
| 推理放在哪里？ | 模型负责推理，harness 负责强制执行。约 1.6% 是 AI，98.4% 是基础设施。 |
| 有多少个执行引擎？ | 一个 queryLoop 供所有入口（CLI、SDK、IDE）共用。 |
| 默认的安全姿态是什么？ | 拒绝优先：拒绝 > 询问 > 允许；最严格的规则优先。 |
| 最根本的资源约束是什么？ | 约 200K（旧模型）/ 1M（Claude 4.6 系列）的上下文窗口。每次模型调用前都要过 5 层压缩。 |
系统分解为7 个组件（用户 → 入口 → 智能体循环 → 权限系统 → 工具 → 状态与持久化 → 执行环境），跨越5 个架构层。
[!NOTE] 完整的架构深度剖析——7 个安全层、9 步轮次管道、5 层压缩等——请参阅**docs/architecture_zh.md**。
架构从5 个人类价值观追溯到13 条设计原则再到实现：
| 价值观 | 核心思想 |
|---|---|
| 人类决策权威 | 人类通过主体层级保持控制。当 93% 的提示批准率暴露出批准疲劳后，Anthropic 的应对是重新划分边界，而不是追加更多警告。 |
| 安全、安保、隐私 | 即使在人类警惕性下降时，系统也能守住安全底线。7 个独立安全层。 |
| 可靠执行 | 按用户的本意去执行；收集—行动—验证的闭环；优雅恢复。 |
| 能力放大 | "一个 Unix 工具，而不是产品。"98.4% 是让模型能够工作的确定性基础设施。 |
| 上下文适应性 | CLAUDE.md 层级、渐进式的可扩展性，以及随时间演变的信任轨迹。 |
13 条设计原则
| 原则 | 设计问题 |
|---|---|
| 拒绝优先并交由人工升级 | 遇到未知操作，是允许、阻止还是交由人工升级？ |
| 渐进式信任光谱 | 用固定权限等级，还是让用户随使用深入逐步跨越的信任光谱？ |
| 深度防御 | 一道安全边界，还是多道相互重叠的安全边界？ |
| 外部化的可编程策略 | 硬编码策略，还是带生命周期钩子的外部化配置？ |
| 上下文是稀缺资源 | 一次性截断，还是渐进式流水线？ |
| 仅追加的持久状态 | 可变状态、快照，还是仅追加的日志？ |
| 最小脚手架，最大 harness | 把投入放在脚手架上，还是放在运行基础设施上？ |
| 价值观优先于规则 | 刚性流程，还是带确定性护栏的语境化判断？ |
| 可组合的多机制扩展 | 单一 API，还是开销各异的分层机制？ |
| 按可逆性加权的风险评估 | 对所有操作一视同仁，还是对可逆操作放宽监管？ |
| 透明、基于文件的配置与记忆 | 用不透明的数据库和嵌入向量，还是用户可直接查看的文件？ |
| 隔离的子智能体边界 | 共享上下文与权限，还是相互隔离？ |
| 优雅恢复与韧性 | 硬失败，还是静默恢复？ |
论文还引入了第六个评估视角——长期能力保持——并援引证据表明：在 AI 辅助条件下工作的开发者，在理解力测试中得分低 17%。
核心是一个 ReAct 模式的 while 循环：组装上下文 → 调用模型 → 分派工具 → 检查权限 → 执行 → 重复。实现为一个产生流式事件的 AsyncGenerator。
每次模型调用前，五个压缩整形阶段按顺序执行（开销最低者优先）：预算削减 → 裁剪 → 微压缩 → 上下文折叠 → 自动压缩。
每轮 9 步管道： 设置解析 → 状态初始化 → 上下文组装 → 5 个预模型整形阶段 → 模型调用 → 工具分派 → 权限门控 → 工具执行 → 停止条件
两条执行路径：
StreamingToolExecutor—— 工具流入时即开始执行（延迟优化）- 后备
runTools—— 将工具分类为并发安全或互斥
故障恢复： 最大输出 token 升级（3 次重试）、反应式压缩（每轮一次）、提示过长处理、流式后备、后备模型
5 个停止条件： 无工具调用、最大轮次、上下文溢出、钩子干预、显式中止
7 个权限模式构成渐进式信任光谱：plan → default → acceptEdits → auto（ML 分类器）→ dontAsk → bypassPermissions（+ 内部 bubble）。
拒绝优先：宽范围的拒绝规则始终压过窄范围的允许规则。7 个独立安全层，从工具预过滤，到 shell 沙箱，再到钩子拦截。恢复会话时权限永不自动恢复——每次会话都要重新建立信任。
[!WARNING] 共享故障模式： 当各层共享同一种约束时，深度防御就会退化。逐个子命令解析会让事件循环陷入饥饿——一旦子命令超过 50 个，Claude Code 就会为了避免 REPL 卡死而跳过整段安全分析。
更多详情：授权管道、auto 模式分类器、CVE
授权管道： 预过滤（剥离被拒绝的工具）→ PreToolUse 钩子 → 拒绝优先规则评估 → 权限处理程序（4 个分支：协调器、swarm worker、推测式分类器、交互式）
Auto 模式分类器（yoloClassifier.ts）：使用内部/外部权限模板的单独 LLM 调用。两阶段：快速过滤 + 思维链。
预信任窗口： 两个已修复的 CVE 根因相同——钩子和 MCP 服务器会在初始化阶段、信任对话框弹出之前就已执行，由此形成一个绕开拒绝优先管道、天然享有特权的攻击窗口。
四个渐进式上下文成本机制： 钩子（零成本）→ Skills（低成本）→ 插件（中成本）→ MCP（高成本）。智能体循环中的三个注入点：assemble()（模型看到的内容）、model()（它能触及的内容）、execute()（操作是否/如何运行）。
工具池组装（5 步）：基础枚举（最多 54 个工具）→ 模式过滤 → 拒绝预过滤 → MCP 集成 → 去重
27 个钩子事件，跨越 5 个类别，4 种执行类型（shell、LLM 评估、webhook、subagent 验证器）
插件清单支持 10 种组件类型：命令、智能体、skills、钩子、MCP 服务器、LSP 服务器、输出样式、通道、设置、用户配置
Skills： SKILL.md 含 15+ 个 YAML frontmatter 字段。关键区别——SkillTool 把内容注入到当前上下文；AgentTool 另开一个隔离的上下文。
由 9 个有序来源拼装出上下文窗口。CLAUDE.md 指令作为用户上下文传递（模型对其遵从是概率性的），而非系统提示（遵从是确定性的）。记忆是基于文件的（不使用向量数据库）——完全可查看、可编辑、可纳入版本控制。
4 级 CLAUDE.md 层级： 托管（/etc/）→ 用户（~/.claude/）→ 项目（CLAUDE.md、.claude/rules/）→ 本地（CLAUDE.local.md，被 gitignore 忽略）
5 层压缩（渐进式惰性降级）：预算削减 → 裁剪 → 微压缩 → 上下文折叠（读取时投影，非破坏性）→ 自动压缩（完整模型摘要，最后手段）
记忆检索： 由 LLM 扫描各记忆文件的文件头，最多挑出 5 个相关文件。不使用嵌入向量，也不使用向量相似度。
6 个内置类型（Explore、Plan、General-purpose、Guide、Verification、Statusline）+ 通过 .claude/agents/*.md 定义的自定义智能体。侧链转录稿：只把摘要回传给父级（父级上下文被屏蔽在子智能体的冗长输出之外）。三种隔离模式：worktree、remote、in-process。多实例间通过 POSIX flock() 协调。
SkillTool vs AgentTool： SkillTool 把内容注入到当前上下文（开销低）。AgentTool 另开一个隔离的上下文（开销高，但能防止上下文爆炸）。
权限覆盖： 子智能体 permissionMode 生效，除非父级处于 bypassPermissions/acceptEdits/auto（显式用户决策始终优先）。
自定义智能体： YAML frontmatter 支持 tools、disallowedTools、model、effort、permissionMode、mcpServers、hooks、maxTurns、skills、memory scope、background flag、isolation mode。
三个通道：仅追加（append-only）的 JSONL 转录稿、全局提示历史、子智能体侧链。恢复会话时权限永不自动恢复——每次会话都要重新建立信任。设计上优先可审计性，而非查询能力。
链式修补： 压缩边界记录 headUuid/anchorUuid/tailUuid。会话加载器在读取时修补消息链；磁盘上的数据不会被就地改写。
检查点： --rewind-files 的文件历史检查点，存储在 ~/.claude/file-history/<sessionId>/。
这些 agent 系统的新进展进一步强化了 Claude Code 揭示的同一个判断：agent 能力不只是模型属性，而是由模型周围的运行时、context 层、执行边界、工具供应链、人类对它的控制和评估闭环共同产生。
| 设计启示 | 对 Agent 构建者意味着什么 | 代表信号 |
|---|---|---|
| 运行时与控制面是一等设计关注点 | 持久执行、检查点、沙箱、agent inventory、策略面和可观测性应该作为用户可感知的系统界面来设计，而不是隐藏在部署管线里。 | Cursor cloud agents、Google Managed Agents、Microsoft Agent 365、Databricks Omnigent |
| Context 是有生命周期的基础设施 | Prompt、文件、skills、IDE 索引、workspace state、memory namespace 和 interpreter state 都需要生命周期、来源、审查和回滚。 | LangChain Context Hub、AWS AgentCore、Anthropic managed-agent memory |
| 执行边界就是安全边界 | 权限、网络可达性、文件系统访问、凭证托管、租户隔离和 OS sandboxing 是核心架构，而不是后期加固项。 | Codex Windows sandbox、Running Codex safely、Anthropic self-hosted sandboxes |
| 工具与 skills 构成供应链 | MCP servers、skills、plugins 和 agent-to-agent protocols 需要 registry、allowlist、identity、语义审查、版本管理和撤销机制。 | NSA MCP security、GitHub MCP allowlists、A2A milestone |
| 人类角色转向管理者与验证者 | Agent 产品应该支持目标、计划、审批、中断、可审查 diff、升级路径，以及受约束的多 agent 写权限。 | Codex from anywhere、Copilot cloud agent、Cognition multi-agents |
| 可观测性必须进入改进闭环 | Traces 不应止步于被动日志，而应进入 eval、failure clustering、policy enforcement 和 prompt/tool repair。 | LangSmith Engine、OpenAI agent improvement loop、AWS AgentCore Evaluations |
这些信号不是在替代 Claude Code 的 design space，而是在让它的边界更清晰：agent loop 是小的部分，周围的 harness 才是大多数能力、安全和可靠性决策发生的地方。按月份记录的资料见 docs/agent-design-space-source-notes_zh.md。
本文不是一份写代码的教程，而是一份关于你必须做出的设计决策的指南——素材全部来自对 Claude Code 的架构分析。
每个生产级智能体都要面对下列决策：
| 决策 | 问题 | 关键洞察 |
|---|---|---|
| 推理放在哪里 | 逻辑放在模型里多，还是 harness 里多？ | 随着模型能力逐渐趋同，harness 才是差异化的关键。 |
| 安全姿态 | 如何防止有害行为？ | 当各层共享故障模式时，深度防御会失效。 |
| 上下文管理 | 模型究竟看到什么？ | 从第一天起就要为上下文稀缺而设计。渐进式优于一次性截断。 |
| 可扩展性 | 扩展如何接入？ | 并非所有扩展都必须消耗上下文 token。 |
| 子智能体架构 | 共享上下文还是隔离上下文？ | Plan 模式下的智能体团队消耗约 7 倍 token；靠子智能体只回传摘要，才能避免上下文爆炸。 |
| 会话持久化 | 什么会延续到下一次会话？ | 恢复会话时绝不自动恢复权限。可审计性优先于查询能力。 |
同样的设计问题，在不同的部署情境下会给出不同的架构答案。下表以论文第 10 节用于 OpenClaw 对比的六个设计维度，对 Claude Code v2.1.88 与两个具有代表性的同类系统进行对比——OpenClaw（本地优先的多渠道个人助手网关）和 NousResearch/hermes-agent（支持多部署场景的自改进智能体）。各单元格均有来源依据，这不是功能评分表。
| 设计维度 | Claude Code (v2.1.88)  |
OpenClaw  |
Hermes-Agent  |
|---|---|---|---|
| 系统范围与部署 | 面向编程的单用户 CLI / SDK / IDE 接口；所有入口共用一个 queryLoop 异步生成器。 |
本地优先 WebSocket 网关（默认端口 18789，默认仅监听回环地址）；将约 23 个消息渠道路由至内嵌智能体运行时；提供 macOS、iOS、Android 伴侣应用。 | 三个入口：hermes（交互式 CLI）、hermes-agent（程序化运行时）、hermes-acp（ACP 服务器）；网关适配器将消息路由至按 LRU 缓存的 AIAgent 实例（最多 128 个，空闲超时 1 小时）；也可通过 hermes mcp serve 作为 MCP 服务器运行。 |
| 信任模型与安全 | 拒绝优先的逐动作评估；7 种权限模式；基于 LLM 的自动模式分类器（yoloClassifier / sideQuery）；会话级权限状态（会话绕过标志、应用白名单状态）在恢复时不予还原。 |
单一可信操作员模型；DM 配对码、发件人白名单、网关身份验证；每个智能体有独立的工具允许/拒绝策略；通过 Docker / SSH / OpenShell 提供可选沙箱，默认关闭；non-main 模式可对非主会话启用沙箱；明确声明不支持对共享网关上的恶意多租户的隔离。 |
危险命令模式检测，配合会话级审批状态；CLI 交互提示与网关异步提示；辅助 LLM 智能审批可自动批准低风险命令；永久白名单持久化于 config.yaml；子智能体工作线程默认自动拒绝危险命令（可通过 subagent_auto_approve 开启批处理/定时任务的自动批准）。 |
| 智能体运行时与工具 | 单一 queryLoop 异步生成器，以流式事件方式产出；环境与特性门控的工具注册表；API 调用前按条件运行压缩（Snip、Microcompact、Context Collapse、Auto-Compact），Auto-Compact 优先尝试会话记忆压缩。 |
内嵌智能体运行时位于网关 RPC 调度层内部（agent RPC 校验参数后立即返回，异步执行，并通过网关协议回传生命周期/流式事件）；每个会话有独立队列序列化，支持可选的全局通道。 |
While 循环，含显式的每轮迭代预算和宽限调用槽；每轮检查点去重；网关 step_callback 钩子在每次迭代时触发；辅助模型上下文压缩对中间轮次进行摘要，同时保护头尾。 |
| 扩展架构 | 四种机制按上下文开销递增排列：hooks → skills → plugins → MCP；27 个钩子事件；10 种插件组件类型。 | 清单优先插件系统，含 12 个能力类别；中央注册表暴露工具、渠道、provider 设置、钩子、HTTP 路由、CLI 命令和服务；独立技能层支持多来源（工作区优先级最高）及 ClawHub 公共注册表；openclaw mcp 同时提供 MCP 服务器接口和面向其他 MCP 服务器的出站客户端注册表。 |
plugins/ 目录下内置 12 个插件（context_engine、disk-cleanup、example-dashboard、google_meet、hermes-achievements、image_gen、kanban、memory、observability、platforms、spotify、strike-freedom-cockpit）；MCP 服务器（mcp_serve.py）暴露 10 个工具；ACP 适配器（acp_adapter/）将 Hermes 暴露为 ACP 服务器。 |
| 记忆与上下文 | 四层 CLAUDE.md 层级；API 调用前压缩（Snip、Microcompact、Context Collapse、Auto-Compact）；基于 LLM 从文件型 Markdown 记忆文件中进行选择。 | 工作区启动文件（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）及条件性 BOOTSTRAP.md / HEARTBEAT.md / MEMORY.md；独立记忆系统（MEMORY.md、memory/YYYY-MM-DD.md 格式的每日笔记、可选 DREAMS.md）；配置 embedding provider 后启用向量+关键词混合检索；实验性 dreaming 在后台整合并将符合条件的条目提升至长期记忆；可插拔压缩 provider。 |
SQLite 状态存储，含 FTS5 全文检索和 WAL 模式并发读取；sessions 通过 parent_session_id 链接以支持压缩触发的会话拆分；plugins/memory/ 下提供 8 个可换记忆后端（byterover、hindsight、holographic、honcho、mem0、openviking、retaindb、supermemory）；辅助 LLM 压缩作为独立的上下文管理层。 |
| 多智能体架构 | 通过侧链转录委托子智能体；6 种内置智能体定义（可用性取决于构建/模式）加自定义；父节点仅接收单条摘要消息（in-process / viewable transcript 情况下可保留更多内部细节）；隔离设置包含 worktree 和 remote，swarm 路径中有 in-process 队友后端。 |
两层架构。(1) 多智能体路由：每渠道独立智能体，拥有各自的工作区、认证配置、会话存储和模型配置，通过确定性绑定规则分发。(2) 子智能体委托：maxSpawnDepth 范围 1–5，默认 1，建议 2；工具策略按深度变化；项目愿景（VISION.md）明确拒绝将智能体层级框架作为默认架构。 |
delegate_task 工具在 ThreadPoolExecutor 中派生子 AIAgent 实例（父节点阻塞直至子节点完成）；每个子节点有全新对话历史、独立 task_id，以及受限工具集（DELEGATE_BLOCKED_TOOLS 移除了 delegate_task、clarify、memory、send_message、execute_code）；默认深度 MAX_DEPTH = 1（可配置，上限为 3）；默认 3 个并发子节点。 |
对比揭示了什么。 从表格中可以得出三点观察。第一，部署情境决定了大多数下游设计选择：面向单用户的编程 CLI 收敛于逐动作审批和单一执行循环，多渠道网关收敛于边界信任和渠道绑定的智能体，多部署消息云端智能体则收敛于可选容器/云隔离、LLM 智能审批和可换后端记忆层。第二，扩展层是各系统最鲜明的差异化所在：Claude Code 按上下文开销将四种机制分层，OpenClaw 将扩展视为网关层的注册表管理能力，Hermes-Agent 则内置插件组并对外暴露双 MCP 服务器 / ACP 服务器接口供其他智能体接入。第三，记忆架构跨越一个连续谱：文件型、可检视的 Markdown（Claude Code），文件型加可选向量及实验性 dreaming（OpenClaw），或 FTS5 全文索引加八个可换插件后端（含专用向量 / RAG provider）（Hermes-Agent）。此表最适合作为设计空间中三个不同定点来阅读，而非功能排行榜。
围绕 Claude Code 架构的仓库、重新实现和学术论文的精选索引。
贯穿论文的主要参考资料——Anthropic 自己的工程和研究出版物，以及产品文档。
| 文章 | 主题 |
|---|---|
| Building Effective Agents | 基础：简单的可组合模式优于重型框架。 |
| Effective Context Engineering for AI Agents | 上下文策划和 token 预算管理。 |
| Prompt Caching with Claude | 缓存读取费用为 10%、写入为 125%；默认 TTL 5 分钟。Claude Code 整套 cache-aware 压缩策略所依赖的平台特性基础。 |
| Harness Design for Long-Running Application Development | 自主全栈开发的 harness 架构；多智能体模式。 |
| Claude Code Auto Mode: A Safer Way to Skip Permissions | ML 分类器批准自动化；93% 批准率发现的来源。 |
| Beyond Permission Prompts: Making Claude Code More Secure and Autonomous | 基于沙箱的安全；权限提示减少 84%。 |
| How We Contain Claude Across Products | 讲述 Anthropic 如何在 claude.ai、Claude Code 与 Cowork 三款产品中约束 Claude 的行为（2026 年 5 月）；内容涵盖 Claude Code 的人在回路沙箱、审批疲劳问题，以及如何在出问题时把影响范围控制到最小。 |
| Measuring AI Agent Autonomy in Practice | 长期使用数据：随着用户熟练度提升，自动批准率从约 20% 上升到 40% 以上。 |
| Our Framework for Developing Safe and Trustworthy Agents | 负责任智能体部署的治理框架。 |
| When AI Builds Itself | Anthropic Institute 关于"递归自我改进"的讨论：AI 正在加速 AI 自身的研发；目前仍主要由人类把握的是研究方向的选择和对结果好坏的判断，文中还探讨了相应的治理设想。 |
| Scaling Managed Agents: Decoupling the Brain from the Hands | 分离推理、执行和会话的托管服务架构。 |
| An Update on Recent Claude Code Quality Reports | 复盘导致质量观感下降的三个 bug：reasoning-effort 默认值、一处缓存优化 bug，以及一次系统提示改动。 |
| Introducing Claude Opus 4.8 | 2026 年 5 月模型更新：判断力与诚实度提升（代码缺陷漏判约减少 4 倍）、可自主运行更久；在 research preview 中引入 dynamic workflows。 |
| Claude Fable 5 and Claude Mythos 5 | 2026 年 6 月发布的 Mythos 级模型，能力位于 Opus 之上；其中 Fable 5 是面向通用用户的安全版本（遇到高风险请求会回退到 Opus 4.8），在软件工程与智能体编码等任务上达到当前最强水平。自 2026 年 6 月 12 日起，两者已在全球暂停访问（见下一条）。 |
| Statement on Suspending Access to Fable 5 and Mythos 5 | Anthropic 关于暂停 Fable 5 与 Mythos 5 的声明。美国出口管制指令（2026 年 6 月 12 日）原本只限制外国公民访问，但 Anthropic 直接对全球所有用户停用了这两个模型，距上线只有几天。这是监管把一个已上线的前沿模型直接下架的罕见案例，也是 agent 系统在部署中要面对的合规与安全压力的一个具体例子。 |
| 文档 | 主题 |
|---|---|
| How Claude Code Works | 智能体循环、工具和终端自动化的官方概述。 |
| Permissions | 分层权限系统、模式、细粒度规则。 |
| Hooks | 27 事件钩子参考、执行模型、生命周期事件。 |
| Memory | CLAUDE.md 层级、自动记忆、习得的偏好。 |
| Sub-agents | 专用隔离助手、自定义提示、工具访问。 |
| Orchestrate Subagents at Scale with Dynamic Workflows | Claude 写一段 JavaScript 编排脚本，后台 runtime 扇出到至多 1,000 个 subagent，中间状态保存在脚本变量中、不进入 context window（v2.1.154+，research preview）。 |
| What's New in Claude Opus 4.8 | 对话中途 system 消息（保留 prompt cache）、更低的可缓存 prompt 阈值、更少 compaction 与更好的 compaction 恢复。 |
| Claude Code CHANGELOG | 发布说明；dynamic workflows 与 Opus 4.8 在 v2.1.154 落地。 |
对 Claude Code 内部设计的深度剖析。
| 仓库 | 描述 |
|---|---|
ComeOnOliver/claude-code-analysis  |
全面的逆向工程：源码树结构、模块边界、工具清单和架构模式。 |
alejandrobalderas/claude-code-from-source  |
18 章技术书（约 400 页）。全部原创伪代码，无专有源代码。 |
liuup/claude-code-analysis  |
中文深度剖析——启动流程、查询主循环、MCP 集成、多智能体架构。 |
sanbuphy/claude-code-source-code  |
四语（EN/JA/KO/ZH）分析——多领域报告，涵盖遥测、代号、KAIROS、未发布的工具。 |
cablate/claude-code-research  |
关于内部结构、Agent SDK 和相关工具的独立研究。 |
Yuyz0112/claude-code-reverse  |
可视化 Claude Code 的 LLM 交互——日志解析器和可视化工具，追踪提示、工具调用和压缩。 |
Piebald-AI/claude-code-system-prompts  |
跨 170+ 个 Claude Code 版本的 prompt 语料库——主 system prompt、内置工具描述、子智能体提示（Plan/Explore/Task）以及约 40 条 system reminder。每次 Claude Code 发布后数分钟内更新。 |
净室重写和可构建的研究分支。
| 仓库 | 描述 |
|---|---|
chauncygu/collection-claude-code-source-code  |
社区 Claude Code 源码产物的聚合集——包括 claw-code（Rust 移植）、nano-claude-code（Python）和提取的原始源码存档。 |
777genius/claude-code-working  |
可运行的逆向工程 CLI。使用 Bun 运行，450+ 个 chunk 文件，polyfill 了 31 个特性标志。 |
T-Lab-CUHKSZ/claude-code  |
香港中文大学（深圳）的可构建研究分支——从原始 TypeScript 快照重建构建系统。 |
ruvnet/open-claude-code  |
夜间自动反编译重建——903+ 测试、25 个工具、4 种 MCP 传输、6 个权限模式。 |
Enderfga/openclaw-claude-code  |
OpenClaw 插件——为 Claude/Codex/Gemini/Cursor 提供统一的 ISession 接口。多智能体委员会。 |
memaxo/claude_code_re  |
从压缩后的包进行逆向工程——对公开分发的 cli.js 文件进行反混淆。 |
agentforce314/clawcodex  |
Python 重新实现，支持多家 LLM 厂商。 |
针对 Claude Code 本身的教程和动手学习路径。
| 仓库 | 描述 |
|---|---|
shareAI-lab/learn-claude-code  |
"Bash 就是你需要的一切"——19 章 0 到 1 课程，包含可运行的 Python 智能体、Web 平台。ZH/EN/JA。 |
FlorianBruniaux/claude-code-ultimate-guide  |
从初学者到高级用户的指南，包含生产级模板、智能体工作流指南和速查表。 |
affaan-m/everything-claude-code  |
智能体 harness 优化——skills、本能、记忆、安全和研究优先开发。 |
与本文设计空间分析相互呼应的外部资源——概念文章、课程和代码，从工程实践视角刻画 harness 这一层。
| 仓库 | 描述 |
|---|---|
deusyu/harness-engineering  |
学习档案——原创概念解读、独立思考与外文翻译；从概念理解到独立实践的 Harness Engineering 入门。 |
walkinglabs/learn-harness-engineering  |
英文项目制课程——PDF 课本、大纲与 capstone 项目，围绕指令、状态管理、验证机制、作用域约束和会话生命周期这五个 harness 子系统展开。 |
china-qijizhifeng/agentic-harness-engineering  |
自动演化 coding agent harness 的可观测系统——一个 meta-agent 读取执行 trace，自动改写 system prompt、工具、中间件、skills、子 agent 和记忆。 |
ZhangHanDong/harness-engineering-from-cc-to-ai-coding  |
《马书》——把 Claude Code v2.1.88 作为 Harness Engineering 案例研究的中文 mdBook；涵盖架构、prompt engineering、上下文管理、prompt cache、安全和给构建者的经验。 |
| 文章 | 它的价值所在 |
|---|---|
| Marco Kotrotsos — "Claude Code Internals"（15 部分系列） | 源码泄露前最系统的分析。架构、智能体循环、权限、子智能体、MCP、遥测。 |
| Alex Kim — "The Claude Code Source Leak" | 反蒸馏机制、挫折检测、Undercover Mode、每天约 25 万次浪费的 API 调用。 |
| Haseeb Qureshi — 跨智能体架构比较 | Claude Code vs Codex vs Cline vs OpenCode——架构级比较。 |
| George Sung — "Tracing Claude Code's LLM Traffic" | 完整系统提示和完整 API 日志。发现双模型使用（Opus + Haiku）。 |
| Agiflow — "Reverse Engineering Prompt Augmentation" | 5 种提示增强机制，由实际网络追踪支持。 |
| Engineer's Codex — "Diving into the Source Code Leak" | 模块化系统提示、约 40 个工具、大型查询/工具子系统、反蒸馏机制。 |
| MindStudio — "Three-Layer Memory Architecture" | 上下文内记忆、MEMORY.md 指针索引、CLAUDE.md 静态配置。关于记忆的最佳单一资源。 |
| WaveSpeed — "Claude Code Architecture: Leaked Source Deep Dive" | 512K 行 TS 源码深度剖析；上下文压缩和反蒸馏。 |
| Zain Hasan — "Inside Claude Code: An Architecture Deep Dive" | 分层架构、5 种入口模式、多智能体演练。 |
| Addy Osmani — "Agent Harness Engineering" | 把 harness engineering 视为一门工程学科，给出命名化的原语（文件系统/git 状态、沙箱、AGENTS.md 记忆、压缩、规划循环、hooks）；将 Claude Code 作为最成熟的范例。 |
| Addy Osmani — "Loop Engineering" | 给 "loop engineering" 命名的那篇：你不再亲自给智能体写 prompt，而是搭一个自动去 prompt 它的循环。它的几个部分（自动化任务、worktree、skills、连接器、子智能体，以及一个记录进度的文件）就是本文分析的 harness 层。 |
| Andrej Karpathy — "Sequoia Ascent 2026" | 主张"智能体工程"：人类负责编排与验证，而不再亲自写代码。"LLM 与强化学习自动化的是你能验证的东西"；"你可以外包思考，但无法外包理解"。 |
其他正在构建代码智能体的厂商的官方工程博客——有助于了解 Claude Code 之外的厂商如何回答同样的设计问题。
| 资源 | 厂商 | 亮点 |
|---|---|---|
| Harness Engineering: Leveraging Codex in an Agent-First World | OpenAI | 把 harness 定义为让智能体产出可靠、可维护结果所需的约束、反馈回路、文档结构与工具；文中提到，他们一款约百万行代码的 beta 版产品几乎没有一行是人工编写的。 |
| Best Practices for Coding with Agents | Cursor | 将智能体 harness 拆为三部分——Instructions、Tools、Model——并按所用模型分别编排。 |
| Build with Google Antigravity | 以智能体为先的平台：通过 Manager 界面异步编排多个智能体，并用 Artifacts（计划、截图、录屏）代替原始日志来做验证。 | |
| Codex Security: Now in Research Preview | OpenAI | 应用安全智能体：先为项目构建专属威胁模型，再在沙箱验证环境中查找并压力测试漏洞。 |
| 论文 | 会议 | 相关性 |
|---|---|---|
| Architectural Design Decisions in AI Agent Harnesses | arXiv | 基于源码、对 70 个 agent 系统项目的研究，识别出反复出现的设计维度；与本文设计空间框架最贴近的同期对照工作。 |
| Decoding the Configuration of AI Coding Agents | arXiv | 对 328 个 Claude Code 配置文件的实证研究——软件工程关注点与共现模式。 |
| On the Use of Agentic Coding Manifests | arXiv | 分析了 242 个仓库中的 253 个 CLAUDE.md 文件——操作性命令中的结构模式。 |
| Context Engineering for Multi-Agent Code Assistants | arXiv | 结合多个 LLM 进行代码生成的多智能体工作流。 |
| OpenHands: An Open Platform for AI Software Developers | ICLR 2025 | 开源 AI 编码智能体的主要学术参考。 |
| SWE-Agent: Agent-Computer Interfaces | NeurIPS 2024 | 基于 Docker 的编码智能体，带有自定义的智能体-计算机接口。 |
上述项目多聚焦于工程层面的逆向工程或实际动手重新实现，而本论文提供的是一套系统的"价值观 → 原则 → 实现"分析框架——从五个人类价值观出发，经由十三条设计原则，一路追到具体的源码级选择；并借助与 OpenClaw 的对比揭示一个事实：真正构成工程复杂性的，是那些横跨各子系统的整合机制，而不是模块化的单点特性。
查看更完整的精选资源列表：docs/related-resources_zh.md
围绕 Claude Code 的更广阔智能体设计空间。上方的跨系统对比节深入分析了三个最相近的同类系统（Claude Code、OpenClaw、Hermes-Agent）；下方条目则在更广的范围给出语境，涵盖编码智能体同类、框架、记忆系统、harness 扩展、MCP 生态和专业领域智能体。
| 仓库 | 推出时间 | 重点 |
|---|---|---|
| openclaw/openclaw |
2026 年 1 月 | 跨消息平台的本地优先个人 AI 助手。（第 10 节分析） |
NousResearch/hermes-agent  |
2026 年 2 月 | 具有跨会话记忆的自我改进个人智能体。（第 10 节分析） |
opensquilla/opensquilla  |
2026 年 6 月 | 主打 token 效率的微内核个人智能体，覆盖 CLI、Web UI 与聊天渠道；它用 ML 分类器按成本给模型分档并据此路由，配有本地 Markdown+SQLite 记忆（一个 MEMORY.md 加上按日期记录的笔记，支持关键词与向量召回），并提供 Bubblewrap/Seatbelt 沙箱。 |
pewdiepie-archdaemon/odysseus  |
2026 年 6 月 | PewDiePie 推出的自托管、本地优先 AI 工作台：带工具、MCP 与 shell 访问的自主智能体，外加记忆、深度研究与按硬件适配的模型服务。AGPL-3.0。 |
sst/opencode  |
2025 年 6 月 | 与模型厂商无关的终端编码智能体，集成 ACP。 |
Aider-AI/aider  |
2023 年 | 在终端中与 LLM 结对编程，支持主流模型。 |
continuedev/continue  |
2023 年 | IDE 中受版本控制的 AI 检查，配套开源 Continue CLI。 |
google-gemini/gemini-cli  |
2025 年 | Google 开源终端编码智能体，含 ReAct 循环与 MCP 支持。 |
openai/codex  |
2025 年 | OpenAI 的本地终端编码智能体，Rust 实现。 |
OpenHands/OpenHands  |
2024 年 | 开源 SWE 智能体平台（原 OpenDevin），含沙箱化运行时。 |
cline/cline  |
2024 年 | VS Code 智能体，显式 Plan/Act 双阶段监督循环。 |
block/goose  |
2025 年 | Block 开源、编辑器无关的智能体，MCP 风格扩展。 |
charmbracelet/crush  |
2025 年 | Go 编写的智能编码 TUI，多 LLM provider 抽象。 |
RooCodeInc/Roo-Code  |
2024 年 | VS Code 多智能体开发团队，含 Architect/Coder/Reviewer 角色。 |
bytedance/trae-agent  |
2025 年 | 字节跳动模块化、面向 SWE-bench 的软件工程智能体。 |
github/copilot-cli  |
2026 年 | GitHub Copilot 正式发布的终端智能体 CLI，跨会话规划、构建、审查。 |
badlogic/pi-mono  |
2025 年 8 月 | monorepo 编码智能体工具包——统一 LLM API、TUI + web UI；OpenClaw 嵌入此处的 pi-coding-agent SDK。 |
| 仓库 | 推出时间 | 重点 |
|---|---|---|
geekan/MetaGPT  |
2023 年 | 角色分工的多智能体软件公司模拟（ICLR 2024 oral）。 |
microsoft/autogen  |
2023 年 | 微软研究院多智能体对话框架（COLM 2024）。 |
microsoft/agent-framework  |
2025 年 | 微软整合 AutoGen 与 Semantic Kernel 的后继框架（2026 年 4 月发布 1.0）。在 BUILD 2026 上加入了内置的 agent harness（上下文压缩、文件记忆、shell）和 CodeAct：让模型把多次工具调用写成一段 Python 一次跑完，而不是一次只调一个。 |
langchain-ai/langgraph  |
2024 年 | 基于状态图的多智能体编排，含检查点。 |
openai/openai-agents-python  |
2024 年 | OpenAI 轻量多智能体框架，含 handoff 与 guardrail。 |
crewAIInc/crewAI  |
2023 年 | 精简 Python 框架，角色化多智能体协作，独立于 LangChain。 |
openai/symphony  |
2026 年 2 月 | OpenAI 的编排方案，用于隔离、自主的实现运行。 |
ComposioHQ/agent-orchestrator  |
2025 年 | 并行 AI 智能体编排层，含 git worktree 隔离。 |
coleam00/Archon  |
2025 年 2 月 | 确定性 harness——YAML 定义工作流与执行审计跟踪。 |
bytedance/deer-flow  |
2026 年 | 字节跳动的长程"SuperAgent" harness：子智能体、记忆、沙箱、技能与消息网关；基于 LangGraph/LangChain 的彻底重写。 |
QwenLM/Qwen-Agent  |
2023 年 | 阿里 Qwen 的 agent 框架：function calling、MCP、Docker code interpreter、RAG；Qwen Chat 的后端。 |
TencentCloudADP/youtu-agent  |
2025 年 | 腾讯云基于 openai-agents SDK 的框架；用 YAML 定义 agent、可自动生成配置，并提供 Claude Code 式的 skills。 |
coze-dev/coze-studio  |
2025 年 | 字节跳动 Coze 的开源版：可视化的 no-code/low-code 平台，用于搭建、调试与部署 agent 和工作流。 |
| 仓库 | 推出时间 | 重点 |
|---|---|---|
mem0ai/mem0  |
2024 年 | 生产级记忆层，含 LoCoMo 与 LongMemEval 基准（arXiv:2504.19413）。 |
letta-ai/letta  |
2023 年 | 有状态智能体平台，OS 式分层记忆分页（原 MemGPT，COLM 2024）。 |
MemPalace/mempalace  |
2026 年 | AI 智能体的本地优先记忆系统。 |
| 仓库 | 推出时间 | 重点 |
|---|---|---|
addyosmani/agent-skills  |
2025 年 | 22 个生命周期 skill 配套斜杠命令（/spec、/plan、/build、/test、/review、/ship）。 |
obra/superpowers  |
2025 年 | 跨 harness（Claude Code、OpenCode、Codex）的强制工作流 skill 框架。 |
mattpocock/skills  |
2026 年 | 作者本人日常使用的 .claude/skills 技能集，面向真实工程——包含可组合的 TDD、diagnose、to-issues/to-prd 等技能；与具体模型无关，适用于 Claude Code、Codex 等编码智能体。 |
multica-ai/andrej-karpathy-skills  |
2026 年 | 单个 CLAUDE.md，凝练 Andrej Karpathy 关于 LLM 编码的四条规则（先想后写、简洁优先、外科手术式改动、目标驱动执行）；可作为插件安装或按项目添加。 |
lsdefine/GenericAgent  |
2025 年 | 极简自演化自主智能体框架——9 个原子工具加约 100 行 ReAct 循环。 |
| 仓库 | 推出时间 | 重点 |
|---|---|---|
PrefectHQ/fastmcp  |
2024 年 | 构建 MCP 服务器与客户端的 Python 框架，事实上的 SDK。 |
upstash/context7  |
2025 年 | 为 LLM 与 AI 编辑器提供实时库文档的 MCP 服务器。 |
microsoft/playwright-mcp  |
2024 年 | 微软官方 MCP 服务器，使用 accessibility tree 快照。 |
| 仓库 | 推出时间 | 重点 |
|---|---|---|
666ghj/MiroFish  |
2026 年 3 月 | 多智能体群体智能模拟引擎。 |
multica-ai/multica  |
2026 年 | 用于任务分配和技能复合的托管智能体平台。 |
HKUDS/nanobot  |
2026 年 2 月 | 来自 HKU-DS 的超轻量级个人 AI 智能体。 |
HKUDS/OpenHarness  |
2026 年 4 月 | 带有内置个人智能体（Ohmo）的开放智能体 harness；harness 架构的学术参考点。 |
karpathy/autoresearch  |
2026 年 3 月 | Andrej Karpathy 出品：在单 GPU 上自动运行 nanochat 训练研究的 AI 智能体循环。 |
HKUDS/CLI-Anything  |
2026 年 3 月 | "Making ALL Software Agent-Native"——把任意软件包装成智能体可调用工具。 |
Panniantong/Agent-Reach  |
2026 年 2 月 | 一个 CLI 让智能体读写 Twitter、Reddit、YouTube、GitHub、Bilibili、小红书。 |
agentscope-ai/QwenPaw  |
2026 年 2 月 | AgentScope 团队的个人 AI 助手。 |
cft0808/edict  |
2026 年 2 月 | 基于 OpenClaw 的多智能体编排，模拟唐代三省六部制（9 个专门智能体 + 实时 dashboard + 完整审计）。 |
@article{diveclaudecode2026,
title={Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems},
author={Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, and Zhiqiang Shen},
year={2026},
eprint={2604.14228},
archivePrefix={arXiv},
primaryClass={cs.SE},
}本作品采用 CC BY-NC-SA 4.0 许可。