136 lines
7.0 KiB
Markdown
136 lines
7.0 KiB
Markdown
# 03 Tool 事实边界：让模型看到必要信息，系统保留真相
|
||
|
||
这一篇只回答一个问题：**Tool 返回的数据应该由谁保管，模型究竟可以看到多少？**
|
||
|
||
## 1. 先看一个具体问题
|
||
|
||
Agent 查询支付日志，后端一次返回了几千行内容，其中包含重复堆栈、敏感字段和远超上下文窗口的正文。
|
||
|
||
直接把原始结果塞回模型会产生几个问题：
|
||
|
||
- 敏感数据进入模型上下文；
|
||
- 大结果挤占 Token，真正关键的证据反而被淹没；
|
||
- 模型后续引用经过裁剪的文本，系统无法证明它对应哪次真实调用；
|
||
- 若只保存裁剪结果，EvidenceGuard 又失去了独立验真的事实来源；
|
||
- 若把完整 raw 长期写入数据库，泄露面和存储成本都会扩大。
|
||
|
||
所以 Tool 设计的核心不是“怎样调用后端”，而是**谁拥有原始事实，以及不同消费者应该看到哪一层数据**。
|
||
|
||
## 2. 一次 Tool 调用的数据怎样变化
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
REQ["Typed Tool Request"] --> B["ToolBoundary<br/>权限、只读、预算、大小检查"]
|
||
B --> RAW["Backend Raw Result"]
|
||
RAW --> P["Tool-specific Projector"]
|
||
P --> C["Canonical Invocation<br/>短期保存 request、raw、agent_result 和状态"]
|
||
C --> CV["Control View<br/>供 Harness 判断状态和进展"]
|
||
C --> MO["Model Observation<br/>供 Agent 推理的白名单内容"]
|
||
C --> EG["EvidenceGuard<br/>按当前 Run 独立验真"]
|
||
B -.-> AU["Durable Audit<br/>长期只留有界元数据"]
|
||
```
|
||
|
||
第一次阅读只需区分三份内容：
|
||
|
||
- **Canonical Invocation**：系统在当前 Run 内短期保管的完整调用真相。
|
||
- **Control View**：Harness 用来判断状态、scope 和证据数量的控制字段。
|
||
- **Model Observation**：模型真正看到的安全、有限内容。
|
||
|
||
## 3. ToolBoundary：所有 Tool 的统一入口
|
||
|
||
RAG、日志和 MySQL 后端完全不同，但它们都必须遵守相同的不变量：
|
||
|
||
1. Run 仍然 active，调用 ID 与当前 Run 匹配；
|
||
2. Tool 已授权，请求声明和实际行为保持只读；
|
||
3. 调用前预算允许，结果大小没有越界；
|
||
4. canonical 状态只能从 `PROJECTING` 进入 `READY` 或 `ERROR`；
|
||
5. 长期 Audit 不保存完整请求和 raw response。
|
||
|
||
如果每个 Adapter 自己实现这些规则，三种 Tool 很快会出现不同的错误码、预算顺序和存储行为。ToolBoundary 集中处理共同规则，Adapter 只处理业务协议。
|
||
|
||
ToolBoundary 不判断信息增益，也不判断某条日志是否支持根因。它只保证调用合法、状态可信、结果有界。
|
||
|
||
主要代码入口：`ToolBoundary`、`ToolCallRequestEnvelope`、`ToolBoundaryResult`、`ToolBoundaryErrorCode`。
|
||
|
||
## 4. Projector：把后端结果变成稳定事实
|
||
|
||
不同后端的 raw 数据不能直接成为 Agent 契约：
|
||
|
||
- RAG 需要限制证据数量和摘录长度，并保留文档身份；
|
||
- Logs 需要限制事件、聚合 pattern，明确实际时间范围和是否截断；
|
||
- MySQL 需要限制行、列、单元格和总 bytes，并保留查询 scope。
|
||
|
||
每种 Tool 使用自己的 `ToolResultProjector`。Projector 负责标准化和计算客观 `EvidenceStatus`，但它不调用模型，也不判断这些事实是否足以支持最终结论。
|
||
|
||
这是刻意保留的业务差异。强行做一个“万能 JSON Cleaner”，往往会丢掉每类证据真正需要的身份和范围信息。
|
||
|
||
## 5. Canonical Store：为什么要保留独立真相
|
||
|
||
Agent Observation 是为推理优化的，它会被裁剪和白名单投影，不能反过来充当验真依据。Canonical Store 保存当前调用的 request、raw、标准化 `agent_result`、状态和时间，使 EvidenceGuard 能绕开 Agent 上下文独立读取事实。
|
||
|
||
当前选择 Redis TTL，是因为完整调用记录：
|
||
|
||
- 只在当前 Run 的验证阶段需要；
|
||
- 可能包含敏感内容，不应永久保存；
|
||
- 需要按 `runId + tool_call_id` 快速定位；
|
||
- 容量必须有硬上限，读取不能自动续期。
|
||
|
||
raw 超限时选择失败，而不是悄悄截断。因为一旦截断，canonical record 就不再代表后端真实返回，后续验真会建立在不完整事实之上。
|
||
|
||
主要代码入口：`CanonicalInvocationStore`、`RedisCanonicalInvocationStore`、`CanonicalToolInvocation`、`CanonicalInvocationLimits`。
|
||
|
||
## 6. Model Observation：模型只拿完成任务所需的内容
|
||
|
||
即使 canonical `agent_result` 已经标准化，其中仍可能包含 Harness 控制字段。`ToolResultViewProjector` 会进一步拆成：
|
||
|
||
```text
|
||
Control View：status、evidence count、scope、截断状态等
|
||
Model Observation：有界证据正文、可读来源和下一步推理所需字段
|
||
```
|
||
|
||
模型不会看到 raw response、Redis key、预算阈值、重复指纹和完整 Harness 状态。这样既减少上下文噪声，也避免模型利用或复述内部控制信息。
|
||
|
||
## 7. MySQL 为什么还需要单独的只读沙箱
|
||
|
||
`readOnly=true` 只是请求声明，不能证明模型生成的 SQL 安全。MySQL Tool 在进入真实执行前还要经过：
|
||
|
||
- JSqlParser AST 解析；
|
||
- 单条 SELECT 和保守语法子集限制；
|
||
- 数据源、schema、table、column 精确 allowlist；
|
||
- 禁止投影通配符和元数据探测；
|
||
- 只读账号、timeout、LIMIT 与最大行数。
|
||
|
||
Validator 产生已经批准的 `MysqlQueryPlan`，Executor 只接受这个 plan，不重新信任原始字符串。这是纵深防御：任何一层都不能单独被当作完整授权。
|
||
|
||
## 8. 为什么短期真相和长期审计要分开
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
C["Canonical Store<br/>完整、敏感、短期"] -->|"用于"| V["当前 Run 验真"]
|
||
A["Durable Audit<br/>有界、元数据、长期"] -->|"用于"| O["排障、统计、成本对账"]
|
||
```
|
||
|
||
把两者合并会走向两个极端：要么长期复制所有敏感正文，要么为了安全只存元数据，导致当前 Run 无法验真。分开后，每种存储只承担自己的责任。
|
||
|
||
## 9. 为什么没有采用其他方案
|
||
|
||
| 方案 | 没有采用的原因 |
|
||
|---|---|
|
||
| raw 直接返回 Agent | 泄露、超限、噪声和无法独立验真 |
|
||
| 只保存 Agent Observation | 投影内容不是完整事实，Guard 会依赖模型看到的版本 |
|
||
| 完整 raw 永久写 MySQL | 扩大敏感数据暴露面和长期存储成本 |
|
||
| raw 超限后静默截断 | canonical truth 会变成不完整真相 |
|
||
| 所有 Tool 共用万能 Projector | 无法保持日志、RAG、表格各自的身份和 scope 语义 |
|
||
|
||
## 10. 先记住这些
|
||
|
||
1. ToolBoundary 统一执行规则，Adapter 处理具体后端。
|
||
2. Canonical Invocation 是系统真相，Model Observation 是模型视图。
|
||
3. Agent 看到的内容不能反过来成为 EvidenceGuard 的事实来源。
|
||
4. 完整真相短期保存，长期 Audit 只留有界元数据。
|
||
5. Tool 找到候选内容，不代表它支持最终根因。
|
||
|
||
下一篇：[04 验证与发布](04-验证与发布-让未经证明的结论无法越过出口.md)。
|
||
|
||
需要深入字段和存储取舍时，阅读[Tool 双视图专题](../Harness-Tool双视图-从原始结果到可验证证据.md)。
|