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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-12T23:15:49.000Z
- 最近活动: 2026-06-12T23:20:45.349Z
- 热度: 157.9
- 关键词: 工具调用, AI Agent, 方言翻译, Harness适配, 模型互操作性, 评估框架, 开源
- 页面链接: https://www.zingnex.cn/forum/thread/crossharness
- Canonical: https://www.zingnex.cn/forum/thread/crossharness
- Markdown 来源: ingested_event

---

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

在AI Agent生态系统中，一个长期被忽视但至关重要的问题是：模型在训练时学习的工具调用方言（dialect）与实际运行环境的Harness所期望的方言往往不匹配。当OpenAI训练的模型被用于Claude Code环境，或者当开源模型被接入不同的Agent框架时，这种"方言鸿沟"会导致工具调用失败、性能下降，甚至完全无法工作。Crossharness项目正是为解决这一痛点而生。

## 原作者与来源

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

## 问题的本质：两层不匹配

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

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

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

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

## 技术架构：中间表示（IR）的核心作用

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上表现不佳时，问题究竟出在哪里？是线编码不匹配，还是表面约定不同？

## 与OpenEnv的互补关系

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

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

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

## 快速开始与Phase 2a扩展

**60秒演示**：
```bash
git clone <this repo> && cd crossharness && python3 demo.py
```

无需依赖、无需安装、无需网络、无需GPU，Python 3.9+即可运行。

演示展示了一个记录的Hermes格式模型回合如何跨越方言并真实执行：解析为IR、表面映射、以结构化`tool_use`块交付给严格的Claude Code方言Harness、在沙箱目录中执行、然后将`tool_result`翻译回模型能读取的`<tool_response>`文本。

**Phase 2a：实时模型测量**

项目已包含将演示表格转化为测量声明的机制。`phase2a/tasks.py`定义了24个种子化、程序化检查的文件操作任务。通过`fixtures/capture.py`捕获开放模型的实时输出，重放相同的三方评估，报告"模型X原始驱动Harness Y损失N分，通过Shim恢复M分"。

## 对Agent生态的意义

Crossharness的价值超越了技术实现本身。它揭示了一个被忽视但至关重要的问题：在AI Agent生态系统中，模型与Harness的耦合不仅仅是技术细节，而是影响整个系统可靠性的关键因素。

通过提供：
1. **标准化的翻译机制**：让任何模型能够驱动任何Harness
2. **精确的评估框架**：量化翻译的效果和局限
3. **分层的归因分析**：区分线编码问题和表面约定问题

Crossharness为Agent技术的互操作性铺平了道路。在一个模型和Harness快速迭代的生态中，这种解耦能力将成为基础设施成熟的重要标志。