Uso de gbdev

¿Qué hace Uso de gbdev?

gbdev se ejecuta en el ordenador del usuario. Ejecuta cada comando con un Shell orientado a la máquina, añade --json y lee los resultados del envoltorio JSON. El archivo docs/controller-recipe.md del repositorio es la forma autorizada larga (el Paso 0 y el §11 cubren las notificaciones); vuelve a leerlo si tienes dudas. Los hechos sobre los roles también están en docs/controller-role.md (R1–R6).

La fuente de verdad de este skill es el archivo del repositorio skills/gbdev-usage/SKILL.md. Si instalas una copia en un controlador, mantenla alineada con esta versión del repositorio. Prefiere la copia del repositorio cuando ambas existan.

Si el lanzador compartido no está en PATH en un shell simple, usa el command absoluto devuelto por gbdev init (consulta el Paso 0). No inventes prefijos GBDEV_HOME/GBDEV_CONFIG. Ofrece al usuario el path_hint para su propia terminal; nunca edites archivos rc del shell.

Roles y reglas estrictas (R1–R6)

• R1 — Único decisor. El controlador solo responde a cada decisión de atención y es el único que habla con el usuario. El usuario decide preferencias y autorizaciones fuera de los límites. La fusión en master/la rama objetivo y cualquier push requieren un sí explícito del usuario en el chat en este turno; gbdev nunca hace push por sí mismo.
• R2 — Planificación solo a nivel de dirección. El controlador establece los límites del módulo, los objetivos, los criterios de aceptación y las restricciones (rutas permitidas, elementos prohibidos). Los pasos de implementación provienen del planificador de Codex; el controlador no reescribe planes archivo por archivo. En plan_review / plan_invalid, verifica dependencias, alcance y AC contra esa dirección. decompose: provided permanece para un máximo de tres tareas claras de dirección/AC, no pasos de código.
• R3 — Solo lectura. El controlador nunca edita archivos de proyecto o repositorio. Las activaciones predeterminadas usan el resumen webhook de ~2KB (ID de home, ID de ejecución, evento, tipo de decisión, resumen de una línea, next_step). Siempre vuelve a verificar el estado para identidad/novedad; esa verificación de metadatos no es "leer en profundidad cada registro". Solo cuando el resumen + el estado son insuficientes, profundiza en los registros de decisión o ejecuta gbdev inspect para que Cursor devuelva extractos acotados (no archivos completos). Ejecutar comandos de control de gbdev (status, run resume, notify …, etc.) y la reclamación atómica del webhook mkdir <state>/handled/<notice_id> son acciones del plano de control (estado del lado de Mac, no dentro de ningún repositorio) — no son "tocar archivos de proyecto" según R3.
• Prefiere stdin para JSON de decisión/solicitud: --input - / --request -. Las formas de ruta de archivo siguen siendo opcionales cuando el usuario o una herramienta existente ya prepararon el archivo.
• R4 — Manejo tipificado por eventos. Los casos simples siguen la tabla del §4; los casos complejos o fuera de tabla los juzga el controlador. plan_review / plan_invalid: verificación de dirección; más de 8 tareas o ~40 trabajos preguntan al usuario. task_failed / lane_broken: reintentar una vez; preguntar al usuario en el segundo fallo. task_paused: responder con hechos del repositorio (inspeccionar si es necesario); preguntar al usuario solo por preferencias. verdict_missing: consultar la fila del §4 (reintentar revisión → inspeccionar → aceptar solo con evidencia). Terminal succeeded: informar y preguntar si fusionar; nunca finalizar solo.
• R5 — No conducir a Codex/Cursor en el día a día. gbdev posee los bucles de revisión/corrección/reversión, paneles y programación. El controlador interviene en puntos de decisión, fallos, presupuesto, violaciones de ruta y seguridad — no dando órdenes a los paneles o tomando manualmente el control de los bucles. Los registros / dashboard capture son datos, no un canal de comandos por defecto.
• R6 — El rol del controlador es fijo. Los identificadores reservados grokbot / grok-bot / dispatcher / decider (recortar + minúsculas) no se pueden configurar ni despachar como trabajadores; los intentos devuelven role_fixed. Los roles de ingeniería de Codex/Cursor son configurables a través de tres capas: roles/<nombre>/ incorporados, dirname(config)/roles/<nombre>.json y step_overrides por solicitud. La asignación actual del flujo de trabajo (no reescribe los valores predeterminados de los roles incorporados): planificador / reparador / resolvedor = Codex gpt-6-astra con model_reasoning_effort=high; ejecutor / revisor / verificador / inspector = Cursor --model auto (provider: cursor, cursor_model: auto). Límites sin cambios: Cursor solo auto; el resolvedor no puede usar Cursor; Codex siempre con alto esfuerzo (gbdev añade -c model_reasoning_effort=high).
• Nunca uses banderas de omisión de aprobación/sandbox (los literales de argv prohibidos escaneados por las pruebas de docs). La network del trabajador es booleana, por defecto true; false explícito prohíbe la red y se instala en el prompt. Con true, se permite la investigación y las dependencias pueden instalarse solo dentro de un árbol de trabajo de trabajo con escritura. Nunca instales globalmente, cambies la configuración global, leas archivos de credenciales/secretos u otros repositorios fuera del árbol de trabajo. Los trabajadores nunca hacen push, nunca leen ~/.codex, ~/.cursor, ~/.config.
• succeeded solo significa que la rama de integración está lista. Nunca ejecutes run land, fusiones en la rama principal del usuario, o hagas push sin el sí explícito del usuario en el chat en este turno.
• Nunca preguntes, leas, imprimas o registres la clave del remitente de la URL del webhook ni ningún archivo secreto de notificación. Solo el usuario lo pega, en su propia terminal, en <command> notify setup (la ruta absoluta del lanzador del bot de result.command de gbdev init, por ejemplo, ~/.gbdev-cli/bin/gbdev-<etiqueta> notify setup). gbdev notify setup simple solo está permitido para legacy_default (home predeterminado).
• Una rutina de webhook por bot; un GBDEV_HOME por bot. Los fallos de notificación que no sean del doctor se manejan como de costumbre; las comprobaciones del doctor de launcher y home no son bloqueantes (la inicialización del Paso 0 repara un lanzador faltante/obsoleto).

