learn-claude-code 精读：Agent Harness 工程 17 讲

快照：2026-08-14社区项目 · MIT

🎯 这篇笔记解决什么

你之前读过前几章就搁置了。这篇笔记的目标不是复述教程，而是让你在不重读 17 章的情况下拿到全部结论：核心命题是什么、每章真正新增了哪一个机制、哪些设计原则可以迁移到自己的项目、哪些地方是教学简化不能直接抄进生产。文末给出按时间预算的补读路径。

⚠️ 证据边界

本文基于 2026-08-14 克隆的仓库快照（最新提交 eb4307f，2026-08-12，feat/course-v22-refresh），阅读对象是根目录 s01–s17 的中文 README 与代码规模统计。仓库更新频繁，章节编号与实现细节可能变化。

另需说明：这是 shareAI-lab 的社区教学项目，不是 Anthropic 官方文档，也不是 Claude Code 的源码。它是对一个闭源 harness 的教学式重构——用可运行的 Python 复现同类机制，并非逐行还原。凡本文写"Claude Code 如何如何"的地方，都是作者的观察与主张，不是官方实现说明。

一、项目是什么

维度	事实
仓库	`shareAI-lab/learn-claude-code`，MIT 许可
主题	Agent Harness 工程——不是训练模型，而是造模型工作的环境
主线	根目录 `s01_agent_loop` → `s17_goal_loop`，17 章递进
每章结构	`README.md`（英文正本）+ `README.zh.md` / `README.ja.md` + 独立可运行的 `code.py` + `images/` SVG 图
代码规模	17 章合计约 12,000 行 Python；最小 s01 为 137 行，最大 s15 集成运行时 3,061 行、s13 团队运行时 1,794 行
依赖	只有 `anthropic`、`python-dotenv`、`pyyaml` 三个包，无框架
其他目录	`agents/`+`docs/`（旧 12 章过渡版）、`skills/`（s07 用的 4 个技能）、`web/`（课程生成的 Web 平台）、`tests/`
配套产品	Kode Agent CLI（`npm i -g @shareai-lab/kode`）、Kode Agent SDK；姊妹教程 claw0（常驻式 harness）

旧 12 章与新 17 章章节号不一致，不要混用：旧 s03 = 新 s05（TodoWrite），旧 s09–s12 全部合并进新 s13（Agent Teams）；新增的是 s03 Permission、s04 Hooks、s09 Memory、s12 Cron、s14 MCP、s15 集成、s16 Workflow、s17 Goal Loop。

二、核心命题：Agency 来自模型，Harness 只是载具

这是整个仓库的立论，也是最值得先记住的一段（以下为作者主张，非中立事实）：

Agency——感知、推理、行动的能力——来自模型训练，不是来自外部代码的编排。 但能干活的 agent 产品，模型和 harness 缺一不可。模型是驾驶者，harness 是载具。

作者用 DQN（2013 Atari）、OpenAI Five（2019 Dota 2）、AlphaStar（2019 星际 II）、腾讯绝悟（2019 王者荣耀）到 2024—2025 的编程 LLM 做论据：每一代"agent"的智能都长在权重里，环境只提供行动空间。由此推出两个定义：

text

Agent 产品 = 模型（LLM） + Harness（操作环境）

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

    Tools        文件读写、Shell、网络、数据库、浏览器
    Knowledge    产品文档、领域资料、API 规范、风格指南
    Observation  git diff、错误日志、浏览器状态、传感器数据
    Action       CLI 命令、API 调用、UI 交互
    Permissions  沙箱隔离、审批流程、信任边界

配套的是一段相当尖锐的批评：把 LLM 调用用 if-else、节点图、硬编码路由串起来的拖拽式"AI Agent 平台"，被作者称为**"提示词水管工"**——"有着宏大妄想的 shell 脚本"、"GOFAI 喷了一层 LLM 的漆"。

💡 笔者判断

这个二分法（模型出智能、harness 出能力边界）作为工程指导原则是成立且有用的：它把工程投入从"用代码模拟决策"扭向"把环境造好"，直接决定了后面 17 章都在做减法而不是加法。

