CodeWiki Hub API 增量代码质检报告

• 项目：codescan/codewiki-hub-api
• 分支：v1.5.0-pre.6
• 对比区间：f72f2e5（base） → e0a6558（head）
• 变更规模：10 个文件，其中新增 3 个测试文件；无 High/Critical 级问题引入
• 质检问题对比（真实数据，来自 issues_diff）：修复 26 条 / 新增 37 条

---

一、本版本变更主题

本版本是一条围绕「Agent 报告完整性治理」的修复线，核心目标：把"有任意一路报告就算成功"的宽松语义，收紧为"四路齐全才算可用，部分产出显式降级并隔离"。

变更包含 4 组改动：

变更文件清单：CHANGELOG.md、configs/{config,config-sit,config-ent3,config.example}.yaml、configs/config.go、internal/biz/repo_pipeline_status.go(+test)、internal/data/models.go、internal/data/task_queue_repo.go(+test)、internal/engine/orchestrator.go、internal/engine/orchestrator_agent_retry_test.go（新）、internal/engine/orchestrator_report_status_test.go（新）、internal/engine/review_regression_test.go。

---

二、修复的问题（26 条，真实数据）

结论先行：这 26 条"修复"绝大多数不是真修复，而是同一批存量问题因代码整体上移/函数重命名后行号漂移，在 head 中消失、随后又在新行号以"新增"形式出现（见第三节的成对north映射）。真正被消除的只有因函数拆分带来的少量结构性改善。

按类型分布：

① 重复代码块（3 条）

• internal/biz/repo_pipeline_status.go:59 — 重复分支块
• internal/data/task_queue_repo.go:203 — 重复查询块
• internal/engine/orchestrator.go:239 — 重复块（3 处）

② 圈复杂度过高（6 条）

• internal/data/task_queue_repo.go:380
• internal/engine/orchestrator.go:547、:737、:852、:917、:1104

③ 嵌套深度过高（2 条）：orchestrator.go:547、:917

④ 函数过长（2 条）：orchestrator.go:917、:1104

⑤ 高耦合（3 条）：orchestrator.go:737、:917、:1104

⑥ 缺少默认分支（2 条，Low/Bug）：orchestrator.go:577、:637

⑦ 参数过多（2 条）：data/task_queue_repo.go:421、data/task_queue_repo_status_test.go:128

⑧ 未使用参数（3 条）：data/task_queue_repo.go:421、orchestrator.go:852、:1078

⑨ 行过长（2 条）：data/task_queue_repo_status_test.go:42、orchestrator.go:263

行号漂移对照（"修复"实为同一问题搬家）：

---

三、新增的问题（37 条，真实数据）

全部为 Low / Medium，无 High/Critical。分三类：

3.1 真实新增（由本次改动直接引入）— 值得关注

3.2 重复代码块（4 条，Low）

• internal/biz/repo_pipeline_status.go:65 — 新增的 partial 分支与 completed 分支重复 4 行（可抽 completedStatus() 辅助）
• internal/data/task_queue_repo.go:176 — 查询块重复
• internal/engine/orchestrator.go:243 — 重复块 3 处
• internal/data/task_queue_repo_status_test.go:55、internal/engine/orchestrator_agent_retry_test.go:21、internal/engine/orchestrator_report_status_test.go:28 — 测试重复块

3.3 行号漂移复现（Low/Medium，其余约 20 条）

task_queue_repo.go:{385,426}、task_queue_repo_status_test.go:{36,54,209}、orchestrator.go:{267,557,587,647,717,1010,1236} 等，与第二节"修复"项一一对应，属存量问题随行号迁移，并非新引入。

---

四、关键实现分析与风险

4.1 逻辑正确性（实现合理）

• 重试语义：runSingleAgentWithRetry 用 context.WithTimeout(ctx, effectiveAgentTimeout()) 建立共享超时预算，第 2/3 次重试用 {id}_{config}_retry_N 独立任务 ID，避免复用已失败任务；agentMaxAttempts() 以 min(cfg,3) 硬顶上限，测试 TestAgentMaxAttemptsCapsAtThree 覆盖了越界配置。✅
• 终态扩展：failed/cancelled/canceled/timeout 均视为终止失败并触发重试，修掉了"timeout 终态死等"的隐患。✅
• 空 manifest 判定：单路返回 S3Manifest[config] 为空即判失败（runSingleAgentAttempt 内 strings.TrimSpace 校验），避免"ok 但无产物"被计入成功。✅
• 状态机收敛：aggregateAgentResults 用 available / partial / empty 三态，且 available 时清空 ReportError；对应汇总口径 anySuccessful()（是否失败）与 allSuccessful()（是否可发卡片）。✅
• 基线隔离：RunMergePhase 在 okCount != 4 时调用 markBaselineMergePartial 把基线置 partial 并写 ReportError，返回 ，避免"被原地覆盖过的基线继续宣称完整"。✅

4.2 需关注的风险与不一致（建议跟进）

R1（中）基线选择口径不统一——读取路径仍用宽松查询。 GetLatestCompleteScan（4 路齐全）只被 pr_merge 与 RunMergePhase 使用；而 GetLatestScan（仅 state='completed'，不看 report_status/manifest 完整性）仍被以下路径调用：