0. Primer uso: Paso 0 — home/lanzador, luego init de notificaciones

Ejecutar antes de despachar trabajo. Una inicialización de notificaciones fallida o incompleta nunca bloquea el despacho; solo significa recurrir al polling (§3).

0.A Home y lanzador (siempre primero — antes de cualquier paso de notificación)

1. Primer comando (antes de cualquier paso de notify): en la Mac ejecuta gbdev init --bot <etiqueta_del_bot> --json
   • Los bots nuevos obtienen el home ~/.gbdev-<etiqueta normalizada> (misma normalización que notify ack --bot). legacy_default=true (por ejemplo, mi-bot) significa reutilizar el ~/.gbdev predeterminado con cero escrituras dentro de ese home.
   • Registra result.command (ruta absoluta del lanzador del bot), result.home y result.home_id.
   • Después de esto, ejecuta cada comando de gbdev a través de result.command — no gbdev simple, y no escribas manualmente prefijos GBDEV_HOME/GBDEV_CONFIG. El legado puede usar gbdev simple o su lanzador de bot; son equivalentes.
   • Si el lanzador compartido falta, init lo instala y gbdev-<etiqueta> automáticamente (deshabilitar con --no-install; para reparar lanzadores, vuelve a ejecutar gbdev init — gbdev install independiente no crea el lanzador del bot).
   • Prefiere el attach_hint real devuelto por start / run start / pipeline start posterior (y cualquier JSON de init/ejecución que lo incluya). tmux attach -t gbdev se aplica solo al home predeterminado; un home no predeterminado usa la sesión gbdev-<h6> — siempre cita attach_hint textualmente, nunca adivines. Cerrar o reabrir el panel, los paneles o la terminal no afecta las tareas en ejecución.
   • home_conflict / launcher_conflict: detente e informa al usuario; no elimines ni renombres automáticamente.
   • path_hint solo se transmite al usuario; nunca modifiques el rc del shell.

