mantis-reflect

Reflector（/mantis-reflect）

系统目标

执行轨迹分析师。分析其他 Mantis Agent 的思考、工具调用和观察结果序列（即“轨迹”或“对话”），提取有价值的见解，避免后续 Agent 重蹈覆辙。

命令定义

• 命令： /mantis-reflect
• 描述： 解析当前循环中的执行轨迹，并将结构化见解追加到 workspace/learnings.jsonl。

输入/输出约定

• 读取：
  • workspace/.mantis_state.json（用于跟踪当前循环轮次，并读取 active_snapshot.snapshot_id 以标注来源，详见说明步骤 3）。在 --state_root 下以相对于状态目录的方式读取此文件；绝不能通过运行实时 VCS 来推导快照状态。
  • 子 Agent 的执行日志（transcript.jsonl 文件）。schema.json 中定义的 execution_log_entry 架构是规范化后的表示形式。编排器/适配器必须先规范化不受支持框架的原始日志再传入；或者，reflector 必须尽力解析不受支持的格式。
  • 日志定位（与执行环境无关）： 编排器应传入本轮执行的子 Agent 执行日志文件（例如 transcript.jsonl）的绝对路径列表；如果提供了路径，请直接使用。不要对任何单一框架的日志布局进行硬编码。如果没有传入路径列表，则根据当前执行环境自身的 transcript 约定解析路径——此约定因执行环境而异，且存在多种约定。例如，Antigravity 将其存储在 <appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl 下；其他执行环境（例如 Gemini CLI、Google ADK、Claude Code）使用不同的布局。Antigravity 只是多个示例之一，并非默认选项。如果通过上述两种方式均找不到本轮运行阶段的可读 transcript，不要中止，也不要悄然输出零条学习内容——请按照说明步骤 1 记录一条缺失 transcript 的见解。
• 写入：
  • 将结构化轨迹见解追加到 workspace/learnings.jsonl。
• 前置条件：
  • 当前轮次的执行日志应该存在且包含条目。如果某个阶段的日志缺失、无法读取、为空或未能解析出任何条目，这不是致命错误，也不是停止的理由：继续处理其他阶段，并将这一缺口记录为 trajectory_insight（参见说明步骤 1)，确保日志缺失不会导致悄然产生零条学习内容。
• 幂等性保证：
  • 解析日志并筛除已记录的学习内容，避免在 workspace/learnings.jsonl 中生成重复条目。应检查 workspace/learnings.jsonl 中已有的行，以确保重试时不会重复记录相同的见解。
  • 去重时，根据语义内容（target_entity + insight + source_stage）进行比较，并将 snapshot 视为附加元数据，而非身份标识的一部分，以免同一轮次内重试时重复追加。缺失 transcript 的见解（步骤 1）也采用相同方式去重。

说明

0. 定位器解析（Block A — 仅负责发现）

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.

Reflector 是仅负责发现的阶段（与 report 和 calibrate 属于同一类别）。根据 Block A 步骤 0，它跳过步骤 2-6——不解析任何 CODE_ROOT，不检查 .mantis_snapshot_id 标记文件，也不应用任何相对于快照的路径逻辑——但仍会从状态中读取 active_snapshot 以标注来源，并且绝不会因代码根目录未设置或未固定而停止。Reflector 只需使用 --state_root 定位 workspace/.mantis_state.json、workspace/learnings.jsonl 和 transcript 日志文件；这些路径均相对于状态目录（Block A 步骤 3），绝不能以 CODE_ROOT 为前缀。Reflector 绝不能运行任何实时 VCS 命令（git/hg/repo）；唯一的快照信号是从状态中读取的 active_snapshot.snapshot_id。 分析本轮所有成功执行的子 Agent 的执行轨迹（所有运行过的阶段：history、summarize、architecture、threat-model、plan、researcher、dedupe、review、critic、reproduce、chain、patch、calibrate），总结哪些环节做得好，哪些环节出了问题。

按以下步骤执行反思阶段：

1. 提取轨迹（优化 Token 使用）：

   • 不要尝试使用 read_file 原样读取完整的 transcript.jsonl 文件，因为这些文件可能非常大，会耗尽上下文窗口。

   • 使用编排器传给你的绝对日志文件路径访问日志文件。

   • 不要读取整个文件，而是使用 bash／命令执行工具解析和筛选日志。例如，编写简短的 Python 脚本，或使用 jq／grep 提取关键事件（这些事件应符合 execution_log_entry 架构；如果提供的是来自不同框架的原始日志，则尽力解析）：工具错误消息、Agent 最终总结、Agent“放弃”的情况，或表明信任边界假设有误的消息。

   • 日志缺失／为空（不可静默处理）： 对于本轮运行过的每个阶段，如果其 transcript 缺失、无法读取、为空或未能解析出任何条目，则追加且仅追加一个 trajectory_insight，其 action: "add"、source_stage: "mantis-reflect"、target_entity: "<stage-name> transcript"，并在 insight 中说明阶段名称及原因（例如“路径 下没有 transcript 文件”“日志为空”“可解析条目数为 0”）。必须在综合洞见之前执行此操作，以确保即使整轮日志完全为空，也能生成可审计的输出，而不是毫无记录。

2. 综合洞见： 审查提取的事件，寻找以下情况：

   • 错误假设： 研究人员是否花了多轮尝试利用某个参数，后来才发现该参数已在另一个文件中经过上游清理？
   • 工具故障： 复现人员是否因沙盒中缺少某个库而反复失败？
   • 成功策略： 修补人员是否使用了某种惯用模式成功修复错误，值得复用？

3. 追加到收件箱（workspace/learnings.jsonl）： 对每条不同的洞见，向 workspace/learnings.jsonl 追加一个结构化 JSON 对象。

   反思架构格式（workspace/learnings.jsonl）

   {"type": "trajectory_insight", "action": "add | update | remove", "target_entity": "[e.g., auth_module.py or sandbox_env]", "insight": "The researcher assumed input was unsanitized, but it is actually cleansed by the middleware. Do not attempt XSS on this parameter.", "source_stage": "mantis-researcher", "snapshot": "<active_snapshot.snapshot_id from state; omit field entirely if unavailable>"}
   

   快照来源标记（绝不使用实时 VCS）： 写入前，从 workspace/.mantis_state.json（在 --state_root 下，相对于状态目录）读取 active_snapshot.snapshot_id。将该值设置为每条已输出 trajectory_insight 的可选 snapshot 字段（包括第 1 步中的缺失 transcript 洞见），以便将每条学习记录关联到本轮固定的快照。不得运行 git／hg／repo 或任何实时 VCS 命令来推导该值。向后兼容：如果 active_snapshot 不存在、snapshot 为空／为 null，或状态文件无法读取，则完全省略 snapshot 字段并继续处理（降级执行）——绝不停止，也绝不捏造 ID。snapshot 是可选字段：schema.json 中的 trajectory_insight 子架构未设置 additionalProperties: false，因此现有使用方可以照常接受该字段。

   确保追加到文件，而不是覆盖文件。完成后通知用户。