Pro Debug Watch

Pro Debug Watch 是面向 Cortex-Debug 的开源 VS Code 扩展。它为嵌入式调试补充批量表达式管理、Live Watch 趋势绘图，以及供本机 AI 客户端读取调试上下文的只读 MCP 服务。源码与问题跟踪位于 GitHub 仓库。

功能

• 批量导入表达式，或从当前 ELF 中多选全局变量，并分别写入原生 WATCH、Cortex Live Watch 和绘图。
• 运行态优先通过 Cortex-Debug Live Watch provider 添加和读取表达式，不主动暂停、复位、写内存或发送 Monitor 命令。
• 以 1--20 Hz 显示最近 20 秒的自动缩放趋势图，并可导出当前调试会话的完整长格式 CSV。
• 提供仅监听回环地址、使用 Bearer Token 鉴权的只读 MCP 服务，支持会话状态、只读求值、表达式、绘图快照、暂停态内存和寄存器读取。

要求

• VS Code 1.106 或更高版本。
• Cortex-Debug 1.12.1 或更高版本。
• 调试配置包含 executable，且系统可找到对应工具链的 arm-none-eabi-nm，用于 ELF 符号选择。
• 若需运行态采样，在 launch.json 启用 Cortex-Debug Live Watch：

"liveWatch": {
  "enabled": true,
  "samplesPerSecond": 4
}

安装与使用

1. 从发布产物安装 pro-debug-watch-1.0.0.vsix，然后重新加载 VS Code。
2. 启动 Cortex-Debug 调试会话，打开“运行和调试”侧栏中的“批量监视”或“绘图”。
3. 在“批量监视”中粘贴多行表达式，或选择“ELF 选择”添加全局变量；勾选要写入的目标后提交。
4. 在“绘图”中可直接添加单个只读表达式。暂停、清空、导出和采样率控件只影响本扩展的绘图数据。

删除由本扩展管理且已写入原生 WATCH 的表达式时，扩展会先显示确认，再重建剩余的托管 WATCH。VS Code 尚未提供按表达式删除原生 WATCH 的公开 API，因此手动创建、不由本扩展管理的 WATCH 不会被保留。

MCP

默认启用的 MCP 服务仅监听 127.0.0.1:38473。首次启动生成的 Bearer Token 存在 VS Code SecretStorage 中；端口和 Token 在扩展重启后保持稳定。执行命令“Pro Debug Watch: 复制 MCP 配置”即可获取外部客户端的连接配置。

设置项：

• proDebugWatch.mcp.enabled：启用或关闭 MCP 服务。
• proDebugWatch.mcp.port：本机回环端口，范围为 1024--65535；同一主机上的多个 VS Code 窗口需使用不同端口。
• proDebugWatch.plot.sampleRateHz：目标采样频率，范围为 1--20 Hz。
• proDebugWatch.logLevel：输出日志级别。

服务不会提供写表达式、写内存、控制执行或其他有副作用的工具。内存和寄存器读取仅在目标暂停时可用。Token 属于连接凭据，不应提交到仓库、日志或共享配置中。

可用工具：

• pro_debug_watch_session_state：读取会话和 Live Watch 状态。
• pro_debug_watch_evaluate：求值通过保守语法检查的表达式。
• pro_debug_watch_list_expressions：读取当前工作区的托管表达式。
• pro_debug_watch_plot_snapshot：读取最近的绘图样本。
• pro_debug_watch_read_memory：暂停态读取最多 4096 字节内存。
• pro_debug_watch_read_registers：暂停态读取核心寄存器。

数据与兼容性

• “只读表达式”由保守的语法规则限制赋值、自增/自减、语句块和函数调用；它不是 C/C++ 语义证明。只应把 MCP Token 提供给可信的本机客户端。
• 未导出的绘图样本临时写入 VS Code 扩展全局存储，以支持完整 CSV 导出；扩展再次激活或停用时会清理这些临时文件。用户明确导出的 CSV 不会自动删除。
• Live Watch provider、Live Watch DAP 请求和原生 WATCH 命令不是稳定的公开 API。兼容基线为 Cortex-Debug 1.12.1 与 VS Code 1.106；升级依赖后应重新验证这些路径。
• 同时打开多个启用 MCP 的 VS Code 窗口时，每个窗口必须配置不同的 proDebugWatch.mcp.port。

开发

npm ci
npm run check
npm run test:vscode
npm run package

npm run check 执行类型检查、ESLint、Vitest 和生产构建。npm run test:vscode 仅使用本机 /Applications/Visual Studio Code.app/Contents/MacOS/Code 或 VSCODE_EXECUTABLE_PATH 指定的 VS Code，不下载其他版本。npm run package 会在 dist/ 中生成与 package.json 版本一致的 VSIX。

参与开发前请阅读 贡献指南 和 架构说明。

许可证与致谢

本项目以 MIT License 发布。发行包内依赖、内嵌资源及 Cortex-Debug / VS Code 兼容性接口参考均在 第三方声明 中列出；构建会把所用组件的原始许可证文本复制进 VSIX，package-lock.json 锁定完整依赖树。