Skip to content

RemoteDebug

DevStar Bot edited this page Nov 13, 2026 · 2 revisions

云端协同调试(DevContainer + Remote Debug)

云端协同调试(DevContainer + Remote Debug)将远程 DevContainer 与开发者电脑Host连接起来,使项目可以在DevContainer容器中完成构建,然后使用开发者电脑Host上的 QEMU、OpenOCD、J-Link GDB Server、烧录工具或其他本地程序完成调试。

开始前先认识四个名称:

  • DevContainer:项目源代码、编译构建环境、GDB调试器客户端和 Agent等。
  • Host:与 DevContainer 建立连接的开发者电脑,或电脑上的 Linux/WSL 环境。
  • Debug Service:在 Host 上运行并开放 GDB 调试端口的 QEMU、OpenOCD、J-Link GDB Server 等程序。
  • Relay:连接 DevContainer 与 Host,负责转发调试流量、同步构建产物和执行 Host 命令。

推荐按以下顺序阅读:

使用场景 阅读章节
使用 Agent 完成连接和调试 第 1 节
使用 VSCode 手工完成连接和调试 第 2 节
使用 WebTerminal 手工完成连接和调试 第 3 节
云端协同调试的基本工作原理 第 4 节
查询 Host、执行 Host 命令 第 5 节
排查连接或调试问题 第 6~7 节
从空白项目配置云端协同调试 第 8 节

1. 从模板开始:Agent 最简使用

第一次使用建议完成一条最短路径:

从模板创建项目 → 配置Agent、创建 DevContainer → 连接 Host → 启动 Agent → 让 Agent 完成构建、同步、调试和清理。

1.1 创建模板项目

在 DevStar 中选择 从模板创建仓库,使用 embedded 嵌入式模板创建项目。模板已经包含:

  • DevContainer 和 ARM Cortex-M 构建工具链。
  • 示例固件、Makefile、链接脚本和启动代码。
  • .devstar/remote-debug.json Remote Debug 配置。
  • .vscode/launch.json 和构建任务。
  • 供 Agent 使用的 embedded-debug Skills。

后续修改应在新建项目中进行,不要直接修改模板仓库。

1.2 配置Agent、创建 DevContainer 并连接 Host

在创建 DevContainer之前可以配置 DevContainer 启动脚本安装一个 AI CLI 作为容器内 Agent:

  1. 进入项目的 设置 → 开发容器 → 脚本管理。
  2. 在启动脚本中添加 DEVSTAR_INSTALL_CODEX_CLI;也可以按实际需要使用 DEVSTAR_INSTALL_CLAUDE_CODE、DEVSTAR_INSTALL_OPENCODE 等脚本。
  3. 在项目 AI 设置或变量管理中准备对应的 API Key、Base URL 和 Model。
  4. 创建 DevContainer;已经创建过容器时,需要重新创建,新增启动脚本才会执行。

在项目页面创建 DevContainer,等待初始化完成,再建立远程调试连接,如下两种方法(二选一):

  • 使用支持 Remote Debug 的IDE打开项目(比如使用VSCode打开项目),其中DevStar插件会自动在DevContainer 和 Host 之间建立连接。
  • 在 DevContainer 的 WebTerminal 中执行 devstar remote-debug 命令会输出两种 Host 启动命令,手工在Host执行启动命令即可建立连接。

成功建立连接后,在 DevContainer 的 WebTerminal 右侧远程调试面板显示绿色表示Remote Debug链路健康可用,但不表示 QEMU、OpenOCD 等 Debug Service 已经启动。

在 WebTerminal 或 VSCode Terminal中确认 AI CLI 已安装:

codex --version

1.4 使用 Agent 完成连接和调试

让Agent读取 embedded-debug Skills,模板项目中默认使用的是.claude/skills/embedded-debug,假如我们使用codex,则需要如下配置:

mkdir -p .agents/skills
ln -s .claude/skills/embedded-debug .agents/skills/embedded-debug

在 DevContainer 的仓库目录启动 Agent 后,直接给它以下任务:

