Probes VS Code 扩展

Probes 是面向嵌入式工程的 AI 协作扩展，覆盖代码理解、工程构建、烧录、调试、串口/UART、逻辑分析和 PID 参数迭代。

设备中心与 Deck 的唯一后续执行规划见统一执行规划。保持原有两层产品界面及受管理 Node/Python 架构，底层通信和终端/表格/图表复用成熟方案并完整呈现约定的数据视图。M1 交付独立 EXE/UART、原始记录/速率趋势及人机共用界面；M2-M4 再交付独立串行族、Modbus、CAN/DBC 的完整视图，不等于当前已支持全部协议。 USB-TTL、RS-232、RS-422、RS-485 各自创建固定类型面板和 session，只共享底层代码；不能在串口终端或 CLI configure 中切换类型，各实例配置、日志和显示状态互不影响。

设备通信的当前运行时参考见 docs/shared/comm-runtime-architecture.md： probes-comm CLI 与单实例 Daemon 是 AI、面板和 CI 的共同入口，底层使用受治理的 pySerial、PyModbus、python-can 和 cantools runtime。旧 UART MCP 与 PowerShell transport 已退休。不新增设备签名许可或多窗口接管平台，也不改变现有 runtime 权限。

适用场景

理解现有工程、符号和调用关系
使用 CMake 或常见 MCU 工具链完成构建与烧录
在 VS Code 中串联代码修改、构建、调试和设备观测
结合 UART、RTT、逻辑分析和仪器数据定位问题
记录实验结果并迭代 PID 或其他控制参数

支持范围

当前重点覆盖 ARM 和 RISC-V 嵌入式项目，包括 STM32、Nordic nRF、Espressif ESP32、NXP LPC/i.MX RT、Microchip/Atmel SAM、TI MSPM0、WCH CH32、Holtek HT32、Silicon Labs EFM32/ EFR32 和 Infineon XMC 等系列。具体工具可用性取决于本机工具链、设备连接和项目配置。

自定义提供方（本地直连第三方 API）

Probes 支持在扩展内接入你自己的第三方 Responses 兼容端点：该模式下 Codex runtime 直接请求你的端点，不经 Probes 后端网关、不产生计费、不消耗积分、不依赖任何 Probes 服务端。

使用方式

打开 Probes 设置面板：页面顶部是"模型"概览——第一行为当前选中的模型，下方逐行列出自定义提供方；通过各行"编辑"展开模型列表或自定义提供方详情，底部"+ 添加自定义提供方"打开表单。
填写表单后点击右下角主按钮即完成：新增时按钮显示"添加提供方"，通过某一行"编辑"进入同一表单时按钮变为"保存"（同一表单兼作新增与编辑）：
- 名称：仅本地展示。
- Base URL：必须为 https（本地开发允许 http://localhost / http://127.0.0.1），不能携带 query 或 fragment，形如 https://api.example.com/v1。
- API 协议：openai-responses（默认，Codex 直连）；chat-completions 与 anthropic-messages 经本机协议转换代理转发（仍为本地直连，不经 Probes 后端）。
- API Key：密码型输入，仅写入 VS Code SecretStorage（键 probes.customProvider.<id>.apiKey），不落盘到 config.toml/auth.json/globalState，也不进日志。
- 模型：模型清单只能通过"获取可用模型"从提供方的 /v1/models 端点获取，表单不再提供手工输入模型名称的文本框；已添加的数量在表单内以摘要行显示。
  - 获取可用模型：填写 Base URL 后，点击"获取可用模型"按钮可自动从提供方的 /v1/models 端点获取可用模型列表。功能特性：
    - 支持所有兼容 OpenAI API 格式的提供方（标准 /v1/models 端点）
    - 可选填写 API Key（部分提供方的 /v1/models 端点需要认证）
    - 弹出对话框展示所有可用模型，支持搜索和多选
    - 点击"添加所选"将选中的模型追加到模型清单（自动跳过已存在的模型）
    - 请求超时时间为 15 秒
    - 如果提供方不支持此端点或发生错误，会显示相应的错误提示；此时无法为该提供方添加模型，提交会被拒绝
- Reasoning Effort（可选）：none/low/medium/high；不填则运行时配置省略该行。
在提供方卡片上选择"使用此提供方"，或用顶部开关切回"托管网关"。

边界与须知

使用自定义提供方时，第三方端点将收到你的代码上下文与提示内容。
用量/账单面板在该模式下没有数据（无后端参与）。
Probes 的客户端错误上报在该模式继续可用，但采用字段白名单，不包含 baseUrl、模型输出内容或任何请求头值；support bundle 只记录模式与提供方 id（不含 URL 与 key）。
模型选择、图片输入等能力按 v1 声明渲染：自定义模型为 text-only，推理 effort 按 profile 声明。
切换提供方（托管 ↔ 自定义，或在不同自定义提供方之间）后需重启运行时才生效；设置面板会给出提示。切换回托管网关不会残留第三方 key：自定义 key 只经进程环境变量 PROBES_CUSTOM_PROVIDER_API_KEY 传递，managed 凭据通道在该模式下完全隔离。

技术摘要

