agent-session-resume

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Session Resume

Agent 会话恢复

Purpose

用途

Resume or audit prior coding-agent work with continuity. Reconstruct what happened before acting, then continue from the real stopping point.

在保持连续性的情况下恢复或审计此前的编程 Agent 工作。采取行动前重建之前发生的事情，然后从实际停止点继续。

Core Workflow

核心工作流

Run a provenance self-check.
- Run
```
python3 skills/agent-session-resume/scripts/skill-provenance.py
```
  when available.
- Otherwise compare the loaded SKILL.md path and size against the known install paths under
```
$HOME/.claude
```
  and
```
${CODEX_HOME:-$HOME/.codex}
```
  .
- Report staleness on the
```
Loaded skill
```
  line of the resume report. Details:
```
references/evidence-and-provenance.md
```
  .
Identify the source. If the user names a platform, read the matching file in
```
references/
```
; if the ask spans platforms, read
```
references/cross-platform.md
```
. Otherwise inspect the workspace for session folders, exports, summaries, and artifacts. When a session title is given, prefer exact or fuzzy title matches over recency.
Locate the transcript or best substitute. Prefer full transcripts over summaries, workspace-local session data over global history, and explicit user-provided paths over discovered paths.
Read the full available session record before acting. For large transcripts, inventory files, event types, and timestamps first, then read the evidence-bearing slices until the record is accounted for. Full coverage means no relevant evidence skipped; bounded searches and slices are fine for giant records, but say so and name the file/event. Do not edit files or repeat prior work before this pass is complete.
Record loaded-skill provenance in the report: path and source/version marker, or
```
unknown
```
, never a guess. Details:
```
references/evidence-and-provenance.md
```
.
Reconstruct context. Summarize the goal, decisions, constraints, and preferences; identify completed work, changed files, commands and tests run; pin the exact stopping point. Every work-state claim carries an evidence ref (
```
src/file.ts:L20-L35
```
, transcript lines, command output, or explicit "not checked yet"). Prior resume reports, summaries, and handoffs are claims, not primary evidence: re-verify against transcripts, files, git state, or command output, or label them unverified. Preserve explicit user deferrals ("skip", "park", "not now", "hold") with evidence, scope, and reopen condition.
Extract tasks. Capture explicit TODOs, plans, and open questions; infer implicit tasks from failing tests, unfinished edits, and "next step" language. Keep specific unfinished tasks specific. Track deferred work separately from
```
NOT DONE
```
. Classify:
```
DONE
```
(completed and verified, or no longer needed),
```
PARTIALLY DONE
```
(started but missing implementation, tests, review, commit, push, or confirmation),
```
NOT DONE
```
(not started or only discussed).
Validate against the workspace. Inspect git status before editing and mention it in the checkpoint; read files the prior session touched. Preserve unrelated user changes in a dirty worktree; use a separate worktree or ask before colliding work. If transcript claims conflict with current files, trust current files and report the mismatch.
Continue from the first unfinished step. Do not repeat completed work; follow the established approach and style unless clearly broken. Ask the user only when blocked by missing information or an unsafe choice.

执行来源可追溯性自检。
- 如果可用，运行
```
python3 skills/agent-session-resume/scripts/skill-provenance.py
```
  。
- 否则，将已加载的
```
SKILL.md
```
  路径和大小与
```
$HOME/.claude
```
  和
```
${CODEX_HOME:-$HOME/.codex}
```
  下的已知安装路径进行比较。
- 在恢复报告的
```
Loaded skill
```
  行中报告陈旧状态。详情：
```
references/evidence-and-provenance.md
```
  。
