AI 流程 · IDE 插件（coding-workflow-plugin）

在 IDE 里查看并推进 AI 编码工作流：本地 .coding-workflow/ 为真源，通过 cw serve 本地 HTTP 桥读写， 与 coding-workflow-server（管理端）弱同步。

宿主兼容性

探针方法与原始证据（可复现）：构造一个只注册一条命令的最小扩展，activate() 时把宿主信息写入 %TEMP%\cw-probe.log，并在 2.5s 后自动创建 WebviewPanel，其 CSP 声明 connect-src http://127.0.0.1:*，页面内 fetch('http://127.0.0.1:<随机端口>/health') 打回结果。 Trae CN 上的实测输出：

[2026-10-27T02:24:06.587Z] activate: vscode=1.107.1 appName=Trae CN appHost=desktop uiKind=1
[2026-10-27T02:24:20.514Z] probe server on http://127.0.0.1:57929
[2026-10-27T02:24:40.396Z] webview result: {"step":"fetch-ok","status":200,"body":"{\"ok\":true,\"from\":\"probe-server\",\"url\":\"/health\"}"}

结论：Webview 直接 fetch 本地回环端口可行，不需要退化为 postMessage → 宿主 → HTTP 代理 （代理通道仍保留在 hostBridge 里，供未来宿主受限时切换）。

这是什么

这是 AI 编码工作流的 IDE 客户端工作台：以工作区本地 .coding-workflow/ 为真源，经 cw serve 本地 HTTP 桥读写流程定义与节点运行状态，与 coding-workflow-server（管理端）弱同步；管理端不可达时 页面照常渲染（离线优先）。

插件提供两个容器：

• 编辑器标签页（宽版）：由命令 AI Flow: 打开流程执行总览（或 AI Flow: 打开当前节点）在编辑器区 打开 WebviewPanel，适合浏览流程总览等宽内容；容器开启 retainContextWhenHidden，切走再回来不丢状态。

• Activity Bar 侧边栏（紧凑版）：点击左侧活动栏的「AI 流程」图标打开 WebviewView，适合长期驻留、 随手查看当前节点；不开 retainContextWhenHidden，改用 webview 原生 setState/getState 持久化状态。

• 两者共享同一份 webview UI（同一份 Vue bundle）；布局由注入的 surface 与 480px 断点决定： surface=sidebar 或容器宽度 < 480px 判为紧凑版，否则宽版；紧凑版只折叠区块、不删减信息项。

• 两者可互跳（标签页 ⇄ 侧边栏）且状态自动同步（本地状态文件变更或节点写操作后，宿主向其它容器广播刷新）。

• 两个容器的顶栏下方均有**「总览 / 接入 / 回传」三个 tab**，用于切换两个辅助页：13 项目接入（只读诊断 + 版本校验）与 16 交付物回传（产物登记回传 + 交付物回传：产物登记 + 真实文件按 5MB 分片上传（≤500MB），支持断点续传与离线补传 + 本地未回传队列 + 版本历史）；节点执行页仍从总览或命令进入。

• 本期交付后，由使用者自行对比两种容器再决定下一期保留哪一个。

构建与安装

前置

• Node 18+（构建脚本依赖 esbuild 0.24）。
• cw 可不在本机预装：插件启动后若未找到，可在引导页/状态页点「一键安装 cw」（经内网 npm 源）； 手工安装可用 npm i -g @h3c/cw --registry <内网源>，cw version 可验证。

构建

npm install                 # 安装扩展开发依赖
cd webview && npm install   # 安装 webview（UI 子工程）依赖
cd ..                       # 回到插件根目录
npm run build               # 打包扩展（esbuild）+ 构建 webview（Vite）+ 同步产物到 dist/
npm run pack                # 产出 coding-workflow-ai-flow-<version>.vsix

npm run build = build:extension + build:webview + sync-webview；npm run pack 会先 build，再优先用 vsce 打包，失败回退内置 ZIP 打包器。产出文件名形如 coding-workflow-ai-flow-0.2.11.vsix。 npm test 运行单元测试（vitest：cw 定位优先级/预检、serve 启动行解析、版本比较）。

安装（按宿主）

