@chenguangyao/devflow-kit 0.1.43 → 0.1.44

package/client/workflow-adapter.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../src/client/workflow-adapter-client.js');

package/docs/workflow-orchestration.md

@@ -219,29 +219,110 @@ devflow flow picker --slug=<slug> --json
 - `quality`：专项检查，例如 frontend-quality / security-hardening / dependency-upgrade / ci-fix。
 - `delivery`：质量闸与交付，例如 review / verify / deliver / archive。
 
-每个 item 会标记 `selected`、`recommended`、`locked`、`required`、`protected`、`installed`、`source` 和可执行的 `command`。系统推荐 recipe 中的 step 会自动 `selected=true`；open risk signal 对应但尚未选中的专项 skill 会显示 `recommended=true` 和原因，例如 `open frontend_change risk signal`。`review`、`verify`、`deliver` 这类 protected gate 会显示 `locked=true`，UI 可以渲染为不可取消。
+每个 item 会标记 `selected`、`recommended`、`locked`、`required`、`protected`、`installed`、`source`、`after`、`before` 和可执行的 `command`。系统推荐 recipe 中的 step 会自动 `selected=true`；open risk signal 对应但尚未选中的专项 skill 会显示 `recommended=true` 和原因，例如 `open frontend_change risk signal`。`review`、`verify`、`deliver` 这类 protected gate 会显示 `locked=true`，UI 可以渲染为不可取消。候选专项 skill 会带上 `after` / `before` placement，UI 直接提交修改后的 picker surface 时不需要自己推断插入位置。
 
-这份 picker 协议的 schema 真源是 `schemas/workflow-picker.schema.json`。UI 不应依赖 CLI 人类输出解析，而应使用 `flow picker --json` 中的 `groups[].items[]` 渲染线性选项卡。典型 picker 输出样例固定在 `test/fixtures/workflow-surfaces/picker-*.json`，覆盖默认推荐和 risk signal 推荐专项 skill 两种场景。
+这份 picker 协议的 schema 真源是 `schemas/workflow-picker.schema.json`。`apply-selection` 的输入 schema 真源是 `schemas/workflow-selection.schema.json`，它同时支持最小 `{ "items": [...] }` 和前端修改后的完整 `workflow_picker_surface`。UI 不应依赖 CLI 人类输出解析，而应使用 `flow picker --json` 中的 `groups[].items[]` 渲染线性选项卡。典型 picker 输出样例固定在 `test/fixtures/workflow-surfaces/picker-*.json`，覆盖默认推荐和 risk signal 推荐专项 skill 两种场景。
 
-静态 UI 原型固定在 `docs/workflow-ui-prototype.html`，由 `npm run prototype:workflow` 从 `test/fixtures/workflow-surfaces/*.json` 生成。它展示线性 skill 选项卡、推荐勾选态、locked gate 和 workflow 确认卡，不需要 dev server，直接打开 HTML 即可检查交互形态。
+静态 UI 原型固定在 `docs/workflow-ui-prototype.html`，由 `npm run prototype:workflow` 从 `test/fixtures/workflow-surfaces/*.json` 生成。它展示线性 skill 选项卡、推荐勾选态、locked gate、`workflow_selection_result_surface` 成功应用面板、workflow 确认卡和风险确认卡，不需要 dev server，直接打开 HTML 即可检查交互形态。
 
