CodeWiki 增量代码审查报告

• 项目：codescan/code-agent-v2
• 分支：v1.5.0-pre.6
• 基准 commit（base）：aeded010d957921ebc25783820120eb9459ee589
• 目标 commit（head）：71608082aecbfdab2c567f2a648700a2e4345179

---

一、变更概览

本版本是一次聚焦的 CodeWiki 模块文档路径治理改动，核心是把「模块文档身份」从中文展示名（name 层级拼接）统一切换为模块源码路径（node.path），并在生成、增量复用、上传与读取校验四处保持一致，同时拒绝非法/保留/重复路径。

变更文件

关键实现点

1. 新模块 module-path.ts

   • normalizeMarkdownPath：拒绝 \0、\、//、绝对路径、.././空段；拒绝 overview.md/summary.md 作为模块文档（rejectReserved）。
   • moduleMarkdownPath(node) = node.path 规范化 + .md 后缀（保留保留名拒绝）。
   • requestedDocumentMarkdownPath(requested)：读取请求用，不拒绝保留名（保证能读 overview.md/summary.md）。
   • collectModuleDocumentPaths(tree)：递归收集并拒绝重复文档 key、校验节点结构（name/path/sub_items）。

2. orchestrator 一致化

   • processTree 写文件路径由 assertSafeModKey(modKey) + {name-path}.md 改为 moduleMarkdownPath(node)；增量上下文 incrementalContexts.get(docRelativePath) 同键。
   • / 读取与链接索引改用 。

---

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

来源：codescan_issues_diff（base=aeded010… → head=71608082…），修复 72 条 / 新增 74 条。

⚠️ 重要说明：经逐条比对，本次「修复 72 条 / 新增 74 条」中的绝大多数并非功能缺陷修复，而是同一规则、同一文件的行号平移：

• orchestrator.ts：所有条目前后偏移 +4 行（例如 圈复杂度过高 @ :78 → :82、上帝类 @ :207 → :211、processTree :253 → :257），属新增 4 行 import 导致的编号位移。
• service.ts：所有条目前后偏移 -42 行（例如 上帝类 @ :426 → :384、readDocument :611 → :569），属删除约 46 行旧路径校验函数导致的上移。

因此 base 与 head 的问题集合基本等价，工具按行号对不齐而记为「修复 + 新增」。真正的「修复」信号是：删除 service.ts 的重复路径校验函数后，其对应的重复/校验类条目被等价条目取代，代码去重收敛（assertSafeModuleKey/requiredModuleMarkdownPaths 已彻底删除，isRecord 等无残留死代码）。

代表性「修复」条目（按严重度）：

• [Medium/Bug] 未处理的 Promise @ service.ts:784 / :789 → 平移到 :730 / :735（未真正修复，见下节）
• [Medium/Complexity] 函数过长 @ orchestrator.ts:253 (processTree) → :257
• [Medium/Complexity] 圈复杂度过高 @ orchestrator.ts:78/253/574/1007、[Medium/Dependency] 高耦合、[Low/Maintainability] 重复代码块 @ service.ts:63/442

---

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

同样来自 codescan_issues_diff 的「新增」集合（74 条）。

1) 本次改动真正引入的新代码问题（仅新文件 module-path.ts）

• [Medium/Complexity] 圈复杂度过高 @ src/codewiki/module-path.ts:10（normalizeMarkdownPath，count=14）
• [Medium/Complexity] 圈复杂度过高 @ src/codewiki/module-path.ts:53（collectModuleDocumentPaths，count=11）

建议：将「字符级非法校验」与「段级校验」拆为小函数，或抽出 isUnsafePath(raw) 谓词，降低单函数分支数。

2) 行号平移的「伪新增」（非真实新缺陷）

orchestrator.ts（60 条）与 service.ts（12 条）的新增条目与第二节「修复」条目一一对应，均为同一问题在 head 版本上的新行号，包括：

