GSD Headless 编排实战：用 `gsd headless` 无 TUI 驱动 GSD 项目的完整指南

人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载GSDGet Shit Done项目内置了一套面向 Agent 与自动化脚本的无界面编排入口gsd headless它通过 RPC 子进程运行 GSD 命令、自动应答 UI 提示并实时流式输出进度让外部编排器可以像指挥一个不会问问题的手下一样驱动整个软件开发流程。本文以 gsd-headless SKILL.md 为骨架结合仓库内 src/headless.ts、src/headless-query.ts、src/headless-answers.ts 等源码实现讲解从根据 spec 创建里程碑到多会话并行编排、预算控制、状态查询、答案注入的完整实战方案。读完本文你将掌握headless 模式全部命令与标志位、三种输出格式text/json/stream-json、基于退出码与query快照的编排决策循环、JSONL 事件流消费、多工作进程的文件级 IPC 并行编排以及用--answers预置答案与密钥实现完全无人值守的自动化。命令语法与全局标志所有 headless 命令都以子进程方式运行统一语法为gsd headless [flags] [command] [args...]在 src/headless.ts 的参数解析实现中命令行采用标志位在前、命令在后的顺序--开头的参数会被解析为标志位第一个非--参数被识别为子命令默认是auto其后参数作为该命令的参数。常用标志位标志说明默认值--timeout N整体超时毫秒0表示禁用3000005 分钟--jsonJSONL 事件流输出到 stdout关闭--output-format fmttext/json结束时的结构化结果/stream-jsonJSONL 流text--model ID覆盖 LLM 模型默认模型--verbose在进度输出中显示工具调用细节关闭--supervised将交互式 UI 请求通过 stdout/stdin 转发给编排器关闭--response-timeout Nsupervised 模式下编排器响应的超时毫秒30000--max-restarts N崩溃后自动重启带退避0禁用3--answers path从 JSON 文件预置答案与密钥无--events types过滤 JSONL 输出到指定事件类型逗号分隔隐含--json不过滤--bare最小上下文跳过 CLAUDE.md、AGENTS.md、用户设置、用户技能关闭--resume id按会话 ID 恢复之前的 headless 会话无几个值得注意的实现细节来自 src/headless.tsauto与next是多轮命令isMultiTurnHeadlessCommand将auto、next、discuss、plan归类为多轮命令它们的完成判定依赖终端通知如Auto-mode stopped...而非单轮事件因此不会被单次execution_complete事件提前打断。auto默认禁用整体超时auto-mode 会话可持续数分钟到数小时内部由 auto-supervisor 做每单元超时管理因此auto命令在未显式指定--timeout时会将整体超时设为0禁用。new-milestone默认放宽到 10 分钟因为里程碑创建涉及代码库调研与产物写入若--timeout仍为默认值则自动提升为600000毫秒。--supervised与--context -互斥两者都需要占用 stdin同时使用会直接报错退出。--events和--supervised都隐含--json--events会自动把输出格式切换为stream-json。退出码约定headless 模式用退出码向编排器传递结果。SKILL.md 中简要给出0complete, 1error/timeout, 2blocked在 src/headless.ts 中定义了完整契约gsd-orchestrator 的 SKILL.md 也给出了一致的语义退出码含义触发场景0成功单元/里程碑正常完成1错误或超时运行时错误、LLM 失败或--timeout超时10阻塞blocked执行遇到需要人工介入的阻碍11已取消用户或编排器发出 SIGINT/SIGTERM源码中通过EXIT_SUCCESS / EXIT_ERROR / EXIT_BLOCKED / EXIT_CANCELLED常量区分这些状态mapStatusToExitCode将结构化状态success/error/blocked/cancelled映射到对应退出码。崩溃恢复采用指数退避重启backoffMs min(5000 * restartCount, 30000)最多重启--max-restarts默认 3次。核心工作流1. 从 spec 创建并执行里程碑端到端gsd headless new-milestone --context spec.md --autonew-milestone读取 spec 文件自动引导bootstrap项目目录下的.gsd/结构创建里程碑然后链式进入 auto-mode 执行全部阶段discuss → research → plan → execute → summarize → complete。--auto链式跳转的实现依赖一个内部标志--headless-chain-auto并在检测到Milestone X ready.通知后自动发送/gsd auto命令见 src/headless.ts 与 src/headless.ts。new-milestone专属参数--context pathspec/PRD 文件路径用-表示从 stdin 读取--context-text text内联 spec 文本--auto创建完成后立即链入 auto-mode# 三种等价用法 gsd headless new-milestone --context spec.md gsd headless new-milestone --context-text Build a REST API --auto cat spec.md | gsd headless new-milestone --context - --auto在源码层面new-milestone会先加载上下文文件或文本若当前目录尚无.gsd/则调用bootstrapGsdProject初始化目录结构再把上下文写入.gsd/runtime/headless-context.md供 RPC 子进程读取见 src/headless.ts。2. 运行所有排队工作gsd headless auto默认命令。循环执行所有待处理单元直到里程碑完成或进入阻塞状态。这是放手让 GSD 干完活的模式适合信任构建过程、只关心最终结果的场景。3. 只运行一个单元gsd headless next恰好执行一个单元task/slice/milestone step后退出。这是逐步编排的核心命令——每一步之间外部决策逻辑可以介入例如检查预算、上报进度、决定是否改道。4. 即时状态快照不启动 LLMgsd headless query返回单个 JSON 对象包含完整项目快照——不启动 LLM 会话毫秒级返回约 50ms零成本。这是编排器检查状态的推荐方式。{ state: { phase: executing, activeMilestone: {...}, activeSlice: {...}, progress: {...}, registry: [...] }, next: { action: dispatch, unitType: execute-task, unitId: M001/S01/T01 }, cost: { workers: [{ milestoneId: M001, cost: 1.50, ... }], total: 1.50 } }从 src/headless-query.ts 的实现看query是纯只读命令它加载 GSD 扩展的deriveState从磁盘文件推导状态、resolveDispatch对下一个调度动作做干跑预览与readAllSessionStatuses聚合各并行 worker 的成本然后直接输出 JSON 快照全程不创建 RPC 子进程因此可以放心地高频轮询。常用解析示例# 项目处于哪个阶段 gsd headless query | jq .state.phase # auto-mode 接下来会做什么 gsd headless query | jq .next # 全部并行 worker 的总花费 gsd headless query | jq .cost.total5. 强制调度到指定阶段gsd headless dispatch research|plan|execute|complete|reassess|uat|replan强制路由到某个具体阶段绕过正常的状态机路由。适合编排器需要干预执行路径例如跳过某个阻塞环节的场景。编排器模式轮询-反应循环Poll-and-Reactquery零成本、毫秒级因此可以高频调用。最基础的编排循环如下# 即时状态检查——无 LLM 成本 PHASE$(gsd headless query | jq -r .state.phase) NEXT_ACTION$(gsd headless query | jq -r .next.action) case $PHASE in complete) echo Done ;; blocked) echo Needs intervention ;; *) [ $NEXT_ACTION dispatch ] gsd headless next ;; esac更完整的poll_project函数含进度与成本报告见 monitor-and-poll 工作流它按阶段分类输出COMPLETE / BLOCKED / IN_PROGRESS三种状态行。逐步执行 监控Step-by-Stepwhile true; do gsd headless next EXIT$? [ $EXIT -ne 0 ] break # 步骤之间做即时进度检查 gsd headless query | jq {phase: .state.phase, progress: .state.progress} done完整的逐步执行脚本含预算检查、阶段完成判定、进度上报见 step-by-step 工作流。其核心思路是每执行一步next解析退出码退出码0继续1记录失败并退出10查询.state处理阻塞11判定取消随后用query检查是否到达complete阶段、累计成本是否超过MAX_BUDGET。多会话编排Multi-Session OrchestrationGSD 通过.gsd/parallel/目录下的文件实现进程间通信IPC——不使用 socket 或端口。完整的架构说明见 multi-session 参考文档。每个 worker 的隔离方式GSD_MILESTONE_LOCKM00X——状态推导只看到这一个里程碑GSD_PARALLEL_WORKER1——阻止嵌套的并行衍生专属 git worktree.gsd/worktrees/M00X/分支milestone/M00X# 为 M001 在其 worktree 中派生一个 worker GSD_MILESTONE_LOCKM001 GSD_PARALLEL_WORKER1 \ gsd headless --json auto \ --cwd .gsd/worktrees/M001 2worker-M001.log # 监控全部 worker读取 .gsd/parallel/*.status.json for f in .gsd/parallel/*.status.json; do jq {mid: .milestoneId, state: .state, unit: .currentUnit.id, cost: .cost} $f done # 向 M001 发送暂停信号 echo {signal:pause,sentAt:$(date %s000),from:coordinator} \ .gsd/parallel/M001.signal.json状态文件字段milestoneId、pid、staterunning/paused/stopped/error、currentUnit、completedUnits、cost、lastHeartbeat、startedAt、worktreePath。信号命令pause、resume、stop、rebase。存活检测PID 存活检查kill -0 $pid 心跳新鲜度30 秒超时。过期会话会被自动清理。跨项目编排每个项目有自己独立的.gsd/目录GSD 本身没有跨项目感知编排器必须自行维护(projectPath, milestoneId)元组注册表来桥接多个项目。JSONL 事件流使用--json在 stdout 上获取实时事件供下游处理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完整可用的事件类型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、init_result见 src/headless.ts。过滤事件流使用--events只接收特定事件类型减少编排器收到的噪音# 只要与阶段相关的事件 gsd headless --events agent_end,extension_ui_request auto 2/dev/null # 只要工具执行事件 gsd headless --events tool_execution_start,tool_execution_end auto重要语义--events的过滤只作用于 stdout 输出。内部处理完成检测、supervised 模式、答案注入完全不受影响——所有事件仍然会在内部被完整处理见 src/headless.ts过滤仅发生在 JSONL 转发分支。答案注入Answer Injection--answers允许为 headless 运行预置答案与密钥从而消除交互式提示gsd headless --answers answers.json auto答案文件的 JSON Schema{ questions: { question_id: selected_option }, secrets: { API_KEY: sk-... }, defaults: { strategy: first_option } }questions—— 问题 ID → 答案单选用字符串多选用字符串数组string[]secrets—— 环境变量名 → 值注入到子进程环境变量中defaults.strategy——first_option默认或cancel用于未匹配到答案的问题从 src/headless-answers.ts 的loadAndValidateAnswerFile实现可见答案文件会做严格校验必须是 JSON 对象questions的值必须是 string 或全为 string 的数组secrets的值必须是 stringdefaults.strategy只能是first_option或cancel非法内容会直接报错退出。密钥注入原理编排器通过--answers传入答案文件headless 读取文件将密钥设置为子进程环境变量见 src/headless.ts通过clientOptions.env injector.getSecretEnvVars()注入Agent 内的secure_env_collect工具发现密钥已存在于process.env中工具跳过交互式提示将密钥报告为已配置密钥永远不会被记录进日志或事件流。完整的机制说明见 answer-injection 参考文档。问题匹配机制采用两阶段关联观察Observe——headless 监听tool_execution_start事件中的ask_user_questions提取问题元数据ID、选项、是否允许多选匹配Match——后续的extension_ui_request事件与元数据关联用预置答案响应该机制通过带 500ms 超时的延迟处理队列处理乱序事件extension_ui_request可能先于tool_execution_start到达对应实现见 src/headless-answers.ts 的DeferredEvent与deferredEvents队列。与--supervised共存--answers和--supervised可以同时生效优先级顺序答案注入器优先尝试若无匹配答案supervised 模式转发给编排器若在--response-timeout内编排器无响应内置自动应答器兜底无答案注入时的默认行为headless 模式对所有提示类型都有内置自动应答器提示类型默认行为Select选择第一个选项Confirm自动确认Input空字符串Editor返回预填内容或空答案注入仅在需要精确控制时覆盖这些默认值。会话结束时注入器会输出诊断统计questionsAnswered从答案文件解决的问题数、questionsDefaulted按默认策略处理的问题数、secretsProvided注入的密钥数未使用的 question ID 和密钥键会给出警告。编排器使用示例# 创建答案文件 cat answers.json EOF { questions: { test_framework: vitest, package_manager: pnpm }, secrets: { OPENAI_API_KEY: sk-..., DATABASE_URL: postgres://localhost:5432/mydb }, defaults: { strategy: first_option } } EOF # 用预置答案运行 gsd headless --answers answers.json --output-format json auto 2/dev/null # 解析结果 RESULT$(gsd headless --answers answers.json --output-format json next 2/dev/null) echo $RESULT | jq {status: .status, cost: .cost.total}GSD 项目结构所有状态以 markdown 文件形式存于.gsd/目录可纳入版本控制.gsd/ milestones/M001/ M001-CONTEXT.md # 需求、范围、决策 M001-ROADMAP.md # 带任务的切片、依赖、复选框 M001-SUMMARY.md # 完成总结 slices/S01/ S01-PLAN.md # 任务清单 S01-SUMMARY.md # 切片总结带 frontmatter tasks/T01-PLAN.md # 单个任务规范状态是从磁盘文件推导出来的——ROADMAP.md 中的复选框就是完成度的真相来源source of truth。编排器可以读取这些文件了解进度但无需也不应编辑它们GSD 负责维护。完整结构含 PROJECT.md、REQUIREMENTS.md、DECISIONS.md、KNOWLEDGE.md、STATE.md 与 T01-SUMMARY.md 等见 gsd-orchestrator 的 project_structure 一节。Headless 命令速查命令用途auto运行所有排队单元默认命令next运行一个单元query即时 JSON 快照——状态、下一步调度、成本不启动 LLMnew-milestone从 spec 创建里程碑queue排队/重排里程碑history查看执行历史支持--cost、--phase、--model、limit参数stop/pause控制 auto-modestop优雅停止pause保留状态、可恢复dispatch phase强制指定阶段skip/undo单元控制undo支持--force跳过确认doctor健康检查 自动修复steer desc执行中途硬性改写计划status进度仪表盘TUI 覆盖层适合交互使用而非解析discuss启动引导式里程碑/切片讨论prefs管理偏好全局/项目/状态/向导/设置knowledge rule\|pattern\|lesson添加持久项目知识规则追加到 KNOWLEDGE.md模式与教训作为记忆投影回 KNOWLEDGE.md完整命令参考见 commands.md其中还包含了doctor的 JSON 输出选项以及history的过滤参数细节。注意doctor与query、recover一样是 headless 中少数不需要启动 RPC 子进程的直连命令见 src/headless.ts。阶段状态机GSD 工作流按以下阶段推进pre-planning → needs-discussion → discussing → researching → planning → executing → verifying → summarizing → advancing → validating-milestone → completing-milestone → complete特殊阶段paused、blocked、replanning-slice。各阶段在编排循环中的含义与应对动作见 monitor-and-poll.md 的阶段表——例如blocked阶段应查询.state.blockers并选择steer 绕过 / 注入答案 / dispatch 强制阶段 / 上报人工四种处理路径之一。工作单元层级Milestone里程碑可交付版本4–10 个切片1–4 周Slice切片一个可演示的纵向能力1–7 个任务1–3 天Task任务一个上下文窗口大小的工作单元一个会话结构化结果HeadlessJsonResult使用--output-format json时headless 会静默收集事件并在进程退出时向 stdout 输出单个HeadlessJsonResultJSON 对象——这是编排器做决策的结构化结果类型定义见 src/headless-types.ts字段参考与示例见 json-result.md。# 捕获 JSON 结果注意进度文本走 stderrJSON 结果走 stdout RESULT$(gsd headless --output-format json next 2/dev/null) EXIT$? echo $RESULT | jq .status echo $RESULT | jq .cost.total echo $RESULT | jq .nextAction重要解析 stdout 时必须把 stderr 重定向到/dev/null。顶层字段字段类型说明statussuccess \| error \| blocked \| cancelled \| timeout最终会话状态直接映射到退出码exitCodenumber进程退出码0成功、1错误/超时、10阻塞、11取消sessionIdstring \| undefined会话标识可传给--resume id继续该会话durationnumber会话墙钟时长毫秒costCostObjecttoken 用量与成本分解toolCallsnumber会话期间的工具调用总数eventsnumber会话期间处理的事件总数milestonestring \| undefined活动里程碑 ID如M001phasestring \| undefined会话结束时的 GSD 阶段如executing、blocked、completenextActionstring \| undefined状态机推荐的下一个动作如dispatch、completeartifactsstring[] \| undefined会话中创建或修改的产物路径commitsstring[] \| undefined会话中产生的 Git commit SHA成本对象字段说明cost.total会话总成本美元cost.input_tokens消耗的输入 token 数cost.output_tokens生成的输出 token 数cost.cache_read_tokens命中提示词缓存的 token 数cost.cache_write_tokens写入提示词缓存的 token 数成本统计在源码中采用累计最大值模式--output-format json模式下 headless 静默跟踪cost_update事件中的cumulativeCost用Math.max汇总各次报告的成本与 token 数避免重复计数见 src/headless.ts。每一步之后的决策示例RESULT$(gsd headless --output-format json next 2/dev/null) EXIT$? case $EXIT in 0) PHASE$(echo $RESULT | jq -r .phase) NEXT$(echo $RESULT | jq -r .nextAction) echo Success — phase: $PHASE, next: $NEXT ;; 1) STATUS$(echo $RESULT | jq -r .status) echo Failed — status: $STATUS ;; 10) echo Blocked — needs intervention gsd headless query | jq .state ;; 11) echo Cancelled ;; esac会话恢复与产物收集# 第一次运行——捕获会话 ID RESULT$(gsd headless --output-format json next 2/dev/null) SESSION_ID$(echo $RESULT | jq -r .sessionId) # 稍后用同一个会话 ID 恢复 gsd headless --resume $SESSION_ID --output-format json next 2/dev/null # 列出会话期间创建/修改的文件与提交 RESULT$(gsd headless --output-format json auto 2/dev/null) echo $RESULT | jq -r .artifacts[]? echo $RESULT | jq -r .commits[]?--resume在源码中会先列出项目会话目录下的所有会话然后按精确 ID 优先、前缀匹配兜底的规则解析前缀匹配到 0 个或多个会话都会报错见 src/headless.ts 与 src/headless.ts。处理阻塞的完整路径当退出码为10或阶段为blocked时编排器有五条可选路径详见 monitor-and-poll.md 的Handling Blockers一节# 1. 理解阻塞原因 gsd headless query | jq {phase: .state.phase, blockers: .state.blockers, nextAction: .state.nextAction} # 2. 方案 A用 steer 绕过 gsd headless steer Skip the database dependency, use in-memory storage instead # 3. 方案 B注入预置答案 cat fix.json EOF { questions: { blocked_question_id: workaround_option }, defaults: { strategy: first_option } } EOF gsd headless --answers fix.json auto # 4. 方案 C强制指定阶段 gsd headless dispatch replan # 5. 方案 D升级给用户 echo GSD build blocked. Phase: $(gsd headless query | jq -r .state.phase) echo Manual intervention required.预算强制模式结合query的零成本特性编排器可以在每次迭代后检查累计成本并执行预算红线MAX_BUDGET15.00 check_budget() { TOTAL$(gsd headless query | jq -r .cost.total) OVER$(echo $TOTAL $MAX_BUDGET | bc -l) if [ $OVER 1 ]; then echo Budget exceeded: \$$TOTAL \$$MAX_BUDGET gsd headless stop return 1 fi return 0 }多 worker 场景下还可以对所有.gsd/parallel/*.status.json的cost字段求和超限时逐个发送stop信号批量叫停。关键实践提醒标志位必须在命令之前gsd headless [--flags] [command] [args]命令后的标志会被当作参数忽略。解析 JSON 务必重定向 stderrJSON 输出走 stdout进度走 stderr2/dev/null是标准姿势。用query而非auto查状态query不启动 LLM、毫秒级、零成本是步骤之间的最佳状态源。长任务前先设预算在启动长时间运行前先读取cost.total并设定MAX_BUDGET红线。每个构建独立目录每个 GSD 项目需要自己的目录与.gsd/文件夹跨项目编排时由编排器维护(projectPath, milestoneId)注册表。复用会话sessionId是编排器的指针配合--resume可在中断后无损续跑。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐GSD 命令完全参考从 /gsd auto 自主模式到 Headless 自动化的实战指南GSD 命令完全参考从 /gsd auto 自主模式到 Headless 自动化的实战指南 GSDGet Shit Done是一套基于 meta prom人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD 无头模式命令参考用 gsd headless 构建可编程的自动化软件交付流水线GSD 无头模式命令参考用 gsd headless 构建可编程的自动化软件交付流水线 本文是 gsd 2 仓库中 GSDGet Shit Done无头模人工智能AI Agent代码智能体Agent 编排CLIAI 应用gsd headless 模式实战指南面向 CI/CD 的无 TUI 自动化执行、状态查询与故障恢复gsd headless 模式实战指南面向 CI/CD 的无 TUI 自动化执行、状态查询与故障恢复 gsd headless 是 GSDGitHub 加速人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇微博图片批量下载终极指南如何高效获取高清素材库下一篇Ocelot 路由元数据Metadata扩展机制配置 Schema、GetMetadataT 类型转换与中间件实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考