学习 Claude Code：智能体赋能（Harness）工程实战
从零开始，逐步构建一个类似 Claude Code 的智能体运行框架（Harness），掌握真正的智能体产品开发——模型负责智能，Harness 负责载体。
证据显示：README 中描述了权限控制（s03 Permission）和用户确认（s03 中“执行还是停止还是询问用户”），但未提供具体实现细节。数据流透明性：README 提到工具执行和结果追加，但未说明数据如何流动或是否记录。敏感数据处理：未提及 API 密钥处理，但 .env.example 存在，暗示密钥管理。依赖安全：requirements.txt 列出 anthropic、python-dotenv、pyyaml，未固定版本，未提及漏洞扫描。外部影响：工具执行可能产生外部影响，但未讨论安全边界。回滚：未提及任何回滚机制。来源归属：README 提到“shareAI-lab”和“Kode Agent CLI”，但未提供作者或维护者信息。扣分原因：权限和确认机制仅提及未实现细节；数据流和敏感数据处理缺乏具体说明；依赖未固定版本；外部影响未讨论；回滚缺失；来源归属不明确。
证据显示：README 中描述了多个会话（s01-s20）和旧版迁移，但未提供一致性保证。依赖可用性：requirements.txt 列出依赖，但未固定版本，可能影响可复现性。失败消息：README 提到错误恢复（s11），但未提供具体失败消息示例。扣分原因：自洽性因新旧版本并存而降低；依赖版本未固定；失败消息未具体化。
证据显示：README 面向 Harness 工程师，提供了学习路径和多种场景（如农业、酒店等）。能力边界：README 明确说明简化或省略了某些生产机制（如完整事件/Hook 总线、规则权限治理等）。触发精度：README 描述了会话和工具，但未详细说明触发条件。环境适配：README 提到 Web 平台和 CLI，但未说明系统要求。扣分原因：触发精度未详细说明；环境适配信息不足。
证据显示：README 提供了项目结构、安装说明（pip install、npm install）、示例（s01-s20 代码）、已知限制（范围部分）、MIT 许可证。命名稳定性：README 提到新旧版本并存，可能导致命名混乱。版本变更日志：未提供。维护责任：未明确。扣分原因：命名稳定性因新旧版本并存而降低；版本变更日志缺失；维护责任未明确。
证据显示：README 提供了可运行的代码示例（code.py），输出可用性较高。边际价值：作为学习项目，提供了从 0 到 1 的 Harness 构建教程，具有教育价值。成本效益：依赖较少，安装简单，成本低。扣分原因：输出可用性未经过实际运行验证；边际价值基于描述，未验证。
证据显示：README 中引用了外部链接（如 Nature、OpenAI 等）支持其论点，但未提供内部代码的验证。交叉来源：未提供其他来源的验证。事实与推断分离：README 中混合了事实（历史事件）和推断（Harness 工程原则）。扣分原因：声明可追溯性不足；交叉来源缺乏；事实与推断未明确分离。
- 依赖未固定版本，可能引入不兼容或安全风险。
- 权限和用户确认机制仅描述，未提供实现细节，实际安全性未知。
- 新旧版本并存可能导致命名混乱，影响使用。
- 未提供版本变更日志，维护责任不明确。
这个 Agent 能做什么，适合哪些场景？
本仓库是一个从0到1的智能体 Harness 工程教学项目，教你如何为智能体模型构建运行环境。它强调智能体（Agency）来自模型训练，而非外部代码编排；产品 = 模型 + Harness。项目以 20 个渐进式章节（s01-s20）系统讲解 Harness 的核心机制：从最基础的 Agent Loop（消息循环 + Bash 工具）出发，逐步添加工具调用、权限控制、Hook 扩展、任务规划、子智能体、技能加载、上下文压缩、记忆系统、错误恢复、任务系统、后台任务、定时触发、多智能体协作、工作树隔离、MCP 插件等。每个章节包含完整的 README 叙述、多语言翻译（中英日）、可运行的 code.py 和图表。项目遵循 MIT 协议，附带详细的学习路径、章节索引和快速入门指南，并提供了姊妹项目（Kode CLI、Kode SDK、claw0）作为知识延伸。适合希望深入理解智能体产品内部机制的开发者。
本仓库提供可运行的 Python 代码（code.py），实现一个极简但功能完整的智能体运行时：核心是一个 agent_loop 函数，循环调用 Anthropic API（client.messages.create）向模型发送消息并接收响应，通过检查 stop_reason 判断是否触发工具调用，并通过 TOOL_HANDLERS 字典分发到具体处理函数（如 Bash 工具）。每个章节在同一循环之上叠加一个 Harness 机制，例如权限规则（PermissionRule）、Hook（PreToolUse/PostToolUse）、TodoWrite 规划、子智能体（fresh messages）、技能清单（SkillManifest）、上下文压缩（snipCompact/microCompact）、记忆系统（selection/extraction/consolidation）、任务文件（TaskRecord/blockedBy）、后台线程、Cron 调度、多智能体 Mailbox（MessageBus）、工作树（WorktreeRecord）、MCP 插件等。用户可按照学习路径顺序运行 python s01_agent_loop/code.py 等命令，观察每个机制的运行效果。仓库还包含命令行工具 kode 和 Web 平台。
- 希望深入理解 Claude Code 等智能体产品内部机制、想自己动手构建 Harness 的工程师。
- 在 Ansible、Node-RED 等流程图中挣扎，想摒弃'胶水代码 + LLM'的做法、转向更本质的智能体开发的开发者。
- 需要为自己的应用集成智能体能力，但想先掌握基础原理、再使用 Kode SDK 等技术栈的开发团队。
- 教育工作者或学习者，需要一套循序渐进的、带可运行代码和图表的多语言教程来教授智能体开发。
- 探索将智能体从'用完即走'升级为'常驻助手'（如基于 claw0 的 heartbeat、cron 机制）的开发者。
这个 Agent 有哪些优点和局限？
- 从0到1逐步构建，每一课只新增一个 Harness 机制，学习曲线平缓且每个概念都可独立运行验证。
- 核心思想明确：Agency 来自模型，Harness 是载体，避免盲目堆砌流程编排，直击智能体产品本质。
- 提供完整的中英日三语教学文档，附带可运行代码和 SVG 图（复杂章节），适合系统性自学。
- 强依赖 Anthropic API（ANTHROPIC_API_KEY），模型提供商锁定，无法直接切换其他模型。
- 部分生产机制被刻意简化或省略（如完整的 Hook 事件、权限治理、会话生命周期），需要自行补充才能用于生产环境。
- 需要较好的 Python 基础和阅读大量英文技术文档的能力，完整走完20个章节有一定时间投入。
如何安装或部署这个 Agent？
- 克隆仓库：git clone https://github.com/shareAI-lab/learn-claude-code；2. 进入目录：cd learn-claude-code；3. 安装 Python 依赖：pip install -r requirements.txt；4. 配置环境变量：复制 .env.example 为 .env，并填入 ANTHROPIC_API_KEY（需要 Anthropic API 密钥）。
如何使用这个 Agent？
按顺序学习 20 个章节（s01 到 s20）。例如先运行基础章节：python s01_agent_loop/code.py，观察最核心的 Agent Loop + Bash 工具的运作；然后逐步运行更复杂的章节，如 python s08_context_compact/code.py 学习上下文压缩，最后运行 python s20_comprehensive/code.py 查看所有机制集成后的完整智能体。每个章节的 README.md 提供了详细叙述和代码解析。
这个 Agent 与同类方案有什么区别？
与 Claude Code 相比，本仓库提供的是教学用途的极简版实现，仅用于学习 Harness 机制，而非可直接替代的生产工具。与 OpenClaw 相比，学习仓库专注于'用完即走'的 Harness，而 OpenClaw 展示了通过 heartbeat 和 cron 实现'常驻助手'的另一种可能性，两者是姊妹项目。