确定来源。如果用户指定了平台，读取
```
references/
```
中对应的文件；如果请求跨多个平台，读取
```
references/cross-platform.md
```
。否则，检查工作区中的会话文件夹、导出内容、摘要和产物。给定会话标题时，优先使用精确或模糊的标题匹配，而不是按最近时间选择。
定位会话记录或最佳替代材料。优先使用完整记录而非摘要，优先使用工作区本地的会话数据而非全局历史记录，并优先采用用户明确提供的路径而非自行发现的路径。
采取行动前，读取所有可用的会话记录。对于大型记录，先清点文件、事件类型和时间戳，再读取承载证据的片段，直至记录内容全部得到处理。完整覆盖意味着不跳过任何相关证据；对于超大记录，可以进行有边界的搜索和片段读取，但应说明这一点并指出具体文件或事件。在此轮读取完成前，不要编辑文件或重复之前的工作。
在报告中记录已加载 skill 的来源可追溯性：路径及来源/版本标记，或
```
unknown
```
，绝不作猜测。详情：
```
references/evidence-and-provenance.md
```
。
重建上下文。概括目标、决策、约束和偏好；识别已完成的工作、变更过的文件、执行过的命令和测试；确定准确的停止点。每项有关工作状态的断言都必须附有证据引用（
```
src/file.ts:L20-L35
```
、会话记录中的行、命令输出，或明确的“not checked yet”）。先前的恢复报告、摘要和交接信息只是声明，而非主要证据：必须对照会话记录、文件、git 状态或命令输出重新验证，否则应标记为未经验证。保留用户明确暂缓的事项（“skip”、“park”、“not now”、“hold”），同时记录证据、范围和重新开启条件。
提取任务。收集明确的 TODO、计划和开放问题；从失败的测试、未完成的编辑以及“next step”表述中推断隐含任务。保持具体未完成任务的准确性。将暂缓工作与
```
NOT DONE
```
分开跟踪。分类：
```
DONE
```
（已完成并验证，或已不再需要）、
```
PARTIALLY DONE
```
（已开始，但缺少实现、测试、审查、提交、推送或确认）、
```
NOT DONE
```
（尚未开始或仅讨论过）。
针对工作区进行验证。编辑前检查 git status，并在检查点中说明；读取上一会话涉及的文件。保留脏工作区中与当前任务无关的用户改动；使用独立 worktree，或在可能发生冲突前询问用户。如果会话记录中的陈述与当前文件冲突，以当前文件为准并报告差异。
从第一个未完成的步骤继续。不要重复已完成的工作；沿用既定的方法和风格，除非它们明显失效。只有在因信息缺失或存在不安全选择而受阻时，才询问用户。

Resume Modes

恢复模式

Decide from the user's prompt how far to go after the checkpoint:

```
Report-only
```
: the ask is what happened, done versus pending, or to check/audit/review a prior session without edits. Stop after the resume report and clear next action.
```
Continue-edit
```
: the ask is to continue, fix, implement, open a PR, or run tests. Report first, then continue from the first unfinished safe step.
```
Quick resume
```
: status report or task breakdown. Prefer a compact source inventory, task classification, and next action.
```
Deep resume
```
: implementation continues, the source is ambiguous, or files may have drifted. Read the full record and current git state, then continue.

根据用户的提示决定在检查点之后推进到何种程度：

```
Report-only
```
：请求内容是了解发生了什么、已完成与待完成事项，或在不进行编辑的情况下检查、审计或审查先前的会话。完成恢复报告和明确下一步后停止。
```
Continue-edit
```
：请求是继续、修复、实现、创建 PR 或运行测试。先进行报告，然后从第一个未完成且安全的步骤继续。
```
Quick resume
```
：状态报告或任务拆解。优先提供紧凑的来源清单、任务分类和下一步操作。
```
Deep resume
```
：需要继续实现、来源不明确，或文件可能已经发生漂移。读取完整记录和当前 git 状态，然后继续。

Platform References

平台参考

Claude Code:
```
references/claude-code.md
```
Codex:
```
references/codex.md
```
Cursor:
```
references/cursor.md
```
Antigravity:
```
references/antigravity.md
```
OpenCode:
```
references/opencode.md
```
GitHub Copilot:
```
references/github-copilot.md
```
Cross-platform / multi-agent asks:
```
references/cross-platform.md
```

