Crossharness：推理时工具调用方言翻译与能力恢复评估框架

Crossharness是一个开源的跨Harness工具调用翻译层，解决模型在训练时学习的工具调用方言与实际运行Harness不匹配的问题，通过中间表示（IR）实现方言转换，并提供分层归因评估来量化恢复效果。

• 原作者/维护者：SunnyDagupta
• 来源平台：GitHub
• 原始标题：crossharness
• 原始链接：https://github.com/SunnyDagupta/crossharness
• 发布时间：2026年6月12日
• 许可证：MIT

工具调用方言的不匹配实际上包含两个截然不同的层次，混淆这两个层次会掩盖真正未解决的问题：

这是已解决的问题。例如，使用<tool_call>文本内联格式 vs 结构化tool_use块；参数作为JSON对象 vs JSON编码字符串；缺失的调用ID等。LiteLLM等工具已经能够翻译提供商格式，vLLM的--tool-call-parser也能解析内联文本。

这是未解决的问题。例如，模型调用read_file({"path": ...})，但Harness暴露的是Read({"file_path": ...})。现有的适配器无法在不同Harness之间映射工具名称、模式和约定。

Crossharness的核心创新在于：它同时处理这两个层次，更重要的是，它的评估机制能够分层归因恢复效果，明确区分"线编码修复"和"表面映射修复"各自贡献了多少。

Crossharness采用中间表示（IR）作为翻译枢纽，将不同方言统一为通用格式：

模型文本（Hermes方言）          Harness API（Claude Code方言）
散文 + <tool_call>{...}</tool_call>    {"type":"tool_use","id":...,
      |                                "name":"Read","input":{...}}
      v                                ^
 [编码：解析内联文本，          [编码：输出结构化块，
  合成ID，规范化参数]            按ID关联]
      \                               /
       ToolCall IR {id, name, args, origin, raw, canonical}
              |
       [通过Harness配置进行表面映射]
       read_file -> fs.read -> Read
       path -> file_path

核心组件：

• crossharness/ir.py：IR定义，包含ToolCall、ToolResult和确定性ID合成
• crossharness/encodings/：线格式处理（Hermes内联文本、Anthropic结构化块）
• crossharness/surfaces.py：Harness配置，声明式工具表面表，支持别名
• crossharness/shim.py：组合层 + 会话账本，确保结果以模型自己的方言返回
• crossharness/executor.py：严格的Claude Code风格Harness，支持真实沙箱执行

Crossharness的评估设计是其最具价值的部分。它通过对比三种条件下的执行结果，精确量化翻译的恢复效果：

条件	write_haiku	config_extract	find_and_read	总计
无翻译	FAIL	FAIL	FAIL	0/3
仅语法翻译	PASS	FAIL	FAIL	1/3
完整Shim	PASS	PASS	PASS	3/3

解读：

• 无翻译：模型以其训练方言输出，Harness无法理解，全部失败
• 仅语法翻译（LiteLLM类能力）：恢复了T1，因为模型使用了正确的工具名称，只是线格式错误。但无法恢复T2和T3，因为模型退回到其训练的通用表面（read_file、path），而Harness期望的是Read/file_path——语法正确但Harness拒绝执行
• 完整Shim：表面映射层恢复了T2和T3，这是现有适配器无法提供的功能

这种分层归因能力让开发者能够准确判断：当模型在新Harness上表现不佳时，问题究竟出在哪里？是线编码不匹配，还是表面约定不同？

Crossharness在Agent技术栈中的定位非常清晰。每一层相邻技术都有标准，唯独"模型到Harness的推理时接口"缺乏标准：

层级	标准	解决的问题
Agent到工具	MCP	工具发现和执行
编辑器/客户端到Agent	ACP	会话、文件操作、权限
模型到Harness（训练时）	OpenEnv	针对标准化环境训练开放模型
模型到Harness（推理时）	无	训练于方言A的模型驱动期望方言B的Harness

OpenEnv从训练角度攻击耦合问题，而Crossharness是互补的推理时方案：无需重新训练，在边界处翻译，并量化单独翻译能恢复多少。如果恢复比例很小，这本身也是一个重要发现——意味着残差耦合是行为性的而非符号性的，此时训练时方法才是唯一解决方案。