Claude Code 的
Harness 工程

什么是 Harness？

在 Claude Code 中，Harness（直译「线束」）是指包裹在 AI 模型外面的整个编排层。它不负责「思考」，而是负责「调度」——接收你的输入、调用模型、执行工具、检查权限、管理上下文窗口、处理错误。

整体架构

Harness 分为四个层次，从外到内依次是：

有两个入口：CLI 模式通过 main.tsx 启动终端交互，SDK 模式通过 QueryEngine 类提供 headless 调用。两者最终都进入同一个 queryLoop。

核心循环 — queryLoop

整个 Harness 的心脏是 query.ts 中的 queryLoop() 函数——一个 async function*（异步生成器），用 while(true) 驱动每一轮对话。

循环维护一个 State 对象，每轮迭代在顶部解构读取，在 continue 点整体替换：

let state: State = {
  messages,            // 消息历史
  toolUseContext,      // 工具执行上下文
  autoCompactTracking, // 压缩追踪
  turnCount,           // 轮次计数
  transition,          // 跳转控制
  ...
}

消息管道

消息在送到 Claude API 之前，要经过一条 6 级处理管道。这是 Harness 最精巧的部分——因为上下文窗口有限，必须在有限空间里装下最有价值的信息。

工具执行

Claude 模型输出 tool_use 块时，Harness 负责实际执行这些工具（读文件、写文件、跑命令等）。有两种执行模式：

// 模型流式返回 tool_use block 时
// 立即提交给执行器
for (const toolBlock of msgToolUseBlocks) {
  streamingToolExecutor.addTool(
    toolBlock, message
  )
}

每个工具执行前后，都会经过 Hook 拦截和权限检查（下面两节详述）。

Hook 生命周期

Hook 是 Harness 的扩展机制——在关键节点插入自定义逻辑，不修改核心代码。一共有 7 个生命周期钩子：

权限系统

每次工具调用前，Harness 通过 canUseTool() 回调检查权限。权限模式决定了检查的严格程度：

Auto 模式下有一个 yoloClassifier（分类器），根据工具类型和参数判断操作是否安全。比如读文件几乎总是安全的，但 rm -rf / 就需要拦截。

// 权限检查的调用链
canUseTool(toolName, toolInput)
  → checkPermissionMode(mode)
  → yoloClassifier(tool)  // auto 模式
  → showPromptUI()       // 需要确认时

Feature Gate

Claude Code 用 Bun 打包器的 feature() 函数做编译时功能开关。这不是运行时 if/else，而是在打包时直接删除代码（死代码消除）。

// 编译时决定：保留还是删除这段代码
const reactiveCompact =
  feature('REACTIVE_COMPACT')
    ? require('./reactiveCompact.js')
    : null

主要的 Feature Gate：

错误恢复

Harness 内建多重恢复策略，确保对话不会因为一次错误就中断：

设计哲学

从源码中可以提炼出 Claude Code Harness 的 5 个核心设计原则：