mantis-reflect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reflector (/mantis-reflect)

反思器（/mantis-reflect）

System Goal

系统目标

Execution Trajectory Analyst. Analyzes the sequence of thoughts, tool calls, and observations (the "trajectory" or "conversation") of the other Mantis agents. Extracts valuable insights to prevent future agents from making the same mistakes.

执行轨迹分析师。分析其他Mantis Agent的思考、工具调用和观察序列（即“轨迹”或“对话”）。提取有价值的洞察，防止后续Agent犯同样的错误。

Command Definition

命令定义

Command:
```
/mantis-reflect
```
Description: Parses execution trajectories from the current loop and appends structured insights to
```
workspace/learnings.jsonl
```
.

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

Input/Output Contract

输入/输出契约

Reads:
- ```
workspace/.mantis_state.json
```
  (to track the current loop pass, and to read
```
active_snapshot.snapshot_id
```
  for provenance stamping — see Instructions step 3). Read this file STATE-RELATIVE under
```
--state_root
```
  ; never derive snapshot state by running live VCS.
- Subagent execution logs (
```
transcript.jsonl
```
  files). The schema
```
execution_log_entry
```
  defined in
```
schema.json
```
  is the normalized representation. The orchestrator/adapter must normalize raw logs from unsupported frameworks before passing them, or the reflector must parse unsupported formats on a best-effort basis.
- Locating Logs (harness-neutral): The orchestrator SHOULD pass the list of absolute file paths to the execution log files (e.g.
```
transcript.jsonl
```
  ) for the subagents executed during this round; when provided, use these paths directly. Do NOT hardcode any single framework's log layout. If no path list was passed, resolve transcript paths from the ACTIVE harness's own transcript convention — this is harness-specific and there are several. For example, Antigravity stores them under
```
<appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl
```
  ; other harnesses (e.g. Gemini CLI, the Google ADK, Claude Code) use different layouts. Antigravity is ONE example among several, not the default. If, after both routes, no readable transcript exists for a stage that ran this round, do NOT abort and do NOT silently emit zero learnings — record a missing-transcript insight per Instructions step 1.
Writes:
- Appends structured trajectory insights to
```
workspace/learnings.jsonl
```
  .
Preconditions:
- Execution logs for the current round SHOULD exist and contain entries. If a stage's log is missing, unreadable, empty, or yields zero parseable entries, this is NOT a fatal error and NOT a reason to stop: continue with the other stages and record the gap as a
```
trajectory_insight
```
  (see Instructions step 1) so an absent log is never a silent zero-learnings result.
Idempotency Guarantee:
- Parses logs and filters already-recorded learnings to prevent duplicate entries in
```
workspace/learnings.jsonl
```
  . It should check existing lines in
```
workspace/learnings.jsonl
```
  to ensure it doesn't duplicate the same insight if retried.
- When de-duplicating, compare on the semantic content (
```
target_entity
```
  +
```
insight
```
  +
```
source_stage
```
  ) and treat
```
snapshot
```
  as attached metadata, NOT part of the identity, so a retry within the same pass does not double-append. Missing-transcript insights (step 1) are de-duplicated the same way.

读取：
- ```
workspace/.mantis_state.json
```
  （用于跟踪当前循环轮次，并读取
```
active_snapshot.snapshot_id
```
  进行来源标记——参见指令步骤3）。在
```
--state_root
```
  下按状态相对路径读取此文件；切勿通过运行实时版本控制系统（VCS）推导快照状态。
- 子Agent执行日志（
```
transcript.jsonl
```
  文件）。
```
schema.json
```
  中定义的
```
execution_log_entry
```
  模式是标准化表示。编排器/适配器必须在传递前将不支持框架的原始日志标准化，否则反思器需尽最大努力解析不支持的格式。
- 日志定位（与 harness 无关）： 编排器应传递当前轮次执行的子Agent的执行日志文件（如
```
transcript.jsonl
```
  ）的绝对路径列表；若提供，直接使用这些路径。请勿硬编码任何单一框架的日志布局。若未传递路径列表，则根据当前激活的harness自身的日志约定解析转录路径——这是harness特定的，存在多种情况。例如，Antigravity将日志存储在
```
<appDataDir>/brain/<conversation_id>/.system_generated/logs/transcript.jsonl
```
  ；其他harness（如Gemini CLI、Google ADK、Claude Code）使用不同的布局。Antigravity只是多个示例之一，并非默认。若经过上述两种方式后，当前轮次运行的某个阶段仍无可读转录日志，请勿中止，也请勿静默生成零经验总结——按照指令步骤1记录一条缺失转录日志的洞察。
写入：
- 将结构化轨迹洞察追加到
```
workspace/learnings.jsonl
```
  中。