• [Medium/Complexity] 上帝类 @ orchestrator.ts:211（CodeWikiOrchestrator 24 个方法 > 20）
• [Medium/Complexity] 函数过长 @ orchestrator.ts:257 (processTree, 106 行) / :1014 (mergeIncremental, 160 行)
• [Medium/Dependency] 高耦合：processTree 直连 21 个函数、run 直连 24 个、mergeIncremental 直连 34 个、generateSummary 16 个、update/readDocument/schedule 等
• [Medium/Concurrency] 异步函数中的同步阻塞调用（fs.mkdirSync/writeFileSync/existsSync 等，遍布 orchestrator 与 service）
• [Medium/Bug] 未处理的 Promise @ src/codewiki/service.ts:730 / :735
• [Medium/Complexity] 嵌套深度过高 @ src/codewiki/service.ts:748 / :796、[Medium/Performance] 循环内字符串拼接 @ orchestrator.ts:406 等

结论：除 module-path.ts 的 2 条圈复杂度外，本次改动没有净新增的真实缺陷；其余均为技术债的既有项 + 行号漂移。

---

四、风险评估与建议（重点）

本次改动逻辑上自洽（路径生成/复用/上传/校验四处已统一，测试同步更新），但存在以下兼容性与健壮性风险，建议在合并前确认：

1. 【高】跨版本增量合并会失败（迁移风险）

   • 旧版本 baseline 的模块文档在对象存储中按中文名 key存储（如 用户模块/认证子模块.md）；
   • 新版 loadBaselineArtifacts 通过 collectModuleDocumentPaths(baselineTree) 生成源码路径 key（如 src/user/auth.md）读取 baseline；
   • 因此对「旧版本生成的 baseline」执行增量合并，会命中 Baseline 缺失模块 Markdown: … 直接失败。
   • 建议：要么做 baseline key 迁移/回退双读（同时尝试 name 与 path），要么明确「该版本起 baseline 需重新全量生成」并在发布说明中提示。

2. 【中】Planner 契约变更为强约束

   • 新版仅接受 module_path = 源码路径（module_tree_index.path）；若 Planner（或历史 prompt 缓存）返回 name 拼接路径，则该模块被 静默跳过，全部不匹配时抛 Planner 模块全部无法映射到 baseline 树。
   • prompt 已同步修改，但建议对「跳过模块数占比过高」增加告警，避免文档静默缺失。

3. 【中】run() 的强前置校验会放大整体失败面

   • run() 中 collectModuleDocumentPaths(tree) 在 任何 try 之外调用，一旦 discovery 产出的任一节点缺失/非法 path、或出现重复源码路径，将整体任务失败；而 processTree 内对非法路径是「单模块记错、其余继续」。建议统一为可降级的单模块错误，或对 discovery 输出先做兜底修复。

---

五、验证建议

• 单元测试：test/codewiki/module-path.test.ts（新增）、test/codewiki/incremental.test.ts、test/codewiki/orchestrator.test.ts、test/codewiki/service.test.ts 已同步更新，建议全量回归。
• 重点回归用例：
  1. 生成 → 上传 → 读取链路均以 node.path.md 为 key（含中文 name 的模块）。
  2. 路径注入（../、绝对路径、\、\0）在 run / processTree / merge 三处均被拒且不逃逸 reports 目录。
  3. 重复源码路径 / 结构不完整树被拒（CodeWiki 模块路径重复 / CodeWiki 模块树非法）。
  4. 跨版本 baseline：用旧版本产物做 baseline 跑一次 mergeIncremental，确认是否如前所述失败（决定是否需要迁移方案）。

---

附：整体结论

本次改动方向正确、范围收敛，统一了 CodeWiki 模块文档路径的身份来源，消除了 service.ts 与 orchestrator.ts 之间的重复路径校验实现，并补齐了安全/去重单测。质检层面未净增真实缺陷（仅新文件 module-path.ts 2 处圈复杂度）；但需重点关注跨版本 baseline 迁移与run() 强校验放大失败面两个运行期风险。