但作为绝对论断需要打折。编排层不是只有"死板路由"一种形态——s16 自己就承认，流程形状固定时把编排写进代码是更优解；s17 的独立判断器也是典型的"代码替模型把关"。作者反对的其实是"用编排替代推理"，不是"编排本身"。读的时候把它当成工程重心的排序，而不是非黑即白的技术站队。

作者选 Claude Code 作教学标本的理由同样是一句减法："它没有试图成为 agent 本身"——不强加僵化工作流、不用决策树替模型判断，只给工具、知识、上下文管理和权限边界，然后让开。

三、17 章唯一不变的东西：那个循环

全书只有一段代码从头到尾没变过。s01 建立它，s02–s17 全部是在它周围挂机制：

python

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

只有两个信号：stop_reason == "tool_use" 就执行并回喂，否则退出。模型决定做什么，harness 只负责执行并把结果变成下一条消息。

这也是全书最重要的阅读线索——每一章的正确问法是："这一章往循环的哪个位置插了什么？循环本身动了没有？"绝大多数章节的答案是：循环没动。

四、17 个机制速览

先看全表，再看下一节的分层解读。

章	机制	一句话内核
s01	Agent Loop	`while True` + `stop_reason`，30 行跑通最小 harness
s02	Tool Use	加工具 = `TOOLS` 加一条 + `TOOL_HANDLERS` 加一行，循环不动
s03	Permission	硬拒绝表 → 规则匹配 → 用户审批，三道闸门插在执行前
s04	Hooks	四个事件（UserPromptSubmit / PreToolUse / PostToolUse / Stop）把扩展挂在循环外
s05	TodoWrite	先列计划再动手；连续 3 轮不更新计划就注入 reminder
s06	Subagent	子任务用全新 `messages[]`，只把最终文本作为一条 tool_result 返回
s07	Skill Loading	system prompt 只放技能目录，`load_skill(name)` 才展开正文
s08	Context Compact	四步压缩：转存大结果 → 归档旧消息 → 占位旧结果 → 最后才摘要
s09	Memory	一个记忆一个文件 + 索引；召回先选后读，写入要过持久性检查
s10	Task System	任务落盘为 `.tasks/*.json`，`blockedBy` 依赖图 + `owner` 认领
s11	Background Tasks	显式 `run_in_background`，先回占位结果，后续轮次收 `<task_notification>`
s12	Cron Scheduler	五段式 cron 到点入队，Agent 空闲时才交付；至少一次语义
s13	Agent Teams	持久队友 + 文件收件箱 + 原子认领 + 任务绑定 worktree + 类型化协议
s14	MCP Plugin	连接即发现，`mcp__{server}__{tool}` 命名，权限由宿主策略决定
s15	Integrated Harness	25 个内置工具、全部机制归到同一个循环
s16	Workflow Runtime	编排形状固定时写进代码，journal 记录每步，可断点续跑
s17	Goal Loop	模型"想停"不等于"做完"，独立判断器决定是否再来一轮

五、分层解读：每章真正教了什么

5.1 让 Agent 能动手（s01–s04）

s02 的关键不是"多了 4 个工具"，而是循环里只改了一行：run_bash() 换成 TOOL_HANDLERS[block.name]() 查表分发。工具从此是数据，不是控制流。

s03 三道闸门的顺序有讲究：硬拒绝表（rm -rf /、sudo、mkfs…）→ 上下文相关规则（写工作区外、破坏性命令）→ 命中规则才暂停问用户；三道都不命中直接放行。作者自己标注：这张 DENY_LIST 是字符串匹配，"说明权限闸门的位置，不能视为完整的安全边界"。

s04 是全书结构上最关键的一章。它没有新增任何能力，只是把 s03 的 check_permission() 从循环体里移到 hook 注册表上。此后每一章的扩展都往 hook 上挂，循环再没膨胀过。四个事件的返回值语义值得记：PreToolUse 返回非 None → 阻止本次工具执行；Stop 返回非 None → 强制循环继续（这正是 s17 Goal Loop 的接入点）。