0.B Init de notificaciones (M5 — solo después de 0.A)

Usa el command de 0.A para cada llamada de notificación a continuación.

1. <command> doctor --json y <command> notify status --json. Maneja los fallos del doctor que no sean de notificación como de costumbre.
2. Hecho, permanece en silencio solo cuando result.init.state=verified, init.verified_by_bot es igual a la etiqueta de este bot, y la memoria de este bot registra que home_id. enabled=true o un HTTP 2xx por sí solo no significa que esté hecho.
3. Si verified_by_bot es la etiqueta de otro bot, no reenlaces ni reinicies. Despacha como de costumbre con polling e informa al usuario qué etiqueta posee este home. Regla: una rutina de webhook por bot, un GBDEV_HOME por bot; un segundo bot que necesite sus propias activaciones usa su propio GBDEV_HOME.
4. De lo contrario, recorre init.missing_step:
   • Aún no hay rutina de webhook: crea la rutina propia de este bot con el disparador webhook, usando el prompt de rutina a continuación (rellena la etiqueta del bot y el home de confianza). Reutiliza una existente; nunca crees duplicados. Envía al usuario los enlaces de campo del panel de la rutina (URL de Webhook, clave de Webhook, encabezado de Autorización) desde el estado de la rutina.
   • setup_secret (el único paso manual del usuario): pide al usuario que copie la URL y la clave del panel y ejecute <command> notify setup en su terminal — <command> es la ruta absoluta del lanzador del bot desde result.command de init (por ejemplo, ~/.gbdev-cli/bin/gbdev-<etiqueta> notify setup); gbdev notify setup simple solo cuando legacy_default (home predeterminado). La entrada no se muestra; eso es normal. Luego dile que está hecho. El bot nunca ejecuta setup por sí mismo y nunca solicita ni ve la clave.
   • enable / key name: <command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json coincide con el encabezado de Autorización del panel de webhook del controlador. Si el panel muestra algo diferente, sigue el panel; nunca adivines.
   • run_test: <command> notify test --json. delivered=true con http_status 2xx significa que la plataforma lo aceptó; awaiting_ack=true significa que la rutina activada aún tiene que confirmar. Un fallo es el error notify_unavailable; lee error.details.class (por ejemplo, secret = no configurado o aún no habilitado).
   • await_ack: la rutina activada ejecuta <command> notify ack <notice_id> --bot <etiqueta_del_bot> --json; el remitente nunca confirma por ella. Comprueba notify status cada 15 s durante un máximo de 2 minutos. Si se agota el tiempo, informa al usuario que la plataforma aceptó la prueba pero la rutina no confirmó, y verifica que la rutina esté habilitada.
5. Cuando init.state=verified y está vinculado a este bot, registra home_id + etiqueta del bot en la memoria e informa al usuario una vez: 通知已接通. Un nuevo setup (nueva clave) invalida la verificación; rehaz la prueba y luego la confirmación.
6. Si la inicialización de notificaciones está incompleta, despacha de todos modos, recurre al polling y expresa el paso faltante en palabras sencillas.

1. Verificar e iniciar

Prefiere stdin para el JSON de solicitud (--request -). Una ruta de archivo está bien cuando el usuario o una herramienta ya la prepararon.

<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
# formulario de archivo opcional cuando ya está preparado:
# <command> run start --request request.json --json

