# 天空星调试助手

**Repository Path**: work_s/sky-star-web-debugger

## Basic Information

- **Project Name**: 天空星调试助手
- **Description**: 基于 WebUSB + DAPLink 的嵌入式调试工具，支持 SVD 寄存器解析、实时示波器、内存查看等功能
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sky Star Web Debugger

Sky Star Web Debugger 是一个围绕 DAPLink 的本地网页调试服务器。浏览器通过 WebUSB + DAPjs 直接连接 CMSIS-DAP/WebUSB 调试器，再通过 SWD 调试 STM32、GD32 等 Cortex-M 目标芯片；本地 Node 服务负责提供网页、缓存调试快照、维护动作队列，并把芯片运行状态开放给 AI 或自动化工具读取。

需要明确的是：Node 服务不是 CMSIS-DAP 协议代理，也不直接转发 SWD 数据。DAP/SWD 通信仍在浏览器内完成。服务器负责文件索引、快照缓存、日志、事件流和动作队列。

## 主要能力

- WebUSB 连接 DAPLink/CMSIS-DAP v2 设备。
- 读取目标芯片 Core 状态、寄存器、内存和 SVD 外设寄存器。
- 以 Watch/Scope 方式周期采样 RAM 变量，便于观察运行数据。
- 管理目标芯片配置文件，目标下拉菜单来自 `targets/`。
- 管理项目 SVD 文件，加载 SVD 时默认读取 `targets/svd-files/`。
- 管理用户 Keil/CMSIS `.FLM` FlashOS 算法，FLM 下拉菜单来自 `targets/flash-algorithms/`。
- 在网页中选择 `.bin`、`.hex`、`.ihex` 固件并烧录目标芯片 Flash。
- 本地服务器提供调试快照、日志、Watch 数据、SSE 事件流和动作队列 API。
- AI/自动化工具可通过 API 请求刷新状态、读内存、控制运行、写内存或烧录固件；服务器不对 AI 动作做分级限制，请求默认直接进入队列等待浏览器执行。

## 目录结构

```text
sky-star-web-debugger/
  index.html              # WebUSB 调试页面
  dap.umd.js              # DAPjs UMD 运行时
  server/dap-server.mjs   # 本地静态服务和调试 API
  targets/                # 目标芯片配置和目标相关资源
    *.json                # 目标芯片配置 JSON
    svd-files/            # 用户和项目 SVD/XML 文件
    flash-algorithms/     # 用户放置 Keil/CMSIS .FLM 算法文件
  stop-dev-server.ps1     # 停止本地端口服务
  package.json            # npm 脚本和依赖
  vite.config.js          # 生产构建配置
  assets/                 # README 和页面使用的图片资源
```

运行产物如 `node_modules/`、`dist/`、`.npm-cache/`、日志文件和历史备份文件不需要提交，已由 `.gitignore` 忽略。

## 环境要求

- Windows 10/11。
- Microsoft Edge 或 Google Chrome，必须支持 WebUSB。
- Node.js LTS 或较新稳定版本，建议 Node.js 20+。
- npm，随 Node.js 安装。
- 支持 WebUSB 的 DAPLink/CMSIS-DAP v2 调试器。
- 目标 Cortex-M 芯片板卡，例如 STM32F407、GD32F407。

硬件连接示例：

```text
DAPLink SWDIO -> 目标板 SWDIO
DAPLink SWCLK -> 目标板 SWCLK
DAPLink GND   -> 目标板 GND
DAPLink VTref -> 目标板参考电压
```

目标板需要按硬件设计正常供电。WebUSB 第一次连接必须由用户在浏览器设备选择框中选择 DAPLink；浏览器获得授权后，后续 AI 请求可以复用网页中的连接状态。

## 安装与启动

进入项目目录：

```powershell
cd D:\codeSpace\svn-ww\DChargeWW\dap\sky-star-web-debugger
```

安装依赖：

```powershell
npm install
```

如果 npm 缓存异常，可以使用项目内缓存：

```powershell
npm install --cache .\.npm-cache
```

启动本地 DAP 网页服务器：

