Trellis 中断任务恢复实战：EcoPaste 仓库 Continue Current Task 命令解析与路由指南

• 桌面应用
• 开发工具

本指南面向在 EcoPaste 这类接入 Trellis 工作流的仓库中开发/协作的工程师与 AI Agent，完整解析.cursor/commands/trellis-continue.md这条"继续当前任务"命令的四个执行步骤、状态路由决策表与阶段规则，并结合.trellis/目录下的脚本源码（get_context.py、workflow_phase.py）讲清底层机制。读完你将掌握：如何一键加载会话上下文、如何根据task.json.status与规划产物（prd.md / design.md / implement.md / jsonl）定位正确的恢复步骤，以及如何在 Plan / Execute / Finish 三阶段间正确穿梭。

一、命令定位：为什么需要一条"继续"命令

AI 驱动的开发会话天然具有中断性——一次长任务可能跨越多个会话、多次终端窗口、甚至多个 Agent 平台（Claude Code、Cursor、OpenCode、Codex 等）。会话上下文会随聊天压缩丢失，而文件不会丢。Trellis 工作流的核心原则之一就是"持久化一切"（research、decisions、lessons 全部落盘），因此恢复的关键不在于"回忆上次聊了什么"，而在于"读取仓库里已经写好的状态"。

.cursor/commands/trellis-continue.md正是为此设计的入口命令。它的定位在文档第一段就写得很清楚：

Resume work on the current task — pick up at the right phase/step in.trellis/workflow.md.

它本身不承载完整流程，而是引导你回到 workflow.md（Trellis 流程的唯一权威定义），并在正确的 Phase / Step 上继续。命令全文围绕 4 个步骤展开：

1. 加载当前上下文（Step 1）
2. 加载阶段索引（Step 2）
3. 判定自己处在哪个阶段（Step 3，含路由决策表）
4. 加载具体步骤的详细指引（Step 4）

二、Step 1：加载当前会话上下文

恢复工作的第一步是弄清"现在是什么状态"。执行：

python3 ./.trellis/scripts/get_context.py

这条命令的输出由 session_context.py 生成，默认（text）模式下会依次给出：

从源码看，get_context.py是典型的 argparse 入口（见 get_context.py），支持四个输出模式：

python3 ./.trellis/scripts/get_context.py # 默认：完整会话上下文 python3 ./.trellis/scripts/get_context.py --mode record # 精简版：任务 + git + 最近提交 python3 ./.trellis/scripts/get_context.py --mode packages # 列出包与 spec 层级 python3 ./.trellis/scripts/get_context.py --mode phase # 阶段索引（Step 2 用）

命令文档中特别强调了一个设计意图："get_context.pyshows the active task'sstatusfield… this commandreplaces the user needing to remember the Trellis flow; it does not itself approve implementation."——即该命令只负责"帮你想起流程"，本身不构成实现授权，真正的实现仍然要等task.py start之后。

三、Step 2：加载阶段索引（Phase Index）

在拿到基本上下文后，加载流程总览：

python3 ./.trellis/scripts/get_context.py --mode phase

这会从 workflow.md 的## Phase Index小节中提取出三阶段的精简总览（不含各步骤详细正文），并保留"路由 + skill 映射"信息：

Phase 1: Plan → classify, get task-creation consent, then write planning artifacts Phase 2: Execute → implement only after task status is in_progress Phase 3: Finish → verify, update spec, commit, and wrap up

• Phase 1（Plan）：步骤 1.0 创建任务、1.1 需求探索（产出prd.md）、1.2 研究（可选）、1.3 配置上下文（jsonl 策划）、1.4 激活任务（review 后task.py start）、1.5 完成标准。核心纪律：先规划后代码，任务创建授权 ≠ 实现授权。
• Phase 2（Execute）：步骤 2.1 实现、2.2 质量检查、2.3 按需回滚。前提是任务状态已进入in_progress。
• Phase 3（Finish）：步骤 3.2 调试复盘（按需）、3.3 更新 spec（[required]）、3.4 批量提交（[required]）、3.5 收尾提醒。注意 3.1 已被合并进 2.2 与 3.4，编号刻意保持稳定以免破坏外部引用。

