在代码审计循环开始时，把零散学习记录与代码结构分析综合成可交…

当需要为后续 agent 建立或更新架构、实体与漏洞类别的持久化知识库时，从 learnings 队列和代码快照中合成 workspace/kb/。

适用场景

解决思路

1. 先做 LOCATOR RESOLUTION：按优先级确定 CODE_ROOT —— 本次传入 --target_root 则用它（权威，覆盖 SNAPSHOT_ROOT 与 state 回退）；否则用 --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. 若 snapshot_pinned 为 true 且未走 --target_root 路径，做 SENTINEL CHECK：验证 CODE_ROOT/.mantis_snapshot_id 存在且等于 SNAPSHOT_ID，缺失或不一致则停止并报 "snapshot sentinel mismatch"（--target_root 树故意被改动，豁免 sentinel）。
3. 区分路径字段：SNAPSHOT-RELATIVE（在 CODE_ROOT 下读）包括 code_paths 条目与 plan 的 target_files 文件路径，只剥离结尾的 ":<digits>"；含 "://" 的是 URL/端点不是文件；非 <existing-path>:<integer> 形式的是非源码 LOCATOR，只检查符号/工件存在，跳过所有行范围与行存在性逻辑。STATE-RELATIVE（在 state_root/workspace 下读写，绝不加 CODE_ROOT 前缀）包括 kb_references、repro_file_path、reattack_file_path、helper 脚本、报告文件及所有 state/findings JSON。
4. snapshot_pinned 为 true 时绝不写入 CODE_ROOT；任何编译、生成或写产物的命令必须在私有影子副本（从 CODE_ROOT 用 mktemp -d 创建）中运行，绝不以 cwd=CODE_ROOT 运行；只读检查可以 cd 进 CODE_ROOT。
5. VCS 元数据例外：历史日志提取与任何 VCS diff/blame 命令在仍含 .git/.hg/.repo 的实时仓库根运行，而非 CODE_ROOT（快照副本剥离了 VCS 元数据）；不要仅因 CODE_ROOT 缺少 .git/.hg/.repo 就停止。
6. 每条 shell 命令使用绝对路径并在该次调用中设置自己的工作目录，不要假设工作目录在调用之间保持。
7. 执行 KB SNAPSHOT FRESHNESS GATE（纯机械，仅用 STATE + KB marker，不跑实时 VCS）：CUR = SNAPSHOT_ID（active_snapshot 缺失时为空串），PINNED = snapshot_pinned（缺失为 false）。
8. MODE-OFF 短路（三态规则）：若 state 中 active_snapshot 缺失（未请求 --sync），完全跳过 freshness gate，对 CODE_ROOT 做尽力而为的构建/更新，不加任何 STALE 横幅，也不写 kb_snapshot_id（与今天行为逐字节一致）；只有 HALT 与 PINNED 才跑该 gate。
9. 确定 KB_ID：优先取 .mantis_state.json 中的 kb_snapshot_id；否则若 state_root/workspace/kb/index.md 存在，取其第一行 KB_SNAPSHOT: 之后的文本（旧运行的回退）；否则为空串（无先前 KB）。state 优先，避免文件 marker 解析陷阱。
10. 按字符串检查自上而下、首个匹配胜出，恰好选一个结果：1) PINNED 为 false（HALT 模式）→ STALE/HALT：对 CODE_ROOT 尽力构建/更新，但在 index.md 首部前置 STALE 横幅，不声称时效性，设 kb_snapshot_id = CUR（live: id）。2) KB_ID == CUR（均非空）→ CURRENT：做增量更新 + 衰减检查（步骤 4），在每个（重）写文件上重打 KB_SNAPSHOT: CUR，并移除 index.md 上先前前置的 STALE 横幅。3) PINNED 为 true 且（KB_ID 为空或 KB_ID != CUR）→ BUILD FRESH（全量或范围化重建）。
11. BUILD FRESH 时选择全量或范围化：范围化失效（Phase 2 增量效率）——若 changed_files_status 已知（非 UNKNOWN）且 KB 已有 KB_SNAPSHOT 戳（KB_ID 非空但不同）且 changed_files_pass 等于当前 state.pass_number（diff 来自本 pass，缺失或不同则视为 UNKNOWN 走全量重建），则只失效源文件在 changed_files 中的 KB 条目及其父级汇总依赖者，仅从 CODE_ROOT 重新推导这些条目，其余条目原样保留，并在每个（重）写文件上重打 KB_SNAPSHOT: CUR。
12. 范围化失效时做父级汇总（2 跳，匹配 plan 的扇出）：失效变更文件 F 的 KB 条目时，同时失效直接引用 F 的条目（1 跳）以及引用 F 的 1 跳依赖者的条目（2 跳），确保孙级实体（H 导入 G，G 导入变更的 F）不会被陈旧地保留、之后作为 kb_reference 喂入而其依赖已变。
13. 范围化失效护栏：若出现任何不确定性（无法确定哪些 KB 条目映射到哪些源文件、KB 结构有歧义、或 changed_files 为空但 KB_ID != CUR），回退到全量重建；绝不把变更文件的陈旧条目保留下来。
14. 全量重建（Phase-1 回退）：若 KB_ID 为空（无先前 KB）、或 changed_files_status 为 UNKNOWN、或范围化护栏触发，则对 CODE_ROOT 从头重建每个 KB 文件；不要保留任何本 pass 未从 CODE_ROOT 重新推导的先前断言；打上 KB_SNAPSHOT: CUR；移除任何 STALE 横幅。
15. STALE 横幅逐字粘贴（替换 <KB_ID> 与 <CUR>，每行保留前导 > 使其渲染为可见引用块）：> **STALE KB WARNING — do not trust without re-verifying.** / > snapshot_pinned=false, or the KB was built against a different snapshot. / > KB_SNAPSHOT=<KB_ID> does not match active_snapshot.snapshot_id=<CUR>. / > Every SECURE/FIXED/NON_VIABLE/SAMPLE_OR_TEST claim below is UNVERIFIED / > against the current code. Re-verify before trusting; do NOT filter, skip, / > or down-prioritize work based on this KB.
16. 读取收件箱：解析 workspace/learnings.jsonl（以及存在时的 workspace/historical_learnings.jsonl），提取所有轨迹洞察、已发现漏洞、可行崩溃路径与已验证补丁。
17. 分析源码边界：在 CODE_ROOT 下检查目录结构与关键源文件（用绝对路径，不跑 VCS 命令），根据仓库内容动态识别系统核心组件、接口与信任边界；适用于软件系统（解析器、控制器、网络守护进程）、硬件/RTL 设计（IP 块、JTAG 接口、内存控制器）、IaC（云权限、VPC 边界、部署描述符）、数据/ML 流水线（数据入口、模型序列化机制、训练边界）。
18. 构建或更新知识库：在 workspace/kb/ 下用标准 Markdown 创建或更新文件，严格遵循路径 —— workspace/kb/architecture.md（高层数据流、区域定义、系统设计、整体可用性/正常运行时间要求，若文档化或可从 systemd、kubernetes、负载均衡器等配置推断）；workspace/kb/entities/[component_name].md（组件具体定义，如 auth_module.md，必须包含指向关联漏洞类别的链接并记录已知约束，如 "This module sanitizes input X"，记录组件关键性与可用性要求，分类为 CRITICAL、STANDARD 或 LOW_CRITICALITY，并纳入轨迹洞察）；workspace/kb/vulnerabilities/[CWE-ID_or_BugClass].md（历史上与本代码库相关的 bug 类别描述，如 CWE-79.md 或 Memory-Corruption.md，含不该做什么的示例）；workspace/kb/index.md（根目录，含指向上述每个文件的链接与一行摘要，是 Planner 读取的地图）。
19. 格式规则：用相对链接交叉引用实体与漏洞（如 [Auth Module](entities/auth_module.md)）；所有 markdown 文件保持简洁，聚焦可操作的安全上下文。
20. 快照打戳（跑 freshness gate 即 HALT 或 PINNED 时，每个（重）写 KB 文件必需；MODE-OFF 绝不打）：使 index.md、每个 entities/*.md、每个 vulnerabilities/*.md 的第一行恰为 <!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->（用步骤 0b 的 CUR 替换；它是 HTML 注释不渲染），这是下一 pass freshness gate 检测漂移的方式。MODE-OFF 门（三态规则）：若 active_snapshot 缺失（未请求 --sync），不要打每文件 KB_SNAPSHOT marker，因为 CUR 为空串，强制 marker 会变成 <!-- KB_SNAPSHOT: -->（空值），是 Phase 1 不存在的快照期产物；该 marker 只被步骤 0b 的 freshness gate 消费，而 MODE-OFF 完全跳过它。
21. 每文件 KB_SNAPSHOT 打戳是 KB 断言唯一的溯源机制：不要写每断言的 (AS_OF:<snapshot>) 标签 —— AS_OF 重验证读取器从未构建，陈旧保护已由 freshness gate（比较 kb_snapshot_id 与 SNAPSHOT_ID）加每 finding 的 discovery_commit（由 mantis-critic Block B 强制）提供；后来被回退的修复由这些机制捕获，而非每断言标签。
22. 验证并衰减知识（防漂移）：在最终确定 KB 更新前，对照 CODE_ROOT 下的源码（固定快照，不是实时 VCS 查询，也不是实时工作树）抽查现有 workspace/kb/entities/ 中的断言。BUILD FRESH 结果下完全不抽查：丢弃先前断言，本 pass 从 CODE_ROOT 重新推导每个实体。STALE/HALT 结果下只做尽力而为的抽查，无论结果如何都保留 STALE 横幅。
23. 若某实体文件声称某变量未净化（基于旧学习）但当前代码已含净化函数（补丁已落地），则在 KB 中删除或修正该过时学习。
24. 若某学习被当前轨迹洞察反复证明为错，主动修正它，防止 "错误学习" 持续存在并蒙蔽未来 agent。
25. 当你修正或重新确认某条由 finding 推导的断言时，在该 KB 文件上重打 KB_SNAPSHOT marker。
26. 事务性清空收件箱与归档：为防止无限循环与 token 膨胀，必须清空队列并归档 learnings。
27. 验证并定稿：以程序方式验证所有 Markdown KB 更新已成功写入磁盘且交叉引用有效；提交前还要验证每个（重）写 KB 文件以其 <!-- KB_SNAPSHOT: <SNAPSHOT_ID> --> marker 开头，且每个由 finding 推导的结论都基于当前 SNAPSHOT_ID。
28. 以移动方式提交：仅在验证综合成功后，把 workspace/learnings.jsonl 移到归档目录 —— 确保目标目录存在（如 mkdir -p workspace/archive/learnings/）；从 workspace/.mantis_state.json 读 "pass_number" 确定循环 pass 号 N，缺失或无效则扫描 workspace/archive/ 下匹配 findings_pass_N 或 loopN_findings 的文件夹，解析 N = max_found + 1，无归档则默认 1；统计 workspace/archive/learnings/ 中匹配 learnings_pass_${N}_*.jsonl 的现有文件数加 1 得子索引 X；执行 mv workspace/learnings.jsonl workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl。
29. 快照 KB（每 pass 归档）：综合成功后把整个 KB 树复制到每 pass 归档 —— 确保目录存在（mkdir -p workspace/archive/kb/）；计算子索引 X_kb = workspace/archive/kb/ 中现有 kb_pass_${N}_* 目录数 + 1；复制（不要移动 —— 实时 workspace/kb/ 必须为下一 pass 保留）：cp -a workspace/kb/. workspace/archive/kb/kb_pass_${N}_${X_kb}/。
30. 写入 state：把 kb_snapshot_id = SNAPSHOT_ID（步骤 0b 的 CUR）写入 workspace/.mantis_state.json。若 active_snapshot 缺失（MODE-OFF），不要写 kb_snapshot_id，也不要前置任何 STALE 横幅（freshness gate 已跳过）。HALT 模式下写 kb_snapshot_id = CUR 并在 index.md 中保留 STALE 横幅。
31. 若综合失败或被中断，把 workspace/learnings.jsonl 原样留在原位置，确保不丢数据。
32. 若进入时 workspace/learnings.jsonl 缺失（如 Stage-15 调用，因为 Stage-2 调用本 pass 已归档它），只跳过 learnings 移动；仍要跑 freshness gate（步骤 0b）、打 KB_SNAPSHOT marker、写 kb_snapshot_id、复制每 pass KB 归档 —— 每次调用都必须记录 KB 溯源。
33. 完成后通知用户。

适用边界 · 注意事项

• 不要用于生成威胁模型或制定执行计划（本技能只做知识库综合）。
• 不要用实时 VCS 命令（git/hg/repo）判断 KB 时效性；快照信息只从 state 读取。
• 不要在 snapshot_pinned 为 true 时写入 CODE_ROOT，也不要在 CODE_ROOT 下运行编译/生成/写产物的命令。