Claude Code：
```
references/claude-code.md
```
Codex：
```
references/codex.md
```
Cursor：
```
references/cursor.md
```
Antigravity：
```
references/antigravity.md
```
OpenCode：
```
references/opencode.md
```
GitHub Copilot：
```
references/github-copilot.md
```
跨平台或多 Agent 请求：
```
references/cross-platform.md
```

Required Response Shape

必需响应结构

Before continuing execution, report:

markdown

undefined

在继续执行前，报告：

markdown

undefined

Brief context summary

Goal: <prior session goal>
Loaded skill: path=<loaded SKILL.md path or "unknown">; source/version=<version marker or "unknown">
Source reviewed: <transcript/export/artifact refs>
Current workspace check: <git status summary and touched-file refs, or why not checked>
Transcript/current repo mismatches: <none found | claim, transcript ref, current-repo ref, action>
User deferrals: <none found | deferred scope, user wording, evidence ref, reopen condition>
Stopping point: <last command, edit, failure, or user pause instruction with evidence>

Goal: <prior session goal>
Loaded skill: path=<loaded SKILL.md path or "unknown">; source/version=<version marker or "unknown">
Source reviewed: <transcript/export/artifact refs>
Current workspace check: <git status summary and touched-file refs, or why not checked>
Transcript/current repo mismatches: <none found | claim, transcript ref, current-repo ref, action>
User deferrals: <none found | deferred scope, user wording, evidence ref, reopen condition>
Stopping point: <last command, edit, failure, or user pause instruction with evidence>

Task status breakdown

DONE: <task> - evidence: <implementation refs>; verification: <test/tool refs or "not recorded">.
PARTIALLY DONE: <task> - evidence: <started-work refs>; missing: <remaining gap refs>.
NOT DONE: <task> - evidence: <TODO, failing test, absent artifact, or transcript gap refs>.

DONE: <task> - evidence: <implementation refs>; verification: <test/tool refs or "not recorded">.
PARTIALLY DONE: <task> - evidence: <started-work refs>; missing: <remaining gap refs>.
NOT DONE: <task> - evidence: <TODO, failing test, absent artifact, or transcript gap refs>.

Clear next action

Next: <first unfinished step to take now>
Blocked: <no | yes - reason and evidence>


Then continue immediately unless blocked. Evidence rules and the static idempotency contract: `references/evidence-and-provenance.md`.

Next: <first unfinished step to take now>
Blocked: <no | yes - reason and evidence>


除非受阻，否则随后立即继续。证据规则和静态幂等性契约：`references/evidence-and-provenance.md`。

Guardrails

防护规则

Never assume the newest file is the right transcript when the user supplied a title or path.
Never summarize from filenames alone or treat a compact summary as equivalent to an available full transcript.
Never reset, revert, or discard existing changes unless the user explicitly asks.
Never mark a task
```
DONE
```
or
```
PARTIALLY DONE
```
from a plan alone; status requires evidence of completion or started work.
Never omit transcript/current-repo mismatches when the transcript and checked files disagree.
Never unpark deferred scope from a vague "proceed" or "continue"; confirm the user wants that parked work reopened.

当用户提供了标题或路径时，绝不要假定最新文件就是正确的会话记录。
绝不要仅根据文件名进行总结，也不要将精简摘要视为与可用完整记录等效。
除非用户明确要求，否则绝不要重置、回退或丢弃现有改动。
绝不要仅根据计划将任务标记为
```
DONE
```
或
```
PARTIALLY DONE
```
；状态必须有完成或已开始工作的证据。
当会话记录与检查过的文件不一致时，绝不要省略这些差异。
绝不要仅凭含糊的“proceed”或“continue”就解除暂缓范围；应确认用户希望重新开启已暂缓的工作。