-如果要用真实 change state 生成实时原型，可以运行 `npm run prototype:workflow -- --slug=<slug> --cwd=<repo>`。脚本会调用 `devflow flow picker --slug=<slug> --json` 和 `devflow flow card --slug=<slug> --json`，默认写到系统临时目录的 `devflow-workflow-ui-<slug>.html`，避免覆盖仓库内的静态 fixture 原型；需要指定位置时加 `--out=<file>`。
+如果要用真实 change state 生成实时原型，可以运行 `npm run prototype:workflow -- --slug=<slug> --cwd=<repo>`。脚本会调用 `devflow flow picker --slug=<slug> --json` 和 `devflow flow card --slug=<slug> --json`，默认写到系统临时目录的 `devflow-workflow-ui-<slug>.html`，避免覆盖仓库内的静态 fixture 原型；需要指定位置时加 `--out=<file>`。如果要预览用户勾选后的链路，可以追加 `--selection='{"items":[...]}'` 或 `--selection-file=<file>`，脚本会先调用 `devflow flow apply-selection --slug=<slug> --selection=<json> --json`，或从 picker surface 的 `actions.applySelectionFile` 读取文件版 action，把 `<file>` 替换为真实选择文件路径后执行，再渲染 `workflow_selection_result_surface` 或风险确认卡。
+
+真实本地宿主可以直接运行：
+
+```bash
+devflow flow ui --slug=<slug> --port=8787
+```
+
+它会启动一个零依赖 HTTP UI，默认监听 `127.0.0.1`，浏览器页面通过 `/api/status`、`/api/picker`、`/api/adapter/catalog`、`/api/adapter?host=codex`、`/api/diff`、`/api/explain`、`/api/apply-selection`、`/api/card`、`/api/confirm` 和 `/api/checkpoint/resolve` 调用现有 CLI JSON surface。这个 host 不读取或改写 devflow 内部文件格式，所有状态变化仍通过 `devflow status --json`、`flow picker --json`、`flow adapter --json`、`flow apply-selection --json`、`flow confirm` 和 `checkpoint resolve` 完成；`diff` / `explain` 只读展示相对默认 recipe 的变化、风险信号、verify 要求和 override 来源。页面会把 `status --json` 的 `primaryPanel` / `availableActions` 渲染成主操作区：`confirm-workflow` 会调用 `/api/confirm`，`checkpoint-decision` 会调用 `/api/checkpoint/resolve`，`open-surface` 只打开已有 picker/card/checkpoint surface；其他命令只展示，不自动执行任意 shell。`apply-selection` 返回 `workflow_policy_confirmation_surface` 时，页面会直接渲染“接受风险 / 保留当前流程”确认卡；接受风险会调用 `/api/checkpoint/resolve`，然后刷新当前 workflow。脚本集成可以使用 `devflow flow ui --slug=<slug> --port=0 --json --once` 获取一次性的 URL / endpoint surface，用于校验宿主命令是否可启动；这个 surface 会带 `schemas.adapter`、`schemas.adapterCatalog`、`schemas.selection`、`schemas.error` 和 `schemas.commandResult`，并且 `actions.adapter` 指向 `/api/adapter`，`actions.adapterCatalog` 指向 `/api/adapter/catalog`。Codex/Cursor 扩展可以加 `?host=codex` 或 `?host=cursor` 获取对应聊天卡 surface；其他宿主可以先读 `/api/adapter/catalog` 发现支持的 profile/renderMode，再用 `/api/adapter?host=windsurf&profile=cursor&render-mode=webview_or_browser` 复用 WebView 能力；也可以加 `/api/adapter?host=<host>&validate=1` 让本地 host 在转发 `flow adapter` 时启用契约校验。
+
+宿主 adapter 可以用下面的命令获取机器可读接入说明：
+
+```bash
+devflow flow adapter-catalog --json
+devflow flow adapter-catalog --json --validate-contract
+devflow flow adapter --slug=<slug> --host=codex --json
+devflow flow adapter --slug=<slug> --host=cursor --json
+devflow flow adapter --slug=<slug> --host=cli --json
+devflow flow adapter --slug=<slug> --host=windsurf --profile=cursor --json
+devflow flow adapter --slug=<slug> --host=jetbrains --render-mode=browser --json
+devflow flow adapter --slug=<slug> --host=codex --json --validate-contract
+```
+
+`codex` adapter 的 `renderMode` 是 `in_app_browser`：Codex App 聊天侧可以直接展示 `chatCard.markdown`，交互卡片在 in-app browser 中打开 `flow ui` URL。`cursor` adapter 的 `renderMode` 是 `webview_or_browser`：Cursor 扩展可以先在对话框展示同一份 `chatCard.markdown`，再把本地 URL 嵌入 WebView；没有扩展时保持 `devflow flow ui` 进程运行，在系统浏览器打开 URL。`cli` adapter 的 `renderMode` 是 `terminal_markdown`：纯终端、普通聊天窗口或不支持 WebView 的宿主可以只打印 `chatCard.markdown`，再把编辑后的 `workflow_chat_selection` POST 到 `chatSelectionApi`。CLI 非 JSON 输出也会打印这张 Markdown 卡片，方便纯终端或普通聊天窗口复制展示。
+
+其他工具不需要进入 devflow 内置白名单：`host` 只是宿主名称，允许 `windsurf`、`jetbrains`、`zed` 等安全标识；`profile` 才是能力模板。未指定 profile 时，自定义 host 默认使用 `browser` profile；如果宿主支持 WebView，可用 `--profile=cursor` 复用 WebView 能力；如果宿主只能展示终端/Markdown，可用 `--profile=cli` 或 `--render-mode=terminal_markdown`。`renderMode` 可以显式覆盖 profile 的默认值，但状态变更仍只能走 adapter surface 暴露的受控 action。`devflow flow adapter-catalog --json` 会返回 `workflow_adapter_catalog`，列出 `profiles`、`renderModes`、`hostAliases`、示例命令和 safety 模型；第三方工具应该优先用这个 catalog 做运行时发现，而不是硬编码 devflow 当前支持列表。加 `--validate-contract` 或请求 `/api/adapter/catalog?validate=1` 会用 `schemas/workflow-adapter-catalog.schema.json` 做运行时契约校验。
+
+如果当前 change 已经有 workflow draft，`chatCard.markdown` 会内联一份线性 checkbox 选择卡：按核心流程、专项检查、质量闸与交付分组列出所有 step；推荐项默认勾选，`review` / `verify` / `deliver` 等 locked gate 会标记为锁定。宿主如果支持原生交互，可以读取 `chatCard.selection.groups[].items[]` 渲染自己的 checkbox UI；用户提交后，可以把编辑后的 `workflow_chat_selection` 原样传给 `chatSelectionApi`（本地 UI host 下是 `/api/adapter/apply-selection`），或等价的 `applySelectionApi` / `devflow flow apply-selection --json`，它已经被 `workflow_selection.schema.json` 接受。聊天层不需要也不应该自己判断风险，`apply-selection` 会在取消 locked gate、降低验证覆盖或关闭风险相关检查时返回 workflow policy confirmation card。
+
+本地 UI host 会在 `/api/apply-selection` 和 `/api/adapter/apply-selection` 边界先做轻量 selection 校验：只接受最小 `{ "items": [...] }`、`workflow_picker_surface` 或 `workflow_chat_selection`，并要求每个 item 至少包含非空 `step` 和布尔 `selected`。结构错误会直接返回 `workflow_ui_error`，`code: "invalid-workflow-selection"`，不会继续调用 CLI；无效 JSON body 会返回 `code: "invalid-json-body"`。策略风险仍交给 `devflow flow apply-selection` 的 policy engine 判断。
+
+所有本地 UI host 的 JSON endpoint 都会优先透传 CLI 返回的合法 JSON surface；如果 CLI 命令失败但没有 JSON 输出，会返回 `workflow_ui_error`，`code: "devflow-command-failed"`，并带上 `command`、`exitCode`、`stdout`、`stderr`。如果 CLI 退出成功但没有返回 JSON，会返回 `code: "devflow-json-missing"`。宿主可以只根据 `type` 和 `code` 渲染错误卡，不需要解析人类文本。
+
+这份错误 surface 的 schema 真源是 `schemas/workflow-ui-error.schema.json`。每个 `workflow_ui_error` 都会带 `schema: "https://devflow.dev/schemas/workflow-ui-error.schema.json"`，宿主可以用它校验 `code`、`message`、`details` 和可选命令输出字段，再决定展示内联错误、确认卡错误态，或退回纯文本 fallback。
+
+两者都使用同一套 `/api/*` endpoint，不需要为不同 IDE 复制业务逻辑。adapter surface 会带上 `protocolVersion: workflow-adapter-surface/v1`、`features`、`host`、`profile`、`renderMode` 和 `capabilities`：宿主先看协议版本，再按 `features` 以及 `supportsChatCard`、`supportsChatSelection`、`supportsEmbeddedUi`、`supportsApplySelection`、`supportsCheckpointResolve`、`supportsConfirm` 等能力决定是渲染原生 checkbox、嵌入本地 UI，还是只展示 Markdown fallback。当前 feature 包括 `catalog-discovery`、`chat-card`、`chat-selection`、`embedded-ui`、`read-only-diff`、`read-only-explain`、`checkpoint-resolve` 和 `controlled-confirm`；后续新增能力会优先加 feature 标识，而不是立刻更换协议版本。`capabilities.errorSchema` 和 `capabilities.commandResultSchema` 会分别指向 `workflow_ui_error` 与 `workflow_ui_command_result` 的 schema，方便宿主统一处理 `/api/*` 成功命令结果和错误卡。adapter surface 的 `actions` 会显式列出 `statusApi`、`pickerApi`、`diffApi`、`explainApi`、`applySelectionApi`、`chatSelectionApi`、`cardApi`、`checkpointResolveApi` 和 `confirmApi`；其中 `diffApi` / `explainApi` 是只读说明，`applySelectionApi` / `chatSelectionApi` / `checkpointResolveApi` / `confirmApi` 是受控状态变更入口。`chatCard` 只承载可渲染的展示内容，不直接修改 workflow；Codex/Cursor 或其他宿主如果要做原生按钮，应该把按钮映射到这些受控 action，而不是在聊天层执行任意 shell。
+
+这份宿主接入协议的 schema 真源是 `schemas/workflow-adapter-surface.schema.json`。插件侧可以用它校验 `workflow_adapter_surface`、`workflow_chat_card` 和 `workflow_chat_selection` 三层结构；`capabilities.schema` / `capabilities.selectionSchema` 会显式指向 adapter surface 和用户选择输入的 schema。用户编辑后的 `workflow_chat_selection` 则继续由 `schemas/workflow-selection.schema.json` 约束并提交给 `chatSelectionApi`。
+
+CLI 侧也提供轻量运行时校验：加 `--validate-contract` 时，`flow adapter` 会在输出前用内置 schema 子集校验 adapter surface；成功时仍只输出原 JSON，失败时阻断并报告具体字段路径，例如 `capabilities.supportsConfirm`。
+
+adapter surface 还有一组 snapshot fixture：`test/fixtures/workflow-adapter-surfaces/{codex,cursor,cli,browser}.json`。它们固定了 `protocolVersion`、`renderMode`、`capabilities`、`actions`、`chatCard.selection` 和 host-specific instructions；修改 adapter 协议或宿主行为时，应同步更新这些 fixture，并确认是有意变更。
+
+为了让宿主接入更具体，仓库提供了可复用 SDK 和最小 client 示例。npm 包的稳定入口是 `@chenguangyao/devflow-kit/client/workflow-adapter`，仓库内源码入口是 `src/client/workflow-adapter-client.js`；它提供 `ensureCompatibleCatalog`、`recommendAdapterProfile`、`ensureCompatibleSurface`、`buildSelectionPayload`、`submitSelection`、`renderCatalogExample`、`renderHostExample` 和 `renderSurfaceMarkdown`。脚本 `scripts/workflow-adapter-client-example.js` 只是这个 SDK 的 CLI 包装。
+
+```bash
+devflow flow adapter-catalog --json --validate-contract > /tmp/devflow-adapter-catalog.json
+node scripts/workflow-adapter-client-example.js --catalog-file=/tmp/devflow-adapter-catalog.json --host=windsurf
+devflow flow adapter --slug=<slug> --host=codex --json --validate-contract > /tmp/devflow-adapter.json
+node scripts/workflow-adapter-client-example.js --surface-file=/tmp/devflow-adapter.json --host=codex
+node scripts/workflow-adapter-client-example.js --surface-file=/tmp/devflow-adapter.json --host=cursor
+node scripts/workflow-adapter-client-example.js --surface-file=/tmp/devflow-adapter.json --host=cli
+node scripts/workflow-adapter-client-example.js --surface-file=/tmp/devflow-adapter.json --dry-run --steps=requirement,design,review,verify,deliver
+node scripts/workflow-adapter-client-example.js --surface-file=/tmp/devflow-adapter.json --submit --steps=requirement,design,review,verify,deliver
+```
+
+这个示例只做宿主侧该做的事：读取 `workflow_adapter_catalog` 推荐 host 对应的 `profile` / `renderMode` 和 adapter 命令；检查 adapter surface 的 `protocolVersion` 和 `capabilities`；展示 `chatCard.markdown`；基于 `chatCard.selection` 生成 `workflow_chat_selection` payload，并把提交目标固定到 `actions.chatSelectionApi`。默认只打印说明；`--dry-run` 只输出将要 POST 的 URL 和 payload，不发网络请求；`--submit` 才会 POST 到本地 UI host。它不会直接改 `state.json`，也不会绕过 policy engine；真正的状态变更仍由 `/api/adapter/apply-selection` / `devflow flow apply-selection` 完成。提交失败时，示例会把 `workflow_ui_error.code` 和 `message` 放进错误信息，同时保留完整 `response`，方便 Codex/Cursor 扩展渲染错误卡。
+
+宿主模板放在 `examples/adapter-hosts/`：`terminal-host.js` 展示纯终端/Markdown 接法，`webview-host.html` 展示 WebView 如何先读 catalog 再嵌入本地 UI，`generic-agent-host.md` 给未知 IDE/Agent 工具一份接入检查表。三个模板都遵守同一条边界：不执行卡片里的任意 shell，所有 mutation 都通过 devflow-controlled action。
+
+adapter 端到端 smoke 固定在 `test/workflow-ui-host.test.js`：它通过 `/api/adapter?host=codex&validate=1` 获取并校验 surface，再用 `scripts/workflow-adapter-client-example.js` 把用户选择提交到 `chatSelectionApi`，最后断言本地 UI host 转发到 `devflow flow apply-selection`。这条测试覆盖 Codex / Cursor / CLI 宿主最关键的闭环：推荐 skill 展示、用户勾选、受控提交、policy engine 接管。高风险路径也有独立 smoke：第一次提交返回 `workflow_policy_confirmation_surface`，宿主调用 `/api/checkpoint/resolve` 接受风险后，再重试同一份 chat selection，确认风险确认不会绕过 policy engine，也不会让宿主直接改 state。
+
+浏览器级 smoke 可以通过下面的 opt-in 脚本执行：
+
+```bash
+npm run test:workflow-ui-browser
+```
+
+这个脚本只使用本地已安装的 Playwright，不会自动下载依赖。没有 Playwright 时输出 `[skip]` 并退出成功；有 Playwright 时会启动临时 `flow ui` host，真实打开浏览器页面，点击“应用选择”和“确认 workflow”，验证主要 UI 交互链路。
 
 picker 只负责展示候选和推荐，不直接保存用户选择。用户确认推荐流程时优先运行 `devflow flow card --slug=<slug> --json` 再执行 `devflow flow confirm --slug=<slug>`；脚本仍可直接运行 `devflow flow check --slug=<slug> --json` 做底层预检。如果用户在选项卡里勾选额外专项 skill 或取消 optional step，UI 可以把选择结果交给：
 
 ```bash
 devflow flow apply-selection --slug=<slug> --selection='{"items":[...]}' --json
+# 或
+devflow flow apply-selection --slug=<slug> --selection-file=selection.json --json
 ```
 
