# TCOC-5820 固定 SHA Code Investigator 验证追踪

**日期：** 2026-08-28  
**状态：** 完成：artifact 投递与焦点合约端到端回归通过
**范围：** TiDB 指定提交的源码诊断能力与端到端性能；不包含生产部署变更。

## 目标与边界

主 agent 接收用户提供的 TiDB 完整 Git SHA，将一个有界源码问题交给 `code-investigator`。子 agent 返回完整结构化 artifact：源码行为、调用链、配置或阈值语义、必要条件、混杂因素、运行时预测、建议检查、局限性和置信度。它只能说明源码机制，不能在没有运行时证据的情况下断言真实事故因果。

固定输入：

    repo: pingcap/tidb
    commit SHA: 202b7f47286a1109b5c957401d34c9358d130ae0

证据引用格式只能是 `path:line` 或 `path:lineA-lineB`，不使用冗余的 `@SHA`。完整 SHA 由 task header、artifact `commit_sha` 和 context ID 固定。

本次不修改正式 backend 部署，也不删除、重建或修改独立代码快照 PVC。隔离测试 Pod 的手动清单不属于本 PR。

## 当前实现

- fixed-SHA snapshot context ID：`tidb:<sha>:no-tests`。
- 仅当完整 40 位 SHA 与有界源码问题同时存在时，主 agent 才派发 `code-investigator`。
- 正常 helper 路径为 `prepare -> inspect`。只有首次 `inspect` 返回 `truncated=true` 与 `refinement_available=true` 时，才允许一次 `inspect-refine`。
- child 禁止通用循环恢复路径：`discover`、`search`、`read-many`、通用 `read`、`grep` 与 `glob`。
- artifact 只接受受控 `code-investigator` Task 的成功完成输出，并验证 task header 中的 repo、精确小写 SHA 和非空 `focus_terms`。
- `focus_terms` 是用户问题中的命名对象；artifact 必须为每个术语返回带 `path:line` 证据的 `direct_answers`，否则拒绝投递。

## 已完成验证

隔离 dev Pod 中已经存在目标 SHA 的无测试源码快照：

    /code-cache/snapshots/pingcap-tidb/202b7f47286a1109b5c957401d34c9358d130ae0/no-tests

最近一次真实 workspace turn 使用该 SHA，端到端耗时约 **165.0 秒**：

| 阶段 | 耗时 | 说明 |
| --- | ---: | --- |
| `prepare` | 1.204s | 固定 SHA 上下文准备 |
| `inspect` | 8.126s | 首次批量、有界源码检查 |
| `inspect-refine` | 7.255s | 截断后唯一一次补充检查 |
| helper 合计 | 16.585s | 三次受控 helper/ACP 生命周期 |
| `code-investigator` Task | 116.747s | 子 agent 推理、工具调用和 artifact 组织 |
| 主 agent turn | 约 165.0s | 用户可见端到端时间 |

helper trace 为 `prepare -> inspect -> inspect-refine`，没有观察到被禁止的泛化工具。`inspect-refine` 的前提已满足。子 agent 的源码结论和无 `@SHA` 引用符合目标，例如 `pkg/util/topsql/reporter/reporter.go:221-229`；结论明确保留为源码行为说明。

聚焦回归验证结果：42 个测试通过，Ruff 通过，`git diff --check` 通过。

## 已修复问题

上一轮真实运行中，子 agent 的结构化结果生成成功，但 `evidences/agent-runs/code-investigator.json` 未落盘。根因是 OpenCode 的事件时序：`ToolCallStart` 携带空 `raw_input`，完整的 `subagent_type=code-investigator` 和受控 task header 仅在后续 `ToolCallProgress` 到达。旧实现只在 start 事件注册 authorized Task，completion 时因此找不到关联。

修复已包含在本 PR：每个 progress 合并输入后立即、幂等地注册 Task。回归测试模拟真实顺序：空 start input，随后在 completion progress 出现完整受控输入。

该问题已在后续真实回归中修复并验收。

## 最终回归与验收

在隔离 dev Pod 的临时新代码实例中，以新的可丢弃 workspace 和 600 秒 timeout 重跑同一个 SHA。以下条件均已满足：

1. turn 在 600 秒内完成。
2. `evidences/agent-runs/code-investigator.json` 存在。
3. artifact `commit_sha` 等于目标 SHA，`code_context.context_id` 等于 `tidb:202b7f47286a1109b5c957401d34c9358d130ae0:no-tests`。
4. artifact source references 不含 `@`。
5. 日志包含 `code_investigator_task_registered` 和 `code_investigator_artifact_delivered`，没有 delivery failure。
6. helper trace 只含 `prepare + inspect`，或在截断前提成立时额外一次 `inspect-refine`；不存在泛化工具循环。
7. `others` 焦点问题的 artifact 具有 `focus_terms` 和逐项 `direct_answers`；泛化的调用链不能替代直接回答。
8. 分别记录 helper、Task 与端到端 turn 时间；不将单样本与旧约 300 秒或 380 秒运行作严格比较。

最终 `others` 焦点回归的端到端时间为 **178.576 秒**，其中 `prepare` 为 1.336 秒、`inspect` 为 5.525 秒、`inspect-refine` 为 7.814 秒、`code-investigator` Task 为 125.514 秒。artifact 已投递，包含 `others`、`Top-N aggregation`、`channel drop` 和 `reporting drop` 的逐项源码回答。相关后端回归共 50 项通过，Ruff 与 `git diff --check` 通过。

## 性能结论

当前受控 helper 已从此前约 11 次调用、44.7 秒，收敛到 3 次调用、16.6 秒。端到端时间仍主要由 agent 推理、任务编排和结构化输出决定。artifact 投递成功后至少再取得一个完整样本，再评估主 agent 输入读取、artifact 写入和模型侧任务组织的后续优化；这些优化不得削弱固定 SHA、完整 artifact 合约、source-only 因果边界或通用性。