step-running

步骤运行

你将作为原子化后台子 Agent，执行 DAG 计划中的单个步骤。你会自主完成工作并报告结果——不会与用户交互。

这是 phase-running 的 DAG 同级版本。执行模型和原子性约定相同；区别如下：

• 你收到的是步骤文件路径（step-<n>.md），而非计划路径加阶段编号。
• 执行工作前，你会通过步骤的 frontmatter status 字段原子地认领步骤，并在完成／失败时释放。这使多个编排器实例可以安全地驱动同一计划目录。

执行模型

此技能在后台 Agent（子 Agent）中运行。v-implementing（或调用 /run-step 的用户）会通过 Agent 工具以 run_in_background: true 的方式启动它。

步骤 Agent 会收到：

• 步骤路径：step-<n>.md 的完整路径
• 计划目录：父计划目录的完整路径（从这里读取 root.md，获取计划级上下文）
• Agent ID：此子 Agent 的唯一标识符（例如编排器会话 ID + 步骤 ID + 时间戳）。用于原子认领和过期认领检测。
• 相关上下文：调用方提供的任何其他上下文

并发：原子认领

开始任何工作前，认领步骤：

1. 读取步骤文件的 frontmatter。
2. 如果 status: done——报告 Status: skipped 并退出。此步骤已完成。
3. 如果 status: claimed 且 assignee 与你的 Agent ID 不同：
   • 认领未过期（claimed_at 在最近一小时内）：报告 Status: blocked（原因：claimed by <other-id>）并退出。
   • 认领已过期（超过 1 小时）：继续并覆盖——之前的工作进程可能已崩溃。
4. 否则（status: ready 或已过期的 claimed）：通过单次 Edit 重写 frontmatter 块，使写入具备足够的文件系统原子性。设置：
   • status: claimed
   • assignee: <your-agent-id>
   • claimed_at: <ISO timestamp UTC>
5. 重新读取文件。如果 assignee 不是你的 ID，则说明另一工作进程抢先认领——报告 Status: blocked（原因：lost claim race）并退出。

终态转换时，设置 frontmatter：

• 已完成：status: done，清除 assignee 和 claimed_at。
• 受阻或失败（可重试）：status: ready，清除 assignee 和 claimed_at。编排器（或其他工作进程）可以重试。
• 失败（不可重试）：保留 status: claimed，供编排器调查；在报告中说明原因。

如需真正的跨机器原子性（NFS 等），调用方需负责协调（例如使用共享锁服务）。单次 Edit 模式对于本地文件系统和行为良好的网络文件系统已足够。

自主运行

步骤 Agent 在子 Agent 内始终以 Autopilot 模式运行。外层自主模式和人工检查点由调用上下文控制。

重要：步骤 Agent 不使用 AskUserQuestion。如有歧义，请报告 Status: blocked 并提供详情。由调用方处理所有用户交互。

流程步骤

步骤 1：加载上下文

1. 认领步骤（参见“并发：原子认领”）。遇到任何无法认领的情况时，立即停止。
2. 阅读完整的步骤文件。
3. 从计划目录读取 root.md，获取计划级上下文：概述、当前状态、预期最终状态、实现方案、全局验证。
4. 阅读步骤“所需更改”部分中提及的所有文件。

步骤 2：预检

检查	失败时的操作
所有 depends_on 步骤的 status 均为 done	调度器错误——释放认领并报告 blocked
目标文件中不存在合并冲突	释放认领并报告 blocked
依赖步骤涉及的文件／目录均存在	释放认领并报告 blocked

步骤 3：执行步骤

实现步骤“所需更改”部分描述的变更。对于轻微不匹配，可自行调整；遇到重大不匹配时，请报告 blocked。

第 4 步：运行验证

与 phase-running 采用相同的三类模式：

1. 自动化验证（可运行的命令）：逐一运行并记录通过/失败。失败时，尝试修复并重试一次。
2. 自动化 QA（由 Agent 驱动的场景——browser-use、截图差异对比、CLI 演练）：执行并逐项记录通过/失败。
3. 手动验证：保持未勾选。由调用方与用户处理。
4. QA 规范（关联文档）：如果存在，报告 QA Doc: <path>。不要直接执行其中的场景。

第 5 步：更新步骤文件

• 勾选（- [x]）通过的自动化验证和自动化 QA 项目。
• 不要勾选手动验证项目。
• 根据“并发：原子认领”终态转换规则更新 frontmatter 中的 status。
• 如果存在 last_updated / last_updated_by frontmatter 字段，也要更新。

第 6 步：报告结果

已完成：

Status: completed
Step: step-N - <Name>
Final frontmatter status: done
Files changed: [list]
Automated Verification: N/M passed
- [x] [Check 1] — passed
Automated QA: N/M passed
- [x] [Scenario 1] — passed
QA Doc: <path> | n/a
Manual verification needed:
- [ ] [Manual check 1]

**受阻 / 失败：**采用与 phase-running 相同的格式，并添加一行 Final frontmatter status:，以便编排器了解该步骤是已释放以供重试（ready），还是被保留以待调查（claimed）。

原子性约定

• 不提出交互式问题。
• 不留下未作说明的部分状态。
• 退出时，frontmatter 中的 status 始终反映最终状态。
• 报告需包含足够详细的信息，供调用方决定后续步骤。

上下文交接模式

方向	数据
调用方 → 步骤 Agent	步骤路径 + 计划目录 + Agent ID + 自主模式
步骤 Agent 读取	步骤文件 + root.md + Changes Required 中的文件
步骤 Agent 写入	frontmatter 状态转换 + 复选框 + 代码更改
步骤 Agent → 调用方	状态 + 已更改文件 + 验证结果 + 最终 frontmatter 状态
调用方处理	手动验证、跨步骤协调、执行 QA 文档、人工检查点