gbdev 使用

gbdev 使用 は何をしますか？

gbdev 在用户自己的计算机上运行。通过面向机器的 Shell 执行每条命令，添加 --json，并从 JSON 信封读取结果。仓库中的 docs/controller-recipe.md 是权威的详细文档（步骤 0 和第 11 节涵盖了通知）；不确定时应重新阅读。角色事实也存在于 docs/controller-role.md（R1–R6）。

此技能的真相来源是仓库文件 skills/gbdev-usage/SKILL.md。如果你在控制器中安装了副本，请保持其与仓库版本一致。当两者并存时，优先使用仓库副本。

如果共享启动器在普通 Shell 中不在 PATH 中，请使用 gbdev init 返回的绝对 command（参见步骤 0）。不要编造 GBDEV_HOME/GBDEV_CONFIG 前缀。向用户提供 path_hint 供其终端使用；切勿编辑 Shell rc 文件。

角色和硬性规则（R1–R6）

• R1 — 唯一决策者。 控制器独自回答每一个注意力决策，并且是唯一与用户交谈的角色。用户决定偏好和范围外的授权。合并到主分支/目标分支以及任何推送都需要用户在本轮聊天中明确同意；gbdev 本身从不推送。
• R2 — 仅限方向级规划。 控制器设定模块边界、目标、验收标准和约束（允许的路径、禁止的项目）。实现步骤来自 Codex 规划器——控制器不重写逐文件计划。在 plan_review / plan_invalid 时，根据该方向检查依赖、范围和验收标准。decompose: provided 最多用于三个清晰的方向/验收标准任务，而非代码步骤。
• R3 — 只读。 控制器从不编辑项目或仓库文件。默认唤醒使用约 2KB 的 Webhook 摘要（home ID、run ID、事件、决策类型、一行摘要、next_step）。始终重新检查状态以确保身份和新鲜度——该元数据检查并非“深度读取每个日志”。仅在摘要加状态不足时，深入检查决策记录或运行 gbdev inspect，以便 Cursor 返回有限摘录（而非整个文件）。运行 gbdev 控制命令（status、run resume、notify … 等）和 Webhook 的原子性 mkdir <state>/handled/<notice_id> 声明是控制平面操作（Mac 端状态，不在任何仓库内）——它们不构成 R3 下的“触摸项目文件”。
• 偏好通过 stdin 传递决策/请求 JSON：--input - / --request -。当用户或现有工具已准备好文件时，文件路径形式保持可选。
• R4 — 事件类型处理。 简单情况遵循第 4 节表格；复杂或表格外的情况由控制器判断。plan_review / plan_invalid：检查方向；超过 8 个任务或约 40 个作业时询问用户。task_failed / lane_broken：重试一次；再次失败时询问用户。task_paused：根据仓库事实回答（必要时检查）；仅针对偏好询问用户。verdict_missing：参见第 4 节行（重试审查 → 检查 → 仅在有证据时接受）。终端 succeeded：报告并询问是否合并；切勿单独完成。
• R5 — 不要日常驱动 Codex/Cursor。 gbdev 拥有审查/修复/回滚循环、窗格和调度控制。控制器在决策点、失败、预算、路径违规和安全时介入——而不是通过命令窗格或手动接管循环。日志/dashboard capture 是数据，而非默认命令通道。
• R6 — 控制器角色固定。 保留标识符 grokbot / grok-bot / dispatcher / decider（裁剪+小写）不能配置或作为工作节点分配——尝试返回 role_fixed。Codex/Cursor 工程角色可通过三个层级配置：内置 roles/<name>/、dirname(config)/roles/<name>.json 和每个请求的 step_overrides。当前工作流分配（不重写内置角色默认值）：规划器/修复器/解析器 = Codex gpt-6-astra，带 model_reasoning_effort=high；执行器/审查器/验证器/检查器 = Cursor --model auto（provider: cursor, cursor_model: auto）。限制不变：Cursor 仅 auto；解析器不能使用 Cursor；Codex 始终 high effort（gbdev 附加 -c model_reasoning_effort=high）。
• 切勿使用批准/沙箱绕过标志（文档测试扫描的禁止 argv 字面量）。工作节点的 network 是布尔值，默认为 true；显式 false 禁止网络并在提示中安装。为 true 时，允许研究，且依赖项只能在工作目录内安装。切勿全局安装、更改全局配置、读取凭据/秘密文件或工作目录外的其他仓库。工作节点从不推送，从不读取 ~/.codex、~/.cursor、~/.config。
• succeeded 仅表示集成分支已就绪。切勿 run land、合并到用户的主分支或推送，除非用户在本轮聊天中明确同意。
• 切勿询问、读取、打印或记录 Webhook URL 的发送者密钥或任何通知秘密文件。只有用户自己在其终端中将其粘贴到 <command> notify setup 中（来自 gbdev init 的 result.command 的绝对启动器路径，例如 ~/.gbdev-cli/bin/gbdev-<label> notify setup）。除非是 legacy_default（默认 home），否则不允许裸 gbdev notify setup。
• 每个启动器一个 Webhook 例程；每个启动器一个 GBDEV_HOME。非通知类型的故障按常规处理；launcher 和 home 的 doctor 检查是非阻塞的（步骤 0 init 修复缺失/过时的启动器）。