阅读仓库中的构建说明和 .devstar/remote-debug.json,完成一次嵌入式项目联调。
请确认 Host 环境,构建并同步固件,启动项目需要的调试服务,使用 GDB 验证程序能够运行到 main。
不要猜测固件路径、目标板参数或 Host 项目目录;任务结束后清理本次启动的进程。

Agent 应完成:

  1. 读取项目配置和构建说明。
  2. 使用 devstar host inspect 确认 Host 在线。
  3. 在 DevContainer 中构建固件。
  4. 使用 devstar sync 获得固件在 Host 上的实际路径。
  5. 在 Host 启动 QEMU、OpenOCD 或其他 Debug Service。
  6. 在 DevContainer 中通过 $DEVSTAR_RELAY_DEBUG_ENDPOINT 连接 GDB。
  7. 验证断点或运行结果,并清理本次启动的 Host 进程。

成功标准是:构建退出码为 0、devstar sync 成功并返回实际 Host 路径、GDB 能连接并到达预期位置、调试结束后端口已经释放。Agent 使用 devstar sync --json 时还应确认 ok:true。

如果项目修改了固件路径、QEMU machine 或调试参数,应先更新项目说明或 Skill,不要要求 Agent 猜测。

警告⚠:Host Command 使用 Host Relay 进程所属用户的权限,没有命令级权限限制、逐次确认或命令审计,用户只应把 Host 连接交给可信项目和可信 Agent。

2. 使用 VSCode 手工完成连接和调试

本节继续使用第 1 节创建的模板项目。模板已经提供 VS Code 调试配置,通常只需准备固件和 Debug Service。

2.1 打开项目并确认连接

使用 DevStar 插件打开项目,等待 VS Code 连接 DevContainer,然后在容器终端执行:

devstar host inspect

只有看到 Host connection: connected 后,才继续调试。连接失败时可按第 3 节改用手工连接。

2.2 准备固件和 Debug Service

按顺序完成:

  1. 在 DevContainer 中执行 make all 构建固件。
  2. 执行 devstar sync,取得返回的 Host 固件路径。
  3. 在 Host 使用该路径启动 QEMU、OpenOCD、J-Link GDB Server 或其他 Debug Service。

这三步可以手工完成,也可以交给 Agent。需要继续使用 VS Code 调试时,可以告诉 Agent:

构建并同步固件,在当前 Host 启动项目需要的 Debug Service。
确认调试端口开始监听后保持服务运行,不要启动 GDB;我将使用 VS Code 连接。
告诉我同步后的 Host 路径和调试结束后的清理方式。

调试期间不要取消 Agent 管理的 Host 命令,否则 Debug Service 会随该调用结束。调试完成后再让 Agent 清理本次启动的进程。

2.3 使用模板调试配置

模板中的核心 .vscode/launch.json 配置如下:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "cppdbg",
      "request": "launch",
      "name": "Remote GDB",
      "program": "${workspaceFolder}/build/firmware.elf",
      "cwd": "${workspaceFolder}",
      "MIMode": "gdb",
      "miDebuggerPath": "gdb-multiarch",
      "miDebuggerServerAddress": "${env:DEVSTAR_RELAY_DEBUG_ENDPOINT}",
      "stopAtConnect": true,
      "preLaunchTask": "build"
    }
  ]
}

将模板用于其他项目时,按实际情况修改 program、miDebuggerPath 和构建任务。

在 VS Code 的 运行和调试 面板选择 Remote GDB,设置断点后按 F5。preLaunchTask 只负责容器内构建,不会自动执行 devstar sync,也不会自动启动 Host 上的 Debug Service。

连接成功后,应能加载当前 ELF 的符号,并查看断点、调用栈、寄存器和变量。

3. 使用 WebTerminal 手工完成连接和调试

本节适用于无法使用 VSCode 等 IDE 及 DevStar 插件,或希望手工逐步完成连接、同步和调试的用户。示例中的固件名、QEMU machine 和端口必须按项目实际配置修改。

3.1 建立远程调试连接

本节继续使用第 1 节创建的模板项目。在 DevContainer 的 WebTerminal 中执行:

