在代码审查活动开始前为#每个目录生成安全摘要以降低后续规划与…

在启动安全审查活动、需要先映射代码库时，用自底向上的遍历为每个源码目录生成安全聚焦的 mantis-summary.md 摘要。

适用场景

解决思路

1. 先做定位解析（Locator Resolution）：按优先级确定 CODE_ROOT——本次调用传入的 --target_root 优先且权威，覆盖 SNAPSHOT_ROOT 与状态回退；否则用 --snapshot_root（或 SNAPSHOT_ROOT）；否则读 state_root/workspace/.mantis_state.json 的 active_snapshot.root/.snapshot_id/.snapshot_pinned；都没有则 CODE_ROOT=当前目录并视 snapshot_pinned=false（MODE-OFF），不要停止。
2. 若本技能从不读取目标源码（如 report、calibrate、reflect），则视为 FINDINGS-ONLY 阶段：跳过步骤 2-6，但仍从状态读取 active_snapshot 用于溯源/标注，且不因代码根未设置而停止。
3. 仅当 snapshot_pinned 为 true 且未走 --target_root 路径时做哨兵检查：验证 CODE_ROOT/.mantis_snapshot_id 存在且等于 SNAPSHOT_ID，缺失或不一致则停止并报 “snapshot sentinel mismatch”；--target_root 树被有意改动，哨兵豁免。
4. 区分路径字段：SNAPSHOT-RELATIVE（在 CODE_ROOT 下读取）包括 code_paths 条目、plan 中作为文件路径的 target_files，仅剥离末尾的 ":<digits>"；含 "://" 的 code_paths 是 URL/端点而非文件读取；非 <existing-path>:<integer> 形式的 code_paths 是非源码 LOCATOR（符号/偏移/端点），只检查其存在，跳过所有行范围与行存在性逻辑。STATE-RELATIVE（在 state_root/workspace 下读写，绝不加 CODE_ROOT 前缀）包括 kb_references、repro_file_path、reattack_file_path、辅助脚本、报告文件及所有状态/发现 JSON。
5. snapshot_pinned 为 true 时绝不写入 CODE_ROOT；任何编译、生成或写产物的命令必须在私有影子副本（用 mktemp -d 从 CODE_ROOT 复制）中运行，绝不以 cwd=CODE_ROOT 执行；只读检查可以 cd 进 CODE_ROOT。
6. VCS 元数据例外：历史日志提取及任何 VCS diff/blame 命令在仍含 .git/.hg/.repo 的实时仓库根运行，而非 CODE_ROOT（快照副本剥离了 VCS 元数据）；不因 CODE_ROOT 缺少 .git/.hg/.repo 而停止。
7. 每条 shell 命令使用绝对路径，并在该次调用中自行设置工作目录，不要假设工作目录在调用之间保持。
8. 确定输出位置：PINNED 模式（snapshot_pinned 为 true）本次跳过摘要，不写任何 mantis-summary.md（CODE_ROOT 只读，消费者从代码树源目录读取摘要，写无人读取的镜像会浪费工作）；HALT 模式（存在 active_snapshot 且 snapshot_pinned=false）按 MODE-OFF 处理，把 mantis-summary.md 写入各源目录；MODE-OFF（无 active_snapshot，默认）同样写入各源目录。除 PINNED 外，mantis-summary.md 必须对所有 VCS 脏检查不可见，并在任何同步前从目标树删除，绝不让摘要使树看起来变脏。
9. 编写遍历脚本（自底向上分层）：在工作区写一个脚本（如 Python 或 bash），用后序遍历（bottom-up/post-order）遍历仓库目录树，确保子目录先于父目录被摘要。
10. 脚本忽略非源码目录，如 node_modules、vendor、.git、构建产物和 tests/。
11. 分析某目录时，把该目录的本地源码文件加上其直接子目录的 mantis-summary.md 传给 LLM，不要把子目录的原始源码文件传给父目录。
12. 分析超大目录时若上下文窗口吃紧，不要批量传入文件与目录摘要，改为生成逐文件摘要或按更高效的块处理，避免传入过多 token。
13. 生成安全摘要（Map-Reduce）：脚本读取 workspace/historical_learnings.jsonl（若存在），检查与当前目录文件相关的历史漏洞与安全修复并放入上下文，指示 LLM 或 agent 工具生成简洁、安全聚焦的目录摘要；在目录树更高层要抽象掉低层细节，聚焦汇总后的架构，以保持 token 长度合理。
14. 摘要提示词需覆盖：Core Components（主要文件与子目录及其作用）；API Endpoints & Exports（暴露给其他模块的函数或类）；Trust Boundaries & External Inputs（是否处理不可信数据、网络请求或用户输入）；Sensitive Operations（是否有解析器、加密函数或内存管理操作）；Historical Vulnerabilities & Fixes（该目录中哪些文件或组件在 workspace/historical_learnings.jsonl 中有历史漏洞或安全修复记录，总结过往修复、受影响组件与漏洞类别，以突出回归或反复出现的弱点）。
15. 摘要规模控制在数千词以内，以便嵌入更大问题的处理中。
16. 输出到 mantis-summary.md：在 MODE-OFF（或 HALT）下写入对应源目录（存在则覆盖）；PINNED 模式下不写，本次跳过摘要；绝不写入只读快照。
17. 执行刚写的脚本，在仓库中生成所有摘要，等待其成功完成。
18. 完成后通知用户。

适用边界 · 注意事项

• 不用于执行代码审查、编写测试脚本或修补代码。
• PINNED 模式（snapshot_pinned 为 true）下不适用，本次跳过摘要且不写入任何 mantis-summary.md。
• 无源码文件与目录结构时无法使用（前置条件要求源码与目录结构存在）。