MarcusYuan/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 摘要（主页 ID、运行 ID、事件、决策类型、单行摘要、next_step）。始终检查状态以确保身份/新鲜度——这种元数据检查不是“深入读取所有日志”。仅当摘要和状态不足时，才深入检查决策记录或运行 gbdev inspect，以便 Cursor 返回有限的摘录（而不是整个文件）。运行 gbdev 控制命令（status、run resume、notify … 等）和 webhook 原子操作 mkdir <state>/handled/<notice_id> 声明属于控制平面操作（Mac 端状态，不在任何仓库内部）——它们不属于 R3 规则下的“接触项目文件”。
• 优先使用标准输入传递决策/请求 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 始终高努力（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（默认主页）使用裸 gbdev notify setup。
• 每个机器人一个 webhook 例程；每个机器人一个 GBDEV_HOME。非通知类故障按常规处理；launcher 和 home 的 doctor 检查是非阻塞的（步骤 0 初始化会修复缺失/过时的启动器）。

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

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

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

1. 第一条命令（在任何 notify 步骤之前）：在 Mac 上运行 gbdev init --bot <bot_label> --json
   • 新机器人获得主页 ~/.gbdev-<规范化标签>（与 notify ack --bot 的规范化相同）。legacy_default=true（例如 my-bot）意味着重用默认的 ~/.gbdev，并且在该主页内部零写入。
   • 记录 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 仅适用于默认主页；非默认主页使用会话 gbdev-<h6>——始终按原样引用 attach_hint，绝不猜测。关闭或重新打开面板、窗格或终端不会影响正在运行的任务。
   • home_conflict / launcher_conflict：停止并报告给用户；不要自动删除或重命名。
   • path_hint 仅转达给用户；绝不修改 Shell rc。

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

对下面的每个 notify 调用使用 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 是另一个机器人的标签，不要重新绑定或重新初始化。照常使用轮询进行分派，并告知用户哪个标签拥有此主页。规则：每个机器人一个 webhook 例程，每个机器人一个 GBDEV_HOME；需要自己唤醒功能的第二个机器人应使用自己的 GBDEV_HOME。
4. 否则遍历 init.missing_step：
   • 尚无 webhook 例程：为此机器人创建自己的例程，触发器为 webhook，使用下面的例程提示（填写机器人标签和受信任的主页）。重用现有例程；绝不创建重复项。向用户发送例程面板中的字段链接（Webhook URL、Webhook 密钥、Authorization 标头）。
   • setup_secret（用户唯一的操作步骤）：要求用户从面板复制 URL 和密钥，并在其终端中运行 <command> notify setup——<command> 是 init 的 result.command 中的绝对机器人启动器路径（例如 ~/.gbdev-cli/bin/gbdev-<label> notify setup）；仅当 legacy_default（默认主页）时才使用裸 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. 检查并启动

优先使用标准输入传递请求 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 非空表示暂停或损坏；它不包含初始化信息，因此请使用 notify status 确认。

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

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

如果 watch_hint 以 gbdev 开头且主页不是默认主页，则在转达给用户时将第一个 gbdev 替换为机器人启动器名称（例如 gbdev-example-dev）。按原样转达 attach_hint（默认主页会话 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. 跟踪进度

对于只读盘点，在此机器人的主页中使用 <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 数组和单 ID 行为（不带 --all）保持不变。如果需要输入/已阻塞/失败/超时/已取消的任务会被同一流水线步骤实例中的后续尝试取代，或被终端的父流水线/所属运行（即使其流水线仍为非终端，终端运行也足够）取代；损坏的尝试条目仅跳过后续尝试检查，而不跳过终端父级证据。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

…