5.2 KiB
Context
ISS-014 是一次 L4 Chat 重构的总设计来源，但实施被拆成 11 个必须串行归档的 OpenSpec changes。阶段 0 不切换公开协议或 Agent 运行链，只创建后续阶段复用的类型化契约、安全前置、失败语义和 focused baseline。
现有代码已经具备 runId Trace、工具调用审计、no-evidence 精确引用、Verifier/Composer fallback 和模块化 RAG，但这些能力分散在 ChatService、Hook、ThreadLocal、Tool 和 JSON 字符串中。Spring AI Alibaba 已提供 ToolInterceptor、结构化输出类型、工具执行超时、调用限额 Hook 和 ReactAgent.interrupt；Spring AI 底层 retry 默认最多 10 次，不能直接满足 ISS-014 的显式 Harness 重试矩阵。
Goals / Non-Goals
Goals:
- 生成后续阶段可直接复用的 Java contract types 和枚举，不实现新 Agent 执行链。
- 冻结 Tool ID、双状态、Draft、Knowledge Answer、Fallback、previous turn、SSE、重试和取消语义。
- 冻结 MySQL fail-closed 允许子集和安全前置。
- 移除仓库脚本和主配置中的明文凭据并建立改造前 focused baseline。
- 保证 ISS-014、OpenSpec、devflow 术语和 11 个阶段门禁一致。
Non-Goals:
- 不接入 Harness、Diagnosis Agent、EvidenceGuard 或 SemanticGuard 运行时。
- 不修改 Controller 协议、旧 ChatService 行为、Redis invocation store 或数据库表。
- 不实现 RAG/日志/MySQL Tool 投影。
- 不运行完整 live E2E。
Decisions
Contract types are reusable runtime inputs
阶段 0 创建位于 com.superbiz.agent.harness.contract 的轻量 record/enum，而不是只写文档或引入 JSON Schema 引擎。后续 ReactAgent outputType、Harness validator、持久化和 SSE DTO 可以直接复用这些类型，减少同一字段在多个阶段重复定义。
Framework Tool Call ID is canonical
tool_call_id 使用框架协议 ID。Harness 后续只校验非空、长度/字符安全和 Run 内唯一性，不生成第二套 ID。Redis Key 仍按 runId + toolCallId 隔离，真实性来自当前 Run 的 canonical record，而不是 ID 本身。
Invocation lifecycle and evidence outcome are orthogonal
InvocationStatus=PROJECTING/READY/ERROR 只描述调用与投影生命周期；EvidenceStatus=EVIDENCE_FOUND/NO_EVIDENCE/ERROR 描述结果语义。NO_EVIDENCE 只允许绑定 AnalysisKind=NEGATIVE_OBSERVATION，并必须保留查询范围和零匹配信息。
Diagnosis and knowledge answer contracts stay separate
Diagnosis Draft 使用 Analysis ID 与 Tool Call IDs；KNOWLEDGE_QUERY 使用 answer items，每项绑定一次 lookup 的 Tool Call ID 和返回的 document IDs。Harness 后续验证精确成员关系并确定性展开引用。首版 KNOWLEDGE_QUERY 不进入 SemanticGuard。
Safe published context belongs to Diagnosis Run
diagnosis_run 是 intent/release_outcome/published_result 的持久化真理源。只有同 Session 最近一个 DIAGNOSIS + SUCCESS 且 published result 非空的 Run 可形成 previous turn。Published result 只含用户查询、已发布结论、范围、限制和 RAG 文档元数据。
Cancellation is observable and layered
取消请求立即阻止新模型/Tool 轮次和最终 Draft 释放；框架中断、可控 Future/JDBC 取消尽力执行；已进入同步 ChatModel.call 的请求依靠底层 HTTP timeout。Run 终态通过原子状态转换保证唯一，晚到结果被丢弃，不宣称无法证明的底层硬取消。
Harness owns all retries
底层 SDK/HTTP/数据库 retry 必须关闭或压为一次 attempt。Intent Router 和 SemanticGuard 的第二次 attempt 由 Harness 显式执行并审计。阶段 0 只冻结矩阵；阶段 2 实现执行器和配置。
Stage boundaries are release boundaries
阶段 4 和 6A 仅内部运行；阶段 6B 在 Guards 已完成后原子切换公开入口。每个 change 必须 Archive 并 Git commit 后才能进入下一项，阶段 7 才执行统一 live E2E。
Risks / Trade-offs
- [Risk] Contract records过早绑定实现细节 → Mitigation：只包含跨阶段稳定字段，不包含 Redis、JPA 或框架对象。
- [Risk] Spring AI provider 对 Tool Call ID 行为不同 → Mitigation：阶段 3A 使用 Fake Model 和当前 DeepSeek 路径验证，缺失或重复时 fail closed。
- [Risk] 同步模型调用不能立即取消 → Mitigation：明确 layered semantics、HTTP timeout 和晚到结果丢弃，不把状态更新等同底层资源已终止。
- [Risk] 设计冻结测试增加维护成本 → Mitigation：只保留 focused serialization/validation tests，不复制完整 E2E。
- [Risk] 明文凭据可能已泄露 → Mitigation：仓库中移除并要求外部轮换；轮换证据记录在 acceptance。
Migration Plan
- 创建 contract types、契约测试和阶段台账，不接运行链。
- 清理查询脚本凭据，改为环境变量注入。
- 记录 focused baseline；Archive 本 change。
- 后续 10 个 change 逐步实现，并在各自 Archive 时同步对应运行 capability specs。
Rollback：阶段 0 没有公开行为变化；可删除新增 contract package/tests 并恢复文档。已经轮换的凭据不得回滚为旧值。
Open Questions
无。所有影响实现的用户决策已经在 decisions.md 中确认。