用途
subtask4llm-pi 用于规划并执行一项有依赖顺序的软件变更。它把工作拆成有序步骤，交给顺序执行、一次性的 Pi 工作者完成，步骤之间通过明确的依赖关系交接结果，并带有受限重试机制。
只有当请求的实现包含多个具体步骤、且有序交接能让独立工作者上下文发挥作用时，才应选用该工作流；不要为了使用运行器而把一个小改动强行拆分。
主要能力
- 规划与审查在同一 Pi 会话内完成：当前 Pi 会话充当规划者和审查者，独立运行器 scripts/run_workflow.py 负责在目标工作区中按顺序启动 Pi 工作者。
- 版本 1 JSON 计划：计划包含 1–10 个有序步骤，每一步都有唯一 ID、有边界的任务、非空的验收标准，且只能依赖更早的步骤。计划中需写入共享的仓库发现、用户需求、约束、相关路径、设计决策和边界情况，使工作者无需依赖规划者的对话上下文。
- 执行前校验：读取 references/plan-format.md，把计划写入临时 JSON 文件，先用 --dry-run 校验，再执行。
- 用户确认：启动工作者前，向用户展示目标、各步骤标题、简短描述和依赖关系；除非用户要求先审查或修改计划，否则随后启动工作流。
- 运行器控制项：--model 仅在模型 ID 已知且需要覆盖已配置模型时使用，否则依次使用 PI_WORKFLOW_MODEL 和 Pi 的默认模型；可按需使用 --timeout-seconds、--timeout-checkpoint-seconds、--retries 0|1、--max-summary-chars、--pi-bin、--artifacts-dir；--continue-on-error 仅在用户希望某一步失败后继续执行后续步骤时使用，最终状态仍会报告失败。产物为可选项，运行器拒绝覆盖已存在的产物目标。
- Pi 工作者模式：工作者以 --mode json --no-session --no-skills 的一次性 JSON 事件进程运行，提示通过标准输入发送，运行器提取最终助手文本，要求其是与结果 schema 匹配的原始 JSON。
- 统一实时日志：运行器把每个子任务和编排器的可读摘要汇入一份工作流级实时日志，不生成每次尝试的进度日志文件。日志包含工具命令和简短输出或助手响应摘要，应视为可能敏感的内容。启动时会打印日志路径和可直接复制的 tail -f 命令；可用 --live-log <path> 指定其他路径，默认日志位于工作区之外的系统临时目录。
- 超时与重试：运行器每 10 分钟检查一次进度，停止 10 分钟无更新的 shell 命令，其余情况继续到 30 分钟硬上限；超时诊断会包含近期活动，且不重试。非超时失败最多使用配置的一次重试；超时和被检测到停滞的命令不重试。默认在步骤未成功时停止，使用 --continue-on-error 时继续运行剩余计划步骤。
- 上下文可见性：工作者保留常规的 AGENTS.md 上下文发现，运行器不会禁用上下文文件。每个工作者获得共享上下文、完整工作流映射、自己的任务与验收标准，以及仅其声明依赖的详细结果。
使用方式
- 检查仓库并准备完整的版本 1 JSON 计划（1–10 个有序步骤），按格式写入临时文件并用 --dry-run 校验。
- 在目标仓库中运行运行器。macOS 或 Linux：
python3 <skill-path>/scripts/run_workflow.py <plan.json> --workspace <repository>
Windows PowerShell：
py -3 <skill-path>\scripts\run_workflow.py <plan.json> --workspace <repository>
- 运行器启动后，把日志路径和 tail -f 命令展示给用户，然后等待运行器进程结束；不要反复轮询进程、单独执行 sleep/tail 检查、重读实时日志或定时发送进度更新。只有当用户询问或排查问题时才再次检查进度。
- 运行器退出后，不要临时追加额外的工作者运行；审查运行器的最终报告和实际工作区差异，按比例验证所请求的变更，并报告改动的文件、检查项和未解决的风险。
适用场景
适用于请求的实现具有多个具体步骤、且步骤之间的有序交接能让独立工作者上下文产生价值的情况，例如需要按依赖顺序推进的多步软件变更。
前提与限制
- 运行前必须已安装并可正常使用 Pi CLI 以及为 Pi 配置好的提供方；该技能不会自动安装 Pi、提供方或其他工具。
- Pi 工作者命令可在当前用户权限下修改文件；Pi CLI 不是沙箱。仅当这些权限适合所请求的仓库工作时才使用运行器，并保留无关改动，不要授予工作者无关的外部操作。
- 超时和检测到的停滞命令不重试；非超时失败最多限于配置的一次重试。
参考资料
版本 1 计划与结果格式、CLI 控制项和示例；独立顺序 Pi 运行器。