+`--selection` / `--selection-file` 既可以提供最小 `{ "items": [...] }`，也可以提供前端修改后的完整 `workflow_picker_surface`。完整 surface 会从 `groups[].items[]` 展平成选择项，因此 UI 可以直接把用户勾选后的 picker JSON 回传给 CLI。脚本或 IDE 集成更适合用 `--selection-file`，避免在 shell 参数里转义大段 JSON。
+
+宿主集成时不要自己拼 `apply-selection` 命令。推荐流程是：
+
+1. 调用 `devflow flow picker --slug=<slug> --json`。
+2. 用 `groups[].items[]` 渲染线性选项卡，把推荐项自动勾上，把 `locked=true` 的 gate 渲染为不可取消。
+3. 用户调整后，把修改后的 picker surface 或最小 `{ "items": [...] }` 写入临时 JSON 文件。
+4. 读取 `actions.applySelectionFile`，将命令中的 `<file>` 替换为临时文件路径，用参数数组执行该 action，而不是通过 shell 拼接字符串。
+5. 根据返回的 `workflow_selection_result_surface` 或 `workflow_policy_confirmation_surface` 渲染结果面板或风险确认卡。
+
 picker 的 `actions` 会返回 UI 可直接使用的入口：
 
 - `card`：打开统一 workflow 确认面，命令为 `devflow flow card --slug=<slug> --json`。
 - `check`：执行底层预检，适合脚本或调试入口。
 - `applySelection`：提交选项卡勾选结果。