```powershell
npm run dev
```

默认访问地址：

```text
http://127.0.0.1:5173/
```

`npm run dev:ai-flash` 是兼容旧脚本的启动方式，会把固件根目录设为项目上一级目录；当前服务端不再依据 `DAP_AI_AUTOMATION` 限制 AI 动作。

停止本地服务：

```powershell
npm run stop
```

## 常用 npm 脚本

```text
npm run dev           启动 Node 本地服务，提供网页和 API
npm run dev:ai-flash  兼容旧脚本：启动服务并把固件根目录设为 ..
npm run dev:vite      使用 Vite 开发服务器，仅用于前端开发
npm run serve         等同 npm run dev
npm run serve:static  使用 Python 提供纯静态页面，不提供 API
npm run stop          停止 5173 端口上的本地服务
npm run build         生产构建，输出 dist/
npm run preview       预览生产构建
```

## 网页调试流程

1. 插入支持 WebUSB 的 DAPLink，并连接目标板 SWD。
2. 使用 Edge 或 Chrome 打开 `http://127.0.0.1:5173/`。
3. 在顶部“目标芯片”下拉菜单中选择目标配置。
4. 点击连接按钮，在浏览器 USB 设备列表中选择 DAPLink。
5. 确认页面日志显示 DAPLink 和目标芯片连接成功。
6. 加载或确认目标芯片对应 SVD 文件。
7. 使用寄存器、内存、Core、Watch/Scope、串口和固件烧录功能调试目标芯片。

页面连接后会周期性向本地服务发布快照，内容包括连接状态、DAP 信息、Target 信息、Core 寄存器、Watch 值、烧录状态、目标配置和最近日志。

## 目标配置

目标芯片配置文件放在：

```text
targets/
```

网页顶部“目标芯片”下拉菜单会读取该目录下的 `.json` 文件。一个目标配置通常包含芯片名、别名、SVD 文件名、FLM 文件名、Flash/RAM 布局和 FLM 运行参数。

示例：

```json
{
  "id": "stm32f407vet6",
  "name": "STM32F407VET6",
  "vendor": "STMicroelectronics",
  "family": "STM32F4",
  "core": "Cortex-M4",
  "svd": "STM32F407.svd",
  "flm": "STM32F4xx_512.FLM",
  "flash": { "base": "0x08000000", "size": 524288 },
  "ram": { "base": "0x20000000", "size": 131072 },
  "runtime": { "flmLoadBase": "0x20000000", "clockHz": 168000000 },
  "aliases": ["STM32F407VE", "STM32F407"]
}
```

选择目标配置后，网页会尝试自动匹配同名 FLM，设置 BIN 默认烧录地址，并从 `targets/svd-files/` 自动加载配置里的 SVD。

## SVD 文件

项目 SVD 目录：

```text
targets/svd-files/
```

点击网页“加载 SVD 文件”时，弹窗会优先列出该目录中的 `.svd` 和 `.xml` 文件。也可以在弹窗中选择本地 SVD 文件。

服务端接口：

```text
GET /api/svd/files
GET /api/svd/file?id=svd:STM32F407.svd
```

## FLM 算法

用户 FLM 算法目录：

```text
targets/flash-algorithms/
```

把 Keil/CMSIS `.FLM` 算法文件放入该目录后，网页会通过 `GET /api/flash/algorithms` 扫描，并在“FLM算法”下拉菜单中列出。目录内的 `.FLM` 文件默认被 `.gitignore` 忽略，避免把本地算法文件误提交到仓库。

选择用户 `.FLM` 后，网页会通过 `GET /api/flash/algorithm/file` 获取算法文件，在浏览器端解析 FlashOS ELF，下载算法到目标 SRAM，并按 `Init`、`EraseChip` 或 `EraseSector`、`ProgramPage`、`UnInit` 流程执行烧录。写后校验使用目标内存读回对比。

当前用户 FLM 支持范围：

