feat(harness): freeze aci tool contracts

2026-07-21 18:01:18 +08:00
parent 58c39107c5
commit 4274f3350b
32 changed files with 977 additions and 1 deletions
@@ -0,0 +1,32 @@
+# Brief: single-react-aci-tool-contracts
+
+## 背景
+
+旧 RAG 和日志 Tool 暴露检索/基础设施细节与不一致状态，MySQL Tool 尚无 Agent-facing 类型。Harness 实现前需要先冻结三类最小 ACI 契约。
+
+## 目标
+
+- 冻结 RAG、日志、MySQL 的 Request/Result JSON Schema。
+- 统一 `evidence_status`，并保持其与 invocation lifecycle 独立。
+- 统一使用框架 `tool_call_id`，禁止模型传入或 Harness 生成第二套 ID。
+- 冻结简短 Tool 名称/描述和 Mock 日志来源边界。
+- 用三个独立契约测试锁定行为。
+
+## 范围
+
+- 新增 `com.superbiz.agent.harness.tool.contract` 值对象、枚举和描述常量。
+- 复用阶段 0 的 `InvocationStatus` 与 `EvidenceStatus`。
+- 验证 JSON、不可变集合、描述泄漏和新旧边界。
+
+## 非目标
+
+- 不切换旧 RAG/日志运行方法或 Chat/AIOps 注册。
+- 不实现投影、Redis store、真实日志适配器或 MySQL 执行。
+- 不修改 Controller/SSE 或公开协议。
+
+## 元数据
+
+- 分档：standard
+- 接口影响：L2 前置内部契约；当前运行行为无变化
+- 关联 Issue：ISS-014 阶段 1
+- 关联 OpenSpec：`openspec/changes/single-react-aci-tool-contracts`