devstar remote-debug

命令会输出两种 Host 启动方式:

  • Linux、macOS 或 WSL:执行输出的 curl ... | bash。
  • Windows PowerShell:执行输出的 irm ... | iex。

启动命令包含一次性授权码,生成后 120 秒内有效,并且只能成功使用一次。过期后重新运行 devstar remote-debug。

同一个 DevContainer 同时只保留一个活动 远程调试连接 Session。如果出现 Session 冲突:

  • 原连接仍然可用时,继续使用原连接。
  • 确实需要切换 Host 时,确认替换;旧 Session 会被关闭。

连接完成后执行:

devstar host inspect

host inspect 成功才能证明当前远程调试连接实时可用。

3.2 构建并同步固件

在 DevContainer 的仓库根目录运行项目构建命令,例如:

make all

确认 ELF 存在且构建退出码为 0,然后执行:

devstar sync

不带参数时,命令同步 .devstar/remote-debug.json 中配置的 artifactPath。也可以显式传入文件:

devstar sync build/another-firmware.elf

成功时输出便于直接阅读的同步结果:

Artifact synchronized
Artifact: firmware.elf
Host path: <path-on-host>
Size: 123456 bytes
SHA-256: <sha256-of-current-file>

脚本或 Agent 需要解析字段时使用:

devstar sync --json build/another-firmware.elf

此时返回 JSON:

{
  "artifact": "firmware.elf",
  "host_path": "<path-on-host>",
  "ok": true,
  "path": "<path-on-host>",
  "sha256": "<sha256-of-current-file>",
  "size": 123456
}

使用时注意:

  • 普通调用先确认退出码为 0;--json 调用还应确认 ok 为 true。
  • 文本中的 Host path,或 JSON 中的 path/host_path,是本次同步后的 Host 实际路径。
  • 容器路径和 Host 路径没有自动映射,不要自行拼接 Host 路径。
  • SHA-256 和大小用于核对本次传输结果,不应写成固定预期值。
  • 默认单文件上限为 512 MiB,部署管理员可以修改该限制。

3.3 在 Host 启动 Debug Service

在 Host 使用 devstar sync 返回的路径启动项目需要的 Debug Service。服务端口必须与 .devstar/remote-debug.json 一致。

下面是 ARM Cortex-M3 的 QEMU 示例。请替换固件路径和 machine:

qemu-system-arm -M lm3s6965evb -m 64K -nographic -semihosting-config enable=on,target=native -kernel "<path-on-host>" -S -gdb tcp:127.0.0.1:21234
  • -S 表示启动后暂停,等待 GDB。
  • -gdb tcp:127.0.0.1:21234 表示只在 Host 本机监听 GDB 端口。

OpenOCD、J-Link GDB Server 和其他 GDB server 使用相同原则:监听配置端口,并优先只监听回环地址,避免把调试端口暴露到外部网络。

3.4 从 DevContainer 连接 GDB

DevContainer 中的调试入口保存在:

echo "$DEVSTAR_RELAY_DEBUG_ENDPOINT"

加载容器内的 ELF 并连接:

gdb-multiarch build/firmware.elf \
  -ex "target remote $DEVSTAR_RELAY_DEBUG_ENDPOINT"

根据目标架构,也可以使用 arm-none-eabi-gdb 或项目工具链提供的其他 GDB。

常用验证命令:

break main
continue
bt
info registers

成功标准是 GDB 能连接远端,并在 main 或项目指定位置停止。

3.5 结束调试

退出 GDB 后,停止本次启动的 QEMU、OpenOCD 或其他 Debug Service,并确认调试端口已经释放。只清理本次任务对应的进程,不要按程序名批量结束其他任务。

4. 云端协同调试的基本工作原理

