feat(harness): add chat application use case

2026-07-22 00:57:39 +08:00
parent ee0949d464
commit f8809cb7dd
56 changed files with 2815 additions and 6 deletions
@@ -41,3 +41,4 @@
 | 2026-07-21 | single-react-mysql-readonly-tool | Fail-closed read-only MySQL evidence Tool with AST allowlist, JDBC controls and bounded projection | Harness/MySQL security | ISS-014, MySQL, JSqlParser, allowlist, PreparedStatement, timeout, projection | openspec/changes/archive/2026-07-21-single-react-mysql-readonly-tool | archived |
 | 2026-07-21 | single-react-diagnosis-agent | Single internal Diagnosis ReactAgent with Harness-controlled model/tool loop, bounded context and typed Draft | Harness/Diagnosis Agent/ReAct | ISS-014, ReactAgent, DiagnosisDraft, PreviousTurn, ToolInterceptor, ModelInterceptor, budget | openspec/changes/archive/2026-07-21-single-react-diagnosis-agent | archived |
 | 2026-07-21 | single-react-evidence-semantic-guards | Deterministic evidence validation, isolated semantic review and fail-closed diagnosis release | Harness/EvidenceGuard/SemanticGuard/Release | ISS-014, EvidenceGuard, verified snapshot, SemanticGuard, repair, fallback, release policy | openspec/changes/archive/2026-07-21-single-react-evidence-semantic-guards | archived |