从 workflow_phase.py 的实现看，--mode phase不带--step时调用get_phase_index()，只截取## Phase Index到## Phase 1: Plan之间的内容，并剥离[workflow-state:STATUS]面包屑块（这些块由每轮的 hook 单独注入，不属于阶段索引输出）。

四、Step 3：核心——根据 status 与产物路由

这是整条命令的核心价值所在：不需要记 Trellis 流程，只需要读 status + 检查产物是否存在，即可定位下一步。文档给出的完整路由决策表如下：

4.1 路由背后的产物语义

要正确路由，必须理解各规划产物的含义（见 workflow.md 的Planning Artifacts小节）：

• prd.md—— 需求、约束与验收标准。不要把技术设计或执行清单写进去。
• design.md—— 复杂任务的技术设计：边界、契约、数据流、取舍、兼容性、上线/回滚形态。
• implement.md—— 复杂任务的执行计划：有序检查清单、验证命令、评审门禁、回滚点。
• implement.jsonl/check.jsonl—— 子代理的 spec 与研究清单（每行一个{"file": "...", "reason": "..."}），不替代implement.md。

关键判断：轻量任务可以只有 PRD；复杂任务在task.py start之前必须同时具备prd.md、design.md、implement.md三个文件。在 EcoPaste 仓库的 tasks 归档目录 中可以看到两类实例：轻量修复任务（如06-30-fix-divider-deprecation、06-30-i18n-window-lifecycle-name）只含task.json + prd.md + 两个 jsonl；而复杂任务07-03-onboarding-admin-launch则同时包含design.md、implement.md，正好印证了这一产物矩阵。

任务目录统一遵循{MM-DD-name}/命名，内部结构为：

.trellis/tasks/{MM-DD-name}/ ├── task.json # 元数据：status / assignee / priority / children / hooks ├── prd.md # 需求与验收标准 ├── design.md # （复杂任务）技术设计 ├── implement.md # （复杂任务）执行计划 ├── research/ # （可选）研究成果落盘 ├── implement.jsonl # 实现子代理的上下文清单 └── check.jsonl # 检查子代理的上下文清单

4.2 三条阶段规则

文档在路由表后给出了三条必须遵守的阶段规则（与 workflow.md 的Rules小节一致）：

1. 阶段内按序执行——[required]步骤不得跳过；
2. [once]步骤已产出即视为完成——不要重复执行；例如已有prd.md就说明 1.1 的部分工作已完成，轻量任务可以凭prd.md直接进入 1.4；
3. 允许回退到更早阶段——例如执行阶段发现prd.md有缺陷，可回到 Phase 1 修正后再重新进入 Execute。

4.3 路由表隐含的关键纪律

• planning + 产物齐全 ≠ 可以直接实现：必须进入 1.4，先请求用户发起 review，只有用户确认后才运行task.py start（start会把 status 翻转为in_progress，面包屑随之切换）。
• 子代理平台 vs inline 平台：在支持子代理分发的平台（Claude Code、Cursor、OpenCode、Codex sub-agent 等），implement.jsonl与check.jsonl都必须至少有一条真实条目才算"可启动"（种子_example行不计）；而 Codex 的 inline 模式（codex.dispatch_mode: inline，见 config.yaml）跳过 jsonl 策划，Phase 2 直接由trellis-before-devskill 读取产物。
• completed状态在常规流程中基本不会出现：因为task.py archive在同一个调用里既把 status 写成completed又把任务目录移入archive/，活动任务解析器随即丢失指针——从源码注释看，该状态块目前处于"DEAD"状态，保留是为将来显式的in_progress → completed迁移做准备。

五、Step 4：加载具体步骤的详细指引

一旦确定了要恢复的步骤编号（如 1.1 / 2.1 / 3.3），加载该步骤的完整正文：

python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform cursor

其中：

• --step <X.X>指定步骤编号（例如--step 1.1、--step 2.2）；
• --platform cursor指定当前平台，用于过滤掉平台专属段落，只保留适用于你的指令。

从 workflow_phase.py 的实现看，get_step()通过正则^####\s+(\d+\.\d+)\b匹配workflow.md中的#### X.X标题，正文一直截取到下一个####/##标题或---分隔线为止。例如--step 1.1会返回 1.1 需求探索步骤的完整正文（包含trellis-brainstormskill 的使用指引）。

