记录 Harness 学习笔记，教程来自于github的learn-claude-code，教学版只是抽象入门，更多的东西可能还需要去看cc的源码
前言
- agent = llm + harmness，我们的重点是构建harness，llm由专业的模型训练团队负责。
Agent loop
- 最小的Agent loop就是发送初始信息（包含system prompt、user prompt、tools、messages）给llm，由llm判断是否需要获取进一步的信息（依赖tool-use）直到回答问题或完成任务，本质是调用LLM并循环实现其决策所需要的tool calls的结果，直到输出答案
- LLM是无状态的，所谓的有状态LLM，都是由客户端构建的，每次累计messages发送
Tool use/Function call
- 工具可以实现从主Agent loop分离，通过tool_handler来注册与分发机制来增删修改
- agent的tools调用机制是自己解析，可能是各种命令执行的函数或者代码体
- tools的基本三要素为：name、description、input_schema，其中input_schema为声明返回的tool call格式
- tool调用的权限控制:
- 绝对禁止：命中黑名单关键词的直接拒绝。
- 规则匹配：命中匹配规则的上报，由用户决策
Hooks
- 同一阶段的各种机制，可以统一抽象为hooks并自动调用，避免了主循环的不断膨胀。
- hooks可以根据执行阶段来注册和执行，有点类似于tool的注册于分发机制
- hooks的机制有点像拦截器，可以对提示词，上下文，调用过程等进行拦截与处理
任务系统
- Agent需要对复杂任务进行拆解，先规划再执行。
- harness侧可以注入特定提醒来提示Agent及时更新任务状态
- 任务需要持久化，逻辑层面需要有DAG依赖图来控制依赖关系
- 任务需要有状态流转，并需要根据状态来更新下游任务状态
子Agent并行执行
- 可并行执行的任务可以交给子Agent来执行
- 子Agent执行可以规避主Agent上下文窗口保障问题
- 父Agent可子Agent可共用代码，只是完全的任务不一致
- 子Agent不允许再派生孙agent
Skills注入
- 启动时扫描metadata，并注入系统提示词
- 使用时才读取所需要的skills全文
上下文压缩
- tool_result_budget：某一轮次的工具执行结果过大时直接落盘，messages注入落盘文件占位符
- snip_compact：消息大于50条时进行剪裁，只保留开头（用户提示词）和结尾（最新的工具调用），中间裁剪的过程持久化落盘
- micro_compact：对tool-use进行单独压缩，已落盘的跳过，保留最新的3条，其他没落盘的占位抹除
- compact_histroy：调用llm对messages理解，压缩为1条messages，messages中包含用户初始要求，以及对话摘要，决定与剩余工作
- reactive_compact：api返回提示词超长时触发，被动触发，进行一次压缩补救
- 注册compact，注入压缩工具，可以在每轮结束后提示llm主动触发压缩。
memory机制
- 格式与skills类似，机制也与skills类似
- skills是通用型描述，memory机制是针对于项目或者user维度的适配
- 存储：一个memory一个文件，新生成memory后会重建全局memory索引
- 召回：用户发起请求前，召回相关的memory供llm和关键词匹配逻辑选择
- 提取：本轮回答完成后，llm提取么memory并落盘，只有persistent才落
- 整理：达到一定数量后进行去重，合并
后台任务
- 时间敏感的阻塞型任务可以放到后台执行并进行占位
- 后续轮次主Agent主动收集任务执行结果成注入task_notification到messages中
- 任务是否在后台执行，由llm决定，提供run_in_bg参数
- BackgroundManeger来控制后台执行与生命周期，需要有互斥锁来保证线程安全
定时任务
- 可实现定时任务机制来重复执行某些任务
- 需要进行任务去重入队检查与任务补偿机制
- Agent loop的入口变为定时任务和用户输入两部分
Agent Teams
- 适用于大型复杂任务
- 由lead接受用户对话，创建任务并规划团队，完成后用户确认
- lead可以根据任务类型让队友提交执行计划、并审批计划；或者简单任务队友自己执行即可
- lead与队友的双向通信通过mailbox进行实现，跨机器的通信则需要通过网络实现，发送与收信都由运行时来控制，这也是harness的体现
- 队友状态有Work 和 IDLE和shutdown，并可以切换
- lead进行创建队友时，会初始化队友的taskid来认领任务，认领失败后不会启动队友
- 后续队友的任务运行时来帮队友认领（避免任务已经被别的队友领走了），认领需要原子级别
- result的上报和IDLE的状态上报是分开的，这是两码事
- 工作目录基于git worktree来实现，可以做到多Agent执行隔离的效果，worktree只能用户或者宿主来清除
- 关闭队友和审批需要结构化的消息协议，并需要对应的requestid来进行关联
- 计划的审批是严格且约束的，工具调用需要队友满足特定条件（比如已经有任务在执行）
MCP
- 支持外部工具调用的能力，mcp不多说了，没太多新东西
WorkFLow
- 本质还是ai工作流编排，不多说了，没太多新东西
Goal Loop
- 通过设定goal来实现Agent的任务完成状态检查与返工，从而达到持续闭环的效果，有点像最近新出的loop Engineering，这里不展开说，后面看下loop Engineering。
附录
本文作者：
yd0ng
本文链接： https://blog.yd0ng.top/2026/07/30/AI/Harness%E5%AD%A6%E4%B9%A0%E7%AC%94%E8%AE%B0/
版权声明： 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。转载请注明出处！
本文链接： https://blog.yd0ng.top/2026/07/30/AI/Harness%E5%AD%A6%E4%B9%A0%E7%AC%94%E8%AE%B0/
版权声明： 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。转载请注明出处！