5.2 做复杂任务（s05–s08）

s05 TodoWrite 的洞察是一句话：它不增加任何执行能力，只增加规划能力。对话越长，工具结果越多，system prompt 的影响力被稀释，10 步重构做到第 3 步就开始即兴发挥——计划落在对话里，是对注意力衰减的对抗。约束也很具体：一次最多 20 项、只能有一个 in_progress、解析不用 eval。

s06 Subagent 隔离的是消息，不是进程。父子共享同一个 WORKDIR，文件写入互相可见；子 agent 没有 task 工具（本章只允许一层委派），共享同一套权限与 hooks，最多 30 轮，只把最终文本返回父对话。

s08 是整本书工程含量最高的一章，四步压缩按"信息损失 × 调用成本"排序：

步骤	触发	做什么	代价
1. `tool_result_budget`	单批工具结果 > 200,000 字符	超过 30,000 字符的结果写入 `.task_outputs/`，上下文只留路径 + 前 2,000 字符	无 API 调用，可完整恢复
2. `snip_compact`	消息 > 50 条	全量写入 `.transcripts/`，只保留最初 3 条 + 最近 47 条	无 API 调用，可从归档恢复
3. `micro_compact`	—	最近 3 条 tool_result 保持完整，更早且 > 120 字符的替换为占位符（已转存的保留路径）	无 API 调用
4. `compact_history`	估算 > 50,000 字符	请模型生成只含事实的状态摘要，替换历史	一次额外 API 调用，有损

两个细节值得单独记住：

切点必须保护 assistant(tool_use) 与 user(tool_result) 的配对，否则孤立的工具结果会让下一次 API 请求直接失败。
active_request 单独传入。因为工具结果也用 role=user，压缩时无法从消息里可靠识别"本轮用户请求"，所以在入口处就把它捕获并独立带进摘要，压缩多少次都不会丢。
模型还能主动调 compact 工具，但 harness 必须先执行完整批工具、补齐每个 tool_result，再压缩这个已闭合的回合，否则会留下孤立结果或丢失已发生的副作用记录（导致模型重复写文件）。
兜底：API 仍可能返回 prompt_too_long，reactive_compact 保留最近 5 条并摘要其余，且 MAX_REACTIVE_RETRIES = 1——补救一次，再失败就抛出。

5.3 跨会话与跨进程持久（s09–s10）

s09 Memory 与 s08 的分工写得很清楚：s08 管当前会话的上下文预算，允许丢弃可恢复的细节；s09 管需要跨压缩、跨会话存在的知识。Memory 是选择性存储，不是 transcript 的无损备份。