+| 2026-07-21 | single-react-chat-application-usecase | Internal Chat application use case with isolated routing, fixed executors and safe PreviousTurn | Harness/Chat application/Run persistence | ISS-014, Intent Router, PreviousTurn, PublishedResult, V012, observer, cancellation | openspec/changes/archive/2026-07-21-single-react-chat-application-usecase | archived |
@@ -0,0 +1,42 @@
+# Acceptance: single-react-chat-application-usecase
+
+## Result
+
+- Status: archived
+- OpenSpec tasks: 14/14 complete
+- Interface impact: L3 database/collaboration
+- Public protocol: unchanged
+
+## Static Verification
+
+- V012 migration、`DiagnosisRun` 和 `DiagnosisRunRepository` 对齐 `intent/release_outcome/published_result` 及安全 PreviousTurn filter。
+- 公开 Controller、前端和 endpoint diff 为空。
+- Router/System executor 未检出 Tool、ReactAgent、ThreadLocal 或手写循环。
+- `PublishedResult` 固定为 `user_query/published_conclusion/scope/limitations/source_documents`；序列化负向测试覆盖内部字段泄漏。
+
+## Script Verification
+
+- `mvn -q -DskipTests compile`：通过。
+- Stage 6A focused `ApplicationExecutorsTest,PublishedResultPersistenceTest,ChatApplicationUseCaseTest`：13 tests，通过。
+- Stage 2-5 与 6A regression selection：18 suites / 76 tests，0 failure/error/skipped。
+- `openspec validate single-react-chat-application-usecase --strict`：通过。
+
+## Browser or Manual Verification
+
+- Not applicable。阶段 6A 没有 UI 或公开入口变化。
+
+## Not Verified
+
+- 未运行真实 LLM、Redis、日志和 MySQL live E2E；按 ISS-014 串行门禁统一留到阶段 7。
+- V012 未在本阶段连接真实数据库执行；migration/entity/query 已由静态检查、focused persistence tests 和 compile 覆盖。
+
+## Remaining Work
+
+- 阶段 6B：唯一 `POST /api/chat` SSE 原子切换、旧 endpoint 删除和前端消费者迁移。
+- 阶段 7：旧链路清理、全局 spec 格式修复和最终 live E2E。
+
+## Archive
+
+- `.archive-ready`: created
+- OpenSpec archive: `openspec/changes/archive/2026-07-21-single-react-chat-application-usecase`
+- Main spec sync: `openspec/specs/single-react-chat-application-usecase/spec.md`
@@ -0,0 +1,31 @@
+# Brief: single-react-chat-application-usecase
+
+## Background
+
+阶段 2-5 已具备 RunContext、单一 Diagnosis Agent 和安全释放门禁，但没有统一应用用例拥有 Session/Run、意图路由、PreviousTurn、固定执行器和最终持久化，阶段 6B 因而无法只做协议切换。
+
+## Goal
+
+在不改变公开 Chat/SSE 行为的前提下，建立内部 `ChatApplicationUseCase`，统一三类意图、同一 Run 生命周期、安全 PreviousTurn 和 typed public content。
+
+## Scope
+
+- 无 Tool、无记忆、无 ReAct 的三分类 Intent Router。
+- SYSTEM_CHAT、KNOWLEDGE_QUERY、DIAGNOSIS 固定执行器。
+- Knowledge exact invocation/document reference validation。
+- 同 Session 最近安全 Diagnosis SUCCESS 的有界 PreviousTurn。
+- `diagnosis_run` V012 字段、JPA store 和安全 `PublishedResult`。
+- Protocol-neutral observer、Run control、终态持久化和 focused tests。
+
+## Non-goals
+
+- 不修改 Controller、`/api/chat`、`/api/chat_stream`、SSE schema 或前端消费者。
+- 不删除旧 ChatService、多 Agent、ThreadLocal 或旧 session storage。
+- 不运行真实模型、Redis、日志和 MySQL live E2E；统一留到阶段 7。
+
+## Metadata
+
+- Scale: complex
+- Interface impact: L3 database/collaboration
+- OpenSpec: `single-react-chat-application-usecase`
+- Parent issue: `ISS-014`
@@ -0,0 +1,117 @@
+# Decisions: single-react-chat-application-usecase
+
+## Discover Status
+
+- Checkpoint: Discover
+- Capability source: `sm-flow` + `grill-with-docs`；`codebase-retrieval`、LSP 和 GitNexus MCP 当前不可用，使用既有 GitNexus 结论、`rg` 引用核对和源码阅读降级。
+- Scale: complex。跨模型路由、三类执行器、Run/session 生命周期、数据库 migration、PreviousTurn 和阶段 6B consumer boundary。
+- `devflow/index.md` 命中阶段 0-5、session-run-trace-isolation、RAG contracts 和 release guards；无 ADR 冲突。
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | Chat Application Use Case 与 Controller、Harness、Agent 的职责边界是什么？ | evidence-driven | 已解决 |
+| Q2 | 路由 | Router 输入、输出和可重试失败范围是什么？ | evidence-driven | 已解决 |
+| Q3 | 路由 | Router 最终失败是否允许默认进入 Diagnosis？ | evidence-driven | 已解决 |
+| Q4 | 执行器 | 三种 intent 分别允许哪些模型和 Tool 行为？ | evidence-driven | 已解决 |
+| Q5 | Knowledge | 单次 RAG 调用如何验证模型引用且不公开 Tool Call ID？ | evidence-driven | 已解决 |
+| Q6 | PreviousTurn | 上一回合的真理源、筛选条件和截断边界是什么？ | evidence-driven | 已解决 |
+| Q7 | 生命周期 | 何时读取上一回合、创建当前 Run、记录 intent 和终态？ | evidence-driven | 已解决 |
+| Q8 | 持久化 | diagnosis_run 需要新增哪些字段，哪些内部内容禁止进入 published_result？ | evidence-driven | 已解决 |
+| Q9 | 6B 边界 | 如何让 Controller 切换时不重写应用用例？ | evidence-driven | 已解决 |
+| Q10 | 接口 | 数据库/内部接口影响等级和回滚要求是什么？ | evidence-driven | 已解决 |
+| Q11 | 验收 | 如何证明原始 Query、sessionId/runId 和失败终态一致传播？ | evidence-driven | 已解决 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| Controller 只负责协议；Application Use Case 拥有 session/run、routing、executor、persistence，Harness 拥有预算/取消/释放，Agent 拥有诊断语义。 | ISS-014 3、4.2、阶段 6A/6B | 已汇报 |
+| Router 输入只含 query/last_intent/last_user_query，输出只允许三枚举；无 Tool/记忆/ReAct。 | ISS-014 4.5 | 已汇报 |
+| timeout/transport/非法输出可重试一次；第二次失败返回安全入口错误，不进入 Diagnosis。 | ISS-014 重试策略、`HarnessRetryPolicies.intentRouter()` | 已汇报 |
+| SYSTEM_CHAT 无 Tool；KNOWLEDGE_QUERY 只调用一次 lookup；DIAGNOSIS 进入 Agent + Guards。 | ISS-014 4.5 | 已汇报 |
+| PreviousTurn 只来自同 Session 最近 `DIAGNOSIS + SUCCESS + published_result`，不使用 Redis 历史。 | ISS-014 4.6 | 已汇报 |
+| `PublishedResult`/`PreviousTurn` 已冻结为 query/conclusion/scope/limitations/source_documents，不含 Tool ID/raw/Draft/reason。 | 阶段 0 contracts、`PublishedResult`、`PreviousTurn` | 已汇报 |
+| 当前 `DiagnosisRun`/V011 尚无 intent/release_outcome/published_result，需要 V012 和 repository query。 | `DiagnosisRun.java`、`V011__add_session_run_isolation.sql` | 已汇报 |
+| 上一回合必须在保存当前 PENDING Run 前读取，否则 latest query 会命中当前请求。 | repository 当前 latest method + 生命周期顺序推导 | 已汇报 |
+| 6B 需要 metadata/status/cancel，6A 应提供 observer 和显式 RunContext，而不包含 SSE 类型。 | ISS-014 4.7、阶段 6B | 已汇报 |
+
+## User-interview
+
+- 无新增 user-interview。三类路由、数据库字段、PreviousTurn、失败语义、阶段边界和自动 Apply/Archive/commit 均由 ISS-014 与用户持续授权冻结。
+
+## Key Decisions
+
+- 在创建当前 Run 前读取 latest safe routing context 和 PreviousTurn，随后 `startRun -> persist RUNNING -> observer metadata -> route`。
+- Application output 使用 typed content union，Diagnosis success 转为无 Tool ID 的 public report view；Fallback output 不携带完整 snapshot。
+- Knowledge path 生成一次 direct canonical Tool Call ID（该路径没有框架 Tool Call），只调用 `lookup_knowledge`，严格验证 `KnowledgeAnswerDraft` 的 exact call ID 和 document subset，再移除 ID 发布。
+- 所有普通单轮模型调用复用阶段 5 的受控 `GuardModelCall`，从而共享 Core 模型/Token/timeout/cancel 边界；不引入新模型路由。
+- `PublishedResult` 仅在 Diagnosis SUCCESS 且 conclusion 非空时写入；Fallback/Failed/Cancelled/System/Knowledge 不生成 PreviousTurn 真理源。
+- 数据库变更使用 V012 可前向迁移；回滚为先停止新应用用例，再删除新索引/列，不影响 V011 既有字段。
+- 不创建 ADR：这些是 ISS-014 已冻结设计的落地，不是新的跨项目不可逆决策。
+
+## OpenSpec Backfill
+
+- 需进入 proposal/design/spec/tasks：路由隔离/重试、三执行器、original query、PreviousTurn filter/bounds、observer/cancel、Run terminal persistence、V012/L3、公开隔离。
+- 非目标：Controller/SSE/前端切换、旧链路删除、live E2E。
+
+## Cross-artifact Alignment
+
+| 上游 -> 下游 | 检查内容 | 状态 |
+|---|---|---|
+| ISS-014/brief -> proposal | 三路由、previous turn、Run lifecycle、内部-only 和阶段 6B handoff | 已对齐 |
+| proposal -> design | typed executors、observer、JPA/V012、异常/终态、L3 migration/rollback | 已对齐 |
+| design -> specs/tasks | 每项所有权/安全边界均有可观察 requirement 和实现测试切片 | 已对齐 |
+| specs -> tasks | 9 组 requirements 覆盖 Router/executors、store/policy、application、verification | 已对齐 |
+
+## Architecture Audit
+
+- 能力来源：`zoom-out`，使用 Chat Session、Diagnosis Run、RunContext、Diagnosis Agent、EvidenceGuard、SemanticGuard 和 PublishedResult 术语。
+- 链路为 `request -> application use case -> run store/router -> fixed executor -> Harness/Agent/Tool -> typed public content -> run finish`；Controller 不拥有模型/工具/Run。
+- ChatRunStore 拥有 MySQL 映射，Core 拥有运行状态，Application 拥有 dispatch/终态，path executor 拥有单一路径行为；PreviousTurn policy 是唯一安全历史投影。
+- 最大风险是 prior/current Run 顺序和 DB/lifecycle 双终态，design/tasks 已固定 prior read before start、single finish path 和 focused failure/cancel tests。
+- V012 是 L3 additive schema；migration、entity、repository、rollback 独立章节完整，公开入口阶段 6A 零变化。
+
+## Interface Impact
+
+- 级别：L3 database/collaboration interface。
+- 新增 `diagnosis_run.intent/release_outcome/published_result` 和索引；修改 Entity/Repository，新增 internal application/store/output contract。
+- 消费者：阶段 6B Controller/SSE adapter、MySQL/Flyway；旧 ChatService 在本阶段不消费新字段。
+- 迁移/回滚：V012 nullable additive；回滚先切旧入口，再删除 index/columns。
+
+## Commit Gate Preflight
+
+- proposal、design、specs、tasks 完整，`openspec status` complete，change strict validation 通过。
+- Question pool 全部已解决并汇报，无 user-interview、未判级接口或未接受架构风险。
+- Cross-artifact 四段对齐无 gap；V012/L3、prior read ordering、terminal persistence 和 6B handoff 已进入 design/spec/tasks。
+- Apply/Archive/commit 使用用户持续授权；公开协议和前端必须保持零 diff。
+- `.committed` 已创建，可进入 Apply。
+
+## Pre-apply Research
+
+- `DiagnosisHarnessCore`/`RunContext`：Run ID、budget、cancel 和 first-terminal-wins。
+- `GuardModelCall`/`HarnessRetryExecutor`：单轮模型 timeout/usage 和 Router 两次 attempt。
+- `HarnessEvidenceTools`/`RagToolResult`：Knowledge 唯一 lookup 路径和有界 projection。
+- `DiagnosisAgentUseCase`/`DiagnosisReleaseUseCase`：Diagnosis Draft 与安全 release boundary。
+- `DiagnosisRun`/`DiagnosisRunRepository`/`V011`：现有 Run schema 和写入模式。
+- `ChatService.ensureChatSession/startDiagnosisRun`：只参考 session metadata/JPA 写法，不复用旧 routing、多 Agent 或 ThreadLocal。
+- 技术栈：Spring AI direct Prompt、Jackson strict JSON、JPA repository、Flyway additive migration、protocol-neutral observer；无 MQ/新依赖。
+
+## Apply Progress
+
+- Router/System/Knowledge contracts 与 executors 已完成，tasks 1.1-1.4 完成。
+- 5 个 `ApplicationExecutorsTest` 通过：同输入 retry、最终 routing failure、System direct call、Knowledge exact references/no ID、NO_EVIDENCE/model skip。
+- TODO：PublishedResult/JPA/V012、Diagnosis executor、总应用用例和综合验证。
+- REVIEW：修正 `JpaChatRunStore` 多构造器 Spring 注入歧义；prior/start/intent/finish 持久化异常统一为稳定 `RUN_PERSISTENCE_FAILED`，并在安全完成时更新 ChatSession 活跃时间/消息对数。均为代码偏离修复，无需变更 OpenSpec。
+- PublishedResult/JPA/V012、Diagnosis executor、protocol-neutral Run control 与总 ChatApplicationUseCase 已完成，tasks 2.1-3.4 完成。
+- 13 个 stage 6A focused tests 通过；TODO 仅剩综合回归、static scope 和 OpenSpec verification。
+- 综合回归曾在 `SemanticGuardTest.attemptTimeoutCancelsBothPermittedModelCalls` 出现负载相关失败。诊断确认生产代码对每次 timeout 均调用 `Future.cancel(true)`，但第二个 Future 可能在任务线程启动前已取消，此时不存在可接收 interrupt 的线程。分类为测试假设偏差，不是 OpenSpec 或生产代码偏离；回归断言改为两次 TIMEOUT attempt、两次模型预算预留，以及至少一个已运行调用收到 interrupt。
+
+## Final Review
+
+- Stage 6A focused tests 与阶段 2-5 regression 共 18 suites / 76 tests，0 failure/error/skipped；Maven compile 通过。
+- OpenSpec strict validation 通过；V012、Entity、Repository 的三个字段和 previous-turn filter 对齐。
+- 公开 Controller、前端和 endpoint 零 diff；Router/System executor 无 Tool、ReactAgent、ThreadLocal 或手写 loop。
+- `PublishedResult` 只包含 `user_query/published_conclusion/scope/limitations/source_documents`，负向序列化测试通过。
+- 本阶段不运行 live E2E，按 ISS-014 门禁留到阶段 7。
@@ -0,0 +1,31 @@
+# Evidence: single-react-chat-application-usecase
+
+## Code and Contract Evidence
+
+- `DiagnosisHarnessCore`/`RunContext` 已提供 Run ID、预算、取消和 first-terminal-wins，应用用例无需创建第二套生命周期。
+- `GuardModelCall`/`HarnessRetryExecutor` 提供单轮模型 timeout、Token 记账和两次 Router attempt。
+- `HarnessEvidenceTools`/`RagToolResult` 提供 Knowledge 路径唯一 lookup 和有界 projection。
+- `DiagnosisAgentUseCase`/`DiagnosisReleaseUseCase` 已形成 Diagnosis Draft 与安全发布边界。
+- `DiagnosisRun`/`DiagnosisRunRepository`/V011 提供既有 Run 持久化，V012 以 nullable additive 字段扩展。
+
+## Confirmed Boundaries
+
+- Router 输入只含原始 Query、可选 last intent 和 last user query；最终失败不得默认进入 Diagnosis。
+- 三类 executor 不互相调用，所有路径接收未改写 Query。
+- PreviousTurn 只来自同 Session 最近 `DIAGNOSIS + SUCCESS + published_result`，且必须在保存当前 Run 前读取。
+- Knowledge 公开内容只保留 stable document metadata，不发布 direct Tool Call ID。
+- `PublishedResult` 不保存 Tool ID、raw evidence、完整 Draft 或 SemanticGuard reason；Fallback/Failed/Cancelled 不写安全历史。
+- Controller/SSE/前端切换属于阶段 6B，本阶段保持公开协议不变。
+
+## Diagnosis Finding
+
+- 综合回归暴露 `SemanticGuardTest` 的负载竞态：第二个 Future 可能在获得线程前被取消，因而不会产生第二次 interrupt。
+- 生产代码已对每次 timeout 调用 `Future.cancel(true)`；测试改为验证两次 TIMEOUT attempt、两次模型预算预留，以及至少一个运行中调用被中断。
+- 分类为测试假设偏差，不是生产代码或 OpenSpec 偏离。
+
+## Verification Evidence
+
+- Stage 6A focused tests：13 tests 通过。
+- Stage 2-5 与 6A 综合回归：18 suites / 76 tests，0 failure/error/skipped。
+- Maven compile 与 change strict validation 通过。
+- 公开 Controller/前端零 diff；Router/System executor 无 Tool、ReactAgent、ThreadLocal 或手写 loop。