What · 是什么
无 git 历史/无有意义 diff 时：全文件扫描，按语言/目录分束，DEDUP 去重，项目级总结
面向无 git 历史或无有意义 diff 的仓库：接手遗留代码、安全审计、整体摸底时用扫描模式而非 diff 模式
ocr scan 扫描整个仓库，ocr scan --path internal/agent 可限定子目录，聚焦特定模块
--batch 支持 by-language 或 by-directory 分束：按语言或目录分批处理，控制单次扫描的规模与成本
DEDUP 机制对跨文件/跨批次重复问题去重，防止同一问题在多文件重复评论
PROJECT_SUMMARY 生成项目级总结：扫描后汇总整体健康状况、共性风险与改进建议，而非只给零散评论
适用场景：接手遗留代码、安全审计、新人熟悉代码库
Why · 为什么
原理 · Principle
陌生代码库没有『变更』概念，diff 模式无从谈起，必须整库扫描建立基线
全库一次性送入模型不可行，by-language/by-directory 分束把扫描切成可管理的批次
审计场景下重复评论噪音极大，DEDUP 保证每条问题只出现一次，报告才可信
项目级总结把『发现的问题』提升为『对项目的判断』，正是审计报告需要的形态
How · 怎么做
整库扫描：在仓库根目录运行 ocr scan，等待扫描完成并查看逐文件评论
限定范围：ocr scan --path internal/agent，只扫指定目录，快速聚焦目标模块
分束控制规模：ocr scan --batch by-language 按语言分批，或 --batch by-directory 按目录分批，避免单批过大
安全审计流程：先全库扫描 → 查看 DEDUP 后的去重问题列表 → 读 PROJECT_SUMMARY 项目级总结 → 按严重性逐项跟进
遗留代码接手：扫描建立基线后，把项目级总结作为改造计划与排期的输入
案例 · Cases
| 代表性案例 |
|---|
| 接手遗留项目：整库扫描产出问题清单与项目总结，快速定位技术债最重的模块 |
| 安全审计：对指定敏感目录 ocr scan --path，配合去重列表逐条验证漏洞风险 |
| 技术选型评估：扫描候选第三方库源码，用项目总结判断代码质量与维护风险 |
| 团队代码体检：定期整库扫描，对比多次 PROJECT_SUMMARY 看质量趋势 |
反模式 · Anti-patterns
- 对超大仓库不做 --batch 直接全量扫描，单批输入超限导致任务失败或成本爆炸
- 忽略 DEDUP 去重，跨文件重复问题刷屏，掩盖真正的高价值发现
- 把扫描报告当最终结论而非输入：不结合人工验证就把问题列表直接派工
- 在无 git 历史的仓库误用 review 模式（无 diff 可审），应改用 scan 模式
正反实例论证 · Evidence
正例 · Pro
按目录分束控制扫描规模
ocr scan --batch by-directory# 或限定范围ocr scan --path internal/agent把全库扫描切成可管理批次，单批输入不超限，接手遗留项目时先聚焦核心模块。
反例 · Con
超大仓库不做分束直接全量扫描
ocr scan # 无 --batch，单批塞入全部文件单批输入超限导致任务失败或成本爆炸，一次审计跑不完还留下高额账单。
正例 · Pro
保留 DEDUP 去重输出干净问题清单
ocr scan# DEDUP: 同一问题跨文件只报一次found 23 unique issues across 41 files跨文件/跨批次重复问题被去重，问题列表干净可信，审计人力聚焦真正的高价值发现。
反例 · Con
关闭去重导致重复问题刷屏
ocr scan --no-dedup同一问题在数十个文件重复评论，列表被刷屏，真实风险被噪音掩盖，审计报告不可信。
正例 · Pro
PROJECT_SUMMARY 作为改造排期输入
ocr scan# 输出项目级总结：共性风险、技术债集中模块PROJECT_SUMMARY: 12 modules, 3 high-risk patterns (panic, sql concat, no tls)项目级总结把零散发现提升为对项目的整体判断，直接作为遗留代码改造计划与安全审计结论的输入。
反例 · Con
把扫描报告当最终结论直接派工
# 不做人工验证，直接把去重问题列表全量派单扫描结果未经验证即派工，假阳性进入任务系统，修复成本与信任度双输。