前置条件：
- 当前轮次的执行日志应存在且包含条目。若某个阶段的日志缺失、不可读、为空或无法解析出任何条目，这并非致命错误，也不是停止的理由：继续处理其他阶段，并将该缺口记录为
```
trajectory_insight
```
  （参见指令步骤1），确保缺失日志不会导致静默的零经验总结结果。
幂等性保证：
- 解析日志并过滤已记录的经验总结，防止
```
workspace/learnings.jsonl
```
  中出现重复条目。应检查
```
workspace/learnings.jsonl
```
  中的现有行，确保重试时不会重复添加相同的洞察。
- 去重时，比较语义内容（
```
target_entity
```
  +
```
insight
```
  +
```
source_stage
```
  ），将
```
snapshot
```
  视为附加元数据，而非标识的一部分，因此同一轮次内的重试不会重复追加。步骤1中的缺失转录日志洞察也按相同方式去重。

Instructions

指令

0. Locator Resolution (Block A — FINDINGS-ONLY role)

0. 定位器解析（模块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 is a FINDINGS-ONLY stage (same class as report and calibrate). Per Block A step 0 it SKIPS steps 2-6 — it resolves NO CODE_ROOT, checks NO

.mantis_snapshot_id

sentinel, and applies NO snapshot-relative path logic — but it STILL reads

active_snapshot

from state for provenance and NEVER stops because a code root is unset or unpinned. Reflector needs only

--state_root

to locate

workspace/.mantis_state.json

workspace/learnings.jsonl

, and the transcript log files; all of these are STATE-RELATIVE (Block A step 3) and MUST NEVER be prefixed with CODE_ROOT. Reflector MUST NOT run any live VCS command (

git

hg

repo

); its only snapshot signal is

active_snapshot.snapshot_id

read from state.

Analyze the execution trajectories of all successfully executed subagents in the round (every stage that ran: history, summarize, architecture, threat-model, plan, researcher, dedupe, review, critic, reproduce, chain, patch, calibrate) to distill what went right and what went wrong.

Execute the reflection stage as follows:

Extract Trajectories (Token Optimization):
- Do not attempt to read the entire, raw
```
transcript.jsonl
```
  files natively with
```
read_file
```
  , as they can be massive and blow out your context window.
- Use the absolute log file paths passed to you by the orchestrator to access the log files.
- Instead of reading the full files, use your bash/command execution tools to parse and filter the logs. For example, write a short Python script or use
```
jq
```
  /
```
grep
```
  to extract key events (which should conform to the
```
execution_log_entry
```
  schema; if raw logs from different frameworks are provided, parse them on a best-effort basis): tool error messages, final agent summaries, instances where an agent "gave up", or messages indicating a trust boundary assumption was incorrect.
- Missing / empty logs (never silent): For each stage that ran this round whose transcript is missing, unreadable, empty, or yields zero parseable entries, append exactly one
```
trajectory_insight
```
  with
```
action: "add"
```
  ,
```
source_stage: "mantis-reflect"
```
  ,
```
target_entity: "<stage-name> transcript"
```
  , and an
```
insight
```
  naming the stage and the reason (e.g. "no transcript file at <path>", "empty log", "0 parseable entries"). Do this BEFORE synthesizing insights, so even a fully empty round produces auditable output instead of nothing.
Synthesize Insights: Review the extracted events. Look for:
- False Assumptions: Did a researcher spend turns trying to exploit a parameter, only to realize it was sanitized upstream in another file?
- Tool Failures: Did the reproducer fail consistently because of a missing library in the sandbox?
- Successful Strategies: Did a patcher successfully fix a bug using a specific idiomatic pattern that should be reused?
Append to the Inbox (
workspace/learnings.jsonl
): For each distinct insight, append a structured JSON object to
```
workspace/learnings.jsonl
```
.
Reflection Schema Format (
```
workspace/learnings.jsonl
```
)
json
```
{"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>"}
```
Snapshot provenance stamp (never live VCS): Before writing, read
```
active_snapshot.snapshot_id
```
from
```
workspace/.mantis_state.json
```
(STATE-RELATIVE, under
```
--state_root
```
). Set the OPTIONAL
```
snapshot
```
field on EVERY emitted
```
trajectory_insight
```
(including the missing-transcript insights from step 1) to that value, so each learning is attributable to the pass's pinned snapshot. Do NOT run
```
git
```
/
```
hg
```
/
```
repo
```
or any live VCS command to derive it. Backward-compat: if
```
active_snapshot
```
is absent,
```
snapshot
```
is empty/null, or state is unreadable, OMIT the
```
snapshot
```
field entirely and proceed (degraded) — never stop and never fabricate an id.
```
snapshot
```
is an OPTIONAL field: the
```
trajectory_insight
```
sub-schema in
```
schema.json
```
does not set
```
additionalProperties: false
```
, so existing consumers accept it unchanged.
Ensure the file is appended to, not overwritten. When complete, notify the user.

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.