• internal/biz/wiki.go:152/183/204/220（Wiki 树/文档/报告 manifest/报告正文）
• internal/mcp/resolve.go:66（MCP 数据基线）
• internal/biz/repo.go:122（仓库详情最新全量任务）

后果：当某仓库最新全量任务是 partial/empty 时，Wiki 与 MCP 仍会把缺路 manifest当作基线对外提供。建议这些读取路径同样改为"优先取完整记录、否则回退并显式标注"。

R2（中）未配置 Agent 时全量去重失效。 FindCompletedByHeadSHA 新增 report_status='available' 过滤。若部署未配置 Agent（o.agent == nil → runAgentBatch 直接返回空结果、ReportStatus 非 available），则任何全量任务的去重都失效，同 commit 会反复重扫。上线前需确认 Agent 为必备组件，或对 agent==nil 保留旧的宽松去重。

R3（中）新增状态值 partial 的前端契约。 deriveRepoPipelineStatus 开始输出 report_generation_status="partial"。仓库内无枚举校验，openapi.yaml 亦未定义该字段（见调研），实际识别取决于前端。需与前端确认新取值渲染（否则可能显示为"未知/失败"）。

R4（低）列表/详情口径与去重口径可能"闪跳"。 GetLatestScansByRepoIDs（仓库列表/我的仓库）仍取最新完成全量任务，不看完整性。若最新任务是 partial、而更早存在完整基线，列表会显示 report_generation_status=failed（hasAvailableReport 为 false 且非 partial），与"存在可用基线"的事实不一致。

R5（低）移除 code_overview 兼容键的影响面。 RunMergePhase 删除了 baseKey=="" && rt=="code_summary" 时用 code_overview 兜底的兼容逻辑，改由 completeBaselineManifest 严格要求 4 键齐全。这会让历史旧格式基线（用 code_overview 命名）彻底不可用于增量合并——与"隔离历史缺路基线"的设计一致，但需在运维侧确认：这类仓库会被强制走一次新的全量扫描。

R6（低）重试会新增 Agent 侧任务与超时预算紧张。 以 120m 为单路共享预算、每路最多 3 次尝试，4 路并发下最坏情况对 Agent 侧的压力×3；共享预算意味着首次尝试若已接近 120m，后续重试基本无预算可用（timeoutCtx.Err()!=nil 直接 break），实际重试机会取决于单次耗时。建议对单次尝试设置更短的分段预算或补充可观测指标。

4.3 配置变更

agent_max_retries: 3 已同步到 config.yaml、config-sit.yaml、config-ent3.yaml、config.example.yaml，并在 configs/config.go 补充 AgentMaxRetries 字段（JSON/yaml 双 tag）。未见遗漏。✅

---

五、测试覆盖评估

本次改动测试补充充分，且针对性强：

• internal/engine/orchestrator_report_status_test.go（新）：TestAggregateAgentResults 覆盖 4/4、3/4、0/4 三态与 ReportError 内容、available 清空错误；TestCompleteBaselineManifest 覆盖 partial/缺路拒绝；TestMarkBaselineMergePartial 验证隔离。
• internal/engine/orchestrator_agent_retry_test.go（新）：覆盖"第三次成功即停止且任务 ID 序列正确""连续失败严格停在 3 次""timeout 终态立即重试""配置越界仍硬顶 3 次"。
• internal/data/task_queue_repo_status_test.go：新增 TestFindCompletedByHeadSHARequiresAvailableReport、TestGetLatestCompleteScanSkipsPartialAndLegacyIncomplete，直接验证 partial/历史 3/4 记录不再阻止补扫与基线选择。
• internal/biz/repo_pipeline_status_test.go：把"partial 全量报告"的期望从 failed 改为 partial。
• internal/engine/review_regression_test.go：新增源码级回归断言，锁定 GetLatestCompleteScan、pr_merge 失败传播、以及"模板读取不得用 context.Background()"。

缺口：未见针对 R1（Wiki/MCP 读取路径完整性）、R2（未配置 Agent 去重）、RunMergePhase 部分失败时基线被落库为 partial 的端到端集成测试；也未覆盖 GetLatestScansByRepoIDs 的完整性口径。

---

六、结论与建议

总体评价：本次是有明确缺陷驱动的质量改进，方向和实现均正确，测试覆盖扎实，未引入 High/Critical 问题。主要代价是 orchestrator.go 复杂度进一步上升（单文件新增 7 个方法，触发"上帝类"阈值）。

优先级建议：

1. P1：统一基线/最新任务的"完整性口径"——让 GetLatestScan 的读取方（wiki.go、resolve.go、repo.go）也能感知 partial，消除 R1/R4 的口径分裂。
2. P1：确认 Agent 为必备组件，否则为 agent==nil 场景保留宽松去重（R2）。
3. P2：与前端对齐 report_generation_status="partial" 契约（R3）。
4. P2：为 RunMergePhase/runSingleAgentAttempt 拆分（复杂度 12/23、90+ 行），并补充合并部分失败的落库集成测试（第三节 3.1）。
5. P3：抽取 hasAvailableReport/hasCompleteFullReport/completeBaselineManifest 三处重复的"四路齐全"判定为共享函数，消除重复代码块与二义性。

关于"修复 26 条"的提醒：请勿将其理解为 26 个缺陷已解决；其中约 20 条为行号漂移后的同源问题（对照见第二节），真实净变化是"存量复杂度问题 + 新增类膨胀"，建议按第四节建议逐步治理。