learn-claude-code：从零搭一个 Claude Code 式 agent harness，而不是再造一个 agent
动手实践的教程，围绕 Bash 从零构建一个极简的 Claude Code 式智能体外壳，讲解模型与外壳如何组合成可用的智能体产品。
秒懂
- 它是什么？
- 这个仓库用 Python 从 0 到 1 实现了一个极简的 Claude Code 风格 agent harness。它的核心主张是：智能来自模型，代码只负责给模型造车。本文拆解它的架构、启动方式、局限，以及它和真正 agent 框架的区别。
- 适合谁用？
- 适合两类人：想理解 harness 工程细节的开发者，以及需要快速搭建一个可控、透明、可审计的编码 agent 原型的团队。不适合指望开箱即用、自带模型能力或完整生态的人。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 20 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的不是写 agent，而是造 harness
这个仓库的立论很明确：agent 的能力来自模型训练，不是来自外部代码编排。作者把当前市面上那些拖拽式工作流、无代码平台、prompt 链编排库称作「Rube Goldberg 机器」，认为它们只是把 LLM API 调用串起来，加上 if-else 分支和节点图，本质上是一个披着宏大外衣的 shell 脚本。learn-claude-code 要教你的，不是怎么训练模型，而是怎么给模型造一个能干活的环境。这个环境就是 harness，公式是：Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions。它针对的是编码场景，但设计模式可以推广到任何领域。
从 0 到 1 的极简架构：nano 到什么程度
仓库自称为 nano claude code 式 agent harness，Python 实现。从 README 看，它的核心不是提供一个完整产品，而是展示一个最小可工作的 harness 长什么样。它把 harness 拆成五个组成部分：工具（文件读写、shell、网络、数据库、浏览器）、知识（产品文档、API 规范、风格指南）、观察（git diff、错误日志、浏览器状态）、动作（CLI 命令、API 调用、UI 交互）、权限（沙箱隔离、审批流程、信任边界）。这个拆分本身就构成了架构骨架。每个工具被设计成原子化、可组合、描述清晰，这是 README 里明确提到的工具设计原则。它没有提供任何 benchmark 或性能数据，所以无法确认它在真实代码库上的表现。
核心机制：模型决策，harness 执行
README 反复强调一个分工：模型负责感知、推理和决策，harness 负责执行和提供上下文。具体到机制，它提到三个关键点：subagent 把专注的工作放在独立的消息列表中，避免污染主上下文；context compaction 缩短较早的历史记录；task system 让目标能跨越单次对话持续存在。这些机制对应的是上下文管理这个 harness 工程的核心难题。仓库没有给出具体的代码实现细节，但根据描述，它的数据流大致是：模型接收观察（如 git diff、错误日志），通过工具接口发出动作（如执行 shell 命令），然后观察结果，循环往复。权限层负责在动作执行前进行沙箱隔离或审批。
怎么跑起来：从 README 能确认的部分
README 没有给出安装命令或启动步骤，这本身就是一个信号：它更像一个教学仓库，而不是一个开箱即用的工具。你能确认的只有：它是 Python 项目，license 是 MIT，默认分支是 main，首页是 learn.shareai.run。没有 release 记录，也没有版本号。如果你想运行它，需要自己 clone 仓库、阅读源码、按项目内的说明补齐依赖。这一点和 Claude Code 本身不同，后者是一个商业产品，有完整的 CLI 和配置体系。learn-claude-code 的定位是让你读代码、改代码、理解 harness 的每一根线。
真正的局限：它不提供智能，也不提供安全
最大的局限是它明确不做什么。它不训练模型，也不内置任何模型能力。你得自己接入一个 LLM，比如 Claude、GPT 或 Gemini，才能让这个 harness 动起来。第二个局限是权限层。README 提到了沙箱隔离和审批流程，但没有说明默认实现是什么。这意味着你可能需要自己补上安全边界，否则一个能执行 shell 命令的 agent 在真实环境里是危险的。第三个局限是它没有提到持久化、多用户、日志审计这些生产级功能。如果你需要一个能直接部署给团队用的工具，它不是。它是教材，不是产品。
和主流 agent 框架的本质区别：重模型还是重流程
主流 agent 框架，比如 LangChain 或 AutoGen，倾向于用节点图、链式调用、工具注册表来编排 LLM。learn-claude-code 的作者认为这些是「过度工程化、脆弱、程序化的规则管道」，是「grandiose pretensions 的 shell 脚本」。它的替代方案是极简的 harness：只提供工具、知识、观察、动作和权限，把推理完全交给模型。这个区别很关键：前者把智能放在代码里，后者把智能放在模型里。实际效果取决于模型的能力。如果模型足够强，极简 harness 可能更透明、更可控；如果模型不够强，复杂的编排可能能弥补一些缺陷，但作者显然认为那是错误的方向。
维护与升级成本：MIT 许可下的自由与风险
repository 没有被归档，但最近 push 时间未知，也没有任何 release。这意味着它可能处于活跃开发中，也可能已经停滞，你无法从现有材料确认。MIT 许可给了你很大的自由：可以修改、分发、商用，但没有任何保证。如果你决定基于它构建自己的 harness，你需要自己维护与模型 API 的适配，因为模型接口变化很快。另外，README 提供了英文、中文、日文三种语言版本，说明它面向国际读者，但中文版是否与英文版同步更新，也无法从现有信息确认。
编辑结论
适合两类人：想理解 harness 工程细节的开发者，以及需要快速搭建一个可控、透明、可审计的编码 agent 原型的团队。不适合指望开箱即用、自带模型能力或完整生态的人。它的定位是教学与最小可用，而非生产级产品。在采用前，你需要先确认自己能否接受它依赖外部模型 API、缺少内置持久化与权限管理，以及没有官方发布版本的事实。如果这些都能接受，它是最短路径上最诚实的一份教材。
社区笔记