skill-resume

宿主：Codex CLI — 此技能最初为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前启用的 Codex shell 和子 Agent 工具。在当前会话尚未提供相关能力前，不要声称某个提供方、模型或宿主子 Agent 可用。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

会话恢复

概述

恢复先前会话的上下文，并从上次中断处无缝继续工作流。

核心原则： 检查状态 → 加载自适应上下文 → 显示恢复摘要 → 转到适当操作。

使用时机

用户说以下内容时使用此技能：

• “恢复”或“继续工作”
• “从上次中断的地方继续”
• “我之前在做什么？”
• “恢复会话”
• “接着上次继续”

以下情况不要使用：

• 开始新项目（使用 /octo:embrace）
• 仅检查当前状态（使用 /octo:status）
• 直接修改状态（使用 octo-state.sh）

流程

阶段 0：检查会话交接文件（v9.6.0）

步骤 0：检查会话交接文件

检查 .octo/ 之前，先查找会话交接文件。PreCompact 和 SessionEnd 钩子会自动写入此文件，其中包含上次会话的易读摘要。 该文件位于 octopus state-path 返回的工作流状态文件旁边，处于项目检出目录之外。旧版本会将 .octo-continue.md 写入项目根目录；仅当不存在已迁移的交接文件时才读取该副本，并且绝不要修改、移动或删除它。

HANDOFF_FILE=""
if WORKFLOW_STATE_FILE="$(octopus state-path)" && [[ -n "$WORKFLOW_STATE_FILE" ]]; then
    HANDOFF_FILE="$(dirname "$WORKFLOW_STATE_FILE")/continue.md"
fi
if [[ -n "$HANDOFF_FILE" && -f "$HANDOFF_FILE" ]]; then
    cat "$HANDOFF_FILE"
elif [[ -f ".octo-continue.md" ]]; then
    cat ".octo-continue.md"
fi

如果找到交接文件，请向用户显示其内容作为上下文。然后继续阶段 1 加载完整状态。交接文件提供快速概览；.octo/STATE.md 才是权威状态。如果显示的是旧版 .octo-continue.md，请告知用户该文件已不再更新，可以从项目中删除。

阶段 1：检查项目初始化状态

恢复仓库功能

在查找转录记录或仅存在于本机的 .octo 状态之前，先检查可移植的功能产物：

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}"
python3 "$OCTO_ROOT/scripts/helpers/feature-contract.py" resume --root "$(pwd -P)" --explicit "<feature directory or spec path, empty when omitted>"

明确无误的功能可从仓库中恢复意图、决策、未完成标记以及稳定的已完成／待处理任务 ID。历史完成情况仅作为上下文，仍需重新验证。原始运行时文件缺失属于预期情况。如果存在多个互不相关的功能，请让用户选择一个；绝不要按最近时间选择。将选定的功能传递给现有的 agent-resume 编排流程。明确指定的 Claude Agent ID 仍会继续使用转录记录。

只有规格说明的功能仅恢复规划。包含计划／任务的功能会通过相同的策略、澄清、分析和波次验证关卡，继续执行待处理的实现。在下一次 plan/develop 边界之前，使用宿主的原生提问工具运行一次返回的决策批次。跳过的决策应保持未完成状态。

步骤 1：确认 .octo/ 目录存在

if [[ ! -d ".octo" ]]; then
    echo "No project state found"
    exit 1
fi

如果 .octo/ 不存在，但步骤 0 找到了交接文件，请显示其内容，并提供基于该上下文开始新会话的选项。

如果两者都不存在，请显示：

## Session Restoration Failed

**No project state found.**

There is no machine-local `.octo/` directory. Check the portable feature artifacts before treating this as a fresh project.

### Get Started

Run `/octo:embrace [your project description]` to start a new project.

**Example:**

/octo:embrace build a REST API with user authentication

This will:
1. Initialize .octo/ directory with STATE.md, PROJECT.md, ROADMAP.md
2. Begin the Double Diamond workflow
3. Create session state you can resume later

到此停止——不要继续阶段 2。

阶段 2：读取当前状态

步骤 1：执行 octo-state.sh read_state

./scripts/octo-state.sh read_state

预期输出格式：

schema=2.0
last_updated=2026-02-02T10:30:00Z
current_phase=2
current_position=define-requirements
status=in_progress

步骤 2：解析状态变量

提取以下关键值：

• current_phase - 阶段编号（1-4）
• current_position - 阶段内当前位置的描述
• status - 工作流状态（in_progress、blocked、complete、paused 等）
• last_updated - 上次修改状态的时间戳

阶段 3：加载自适应上下文

步骤 1：获取上下文层级（自动模式）

./scripts/octo-state.sh get_context_tier auto

系统会根据当前状态自动选择合适的上下文层级：

