@chenguangyao/devflow-kit 0.1.43 → 0.1.44

package/src/core/workflow-ui-host.js

@@ -0,0 +1,837 @@
+'use strict';
+
+const childProcess = require('child_process');
+const http = require('http');
+const path = require('path');
+const { URL } = require('url');
+
+const workflowUiAdapter = require('./workflow-ui-adapter.js');
+
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8787;
+const MAX_BODY_BYTES = 1024 * 1024;
+const WORKFLOW_UI_ERROR_SCHEMA = 'https://devflow.dev/schemas/workflow-ui-error.schema.json';
+const WORKFLOW_UI_COMMAND_RESULT_SCHEMA = 'https://devflow.dev/schemas/workflow-ui-command-result.schema.json';
+
+async function createWorkflowUiHost(options = {}) {
+  const root = options.root || process.cwd();
+  const slug = options.slug;
+  if (!slug) throw new Error('createWorkflowUiHost requires slug');
+  const hostname = options.host || options.hostname || DEFAULT_HOST;
+  const port = normalizePort(options.port, 0);
+  const binPath = options.binPath || path.resolve(__dirname, '..', '..', 'bin', 'devflow.js');
+  const execFile = options.execFile || childProcess.execFile;
+
+  const requestContext = { root, slug, binPath, execFile, host: hostname, port: null, url: null };
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res, requestContext).catch((e) => {
+      writeWorkflowUiError(res, e.statusCode || 500, {
+        code: e.code || 'workflow-ui-error',
+        message: e.message,
+        details: e.details || null,
+      });
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, hostname, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address ? address.port : port;
+  const url = `http://${hostname}:${actualPort}/`;
+  requestContext.port = actualPort;
+  requestContext.url = url;
+  return {
+    type: 'workflow_ui_host',
+    slug,
+    root,
+    host: hostname,
+    port: actualPort,
+    url,
+    server,
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    }),
+  };
+}
+
+async function handleRequest(req, res, context) {
+  const url = new URL(req.url || '/', `http://${req.headers.host || DEFAULT_HOST}`);
+  if (req.method === 'GET' && url.pathname === '/') {
+    writeHtml(res, renderWorkflowUiHostHtml({ slug: context.slug }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/status') {
+    await writeDevflowJson(res, context, ['status', `--slug=${context.slug}`, '--json']);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/picker') {
+    await writeDevflowJson(res, context, ['flow', 'picker', `--slug=${context.slug}`, '--json']);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/adapter/catalog') {
+    const catalog = workflowUiAdapter.buildWorkflowAdapterCatalog();
+    if (isTruthyQuery(url.searchParams.get('validate'))) workflowUiAdapter.assertWorkflowAdapterCatalog(catalog);
+    writeJson(res, 200, catalog);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/adapter') {
+    const host = url.searchParams.get('host') || 'browser';
+    const profile = url.searchParams.get('profile');
+    const renderMode = url.searchParams.get('render-mode') || url.searchParams.get('renderMode');
+    const args = [
+      'flow',
+      'adapter',
+      `--slug=${context.slug}`,
+      `--host=${host}`,
+      `--port=${context.port || DEFAULT_PORT}`,
+      '--json',
+    ];
+    if (profile) args.push(`--profile=${profile}`);
+    if (renderMode) args.push(`--render-mode=${renderMode}`);
+    if (isTruthyQuery(url.searchParams.get('validate'))) args.push('--validate-contract');
+    await writeDevflowJson(res, context, args);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/card') {
+    await writeDevflowJson(res, context, ['flow', 'card', `--slug=${context.slug}`, '--json']);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/diff') {
+    await writeDevflowJson(res, context, ['flow', 'diff', `--slug=${context.slug}`, '--json']);
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/api/explain') {
+    await writeDevflowJson(res, context, ['flow', 'explain', `--slug=${context.slug}`, '--json']);
+    return;
+  }
+  if (req.method === 'POST' && (url.pathname === '/api/apply-selection' || url.pathname === '/api/adapter/apply-selection')) {
+    const body = await readJsonBody(req);
+    const selectionErrors = validateWorkflowSelection(body);
+    if (selectionErrors.length) {
+      writeWorkflowUiError(res, 400, {
+        code: 'invalid-workflow-selection',
+        message: selectionErrors[0],
+        details: selectionErrors,
+      });
+      return;
+    }
+    await writeDevflowJson(res, context, [
+      'flow',
+      'apply-selection',
+      `--slug=${context.slug}`,
+      `--selection=${JSON.stringify(body)}`,
+      '--json',
+    ]);
+    return;
+  }
+  if (req.method === 'POST' && url.pathname === '/api/confirm') {
+    const result = await runDevflow(context, ['flow', 'confirm', `--slug=${context.slug}`], { json: false });
+    writeWorkflowUiCommandResult(res, result.exitCode === 0 ? 200 : 500, {
+      ok: result.exitCode === 0,
+      slug: context.slug,
+      output: result.stdout,
+      error: result.stderr || null,
+    });
+    return;
+  }
+  if (req.method === 'POST' && url.pathname === '/api/checkpoint/resolve') {
+    const body = await readJsonBody(req);
+    if (!body.id || !body.decision) {
+      throw new WorkflowUiError(400, 'invalid-checkpoint-resolution', 'checkpoint resolve requires id and decision');
+    }
+    const result = await runDevflow(context, [
+      'checkpoint',
+      'resolve',
+      `--id=${body.id}`,
+      `--decision=${body.decision}`,
+    ], { json: false });
+    writeWorkflowUiCommandResult(res, result.exitCode === 0 ? 200 : 500, {
+      ok: result.exitCode === 0,
+      slug: context.slug,
+      output: result.stdout,
+      error: result.stderr || null,
+    });
+    return;
+  }
+  writeWorkflowUiError(res, 404, {
+    code: 'route-not-found',
+    message: `not found: ${req.method} ${url.pathname}`,
+  });
+}
+
+class WorkflowUiError extends Error {
+  constructor(statusCode, code, message, details = null) {
+    super(message);
+    this.name = 'WorkflowUiError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function isTruthyQuery(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+
+function validateWorkflowSelection(value) {
+  if (!isPlainObject(value)) return ['selection must be an object'];
+  if (value.type === undefined) {
+    return validateSelectionItems(value.items, 'items');
+  }
+  if (value.type === 'workflow_picker_surface' || value.type === 'workflow_chat_selection') {
+    return validateSelectionGroups(value.groups);
+  }
+  return ['selection.type must be workflow_picker_surface or workflow_chat_selection'];
+}
+
+function validateSelectionGroups(groups) {
+  if (!Array.isArray(groups)) return ['groups must be an array'];
+  const errors = [];
+  groups.forEach((group, groupIndex) => {
+    if (!isPlainObject(group)) {
+      errors.push(`groups[${groupIndex}] must be an object`);
+      return;
+    }
+    errors.push(...validateSelectionItems(group.items, `groups[${groupIndex}].items`));
+  });
+  return errors;
+}
+
+function validateSelectionItems(items, pathName) {
+  if (!Array.isArray(items)) return [`${pathName} must be an array`];
+  const errors = [];
+  items.forEach((item, itemIndex) => {
+    const itemPath = `${pathName}[${itemIndex}]`;
+    if (!isPlainObject(item)) {
+      errors.push(`${itemPath} must be an object`);
+      return;
+    }
+    if (typeof item.step !== 'string' || !item.step.trim()) {
+      errors.push(`${itemPath}.step must be a non-empty string`);
+    }
+    if (typeof item.selected !== 'boolean') {
+      errors.push(`${itemPath}.selected must be a boolean`);
+    }
+  });
+  return errors;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function writeDevflowJson(res, context, args) {
+  const result = await runDevflow(context, args, { json: true });
+  if (result.json) {
+    writeJson(res, 200, result.json);
+    return;
+  }
+  const command = `devflow ${args.join(' ')}`;
+  const failed = result.exitCode !== 0;
+  const message = failed
+    ? firstNonEmptyLine(result.stderr, result.stdout) || `${command} failed`
+    : `${command} did not return JSON`;
+  writeWorkflowUiError(res, failed ? 500 : 502, {
+    code: failed ? 'devflow-command-failed' : 'devflow-json-missing',
+    message,
+    command,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    details: {
+      expected: 'json',
+    },
+  });
+}
+
+function writeWorkflowUiError(res, statusCode, fields) {
+  writeJson(res, statusCode, {
+    type: 'workflow_ui_error',
+    schema: WORKFLOW_UI_ERROR_SCHEMA,
+    ok: false,
+    ...fields,
+  });
+}
+
+function writeWorkflowUiCommandResult(res, statusCode, fields) {
+  writeJson(res, statusCode, {
+    type: 'workflow_ui_command_result',
+    schema: WORKFLOW_UI_COMMAND_RESULT_SCHEMA,
+    ...fields,
+  });
+}
+
+function firstNonEmptyLine(...values) {
+  for (const value of values) {
+    const line = String(value || '').split(/\r?\n/).map((item) => item.trim()).find(Boolean);
+    if (line) return line;
+  }
+  return null;
+}
+
+function runDevflow(context, args) {
+  return new Promise((resolve) => {
+    context.execFile(process.execPath, [context.binPath, ...args], {
+      cwd: context.root,
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+    }, (err, stdout = '', stderr = '') => {
+      const exitCode = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+      const out = String(stdout || err?.stdout || '');
+      const errOut = String(stderr || err?.stderr || '');
+      resolve({
+        exitCode,
+        stdout: out,
+        stderr: errOut,
+        json: tryParseJson(out),
+      });
+    });
+  });
+}
+
+function tryParseJson(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch (_) { return null; }
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      data += chunk;
+      if (Buffer.byteLength(data) > MAX_BODY_BYTES) {
+        reject(new WorkflowUiError(413, 'request-body-too-large', 'request body too large'));
+        req.destroy();
+      }
+    });
+    req.on('end', () => {
+      if (!data.trim()) {
+        resolve({});
+        return;
+      }
+      try { resolve(JSON.parse(data)); } catch (e) {
+        reject(new WorkflowUiError(400, 'invalid-json-body', `invalid JSON body: ${e.message}`));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function renderWorkflowUiHostHtml({ slug }) {
+  return [
+    '<!doctype html>',
+    '<html lang="zh-CN">',
+    '<head>',
+    '  <meta charset="utf-8">',
+    '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    `  <title>devflow workflow - ${escapeHtml(slug)}</title>`,
+    '  <style>',
+    renderCss(),
+    '  </style>',
+    '</head>',
+    '<body data-app="workflow-ui-host">',
+    '  <main class="page">',
+    '    <header class="topbar">',
+    '      <div>',
+    '        <h1>Workflow 编排</h1>',
+    `        <p>${escapeHtml(slug)}</p>`,
+    '      </div>',
+    '      <div class="top-actions">',
+    '        <button id="refresh" type="button">刷新</button>',
+    '        <button id="apply" type="button">应用选择</button>',
+    '        <button id="confirm" type="button">确认 workflow</button>',
+    '      </div>',
+    '    </header>',
+    '    <section class="band" aria-label="Workflow status">',
+    '      <h2>当前状态</h2>',
+    '      <div id="primary-panel"></div>',
+    '      <pre id="status">loading...</pre>',
+    '    </section>',
+    '    <section class="band" aria-label="Workflow picker">',
+    '      <div class="section-head">',
+    '        <h2>Skill 选项卡</h2>',
+    '        <code id="picker-command">/api/picker · /api/adapter</code>',
+    '      </div>',
+    '      <div id="picker" class="groups"></div>',
+    '    </section>',
+    '    <section class="band" aria-label="Workflow insight">',
+    '      <div class="section-head">',
+    '        <h2>编排说明</h2>',
+    '        <code>/api/diff · /api/explain</code>',
+    '      </div>',
+    '      <div id="insight" class="insight-grid"></div>',
+    '    </section>',
+    '    <section class="band" aria-label="Workflow result">',
+    '      <h2>结果</h2>',
+    '      <pre id="result">等待操作</pre>',
+    '      <div id="result-card"></div>',
+    '    </section>',
+    '    <section class="band" aria-label="Workflow card">',
+    '      <h2>确认卡</h2>',
+    '      <div id="card" class="timeline"></div>',
+    '    </section>',
+    '  </main>',
+    '  <script>',
+    renderClientScript(),
+    '  </script>',
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}
+
+function renderClientScript() {
+  return `(${browserClientScript.toString()})();`;
+}
+
+function browserClientScript() {
+const state = { picker: null, status: null };
+const $ = (id) => document.getElementById(id);
+
+async function api(path, options = {}) {
+  const res = await fetch(path, {
+    method: options.method || 'GET',
+    headers: options.body ? { 'content-type': 'application/json' } : undefined,
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+  const data = await res.json();
+  if (!res.ok && !data.type) throw new Error(data.message || res.statusText);
+  return data;
+}
+
+async function refresh() {
+  const [status, picker, card, diff, explain] = await Promise.all([
+    api('/api/status'),
+    api('/api/picker'),
+    api('/api/card'),
+    api('/api/diff'),
+    api('/api/explain'),
+  ]);
+  state.picker = picker;
+  state.status = status;
+  $('status').textContent = JSON.stringify({
+    phase: status.phase,
+    workflow: status.workflow ? {
+      status: status.workflow.status,
+      currentStep: status.workflow.currentStep,
+      nextStep: status.workflow.nextStep,
+    } : null,
+    blockingReason: status.blockingReason || null,
+    nextAction: status.nextAction || null,
+  }, null, 2);
+  renderPrimaryPanel(status);
+  renderPicker(picker);
+  renderCard(card);
+  renderWorkflowInsight(diff, explain);
+}
+
+function renderPrimaryPanel(surface) {
+  const panel = surface.primaryPanel;
+  const actions = surface.availableActions || [];
+  if (!panel) {
+    $('primary-panel').innerHTML = '';
+    return;
+  }
+  const reason = surface.blockingReason || {};
+  $('primary-panel').innerHTML = `
+    <div class="primary-panel" data-surface="primary-panel">
+      <div>
+        <strong>${escapeHtml(panel.title || '下一步')}</strong>
+        <small>${escapeHtml(reason.message || surface.nextAction || '')}</small>
+      </div>
+      <div class="inline-actions">
+        ${actions.map((action) => `
+          <button
+            type="button"
+            class="${action.danger ? 'danger-button' : ''}"
+            data-action-id="${escapeAttr(action.id)}"
+            data-action-kind="${escapeAttr(action.kind || '')}"
+          >${escapeHtml(action.label || action.id)}</button>
+        `).join('')}
+      </div>
+    </div>
+  `;
+  for (const button of document.querySelectorAll('[data-action-id]')) {
+    button.addEventListener('click', async () => {
+      const action = actions.find((item) => item.id === button.dataset.actionId);
+      if (action) await runSurfaceAction(action, surface);
+    });
+  }
+}
+
+async function runSurfaceAction(action, surface) {
+  const command = action.command || '';
+  if (action.id === 'confirm-workflow' || command.includes('flow confirm')) {
+    await confirmWorkflow();
+    return;
+  }
+  if (action.kind === 'checkpoint-decision') {
+    await resolveCheckpointAction(command, action);
+    return;
+  }
+  if (action.kind === 'open-surface' && command.includes('checkpoint show')) {
+    renderCheckpointConfirmationSurface({
+      confirmationCard: surface.checkpointConfirmationCard,
+      checkpoint: surface.pendingCheckpoint,
+    });
+    return;
+  }
+  if (action.kind === 'open-surface' && command.includes('flow card')) {
+    const card = await api('/api/card');
+    renderCard(card);
+    document.querySelector('[aria-label="Workflow card"]').scrollIntoView({ block: 'nearest' });
+    return;
+  }
+  if (action.kind === 'open-surface' && command.includes('flow picker')) {
+    document.querySelector('[aria-label="Workflow picker"]').scrollIntoView({ block: 'nearest' });
+    return;
+  }
+  $('result-card').innerHTML = `
+    <div class="decision-card">
+      <strong>需要在终端执行</strong>
+      <small>${escapeHtml(action.label || action.id)}</small>
+      <code>${escapeHtml(command)}</code>
+    </div>
+  `;
+}
+
+async function resolveCheckpointAction(command, action = {}) {
+  const id = commandArg(command, '--id');
+  const decision = commandArg(command, '--decision');
+  if (!id || !decision) {
+    if (action.id === 'keep' || command.includes('status')) {
+      await refresh();
+      return;
+    }
+    $('result-card').innerHTML = `
+      <div class="decision-card">
+        <strong>需要人工处理</strong>
+        <small>${escapeHtml(action.label || action.id || 'checkpoint action')}</small>
+        <code>${escapeHtml(command)}</code>
+      </div>
+    `;
+    return;
+  }
+  const result = await api('/api/checkpoint/resolve', {
+    method: 'POST',
+    body: { id, decision },
+  });
+  $('result').textContent = JSON.stringify(result, null, 2);
+  renderResultSurface(result);
+  await refresh();
+}
+
+function renderPicker(surface) {
+  $('picker-command').textContent = surface.actions && surface.actions.applySelectionFile
+    ? surface.actions.applySelectionFile
+    : '/api/apply-selection';
+  $('picker').innerHTML = (surface.groups || []).map((group) => `
+    <section class="group">
+      <h3>${escapeHtml(group.label || group.id)}</h3>
+      <ol>${(group.items || []).map(renderItem).join('')}</ol>
+    </section>
+  `).join('');
+}
+
+function renderWorkflowInsight(diff, explain) {
+  const added = diff.added || [];
+  const disabled = diff.disabled || [];
+  const moved = diff.moved || [];
+  const verifyReports = diff.verifyReports || [];
+  const risks = explain.openRiskSignals || [];
+  const overrides = explain.overrides || [];
+  const verify = explain.verify || {};
+  $('insight').innerHTML = `
+    <section class="insight-card">
+      <h3>相对默认流程</h3>
+      ${renderInsightList('新增', added)}
+      ${renderInsightList('禁用', disabled)}
+      ${renderInsightList('移动', moved)}
+      ${renderInsightList('验证要求', verifyReports.length ? verifyReports : (verify.requiredReports || []))}
+    </section>
+    <section class="insight-card">
+      <h3>推荐原因</h3>
+      ${renderInsightList('风险信号', risks.map((risk) => `${risk.type}${risk.reason ? ': ' + risk.reason : ''}`))}
+      ${verify.reason ? `<p>${escapeHtml(verify.reason)}</p>` : ''}
+      ${renderInsightList('本次 override', overrides.map(formatOverride))}
+    </section>
+  `;
+}
+
+function renderInsightList(label, items) {
+  const values = Array.isArray(items) ? items.filter(Boolean) : [];
+  return `
+    <div class="insight-row">
+      <strong>${escapeHtml(label)}</strong>
+      <span>${values.length ? values.map((item) => `<code>${escapeHtml(item)}</code>`).join('') : '<small>-</small>'}</span>
+    </div>
+  `;
+}
+
+function formatOverride(item) {
+  if (!item) return '';
+  if (typeof item === 'string') return item;
+  return [
+    item.type || item.action || 'override',
+    item.step || item.skill || null,
+    item.reason || null,
+  ].filter(Boolean).join(': ');
+}
+
+function renderItem(item) {
+  const checked = item.selected ? ' checked' : '';
+  const disabled = item.locked ? ' disabled' : '';
+  const tags = [
+    item.recommended ? 'recommended' : null,
+    item.required ? 'required' : null,
+    item.optional ? 'optional' : null,
+    item.locked ? 'locked' : null,
+  ].filter(Boolean).join(' / ');
+  return `
+    <li>
+      <label>
+        <input type="checkbox" data-step="${escapeAttr(item.step)}"${checked}${disabled}>
+        <span>${escapeHtml(item.step)}</span>
+      </label>
+      <small>${escapeHtml(item.skill || '')}${tags ? ' · ' + escapeHtml(tags) : ''}</small>
+      ${item.reason ? `<p>${escapeHtml(item.reason)}</p>` : ''}
+    </li>
+  `;
+}
+
+function currentSelection() {
+  const selected = new Map(Array.from(document.querySelectorAll('[data-step]')).map((input) => [
+    input.dataset.step,
+    input.checked,
+  ]));
+  const items = [];
+  for (const group of state.picker.groups || []) {
+    for (const item of group.items || []) {
+      items.push({
+        step: item.step,
+        skill: item.skill,
+        selected: selected.has(item.step) ? selected.get(item.step) : item.selected === true,
+        reason: item.selected && selected.get(item.step) === false ? 'disabled from workflow UI' : undefined,
+        after: item.after || undefined,
+        before: item.before || undefined,
+      });
+    }
+  }
+  return { items };
+}
+
+async function applySelection() {
+  const result = await api('/api/apply-selection', { method: 'POST', body: currentSelection() });
+  $('result').textContent = JSON.stringify(result, null, 2);
+  renderResultSurface(result);
+  await refresh();
+}
+
+async function confirmWorkflow() {
+  const result = await api('/api/confirm', { method: 'POST', body: {} });
+  $('result').textContent = JSON.stringify(result, null, 2);
+  renderResultSurface(result);
+  await refresh();
+}
+
+function renderResultSurface(surface) {
+  if (surface.type === 'workflow_policy_confirmation_surface') {
+    renderCheckpointConfirmationSurface(surface, 'workflow-policy-card');
+    return;
+  }
+  if (surface.type === 'checkpoint_confirmation_surface') {
+    renderCheckpointConfirmationSurface(surface, 'checkpoint-card');
+    return;
+  }
+  if (surface.type === 'workflow_selection_result_surface') {
+    $('result-card').innerHTML = `
+      <div class="decision-card ok">
+        <strong>选择已应用</strong>
+        <small>added=${(surface.added || []).length} · disabled=${(surface.disabled || []).length}</small>
+        <code>${escapeHtml(surface.nextAction || '')}</code>
+      </div>
+    `;
+    return;
+  }
+  if (surface.type === 'workflow_ui_command_result') {
+    $('result-card').innerHTML = `
+      <div class="decision-card ${surface.ok ? 'ok' : 'danger'}">
+        <strong>${surface.ok ? '命令已执行' : '命令失败'}</strong>
+        <small>${escapeHtml(surface.output || surface.error || '')}</small>
+      </div>
+    `;
+    return;
+  }
+  $('result-card').innerHTML = '';
+}
+
+function renderCheckpointConfirmationSurface(surface, surfaceName = 'checkpoint-card') {
+  const card = surface.confirmationCard || {};
+  const checkpoint = surface.checkpoint || card.checkpoint || {};
+  const primary = card.primaryAction || {};
+  const checkpointId = checkpoint.id || commandArg(primary.command, '--id');
+  const decision = commandArg(primary.command, '--decision') || primary.id || 'accept-risk';
+  const secondary = (card.secondaryActions || [])[0];
+  $('result-card').innerHTML = `
+    <div class="decision-card policy" data-surface="${escapeAttr(surfaceName)}">
+      <strong>${escapeHtml(card.title || '确认下一步')}</strong>
+      <p>${escapeHtml(card.question || checkpoint.summary || '这个 workflow 调整会提高风险，是否接受？')}</p>
+      <small>${escapeHtml(checkpoint.summary || checkpointId || '')}</small>
+      <div class="inline-actions">
+        <button type="button" data-checkpoint-id="${escapeAttr(checkpointId)}" data-decision="${escapeAttr(decision)}">${escapeHtml(primary.label || decision || '确认')}</button>
+        <button type="button" data-refresh="true">${escapeHtml(secondary ? secondary.id : 'keep')}</button>
+      </div>
+      <code>${escapeHtml(primary.command || '')}</code>
+    </div>
+  `;
+  const accept = $('result-card').querySelector('[data-checkpoint-id]');
+  if (accept) {
+    accept.addEventListener('click', async () => {
+      const result = await api('/api/checkpoint/resolve', {
+        method: 'POST',
+        body: {
+          id: accept.dataset.checkpointId,
+          decision: accept.dataset.decision,
+        },
+      });
+      $('result').textContent = JSON.stringify(result, null, 2);
+      renderResultSurface(result);
+      await refresh();
+    });
+  }
+  const keep = $('result-card').querySelector('[data-refresh]');
+  if (keep) keep.addEventListener('click', refresh);
+}
+
+function commandArg(command, name) {
+  const tokens = String(command || '').split(/\s+/);
+  for (const token of tokens) {
+    if (token.startsWith(`${name}=`)) return token.slice(name.length + 1);
+  }
+  const idx = tokens.indexOf(name);
+  return idx === -1 ? '' : tokens[idx + 1] || '';
+}
+
+function renderCard(surface) {
+  const card = surface.confirmationCard || {};
+  $('card').innerHTML = (card.steps || []).map((step, idx) => `
+    <div class="step">
+      <span>${idx + 1}</span>
+      <strong>${escapeHtml(step.id)}</strong>
+      <small>${escapeHtml(step.skill || '')}</small>
+    </div>
+  `).join('');
+}
+
+function escapeHtml(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function escapeAttr(value) {
+  return escapeHtml(value);
+}
+
+$('refresh').addEventListener('click', refresh);
+$('apply').addEventListener('click', applySelection);
+$('confirm').addEventListener('click', confirmWorkflow);
+refresh().catch((e) => { $('result').textContent = e.stack || e.message; });
+}
+
+function renderCss() {
+  return [
+    ':root { color-scheme: light; --ink:#162126; --muted:#62737c; --line:#d7e0e5; --panel:#f7fafb; --accent:#12695f; --danger:#9f3d20; }',
+    '* { box-sizing: border-box; }',
+    'body { margin:0; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color:var(--ink); background:#eef3f5; }',
+    '.page { width:min(1180px, calc(100vw - 32px)); margin:0 auto; padding:28px 0 44px; }',
+    '.topbar { display:flex; justify-content:space-between; align-items:flex-end; gap:18px; padding-bottom:16px; }',
+    'h1,h2,h3,p { margin:0; }',
+    'h1 { font-size:28px; line-height:1.15; }',
+    'h2 { font-size:18px; }',
+    'h3 { font-size:14px; color:var(--muted); }',
+    'p, small { color:var(--muted); }',
+    '.top-actions { display:flex; flex-wrap:wrap; gap:8px; }',
+    'button { border:0; border-radius:6px; padding:8px 12px; background:var(--accent); color:white; font-weight:700; cursor:pointer; }',
+    'button.danger-button { background:var(--danger); }',
+    'button:active { transform: translateY(1px); }',
+    '.band { margin-top:16px; border:1px solid var(--line); border-radius:8px; background:white; padding:16px; }',
+    '.section-head { display:flex; justify-content:space-between; gap:12px; align-items:center; margin-bottom:12px; }',
+    'code, pre { max-width:100%; overflow:auto; border:1px solid var(--line); border-radius:6px; background:var(--panel); }',
+    'code { padding:5px 7px; font-size:12px; overflow-wrap:anywhere; }',
+    'pre { min-height:72px; padding:12px; font-size:12px; line-height:1.45; }',
+    '.groups { display:grid; grid-template-columns:repeat(3, minmax(0, 1fr)); gap:12px; }',
+    '.insight-grid { display:grid; grid-template-columns:repeat(2, minmax(0, 1fr)); gap:12px; }',
+    '.insight-card { display:grid; gap:10px; border:1px solid var(--line); border-radius:8px; padding:12px; background:var(--panel); }',
+    '.insight-row { display:grid; grid-template-columns:92px minmax(0, 1fr); gap:8px; align-items:start; }',
+    '.insight-row span { display:flex; flex-wrap:wrap; gap:6px; min-width:0; }',
+    '.group { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:12px; }',
+    'ol { list-style:none; margin:0; padding:0; }',
+    'li { min-height:96px; display:grid; gap:6px; align-content:start; border-top:1px solid var(--line); padding:10px 0; }',
+    'li:first-child { border-top:0; }',
+    'label { display:flex; align-items:center; gap:8px; font-weight:700; }',
+    'input { width:16px; height:16px; accent-color:var(--accent); }',
+    'li p { color:var(--danger); font-size:12px; }',
+    '.timeline { display:grid; grid-template-columns:repeat(8, minmax(96px, 1fr)); gap:8px; overflow-x:auto; }',
+    '.step { min-width:96px; display:grid; gap:5px; border:1px solid var(--line); border-radius:8px; padding:10px; background:var(--panel); }',
+    '.step span { display:grid; place-items:center; width:22px; height:22px; border-radius:999px; background:var(--accent); color:white; font-size:12px; font-weight:700; }',
+    '.decision-card { display:grid; gap:8px; margin-top:12px; border:1px solid var(--line); border-radius:8px; padding:12px; background:var(--panel); }',
+    '.decision-card.policy { border-color:#e3b16f; background:#fffaf3; }',
+    '.decision-card.ok { border-color:#95c9bf; background:#f5fbf9; }',
+    '.decision-card.danger { border-color:#e0a28f; background:#fff6f3; }',
+    '.primary-panel { display:flex; justify-content:space-between; gap:12px; align-items:center; margin:12px 0; border:1px solid var(--line); border-radius:8px; padding:12px; background:var(--panel); }',
+    '.primary-panel > div:first-child { display:grid; gap:4px; }',
+    '.inline-actions { display:flex; flex-wrap:wrap; gap:8px; align-items:center; }',
+    '@media (max-width: 860px) { .topbar { align-items:flex-start; flex-direction:column; } .groups, .insight-grid { grid-template-columns:1fr; } .timeline { grid-template-columns:repeat(4, minmax(96px, 1fr)); } }',
+  ].join('\n');
+}
+
+function writeHtml(res, html) {
+  res.writeHead(200, {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(html);
+}
+
+function writeJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(JSON.stringify(body, null, 2));
+}
+
+function normalizePort(value, fallback = DEFAULT_PORT) {
+  if (value === undefined || value === null || value === true || value === '') return fallback;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`invalid port: ${value}`);
+  return port;
+}
+
+function escapeHtml(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+module.exports = {
+  createWorkflowUiHost,
+  renderWorkflowUiHostHtml,
+  normalizePort,
+};