执行保障机制 Skill（通用组件）

本 Skill 是通用组件，不直接调用，而是被其他 Skill 引用。

在其他 Skill 开头添加：引用: execution-guard

一、核心规则

1.1 Task 状态追踪

使用 Task 系列工具追踪每个步骤的执行状态：

工具	用途
`TaskCreate`	创建任务，指定 subject、description、activeForm
`TaskUpdate`	更新状态（in_progress/completed）、设置依赖关系
`TaskList`	查看所有任务状态
`TaskGet`	获取单个任务详情

规则	说明
启动初始化	进入任何阶段前，必须先用 TaskCreate 创建该阶段所有步骤
执行前标记	开始执行前，`TaskUpdate({ taskId, status: "in_progress" })`
完成后标记	完成后立即标记为 `completed`，不得批量标记
禁止跳过	只有 `completed` 后才能开始下一步（除非设置了并行依赖）
独立追踪	多目标场景（多仓库/多服务），每个目标独立 Task
依赖管理	使用 `addBlockedBy` 设置任务依赖关系

1.2 Task 命名规范

subject 格式：

[阶段X.Y] <步骤描述> [目标名]

示例：

[1.1] 需求分析
[2.3] 编码实现 [api_server]
[2.3] 编码实现 [common]

1.3 activeForm 规范

TaskCreate 的 activeForm 用于显示 spinner 动态提示：

subject (任务标题)	activeForm (spinner 显示)
创建功能分支	创建分支中
编码实现	编码中
推送并创建 MR	推送中

用户看到的效果：

pending: ☐ [2.1] 创建功能分支
in_progress: ⏳ 创建分支中...（spinner 转动）
completed: ✅ [2.1] 创建功能分支

二、输出精简规范

2.1 核心原则

用户只关心结果，不关心过程细节。

原则	说明
静默执行	工具调用、命令过程不输出，失败时才报告
结果导向	只输出链接、状态、下一步动作
合并同类	多目标的相同操作合并为一行
禁止解释	不说"我正在做"、"接下来我会"

2.2 示例对比

❌ 冗长（禁止）：

我现在开始创建功能分支。首先定位 epic 根目录...
找到了 epic 根目录在 /path/to/epic。
执行 gitepic feat 命令创建分支...
分支创建成功！接下来生成 VS Code 工作区...

✅ 精简（正确）：

分支 feat-xxx-20260204 已创建

2.3 阶段 Checkpoint 格式

每个阶段完成后，输出 1-2 行 Checkpoint：

✅ 阶段X完成 | <关键信息>
→ 下一步: <动作>

示例：

✅ 方案已确认 | 仓库: api_server, common | 分支: feat-xxx
→ 开始执行：创建分支 → 编码 → 提交

2.4 最终输出格式

任务完成时，输出精简报告：

✅ 完成
- <产出1>: <值>
- <产出2>: <值>

→ <下一步建议>

三、异常处理

3.1 失败时行为

保持当前 todo 为 in_progress（不标记 completed）
输出精简异常报告

3.2 异常报告格式

⚠️ 失败: [阶段X.Y] <步骤>
原因: <一句话>
→ 需要: <用户决策/自动重试>

四、引用方式

在其他 Skill 的 SKILL.md 开头添加：

## 执行保障

**引用: `execution-guard`**

本 Skill 遵循 execution-guard 的执行保障机制，详见该 Skill 文档。

4.1 自定义阶段 Task

根据 Skill 的具体流程，定义各阶段的 Task：

TaskCreate({ subject: "[1.1] 步骤A", description: "步骤A的详细说明", activeForm: "执行步骤A中" })
TaskCreate({ subject: "[1.2] 步骤B", description: "步骤B的详细说明", activeForm: "执行步骤B中" })

执行时更新状态：

# 开始执行
TaskUpdate({ taskId: "<id>", status: "in_progress" })

# 执行完成
TaskUpdate({ taskId: "<id>", status: "completed" })

4.2 多目标场景

当存在多个目标（仓库/服务/文件）时，为每个目标创建独立 Task：

TaskCreate({ subject: "[2.1] 处理 [target1]", description: "处理 target1", activeForm: "处理 target1 中" })
TaskCreate({ subject: "[2.1] 处理 [target2]", description: "处理 target2", activeForm: "处理 target2 中" })

4.3 任务依赖关系

使用 addBlockedBy 设置任务依赖，被阻塞的任务需等待依赖完成：

# 创建任务
TaskCreate({ subject: "[2.1] 编码 [api_server]", ... })  # 假设返回 id: "1"
TaskCreate({ subject: "[2.1] 编码 [common]", ... })      # 假设返回 id: "2"
TaskCreate({ subject: "[2.2] 提交 [api_server]", ... })  # 假设返回 id: "3"
TaskCreate({ subject: "[2.2] 提交 [common]", ... })      # 假设返回 id: "4"

# 设置依赖：提交依赖编码完成
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })  # 提交 api_server 依赖 编码 api_server
TaskUpdate({ taskId: "4", addBlockedBy: ["2"] })  # 提交 common 依赖 编码 common

并行执行： 无依赖关系的任务可以并行执行（如编码 api_server 和编码 common）

五、检查清单

执行 Skill 时，自检以下要点：

阶段开始前是否用 TaskCreate 初始化了所有任务？
每个步骤执行前是否用 TaskUpdate 标记了 in_progress？
每个步骤完成后是否立即标记了 completed？
多目标场景是否设置了正确的依赖关系（addBlockedBy）？
输出是否遵循精简原则？
异常时是否保持了 in_progress 状态？