recover

/recover — 压缩后的上下文恢复

目的： 帮助你在上下文压缩后快速恢复进度。检测正在进行的工作（RPI 运行、evolve 周期），加载相关知识，并总结你正在做的事情以及接下来的步骤。AgentOps 3.0 的默认恢复路径是显式的（ao session bootstrap、ao codex start / ao codex stop）；Codex 原生钩子是可选的兼容功能，不会被默认启用。

你必须执行此工作流。不要只描述它。

CLI 依赖项： gt、ao、br——均为可选项。显示可用项，跳过不可用项。

折叠触发器（ag-s43tg wave 1）：trace 路由至此

• trace → 恢复证据追溯。 当你需要通过工件追溯决策时使用 — 从相关工件出发，逆向检查提交、beads、 计划和 .agents/ 证据，重建某项变更的原因。下面 Step 1 的并行证据扫描（git log、工作队列状态、知识工件）就是 trace 的追溯范围；从工件出发，沿着引用逐步追溯，并在仪表板中总结 决策链。

---

快速开始

/recover              # Full recovery dashboard
/recover --json       # Machine-readable JSON output
ao codex status       # Codex hookless lifecycle health
ao codex start        # Rebuild startup context explicitly in Codex

---

执行步骤

Step 1：检测正在进行的会话（并行）

通过并行 bash 调用运行以下所有命令：

调用 1 — RPI 分阶段状态：

if [ -f .agents/rpi/phased-state.json ]; then
  echo "=== RPI_STATE ==="
  cat .agents/rpi/phased-state.json
else
  echo "RPI_STATE=NONE"
fi

调用 2 — Evolve 周期历史：

if [ -f .agents/evolve/cycle-history.jsonl ]; then
  echo "=== EVOLVE_STATE ==="
  tail -3 .agents/evolve/cycle-history.jsonl
else
  echo "EVOLVE_STATE=NONE"
fi

调用 3 — Git 最近变更：

echo "=== GIT_STATUS ==="
git status --short

echo "=== GIT_LOG ==="
git log --oneline -5

echo "=== GIT_BRANCH ==="
git branch --show-current

调用 4 — 工作队列状态：

if command -v br &>/dev/null; then
  BEADS_DIR="$(ao beads dir)"
  echo "=== IN_PROGRESS ==="
  BEADS_DIR="$BEADS_DIR" br list --status in_progress 2>/dev/null | head -3
  echo "=== READY ==="
  BEADS_DIR="$BEADS_DIR" br ready 2>/dev/null | head -3
else
  echo "BR_UNAVAILABLE"
fi

调用 5 — 知识和消息：

# Knowledge artifacts
echo "=== KNOWLEDGE_COUNT ==="
echo "Learnings=$(ls .agents/learnings/ 2>/dev/null | wc -l | tr -d ' ')"
echo "Patterns=$(ls .agents/patterns/ 2>/dev/null | wc -l | tr -d ' ')"

# Inbox if gt available
if command -v gt &>/dev/null; then
  echo "=== MESSAGES ==="
  gt mail inbox 2>/dev/null | head -3
else
  echo "GT_UNAVAILABLE"
fi

调用 6 — Codex 生命周期（如果可用）：

if command -v ao &>/dev/null; then
  echo "=== CODEX_STATUS ==="
  ao codex status --json 2>/dev/null || echo "CODEX_STATUS=UNAVAILABLE"
else
  echo "AO_UNAVAILABLE"
fi

Step 2：从知识库加载上下文

如果检测到 RPI 状态，运行：

if command -v ao &>/dev/null; then
  ao lookup --query "rpi recovery context" --limit 5 2>/dev/null || true
fi

应用检索到的知识： 如果返回了经验总结，请逐条检查其是否适用于当前恢复上下文。引用适用的经验总结，并记录：ao metrics cite "<path>" --type applied 2>/dev/null || true

如果检测到 Codex 无钩子回退模式（v0.115.0 之前的版本，没有原生钩子），也要运行：

if command -v ao &>/dev/null && { [ -n "${CODEX_THREAD_ID:-}" ] || [ "${CODEX_INTERNAL_ORIGINATOR_OVERRIDE:-}" = "Codex Desktop" ]; }; then
  ao codex start --no-maintenance 2>/dev/null || true