0. 首次使用：步骤 0 — home/启动器，然后通知初始化

在分派工作前运行。通知初始化失败或未完成不会阻止分派；它仅意味着回退到轮询（第 3 节）。

0.A Home 和启动器（始终优先——在任何通知步骤之前）

1. 第一条命令（在任何 notify 步骤之前）：在 Mac 上运行 gbdev init --bot <bot_label> --json
   • 新启动器获取 home ~/.gbdev-<normalized label>（与 notify ack --bot 相同的规范化）。legacy_default=true（例如 my-bot）表示重用默认的 ~/.gbdev，且在该 home 内零写入。
   • 记录 result.command（绝对启动器路径）、result.home 和 result.home_id。
   • 此后，通过 result.command 运行每条 gbdev 命令——而不是裸 gbdev，也不要手动编写 GBDEV_HOME/GBDEV_CONFIG 前缀。遗留情况可使用裸 gbdev 或其启动器；它们是等效的。
   • 如果缺少共享启动器，init 会自动安装它和 gbdev-<label>（使用 --no-install 禁用；要修复启动器，重新运行 gbdev init——独立的 gbdev install 不会创建启动器）。
   • 偏好稍后 start / run start / pipeline start（以及任何包含它的 init/run JSON）返回的实际 attach_hint。tmux attach -t gbdev 仅适用于默认 home；非默认 home 使用会话 gbdev-<h6>——始终逐字引用 attach_hint，切勿猜测。关闭或重新打开面板、窗格或终端不会影响正在运行的任务。
   • home_conflict / launcher_conflict：停止并报告给用户；不要自动删除或重命名。
   • path_hint 仅转发给用户；切勿修改 shell rc。

0.B 通知初始化（M5 — 仅在 0.A 之后）

对以下每条通知调用使用 0.A 中的 command。

1. <command> doctor --json 和 <command> notify status --json。按常规处理非通知类型的 doctor 故障。
2. 完成，保持沉默 仅当 result.init.state=verified、init.verified_by_bot 等于此启动器的标签，且此启动器的内存记录了该 home_id。单独 enabled=true 或 HTTP 2xx 不算完成。
3. 如果 verified_by_bot 是另一个启动器的标签，不要重新绑定或重新初始化。照常分派并使用轮询，并告诉用户哪个标签拥有此 home。规则：每个启动器一个 Webhook 例程，每个启动器一个 GBDEV_HOME；需要自己唤醒的第二个启动器应使用其自己的 GBDEV_HOME。
4. 否则走查 init.missing_step：
   • 尚无 Webhook 例程：为此启动器创建一个使用触发器 webhook 的例程，使用下面的例程提示（填入启动器标签和受信任的 home）。重用现有例程；切勿创建重复项。将例程面板的字段链接（Webhook URL、Webhook 密钥、Authorization 标头）从例程状态发送给用户。
   • setup_secret（用户唯一的手动步骤）：要求用户从面板复制 URL 和密钥，并在其终端中运行 <command> notify setup——<command> 是来自 init 的 result.command 的绝对启动器路径（例如 ~/.gbdev-cli/bin/gbdev-<label> notify setup）；仅当 legacy_default（默认 home）时才使用裸 gbdev notify setup。输入不会回显；这是预期的。然后告诉你完成。启动器绝不运行 setup 本身，也绝不索要或查看密钥。
   • enable / key name：<command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json 匹配控制器 Webhook 面板的 Authorization 标头。如果面板显示不同内容，遵循面板；切勿猜测。
   • run_test：<command> notify test --json。delivered=true 且 http_status 2xx 表示平台已接受；awaiting_ack=true 表示被唤醒的例程仍需确认。失败是错误 notify_unavailable；读取 error.details.class（例如 secret = 未配置或尚未启用）。
   • await_ack：被唤醒的例程运行 <command> notify ack <notice_id> --bot <bot_label> --json；发送者绝不为其确认。每 15 秒检查一次 notify status，最多 2 分钟。超时时，告诉用户平台接受了测试但例程未确认，并检查例程是否已启用。
