OpenHarness：1.17万行代码拆解Claude Code的Agent骨架与核心架构

Claude Code 的源代码最近被外界深入剖析了一番。其规模令人印象深刻：51.2 万行代码、1884 个文件、50 多个工具——这揭示了一个核心事实，真正复杂的往往不是模型本身，而是承载其运行的“车架”（harness）。诸如上下文预算管理、工具延迟加载、三级压缩与熔断机制、权限预判分类器、子代理的四种隔离模式，以及多达 27 个供扩展的 Hook 节点。这些模块单独看或许并不惊艳，但将它们精密地组合在一起，才是 AI Agent 能在真实、复杂环境中稳定、持续运行的关键。

OpenHarness 恰好站在一个绝佳的对照位置：它仅有 约 1.17 万行代码、163 个文件。它并没有试图复刻 Claude Code 这辆“整车”，而是选择打开引擎盖，将 Agent 最核心的运行骨架单独开源，供开发者学习和理解。

项目卡片

• 项目名: OpenHarness
• GitHub: https://github.com/HKUDS/OpenHarness
• 增长信号: 2026-04-01 发布 v0.1.0；近 30 天持续更新 README、文档和 CI；已补齐 CHANGELOG、CONTRIBUTING、SHOWCASE 与测试说明
• 一句话判断: 这是 Claude Code 的教学底盘——它不是平替，但可能是目前最适合用来拆解学习的 Agent 骨架项目。

骨架摊平：清晰的核心目录结构

OpenHarness 将 Claude Code 隐藏在 51 万行代码中的基础架构，清晰地呈现出来。

engine/ 目录负责管理查询循环，tools/ 管理工具的注册与执行，permissions/ 处理权限与路径规则，而 skills/、plugins/、memory/ 则负责知识库和扩展功能的装载，tasks/ 和 coordinator/ 管理后台任务与多代理协作。Claude Code 当然也包含这些层次，但它们被深深嵌入数十万行的产品级代码中。OpenHarness 则直接把这个骨架“摊平”了。

最典型的例子是 src/openharness/engine/query.py 中的主循环逻辑：模型流式输出 → 检测到工具调用则执行 → 将结果回注上下文 → 进入下一轮。对于单个工具，它顺序执行；对于多个工具，则使用 asyncio.gather 实现并发。其执行链条明确：执行前 hook → 权限检查 → 工具执行 → 执行后 hook。Claude Code 拥有类似的主链，但其外部包裹着上下文压缩、工具搜索、缓存、熔断等大量优化层。OpenHarness 没有把这些复杂性全部实现，因此你能清晰地看到主承力结构。

保留精髓：主链、插槽与原语

OpenHarness 的价值不在于“小”，而在于“小得恰到好处”。

核心调用链完整保留。 模型生成、工具选择、工具执行、结果回注、循环继续——这是 Agent 最不可或缺的部分。无论 Claude Code 的实现多么重量级，OpenHarness 同样完整地具备了这一基础链路。

关键扩展插槽均已预留。 Hook、权限、技能（skills）、插件（plugins）、记忆（memory）这些扩展接口一应俱全。Claude Code 之所以能挂载 50 多个工具并演化出复杂工作流，依赖的不仅仅是提示词工程，更是这些预先设计好的插槽。OpenHarness 也保留了它们，因此它不是一个一次性演示（demo），而是一个能够持续成长的运行时（runtime）。这对于希望进行源码分析和深度定制的开发者来说，是一个清晰的起点。

多代理协作原语已经具备。 任务创建、后台运行、日志记录、状态管理、消息回传等基础能力都已实现。Claude Code 在子代理层面已经实现了诸如 Worktree 文件系统隔离和跨机器执行等重工程特性；OpenHarness 虽然没有照搬那套复杂的工程实现，但至少正确实现了“多代理协作不是简单多开聊天窗口，而是一个任务系统”的核心概念。

差距何在：Claude Code 的 51 万行重在哪里？

那么，Claude Code 做了哪些事情让它如此“重”，而 OpenHarness 选择暂时不做呢？

• 工具治理：Claude Code 让 50 多个工具不会在对话一开始就全部暴露给模型，而是通过 ToolSearch 实现延迟加载，避免模型在庞大的工具列表中选错。OpenHarness 没有实现这套机制。
• 上下文优化：Claude Code 将系统提示词（system prompt）分为固定和动态两部分并做缓存，大型工具的输出结果会写入磁盘而非全部塞入上下文。OpenHarness 没有做这类深度优化。
• 压缩与熔断：Claude Code 采用三级压缩策略并对连续失败进行熔断（据悉，早期未熔断时，连续失败曾每天浪费高达 25 万次 API 调用）。OpenHarness 没有实现这些生产级的稳定性保障。
• 权限体验：Claude Code 会在弹窗询问用户授权前，先运行分类器进行预判，以减少不必要的交互打断。OpenHarness 目前仅在执行前进行硬性检查。
• 扩展平台：Claude Code 开放了 27 个 Hook 节点，允许企业系统从外部深度集成。OpenHarness 的 Hook 系统则相对基础。

简而言之，Claude Code 是一辆焊好了所有稳定系统的量产车，适合直接“上路”投入生产；而 OpenHarness 则是把发动机和传动系统露出来的教学底盘，前者适合使用，后者适合学习和改造。

权限与生态兼容：位置都对了

在权限方面，permissions/checker.py 提供了三种检查模式、工具黑白名单、路径规则、命令拒绝模式（deny pattern）。Claude Code 在此基础上做了更细致的用户体验优化，而 OpenHarness 首先把“先检查，再执行”的安全基石牢牢钉住——对于开源骨架而言，这比追求极致的体验抛光更为重要。

在生态兼容性上，它选择了一条聪明的路线：不复制 Claude Code 的产品表面，而是兼容其文件组织规范。例如，plugin.json、.claude-plugin/plugin.json、hooks/hooks.json、.mcp.json、CLAUDE.md 等文件格式都能被识别和接入。迁移一个 Agent 系统时，最昂贵的成本往往不是更换模型，而是原有的技能、插件和文档能否被新系统继承和使用。通过查阅该项目的技术文档，可以更清晰地了解这些兼容性设计的细节。

结论

OpenHarness 并非 Claude Code 的直接替代品——51.2 万行代码的差距，清晰地表明了成熟 Agent 系统的难度在于产品级的运行时工程，而 OpenHarness 刻意省略了许多重型优化层。

但是，如果你希望看清一个现代 AI Agent 的骨架究竟长什么样，它可能是目前最值得阅读的项目：它保留了 Claude Code 最关键的结构设计，又没有将面向超大规模场景的复杂性堆砌进来。Claude Code 让我们看到了工业级 Agent 面临的真实挑战，而 OpenHarness 则将其中最值得理解、最具有普适性、最便于改造的核心部分，压缩到了一个可以通读的代码体量。

对于开发者而言，在云栈社区这类平台上与同行交流此类项目的实践心得，或许能获得更多启发。