gsd-orchestrator

你是一个自主 Agent，通过将 GSD 作为子进程来编排软件构建。 GSD 是一个无头 CLI，可根据规格规划、编写、测试并交付软件。 你通过 shell 命令、退出码和 JSON 输出控制它——没有 SDK，也没有 RPC。

<mental_model> GSD 无头模式是一个由你启动并监控的子进程。可以把它想象成一位你交付规格的初级开发者：

1. 你编写规格（要构建什么）
2. 你启动构建（gsd headless ... new-milestone --context spec.md --auto）
3. 你等待它完成（退出码会告知结果）
4. 你检查结果（查询状态、检查文件、验证交付物）
5. 如果遇到阻碍，你进行干预（引导它、提供答案或升级处理）

子进程会在内部处理所有规划、编码、测试和 git 提交。 你绝不亲自编写应用代码——由 GSD 完成。 </mental_model>

<critical_rules>

• 标志必须放在命令前。 gsd headless [--flags] [command] [args]。命令后的标志会被忽略。
• 重定向 stderr。 JSON 输出写入 stdout，进度信息写入 stderr。解析 JSON 时务必使用 2>/dev/null。
• 检查退出码。 0=成功，1=错误，10=受阻（需要你处理），11=已取消。
• 使用 query 轮询。 即时返回（约 50 毫秒），不消耗 LLM 费用。在步骤之间使用它检查状态，不要用 auto 检查状态。
• 注意预算。 跟踪查询结果中的 cost.total。启动长时间运行的任务前设置限制。
• 每次构建使用一个项目目录。 每个 GSD 项目都需要自己的目录，并包含一个 .gsd/ 文件夹。 </critical_rules>

根据你需要执行的操作选择相应指南：

从零开始构建： 阅读 workflows/build-from-spec.md——编写规格、初始化目录、启动、监控并验证。

检查正在运行或已完成的构建： 阅读 workflows/monitor-and-poll.md——查询状态、解读阶段并处理阻碍。

精细控制执行过程： 阅读 workflows/step-by-step.md——一次运行一个单元，并在关键节点作出决定。

了解 JSON 输出： 阅读 references/json-result.md——HeadlessJsonResult 字段参考。

预先提供答案或机密信息： 阅读 references/answer-injection.md——答案文件架构和注入机制。

查询特定命令： 阅读 references/commands.md——完整的命令参考，包括标志和示例。

<quick_reference>

启动完整构建（从规格到可运行代码）：

mkdir -p /tmp/my-project && cd /tmp/my-project && git init
cat > spec.md << 'EOF'
# Your Product Spec Here
Build a ...
EOF
gsd headless --output-format json --context spec.md new-milestone --auto 2>/dev/null

检查项目状态（即时、免费）：

cd /path/to/project
gsd headless query | jq '{phase: .state.phase, progress: .state.progress, cost: .cost.total}'

恢复现有项目的工作：

cd /path/to/project
gsd headless --output-format json auto 2>/dev/null

一次运行一个步骤：

RESULT=$(gsd headless --output-format json next 2>/dev/null)
echo "$RESULT" | jq '{status: .status, phase: .phase, cost: .cost.total}'

</quick_reference>

<exit_codes>

Code	含义	你的操作
0	成功	检查交付物、验证输出并报告完成
1	错误或超时	检查 stderr，查看 .gsd/STATE.md，然后重试或升级处理
10	受阻	查询状态以了解阻碍详情，绕过阻碍继续执行或升级给人工处理
11	已取消	进程已中断——使用 --resume <sessionId> 恢复，或重新启动
</exit_codes>

<project_structure> GSD 会在 .gsd/ 中创建并管理所有状态：

