Tool Audit · workflow

tool-contract-end-to-end-audit

21-tool-contract-end-to-end-audit.md

🔧

P0 source: codex-sessions created: 2026-06-13

◉

WHAT IS THIS

定位

Agent tool 契约端到端审计。它从后端 tool schema 出发，一直核对到 agent discover、skill allowlist、capability registry、确认链路、UI 展示和文档。

它比 →#01 更窄：只处理 agent tool 这一条链路。

⚡

TRIGGERS

触发场景

▸新增 tool 后，agent 找不到或不会调用。

▸Tool 已发布，但 skill 没声明 tool_names。

▸写工具 risk/sideEffect 不正确，绕过或误触确认。

▸Tool 返回图片、表格、SSE 事件，但 UI 没展示。

▸Tool docs、skill docs、schema endpoint 和 runtime 行为不一致。

↹

INPUT & OUTPUT

输入 / 产出

↘ INPUT

Tool backend schema endpoint。
Tool name、domain、riskLevel、sideEffectLevel。
Agent discoverTools 代码。
Skill allowlist 和 agent skill_ids。
Capability definitions。
UI 消息渲染/SSE/progress 代码。
Tool docs 和开发规范。

↗ OUTPUT

Tool chain matrix。
缺失或冲突的 schema/skill/capability/UI/docs 项。
修复 patch。
Contract tests、discover tests、UI rendering tests。
Tool docs 更新。

🪜

STEPS

编排步骤

1
拉取 backend schema
确认 endpoint、tool name、input schema、output schema、risk、sideEffect、description。
2
检查 agent discover
确认 tool 是否进入 domain raw tools、read/write pools、allowlist 和 prompt context。
3
检查 skill 绑定
核对 agent skill_ids、skill tool_names、本地 skill 文件、DB skill file。
4
检查 capability registry
核对 capability name、required_inputs、execution mode、high risk confirmation、target agent。
5
检查返回协议
图片 Markdown、tables、JSON、SSE progress、tool summary 是否被保留到 UI。
6
检查 docs
后端 tool docs、agent skill docs、文档站、README 对工具能力和限制一致。
7
补测试
至少覆盖 schema discover、allowlist、write/read 分流、返回协议展示。
8
运行端到端 smoke
用真实或 fixture tool call 验证从用户输入到 UI 输出。

⚙

AGENT ROLES

Agent 分工

⚙

Schema Agent

读取 backend schema。

⚙

Discover Agent

核对 agent tool loading。

⚙

Skill Agent

核对 skill allowlist。

⚙

Capability Agent

核对 routing 和 confirmation。

⚙

UI Agent

核对 SSE、Markdown、progress 展示。

⚙

Docs Agent

同步规范和文档站。

⚙

Verifier Agent

跑 tests 和 smoke。

✓

ACCEPTANCE GATE

验收 gate

✓Tool schema 可从当前 backend endpoint 拉取。
✓Skill allowlist 包含目标 tool。
✓Read/write 分流和 sideEffectLevel 正确。
✓高风险写工具必须有确认链路。
✓Tool 返回的关键内容不被 LLM 或 UI 丢失。
✓Docs 能指导后续开发者新增同类 tool。
✓Matrix 无 P0 unresolved 项。

⊘

FAILURE HANDLING

失败处理

⊘

如果 schema endpoint 不可用，先修 backend 发布或文档，不在 agent 侧硬编码。

⊘

如果 UI 不支持返回协议，先明确降级展示，不让 LLM 自行改写丢内容。

⤳

如果能力来自 DB drift，转 →#20。

⌘

TEMPLATE

Tool chain matrix 模板

TEMPLATE

| Layer | Expected | Actual | Status | Evidence |
| --- | --- | --- | --- | --- |
| Backend schema | | | | |
| Discover | | | | |
| Skill allowlist | | | | |
| Capability | | | | |
| Confirmation | | | | |
| UI rendering | | | | |
| Docs | | | | |