+- `applySelectionFile`：提交保存在文件中的选项卡勾选结果，推荐给 IDE / Web UI 使用。
 - `confirm`：确认当前 workflow 快照。
 - `suggest`：基于自然语言意图生成编排建议。
 
-`apply-selection` 会把安全选择转换成 `flow add-step` / `flow disable-step` 等 draft override，并复用 CLI 的 policy engine。添加检查型 step、禁用无风险 optional step 会直接写入 draft；取消 `review` / `verify` / `deliver` 这类 locked gate，或禁用风险相关专项检查时，会生成 `workflow_policy` checkpoint 并保持 workflow 不变。成功后返回 `nextAction: "devflow flow card --slug=<slug> --json"`，调用方再进入统一确认面。
+`apply-selection` 会把安全选择转换成 `flow add-step` / `flow disable-step` 等 draft override，并复用 CLI 的 policy engine。添加检查型 step、禁用无风险 optional step 会直接写入 draft；取消 `review` / `verify` / `deliver` 这类 locked gate，或禁用风险相关专项检查时，会生成 `workflow_policy` checkpoint 并保持 workflow 不变。成功响应的 schema 真源是 `schemas/workflow-selection-result.schema.json`，返回 `type: "workflow_selection_result_surface"`、`diff`、`actions` 和 `nextAction: "devflow flow card --slug=<slug> --json"`；它只表示安全选择已经写入 draft，不代表 workflow 已 confirm。调用方可以先展示相对 base recipe 的差异，再进入统一确认面。
 
 如果 `apply-selection --json` 触发了风险确认，它不会输出人类文本，而是返回 `workflow_policy_confirmation_surface`，供 UI 直接渲染“保留当前流程 / 接受风险”确认卡：
 