fi

Step 3：解析并总结会话状态

从收集到的数据中提取：

1. RPI 检测： 如果 .agents/rpi/phased-state.json 存在：

   • 提取 goal、epic_id、phase、cycle、started_at
   • 将阶段编号映射为阶段名称（1=research，2=plan，3=implement，4=validate）
   • 显示自 started_at 起经过的时间

2. Evolve 检测： 如果 .agents/evolve/cycle-history.jsonl 存在：

   • 读取最新周期对应的最后一条记录
   • 提取 goals_fixed、result、timestamp
   • 显示最新周期摘要

3. 最近工作： 从 git log 获取：

   • 最近 3 次提交（在调用 3 中提取）
   • 未提交变更的数量

4. 待处理工作： 从 beads 获取：

   • 进行中的问题（最多 3 个）
   • 已就绪问题的数量

5. 知识状态：

   • 可用经验总结和模式的总数
   • 未读消息数（如果 gt 可用）

Step 4：呈现恢复仪表板

将收集到的数据整理成以下格式：

══════════════════════════════════════════════════════════════
  Context Recovery Dashboard
══════════════════════════════════════════════════════════════

IN-PROGRESS RPI RUN
  Epic: <epic_id>
  Goal: <first 80 chars of goal>
  Phase: <phase name: research | plan | implement | validate>
  Cycle: <cycle #>
  Started: <time ago (e.g., "2 hours ago")>
  Status: <PHASE_START | IN_PROGRESS | READY_FOR_GATE | ...>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

RECENT EVOLVE CYCLE (IF NO RPI)
  Cycle: <cycle #>
  Latest Goal: <goal_id or summary>
  Result: <result>
  Items Completed: <count or "—">
  Timestamp: <time ago>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

[NO ACTIVE SESSION]
  No RPI run or evolve cycle in progress.
  Last activity: <time of last commit or "unknown">

IN-PROGRESS WORK
  <list up to 3 in-progress issues with IDs>
  <or "No in-progress work">

READY TO WORK
  <count of ready issues>
  <or "No ready issues">

RECENT COMMITS
  <last 3 commits>

PENDING CHANGES
  <uncommitted file count or "clean">

KNOWLEDGE AVAILABLE
  Learnings: <count>  Patterns: <count>

INBOX
  <message count or "No messages" or "gt not installed">

──────────────────────────────────────────────────────────────
SUGGESTED NEXT ACTION
  <state-aware command from Step 5>
──────────────────────────────────────────────────────────────

QUICK COMMANDS
  /status       Current workflow dashboard
  /research     Deep codebase exploration
  /plan         Decompose work into issues
  /implement    Execute a single issue
  /crank        Autonomous epic execution
  /validate   Full close-out and learnings
══════════════════════════════════════════════════════════════

Step 5：建议下一步操作（根据状态判断）

从上到下评估上下文。使用第一个符合条件的项：

优先级	条件	建议
1	RPI 运行进行中 + phase=research	"继续研究：/research；如果已准备就绪，则使用 /plan"
2	RPI 运行进行中 + phase=plan	"检查计划：编码前使用 /pre-mortem 进行验证"
3	RPI 运行进行中 + phase=implement	"恢复实现：/implement <next-issue-id>"
4	RPI 运行进行中 + phase=validate	"完成周期：使用 /validate 提取经验总结并收尾"
5	Evolve 周期进行中	"继续自主改进：/evolve --resume"
6	存在进行中的问题	"继续工作：/implement <issue-id>"
8	有已就绪的问题	"选择下一个问题：/implement <first-ready-id>"
9	存在未提交的变更	"检查最近的工作：/validate"
10	状态干净，没有待处理事项	"会话已恢复。先使用 /status 规划下一项工作"

步骤 6：JSON 输出（--json 标志）

如果用户传入了 --json，则将所有恢复数据输出为结构化 JSON：