• VS Code / VS Code Insiders：code --install-extension <vsix>
• Trae CN（已实测，下述为本机实测路径）："D:\软件\Trae CN\bin\trae-cn.cmd" --install-extension <vsix>
• TRAE CN Enterprise：trae-cn-enterprise.cmd --install-extension <vsix>
• CodeBuddy CN：buddycn.cmd --install-extension <vsix>
• 任意宿主也可在 IDE 的「扩展」面板右上角菜单选「从 VSIX 安装…」。

除 Trae CN 外，各宿主命令按各自 CLI 约定给出、未逐一实测（见「宿主兼容性」）。

发布到 Open VSX

1. 登录 https://open-vsx.org/login（GitHub 或 Eclipse 账号）。
2. 打开 https://open-vsx.org/user-settings/tokens，点「Generate Access Token」，复制一次性 token。
3. 打开 https://open-vsx.org/user-settings/namespaces，创建与 package.json 的 publisher 同名的命名空间 h3c； 若已被占用，把 publisher 改成唯一值（如 h3c-ai-flow）后重新打包。
4. 认领命名空间：创建命名空间只会成为 contributor，命名空间仍处于 unverified；未认领时扩展页会显示 “not a verified publisher” 警告，版本可能被停用。按 Namespace Access 在 https://github.com/EclipseFdn/open-vsx.org/issues/new/choose 提交 ownership 申请。
5. 发布（token 放环境变量，不要写进脚本或仓库）：

$env:OVSX_PAT = "<token>"
npx ovsx@latest publish coding-workflow-ai-flow-0.2.11.vsix

发布成功后扩展页形如 https://open-vsx.org/extension/h3c/coding-workflow-ai-flow， Trae / CodeBuddy 的扩展市场可直接搜索安装。

若 ovsx publish 在上传阶段报 write ECONNRESET（网关提前断流），可用 curl 直接调用同一接口：