5.1 平台过滤的底层原理

workflow.md中大量使用了成对的平台标记块：

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, ...] （子代理分发平台的专属内容） [/Claude Code, Cursor, OpenCode, ...]

filter_platform() 会：

1. 用^\[(/?)([A-Za-z][^\[\]]*)\]\s*$识别开启/闭合标记；
2. 对标记中的平台名做大小写不敏感 + 去分隔符的模糊匹配（cursor、Cursor、claude-code、Claude Code都能对上）；
3. 丢弃标记行本身，只保留"标记块外的通用内容 + 包含当前平台的块内内容"；
4. 折叠因删块而产生的连续空行。

还有一个值得注意的细节：--platform codex会被 resolve_effective_platform() 映射为codex-inline（默认）或codex-sub-agent（取决于 config 中codex.dispatch_mode），原因是 Codex 子代理运行在fork_turns="none"隔离中、无法继承父会话的任务上下文，因此默认走 inline 模式让主 Agent 直接改代码。

六、命令的边界与配套流程

trellis-continue.md在结尾的Reference小节明确声明了自己的边界：

Full workflow and detailed phase steps live in.trellis/workflow.md. This command is only an entry point — the canonical guidance is there.

也就是说，这条命令只是一个入口，权威指南始终是 workflow.md。与之配套的收尾命令是 trellis-finish-work.md：它负责在任务提交（Phase 3.4）之后归档任务（task.py archive）并记录会话日志（add_session.py --title/--commit/--summary），最终形成<work commits>→chore(task): archive ...→chore: record journal的提交顺序。两者配合即可覆盖"中断恢复 → 继续执行 → 收尾归档"的完整闭环。

七、完整实战：一次中断恢复的端到端走查

将四个步骤串联起来，一次典型的中断恢复流程是：

# 1. 恢复现场：确认当前任务、git 状态、最近提交 python3 ./.trellis/scripts/get_context.py # 2. 若需要，查看三阶段总览与路由映射 python3 ./.trellis/scripts/get_context.py --mode phase # 3. 依据 task.json 的 status 与产物存在性完成路由： # - planning + 无 prd.md → 加载 trellis-brainstorm，回到 1.1 # - planning + 仅 prd.md → 轻量走 1.4；复杂补 design.md + implement.md 再走 1.4 # - planning + 产物齐全 + jsonl 未整理 → 1.3 策划 implement.jsonl / check.jsonl # - planning + 产物齐全 + jsonl 已整理 → 1.4 请求 review，确认后 task.py start # - in_progress + 未实现 → 2.1 # - in_progress + 已实现未检查 → 2.2 # - in_progress + 检查通过 → 3.3 更新 spec → 3.4 提交 # - completed → 归档流程 # 4. 加载目标步骤的详细指引（按当前平台过滤） python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform cursor

配合任务生命周期命令（见 workflow.md 的Task System小节），你还可以在恢复过程中随时核对活跃任务：

python3 ./.trellis/scripts/task.py current --source # 显示当前任务与来源 python3 ./.trellis/scripts/task.py list [--status <s>] # 列出任务（可按状态过滤） python3 ./.trellis/scripts/task.py validate <name> # 校验任务元数据

八、实践建议与注意事项

1. 恢复会话先跑 Step 1，不要凭记忆。get_context.py输出的CURRENT TASK区块里的status字段 +prd.md等产物的存在性，是路由的唯一合法依据。
2. 规划产物矩阵要分清：轻量任务 PRD-only 是合法状态；复杂任务缺design.md/implement.md则代表规划未完成，不得task.py start。
3. 尊重[required]/[once]语义：[required]步骤不可跳过；[once]步骤有产出即跳过，不要重复劳动。
4. 跨阶段回退是正常流程：Execute 阶段发现问题可以回到 Plan 修正prd.md后重新进入，这不是流程失败，而是"规划必须持久化到产物"原则的体现。
5. EcoPaste 仓库的验证基线（见 spec/index.md）：前端pnpm lint+pnpm tsc，Rust 侧cd src-tauri && cargo fmt && cargo clippy -- -D warnings && cargo test；在 Phase 2.2 质量检查与 Phase 3.4 提交前，务必把这两条基线跑绿。

• 桌面应用
• 开发工具