@@ -294,6 +375,7 @@ devflow flow set-verify --slug=<slug> --reports=unit,integration,smoke,self-test
 devflow flow diff --slug=<slug>
 devflow flow picker --slug=<slug> --json
 devflow flow apply-selection --slug=<slug> --selection='{"items":[...]}' --json
+devflow flow apply-selection --slug=<slug> --selection-file=selection.json --json
 devflow flow explain --slug=<slug>
 devflow flow card --slug=<slug> --json
 devflow flow check --slug=<slug> --json
@@ -502,6 +584,7 @@ devflow flow card --slug=<slug> --json
   "actions": {
     "picker": "devflow flow picker --slug=<slug> --json",
     "applySelection": "devflow flow apply-selection --slug=<slug> --selection='<json>' --json",
+    "applySelectionFile": "devflow flow apply-selection --slug=<slug> --selection-file=<file> --json",
     "check": "devflow flow check --slug=<slug> --json",
     "confirm": "devflow flow confirm --slug=<slug>"
   },
@@ -556,6 +639,8 @@ devflow ingest "<url-or-file>" --project-root=<repo>
 devflow checkpoint resolve --id=<problem-card-id> --decision=accept
 devflow flow picker --slug=<slug> --json
 devflow flow apply-selection --slug=<slug> --selection='<json>' --json
+# IDE / Web UI 推荐读取 picker.actions.applySelectionFile 后提交选择文件
+devflow flow apply-selection --slug=<slug> --selection-file=selection.json --json
 devflow flow explain --slug=<slug>
 devflow flow card --slug=<slug> --json
 devflow flow confirm --slug=<slug>
@@ -584,6 +669,8 @@ IDE / Web UI 可以调用 `devflow status --slug=<slug> --json` 作为当前 cha
 - `blockingReason`：如果当前需要用户确认或存在硬阻塞，给出结构化原因；没有阻塞时为 `null`。
 - `availableActions`：可直接渲染的按钮列表，包含 `id`、`label`、`command`、`primary`、`danger`、`requiresReason`。
 
+`workflow.actions` 会带上 `picker`、`applySelection`、`applySelectionFile`、`card`、`check`、`confirm`，方便 IDE / Web UI 从 status 页面直接打开选项卡、提交选择文件或进入确认卡，不需要自己拼 `flow apply-selection` 命令。
+
 这份 JSON contract 的 schema 真源是 `schemas/status-surface.schema.json`。UI 集成或插件适配时，应以该 schema 作为字段兼容边界；新增字段可以向后兼容追加，但 `primaryPanel` / `blockingReason` / `availableActions` 的核心字段不应随意改名。
 典型输出样例固定在 `test/fixtures/status-surfaces/*.json`，覆盖 workflow draft、pending checkpoint、review blocked、verify missing reports 和 confirmed current step。修改 `status --json` UI 字段时，应同步更新这些 golden snapshots。
 