flowchart LR
    subgraph container[DevContainer]
        source[源码与构建工具]
        gdb[GDB / VS Code]
        agent[Agent]
        cli[devstar CLI]
    end

    subgraph platform[DevStar]
        hub[Relay Hub]
    end

    subgraph host[Host]
        hostRelay[Host Relay]
        debugService[QEMU / OpenOCD / J-Link]
        hostTools[Host 工具与文件]
    end

    source --> cli
    agent --> cli
    cli <-->|产物同步与 Host 命令| hub
    gdb <-->|GDB 调试流量| hub
    hub <-->|当前 Relay Session| hostRelay
    hostRelay --> debugService
    hostRelay --> hostTools
Loading
能力 用户入口 作用
建立连接 DevStar 插件或 devstar remote-debug 连接当前 DevContainer 与一个 Host
Debug 转发 $DEVSTAR_RELAY_DEBUG_ENDPOINT 让容器内 GDB 访问 Host 上的 Debug Service
产物同步 devstar sync [--json] [file] 把容器文件传到 Host,并返回实际 Host 路径
Host 检查 devstar host inspect 实时查看 Host 系统、默认命令目录和部分工具
Host 命令 devstar host exec ... 在 Host 上执行非交互命令
本地状态 devstar relay status 检查容器内 Relay 运行时

Relay 通道就绪不代表 Debug Service 已经启动。GDB 能否连接还取决于 Host 上是否有程序监听配置端口。

Remote Debug 与 DevContainer Web 端口转发方向不同:Web 端口转发让浏览器访问容器服务;Remote Debug 让容器访问 Host 上的调试服务。

5. 查询和操作 Host

5.1 查看 Host 信息

devstar host inspect

默认输出便于直接阅读,例如:

Host connection: connected
Host: dev-workstation
Operating system: windows Microsoft Windows [Version 10.0.22621] (amd64)
Shell: powershell
Default command directory: C:\Users\developer
Workspace mapping: unavailable
Detected tools:
  git: 2.39.2.windows.1
  qemu-system-arm: 9.1.0

含义:

  • Default command directory 是 Host Relay 的启动目录,不保证是 Host 项目目录。
  • Workspace mapping: unavailable 表示不能根据容器工作区推测 Host 路径。
  • 工具列表描述的是 Host,不代表 DevContainer 中也安装了相同工具。

脚本需要结构化数据时使用:

devstar host inspect --json

JSON 中可能包含 Host 工具路径和环境信息,不要无必要地复制到公开日志。

工具列表会在 Host Relay 进程中缓存。Host 安装或卸载工具后可强制刷新:

devstar host inspect --refresh-tools
devstar host inspect --refresh-tools --json

host inspect 每次都会验证 Host 实时连接,不会使用旧缓存冒充在线状态。工具版本检测失败只会省略版本,不会把 Host 判定为离线。

5.2 执行 Host 命令

devstar host exec [-w|--workdir PATH] [--timeout SECONDS] [--json] COMMAND [ARG...]

Linux、macOS 或 WSL Host 示例:

devstar host exec git --version
devstar host exec -w '/path/on/host/project' git status
devstar host exec --timeout 30 go test ./...

Windows Host 示例:

devstar host exec powershell.exe -NoProfile -Command '(Get-Location).Path'
devstar host exec -w 'C:\path\to\project' git status

命令行为:

  • 不指定 -w 时,使用 host inspect 显示的默认命令目录。
  • -w 只影响本次调用;多次调用之间不会保留 cd 状态。
  • 命令直接启动,不会自动经过 shell。
  • 管道、重定向、变量展开和复合命令必须显式调用 Host shell。
  • 默认不限运行时间;需要上限时使用 --timeout。
  • stdout 和 stderr 分开返回,Host 程序的非零退出码会传回调用方。
  • 多个 host exec 可以并发运行;取消其中一个调用不会取消其他命令。
  • 超时通常返回 124,用户或 Agent 取消调用通常返回 130。
  • 当前不支持 TTY、stdin 或跨调用保留的交互式 shell。
  • 二进制文件应使用 devstar sync,不要通过命令输出传输。

复合命令示例:

# Linux、macOS 或 WSL Host
devstar host exec sh -lc 'pwd && command -v qemu-system-arm'

# Windows Host
devstar host exec powershell.exe -NoProfile -Command 'Get-Location; Get-Command git'

