Hareness 的核心组件为Agent Loop 与Multi Agent 服务，可以分为5个部分：
-
上下文工程
- 标准化工具层（Tools + Hooks）
- 状态持久化
- 权限模型
- 可观测性和审计系统
Claude Code 本身是一个Harness Engineering 的实现。
我们结合 Claude Code 一次完整请求来讲整个流程。
用户输入进来，第一步是构建系统提示词。加载四层 CLAUDE.md 配置——从全局到项目、到本地覆盖、到子目录，层层叠加。同时注入自定义系统提示和记忆内容。第二步，解析用户输入——解析斜杠命令、 @ 文件引用，完成上下文注入，生成规范化的消息格式。第三步，持久化会话记录。第四步，组装初始化信息——工具列表、MCP 客户端、模型信息、命令、Agent 定义、技能列表，一次性注入。然后进入 Agent Loop。Claude 的工具按名称排序形成稳定前缀，可以利用kv Cache 避免重复计算并节约token；工具加载利用了渐进式披露的思想，首次只加载核心工具，其余工具利用ToolSearchTool进行按需发现。
Agent Loop 的核心是一个无限循环。每轮迭代先进行压缩Pipeline，四级严格顺序：第一级snip裁剪，释放的 token 数传递给后续级别；第二级Micro compact 把旧的工具结果替换成固定占位文本，覆盖 9 种工具类型；第三级 collapse 在读取视角上可恢复性折叠冗余内容，不修改实际消息，（它是模式匹配特定消息，不关心语义，保留原始内容只是为了当前路径探索失败，需要回溯或debug等需求）；第四级auto compact 调 LLM 做摘要压缩，根据上下文窗口阈值触发，优先走零 LLM 调用的内存压缩路径，失败才回退到 LLM 摘要（直接把对话历史中已经确认完成的任务、已过期的工具结果等信息，从内存里标记为”可压缩”，用简单的规则替换掉（比如”这部分内容已完成，不再需要”），不需要 LLM 参与）。四个级别之间有信息传递——前面释放的 token 数直接影响后面的阈值判断。
压缩完调用模型 API。底层是 HTTP POST 走 SSE 流式事件，模型边生成边返回。返回的流式事件被逐条消费：遇到可恢复错误不立即抛出，而是扣留起来等恢复流程走完；正常的消息实时推送给 UI；同时后台并发执行工具——模型还在生成第二个工具调用的时候，第一个已经在跑了。如果发生流式切换，先清理孤儿消息再重建执行器。最后还有一层错误兜底，处理模型切换重试、图片大小超限等情况。
模型响应完成后，先触发后处理钩子，不阻塞主流程。然后进入终止判断。如果有工具调用待执行，跳过判断直接去执行。如果没有，走完整的错误恢复体系：413 错误（上下文超限）分两步恢复——先排空折叠缓存重试，不行再做完整摘要压缩重试，再失败才报告用户；输出截断也是两步——先升级输出上限重试，还截断就注入提示让模型继续，最多三次，超过就放弃。Stop Hook 可以阻止终止，或者注入额外消息要求继续。还有 token 预算检查——500K 预算没用完就自动继续。正常完成就返回结果。
7种continue 重试路径：
| 路径 | 场景 | 做法 |
|---|---|---|
next_turn |
工具执行完成 | 正常下一轮 |
token_budget_continuation |
500K token 预算未耗尽 | 自动继续 |
max_output_tokens_escalate |
输出被截断 | 升级 max_tokens 从 8K→64K 重试 |
max_output_tokens_recovery |
升级后仍截断 | 注入提示让模型继续，最多3次 |
collapse_drain_retry |
413 上下文超限 | 排空折叠缓存重试 |
reactive_compact_retry |
排空折叠后仍 413 | 完整摘要压缩重试 |
stop_hook_blocking |
Stop Hook 要求继续 | 注入额外消息继续 |
如果有工具调用，进入工具执行阶段。工具先分区，分区内并发执行——只读工具并发跑、写入工具串行跑，在安全性和性能之间取平衡。每个工具走七步管道：格式校验、输入验证、执行前钩子（可批准、修改上下文）、权限检查（规则匹配→权限模式→AI 分类器三层递进）、实际执行（命令行还要包一层沙盒隔离）、执行后钩子（审计日志、输出修改等）、转成 API 格式。核心安全原则是：拒绝规则优先级最高——即使钩子批准了，配置里的拒绝规则仍然能阻止。同时异步生成工具使用摘要，用轻量模型，不阻塞下一轮。
第一层：规则匹配（零成本）
先查 settings.json 里有没有匹配的 allow/deny 规则。比如”允许读取 src/ 下所有文件”、”禁止删除 .git 目录”。命中了就直接放行或拒绝，不需要往下走。这一步过滤掉大部分调用。第二层：权限模式（零成本）
看当前处于什么模式。如果是bypassPermissions模式，所有操作自动放行；如果是plan模式，只允许只读操作；如果是default模式，需要继续往下判断。第三层：AI 分类器（有成本，调模型）
前两层都判断不了的，交给一个独立的分类模型（YOLO Classifier）。它不是主模型自己判断，而是一个专门的”看门人”模型，二次审查这个操作是否安全。这一步最慢、最贵，但最精准。
最后进入下一轮准备：处理队列中的命令、消费预取的记忆结果、发现新技能、刷新 MCP 工具、生成任务摘要、检查是否超过最大轮次。然后整体更新状态——把本轮的消息、模型回复、工具结果全部拼在一起，回到循环开头，开始下一轮。
整个设计有五个关键决策贯穿始终：用Async Generator让 UI 实时看到进度；所有状态集中在一个对象里整体替换，防止漏改；错误扣留策略防止中间态错误被误判为最终失败；工具在模型流式输出期间并发执行，减少等待延迟。95% 的时间正常循环，但剩下 5% 的错误恢复——七种重试路径、四种扣留条件、三次熔断限制。
四种扣留条件（遇到时不立即抛出错误，而是扣留等恢复）：
| 条件 | 含义 |
|---|---|
| collapse withheld | 上下文超限，等待折叠排空 |
| reactiveCompact withheld | 折叠排空失败，等待完整压缩 |
| media size error withheld | 图片/媒体过大，等待处理 |
| max_output_tokens withheld | 输出截断，等待升级重试 |
复制表格
三次熔断限制：
指 max_output_tokens_recovery 最多执行 3 次。源码里 MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3。连续 3 次恢复都失败（模型仍然截断），就不再重试，放弃并向用户报告错误。防止无限循环。