- 支持 linked ELF32 little-endian ARM `.FLM` 文件。
- `.FLM` 必须包含 `FlashDevice`、`Init`、`UnInit`、`EraseSector`、`ProgramPage` 符号。
- 不支持 relocatable `ET_REL` FLM，也不支持仍带有目标装载段重定位记录的算法文件。
- 默认 FLM 装载地址、RAM 结束地址和时钟可由目标配置中的 `runtime` 字段覆盖。
- 当前校验方式适合内存映射的片内 Flash；外部非内存映射 Flash 后续可接入 FLM `Verify`。

## 固件烧录

网页支持选择本机固件文件并烧录到目标芯片。常见 Cortex-M 应用固件地址为：

```text
0x08000000
```

你当前提供的 GD32 固件路径示例：

```text
D:\codeSpace\svn-ww\DChargeWW\dap\mcu_temp_cmake\build\firmware_gd32f407vet6_lite_app_debug\shDap_GD32407.bin
```

烧录前需要满足：

- 浏览器页面已经连接 DAPLink 和目标芯片。
- 已选择目标配置。
- 已选择与目标配置匹配的用户 `.FLM` 算法。
- 固件扩展名为 `.bin`、`.hex` 或 `.ihex`。
- AI 通过 API 读取固件时，固件路径需要位于服务端允许的固件根目录内。

当前 GD32F407 目标配置期望 `GD32F4xx_512.FLM`。如果本地 `targets/flash-algorithms/` 中没有这个文件，网页会显示 FLM 不匹配或缺失，并阻止烧录。请放入匹配 GD32F407 容量和 Flash 控制器的 FLM，或修改 `targets/gd32f407vet6.json` 中的 `flm` 字段为实际文件名。

AI 请求烧录示例：

```powershell
$body = @{
  kind = 'flash_firmware'
  reason = 'program GD32F407 application image'
  payload = @{
    path = 'D:\codeSpace\svn-ww\DChargeWW\dap\mcu_temp_cmake\build\firmware_gd32f407vet6_lite_app_debug\shDap_GD32407.bin'
    targetProfile = 'gd32f407vet6'
    flm = 'GD32F4xx_512.FLM'
    address = '0x08000000'
    eraseMode = 'needed'
    verify = $true
    resetAfter = $true
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:5173/api/ai/request-action `
  -ContentType 'application/json' `
  -Body $body
```

服务器会把动作加入队列；网页轮询到动作后执行。浏览器页面必须保持打开，因为真正的 DAP/SWD 操作在浏览器内完成。

## AI 调试 API

面向后续 AI 首次接入的完整操作手册见 [AI_DEBUG_GUIDE.md](AI_DEBUG_GUIDE.md)。该文档说明了 AI 如何读取 MCU 状态、下发调试动作、监听动作完成、添加观察变量和触发固件烧录。

所有接口默认只监听本机：

```text
http://127.0.0.1:5173/api/...
```

只读状态接口：

```text
GET /api/health
GET /api/capabilities
GET /api/ai/capabilities
GET /api/snapshot
GET /api/session/state
GET /api/target/info
GET /api/core/registers
GET /api/watch/list
GET /api/watch/snapshot
GET /api/logs/recent?limit=100
GET /api/events/recent?limit=100
GET /api/events
```

`/api/events` 是 Server-Sent Events 流，适合 AI 或自动化工具持续监听快照、日志和动作状态。

目标、SVD、FLM 和固件文件接口：

```text
GET  /api/targets
GET  /api/targets/file?id=target:stm32f407vet6.json
POST /api/targets/select
GET  /api/svd/files
GET  /api/svd/file?id=svd:STM32F407.svd
GET  /api/flash/algorithms
GET  /api/flash/algorithm/file?id=user-flm:STM32F4xx_512.FLM
GET  /api/firmware/file?path=...
```

动作队列接口：

```text
POST /api/ai/request-action
GET  /api/actions
GET  /api/actions?status=queued
GET  /api/actions/{id}
GET  /api/actions/next
POST /api/actions/{id}/complete
```

兼容旧前端或旧脚本的接口仍保留：

```text
GET  /api/actions/pending
POST /api/actions/{id}/resolve
```