curl.exe -X POST "https://open-vsx.org/api/-/publish" `
  -H "Authorization: Bearer $env:OVSX_PAT" `
  -H "Content-Type: application/octet-stream" `
  --data-binary "@coding-workflow-ai-flow-0.2.11.vsix"

同一版本一经发布不可覆盖；需要修正时请提升版本号后重新发布。

注意：open-vsx.org 是公开注册表，发布后 vsix 内容（README、dist 中的 source map）与默认内网地址均对外可见。 若不允许公开，请改用自建 Open VSX（eclipse/openvsx），并让宿主指向内部实例。

开发调试

• 以 F5 等价方式加载本目录（无需打包）：启动宿主时传 --extensionDevelopmentPath=<插件目录>。
• 让 webview 走 Vite dev server 热更新：先 cd webview && npm run dev，再以环境变量 AI_FLOW_DEV_SERVER=http://localhost:5173 启动宿主。

浏览器内调试 UI（不进 IDE）

cd webview && npm run dev

然后打开 http://localhost:5173/?baseUrl=http://127.0.0.1:<cw serve 端口>&token=<token>&surface=panel|sidebar&theme=dark。

• baseUrl / token 取自 .coding-workflow/serve.json；
• surface（panel / sidebar）与 theme（dark / deepblue）用于预览两种容器与配色。

配置项

未受信任的工作区（Workspace Trust）只读取以上配置的用户级值，忽略仓库内 .vscode/settings.json， 且不会自动启动本地服务。信任工作区后会自动恢复。

另有一个进程环境变量（非 IDE 配置项）：CW_UPLOAD_CHUNK_KB 控制 cw serve 上传分片大小，单位 KB，默认 5120（5MB），取值会被钳制到 1～8192（即 1KB～8MB）。

命令清单

首次使用

1. 在项目根目录执行 cw init 接入工作流（生成 .coding-workflow/）。
2. 用该目录作为工作区打开 IDE；扩展在 onStartupFinished 检测到 .coding-workflow/ 后自动定位 cw 并确保 cw serve 就绪（仅监听 127.0.0.1 随机端口）。若 .coding-workflow/serve.json 指向的实例存活 （GET /health 在 1.5s 内响应），直接复用；缺失或失活时才自行启动。
3. 点击 Activity Bar 的「AI 流程」图标，或执行命令 AI Flow: 打开流程执行总览。

退出插件时只回收自己启动的 cw serve 实例；复用他人实例时不动它。

插件更新与 cw 版本要求

内网不走公共扩展市场，IDE 不会原生提示插件更新，故由管理端版本清单 + 插件本机检查承担。

接口契约（管理端）：GET {aiFlow.serverUrl}/plugin/latest → { version, url, notes?, publishedAt?, minCwVersion? }。 未配置（data/plugin.json 不存在或为空）时返回 200 + { "version": null }，插件据此静默忽略。 管理端首次启动会 seeds 一条当前已交付版本的记录（version 与插件 package.json 对齐，url 留空，发布时改成内网 vsix 地址）。

检查时机：插件激活后立即检查一次，此后每 6 小时一次（单次请求超时 10s）。

• 插件新版：清单 version 高于本地扩展版本 → 在两个容器顶部显示提示条「发现新版本 vX（当前 Y）」，并带「立即更新」与「手动下载」按钮： 「立即更新」由扩展下载清单 url 指向的 vsix 到临时目录并调起 workbench.extensions.installExtension 安装，完成后提示重新加载窗口；「手动下载」用系统浏览器打开 url。 原生信息提示（首次发现时弹出）同样带「立即更新」按钮。
• 版本变化提示：扩展激活时若检测到版本较上次运行发生变化（如手动安装 vsix 后），提示「重新加载窗口」，避免旧 webview 残留资源引用导致黑屏。
• cw 兼容性：读本地桥 cw serve 的 GET /health 的 version，若低于清单的 minCwVersion（清单缺省时用插件内置兜底 0.3.0）→ 提示「本地 cw 版本过低」。
• 关闭持久化：用户关闭过的提示按 kind + 版本 持久化，同一容器重建或切换容器后不再重复弹。
• 失败静默：任何检查失败（网络 / 超时 / 非 2xx / 非 JSON / 清单未配置）都不弹错、不阻断，只在 OutputChannel「AI Flow」写一行日志。

发布新版本的做法：改管理端 data/plugin.json 的 version 与 url（指向新 vsix 的内网地址）即可；minCwVersion 用于声明该插件版本要求的最低 cw 版本。

说明：若将来内网部署 Open VSX 实例并让各宿主指向它，可改用 IDE 原生的「检查更新」，本机制可退役。

故障排查

面板/侧边栏在「未初始化」「cw 缺失」「serve 起不来」三种情况下都会渲染明确的中文引导页，不会白屏。

cw serve 接口清单

仅在 127.0.0.1 回环地址监听；除 /health 外均需请求头 Authorization: Bearer <token>。

安全

• cw serve 仅绑定 127.0.0.1，默认使用随机空闲端口，不对局域网暴露。
• 鉴权用 Authorization: Bearer <token>：token 为启动时生成的 32 字节随机值，写入 .coding-workflow/serve.json。
• .coding-workflow/serve.json 含 token，不应提交到版本库，建议加入 .gitignore（cw serve 退出时会自动删除该文件）。
• 扩展的 webview CSP 放行 connect-src http://127.0.0.1:*，并禁止 unsafe-eval。
• 遵循 IDE 的 Workspace Trust：未受信任的工作区不自动启动 cw serve，也不读取工作区级的 cwPath / cwRegistry / serverUrl，避免仓库内配置注入可执行文件或安装源。
• 管理端数据一律经 cw serve 代理（/server/workflow、/server/gate-results、/server/artifact-reports），webview 不直连管理端；CSP 因此仍只放行 http://127.0.0.1:*。

架构速览

IDE（VS Code 系）                      本地
├─ 编辑器标签页（WebviewPanel · 宽版）┐
├─ 侧边栏视图（WebviewView · 紧凑版）┤ 同一份 Vue bundle
│                                  └─► fetch(Authorization: Bearer) ──► cw serve（127.0.0.1:随机端口）
└─ Extension Host（cw 定位 / serve 生命周期 / 单例注册表 / HostAdapter）
                                        └─► 读 .coding-workflow/{flow,state}.json；写 state；回传 report