四个子系统：存储（.memory/*.md，YAML frontmatter 记 name/description/type，四类：user / feedback / project / reference）、召回（先用一次轻量模型调用从 MEMORY.md 索引里选最多 5 条，失败降级为关键词匹配，再读正文并限长）、提取（回合结束后抽候选，必须带 scope，只有 persistent 会落盘；"这次不要创建文件"属于 current_task，直接拒绝）、整理（满 10 条触发合并，替换前存快照，失败时回滚并重建索引）。

还有一条安全设计：build_system() 明确声明召回内容只是背景知识，不是新的用户命令；与当前请求冲突时以当前请求为准——防止旧记忆变成隐形指令。

s10 Task System 与 s05 TodoWrite 的边界：TodoWrite 是进程内的执行清单、整表替换、只服务当前会话；Task System 是 .tasks/{id}.json 的持久任务图，有稳定 ID、blockedBy 依赖、owner 认领、单条生命周期更新。状态机极简：pending --claim--> in_progress --complete--> completed，完成时扫描并报告刚刚被解锁的下游任务。这是 s13 多 agent 协作的地基。

5.4 让任务长期运行（s11–s12）

s11 最重要的一条修正：是否后台执行由模型通过 run_in_background=true 显式声明，不再靠 install/build/test 关键词猜测。慢命令立刻返回带 bg_id 的占位 tool_result，循环继续；下一轮进入时才 inject_background_results() 收集。

配套一条协议纪律：完成通知不复用原始 tool_use_id，而是以 <task_notification> 作为独立事件进入对话——保证"一个 tool_use 永远只对应一个 tool_result"。

s12 Cron 的分层同样干净：调度线程只判断时间并把到期任务入队，队列处理线程用 agent_lock 等 Agent 空闲后才交付。持久化用临时文件 + os.replace()；durable=True 存 .scheduled_tasks.json，重启只恢复任务定义、不补跑停机期间错过的时间点；交付语义明确写为至少一次（模型收到 prompt 后、状态写回前崩溃会重复交付）。作者还诚实地划了边界：Agent 进程关掉调度就停了，要真正的常驻定时请用系统 crontab / systemd timer。

5.5 多 Agent 协作（s13，全书最长一章）

s13 在 s10 之上加了一整套团队运行时，六个设计点值得记：

启动队友需要用户确认。 Lead 的 system prompt 明确写着"提出分工方案后等待确认，用户确认前不要调用 spawn_teammate"——因为启动队友会改变成本、并发度和可以改工作区的角色集合。
队友是持久执行单元，不是 s06 那种一次性子 agent。 队友在 WORK → IDLE → WORK 之间循环、跨任务保留上下文、能双向通信，直到收到关机请求。
通信走文件收件箱（.mailboxes/<name>.jsonl），不共享 messages[]。 否则一个队友的工具结果会污染另一个队友的推理上下文。而且 check_inbox 不是模型工具——消息的到达与消费属于运行时，模型只处理已经投递进上下文的事件。Lead 启动队友后直接结束当前轮次，不做轮询。
result 和 idle_notification 是两个事件。 前者回答"这项任务产出了什么"，后者回答"这个队友能不能继续接活"，一句含糊的"完成了"表达不了两种状态。
发现与认领必须分开，认领必须原子。 scan_unclaimed_tasks() 只拿快照，所有权变更全部收进 claim_task()，由 task_store_lock() 同时取进程内锁与文件锁，写入走临时文件 + 原子替换。多个队友能同时看见同一候选，但只有一个能推进到 in_progress。
worktree 由任务绑定，且移除权保留给宿主。 Task.worktree 是可选字段，认领时把解析出的 cwd 写进 assignment，该队友所有文件/Shell 工具都用这个目录；没认领任务的队友不能使用工作区工具，绑定损坏时认领直接失败、不回退到仓库目录。create_worktree 只给 Lead；remove_worktree() 不暴露给模型，且拒绝清理 pending / in-progress 绑定与本轮仍在使用的 lease。

类型化协议是另一个亮点：关机和计划审批不靠猜测自由文本意图，而用 request_id + type + status 的结构化消息。计划闸门直接落在工具分发层——状态为 required/pending/rejected 时，队友可以读文件、写计划，但 bash/write_file/edit_file 一律拒绝。认领或释放任务会改变 work version，使旧审批失效。

作者反复强调：worktree 只分开 Git 工作目录和分支，不是安全沙箱；Shell 命令仍能访问父进程有权访问的一切。

5.6 接外部能力与集成（s07 / s14 / s15）

s14 MCP 里最该记的是权限那一节：MCP server 可以自报 readOnlyHint / destructiveHint，但这些信息来自 server，不能作为授权依据。宿主维护自己的 MCP_HOST_POLICY，未配置的外部工具默认需要用户确认——哪怕 description 写着 readOnly。命名上用 mcp__{server}__{tool}，并且规范化后要检查冲突（docs.one/get.version 与 docs_one/get_version 不能悄悄映射到同一个名字）和 64 字符上限。工具参数错误被捕获成错误 tool_result 让模型下轮修正，不让脚本退出。注意：本章的 server 是进程内 mock，真实 transport 不在教程范围内。

s15 是"归位图"而不是新机制：25 个内置工具、assemble_tool_pool() 每轮把内置工具与已连接 MCP 工具组装到一起，压缩管线、memory、skills、cron、后台、团队全部挂回同一个 while True。这一章最有价值的是那张**"组件在循环中的位置"**表——它把前 14 章的每个机制精确定位到"LLM 调用前 / 工具执行前 / 工具执行后 / 停止时"。另外新增了错误恢复层：429 指数退避、529 退避并可切 fallback 模型、max_tokens 先提额再要求续写、prompt too long 触发 reactive compact。

一个容易混淆的点，s15 特意澄清：工具列表里的 task 是一次性隔离 subagent，跟 Task System（create_task/claim_task…）不是一回事；两层计划也同时存在——todo_write 防单 agent 漂移，task graph 支撑团队协作。

5.7 编排与收口（s16 / s17）

s16 Workflow Runtime 是对"模型逐轮决定"的一次有意让步：流程形状事先已知时（比如多维度代码审查 → 逐条验证 → 合并去重 → 按严重度排序），把编排写进宿主代码更好，因为要的是并行、稳定结构和可恢复。

模型只提供已注册 workflow 的名称、参数和可选的 resume_from_run_id，不能提交可执行代码或元数据——脚本来自宿主 registry，不来自模型。
编排原语：agent() / parallel()（等齐屏障）/ pipeline()（每个 item 独立走完各阶段，不等齐）/ phase() / log() / workflow()（只支持一层嵌套）。
结构化输出：agent({schema}) 要求子 agent 只返回匹配 schema 的 JSON，不合规重试一次再失败——"工具参数不能全信"的反向版本。
journal 续跑：每个 agent() 结果按 调用内容（类型 + 标签 + prompt + schema）的稳定哈希 记进 <runId>.journal.jsonl。key 绝不能用"第几个完成"这类计数器，否则 parallel/pipeline 的完成顺序不确定会导致缓存错位。续跑时没改过的调用直接命中缓存（demo 里显示 agents=0 tokens=0）。
中间结果留在脚本变量里，不进对话历史。

s17 Goal Loop 修正了一个从 s01 就存在的默认假设：模型不再调用工具，只说明"这一轮想停"，不证明"整件事做完了"。/goal 注册一个会话级 Stop hook，在真正 return 之前跑一次独立判断器：

判断器与干活模型分开，且没有工具——不能自己读文件或重跑测试，只能依据对话里已经出现的内容判断，返回 {ok, reason, impossible}。
因此主模型的 system prompt 被要求：跑完验证命令后要把命令和结果明确写回对话，让判断器可查。作者明说：Goal Loop 不是测试框架，它只判断"验证结果是否已经出现在工作记录里"。
未达成时把理由直接追加进同一份 messages[] 并 continue——没有单独的续跑队列。
后台任务未结束时返回 defer，不调用判断器（关键结果还没回到对话，此时判断没意义）。
出口有两道：主循环全局 max_turns + Stop hook 连续阻止次数上限。达到上限时交还控制权，但绝不把目标伪装成完成，也不自动清除目标；判断器调用失败时同样处理。
好的完成条件要写清三件事：结束状态、验证方式、限制条件。例：/goal 完成登录模块迁移，直到 pytest tests/auth 退出码为 0，并且没有修改 tests/auth 之外的测试文件。

六、提炼：12 条可迁移的设计原则

这一节是笔者从 17 章反复出现的模式中抽出来的，不是原文的章节标题，但它们才是这本教程真正的可复用资产。

循环是不变量。 新能力要么变成一个工具，要么变成一个 hook，要么变成循环外的一次注入——不要改循环。判断一个 agent 项目健康与否，看它的主循环还能不能一眼读完。
能力扩展走数据，不走控制流。 加工具 = 加一条定义 + 一行 handler；接外部服务 = 连接后动态组装工具池。
降级要按"成本 × 信息损失"排序。 先做免费且可恢复的（落盘、裁剪、占位），最后才做花钱且有损的（模型摘要）。这条在任何资源受限系统里都成立。
显式优于猜测。 是否后台执行由参数声明，不靠关键词猜；控制类消息带 type 和 request_id，不靠解析自由文本意图。
权限判断永远在宿主侧。 外部系统（MCP server）的自述不能作为授权依据；默认拒绝，白名单放行。
破坏性操作不给模型。 remove_worktree() 保留为宿主函数，需要人另行确认——能力越强，越要把不可逆动作留在人手里。
协议不变量要硬保。 一个 tool_use 恰好对应一个 tool_result；压缩的切点必须保护调用与结果的配对；异步完成通知另起事件类型而非复用 ID。
共享状态的所有权变更必须原子。 发现（可以并发、可以过期）与认领（必须加锁、必须校验）分开，是所有多 worker 系统的通用解法。
回滚路径要和写入路径一起写。 记忆整理前存快照、任务写入用临时文件 + 原子替换、cron 持久化失败就恢复原状态——教程在这一点上比大多数"agent 教学项目"认真。
旧上下文不是新指令。 召回的记忆、归档的摘要都要显式降级为"背景知识"，冲突时以当前请求为准。
执行与评判分离。 干活的模型和判断"是否达成"的模型分开，判断器无工具、只读对话，并强制主模型把证据写回对话。
自动机制必须有出口，且失败时不能谎报成功。 到达轮数上限就交还控制权、保留目标；判断器挂了就停止续跑并上报错误。

七、教学实现与生产实现的差距（照抄前必读）

教程本身对这些边界基本都做了标注，这里集中列出，避免你把示例代码当成可直接上线的基础设施：

位置	教学实现	生产需要什么
s03 权限	`DENY_LIST` 字符串匹配	真正的沙箱 / 容器隔离；字符串匹配可被轻易绕过
s08 压缩	用字符数估算上下文	真实 token 计数；阈值需按模型窗口重算
s09 记忆整理	满 10 条即触发合并	按数据规模决定时机，并处理多进程并发改写
s11 后台	进程组清理"不是沙箱"	另建 session 的进程仍会逃逸，需要外部资源治理
s12 定时	Agent 进程关掉调度就停；至少一次交付	crontab / systemd timer / 外部调度；下游需幂等
s13 worktree	只分开 Git 工作目录与分支	不等于安全边界，Shell 仍可访问父进程可达资源
s14 MCP	进程内 mock server	真实 transport、连接生命周期、超时与鉴权
s16 workflow	单机 journal + 文件锁	分布式运行时的并发续跑与产物一致性

八、按时间预算的补读路径

你已经读过前几章，下面按投入产出排序。

⏱️ 只有 30 分钟

读 s04（Hooks） + s08（Context Compact）。s04 决定整个 harness 的可扩展形状，s08 是全书工程密度最高、最难自己想出来的一章。其余章节靠本文第四、五节的摘要即可。

2 小时（推荐主线）： s04 → s05 → s08 → s10 → s13 → s17。这条线覆盖"扩展点 → 规划 → 上下文 → 持久任务 → 多 agent → 目标收口"，是 harness 工程的骨架。s06/s07/s11/s12/s14 属于单点机制，摘要够用；s15 建议只看那张"组件在循环中的位置"表。

要动手跑： 只需 pip install -r requirements.txt + .env 填 ANTHROPIC_API_KEY / MODEL_ID。

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code && pip install -r requirements.txt
cp .env.example .env      # 填 ANTHROPIC_API_KEY 与 MODEL_ID

python s01_agent_loop/code.py          # 起点：一个循环 + bash
python s08_context_compact/code.py     # 看 .transcripts/ 与 .task_outputs/ 的实际产物
python s13_agent_teams/code.py         # 看 .tasks/ .mailboxes/ .worktrees/ 三个目录如何联动
python s16_workflow_runtime/code.py demo    # 确定性数据观察事件流
python s16_workflow_runtime/code.py resume  # 全部命中 journal 缓存：agents=0 tokens=0

⚠️ s01–s02 会直接执行模型生成的 shell 命令，权限闸门要到 s03 才有。在临时目录里跑。

九、笔者结论与待验证

值得读的理由： 市面上大量"手写 Agent"教程止步于 s01 那 30 行循环，这个仓库真正有价值的是 s08 之后——上下文压缩的降级顺序、原子认领、类型化协议、journal 续跑、判断与执行分离，这些是把 demo 变成能长期运行系统的关键，而且几乎每处都标注了自己的简化边界。它教的其实不是 Claude Code，是"长时运行的 agent 系统该怎么设计"。

需要保留的判断：

第二节那个"agency 全部来自模型"的强论断是立场性主张，s16/s17 自身就构成部分反例。取其工程重心，不必照单全收。
仓库是社区对闭源实现的教学重构，章节机制与 Claude Code 真实内部实现的对应关系无法从本仓库自证。
主线在快速演进（旧 12 章 → 新 17 章，最新提交为 course-v22 刷新），本文的章节编号有随时失效的风险。

待验证事项：

各章 code.py 是否真能在当前 SDK 版本下跑通（本次只读文档与代码规模，未实际执行）。
s16 journal 的稳定哈希在 prompt 含时间戳等易变内容时的缓存命中率。
s09 记忆召回那次"轻量模型调用"在真实使用中的成本与误选率。
与 Anthropic 官方 Effective harnesses for long-running agents 的主张做交叉比对——两者在压缩、目标收口上的取舍是否一致。

🔺 Anthropic

learn-claude-code 精读：Agent Harness 工程 17 讲

一、项目是什么

二、核心命题：Agency 来自模型，Harness 只是载具

三、17 章唯一不变的东西：那个循环

四、17 个机制速览

五、分层解读：每章真正教了什么

5.1 让 Agent 能动手（s01–s04）

5.2 做复杂任务（s05–s08）

5.3 跨会话与跨进程持久（s09–s10）

5.4 让任务长期运行（s11–s12）

5.5 多 Agent 协作（s13，全书最长一章）

5.6 接外部能力与集成（s07 / s14 / s15）

5.7 编排与收口（s16 / s17）

六、提炼：12 条可迁移的设计原则

七、教学实现与生产实现的差距（照抄前必读）

八、按时间预算的补读路径

九、笔者结论与待验证

延伸阅读

learn-claude-code 精读：Agent Harness 工程 17 讲 ​

一、项目是什么 ​

二、核心命题：Agency 来自模型，Harness 只是载具 ​

三、17 章唯一不变的东西：那个循环 ​

四、17 个机制速览 ​

五、分层解读：每章真正教了什么 ​

5.1 让 Agent 能动手（s01–s04） ​

5.2 做复杂任务（s05–s08） ​

5.3 跨会话与跨进程持久（s09–s10） ​

5.4 让任务长期运行（s11–s12） ​

5.5 多 Agent 协作（s13，全书最长一章） ​

5.6 接外部能力与集成（s07 / s14 / s15） ​

5.7 编排与收口（s16 / s17） ​

六、提炼：12 条可迁移的设计原则 ​

七、教学实现与生产实现的差距（照抄前必读） ​

八、按时间预算的补读路径 ​

九、笔者结论与待验证 ​

延伸阅读 ​

learn-claude-code 精读：Agent Harness 工程 17 讲

一、项目是什么

二、核心命题：Agency 来自模型，Harness 只是载具

三、17 章唯一不变的东西：那个循环

四、17 个机制速览

五、分层解读：每章真正教了什么

5.1 让 Agent 能动手（s01–s04）

5.2 做复杂任务（s05–s08）

5.3 跨会话与跨进程持久（s09–s10）

5.4 让任务长期运行（s11–s12）

5.5 多 Agent 协作（s13，全书最长一章）

5.6 接外部能力与集成（s07 / s14 / s15）

5.7 编排与收口（s16 / s17）

六、提炼：12 条可迁移的设计原则

七、教学实现与生产实现的差距（照抄前必读）

八、按时间预算的补读路径

九、笔者结论与待验证

延伸阅读