状态	选择的层级	加载的上下文
ready、planned、planning、complete、shipped	planning	STATE.md + PROJECT.md + ROADMAP.md
building、in_progress	execution	+ 阶段计划 + 近期摘要
blocked、paused	execution	+ 阶段计划 + 近期摘要

步骤 2：存储上下文以供参考

返回的上下文包括：

• 当前状态详情
• 项目愿景和需求
• 特定阶段的计划和摘要
• 代码库分析（如果是棕地项目）

阶段 4：提取历史记录和阻碍项

步骤 1：读取 STATE.md 中最近 3 条历史记录

# Extract history section from STATE.md
grep -A 4 "^## History" .octo/STATE.md | tail -n 3

预期格式：

- [2026-02-02T10:30:00Z] Phase 2: Completed requirements review (complete)
- [2026-02-02T09:15:00Z] Phase 2: Started define phase (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)

步骤 2：从 STATE.md 中提取阻碍项

# Extract blockers section
sed -n '/^## Blockers/,/^## /p' .octo/STATE.md | head -n -1 | tail -n +2

预期格式：

• 如果存在阻碍项：阻碍项列表
• 如果没有阻碍项：(none)

步骤 3：从 PROJECT.md 中读取项目标题

# Get project title (first H1)
head -n 5 .octo/PROJECT.md | grep "^# " | head -1 | sed 's/^# //'

阶段 5：显示恢复摘要

步骤 1：生成并显示摘要

## Session Restored

**Project:** {project_title from PROJECT.md}
**Last Active:** {last_updated from STATE.md}
**Phase:** {current_phase} - {phase_name}
**Position:** {current_position}
**Status:** {status}

### Where You Left Off

{Last 3 entries from STATE.md history}

### Current Blockers

{Blockers from STATE.md or "None"}

### Ready to Continue

{Intelligent suggestion based on status - see routing table below}

步骤 2：将阶段编号映射为名称

阶段	名称
1	发现
2	定义
3	开发
4	交付

阶段 6：智能路由

步骤 1：根据状态进行路由

状态	操作	消息
in_progress	继续当前阶段	"继续当前阶段。上下文已加载。"
blocked	查看阻碍项	"请先查看阻碍项：/octo:issues"
complete	准备进入下一阶段	"阶段已完成。准备好运行 /octo:ship"
paused	恢复项目	"项目已暂停。使用 /octo:embrace 恢复。"
ready	开始工作流	"准备开始。运行 /octo:embrace 以启动。"
planning	继续规划	"继续规划。使用 /octo:define 完善方案。"
building	继续构建	"继续实施。使用 /octo:develop。"
shipped	项目已交付	"项目已交付！请在 LESSONS.md 中查看经验总结。"
complete_with_gaps	查看差距	"阶段已完成，但仍有差距。继续之前请查看 ISSUES.md。"

步骤 2：阶段专属指南（适用于 in_progress 状态）

阶段 1（发现）：

Continue research and exploration.
- Use `/octo:research [topic]` for multi-AI research
- Use `/octo:debate [question]` for decision support
- Check `.octo/phases/phase1/` for research notes

阶段 2（定义）：

Continue requirements clarification.
- Use `/octo:prd` to write product requirements
- Use `/octo:define` to refine scope
- Check `.octo/phases/phase2/` for requirements docs

阶段 3（开发）：

Continue implementation.
- Use `/octo:develop` to build features
- Use `/octo:tdd` for test-driven development
- Check `.octo/phases/phase3/` for implementation plan

阶段 4（交付）：

Continue validation and delivery.
- Use `/octo:deliver` for final review
- Use `/octo:security` for security audit
- Use `/octo:ship` to finalize delivery

输出示例

示例 1：未找到项目状态

## Session Restoration Failed

**No project state found.**

There is no machine-local `.octo/` directory. Check the portable feature artifacts before treating this as a fresh project.

### Get Started

Run `/octo:embrace [your project description]` to start a new project.

示例 2：成功恢复（进行中）

## Session Restored

**Project:** User Authentication System
**Last Active:** 2026-02-02T10:30:00Z
**Phase:** 2 - Define
**Position:** define-requirements
**Status:** in_progress

### Where You Left Off

- [2026-02-02T10:30:00Z] Phase 2: Started requirements review (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)
- [2026-02-01T14:20:00Z] Phase 1: Research synthesis complete (in_progress)

### Current Blockers

None

### Ready to Continue

Continue with current phase. Context loaded.

Continue requirements clarification.
- Use `/octo:prd` to write product requirements
- Use `/octo:define` to refine scope
- Check `.octo/phases/phase2/` for requirements docs

示例 3：恢复受阻的项目

## Session Restored

**Project:** E-commerce Platform
**Last Active:** 2026-02-01T18:00:00Z
**Phase:** 3 - Develop
**Position:** implement-payment-gateway
**Status:** blocked

### Where You Left Off