{
  "session_type": "rpi|evolve|none",
  "rpi": {
    "epic_id": "ag-l2pu",
    "goal": "Implement...",
    "phase": 2,
    "phase_name": "plan",
    "cycle": 1,
    "started_at": "2026-02-15T14:33:36-05:00",
    "elapsed_minutes": 120
  },
  "evolve": {
    "cycle": 3,
    "result": "improved",
    "goals_fixed": ["goal1", "goal2"],
    "timestamp": "2026-02-15T22:00:00-05:00"
  },
  "work_state": {
    "in_progress_count": 3,
    "in_progress_issues": ["ag-042.1", "ag-042.2"],
    "ready_count": 5,
    "uncommitted_changes": 2
  },
  "git": {
    "branch": "main",
    "recent_commits": [
      "7de51c8 feat: wave 2 — structural assertions",
      "25004f8 fix: replace per-wave vibe gate"
    ]
  },
  "knowledge": {
    "learnings_count": 12,
    "patterns_count": 5
  },
  "inbox": {
    "unread_count": 0
  },
  "suggestion": {
    "priority": 4,
    "message": "Resume implementation: /implement ag-042.1"
  }
}

使用单个代码块呈现。启用 --json 时，不显示可视化仪表盘。

---

示例

RPI 中途压缩后的恢复

用户说： /recover

发生的情况：

1. Agent 并行运行 5 次 bash 调用以收集状态
2. Agent 在 phased-state.json 中检测到 RPI 运行（phase=2，epic ag-l2pu）
3. Agent 运行 ao lookup --query "rpi recovery context" 以加载相关知识
4. Agent 显示目标、当前阶段（计划）、周期 1、开始时间为 2 小时前
5. Agent 列出 2 个进行中的问题和 3 个待处理问题
6. Agent 显示 Git 状态干净，以及最近的提交
7. Agent 建议：“审查计划：/pre-mortem，在开始编码前进行验证”

结果： 仪表盘确认 RPI 会话正在进行，加载上下文并建议下一步操作。

压缩后恢复并继续 Evolve 周期

用户说： /recover

发生的情况：

1. Agent 并行收集状态
2. Agent 未找到 RPI 运行
3. Agent 检测到 Evolve 周期（最近一次：周期 3，结果 "improved"，goals_fixed=["goal1", "goal2"]）
4. Agent 显示时间戳（1 小时前）和 items_completed（8）
5. Agent 使用 ao lookup --query "evolve cycle recovery" 加载知识
6. Agent 建议：“继续自主改进：/evolve --resume”

结果： 仪表盘确认 Evolve 周期，显示进度并提供恢复命令。

在干净状态下恢复（没有活动会话）

用户说： /recover

发生的情况：

1. Agent 并行收集状态
2. Agent 未找到 RPI 运行，也未找到 Evolve 周期
3. Agent 仅显示最近 3 次提交
4. Agent 未发现进行中的工作或待处理问题
5. Agent 显示知识库中有 12 条可用经验
6. Agent 建议：“会话已恢复。使用 /status 规划下一项工作”

结果： 仪表盘确认状态干净，并指引用户查看可用入口。

---

故障排查

问题	原因	解决方案
显示“BR_UNAVAILABLE”或“GT_UNAVAILABLE”	CLI 工具未安装或不在 PATH 中	安装缺失的工具（br / gt）。该技能会优雅降级，仅显示可用状态。
RPI 状态显示错误阶段	过时的 phased-state.json 未更新	检查 .agents/rpi/phased-state.json 的时间戳。如果已过时，可能来自之前的运行。运行 /status 以验证当前阶段。
Evolve 历史记录显示错误周期	旧的 cycle-history.jsonl 条目未清理	Tail -3 会显示最近的条目。使用 tail -20 .agents/evolve/cycle-history.jsonl 检查所有条目。
知识注入静默失败	ao CLI 未安装，或没有知识条目	确认已安装 ao：brew install ao。如果没有经验记录，运行 /validate 为知识库填充初始内容。
建议的操作与上下文不符	感知状态的规则未涵盖边缘情况	使用 --json 检查原始状态并确认匹配的条件。查看步骤 5 中的优先级表。
JSON 输出格式错误	并行 bash 调用返回了意外格式	单独检查每个 bash 调用。确保 jq 能解析实际数据。向用户返回前验证 JSON 结构。

参考文档

• references/recover.feature — 可执行规范：从 phased-state 检测 RPI 阶段、显示已认领/待处理的 br 工作、最近的 Git 状态、--json 仪表盘（soc-qk4b）