Windows Host 没有 ls、pwd 等 Unix 可执行文件。应显式调用 PowerShell,例如 powershell.exe -Command Get-ChildItem;使用 dir 时则需要调用 cmd.exe /d /c dir。Relay 不会把 Linux 命令自动转换成 Windows 命令。

5.3 JSON 输出

需要程序处理命令生命周期时使用 --json。下面是 Linux、macOS 或 WSL Host 示例:

devstar host exec --json sh -lc 'printf "out\n"; printf "err\n" >&2'

输出是逐行 JSON,主要事件包括:

事件 说明
start Host 进程已经创建,包含 command_id 和 pid
output 一块 stdout 或 stderr,使用 stream 区分
end 命令结束,包含退出码和错误信息
error 命令启动前或连接层发生错误

start 只表示进程已经创建,不表示调试端口已经开始监听。Agent 仍应检查服务日志、端口或 GDB 连接结果。

5.4 Agent 使用原则

Agent 自动联调时应遵循:

  1. 先执行 host inspect,再读取项目配置。
  2. 在容器构建,通过 sync 获得 Host 路径。
  3. 使用受管理的 host exec 调用启动 Debug Service。
  4. 确认服务就绪后再运行 GDB。
  5. 无论调试成功还是失败,都取消自己启动的调用并检查端口已经释放。

不要使用 nohup 让 Debug Service 脱离调用生命周期,也不要使用 pkill qemu 等命令批量结束其他任务。项目级具体参数应写在 embedded-debug Skill 中,而不是让 Agent 临时猜测。

6. 状态与 Session 生命周期

6.1 本地 Relay 状态

在 DevContainer 中执行:

devstar relay status

该命令输出简洁的文本摘要,用于检查容器内 Relay 运行时、本地命令入口、运行时版本和已就绪能力:

Relay runtime: ready
Version: <runtime-version>
Capabilities: debug, artifact-sync, command
Command channel: ready
Host metadata: available

脚本或深入排障需要完整字段时使用:

devstar relay status --json

注意:

  • ready 和 ok 只描述容器本地运行时,不证明 Host 实时可达。
  • 判断 Host 是否可用,应执行 devstar host inspect。
  • 文本显示 Relay runtime: unavailable 时命令仍可能返回 shell 退出码 0;自动化脚本应使用 --json 并读取 ok、ready 字段。
  • Relay 位于平台受管目录,不要求 devstar-relay 出现在 PATH 中。

6.2 一个 DevContainer 只保留一个活动 Session

同一个 DevContainer 同时只保留一个活动 Host Relay Session:

  • 已经通过 Host 启动命令建立健康连接时,打开 VS Code 不会再创建第二个活动 Session。
  • 新连接需要接管时,平台会提示 Session 冲突;确认替换后,旧 Session 会关闭。
  • Session 被替换后,旧 Session 立即失效;对应的 Host Relay 或插件后台进程会在检测到关闭后退出。

关闭 VS Code 项目窗口不一定会停止 Relay。VS Code 插件可以通过独立后台进程继续维护连接,因此不能根据窗口是否存在判断 Relay 是否已经断开,应以 devstar host inspect 为准。

手工启动命令应保持运行。关闭终端或中断 PowerShell/Bash 管道后,仍需使用 devstar host inspect 确认连接已经结束,因为 Host Relay 子进程可能仍在运行。需要切换连接且仍提示冲突时,通过 devstar remote-debug 明确确认替换。

当前 devstar CLI 没有统一的 relay disconnect 子命令。停止 DevContainer 会关闭对应 Session;单独重启或停止容器内 Relay 运行时,不等于主动结束整个 Host Session,Host Relay 可能继续等待重连。

6.3 自动重连

Host Relay 和 Container Relay 会在临时网络或传输故障后尝试重连:

[devstar] relay connection lost; reconnecting...
[devstar] relay reconnected

重连只恢复通道,不会恢复已经中断的任务:

  • GDB 需要重新连接。
  • 中断的 devstar sync 需要重新上传。
  • 在途 Host Command 会失败,不会自动重放。

