Skip to content

32-harness-and-eval-runtime.md

Latest commit

 

History

History
153 lines (100 loc) · 6.53 KB

32-harness-and-eval-runtime.md

File metadata and controls

153 lines (100 loc) · 6.53 KB

32. Harness 与 Eval Runtime

所属专题簇：内部运行与评测控制

建议前读：22. CLI Structured IO、Control Protocol 与 Transports

建议后读：24. GrowthBook、Analytics 与 Feature Control 或 21. 记忆系统：CLAUDE.md、Session Memory 与 Agent Memory

研究问题

Claude Code 源码里到底有没有一个 harness 子系统？如果没有，为什么 harness 这个词会在多个地方反复出现？

一句话结论

当前快照里没有一个显式的 src/harness/ 模块，但确实存在一层分散的 harness / eval runtime 语义：它负责宿主侧提示协议、内部运行路径、memory 目录预置、feature override 和内部实验入口。

这篇讲什么

这一章不把 harness 当成一个目录来讲，而是把它当成一个横切概念来研究：Claude Code 假设自己运行在某种“宿主或评测环境”里，而这一假设被编码进多个模块。

如果你不看源码，只看这一章，应该记住什么

  • 仓库里没有独立 harness/ 子系统。
  • 但 harness 在源码里不是偶然词汇，而是稳定出现的宿主运行概念。
  • 它主要出现在 hints 协议、内部路径权限、memory 目录保证、GrowthBook eval override 和 ablation baseline 入口里。

Claude Code 在这里想解决什么

一旦 Claude Code 不只是本地 REPL，而是还要支持：

  • 被宿主程序接管
  • 在评测环境里稳定运行
  • 为内部实验提供可重复配置
  • 在受控目录和内部产物上减少模型摩擦

那么系统就需要一层“不是用户直接看到、但运行时真实存在”的控制面。当前源码里的 harness 基本就是在指这层东西。

源码依据

Mermaid 图：Harness 横切位置图

flowchart TD
    A["Harness / Eval Runtime"] --> B["claudeCodeHints\n宿主侧提示协议"]
    A --> C["permissions internal paths\n内部路径特判"]
    A --> D["memdir provisioning\nmemory 目录已存在假设"]
    A --> E["GrowthBook env overrides\n评测可重复性控制"]
    A --> F["CLI ablation baseline\n内部实验入口"]
    A --> G["structured IO / host runtime\n外部宿主接管"]
Loading

证据一：hints 协议明确把 harness 当宿主

src/utils/claudeCodeHints.ts 顶部注释写得非常直接：

  • CLI 和 SDK 可以在工具输出中发 <claude-code-hint />
  • harness 会扫描这些标签
  • harness 会在输出进入模型前把标签剥掉
  • 它会把安装提示展示给用户

这里的重点是：提示标签不是给模型看的，而是给宿主运行层看的。这已经很接近“外部控制平面”的定义。

证据二：权限系统里存在 internal harness paths

src/utils/permissions/filesystem.ts 中直接有一条注释：

  • Allow reads from internal harness paths

并明确举了：

  • session-memory
  • plans
  • tool-results

这说明系统把某些内部产物目录视为 harness-controlled 空间，因此在权限逻辑里会有专门例外。

证据三：memory 目录被假设由 harness 预先保证

src/memdir/memdir.ts 多处出现：

  • Harness guarantees the directory exists
  • prompt 会直接告诉模型“目录已经存在，不要再 mkdir 或检查”

这说明 memory 子系统依赖一个更外层的运行保证：模型不需要花 token 去探测目录状态，因为 harness 已经准备好了运行环境。

证据四：GrowthBook 支持 eval harness override

src/services/analytics/growthbook.ts 中多处提到：

  • eval harnesses
  • CLAUDE_INTERNAL_FC_OVERRIDES
  • deterministic feature flag configuration

这说明内部评测环境需要绕过远程评估和磁盘缓存，确保某次评测在特定 feature 组合下可重复。这是非常典型的 eval harness 需求。

证据五：CLI 入口有 ablation baseline 支持

src/entrypoints/cli.tsx 顶部就有：

  • Harness-science L0 ablation baseline
  • 一组通过环境变量强制关闭复杂能力的逻辑

这说明 Claude Code 的 CLI 入口本身已经被用作内部实验和消融研究的控制点，而不是只面向普通用户启动。

它和普通用户可见路径有什么关系

对普通用户来说，真正可见的是：

  • REPL
  • slash commands
  • tools
  • remote / bridge

而 harness 更像这些能力的“背后宿主层”：

  • 处理 machine-readable side channel
  • 对内部目录和产物提供特殊语义
  • 为评测和内部实验提供确定性控制

所以它不应该和 commands/ 或 tools/ 一样被理解成用户功能面。

统一判断

如果把这些证据放在一起看，比较合理的解释是：

  • Claude Code 里没有单独的 harness 目录
  • 但存在一层稳定的 harness / eval runtime 假设
  • 这层负责连接宿主、评测、内部路径和实验控制

因此它更像一种横切运行环境，而不是一个单文件夹模块。

你真正应该记住的点

  • “没有 src/harness/” 不等于 “没有 harness 概念”。
  • harness 在这里主要是宿主控制和评测运行语义。
  • 它最适合被当作研究主题，而不是普通用户文档主题。

延伸阅读