281 lines
14 KiB
Markdown
281 lines
14 KiB
Markdown
# Harness Tool 双视图：从原始结果到可验证证据
|
||
|
||
**更新日期**：2026-07-29
|
||
**主题**：ToolBoundary、Canonical Invocation、Harness Control View 与 Agent Observation
|
||
**术语与状态**：[CONTEXT.md](CONTEXT.md) · [Harness生命周期与状态.md](Harness生命周期与状态.md)
|
||
**上位设计**：[Harness设计-非确定性Agent的确定性控制边界.md](Harness设计-非确定性Agent的确定性控制边界.md)
|
||
|
||
## 1. 要解决的不是 Tool 调用，而是 Tool 结果的所有权
|
||
|
||
Agent 调用 Tool 后，最直接的实现是把 backend 返回的 JSON 原样放进模型上下文。这在 Demo 中可以工作，但进入可验证的诊断系统后会出现一个根本矛盾：同一份结果需要同时服务推理、控制、验真和审计，而这些消费者需要的数据范围完全不同。
|
||
|
||
以日志查询为例：
|
||
|
||
- Agent 需要少量匹配事件、模式、实际时间范围和是否截断；
|
||
- Harness 需要返回数量、规范化 scope、重复身份和客观证据状态；
|
||
- EvidenceGuard 需要证明这份结果确实来自当前 Run 的某次 READY 调用；
|
||
- 审计需要 Tool 名、调用 ID、状态、耗时和字节数；
|
||
- 安全边界又要求密码、Token、主机、IP、SQL 字面量和无限日志正文不能进入模型或长期审计。
|
||
|
||
如果只保留一份 JSON，只能在两个错误方向中选择：要么信息过多导致泄露和上下文膨胀，要么信息过少导致后续无法验真。
|
||
|
||
因此这项设计的核心不是“增加一个 Redis Store”，而是重新定义 Tool 数据所有权：
|
||
|
||
> backend raw 属于 Harness；模型只能获得为推理目的生成的有界观察；长期审计只保留允许运营保存的元数据。
|
||
|
||
## 2. 三个消费者，三种数据责任
|
||
|
||
虽然实现中常称为“Tool 双视图”，完整的数据分层实际上包含三种用途：
|
||
|
||
| 数据形态 | 消费者 | 解决的问题 | 生命周期 |
|
||
|---|---|---|---|
|
||
| Canonical Invocation | ToolBoundary、EvidenceGuard、ProgressProjector | 这次 Tool 真实执行了什么、属于哪个 Run、能否引用 | Redis 短 TTL |
|
||
| Harness Control View / Agent Observation | Harness / Diagnosis Agent | 是否重复、是否为空、模型下一步需要看到什么 | 当前 Run / 模型上下文 |
|
||
| Durable Audit | Trace、运营排障 | 何时调用、状态、耗时、大小、关联 Step | MySQL 长期 metadata |
|
||
|
||
所谓“双视图”，特指 canonical 标准结果被进一步分成：
|
||
|
||
1. Harness 使用的 Control View；
|
||
2. 模型使用的 Agent Observation。
|
||
|
||
Durable Audit 是第三个持久化面，但它不是 Tool 内容视图，不参与推理或证据验真。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Typed Tool Request"] --> B["ToolBoundary"]
|
||
B --> C["Backend Raw Response"]
|
||
C --> D["Tool-specific Projector"]
|
||
D --> E["Canonical agent_result"]
|
||
|
||
B --> F["Redis Canonical Invocation<br/>request + raw + agent_result"]
|
||
E --> F
|
||
|
||
E --> G["Harness Control View<br/>count / status / scope"]
|
||
E --> H["Agent Observation<br/>白名单、有界、脱敏"]
|
||
|
||
B --> I["Durable Audit<br/>identity / status / latency / bytes"]
|
||
G --> J["重复检测、NO_GAIN、停止"]
|
||
H --> K["Diagnosis Agent Context"]
|
||
F --> L["EvidenceGuard / ProgressSnapshot"]
|
||
```
|
||
|
||
## 3. 为什么不能让 Agent Observation 充当真相源
|
||
|
||
Agent Observation 是为了控制上下文而生成的投影，它可能：
|
||
|
||
- 只保留前 N 条结果；
|
||
- 截断单条文本；
|
||
- 对敏感列和日志字段做脱敏；
|
||
- 把大量事件聚合成模式；
|
||
- 只暴露粗粒度相关度，不暴露检索轨迹和原始分数。
|
||
|
||
这意味着它适合帮助模型推理，却不适合作为“后台真实返回”的完整证明。如果 EvidenceGuard 反过来验证 Agent 自己收到的 observation，就相当于用被审查对象提供的摘要证明其自身真实性。
|
||
|
||
Canonical Invocation 解决的正是这个独立性问题。它以 exact `runId + tool_call_id` 建立记录，并保存：
|
||
|
||
```text
|
||
tool_call_id
|
||
run_id
|
||
tool_name
|
||
request
|
||
raw_response
|
||
agent_result
|
||
invocation status
|
||
evidence status
|
||
error code
|
||
started_at / completed_at
|
||
```
|
||
|
||
EvidenceGuard 不信任 Draft 中的引用，也不从模型历史反推 Tool 结果，而是重新按当前 Run 构造 key，读取 canonical record 并验证状态和投影内容。
|
||
|
||
## 4. ToolBoundary 为什么必须是统一入口
|
||
|
||
RAG、日志和 MySQL 的业务执行方式不同，但以下控制规则完全相同：
|
||
|
||
- Run 必须仍然 active；
|
||
- envelope 的 runId 必须等于当前 Run；
|
||
- `tool_call_id` 必须合法且不能重复；
|
||
- Tool 必须已授权并声明只读；
|
||
- 调用前必须预占 Tool 预算和 request bytes；
|
||
- raw response 和 agent result 必须分别检查容量；
|
||
- canonical 状态只能按合法路径迁移；
|
||
- 对 Agent 只返回稳定错误码；
|
||
- durable audit 失败不能改变已经得到的 Tool 结果。
|
||
|
||
如果把这些逻辑复制到三个 Adapter，任何新增 Tool 都可能漏掉其中一项。因此统一由 `ToolBoundary` 编排一次调用，具体 Adapter 只负责 typed request、backend 和 projector 的连接。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant I as Tool Interceptor
|
||
participant B as ToolBoundary
|
||
participant C as Harness Core
|
||
participant S as Canonical Store
|
||
participant T as Backend
|
||
participant P as Projector
|
||
participant A as Audit Sink
|
||
|
||
I->>B: RunContext + ToolCallRequestEnvelope
|
||
B->>B: run / id / authorization / readonly / JSON preflight
|
||
B->>C: reserve Tool call + request bytes
|
||
B->>S: begin PROJECTING
|
||
B->>T: execute typed request
|
||
T-->>B: raw response
|
||
B->>C: reserve raw bytes
|
||
B->>P: project raw response
|
||
P-->>B: bounded agent_result + evidence_status
|
||
B->>C: reserve projection bytes
|
||
B->>S: mark READY
|
||
B-->>I: ToolBoundaryResult
|
||
B-->>A: best-effort metadata audit
|
||
```
|
||
|
||
错误发生时，已经创建的 canonical record 会尽力迁移到 ERROR；如果连 Store 都不可用，则向上只返回 `STORE_ERROR` 等稳定码，不把 Redis 或 backend 异常正文交给模型。
|
||
|
||
## 5. 两套状态为什么不能合并
|
||
|
||
Tool 调用同时有两个正交维度：
|
||
|
||
| 维度 | 状态 | 回答的问题 |
|
||
|---|---|---|
|
||
| Invocation lifecycle | `PROJECTING / READY / ERROR` | 这次调用是否完成并形成了可引用记录 |
|
||
| Evidence semantics | `EVIDENCE_FOUND / NO_EVIDENCE / ERROR` | 客观结果中是否存在候选证据 |
|
||
|
||
例如日志查询成功返回 0 条：
|
||
|
||
```text
|
||
InvocationStatus = READY
|
||
EvidenceStatus = NO_EVIDENCE
|
||
```
|
||
|
||
它不是 `ERROR`。这条负向观察可以支持“在指定时间、服务和查询条件下没有匹配日志”，但不能支持“故障不存在”。
|
||
|
||
合法组合被类型约束为：
|
||
|
||
| InvocationStatus | EvidenceStatus | 是否允许引用 |
|
||
|---|---|---:|
|
||
| `PROJECTING` | `null` | 否 |
|
||
| `READY` | `EVIDENCE_FOUND` | 是 |
|
||
| `READY` | `NO_EVIDENCE` | 是，但只能作为限定范围负向观察 |
|
||
| `ERROR` | `ERROR` | 否 |
|
||
|
||
把两者合成一个 `SUCCESS / FAILED` 会丢失最重要的信息：技术成功但业务范围内没有证据。
|
||
|
||
## 6. 三类 Tool 如何投影
|
||
|
||
### 6.1 RAG
|
||
|
||
`RagResultProjector` 从 backend 结果中提取有界 evidence block，稳定文档身份，限制 excerpt 数量和长度，并兼容 `relevanceLevel / relevance_level` 后统一为 `relevance_level`。
|
||
|
||
这里有一个刻意保留的区分：
|
||
|
||
```text
|
||
evidence 非空 -> EVIDENCE_FOUND
|
||
relevance_level=REFERENCE -> 相关度一般
|
||
```
|
||
|
||
`EVIDENCE_FOUND` 只说明存在候选内容，`REFERENCE` 也不自动表示 `NO_GAIN`。内容是否推进当前诊断假设，需要模型结合上下文判断。
|
||
|
||
### 6.2 Logs
|
||
|
||
`QueryLogsResultProjector` 不只是截取前几条日志，它还会：
|
||
|
||
- 脱敏 password、token、secret、API key；
|
||
- 脱敏 pod、host、PID、IP 和 SQL literal；
|
||
- 去掉堆栈尾部噪声；
|
||
- 对数字做模式归一化并聚合重复事件；
|
||
- 对事件做跨范围采样，而不是只保留开头；
|
||
- 保存实际时间、topic、query scope 和截断标记。
|
||
|
||
如果 backend 执行成功且日志数组为空，投影结果是 READY + NO_EVIDENCE。backend 明确返回失败，才是 Tool 执行或投影错误。
|
||
|
||
### 6.3 MySQL
|
||
|
||
MySQL 在投影之前还有独立的只读安全链：`MysqlSqlValidator` 根据逻辑数据源、schema、table 和 column allowlist 生成 `MysqlQueryPlan`，`JdbcMysqlReadOnlyExecutor` 只执行该 Plan。
|
||
|
||
`MysqlResultProjector` 再负责：
|
||
|
||
- 限制最大行数、单元格长度和总 bytes；
|
||
- 保持 number、boolean 和 null 类型；
|
||
- 对 password、token、secret、credential 等敏感列强制脱敏；
|
||
- 结果缩减时标记 `truncated=true`。
|
||
|
||
Validator 负责“能不能执行”，Projector 负责“模型能看到什么”，两者不能合并。
|
||
|
||
## 7. Control View 与 Model Observation 的字段边界
|
||
|
||
| 字段 | Harness | Agent | 原因 |
|
||
|---|---:|---:|---|
|
||
| `tool_call_id` | 是 | 是 | 引用和上一轮评价都需要 |
|
||
| 实际 scope | 是 | 是 | Harness 去重；模型理解负向观察边界 |
|
||
| 有界 evidence/events/rows | 是 | 是 | 模型推理所需事实 |
|
||
| `evidence_status` | 是 | 是 | 区分候选证据、空结果和错误 |
|
||
| `relevance_level` | 是 | 是 | 给模型粗粒度检索语义 |
|
||
| `truncated` | 是 | 是 | 防止模型误以为结果完整 |
|
||
| `returned_count` | 是 | 否 | Harness 统计，不必消耗模型上下文 |
|
||
| normalized scope / duplicate identity | 是 | 否 | 内部控制实现 |
|
||
| 连续 NO_GAIN、阈值和剩余预算 | 是 | 否 | 防止模型围绕限制博弈 |
|
||
| raw response / 检索轨迹 / 原始分数 | 是 | 否 | 敏感且体积不可控 |
|
||
|
||
只有 Harness 必须改变模型行为时，才注入 `STOP_REQUIRED`、错误码或已检查范围等有限控制信息。
|
||
|
||
## 8. 存储决策：为什么是 Redis canonical + MySQL metadata
|
||
|
||
### 8.1 不把完整 raw 长期写 MySQL
|
||
|
||
完整 Tool 结果可能包含日志、SQL 查询结果和内部知识内容。长期保存会扩大泄露半径，也会让 JPA audit 成为第二个事实源。MySQL 只保存运营和对账需要的字段，可以长时间保留而不复制正文。
|
||
|
||
### 8.2 Canonical 读取不续期
|
||
|
||
Redis record 在创建时设置 TTL，读取或状态更新不恢复初始 TTL。原因是：如果一次历史查询就能续期，敏感 raw 可能因审计访问而永久存在。
|
||
|
||
状态更新保留当前剩余 TTL，代价是 read-TTL-write 存在小的并发窗口，但它比无界续期更符合数据治理目标。
|
||
|
||
### 8.3 raw 超限为什么不截断
|
||
|
||
raw 是内部事实。如果静默截断后仍标记 READY，系统无法区分“backend 只返回这些内容”和“Harness 丢掉了内容”。因此 raw 或完整 record 超限时调用进入 ERROR。
|
||
|
||
Agent projection 可以截断，因为它本来就是面向消费的摘要，但必须通过 `truncated=true` 明示不完整。
|
||
|
||
## 9. 真实问题如何改变设计
|
||
|
||
| 真实问题 | 暴露的错误假设 | 最终修正 |
|
||
|---|---|---|
|
||
| Tool raw 直接进入 Agent | backend 输出天然适合模型消费 | 增加 Tool-specific projector 和白名单 observation |
|
||
| Trace、raw、ContextPack、重复正文同时存在 | 多保存几份可以提高可观测性 | canonical、model view、metadata audit 明确分层 |
|
||
| Mock 日志 0 命中返回 `success=false` | 没数据等于调用失败 | 技术执行状态与 NO_EVIDENCE 分离 |
|
||
| RAG 的 `REFERENCE` 在投影中丢失 | 只要 evidence 非空就够了 | 保留 relevance_level，但不提升为根因证据 |
|
||
| 生产 ObjectMapper 未注册 Java Time 模块，Redis 全部 STORE_ERROR | 单元测试序列化环境等同生产 | 使用生产装配验证 canonical record，并增加 live E2E |
|
||
| backend 日志打印 raw/rewritten query | 排障信息可以直接进入普通日志 | 普通日志和 durable audit 只保留安全摘要 |
|
||
|
||
## 10. 代价与边界
|
||
|
||
这项设计不是免费的：
|
||
|
||
1. 每增加一种 Tool，都要同时定义 typed request/result、Adapter、Projector 和 EvidenceGuard 读取规则。
|
||
2. Redis 在 TTL 内成为证据校验依赖；不可用时系统应 fail closed，而不是相信 Draft。
|
||
3. Agent 看到的是有损投影，Projector 设计不当可能丢掉模型真正需要的诊断信号。
|
||
4. durable audit 不能替代 canonical replay；TTL 到期后只能解释调用元数据，无法恢复完整正文。
|
||
|
||
但这些成本换来了明确的责任：Backend 决定原始事实，Projector 决定模型可见范围，Canonical Store 决定短期验真事实，Audit 决定长期允许保存什么。
|
||
|
||
## 11. 如何验证
|
||
|
||
| 验证内容 | 代表性测试或证据 |
|
||
|---|---|
|
||
| Run mismatch、未授权、非只读、重复 ID、预算和超限 | `ToolBoundaryTest` |
|
||
| PROJECTING / READY / ERROR 和 TTL 行为 | `CanonicalInvocationStoreTest` |
|
||
| RAG evidence identity、relevance 和 bytes | `RagResultProjectorTest` |
|
||
| 日志脱敏、模式聚合、空结果和采样 | `QueryLogsResultProjectorTest` |
|
||
| MySQL 行列/敏感字段/容量边界 | `MysqlResultProjectorTest` |
|
||
| typed Tool contract 不漂移 | 三类 `*ToolContractTest` |
|
||
| 生产 Redis serializer 与 ObjectMapper | single-react cleanup live E2E |
|
||
|
||
单元测试只能证明数据变换和状态机；生产 Redis serializer、实际 Tool Calling ID 和 backend 返回格式仍必须通过 live E2E 验证。
|
||
|
||
## 12. 与后续机制的关系
|
||
|
||
Tool 双视图只解决“什么是可验证的 Tool 事实、模型允许看到什么”，并不解决：
|
||
|
||
- 这些事实是否支持最终结论：见[Harness证据安全链-从引用真实到结论可发布.md](Harness证据安全链-从引用真实到结论可发布.md)；
|
||
- Agent 是否应该继续查询：见[Harness信息增益停止-让无证据诊断正常收敛.md](Harness信息增益停止-让无证据诊断正常收敛.md)。
|