当前动作模型：AI 向 `/api/ai/request-action` 写入请求；服务器直接创建 `queued` 动作；网页轮询 `/api/actions/next` 并执行动作；执行完成后网页调用 `/api/actions/{id}/complete` 回写结果。服务端不再因为 AI 等级把动作停在 `pending`。

刷新 Core 寄存器示例：

```powershell
Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:5173/api/ai/request-action `
  -ContentType 'application/json' `
  -Body '{"kind":"refresh_core","reason":"AI wants latest PC/SP"}'
```

读取当前会话状态：

```powershell
Invoke-RestMethod http://127.0.0.1:5173/api/session/state
```

查询服务能力：

```powershell
Invoke-RestMethod http://127.0.0.1:5173/api/capabilities
```

`/api/capabilities` 会返回 `mode: local-unrestricted`、动作种类、固件根目录、SVD 目录、FLM 目录和目标配置目录。

## 服务配置

可用环境变量：

```text
DAP_SERVER_HOST          监听地址，默认 127.0.0.1
DAP_SERVER_PORT          监听端口，默认 5173
DAP_SERVER_ROOT          静态资源根目录，默认项目根目录
DAP_SERVER_MAX_BODY      API 请求体大小限制，默认 2 MiB
DAP_FIRMWARE_ROOTS       固件读取根目录，多个目录用系统分隔符分隔
DAP_FIRMWARE_MAX_BYTES   固件文件大小限制，默认 8 MiB
DAP_FLASH_ALGORITHM_ROOT 用户 FLM 算法目录，默认 targets/flash-algorithms
DAP_MAX_FLASH_ALGORITHM_BYTES  单个 FLM 文件大小限制，默认 2 MiB
DAP_SVD_ROOT             SVD 文件目录，默认 targets/svd-files
DAP_MAX_SVD_BYTES        单个 SVD 文件大小限制，默认 12 MiB
DAP_TARGET_ROOT          目标配置目录，默认 targets
DAP_AI_AUTOMATION        兼容旧脚本读取；当前不用于限制 AI 动作
```

Windows 上多个固件目录使用分号分隔：

```powershell
$env:DAP_FIRMWARE_ROOTS = 'D:\firmware;D:\codeSpace\svn-ww\DChargeWW\dap'
npm run dev
```

## 构建与归档

生产构建：

```powershell
npm run build
```

输出目录：

```text
dist/
```

当前页面通过普通脚本加载 `dap.umd.js`，Vite 构建时会提示该脚本不会被打包。这是预期行为，`vite.config.js` 会在构建结束后把 `dap.umd.js` 复制到 `dist/`。

归档或提交前建议清理以下运行产物：

```text
node_modules/
dist/
.npm-cache/
*.log
*.err.log
index.backup-before-layout-cleanup-*.html
backup-before-layout-cleanup-*-assets/
```

## 常见问题

### 打不开 127.0.0.1:5173

先确认服务是否启动：

```powershell
netstat -ano | findstr 5173
```

如端口被旧进程占用，执行：

```powershell
npm run stop
npm run dev
```

### 浏览器找不到 DAPLink

检查是否使用 Edge/Chrome、是否通过 `http://127.0.0.1:5173/` 打开、DAPLink 固件是否启用 WebUSB、USB 线是否支持数据传输、设备是否被其他调试软件占用。

### 连接成功但读不到目标芯片

检查目标板供电、SWDIO/SWCLK/GND/VTref 接线、目标芯片是否处于复位或低功耗状态、读保护是否开启、SVD 文件是否匹配芯片型号。

### AI 动作未执行

服务器只负责排队，真正执行动作的是浏览器页面。请确认网页已打开、页面没有报错、DAPLink 已连接、网页正在轮询 `/api/actions/next`。烧录动作还需要目标配置和 FLM 匹配，固件路径也必须位于 `DAP_FIRMWARE_ROOTS` 允许的目录内。

### API 返回 snapshot_not_available

这表示网页尚未向服务器发布调试快照。请确认使用 `npm run dev` 启动的是 Node 服务，浏览器打开同一端口，页面已完成加载并至少执行过连接、刷新 Core 或添加 Watch 等操作。