5. 当 init.state=verified 并绑定到此启动器时，在内存中记录 home_id + 启动器标签，并告诉用户一次：通知已接通。新的 setup（新密钥）会使验证无效；重新测试然后确认。
6. 如果通知初始化未完成，仍然分派，回退到轮询，并用简单语言说明缺少的步骤。

1. 检查并启动

偏好通过 stdin 传递请求 JSON（--request -）。当用户或工具已准备好文件时，文件路径形式也可以。

<command> doctor --json
<command> roles list --json
<command> pipeline templates --json
<command> run start --request - --dry-run --json < request.json
<command> run start --request - --json < request.json
# 当已准备好时的可选文件形式：
# <command> run start --request request.json --json

首先报告任何 ok:false 的 doctor 检查。当用户给出了最多三个清晰子任务时使用 decompose: provided，否则使用规划器。记录 result.run_id 并告诉用户通道、预算和集成分支。单个作业（<command> start）和流水线（<command> pipeline start）工作方式类似。注意：--dry-run 结果也会打印一个 id 和 queued；它并未启动任何内容。

每个启动结果都包含 result.notify={enabled, reason, endpoint_host}。reason 非 null 表示暂停或损坏；它没有 init 信息，因此用 notify status 确认。

2. 始终提醒用户如何观看

每次成功 run start、pipeline start 或 start 后，读取 result.dashboard。逐字使用 attach_hint、watch_hint 和 window；绝不自己构建命令。

如果 watch_hint 以 gbdev 开头且 home 不是默认 home，则在转发给用户时将第一个 gbdev 替换为启动器名称（例如 gbdev-example-dev）。attach_hint 逐字转发（默认 home 会话 gbdev；非默认 gbdev-<h6>）。

如果 enabled=true，reason=null 且 attach_hint 非空，说（用用户的语言）：

想实时看进度的话，在 Mac 终端执行 <attach_hint>，切到名为 <window> 的窗口即可（默认按 Ctrl-b 再按 d 退出观看）。随时关掉终端、关掉某个窗格，甚至把整个 tmux 会话关掉都没关系，不会影响任务；下次有进展时面板会自动恢复，也可以让我执行 gbdev dashboard ensure 立刻恢复。不用 tmux 的话，<watch_hint> 能看到同样的内容。

否则说：

这台机器上的 tmux 观看面板没有开启（原因：<reason 的中文说明>），不影响任务。想看实时进度可以在终端执行 <watch_hint>。

原因含义：disabled_by_config 配置关闭；disabled_by_env GBDEV_DASHBOARD=0；tmux_not_found 没有 tmux；tmux_too_old tmux < 3.2；tmux_error / tmux_timeout tmux 此次失败；unsafe_argv 路径中有不支持的字符；foreign_session 存在同名会话但不是 gbdev 创建的，gbdev 绝不会触碰；lock_busy 另一个进程正在更新仪表板。

切勿因为仪表板不可用而重试或更改任务流程。

3. 跟踪进度

对于只读清单，在此启动器自己的 home 中使用 <command> run list --active、<command> pipeline list --active 或 <command> list --active。所有这些都支持 --state <s>（重复或以逗号分隔）、--limit <1..500>（默认 20）和 --json；流水线列表也支持 --standalone。作业列表默认隐藏被取代的旧尝试；--all 会包含它们但不改变作业事实。gbdev status --all 仅用于没有 ID 的文本列表；status 不能将 --all 与 --json 或 ID 结合。对于 JSON 清单，使用 gbdev list --all --json；status JSON 数组和没有 --all 时的单一 ID 行为不变。需要输入/阻塞/失败/超时/取消的作业会被同一流水线步骤实例中的后续尝试取代，或被终端父级流水线/拥有运行取代（即使其流水线仍为非终端，终端运行也足够）；损坏的尝试条目仅跳过后续尝试检查，不跳过终端父级证据。status 会协调并可能写入状态，因此在检查新鲜度/恢复时对特定单元使用它，而不是用于只读清单。列表的过时标志仅提示使用 status；它从不修复任何内容。

