3.4 KiB
3.4 KiB
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 AlibabaToolCallRequest.getToolCallId()；普通 Spring AIToolContext不保证包含该 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 侧旧凭据轮换仍是外部安全前置，不因本阶段契约完成而视为关闭。