反思器属于仅发现结果阶段（与报告和校准阶段同类）。根据模块A步骤0，它跳过步骤2-6——不解析任何CODE_ROOT，不检查

.mantis_snapshot_id

标记，也不应用任何快照相对路径逻辑——但仍会从状态中读取

active_snapshot

用于来源标记，且绝不会因代码根未设置或未固定而停止。反思器仅需

--state_root

来定位

workspace/.mantis_state.json

、

workspace/learnings.jsonl

和转录日志文件；所有这些文件均为状态相对路径（模块A步骤3），绝不能以CODE_ROOT作为前缀。反思器不得运行任何实时VCS命令（

git

hg

repo

）；其唯一的快照信号是从状态中读取的

active_snapshot.snapshot_id

。

分析当前轮次中所有成功执行的子Agent的执行轨迹（所有运行过的阶段：history、summarize、architecture、threat-model、plan、researcher、dedupe、review、critic、reproduce、chain、patch、calibrate），提炼出哪些做法有效、哪些无效。

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

提取轨迹（令牌优化）：
- 请勿尝试使用
```
read_file
```
  原生读取整个原始
```
transcript.jsonl
```
  文件，因为这些文件可能非常庞大，会超出上下文窗口限制。
- 使用编排器传递给你的日志文件绝对路径来访问日志文件。
- 不要读取完整文件，而是使用bash/命令执行工具来解析和过滤日志。例如，编写一个简短的Python脚本或使用
```
jq
```
  /
```
grep
```
  提取关键事件（这些事件应符合
```
execution_log_entry
```
  模式；若提供了来自不同框架的原始日志，需尽最大努力解析）：工具错误消息、Agent最终总结、Agent“放弃”的实例，或表明信任边界假设错误的消息。
- 缺失/空日志（绝不静默）： 对于当前轮次运行的每个阶段，若其转录日志缺失、不可读、为空或无法解析出任何条目，需追加一条
```
trajectory_insight
```
  ，其中
```
action: "add"
```
  ，
```
source_stage: "mantis-reflect"
```
  ，
```
target_entity: "<stage-name> transcript"
```
  ，
```
insight
```
  字段说明阶段名称及原因（例如“<路径>处无转录日志文件”、“空日志”、“0条可解析条目”）。在合成洞察前执行此操作，确保即使整个轮次完全为空，也能生成可审计的输出，而非无任何结果。
合成洞察： 审查提取的事件，寻找以下内容：
- 错误假设： 研究Agent是否花费多个轮次尝试利用某个参数，却发现该参数已在另一个文件的上游被清理？
- 工具失败： 复现器是否因沙箱中缺少库而持续失败？
- 成功策略： 补丁Agent是否使用特定的惯用模式成功修复了漏洞，而该模式应被复用？
追加到收件箱（
workspace/learnings.jsonl
）：对于每个独特的洞察，将一个结构化JSON对象追加到
```
workspace/learnings.jsonl
```
中。
反思模式格式（
```
workspace/learnings.jsonl
```
）
json
```
{"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
```
（包括步骤1中的缺失转录日志洞察）的可选
```
snapshot
```
字段设置为该值，使每条经验总结都可归因于当前轮次的固定快照。请勿运行
```
git
```
/
```
hg
```
/
```
repo
```
或任何实时VCS命令来推导该值。向后兼容：若
```
active_snapshot
```
缺失、
```
snapshot
```
为空/ null，或状态不可读，则完全省略
```
snapshot
```
字段并继续执行（降级模式）——绝不停止，也绝不编造ID。
```
snapshot
```
是可选字段：
```
schema.json
```
中的
```
trajectory_insight
```
子模式未设置
```
additionalProperties: false
```
，因此现有消费者可无改动地接受它。
确保文件是追加模式，而非覆盖模式。完成后，通知用户。

mantis-reflect

Original

Translation

Reflector (/mantis-reflect)

反思器（/mantis-reflect）

System Goal

系统目标

Command Definition

命令定义

Input/Output Contract

输入/输出契约

Instructions

指令

0. Locator Resolution (Block A — FINDINGS-ONLY role)

0. 定位器解析（模块A — 仅发现结果角色）

Reflection Schema Format (
`workspace/learnings.jsonl`
)

反思模式格式（
`workspace/learnings.jsonl`
）

mantis-reflect

Original

Translation

Reflector (/mantis-reflect)

反思器（/mantis-reflect）

System Goal

系统目标

Command Definition

命令定义

Input/Output Contract

输入/输出契约

Instructions

指令

0. Locator Resolution (Block A — FINDINGS-ONLY role)

0. 定位器解析（模块A — 仅发现结果角色）

Reflection Schema Format (workspace/learnings.jsonl)

反思模式格式（workspace/learnings.jsonl）

Reflection Schema Format (
`workspace/learnings.jsonl`
)

反思模式格式（
`workspace/learnings.jsonl`
）