命令中断后,应先检查 Host 当前状态,再决定是否重试有副作用的操作。

7. 常见问题

7.1 devstar 子命令不存在

现象:devstar remote-debug、devstar sync、devstar host inspect 或 devstar host exec 不可用。

检查:

devstar --help
test -f .devstar/remote-debug.json

**原因:**项目没有有效 Relay 配置,或当前 DevContainer 创建时尚未包含该配置。

**处理:**将配置提交到仓库默认分支后重建 DevContainer。

7.2 修改配置后仍使用旧端口或旧路径

**现象:**环境变量、Session 或 sync 行为与当前配置不一致。

**原因:**运行中的 DevContainer 仍使用创建时的旧配置。

**处理:**重建 DevContainer,再建立新的 Relay Session。

7.3 relay status 报告二进制不可用

现象:devstar relay status 显示 Relay runtime: unavailable,原因为 devstar-relay binary is not available;使用 --json 时对应 ok:false、ready:false。

检查:

devstar relay status
devstar host inspect

原因:devstar-relay 不在 PATH 本身不是故障。当前版本会从配置读取受管路径;如果仍报告不可用,通常是容器 helper 或 Relay 配置过旧,或者受管文件确实丢失。

**处理:**重新建立 Relay Session。仍未恢复时重建 DevContainer,然后再次执行以上两个检查命令。

7.4 host inspect 失败或出现 Session 冲突

**现象:**Host 不可达、连接仍在重试,或 devstar remote-debug 报 relay_session_conflict。

**原因:**Host Relay 未运行、Session 已失效,或旧 Host Relay/后台 Controller 仍占用当前 Session。

处理:

  1. 执行 devstar relay status 检查容器本地运行时。
  2. 确认 Host Relay 或插件后台连接是否仍在运行。
  3. 临时断线时等待自动重连。
  4. 确实需要更换连接时,重新执行 devstar remote-debug 并确认替换。

不要因为关闭了 VS Code 项目窗口就假设旧 Relay 已经结束。

7.5 Host 工作目录不存在

现象:devstar host exec -w ... 报工作目录不存在或不是目录。

**原因:**把容器路径当成 Host 路径,或使用了错误的 Host 目录。

**处理:**先执行 devstar host inspect,再在 Host 上确认真实目录。Windows 示例:

devstar host exec powershell.exe -NoProfile -Command 'Test-Path -Path "C:\path\to\project" -PathType Container'

7.6 devstar sync 失败

检查:

test -f build/firmware.elf
devstar host inspect
devstar sync build/firmware.elf

常见原因包括:sync 未启用、文件不存在、当前目录错误、Host 未连接、文件超过限制、Host 缓存不可写或传输中断。

先检查退出码和文本中的失败原因。自动化排障可改用 devstar sync --json build/firmware.elf,再检查 JSON 中的 error_code。失败结果中的 path 不可使用;输出无法解析时保留原始 stdout/stderr 继续排查。

7.7 GDB 无法连接

依次检查:

  1. $DEVSTAR_RELAY_DEBUG_ENDPOINT 是否有值。
  2. devstar host inspect 是否成功。
  3. Host 上的 Debug Service 是否仍在运行。
  4. Debug Service 端口是否与 .devstar/remote-debug.json 一致。
  5. QEMU 是否使用 -S 和正确的 GDB 参数。

Relay 可用不代表 Debug Service 已经监听端口。先修复 Host 服务,再重新连接 GDB。

7.8 Host 命令失败或资源没有清理

  • 退出码 124:命令超时。
  • 退出码 130:调用被取消。
  • 其他非零值:通常是 Host 程序自己的退出码。
  • command_output_overflow 或 relay_stream_error:调用方读取输出过慢,或 Relay 连接中断。

连接中断后不要自动重放有副作用的命令。长命令结束后仍有进程或端口占用时,应根据本次 start.pid 清理准确进程,不要按程序名批量结束。

8. 从空白项目配置云端协同调试

本节只适用于不能使用 embedded 模板的已有项目或空白仓库。

8.1 准备 DevContainer 和工具链