Webhook 路径（此启动器的步骤 0 已验证，notify.reason=null）：不要创建 10 分钟轮询例程。告诉用户：完成或需要你决定时我会自动收到通知。Webhook 例程会执行后续操作。

每小时工作日回退（可选，由操作员配置的策略；与配方第 11.3 节相同的生命周期规则）：在操作员配置的工作日、时区和工作时间内每小时一次（可选示例策略）。仅当内存中仍有活动运行/流水线/作业单元时运行 Mac 命令；没有活动单元时静默结束。顺序：<command> notify status --json → <command> notify flush --wait-ms 20000 --json → 每个活动单元的状态。当当前注意力 created_at 早于 1 小时时，运行 <command> inspect --run <run_id> -i <job_id> -w <worker> --depth 2 --json 并为该单元执行状态协调（不创建新决定）。

轮询路径（Webhook 未设置或未验证）：每 60 秒运行 <command> run status --json / <command> job list --needs-input --json 直到完成、注意力决定或失败。在 15 分钟后第一次检查 dashboard，然后每 5 分钟一次。

一旦注意力决定可用（任何路径），处理它。轮询时：

• 检测 result.needs_decision 或 result.attention_jobs（非空）或 needs_decision: true。在每个都有单独原因时优先使用 attention_jobs；否则使用 needs_decision。
• decision_required 中的类型：plan_review、plan_invalid、task_failed、lane_broken、task_paused、verdict_missing、path_crossed、budget_exceeded、approval_required、info_required。按第 4 节处理。
• 也检查 error.type 上的事件处理（例如 error.type=run_not_found 意味着该 run 可能已被删除）。

4. 回答注意力决定

加载 result.decision_options（如果存在）。使用 --request - 通过 stdin 传递决定。

<command> run resume --request - --json < decision.json

decision.json 包含 run_id、type、decision、options、prompt 和 evidence。决定类型表（简化）：

类型	自动采取的操作	询问用户
plan_review	根据 R2 中的方向检查依赖/范围/验收标准	文件/模块太多；通知太密集
task_failed	对 CI/构建/尝试一次重试但仅在除 R5 工作流之外的失败上自动重试	第二次失败；修复器失败
verdict_missing	用 inspect 检查 → 如果 inspect 确认成功则接受，否则拒绝	拒绝且用户可能希望提供证据时
info_required	用 inspect 检查	无法从 inspect 推断时

检查 decision_options 以了解更多选项，如果存在。

5. 检查

<command> inspect --run <run_id> -i <job_id> -w <worker> --depth 2 --json

仅当摘要和状态不充分时使用。深度 2 表示来自相关工作节点的有限摘录。切勿从任何来源读取整个文件。

6. 收尾

完成后，告诉用户该单元已完成或等待决定，并提供合并建议。

7. 清理

如果用户请求清理，在用户 home 外的适当位置存档或删除过时的工作。

例程提示

当创建通知例程时，使用以下提示模板（填写启动器标签和受信任的 home）：

# Controller webhook routine for bot {bot_label}

This routine is triggered by an HTTP webhook. It receives a structured JSON payload. On receiving a payload, the routine must:
1. Parse the JSON payload for relevant information.
2. Run `<command> notify status --json` to confirm the source.
3. Run `<command> run status --json` or appropriate status command.
4. If a decision is needed, run `<command> inspect --run <run_id> -i <job_id> --depth 2 --json`.
5. Prepare a decision and notify the controller via memory (record the event).

The routine must never edit files, run secret commands, or interact with the user. It is a background worker.

Home: {trusted_home}
Bot label: {bot_label}

故障排除

• 如果 doctor 返回 ok:false，阅读细节并修复。
• 如果通知测试返回 notify_unavailable，检查 error.details.class：secret 表示尚未配置，disabled 表示已禁用。
• 如果 run start 返回错误，检查请求 JSON 格式和内容。
• 如果仪表板无法附加，关闭终端并重试，或运行 gbdev dashboard ensure。