feat(harness): add canonical tool invocation boundary
This commit is contained in:
zhuyongxin
@@ -0,0 +1,106 @@
|
||||
# Decisions: single-react-tool-invocation-store
|
||||
|
||||
## 规模与入口
|
||||
|
||||
- 分档：complex。
|
||||
- 入口：ISS-014 阶段 3A；阶段 0/1/2 已 Archive 并由 `58c3910`、`4274f33`、`6b74990` 提交。
|
||||
- 目标：统一 ToolBoundary 和 Redis canonical invocation store，不实现 Tool-specific projection。
|
||||
|
||||
## Context
|
||||
|
||||
- 阶段 1 主规格已冻结 RAG/log/MySQL Agent-facing Request/Result 和 `EvidenceStatus`。
|
||||
- 阶段 2 主规格已冻结 `RunContext`、预算、取消、Key Factory 和 strict retry。
|
||||
- 旧 `ToolInvocationRecorder` 依赖 `SessionContextHolder`、JPA `ToolInvocation` 和 500 字符 preview，属于 durable audit 兼容路径，不是 canonical store。
|
||||
- 既有 `SessionConfiguration` 提供 `RedisTemplate<String,Object>` + JSON serializer；新 store 复用 bean，不新增连接配置。
|
||||
|
||||
## Question Pool
|
||||
|
||||
| 维度 | 问题 | 模式 | 证据与结论 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 术语 | canonical invocation 与旧 JPA ToolInvocation 是否同一记录？ | evidence-driven | ISS-014 数据分层明确 Redis canonical 保存完整 request/raw/agent，JPA 只做 durable audit；两者分离。 | 已解决并汇报 |
|
||||
| 术语 | `PROJECTING/READY/ERROR` 与 evidence status 如何组合？ | evidence-driven | 阶段 0/1 规格：只有 READY 可为 FOUND/NO_EVIDENCE，ERROR 不可引用；PROJECTING 是内部暂态。 | 已解决并汇报 |
|
||||
| 边界 | 阶段 3A 是否实现 RAG/log projector？ | evidence-driven | ISS-014 3A 明确不实现 Tool-specific projection，3B/3C 单独接入。 | 已解决并汇报 |
|
||||
| 边界 | Redis 读取是否刷新 TTL？ | evidence-driven | ISS-014 固定“创建设置、读取/更新不续期”；更新采用当前剩余 TTL，不恢复初始 TTL。 | 已解决并汇报 |
|
||||
| 验收 | raw 超限是否静默截断？ | evidence-driven | ISS-014 明确 `RESULT_TOO_LARGE` ERROR，raw 不静默截断；agent projection 才可按 projector 预算截断并标记。 | 已解决并汇报 |
|
||||
| 验收 | 缺失/重复/cross-run ID 如何处理？ | evidence-driven | 阶段 3A 任务明确覆盖；Key Factory 保留框架 ID，ToolBoundary 在 store 创建前校验 Run/ID 和 duplicate。 | 已解决并汇报 |
|
||||
| 技术 | Redis 如何避免 update 重置 TTL？ | evidence-driven | 既有 RedisTemplate；begin 使用 setIfAbsent + TTL，update 先读取剩余 TTL 再写回相同/更短 TTL，get 不调用 expire。 | 已解决并汇报 |
|
||||
| 技术 | 是否修改旧 recorder 以复用新 store？ | evidence-driven | 旧链路大量测试依赖 JPA preview/evidence_refs；本阶段零消费者，保持旧 recorder 不变，避免行为回归。 | 已解决并汇报 |
|
||||
|
||||
## Grill 结论
|
||||
|
||||
- 所有术语、边界、验收和技术问题均由 ISS、阶段规格、旧代码和 Redis 配置事实证明。
|
||||
- 没有新增产品偏好或兼容性取舍需要 user-interview；并发更新窗口作为已接受风险记录。
|
||||
- `grill-with-docs` 的代码可证结论已回写 proposal；没有未确认问题。
|
||||
|
||||
## 能力与工具限制
|
||||
|
||||
- Discover 能力来源：`sm-flow` + `grill-with-docs`。
|
||||
- 当前无 `codebase-retrieval`/LSP；使用 `rg`、源码、既有测试、本地 Redis 配置和 focused fake tests 进行等价核对。
|
||||
|
||||
## Cross-artifact 对齐
|
||||
|
||||
| 链路 | 状态 | 结论 |
|
||||
|---|---|---|
|
||||
| brief 目标/范围/非目标 -> proposal | 已对齐 | Boundary、canonical record、TTL/size、Fake tests 和 legacy isolation 全部覆盖。 |
|
||||
| proposal 范围/约束/承诺 -> design | 已对齐 | Redis value、状态机、preflight 顺序、raw/projection 和失败处理均已设计。 |
|
||||
| design 决策/接口影响/风险 -> specs/tasks | 已对齐 | L2 boundary、TTL 更新窗口、oversize/error、ID/Run 所有权有对应要求和任务。 |
|
||||
| specs 可观察行为 -> tasks | 已对齐 | 7 条 requirements 分解为 store、boundary、limits/failure 和隔离验证纵向切片。 |
|
||||
|
||||
## Architecture Audit
|
||||
|
||||
- 能力来源：`zoom-out`，按 RunContext、Invocation Status、Evidence Status、canonical invocation 和 durable audit 术语审计。
|
||||
- ToolBoundary 只编排一次调用；CanonicalInvocationStore 独占 Redis 状态转换；DiagnosisHarnessCore 独占 Run budget/cancellation；旧 recorder 只写 JPA audit。
|
||||
- request/raw/agent result 归同一 canonical record，Agent 只获得 ToolBoundaryResult，不存在 raw 旁路。
|
||||
- Redis adapter 是唯一 Redis 访问点，接口/Fake 不依赖 Redis；后续 3B/3C 可直接复用而不复制状态机。
|
||||
- 风险集中在 read-TTL-write 并发窗口和 canonical raw 敏感性，已进入 design/spec/limits，无架构或 ADR 冲突。
|
||||
|
||||
## Commit Gate Preflight
|
||||
|
||||
- proposal、design、specs、tasks 完整，OpenSpec status complete，strict validation 通过。
|
||||
- question pool 无未汇报 evidence-driven 或未确认 user-interview 项。
|
||||
- L2 内部接口影响已记录；旧 JPA/Chat/Controller/协议不改。
|
||||
- cross-artifact 无 gap，所有错误、TTL、size、ID/Run 所有权和隔离要求可由 Fake tests 验证。
|
||||
- Apply 已获持续授权，范围只包括新 store/boundary 与 focused tests。
|
||||
|
||||
## Pre-apply Research
|
||||
|
||||
### 参考实现与复用
|
||||
|
||||
- 复用 `DiagnosisHarnessCore` 的 active/deadline/Tool budget/Run bytes 门禁。
|
||||
- 复用 `ToolCallKeyFactory` 精确保留框架 Tool Call ID 并隔离 Run key。
|
||||
- 复用阶段 0 `InvocationStatus` / `EvidenceStatus`，不创建字符串状态副本。
|
||||
- 复用 `SessionConfiguration` 提供的 `RedisTemplate<String,Object>` 和 Spring Boot ObjectMapper。
|
||||
- 旧 `ToolInvocationRecorder`/JPA preview 仅作为 durable audit 反例，本阶段不修改或调用。
|
||||
|
||||
### 技术栈清单
|
||||
|
||||
- canonical record：Java 17 record + Jackson JSON String，所有状态组合在 record transition 方法中校验。
|
||||
- Redis create：`ValueOperations.setIfAbsent` + TTL；update：读取当前 remaining TTL 后写回；get 不调用 expire。
|
||||
- 大小：UTF-8 bytes；record/agent result/store limits 与 RunContext 累计 capacity 双重门禁。
|
||||
- 测试：Mockito RedisTemplate/ValueOperations 验证 TTL API；In-memory fake store + Fake Tool/Projector 验证 boundary，不连接外部 Redis。
|
||||
|
||||
### 新建类型
|
||||
|
||||
- canonical model/limits/store/exceptions/Redis adapter。
|
||||
- ToolCallRequestEnvelope、ToolBoundaryResult、ProjectedToolResult、ToolExecutor、ToolResultProjector、ToolBoundary 和稳定 error codes。
|
||||
- Redis adapter tests 与 boundary fake tests。
|
||||
|
||||
### 影响半径
|
||||
|
||||
- 新 package 在阶段 3A 保持零现有消费者。
|
||||
- Redis 访问只允许出现在 `RedisCanonicalInvocationStore`；旧 Chat/AIOps/Controller/JPA/Recorder 不修改。
|
||||
|
||||
## Apply 结果
|
||||
|
||||
- 冲突分类：一次 focused test 断言错误（duplicate 场景应调用 `setIfAbsent` 两次）已修正并复跑通过；无规格偏离。
|
||||
- 新增 canonical record/limits/store exceptions、Redis JSON adapter、ToolBoundary envelope/result/interfaces 和 stable error codes。
|
||||
- ToolBoundary 已实现 preflight、Core budget/capacity、PROJECTING、raw/projection size、READY/ERROR 和安全返回边界；未接具体 projector。
|
||||
- 首模块对齐：store/boundary/limits/failure 与 design/tasks 全部完成；RAG/log/MySQL adapters 仍留给后续阶段。
|
||||
|
||||
## Apply 验证
|
||||
|
||||
- 编译：`mvn -q -DskipTests compile`：通过。
|
||||
- Store/Boundary focused：`mvn -q '-Dtest=CanonicalInvocationStoreTest,ToolBoundaryTest' test`：通过。
|
||||
- 综合回归：`mvn -q '-Dtest=CanonicalInvocationStoreTest,ToolBoundaryTest,HarnessContractTest,RagToolContractTest,QueryLogsToolContractTest,MysqlToolContractTest,RunContextTest,RunBudgetTest,DiagnosisHarnessCoreTest,HarnessRetryExecutorTest,ToolCallKeyFactoryTest,SpringAiRetryConfigurationTest,ChatControllerTest' test`：通过。
|
||||
- 静态隔离：新 Harness 包仅 `RedisCanonicalInvocationStore` 引用 Redis；legacy recorder/JPA/Chat/AIOps/Controller/repository/resources diff 为空。
|
||||
- OpenSpec：`openspec validate single-react-tool-invocation-store --strict`：通过。
|
||||
Reference in New Issue
Block a user