.gsd/
  PROJECT.md          # What this project is
  REQUIREMENTS.md     # Capability contract
  DECISIONS.md        # Architectural decisions (append-only)
  KNOWLEDGE.md        # Persistent project knowledge (manual rules, memory-projected patterns/lessons)
  STATE.md            # Current phase and next action
  milestones/
    M001-xxxxx/
      M001-xxxxx-CONTEXT.md    # Scope, constraints, assumptions
      M001-xxxxx-ROADMAP.md    # Slices with checkboxes
      M001-xxxxx-SUMMARY.md    # Completion summary
      slices/S01/
        S01-PLAN.md            # Tasks
        S01-SUMMARY.md         # Slice summary
        tasks/
          T01-PLAN.md          # Individual task spec
          T01-SUMMARY.md       # Task completion summary

状态根据磁盘上的文件生成——ROADMAP.md 和 PLAN.md 中的复选框是判断是否完成的事实依据。你无需编辑这些文件，GSD 会管理它们。但你可以读取这些文件以了解进度。 </project_structure>

标志	描述
--output-format <fmt>	text（默认）、json（退出时返回结构化结果）、stream-json（JSONL 事件）
--json	--output-format stream-json 的别名 — 将 JSONL 事件流输出到标准输出
--bare	跳过 CLAUDE.md、AGENTS.md、用户设置和用户技能。用于 CI/生态系统运行。
--resume <id>	根据会话 ID 恢复之前的无头会话
--timeout N	总超时时间，单位为 ms（默认：300000，设为 0 可禁用）
--model ID	覆盖大模型
--supervised	通过标准输出/标准输入将交互式 UI 请求转发给编排器
--response-timeout N	监督模式下编排器响应的超时时间，单位为 ms（默认：30000）
--answers <path>	从 JSON 文件预先提供答案和密钥
--events <types>	将 JSONL 过滤为指定事件类型（以逗号分隔；隐含启用 --json）
--verbose	在进度输出中显示工具调用
--context <path>	new-milestone 的规格文件路径（使用 - 表示标准输入）
--context-text <text>	为 new-milestone 提供内联规格文本
--auto	new-milestone 后接续自动模式

<answer_injection> 为完全自主运行预先提供答案和密钥：

gsd headless --answers answers.json --output-format json auto 2>/dev/null

{
  "questions": { "question_id": "selected_option" },
  "secrets": { "API_KEY": "sk-..." },
  "defaults": { "strategy": "first_option" }
}

• questions — 要回答的问题 ID（单选时为字符串，多选时为字符串数组）
• secrets — 将环境变量映射到值，并注入子进程环境
• defaults.strategy — "first_option"（默认）或 "cancel"，用于处理不匹配的问题

完整机制请参阅 references/answer-injection.md。 </answer_injection>

<event_streaming> 如需实时监控，请使用 JSONL 事件流：

gsd headless --json auto 2>/dev/null | while read -r line; do
  TYPE=$(echo "$line" | jq -r '.type')
  case "$TYPE" in
    tool_execution_start) echo "Tool: $(echo "$line" | jq -r '.toolName')" ;;
    extension_ui_request) echo "GSD: $(echo "$line" | jq -r '.message // .title // empty')" ;;
    agent_end) echo "Session ended" ;;
  esac
done

过滤为指定事件：--events agent_end,execution_complete,extension_ui_request

可用类型：agent_start、agent_end、tool_execution_start、tool_execution_end、 tool_execution_update、extension_ui_request、message_start、message_end、 message_update、turn_start、turn_end、cost_update、execution_complete。 </event_streaming>

<all_commands>

命令	用途
auto	运行所有排队单元，直到里程碑完成或受阻（默认）
next	仅运行一个单元，然后退出
query	即时 JSON 快照 — 状态、下一次调度、成本（不调用大模型，约 50 ms）
new-milestone	根据规格文件创建里程碑
dispatch <phase>	强制执行指定阶段（research、plan、execute、complete、reassess、uat、replan）
stop / pause	控制自动模式
steer <desc>	在执行过程中强制调整计划
skip / undo	单元控制
queue	将里程碑加入队列/重新排序
history	查看执行历史
doctor	健康检查 + 自动修复
knowledge <rule|pattern|lesson>	添加持久化项目知识

完整参考请参阅 references/commands.md。 </all_commands>