- [2026-02-01T18:00:00Z] Phase 3: Payment integration blocked (blocked)
- [2026-02-01T15:30:00Z] Phase 3: Started payment gateway integration (in_progress)
- [2026-02-01T12:00:00Z] Phase 3: Completed user auth implementation (complete)

### Current Blockers

- Missing Stripe API credentials
- Payment webhook endpoint not configured
- SSL certificate pending for payment domain

### Ready to Continue

Review blockers first: `/octo:issues`

**To unblock:**
1. Configure Stripe API credentials in environment
2. Set up webhook endpoint at /api/webhooks/stripe
3. Complete SSL certificate setup for payments subdomain

示例 4：恢复已暂停的项目

## Session Restored

**Project:** Data Analytics Dashboard
**Last Active:** 2026-01-28T09:00:00Z
**Phase:** 2 - Define
**Position:** requirements-gathering
**Status:** paused

### Where You Left Off

- [2026-01-28T09:00:00Z] Phase 2: Project paused by user (paused)
- [2026-01-27T16:00:00Z] Phase 2: Stakeholder feedback pending (in_progress)
- [2026-01-27T10:00:00Z] Phase 1: Discovery complete (complete)

### Current Blockers

- Waiting for stakeholder availability

### Ready to Continue

Project paused. Resume with `/octo:embrace`

When ready to continue:
1. Review `.octo/PROJECT.md` for project context
2. Check `.octo/STATE.md` for pause reason
3. Run `/octo:embrace` to resume workflow

最佳实践

1. 始终使用 octo-state.sh 读取状态

推荐：

./scripts/octo-state.sh read_state
./scripts/octo-state.sh get_context_tier auto

不推荐：

# Parse STATE.md manually
grep "Current Phase" .octo/STATE.md

2. 完整恢复上下文

推荐：

• 加载自适应上下文层级
• 显示最近 3 条历史记录
• 显示任何阻碍项
• 提供阶段专属指南

不推荐：

• 仅显示当前阶段
• 忽略历史记录
• 不提供后续步骤

3. 根据状态智能路由

推荐：

Status: blocked → "Review blockers first: /octo:issues"

不推荐：

Status: blocked → "Continue working"

注意事项——请勿这样做

操作	错误原因
跳过 .octo/ 存在性检查	会导致令人困惑的错误
恢复时忽略阻碍项	用户不知道项目为何停滞
从头开始	丢失所有先前的上下文和进度
跳过历史记录显示	用户无法了解已完成的工作
使用硬编码的上下文层级	应根据当前状态进行调整

与其他技能集成

与 /octo:status 集成

/octo:resume → Full restoration with context
/octo:status → Quick dashboard without restoration

与 /octo:embrace 集成

No .octo/ exists → /octo:resume suggests /octo:embrace
.octo/ exists but paused → /octo:resume suggests resuming with /octo:embrace

与 flow-* 技能集成

User runs /octo:resume
→ Context restored
→ User continues with /octo:develop (or appropriate phase skill)

快速参考

用户输入	所需操作
"resume"	使用 octopus state-path 解析状态 → 加载上下文 → 显示摘要 → 路由
"continue"	与 resume 相同
"pick up where I left off"	与 resume 相同
"what was I doing"	与 resume 相同，并突出显示历史记录
"restore session"	与 resume 相同

核心要点

Run `octopus state-path` → Read state → Load adaptive context → Show history + blockers → Route intelligently
Otherwise → User loses previous context and wastes time re-discovering where they were

只要状态仍然存在，就绝不要从头开始。恢复上下文、展示历史记录并智能路由。

压缩后恢复上下文

当上下文被清除时（压缩、退出计划模式或开启新会话），自动检测并重新加载：

# Auto-detect context loss without writing into the project checkout.
# The plugin executable resolves its own installation root on every host.
if ! WORKFLOW_STATE_FILE="$(octopus state-path)" || [[ -z "$WORKFLOW_STATE_FILE" ]]; then
    echo "Unable to resolve persistent workflow state; refusing an incomplete resume." >&2
    exit 1
fi
if [[ -f "$WORKFLOW_STATE_FILE" ]] && [[ -z "${WORKFLOW_CONTEXT_LOADED}" ]]; then
    echo "⚠️  Context was cleared — reloading from persistent state..."
    NEEDS_RESUME=true
fi

上下文清除后仍然保留的内容：

• 主机工作区项目状态（决策、上下文、指标；使用 octopus state-path 解析）
• octopus state-path 返回路径旁的 context/*.md（阶段输出）
• 原生任务（TaskList 仍可使用）
• Git 提交和 WIP 检查点
• ~/.claude-octopus/results/ 中的多 AI 综合文件

恢复完成后，设置 export WORKFLOW_CONTEXT_LOADED=true，以防止重复加载。

状态会持久保存在文件中。上下文清除不是问题。文件比记忆更长久。