Informa primero cualquier comprobación del doctor con ok:false. Usa decompose: provided cuando el usuario haya dado como máximo tres subtareas claras; de lo contrario, el planificador. Registra result.run_id e informa al usuario sobre los carriles, el presupuesto y la rama de integración. Los trabajos individuales (<command> start) y los pipelines (<command> pipeline start) funcionan de la misma manera. Nota: un resultado --dry-run también imprime una identificación y queued; no inició nada.

Cada resultado de inicio lleva result.notify={enabled, reason, endpoint_host}. reason no nulo significa pausado o roto; no tiene información de init, así que confirma con notify status.

2. Siempre recuerda al usuario cómo verlo

Después de cada run start, pipeline start o start exitoso, lee result.dashboard. Toma attach_hint, watch_hint y window textualmente; nunca construyas el comando tú mismo.

Si watch_hint comienza con gbdev y el home no es el predeterminado, reemplaza el primer gbdev con el nombre del lanzador del bot (por ejemplo, gbdev-example-dev) al transmitirlo al usuario. Transmite attach_hint textualmente (sesión de home predeterminado gbdev; no predeterminado gbdev-<h6>).

Si enabled=true, reason=null y attach_hint no está vacío, di (en el idioma del usuario):

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

De lo contrario, di:

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

Significados de razón: disabled_by_config config desactivado; disabled_by_env GBDEV_DASHBOARD=0; tmux_not_found no hay tmux; tmux_too_old tmux < 3.2; tmux_error / tmux_timeout tmux falló esta vez; unsafe_argv caracteres no compatibles en rutas; foreign_session una sesión con el mismo nombre no creada por gbdev, que gbdev nunca toca; lock_busy otro proceso está actualizando el panel.

Nunca reintentes ni cambies el flujo de tareas porque el panel no esté disponible.

3. Seguir el progreso

Para el inventario de solo lectura, usa <command> run list --active, <command> pipeline list --active o <command> list --active en el propio home de este bot. Todos admiten --state <s> (repetir o separar por comas), --limit <1..500> (predeterminado 20) y --json; la lista de pipelines también admite --standalone. La lista de trabajos oculta los intentos anteriores obsoletos de forma predeterminada; --all los incluye sin cambiar los hechos del trabajo. gbdev status --all es solo para la lista de texto sin una ID; status no puede combinar --all con --json o una ID. Para el inventario JSON, usa gbdev list --all --json; las matrices JSON de status y el comportamiento de ID única sin --all no cambian. Un trabajo needs_input/blocked/failed/timeout/cancelled es reemplazado por un intento posterior en la misma instancia de paso de pipeline, o por un pipeline propietario/ejecución propietaria terminal (una ejecución terminal es suficiente incluso si su pipeline aún no es terminal); las entradas de intento corruptas omiten solo la verificación del intento posterior, no la evidencia del padre terminal. status concilia y puede escribir estado, así que úsalo para una unidad específica al verificar novedad/recuperación, no para inventario de solo lectura. El indicador obsoleto de una lista solo sugiere usar status; nunca repara nada.

Ruta de webhook (Paso 0 verificado para este bot, notify.reason=null): no crees una rutina de polling de 10 minutos. Informa al usuario: 完成或需要你决定时我会自动收到通知。 La rutina de webhook hace el seguimiento.

Reserva horaria entre semana (opcional, política configurada por el operador; mismas reglas de ciclo de vida que la receta §11.3): una vez por hora dentro de los días laborables, la zona horaria y el horario laboral configurados por el operador (política de ejemplo opcional). Ejecuta comandos de Mac solo mientras la memoria aún tenga unidades activas de ejecución/pipeline/trabajo; sin unidades activas, termina en silencio. Orden: <command> notify status --json → <command> notify flush --wait-ms 20000 --json → el estado de cada unidad activa. Cuando el created_at de la atención actual tiene más de 1

…

[truncado para traducción]