用途
scan 是一个参数化参考文档扫描器,用于对单个选定的内建参考文档或显式通用自定义文档执行一次“精准、有证据支撑”的更新。它强调保留会改变行动规则、例外情况和已验证的发现,同时避免报告冗余。
主要能力
- 目标解析:强制先解析 --target=<key>,内建键使用清单条目;保留的 generic-reference-doc 模式还要求 --filename="<relative-path>"。无目标或未知键会停止并列出已注册键。
- 配置与适用性校验:通过 .claude/hooks/lib/project-config-loader.cjs 解析项目配置(默认 docs/project-config.json),配置缺失时使用运行时能力解析器和仓库证据;在扫描前检查能力是否真实存在,不存在则标记为 SKIPPED 并写明检查过的配置字段和路径。
- 有序执行流程:Validate → Resolve → Assess → Scan → Write → Apply → Report。
- 并行分片扫描:在授权下启动通用子代理,每个子代理负责不重叠的源范围,增量写入唯一分片文件 tmp/reports/scan-{target}-{YYMMDD}-{HHMM}/;主代理读取并验证所有分片,作为唯一报告写入者。
- 证据要求:所有模式示例必须引用真实 file:line;置信度 >80% 才可写入,60-80% 标记为未解决观察,<60% 省略或报告为材料未知。
- 新鲜度与无操作保护:通过 doc-stamp-guard.cjs 比较候选与基线,退出码 4(冲突)、0(变更)、3(无操作)分别处理;无操作扫描不写任何内容,包括时间戳。
- 强制增强步骤:变更候选在应用前需按清单要求运行 $prompt-enhance,并使用其 agent-guide 分支,防止增强恢复已删除的冗余。
- 验证:Glob 检查所有代码示例文件路径存在;Grep 检查示例中的类/令牌/变量名与实际声明一致;对代码相关主张优先使用项目图(.code-graph/graph.db)验证调用链或依赖关系,无图时直接追踪源调用者。
使用方式
调用时指定目标,例如 $scan --target=backend-patterns;通用自定义文档模式需同时提供 --filename。工具会读取 references/targets.md 注册表索引,再读取目标自己的 references/targets/<key>.md 文件,该文件提供文档路径、适用性、检测表、分区、内容规则、例外、特殊片段和增强要求。若项目配置声明了约定类,主代理按配置的附加合并流程处理。
适用场景
适用于需要按目标键更新单个参考文档、保持已验证规则和证据可追溯的维护场景;适用于代码导向的参考文档扫描,也支持显式声明的通用自定义文档。不适合同时批量更新多个目标(除非目标为 orchestrator 类型并按编排流程处理)。
限制
- 必须提供有效目标;未知键会停止。
- 自定义文档不得通过 basename 继承内建目标;缺失或未选中的文件名会阻塞扫描。
- 配置不证明代码模式存在,必须结合仓库证据;证据冲突需停止并上报。
- 不支持的必需能力会作为跳过报告,而非猜测回退。
- 项目图仅作为可选提示,缺失图不算扫描失败。
- 无操作扫描不写文件;日期重写会产生合并冲突且不增加信息。
- 子代理不得直接写最终报告;主代理是唯一写入者。