mantis-summarize

摘要器（/mantis-summarize）

系统目标

仓库映射器。自动生成目录内容的安全导向、确定性摘要，以减少后续规划和研究阶段的令牌开销。

命令定义

• 命令： /mantis-summarize
• 描述： 通过为每个目录生成安全导向摘要（mantis-summary.md），对仓库进行预处理，从而提高规划和研究效率。
• 参数（可选；由编排器提供，由 Block A 使用）： --snapshot_root/--snapshot_id/--state_root。在 PINNED 模式下，源文件在 CODE_ROOT 下读取，但跳过摘要生成（参见输出位置）。全部缺失 → MODE-OFF（与当前一样，在树内生成摘要）。

输入/输出约定

• 读取：
  • workspace/.mantis_state.json（用于跟踪当前循环轮次）。
  • 代码库目录和源文件（排除 node_modules、vendor、.git、构建输出和 tests/）。
  • 子目录摘要（子目录中的 mantis-summary.md 文件）。
  • workspace/historical_learnings.jsonl（可选，用于丰富摘要）。
• 写入：
  • 将遍历脚本写入工作区。
  • MODE-OFF：在每个源目录中生成 mantis-summary.md（与当前一样）。PINNED：跳过（参见输出位置）。
• 前置条件：
  • 源文件和目录结构必须存在。
• 幂等性保证：
  • 通过确定性地就地覆盖现有 mantis-summary.md 文件，生成更新后的汇总。

说明

步骤 0：定位器解析 + 输出位置（先执行）

LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.

输出位置（必须遵守）：

• PINNED 模式（snapshot_pinned true）：本轮跳过摘要生成。在 PINNED 模式下，CODE_ROOT 为只读（Block A 步骤 4），而使用方（plan、history、researcher）会从代码树中的源目录读取 mantis-summary.md，而不是从相对于状态目录的镜像读取。写入无人读取的镜像只会白白浪费工作。PINNED 模式下不得写入任何 mantis-summary.md 文件。（如果将来有更改让使用方读取镜像并通过来源标记重新映射，则可以重新考虑；目前 PINNED 模式下的摘要不会生效。）
• HALT 模式（存在 active_snapshot + snapshot_pinned=false）：按 MODE-OFF 处理（在每个源目录中写入 mantis-summary.md）。快照不是只读的（没有固定不可变副本），因此写入树中是安全的。
• MODE-OFF（没有 active_snapshot — 当前默认）：完全按当前方式处理 — 在每个源目录中写入 mantis-summary.md。
• 除 PINNED 外，在所有模式下，mantis-summary.md 文件都必须对所有 VCS 脏状态检查保持不可见，并且必须在任何同步之前从目标树中删除（meta-agent 会在 Block C STEP 0 中强制执行此操作）。绝不能让摘要导致树看起来处于脏状态。

你的任务是编写并执行一个脚本，遍历仓库目录树，并在每个包含源代码的目录中创建一个 mantis-summary.md 文件。

这是一个可选的预处理阶段，旨在大幅缩减策略制定者（/mantis-plan）所需的上下文窗口，并为研究人员（/mantis-researcher）提供快速参考地图。

按如下方式执行摘要阶段：

1. 编写遍历脚本（自底向上的分层遍历）： 在工作区中编写一个脚本（例如 Python 或 bash），使用自底向上（后序）遍历遍历仓库目录树。

   • 脚本必须忽略 node_modules、 vendor、.git、构建输出和 tests/ 等非源代码目录。
   • 通过自底向上遍历，脚本可确保先总结子目录，再总结其父目录。
   • 分析目录时，脚本应将该目录中的本地源文件 以及 其直属子目录的 mantis-summary.md 文件传递给大模型。不要将子目录中的原始源文件传递给父目录。
   • 分析非常大的目录时，上下文窗口大小可能会成为问题。不要批量传递文件和目录摘要，而应生成逐文件摘要或采用更高效的分块方式，以免传递过多令牌，超出大模型的处理能力。

2. 生成安全摘要（Map-Reduce）： 脚本应读取 workspace/historical_learnings.jsonl（如果存在），检查其中是否记录了与当前目录文件相关的历史漏洞和安全修复，并将这些信息作为上下文传递。脚本应指示大模型或 Agent 工具生成简洁且以安全为重点的目录摘要。为确保目录树较高层级的令牌长度合理，大模型应概括较低层级的细节，重点描述汇总后的架构。脚本使用的提示词应要求总结以下内容：

   • 核心组件： 主要文件和子目录有哪些？它们分别有什么作用？
   • API 端点和导出项： 向其他模块公开了哪些函数或类？
   • 信任边界和外部输入： 此目录是否处理不可信数据、网络请求或用户输入？
   • 敏感操作： 是否涉及解析器、加密函数或内存管理操作？
   • 历史漏洞和修复： workspace/historical_learnings.jsonl 中记录了此目录下哪些文件或组件存在历史漏洞或安全相关修复？总结过往修复、受影响组件和漏洞类别，以突出过去出现过的回归问题或反复出现的弱点。

   摘要的篇幅必须适中，以便用于较大型问题的处理，因此应控制在几千字以内。

3. 输出到 mantis-summary.md： 在 MODE-OFF（或 HALT）下，将 mantis-summary.md 写入对应的源目录（如已存在则覆盖）。在 PINNED 模式下，不要写入——本轮跳过摘要（见上文的输出位置）。绝不要写入只读快照。

4. 执行脚本： 运行刚刚编写的脚本，为整个仓库生成所有摘要。等待脚本成功完成。

5. 完成： 摘要生成后，通知用户。

完成后，请通知用户。