DevContainer 需要能够构建带调试符号的 ELF,并安装目标架构对应的 GDB。Host 需要安装项目使用的 QEMU、OpenOCD、J-Link GDB Server 或其他 Debug Service。

接入前先确认:

  • 项目构建命令和 ELF 路径。
  • CPU、开发板或模拟器型号。
  • QEMU machine 或 OpenOCD/J-Link 参数。
  • GDB server 端口。

Relay 不会从源码自动推导这些项目专属信息。

8.2 配置 Remote Debug

在仓库根目录创建 .devstar/remote-debug.json:

{
  "ports": [21234],
  "sync": {
    "enabled": true,
    "artifactPath": "build/firmware.elf"
  }
}

配置规则:

  • ports 最多包含一个调试端口,范围为 1024 到 65535。
  • 30001 是 Artifact Sync 保留端口,不能用作调试端口。
  • artifactPath 必须是工作区相对路径,不能是绝对路径或越出工作区。
  • 启用 sync 但省略 artifactPath 时,默认使用 build/firmware.elf。
  • ports 和 sync 至少启用一项。
  • Host Command 随 Relay 提供,不需要单独配置。

平台从仓库默认分支读取该文件。添加或修改配置后,应先提交到默认分支,再创建或重建 DevContainer。

8.3 可选:安装 Agent 并添加 Skill

只有需要让 Agent 在 DevContainer 中自动完成构建、同步、启动 Debug Service 和 GDB 验证时,才需要本节配置。只使用 VS Code 或手工命令行调试时,可以直接跳到第 8.4 节。

需要使用这条 Agent 自动联调流程时,先配置 AI CLI 安装脚本:

  1. 进入项目的 设置 → 开发容器 → 脚本管理。
  2. 添加 DEVSTAR_INSTALL_CODEX_CLI,或选择项目实际使用的 Claude Code、OpenCode 等安装脚本。
  3. 在 AI 设置或变量管理中配置该工具需要的 API Key、Base URL 和 Model。

项目还应提供 embedded-debug Skill。可以从 embedded 模板复制以下目录:

.claude/skills/embedded-debug/SKILL.md
.claude/skills/embedded-debug/references/
.claude/skills/embedded-debug/scripts/

Skill 应说明:

  • 项目构建和清理命令。
  • 固件在 DevContainer 中的相对路径。
  • 目标架构、开发板或 QEMU machine。
  • Debug Service 的启动参数和就绪判断方法。
  • GDB 验证标准与失败清理要求。

不要把某台电脑的绝对路径、固定 PID、一次性授权码或 Session 信息写入 Skill。

8.4 配置 VS Code

需要使用 VS Code 图形化调试时,在 .vscode/launch.json 中至少配置:

  • program 指向 DevContainer 中实际生成的 ELF。
  • miDebuggerPath 指向容器内的 GDB。
  • miDebuggerServerAddress 使用 ${env:DEVSTAR_RELAY_DEBUG_ENDPOINT}。
  • 远程 GDB Server 使用 request: "launch"。

可以从第 2.3 节的配置开始修改。如果只使用命令行 GDB,这一步可以省略。

8.5 创建容器并连接

完成 Remote Debug、Agent 安装脚本和项目文件配置后,再创建 DevContainer。新增启动脚本,或修改端口、sync 开关、固件路径后,需要重新创建已有容器。

  • 使用 DevStar 插件时,由插件建立或使用当前 Host 连接。
  • 手工连接时,在 WebTerminal 执行 devstar remote-debug,再在 Host 运行输出的启动命令。
  • 连接后使用 devstar host inspect 验证实时状态。

如果配置了 Agent 安装脚本,进入 WebTerminal 后先确认 AI CLI 已安装,例如:

codex --version

8.6 完成第一次调试

在 DevContainer 中构建并同步:

make all
devstar sync

使用 sync 返回的 Host 路径启动 Debug Service,然后在容器中通过 $DEVSTAR_RELAY_DEBUG_ENDPOINT 连接 GDB,或使用第 2 节的 VS Code 配置。

Clone this wiki locally