@@ -613,8 +700,12 @@ IDE / Web UI 可以调用 `devflow status --slug=<slug> --json` 作为当前 cha
     "currentStep": "requirement",
     "check": { "ok": false },
     "actions": {
+      "picker": "devflow flow picker --slug=<slug> --json",
+      "applySelection": "devflow flow apply-selection --slug=<slug> --selection='<json>' --json",
+      "applySelectionFile": "devflow flow apply-selection --slug=<slug> --selection-file=<file> --json",
       "card": "devflow flow card --slug=<slug> --json",
-      "picker": "devflow flow picker --slug=<slug> --json"
+      "check": "devflow flow check --slug=<slug> --json",
+      "confirm": "devflow flow confirm --slug=<slug>"
     }
   },
   "pendingCheckpoint": { "type": "workflow_policy" },

package/docs/workflow-ui-prototype.html

@@ -29,11 +29,17 @@
     small { color: var(--muted); font-size: 12px; line-height: 1.35; }
     li p { color: var(--warn); font-size: 12px; margin: 0; }
     .command-row, .actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 14px; align-items: center; }
+    .result { border-color: #95c9bf; background: #f5fbf9; }
+    .result-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px; }
+    .result-grid div { display: grid; gap: 5px; border: 1px solid var(--line); border-radius: 8px; background: white; padding: 12px; min-height: 72px; }
+    .result-grid strong { overflow-wrap: anywhere; }
+    .policy { border-color: #e3b16f; background: #fffaf3; }
+    .risk-box { display: grid; gap: 4px; margin-top: 12px; border: 1px solid #e3b16f; border-radius: 8px; background: white; padding: 12px; }
     .timeline { display: grid; grid-template-columns: repeat(8, minmax(96px, 1fr)); gap: 8px; overflow-x: auto; padding-bottom: 4px; }
     .timeline li { min-width: 96px; border: 1px solid var(--line); border-radius: 8px; padding: 10px; background: var(--panel); display: grid; gap: 5px; }
     .timeline span { display: grid; place-items: center; width: 22px; height: 22px; border-radius: 999px; background: var(--accent); color: white; font-size: 12px; font-weight: 700; }
     button { border: 0; border-radius: 6px; padding: 8px 12px; background: var(--accent); color: white; font-weight: 700; }
-    @media (max-width: 860px) { .toolbar { align-items: start; flex-direction: column; } .groups { grid-template-columns: 1fr; } .timeline { grid-template-columns: repeat(4, minmax(96px, 1fr)); } }
+    @media (max-width: 860px) { .toolbar { align-items: start; flex-direction: column; } .groups, .result-grid { grid-template-columns: 1fr; } .timeline { grid-template-columns: repeat(4, minmax(96px, 1fr)); } }
   </style>
 </head>
 <body>
@@ -216,6 +222,32 @@
         <code>devflow flow card --slug=snapshot-picker-risk --json</code>
       </div>
     </section>
+    <section class="surface result" data-surface="workflow-selection-result" aria-label="Workflow selection result">
+      <div class="surface-head"><h2>选择已应用</h2><span>workflow_selection_result_surface / ok</span></div>
+      <div class="result-grid">
+        <div>
+          <small>新增</small>
+          <strong>frontend-quality</strong>
+        </div>
+        <div>
+          <small>禁用</small>
+          <strong>archive</strong>
+        </div>
+        <div>
+          <small>移动</small>
+          <strong>-</strong>
+        </div>
+        <div>
+          <small>验证报告</small>
+          <strong>-</strong>
+        </div>
+      </div>
+      <div class="actions">
+        <button type="button">continue</button>
+        <code>devflow flow card --slug=snapshot-selection-result --json</code>
+        <code>devflow flow picker --slug=snapshot-selection-result --json</code>
+      </div>
+    </section>
     <section class="surface confirm" data-surface="workflow-card" aria-label="Workflow confirmation card">
       <div class="surface-head"><h2>确认卡</h2><span>ok / draft</span></div>
       <ol class="timeline">
@@ -266,6 +298,19 @@
         <code>devflow flow picker --slug=snapshot-card-safe --json</code>
       </div>
     </section>
+    <section class="surface policy" data-surface="workflow-policy-card" aria-label="Workflow policy confirmation card">
+      <div class="surface-head"><h2>确认 workflow 风险</h2><span>workflow_policy_confirm / pending</span></div>
+      <p>这个 workflow 调整会提高风险，是否接受本次 change 的风险变化？</p>
+      <div class="risk-box">
+        <strong>禁用 required workflow step: verify</strong>
+        <small>workflow_policy-1234abcd · workflow</small>
+      </div>
+      <div class="actions">
+        <button type="button">accept-risk</button>
+        <code>devflow checkpoint resolve --id=workflow_policy-1234abcd --decision=accept-risk</code>
+        <code>devflow status --slug=snapshot-policy-risk</code>
+      </div>
+    </section>
   </main>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenguangyao/devflow-kit",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Independent dev workflow kit fusing arb-workflow-kit, superpowers and OpenSpec ideas. Wiki-first entry, change-folder model, worktree-swarm apply, 3-round review, multi-IDE adapter, pluggable providers.",
   "bin": {
     "devflow": "bin/devflow.js",
@@ -9,6 +9,7 @@
   "main": "src/cli/index.js",
   "files": [
     "bin/",
+    "client/",
     "src/",
     "scripts/",
     "schemas/",
@@ -21,6 +22,7 @@
   "scripts": {
     "start": "node bin/devflow.js",
     "test": "node --test \"test/**/*.test.js\"",
+    "test:workflow-ui-browser": "DEVFLOW_RUN_BROWSER_E2E=1 node scripts/workflow-ui-browser-smoke.js",
     "test:watch": "node --test --watch \"test/**/*.test.js\"",
     "pack:dry": "npm pack --dry-run",
     "lint": "echo 'lint not configured yet'",
@@ -45,8 +47,5 @@
   ],
   "author": "chenguangyao",
   "license": "MIT",
-  "type": "commonjs",
-  "dependencies": {
-    "@chenguangyao/devflow-kit": "^0.1.42"
-  }
+  "type": "commonjs"
 }

package/schemas/status-surface.schema.json

@@ -112,7 +112,12 @@
       },
       "additionalProperties": true
     },
-    "workflow": { "type": ["object", "null"] },
+    "workflow": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "#/definitions/workflow" }
+      ]
+    },
     "pendingCheckpoint": { "type": ["object", "null"] },
     "checkpointConfirmationCard": { "type": ["object", "null"] },
     "primaryPanel": {
@@ -183,6 +188,33 @@
   },
   "additionalProperties": true,
   "definitions": {
+    "workflow": {
+      "type": "object",
+      "required": ["status", "baseRecipe", "currentStep", "nextStep", "overrides", "check", "actions"],
+      "properties": {
+        "status": { "type": ["string", "null"] },
+        "baseRecipe": { "type": ["object", "null"] },
+        "currentStep": { "type": ["string", "null"] },
+        "nextStep": { "type": ["string", "null"] },
+        "overrides": { "type": "object" },
+        "check": { "type": ["object", "null"] },
+        "actions": { "$ref": "#/definitions/workflowActions" }
+      },
+      "additionalProperties": true
+    },
+    "workflowActions": {
+      "type": "object",
+      "required": ["picker", "applySelection", "applySelectionFile", "card", "check", "confirm"],
+      "properties": {
+        "picker": { "type": "string" },
+        "applySelection": { "type": "string" },
+        "applySelectionFile": { "type": "string" },
+        "card": { "type": "string" },
+        "check": { "type": "string" },
+        "confirm": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
     "artifact": {
       "type": "object",
       "required": ["name", "path", "exists"],

package/schemas/workflow-adapter-catalog.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devflow.dev/schemas/workflow-adapter-catalog.schema.json",
+  "title": "devflow workflow adapter catalog",
+  "description": "Machine-readable catalog for workflow adapter host profiles and render modes.",
+  "type": "object",
+  "required": [
+    "type",
+    "protocolVersion",
+    "schema",
+    "defaults",
+    "profiles",
+    "renderModes",
+    "hostAliases",
+    "examples",
+    "safety"
+  ],
+  "properties": {
+    "type": { "const": "workflow_adapter_catalog" },
+    "protocolVersion": { "const": "workflow-adapter-surface/v1" },
+    "schema": { "const": "https://devflow.dev/schemas/workflow-adapter-catalog.schema.json" },
+    "features": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "defaults": {
+      "type": "object",
+      "required": ["customHostProfile", "customHostRenderMode", "mutationModel"],
+      "properties": {
+        "customHostProfile": { "enum": ["browser"] },
+        "customHostRenderMode": { "enum": ["browser"] },
+        "mutationModel": { "const": "devflow-controlled" }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/profile" }
+    },
+    "renderModes": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/renderMode" }
+    },
+    "hostAliases": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "examples": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/example" }
+    },
+    "safety": {
+      "type": "object",
+      "required": ["arbitraryShell", "mutationModel", "readOnlyActions", "mutationActions"],
+      "properties": {
+        "arbitraryShell": { "const": false },
+        "mutationModel": { "const": "devflow-controlled" },
+        "readOnlyActions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "mutationActions": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "profile": {
+      "type": "object",
+      "required": ["id", "label", "defaultRenderMode", "description", "recommendedHosts"],
+      "properties": {
+        "id": { "enum": ["codex", "cursor", "browser", "cli"] },
+        "label": { "type": "string" },
+        "defaultRenderMode": { "enum": ["in_app_browser", "webview_or_browser", "browser", "terminal_markdown"] },
+        "description": { "type": "string" },
+        "recommendedHosts": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "renderMode": {
+      "type": "object",
+      "required": ["id", "label", "supportsEmbeddedUi", "description"],
+      "properties": {
+        "id": { "enum": ["in_app_browser", "webview_or_browser", "browser", "terminal_markdown"] },
+        "label": { "type": "string" },
+        "supportsEmbeddedUi": { "type": "boolean" },
+        "description": { "type": "string" }
+      }
+    },
+    "example": {
+      "type": "object",
+      "required": ["host", "profile", "renderMode", "command"],
+      "properties": {
+        "host": { "type": "string" },
+        "profile": { "enum": ["codex", "cursor", "browser", "cli"] },
+        "renderMode": { "enum": ["in_app_browser", "webview_or_browser", "browser", "terminal_markdown"] },
+        "command": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/workflow-adapter-surface.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devflow.dev/schemas/workflow-adapter-surface.schema.json",
+  "title": "devflow workflow adapter surface",
+  "description": "Machine-readable surface returned by devflow flow adapter --json for Codex/Cursor/browser/CLI and custom host integration.",
+  "type": "object",
+  "required": [
+    "type",
+    "protocolVersion",
+    "host",
+    "profile",
+    "slug",
+    "renderMode",
+    "url",
+    "capabilities",
+    "actions",
+    "chatCard",
+    "instructions",
+    "fallbackMarkdown"
+  ],
+  "properties": {
+    "type": { "const": "workflow_adapter_surface" },
+    "protocolVersion": { "const": "workflow-adapter-surface/v1" },
+    "host": { "type": "string" },
+    "profile": { "enum": ["codex", "cursor", "browser", "cli"] },
+    "slug": { "type": "string" },
+    "renderMode": { "enum": ["in_app_browser", "webview_or_browser", "browser", "terminal_markdown"] },
+    "url": { "type": "string" },
+    "features": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "capabilities": { "$ref": "#/definitions/capabilities" },
+    "actions": { "$ref": "#/definitions/actionMap" },
+    "chatCard": { "$ref": "#/definitions/chatCard" },
+    "instructions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "fallbackMarkdown": { "type": "string" }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "capabilities": {
+      "type": "object",
+      "required": [
+        "schema",
+        "selectionSchema",
+        "errorSchema",
+        "commandResultSchema",
+        "host",
+        "profile",
+        "renderMode",
+        "supportsChatCard",
+        "supportsChatSelection",
+        "supportsNativeCheckboxes",
+        "supportsEmbeddedUi",
+        "supportsReadOnlyDiff",
+        "supportsReadOnlyExplain",
+        "supportsApplySelection",
+        "supportsCheckpointResolve",
+        "supportsConfirm",
+        "mutationModel"
+      ],
+      "properties": {
+        "schema": { "const": "https://devflow.dev/schemas/workflow-adapter-surface.schema.json" },
+        "selectionSchema": { "const": "https://devflow.dev/schemas/workflow-selection.schema.json" },
+        "errorSchema": { "const": "https://devflow.dev/schemas/workflow-ui-error.schema.json" },
+        "commandResultSchema": { "const": "https://devflow.dev/schemas/workflow-ui-command-result.schema.json" },
+        "host": { "type": "string" },
+        "profile": { "enum": ["codex", "cursor", "browser", "cli"] },
+        "renderMode": { "enum": ["in_app_browser", "webview_or_browser", "browser", "terminal_markdown"] },
+        "features": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "supportsChatCard": { "type": "boolean" },
+        "supportsChatSelection": { "type": "boolean" },
+        "supportsNativeCheckboxes": { "type": "boolean" },
+        "supportsEmbeddedUi": { "type": "boolean" },
+        "supportsReadOnlyDiff": { "type": "boolean" },
+        "supportsReadOnlyExplain": { "type": "boolean" },
+        "supportsApplySelection": { "type": "boolean" },
+        "supportsCheckpointResolve": { "type": "boolean" },
+        "supportsConfirm": { "type": "boolean" },
+        "mutationModel": { "const": "devflow-controlled" }
+      },
+      "additionalProperties": true
+    },
+    "actionMap": {
+      "type": "object",
+      "required": [
+        "startUi",
+        "startUiJson",
+        "statusApi",
+        "pickerApi",
+        "diffApi",
+        "explainApi",
+        "applySelectionApi",
+        "chatSelectionApi",
+        "cardApi",
+        "checkpointResolveApi",
+        "confirmApi"
+      ],
+      "properties": {
+        "startUi": { "type": "string" },
+        "startUiJson": { "type": "string" },
+        "statusApi": { "type": "string" },
+        "pickerApi": { "type": "string" },
+        "diffApi": { "type": "string" },
+        "explainApi": { "type": "string" },
+        "applySelectionApi": { "type": "string" },
+        "chatSelectionApi": { "type": "string" },
+        "cardApi": { "type": "string" },
+        "checkpointResolveApi": { "type": "string" },
+        "confirmApi": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "chatCard": {
+      "type": "object",
+      "required": [
+        "type",
+        "format",
+        "title",
+        "selection",
+        "markdown"
+      ],
+      "properties": {
+        "type": { "const": "workflow_chat_card" },
+        "format": { "const": "markdown" },
+        "title": { "type": "string" },
+        "selection": { "$ref": "#/definitions/chatSelection" },
+        "markdown": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "chatSelection": {
+      "type": "object",
+      "required": ["type", "layout", "groups"],
+      "properties": {
+        "type": { "const": "workflow_chat_selection" },
+        "layout": { "const": "linear-checkboxes" },
+        "groups": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/chatSelectionGroup" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "chatSelectionGroup": {
+      "type": "object",
+      "required": ["id", "label", "items"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/chatSelectionItem" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "chatSelectionItem": {
+      "type": "object",
+      "required": [
+        "step",
+        "skill",
+        "label",
+        "selected",
+        "recommended",
+        "locked",
+        "required",
+        "installed",
+        "reason",
+        "command"
+      ],
+      "properties": {
+        "step": { "type": "string" },
+        "skill": { "type": "string" },
+        "label": { "type": "string" },
+        "selected": { "type": "boolean" },
+        "recommended": { "type": "boolean" },
+        "locked": { "type": "boolean" },
+        "required": { "type": "boolean" },
+        "installed": { "type": "boolean" },
+        "reason": { "type": ["string", "null"] },
+        "command": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    }
+  }
+}