@chenguangyao/devflow-kit 0.1.43 → 0.1.44

package/scripts/workflow-ui-browser-smoke.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const path = require('node:path');
+const workflowUiHost = require('../src/core/workflow-ui-host.js');
+
+function detectPlaywright() {
+  try {
+    return require('playwright');
+  } catch (_) {
+    return null;
+  }
+}
+
+async function runWorkflowUiBrowserSmoke(options = {}) {
+  const shouldRun = options.run === true || process.env.DEVFLOW_RUN_BROWSER_E2E === '1';
+  if (!shouldRun) {
+    return { status: 'skipped', reason: 'browser smoke not requested' };
+  }
+
+  const playwright = options.playwright || detectPlaywright();
+  if (!playwright) {
+    return { status: 'skipped', reason: 'Playwright is not installed' };
+  }
+
+  const calls = [];
+  const host = await workflowUiHost.createWorkflowUiHost({
+    root: options.root || process.cwd(),
+    slug: options.slug || 'browser-smoke',
+    port: 0,
+    binPath: options.binPath || path.resolve(__dirname, '..', 'bin', 'devflow.js'),
+    execFile: options.execFile || fakeExecFile(calls),
+  });
+
+  let browser;
+  try {
+    browser = await playwright.chromium.launch({ headless: options.headless !== false });
+    const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+    await page.goto(host.url);
+    await page.getByText('Workflow 编排').waitFor();
+    await page.getByText('编排说明').waitFor();
+    await page.getByText('frontend_change', { exact: false }).waitFor();
+
+    await page.getByRole('button', { name: '应用选择' }).click();
+    await page.getByText('选择已应用').waitFor();
+
+    await page.getByRole('button', { name: '确认 workflow' }).click();
+    await page.getByText('命令已执行').waitFor();
+
+    return {
+      status: 'passed',
+      url: host.url,
+      calls: calls.map((call) => call.args.slice(1).join(' ')),
+    };
+  } finally {
+    if (browser) await browser.close();
+    await host.close();
+  }
+}
+
+function fakeExecFile(calls) {
+  return (cmd, args, execOptions, cb) => {
+    calls.push({ cmd, args, execOptions });
+    const joined = args.join(' ');
+    if (joined.includes('status')) {
+      cb(null, JSON.stringify({
+        type: 'change_status_surface',
+        slug: 'browser-smoke',
+        phase: 'workflow',
+        workflow: { status: 'draft', currentStep: null, nextStep: 'requirement' },
+        primaryPanel: {
+          type: 'workflow_confirm',
+          title: '确认本次 workflow',
+          status: 'needs_input',
+          actionIds: ['confirm-workflow'],
+        },
+        availableActions: [
+          { id: 'confirm-workflow', label: '确认 workflow', command: 'devflow flow confirm --slug=browser-smoke', kind: 'workflow', primary: true },
+        ],
+        blockingReason: { message: 'change workflow is not confirmed' },
+        nextAction: 'devflow flow confirm --slug=browser-smoke',
+      }), '');
+      return;
+    }
+    if (joined.includes('flow picker')) {
+      cb(null, JSON.stringify({
+        type: 'workflow_picker_surface',
+        layout: 'linear-grouped',
+        baseRecipe: { id: 'standard', label: '标准研发' },
+        status: 'draft',
+        groups: [
+          {
+            id: 'quality',
+            label: '质量检查',
+            items: [
+              { step: 'frontend-quality', skill: 'frontend-quality', selected: true, recommended: true, optional: true, reason: 'frontend_change risk signal' },
+            ],
+          },
+        ],
+        actions: { applySelectionFile: 'devflow flow apply-selection --slug=browser-smoke --selection-file=<file> --json' },
+      }), '');
+      return;
+    }
+    if (joined.includes('flow card')) {
+      cb(null, JSON.stringify({
+        type: 'workflow_confirmation_surface',
+        ok: true,
+        status: 'draft',
+        confirmationCard: {
+          steps: [
+            { id: 'requirement', skill: 'requirement-analysis' },
+            { id: 'frontend-quality', skill: 'frontend-quality' },
+            { id: 'review', skill: 'code-review' },
+            { id: 'verify', skill: 'verify' },
+            { id: 'deliver', skill: 'deliver' },
+          ],
+          primaryAction: { id: 'confirm', command: 'devflow flow confirm --slug=browser-smoke' },
+          secondaryActions: [],
+        },
+      }), '');
+      return;
+    }
+    if (joined.includes('flow diff')) {
+      cb(null, JSON.stringify({
+        added: ['frontend-quality'],
+        disabled: [],
+        moved: [],
+        verifyReports: ['self-test.md'],
+      }), '');
+      return;
+    }
+    if (joined.includes('flow explain')) {
+      cb(null, JSON.stringify({
+        verify: { requiredReports: ['unit-test.md', 'self-test.md'], reason: 'frontend change needs self test' },
+        openRiskSignals: [{ type: 'frontend_change', reason: 'UI touched' }],
+        overrides: [{ type: 'add-step', step: 'frontend-quality', reason: 'frontend change' }],
+      }), '');
+      return;
+    }
+    if (joined.includes('flow apply-selection')) {
+      cb(null, JSON.stringify({
+        type: 'workflow_selection_result_surface',
+        ok: true,
+        added: ['frontend-quality'],
+        disabled: [],
+        skipped: [],
+        diff: { added: ['frontend-quality'], disabled: [], moved: [], verifyReports: ['self-test.md'] },
+        nextAction: 'devflow flow card --slug=browser-smoke --json',
+      }), '');
+      return;
+    }
+    if (joined.includes('flow confirm')) {
+      cb(null, '[ok] workflow confirmed: currentStep=requirement\n', '');
+      return;
+    }
+    cb(new Error(`unexpected args: ${joined}`), '', '');
+  };
+}
+
+if (require.main === module) {
+  runWorkflowUiBrowserSmoke({ run: true })
+    .then((result) => {
+      const prefix = result.status === 'passed' ? '[ok]' : '[skip]';
+      console.log(`${prefix} workflow UI browser smoke: ${result.reason || result.url}`);
+      if (result.status !== 'passed' && process.env.DEVFLOW_BROWSER_E2E_REQUIRED === '1') process.exitCode = 1;
+    })
+    .catch((e) => {
+      console.error(`[error] workflow UI browser smoke: ${e.stack || e.message}`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = {
+  detectPlaywright,
+  runWorkflowUiBrowserSmoke,
+};

package/skills/df-orchestrator/SKILL.md

@@ -169,7 +169,7 @@ devflow new <slug> --project-root=/path/to/primary
 
 ## Phase 顺序(硬约束)
 
-> 新流程优先使用入口命令自动生成的 workflow draft,再通过 `devflow flow picker` / `devflow flow apply-selection` / `devflow flow card` / `devflow flow confirm` 完成选项卡确认并冻结 `state.workflow.steps`。`flow check` 仍保留给脚本做预检。下面的 phase 顺序是内置 recipe 的默认展开形态,不是所有需求都必须硬走的唯一链路。`level` 只影响验证强度;实际 skill 编排由 workflow recipe 决定。完整说明见 `docs/workflow-orchestration.md`。
+> 新流程优先使用入口命令自动生成的 workflow draft,再通过 `devflow flow picker` / `devflow flow apply-selection` / `devflow flow card` / `devflow flow confirm` 完成选项卡确认并冻结 `state.workflow.steps`。IDE / Web UI 调整勾选时优先使用文件版 `devflow flow apply-selection --selection-file=<file> --json`。`flow check` 仍保留给脚本做预检。下面的 phase 顺序是内置 recipe 的默认展开形态,不是所有需求都必须硬走的唯一链路。`level` 只影响验证强度;实际 skill 编排由 workflow recipe 决定。完整说明见 `docs/workflow-orchestration.md`。
 
 **入口后的 workflow 确认：**
 ```
@@ -182,6 +182,7 @@ new / ingest 自动生成 workflow draft
 devflow flow picker --json
       ↓
 用户如调整勾选: devflow flow apply-selection --selection='<json>' --json
+IDE / Web UI 推荐: devflow flow apply-selection --selection-file=<file> --json
       ↓
 devflow flow card --json
       ↓

package/skills/df-orchestrator/references/workflow-state-machine.md

@@ -6,10 +6,10 @@ workflow step / phase 之间怎么走、哪些转移合法、哪些必须回退
 
 ## 规范 workflow 模型
 
-新 change 优先由 `devflow new` / `devflow ingest` 自动生成 `state.workflow` draft,再通过 `devflow flow picker --json` → 可选 `devflow flow apply-selection --selection='<json>' --json` → `devflow flow card --json` → `devflow flow confirm` 冻结 `state.workflow.steps`。`devflow flow check --json` 仍保留给脚本做预检。如果自动 draft 失败,再退回 `devflow flow recommend` → `devflow flow draft` 的手动补救路径。orchestrator 决定下一步时:
+新 change 优先由 `devflow new` / `devflow ingest` 自动生成 `state.workflow` draft,再通过 `devflow flow picker --json` → 可选 `devflow flow apply-selection --selection='<json>' --json` 或 IDE / Web UI 推荐的 `devflow flow apply-selection --selection-file=<file> --json` → `devflow flow card --json` → `devflow flow confirm` 冻结 `state.workflow.steps`。`devflow flow check --json` 仍保留给脚本做预检。如果自动 draft 失败,再退回 `devflow flow recommend` → `devflow flow draft` 的手动补救路径。orchestrator 决定下一步时:
 
 1. 若 `state.workflow.status = confirmed`,按 `state.workflow.steps` 中未完成 / 未禁用的 step 推进。
-2. 若 `state.workflow.status = draft`,先展示 `devflow flow picker --json` 让用户看到线形选项卡；如果用户调整勾选,执行 `devflow flow apply-selection --selection='<json>' --json`；然后展示 `devflow flow explain` 和 `devflow flow card --json`,只有确认面 `ok=true` 时才展示 `devflow flow confirm` 下一步卡片,不得直接进入 requirement/design/apply。
+2. 若 `state.workflow.status = draft`,先展示 `devflow flow picker --json` 让用户看到线形选项卡；如果用户调整勾选,CLI 可执行 `devflow flow apply-selection --selection='<json>' --json`,IDE / Web UI 推荐执行 `devflow flow apply-selection --selection-file=<file> --json`；然后展示 `devflow flow explain` 和 `devflow flow card --json`,只有确认面 `ok=true` 时才展示 `devflow flow confirm` 下一步卡片,不得直接进入 requirement/design/apply。
 3. 若旧 change 没有 `state.workflow`,才使用下面的固定 phase 列表作为兼容路径。
 4. `review`、`verify`、`deliver` 是 protected gates,workflow 不得删除或降级。
 

package/src/cli/commands/_helpers.js

@@ -79,6 +79,7 @@ function completeWorkflowStep(st, stepId) {
 function printWorkflowSelectionGuidance(slug) {
   log.dim(`workflow picker: devflow flow picker --slug=${slug} --json`);
   log.dim(`selection:       devflow flow apply-selection --slug=${slug} --selection='<json>' --json`);
+  log.dim(`selection file:  devflow flow apply-selection --slug=${slug} --selection-file=<file> --json`);
   log.dim(`card:            devflow flow card --slug=${slug} --json`);
   log.dim(`check:           devflow flow check --slug=${slug} --json`);
   log.dim(`confirm:         devflow flow confirm --slug=${slug}`);

package/src/cli/commands/flow.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+
 const log = require('../../utils/log.js');
 const config = require('../../core/config.js');
 const state = require('../../core/state.js');
@@ -11,6 +14,9 @@ const workflowVerify = require('../../core/workflow-verify.js');
 const workflowCheck = require('../../core/workflow-check.js');
 const workflowInit = require('../../core/workflow-init.js');
 const workflowPicker = require('../../core/workflow-picker.js');
+const { workflowActions } = require('../../core/workflow-actions.js');
+const workflowUiHost = require('../../core/workflow-ui-host.js');
+const workflowUiAdapter = require('../../core/workflow-ui-adapter.js');
 const helpers = require('./_helpers.js');
 
 async function run({ sub = null, positional = [], flags = {}, cwd }) {
@@ -26,6 +32,7 @@ async function run({ sub = null, positional = [], flags = {}, cwd }) {
     try { return await preview(root, cfg, args[0] || flags.recipe); }
     catch (e) { log.error(e.message); process.exitCode = 2; return; }
   }
+  if (action === 'adapter-catalog' || action === 'adapter-profiles') return adapterCatalog(flags);
   const slug = await helpers.resolveSlug(root, flags, args);
   if (!slug) { process.exitCode = 1; return; }
   const st = await helpers.loadStateOrFail(root, slug);
@@ -44,6 +51,8 @@ async function run({ sub = null, positional = [], flags = {}, cwd }) {
     if (action === 'apply-selection') return await applySelection(root, slug, st, flags);
     if (action === 'card') return card(root, slug, st, flags);
     if (action === 'check') return check(root, slug, st, flags);
+    if (action === 'ui') return await ui(root, slug, flags);
+    if (action === 'adapter') return adapter(root, slug, st, flags);
     if (action === 'confirm') return await confirm(root, slug, st);
     if (action === 'current') return current(st);
     if (action === 'next') return next(st);
@@ -411,15 +420,6 @@ function buildWorkflowConfirmationSurface(root, slug, st) {
   };
 }
 
-function workflowActions(slug) {
-  return {
-    picker: `devflow flow picker --slug=${slug} --json`,
-    applySelection: `devflow flow apply-selection --slug=${slug} --selection='<json>' --json`,
-    check: `devflow flow check --slug=${slug} --json`,
-    confirm: `devflow flow confirm --slug=${slug}`,
-  };
-}
-
 function picker(root, slug, st, flags = {}) {
   const result = workflowPicker.buildPicker(root, slug, st);
   if (flags.json === true) {
@@ -441,7 +441,7 @@ function picker(root, slug, st, flags = {}) {
 }
 
 async function applySelection(root, slug, st, flags = {}) {
-  const selection = parseSelection(flags.selection || flags.input || flags.items);
+  const selection = parseSelection(readSelectionInput(root, flags));
   const applied = { added: [], disabled: [], skipped: [] };
 
   for (const item of selection.items) {
@@ -458,13 +458,16 @@ async function applySelection(root, slug, st, flags = {}) {
         stepId: item.step,
         skill,
       }), { json: flags.json === true })) return;
+      const placement = workflowPicker.placementForCandidate(item.step) || {};
+      const after = item.after || placement.after || null;
+      const before = item.before || placement.before || null;
       const step = workflow.addStep(st.workflow, {
         skill,
         id: item.step,
-        after: item.after || null,
-        before: item.before || null,
+        after,
+        before,
       });
-      state.logEvent(st, 'workflow.step.add', { step: step.id, skill, after: item.after || null, before: item.before || null, source: 'selection' });
+      state.logEvent(st, 'workflow.step.add', { step: step.id, skill, after, before, source: 'selection' });
       applied.added.push(step.id);
       continue;
     }
@@ -486,7 +489,12 @@ async function applySelection(root, slug, st, flags = {}) {
 
   await state.write(root, slug, st);
   const result = {
+    type: 'workflow_selection_result_surface',
+    slug,
+    ok: true,
     ...applied,
+    diff: workflow.diffWorkflow(st.workflow),
+    actions: workflowActions(slug),
     nextAction: `devflow flow card --slug=${slug} --json`,
   };
   if (flags.json === true) {
@@ -498,14 +506,136 @@ async function applySelection(root, slug, st, flags = {}) {
   return result;
 }
 
+async function ui(root, slug, flags = {}) {
+  const host = flags.host && flags.host !== true ? flags.host : '127.0.0.1';
+  const port = workflowUiHost.normalizePort(flags.port, 8787);
+  const app = await workflowUiHost.createWorkflowUiHost({ root, slug, host, port });
+  const surface = {
+    type: 'workflow_ui_host',
+    slug,
+    url: app.url,
+    schemas: {
+      adapter: 'https://devflow.dev/schemas/workflow-adapter-surface.schema.json',
+      adapterCatalog: 'https://devflow.dev/schemas/workflow-adapter-catalog.schema.json',
+      selection: 'https://devflow.dev/schemas/workflow-selection.schema.json',
+      error: 'https://devflow.dev/schemas/workflow-ui-error.schema.json',
+      commandResult: 'https://devflow.dev/schemas/workflow-ui-command-result.schema.json',
+    },
+    actions: {
+      status: `${app.url}api/status`,
+      picker: `${app.url}api/picker`,
+      adapter: `${app.url}api/adapter`,
+      adapterCatalog: `${app.url}api/adapter/catalog`,
+      diff: `${app.url}api/diff`,
+      explain: `${app.url}api/explain`,
+      card: `${app.url}api/card`,
+      applySelection: `${app.url}api/apply-selection`,
+      checkpointResolve: `${app.url}api/checkpoint/resolve`,
+      confirm: `${app.url}api/confirm`,
+    },
+  };
+  if (flags.json === true) {
+    log.raw(JSON.stringify(surface, null, 2));
+  } else {
+    log.ok(`workflow UI: ${app.url}`);
+    log.dim('press Ctrl+C to stop.');
+  }
+  if (flags.once === true || flags['print-only'] === true || flags.printOnly === true) {
+    await app.close();
+    return surface;
+  }
+  await waitForShutdown(app);
+  return surface;
+}
+
+function waitForShutdown(app) {
+  return new Promise((resolve) => {
+    let closing = false;
+    const close = async () => {
+      if (closing) return;
+      closing = true;
+      try { await app.close(); } catch (_) {}
+      resolve();
+    };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+  });
+}
+
+function adapterCatalog(flags = {}) {
+  const catalog = workflowUiAdapter.buildWorkflowAdapterCatalog();
+  if (flags.validate === true || flags.validateContract === true || flags['validate-contract'] === true) {
+    workflowUiAdapter.assertWorkflowAdapterCatalog(catalog);
+  }
+  if (flags.json === true) {
+    log.raw(JSON.stringify(catalog, null, 2));
+    return catalog;
+  }
+  log.raw('workflow adapter profiles');
+  for (const profile of catalog.profiles) {
+    log.raw(`- ${profile.id}: ${profile.defaultRenderMode}`);
+    log.dim(`  ${profile.description}`);
+  }
+  log.raw('');
+  log.raw('render modes');
+  for (const mode of catalog.renderModes) {
+    log.raw(`- ${mode.id}: embedded=${mode.supportsEmbeddedUi}`);
+  }
+  log.raw('');
+  log.dim('custom host default: browser profile / browser render mode');
+  log.dim('next: devflow flow adapter --slug=<slug> --host=<name> --profile=<profile> --json');
+  return catalog;
+}
+
+function adapter(root, slug, st, flags = {}) {
+  const host = flags.host && flags.host !== true ? flags.host : (flags.target && flags.target !== true ? flags.target : 'browser');
+  const profile = flags.profile && flags.profile !== true ? flags.profile : null;
+  const renderMode = flags.renderMode || flags['render-mode'] || null;
+  const port = flags.port === undefined ? 8787 : workflowUiHost.normalizePort(flags.port, 8787);
+  const pickerSurface = st.workflow && Array.isArray(st.workflow.steps)
+    ? workflowPicker.buildPicker(root, slug, st)
+    : null;
+  const surface = workflowUiAdapter.buildWorkflowAdapterSurface({ host, profile, renderMode, slug, port, pickerSurface });
+  if (flags.validate === true || flags.validateContract === true || flags['validate-contract'] === true) {
+    workflowUiAdapter.assertWorkflowAdapterSurface(surface);
+  }
+  if (flags.json === true) {
+    log.raw(JSON.stringify(surface, null, 2));
+    return surface;
+  }
+  log.raw(`${surface.host} workflow adapter`);
+  log.raw(`url: ${surface.url}`);
+  log.raw(`start: ${surface.actions.startUi}`);
+  for (const item of surface.instructions) log.dim(`- ${item}`);
+  log.raw('');
+  log.raw(surface.chatCard.markdown);
+  return surface;
+}
+
+function readSelectionInput(root, flags = {}) {
+  const inline = flags.selection || flags.input || flags.items;
+  if (inline && inline !== true) return inline;
+  const file = flags.selectionFile || flags['selection-file'];
+  if (!file || file === true) return inline;
+  const selectionPath = path.isAbsolute(file) ? file : path.resolve(root, file);
+  return fs.readFileSync(selectionPath, 'utf8');
+}
+
 function parseSelection(raw) {
-  if (!raw || raw === true) throw new Error('usage: devflow flow apply-selection --selection=<json> --slug=<slug>');
+  if (!raw || raw === true) throw new Error('usage: devflow flow apply-selection --selection=<json> | --selection-file=<file> --slug=<slug>');
   const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
-  const items = Array.isArray(parsed) ? parsed : parsed.items;
+  const items = Array.isArray(parsed)
+    ? parsed
+    : parsed.items || flattenPickerGroups(parsed.groups);
   if (!Array.isArray(items)) throw new Error('workflow selection must contain an items array');
   return { items };
 }
 
+function flattenPickerGroups(groups) {
+  if (!Array.isArray(groups)) return null;
+  return groups.flatMap((group) => Array.isArray(group.items) ? group.items : []);
+}
+
 async function confirm(root, slug, st) {
   const result = workflowCheck.checkWorkflow(root, slug, st);
   if (!result.ok) {
@@ -639,7 +769,7 @@ function validateInstalledSkills(root, steps) {
 }
 
 function usage() {
-  log.error('usage: devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|confirm|current|next|explain|validate|preview|use>');
+  log.error('usage: devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|ui|adapter|adapter-catalog|confirm|current|next|explain|validate|preview|use>');
 }
 
 module.exports = { run };

package/src/cli/commands/help.js

@@ -65,7 +65,7 @@ OPS
     [--split-report]          also write legacy reports/<kind>-test.md
   devflow report compact [--remove-split]
                               merge existing split reports into reports/test-report.md
-  devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|confirm|explain>
+  devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|ui|adapter|adapter-catalog|confirm|explain>
                               draft and adjust the change workflow from builtin/project recipes
   devflow deploy test --project=<name>             trigger configured Jenkins test job
     auto-prompts feature->test merge/push before Jenkins when run from a dev branch

package/src/cli/commands/status.js

@@ -9,6 +9,7 @@ const state = require('../../core/state.js');
 const checkpoint = require('../../core/checkpoint.js');
 const workflowCheck = require('../../core/workflow-check.js');
 const workflowVerify = require('../../core/workflow-verify.js');
+const { workflowActions } = require('../../core/workflow-actions.js');
 const aggregate = require('../../reports/aggregate.js');
 const helpers = require('./_helpers.js');
 
@@ -369,11 +370,7 @@ function buildStatusSurface(root, slug, st) {
       nextStep: nextWorkflowStep(wf),
       overrides: summarizeWorkflowOverrides(wf),
       check: workflowCheckResult,
-      actions: {
-        card: `devflow flow card --slug=${slug} --json`,
-        picker: `devflow flow picker --slug=${slug} --json`,
-        confirm: `devflow flow confirm --slug=${slug}`,
-      },
+      actions: workflowActions(slug),
     } : null,
     pendingCheckpoint: pending ? checkpoint.summarizeCheckpoint(pending) : null,
     checkpointConfirmationCard,