Profile 元数据存于 VS Code globalState（probes.customProviderProfiles.v1，zod 契约校验）；激活态为 settings probes.runtimeProviderMode（managed/custom）与 probes.activeCustomProviderId。
自定义提供方在 runtime config 中生成独立 [model_providers.custom-<id>] 段：wire_api = "responses"、requires_openai_auth = false、env_key = "PROBES_CUSTOM_PROVIDER_API_KEY"；凭据仅通过该环境变量注入 runtime 进程。
启动时按激活 profile 投影出模型目录 custom-model-catalog.json（runtime home 内，经 model_catalog_json 指向）：pinned runtime 据此解析各模型的上下文窗口（发现接口不返回该值，统一使用 272k 默认值）、推理等级与 text-only 能力，避免"Model metadata not found"的 fallback 降级告警；投影失败时跳过目录、仅记录告警，会话仍可启动。
运行时要求 pinned Codex 0.156.1（仅支持 wire_api = "responses"）；非 Responses 协议由本地转换代理兜底（见下条）。
本地协议转换代理：选择 openai-completions / anthropic-messages 时，扩展宿主在 127.0.0.1 随机端口启动一个 loopback 代理，Codex runtime 仍只说 Responses 协议，代理在本地完成协议翻译后转发给第三方端点（API key 仅按请求透传，不落盘）。代理启动失败时 fail-open：记录告警并回退直连（会话仍可启动，转换请求会得到上游 404）。
形状错配兜底：第三方端点若对 stream: true 请求返回整段 JSON（而非 SSE），代理会把该响应重放为完整的 Responses 事件序列（response.output_item.added → 增量事件 → response.output_item.done，再以 response.completed 收尾）。pinned runtime 只从 item 级事件构建回合内容，仅发生命周期事件会让"上游有响应"的回合在界面上表现为对话为空，因此这条兜底必须补齐 item 生命周期。

芯片环境与依赖管理

登录后，首次打开未登记的本地工作区时，扩展会先显示芯片环境选择流程，再进入聊天。芯片目录统一分为 available（已正式支持并可自动准备）、pending（计划支持，当前不可确认）和 unavailable（不由 Probes 支持，由用户自备环境）三种状态。available 选择会明确列出将安装和将复用的依赖；选择只在扩展全局存储中登记当前工作区，不会修改工程文件、工作区配置、PATH 或用户工具链。已登记的工作区会直接进入聊天，也可以暂时跳过。

首版选择范围包括全量 STM32、ESP32 Xtensa/RISC-V、Nordic nRF Connect、Pico、NXP、Renesas RA FSP、Silicon Labs、TI、Microchip、Infineon、GigaDevice GD32、Artery AT32、Puya PY32、HPMicro、Nuclei 和 SiFive 方案；厂商 IDE/专有工程、需逐型号核对的 SDK、Linux/应用处理器及安全多核系统标记为 unavailable，由用户准备环境。扩展管理的依赖单元写入扩展全局存储，用于完整验证依赖生命周期，不包含厂商 SDK 或工具链内容。

在侧边栏标题栏点击设置按钮，打开“依赖管理”。页面连续显示当前工作区和状态异常包；当前项目依赖与完整依赖库默认收起，展开后可查看、搜索和筛选。ESP32 Xtensa 和 RISC-V 在依赖列表中各显示一条 support 单元；ESP-IDF SDK、Python、GCC、CMake、Ninja 和离线 Python 组件作为该单元的固定内部组件下载和组装，不产生额外选择项。选择单个依赖后可在行内详情中安装、重试或卸载，刷新入口位于页头。状态异常包只包含完成安装后发现清单缺失、清单损坏或关键文件缺失的依赖；下载、校验、安装、取消或卸载失败会清理当前单元并恢复为待安装。若文件锁等原因阻止清理，依赖显示为“待清理”，可重试清理且不会进入异常区。没有工作区引用且没有已安装反向依赖的依赖会直接卸载；否则 VS Code 会说明引用数和会级联卸载的依赖，确认后按依赖方优先的顺序卸载。卸载完全成功后，闭包内包含被卸载单元的 available 登记会被清除，对应工作区下次进入时会重新完成芯片选择。available 安装只面向本地 Windows 工作区；unavailable 只登记用户自备环境，pending 不会创建安装任务。

典型使用流程

安装扩展并打开目标工作区。
完成登录和芯片环境选择，或登记用户自备环境。
在聊天面板中描述目标和当前工程状态。
根据需要执行编码、编译、烧录、调试、观测分析或 PID 参数迭代。

Technical Docs

在 Probes 视图标题栏使用书本按钮，选择技术指南并在编辑器中打开。在 Probes 视图标题栏使用齿轮按钮，打开设置并选择模型。

版本

当前版本：1.2.0

probes-comm runtime note: the production path is exclusively the managed probes-comm CLI and single-instance daemon backed by the managed protocol runtimes. The VS Code terminal and Codex exec_command share daemon sessions; no UART MCP or direct PowerShell/Python serial transport is part of the active surface.

Runtime model selection is initialized from the validated governed catalog bundled with the extension. The Extension projects only governed, available models into the picker and preserves a thread-owned model for active work. Conversation history is read from the pinned Codex runtime through native thread APIs; the Extension does not persist or merge local timeline snapshots.

Probes AI Embedded Assistant

probes-team