dbt-agent

name	dbt-agent
description	Use for Development Board Toolchain work in Codex, including TaishanPi and RP2350-family boards. Prefer these local DBT tools for board status, capability constraints, environment checks, flashing, runtime control, and board-scoped code execution.

DBT-Agent

Overview

This skill is the umbrella entrypoint for local development-board work through the dbt-agent Codex plugin.

Supported families:

• TaishanPi
• ColorEasyPICO2
• RaspberryPiPico2W

Rules

• When the user explicitly invokes @dbt-agent, [@dbt-agent](plugin://dbt-agent@plugins), or the Embed Labs plugin, treat the message as a DBT tool intent and prefer MCP tools over shell commands.
• For plugin/runtime version requests such as 本地插件版本号, 服务器最新版本号, 当前插件版本, latest plugin version, or plugin version, call dbt_get_plugin_versions directly. Do not inspect the workspace, read plugin files, probe dbtctl, or run shell commands for version lookup.
• For plugin/runtime update requests such as 更新插件, 升级插件, 更新 Embed Labs, 检查插件更新, or update plugin, do not inspect the workspace, read plugin files, probe dbtctl, or run shell commands. If the user asks to update, call dbt_update_plugin directly; if the user only asks whether an update exists, call dbt_check_plugin_update.
• For macOS GUI requests such as 安装 GUI, 安装 mac 端 GUI, 安装图形界面, 卸载 GUI, or uninstall GUI, call dbt_install_gui or dbt_uninstall_gui directly. These tools only manage the optional DBT-Agent.app; they must not remove the shared runtime, dbt-agentd, board environments, Codex plugin, or OpenCode plugin.
• If the user writes a DBT MCP tool name such as dbt_current_board_status, including with a leading $, backticks, or command-like wording, call the matching MCP tool directly. Never run DBT MCP tool names through zsh, and never report command not found as a board result when the MCP server is available.
• For direct live-board requests such as 开发板状态, 当前开发板状态, 查看当前开发板状态, board status, what board is connected, or which device is active, call the MCP tool dbt_current_board_status immediately as the first action.
• Do not run dbtctl status, shell commands, web search, workspace probes, memory-file searches, or repository/skill-file reads before dbt_current_board_status when that MCP tool is available.
• For simple status-only prompts, do not narrate the plan. Use summary_for_user as the compact status anchor, then answer naturally from the returned fields according to what the user asked; do not dump every field unless details are requested.
• Do not run shell workspace probes such as pwd, ls, find, or rg, and do not read repository files before dbt_current_board_status unless the user is explicitly asking about plugin source, installation, or repository maintenance.
• For broad capability or feature prompts such as 开发板有什么能力, 当前开发板有什么能力, 这个开发板支持什么功能, 这块板能做什么, or what can this board do, do not use Search, Read, rg, find, ls, memory files, repository docs, GUI docs, DBT-Agent-Project.md, or local handoff files. If the current board or variant is unknown, first call dbt_current_board_status; then call dbt_list_capability_summaries for that board and variant and answer from the returned capability summaries.
• For user-facing questions about the current board's features, characteristics, supported functions, or coding constraints, answer from DBT tool results such as dbt_current_board_status, dbt_list_capability_summaries, dbt_get_board_config, and dbt_get_capability_context. Do not cite source-checkout docs, local development handoff files, GUI docs, or private paths outside ~/Library/development-board-toolchain.
• For user-facing pin, 40PIN header, pinmux, GPIO, PWM, UART, I2C, or SPI questions, use DBT capability summaries/context first. If DBT tools are temporarily unavailable and the answer is knowledge-only, read only installed published knowledge under ~/Library/development-board-toolchain/agent/{vault,registry}/published; never read or cite DBT-Agent-Project, source checkout docs, GUI docs, or absolute maintainer paths.
• When citing board knowledge, prefer capability names and relative installed knowledge references such as vault/published/boards/<board>/<variant>/pin_header_40pin/usage.md. Do not include absolute /Users/.../DBT-Agent-Project/... paths in the final answer.
• Treat pin_header_40pin as a reference-only capability. It can answer physical pin mapping and default mux, but it does not prove that a Linux runtime node is currently enabled. For PWM, do not claim executable PWM output support from the 40PIN table alone; require a published PWM capability or a live runtime probe of /sys/class/pwm and the device-tree/pinmux state.
• If a DBT tool result includes host paths that are not necessary to answer the user, omit them. If a path is necessary, mention only installed runtime paths under ~/Library/development-board-toolchain, not source workspace paths.
• TaishanPi and similar re-flashed Linux boards regenerate SSH host keys. DBT tools already handle this. If a shell ssh/scp fallback is absolutely necessary for diagnostics, use an ephemeral host-key policy such as -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no and a short connect timeout. Do not report REMOTE HOST IDENTIFICATION HAS CHANGED as a board fault, and do not ask the user to edit ~/.ssh/known_hosts unless they explicitly want a persistent manual SSH workflow.
• Do not read sibling board-family skills before the first live status call. Route to them only after dbt_current_board_status if the follow-up task needs board-specific flows.
• Persist the last confirmed board_id, variant_id, device_id, fetched capability summaries, fetched capability context, and fetched board config within the current conversation. Reuse them for follow-up turns unless the user says the hardware changed or asks to verify live state again.
• If a previous turn already showed that a capability exists for the current board, do not call dbt_get_capability_context again just to confirm support. Call it only when you need implementation-contract details that are not already present in the conversation.
• If dbt_get_board_config or dbt_get_capability_context already ran for the same board, variant, and capability in the current conversation, reuse that result instead of re-fetching it.
• Only use dbt_list_connected_devices when the caller explicitly needs a raw picker-style device list.
• If the board is already known and the user asks a broad capability question, call dbt_list_capability_summaries directly. If the user asks about a specific capability or code-generation constraint, use dbt_get_capability_context and dbt_get_board_config. Do not re-query live board state first unless the user asks for fresh live status.
• For RP2350 code-generation tasks, fetch dbt_get_capability_context and dbt_get_board_config first, then use dbt_rp2350_build_flash_source.
• Treat TaishanPi rgb_led as a capability contract, not as a built-in application feature. For simple atomic LED state changes such as a single solid color or off, dbt_apply_effect may be used as a compatibility/direct-control path. For any request with user logic, timing, blinking, breathing, repeat counts, multi-step sequences, or traffic-light behavior, fetch capability context and board config, generate self-contained C/C++ source in the current workspace, and call dbt_build_run_program with capability=rgb_led.
• For TaishanPi code-generation and deployment tasks, fetch capability context and board config first, then use dbt_build_run_program; always pass workspace as the current user/project directory so the plugin/runtime materializes source and local artifacts directly there, not in a fixed temp path or private source checkout.
• For TaishanPi build or environment work, call dbt_get_board_config with probe_env=true and inspect environment.available_build_modes. For generated program build/run, prefer omitting build_mode or using auto; the runtime must probe the running board rootfs/sysroot ABI and match docker or local-llvm to that userland ABI before compiling. Do not infer the application compiler from the kernel compiler string alone.
• Only pass build_mode=docker or build_mode=local-llvm when the user explicitly chose a mode, when installing/checking a specific environment, or when flashing/downloading a specific image family. If the runtime reports that the requested mode conflicts with the running board rootfs/sysroot ABI, stop and tell the user to switch to the matching mode; flash a matching image only when they intend to change the board's running rootfs/userdata ABI.
• For TaishanPi Qt or QtQuick app requests, do not use dbt_build_run_program, do not search for qmlscene, and do not manually guess qmake/CMake/linker paths. Treat QtQuick work as an engineered app project, not a temporary snippet: create or update a complete Qt project in the current user workspace, keep source/assets/config there, and use embedlabs-app.json when the user is building toward reuse or release. Call dbt_get_board_config with probe_env=true; when the user asks to run on hardware, call dbt_qt_build_run_app with project_dir and workspace.
• Qt runtime images are intentionally clean and may not include qmlscene. A visible QtQuick application should be a compiled executable (usually CMake + qt_add_qml_module) deployed under /userdata/qt-project/<ProjectName> by dbt_qt_build_run_app.
• Live preview and board app entrypoints are different. Main.qml for Embed Labs preview should keep an Item/Rectangle root so the native preview host can load it with QQuickView; the compiled board executable must therefore provide a C++ QQuickView launcher with SizeRootObjectToView and showFullScreen(). Do not use QQmlApplicationEngine alone to load an Item/Rectangle root, because it creates no visible window on the board.
• TaishanPi LLVM Qt images use the /userdata/qt6-rk3566-llvm/qt6-env.sh display stack; default board app QPA is eglfs. Do not force linuxfb just to rotate a screen unless the display stack was explicitly diagnosed for that panel. For rotation, prefer app-level QML/C++ layout handling or an explicit, tested qpa_platform.
• A Qt board deployment is not accepted until all four checks are true: dbt_qt_build_run_app returns a remote app dir, a runner path, a process that is still present after a short delay, and a board log without QML/QPA errors. A local preview session or an initial launch line is not proof that the board display is showing the app.
• If a board Qt app builds but the screen is blank, diagnose in this order: call dbt_list_board_processes for the app name, inspect the returned remote_log_path, confirm the runner QPA is eglfs unless intentionally overridden, and check whether the C++ launcher uses QQuickView for an Item/Rectangle QML root.
• QtQuick has two target modes. Use host-qt-app when the user wants a local macOS Qt application or local UI design/preview; use board-qt-app when the user wants the app cross-compiled and run on a board. Both modes use the local live-preview loop for UI iteration, but only board-qt-app proceeds to dbt_qt_build_run_app.
• Before generating a QtQuick UI, make sure the target screen resolution and orientation are known. If the user has not provided them and they are not already present in project context, ask one concise question for width x height and portrait/landscape before coding. Use those values in embedlabs-app.json, root layout assumptions, and preview tool arguments.
• For local QtQuick UI development or preview requests, use the independent live-preview loop before board deployment: create/edit QML files under the current user workspace, call dbt_qml_preview_validate, ensure board runtime with dbt_qml_board_runtime_start when a connected board should mirror the preview, then call dbt_qml_preview_start. When the user marks a control, container, or region in the preview window, call dbt_qml_preview_feedback, use semantic_item/item/container_item/selection as the edit target, make focused local QML changes, and validate again. Do not treat preview success as release completion.
• Start QtQuick preview with screen_width, screen_height, and orientation whenever available so the local preview keeps the target display ratio. The preview host persists user rotation, window position, and per-rotation window sizes for each project; do not reset the window to default dimensions after toolbar rotation. For board-side live runtime work, call dbt_qml_board_runtime_start, then start dbt_qml_preview_start with backend=board-runtime and the returned board_runtime_host/board_runtime_port; otherwise clearly say the preview is local-only.
• dbt_qt_build_run_app creates a standalone compiled board application. It does not link the computer preview window to the board and it does not make preview toolbar rotation or annotations affect the already deployed process. Use it only after the user confirms the live-preview result should be packaged/run as the final app. For real host<->board live linkage, the session backend must be exactly board-runtime.
• backend=board-runtime must never silently fall back to native-qquickview. If the board runtime is not reachable, if host/port is missing, or if an existing session is running with a different backend, report that the board is not linked and stop or restart the matching preview session before continuing.
• After implementing or materially modifying a QtQuick UI, call dbt_qml_preview_status. If no local preview is running, call dbt_qml_preview_start; then call dbt_qml_preview_capture and inspect the returned image_path when the client supports image viewing. Compare the screenshot against the user's requested function, target resolution, and layout goals; make one focused improvement pass if the screenshot reveals an issue.
• QML generated for live preview must keep important controls traceable with stable objectName, and important layout areas should set designRole. Board-runtime linkage is Runtime Message Center based: workspace sync and hot reload load the same QML, ui.manifest exposes controls, UiControlBinder turns stable standard input-control notify signals into ui.event, and reducers emit lightweight changed-path app.state.patch messages with state_revision. Realtime linkage is verified from revision/status/capture evidence; state_hash/app_state_hash is a low-frequency hello/status/full-state diagnostic, not a per-control frame validation requirement. Runtime-managed pointer/focus/key mirroring is diagnostic/compatibility support for non-bound controls and text focus/key handling; Slider/Dial/SpinBox must stay state-authoritative. ComboBox must synchronize currentIndex plus popupVisible/popupStatePath; do not rely on raw pointer forwarding to open the board popup, because the same click can hit a board-side option and immediately close it. Button, hardware action, and business-command controls must still call appRuntime.dispatch(action, payload) instead of relying on raw pointer side effects. If local state changes but the board does not, debug ui.event -> changed-path app.state.patch -> state_revision/status/capture before changing QML.
• QML generated for board-runtime linkage does not need per-demo synchronization code for standard input controls. Runtime-level linkage covers file sync, hot reload, ui.manifest, stable-control UiControlBinder, ui.event, changed-path app.state.patch, low-frequency full-state diagnostics, capture, default board display rotation, Overlay/Popup rotation, and coordinate mapping through board input_width/input_height. Runtime owns loop prevention and throughput: source=preview-host echoes are ignored, recently host-written continuous-control paths, ui.rotation, and jobs.active.progress paths have short host authority, stale queued continuous-control values are coalesced to the latest value on both host and board, ComboBox *_open/popupVisible paths remain bidirectional, and board-side runtime suppresses ui.* dispatch while applying external patches. Do not send full UI state or require hash validation for every realtime patch. Use explicit appRuntime.state / appRuntime.dispatch for Button actions, Popup/Dialog business state, View scroll commit, ProgressBar/task status, hardware actions, long jobs, errors, custom controls, and business state that must be replayable or durable; use boardRuntimeDisplay.rotation only for optional fine-grained layout adaptation.
• For TextField/TextArea in linked QtQuick work, declare statePath for text, cursorStatePath for cursor position, and focusStatePath for focus. The runtime syncs text, cursorPosition, and activeFocus as one ui.controls batch so middle insert/delete does not move the cursor incorrectly; do not add a second hand-written text sync path unless the control explicitly opts out with dbtAutoBind: false. For Slider/Dial/SpinBox, verify several app.state.patch values during a drag in both directions; a single release-time value, raw-pointer-only dragging, or alternating host/board values is not realtime linkage. For ComboBox, set a stable objectName, optionally declare popupStatePath, and verify both host->board and board->host dropdown opening from the board manifest or screenshot after rotation.
• For QtQuick release or delivery requests, create or update a release manifest under the user's workspace, record the target mode (host-qt-app or board-qt-app), main QML, Qt version, validation results, build artifacts, and runtime/deploy paths. Do not publish or present a one-off preview session as the final deliverable.
• For board-app autostart requests, call dbt_configure_autostart after the app has been deployed. Use app_type=qt with remote_runner_path returned by dbt_qt_build_run_app, and use app_type=native with remote_binary_path/remote_artifact_path returned by dbt_build_run_program. Do not inspect init systems, do not create per-app systemd units, and do not write custom /etc/init.d app scripts; the runtime owns the fixed /userdata/.dbt-autostart broker and single boot hook.
• If the user asks for display rotation in a Qt/QtQuick UI, implement it in the generated QML/C++ project or pass an explicit qpa_platform such as linuxfb:fb=/dev/fb0:rotation=90 when appropriate; do not edit the system image just to rotate one app.
• For generic TaishanPi Linux C/C++ diagnostics, finite CPU stress tests, benchmarks, or board-side probes that are not owned by a narrower capability, use capability linux_program with dbt_build_run_program.
• Do not use capability chip_control with dbt_build_run_program; use dbt_probe_chip_control for live CPU, DDR, temperature, memory, and storage readings. If a workload is needed, run a finite linux_program first, then probe.
• For live CPU, DDR, temperature, WiFi, or Bluetooth checks on Linux boards, prefer dbt_probe_chip_control or dbt_probe_wifi_bluetooth over shell guesses.
• For Linux-board process-list requests such as 当前开发板有哪些进程, call dbt_list_board_processes directly instead of using host shell, SSH narration, or capability lookups.
• For TaishanPi or other Linux-board requests to enter Loader/download mode, call dbt_reboot_loader directly. Do not call capability summary/context tools to discover this path.
• For normal board reboot requests, including returning a Linux board from Loader USB to the normal runtime state, call dbt_reboot_device directly.
• In DBT/TaishanPi context, user phrases such as 下载初始化镜像, 恢复初始镜像, 烧录初始化镜像, 刷写初始化镜像, 恢复出厂镜像, or factory image mean factory full-image burning to the board unless the user explicitly says "只下载到本机" or "只检查本地缓存".
• For real TaishanPi initialization/factory full-image burning, first call dbt_current_board_status, then call dbt_start_flash_image with image_source=factory and scope=all, then call dbt_get_job_status with the returned job_id to show progress. Let dbt-agentd/the installed runtime handle running-vs-Loader/Maskrom transitions.
• If the user provides one complete .img file and asks to burn/flash it directly, do not unpack it and do not run shell flashing commands. Call dbt_start_flash_image with scope=raw and host_image_file=<path-to-img>, then poll dbt_get_job_status. The runtime detects Rockchip RKFW/RKAF update packages, rewrites their GPT/parameter layout, and flashes their contained partition image set internally; only true raw disk images are written from LBA 0.
• Use dbt_flash_image only for dry_run=true, short blocking validation, or when the user explicitly asks to wait for final completion in one blocking tool call.
• Do not call dbt_install_board_environment, dbt_list_installed_board_plugins, file listing, or repository search for initialization-image burning. dbt_install_board_environment is only for installing/repairing local compiler/runtime environments.
• For startup-logo, boot-logo, splash-logo, or logo replacement requests, call dbt_update_logo directly with the user-provided host image path plus requested rotate, scale, build_mode, and flash options. Do not inspect boot workspace files, do not manually run sips, magick, convert, rebuild_boot.sh, or dbt_flash_image; the runtime update-logo method owns image conversion, sizing, boot/resource rebuild, and optional boot flashing.
• Do not invent Pico SDK include paths, link libraries, or support headers. Use DBT capability context exactly.

Routing

• RP2350 hardware control: ../rp2350/SKILL.md
• TaishanPi Linux-board flows: ../taishanpi/SKILL.md