44 lines
3.4 KiB
Markdown
44 lines
3.4 KiB
Markdown
## Why
|
||
|
||
现有 `lookup_knowledge` 和 `query_logs` 将检索实现、基础设施参数、审计数据和不一致的成功语义暴露给 Agent；新增 MySQL Tool 也缺少可复用的 Agent-facing 类型。进入 Harness 和投影实现前，需要先把三类 evidence Tool 的最小输入、稳定有界输出、状态语义与框架 Tool Call 引用冻结为代码契约，避免后续阶段继续依赖字符串和旧 DTO。
|
||
|
||
## What Changes
|
||
|
||
- 新增 RAG、日志和只读 MySQL 三类 Agent-facing Request/Result 契约，JSON 字段严格使用 ISS-014 已确认的 snake_case Schema。
|
||
- 三类结果统一复用 `EvidenceStatus`，并携带框架提供的 `tool_call_id`；契约代码不生成、替换或推导第二套调用 ID。
|
||
- 冻结 `InvocationStatus=PROJECTING/READY/ERROR` 与 `EvidenceStatus=EVIDENCE_FOUND/NO_EVIDENCE/ERROR` 的独立语义，并通过测试禁止混用。
|
||
- 冻结三类 Tool 的短名称与 ACI 描述，描述只说明用途、输入和禁用场景，不泄露 L0/L1、Milvus、CLS region/TopicId、连接、凭据、topK、limit、rerank 或审计实现。
|
||
- 冻结日志 `source_kind=MOCK` 及逻辑 Topic 边界，为后续真实适配器保留同一 Contract；本阶段不新增 CLS/MCP 适配器。
|
||
- 添加三类独立契约测试，覆盖序列化字段、不可变集合、状态与描述边界。
|
||
- 本阶段不修改旧 Tool 的执行签名、返回值或 Chat/AIOps 注册路径，不实现 ResultProjector、Harness invocation store、MySQL SQL 校验或数据库访问。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `aci-evidence-tool-contracts`: 定义 RAG、日志和 MySQL evidence Tool 的 Agent-facing ACI Schema、状态语义、框架调用引用和描述边界。
|
||
|
||
### Modified Capabilities
|
||
|
||
- None. 当前公开运行链路仍使用旧 Tool Contract；新契约将在后续 Harness/Tool 投影和 SSE 切换 change 中接入。
|
||
|
||
## Context Constraints
|
||
|
||
- `tool_call_id` 的真理源是 Spring AI Alibaba `ToolCallRequest.getToolCallId()`；普通 Spring AI `ToolContext` 不保证包含该 ID。
|
||
- `NO_EVIDENCE` 只表示当前查询范围没有匹配证据，只能支持 `NEGATIVE_OBSERVATION`，不能表达工具失败或系统健康。
|
||
- 生命周期 `status` 属于 canonical invocation，`evidence_status` 属于 Agent-facing 查询结果，两者不得互相替代。
|
||
- Agent 不可控制日志 region/TopicId/limit、RAG topK/filter 或 MySQL 连接与资源上限。
|
||
- Mock 日志必须显式保留 `source_kind=MOCK`，不得被后续 Harness 表述为生产实时事实。
|
||
|
||
## Interface Impact
|
||
|
||
- 等级：L2（内部接口，前置冻结）。本 change 新增未来 Harness 内部使用的 Agent-facing DTO 和描述常量，所有消费者均在 ISS-014 后续实施范围内。
|
||
- 当前运行中的旧 Tool 方法、Controller、ChatService 和 AiOpsService 不切换，因此本阶段没有对外可观察行为变化。
|
||
- 阶段 6B 切换公开 `/api/chat` 时属于独立的 L4 破坏性变更，必须使用该阶段自己的迁移和回滚规格。
|
||
|
||
## Risks
|
||
|
||
- 仅有 DTO 不能证明框架 ID 已贯穿执行；阶段 2/3 必须在 Alibaba `ToolInterceptor` 边界接收并校验 `ToolCallRequest.getToolCallId()`。
|
||
- 新旧 Contract 会短期并存；旧运行工具不得被误认为已符合新 ACI 输出，真正接入留给 RAG/日志投影和 MySQL Tool 阶段。
|
||
- Provider 侧旧凭据轮换仍是外部安全前置，不因本阶段契约完成而视为关闭。
|