draftgo-cli 3.0.55 → 4.0.1

package/src/commands/help.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { all } = require('../installers');
+const { all } = require('../targets');
 const { HOSTS } = require('../mcp/hosts');
 const { getPackageVersion } = require('../skill');
 
@@ -43,8 +43,8 @@ Usage:
   draftgo check [custom-services <id...>]
                                     Validate all checkouts or selected custom services.
                                     --remote also compares remote hash/version.
-  draftgo verify [<type> <id...>]   Run unified static verification; --remote adds
-                                    remote comparison and --url enables UI checks.
+  draftgo verify [<type> <id...>]   Run the default delivery verification.
+                                    Browser options are explicit and optional.
   draftgo diff <type> <id>         Show checkout base versus local body.
   draftgo commit <type> <id...>    Validate and upload complete checked-out bodies.
   draftgo refresh <type> <id...>   Safely refresh a clean checkout from the cloud.
@@ -61,12 +61,12 @@ Usage:
   draftgo conflict resolve <type> <id>
                                     Mark a merged worktree file ready against the
                                     preserved remote base; then check/diff/commit.
-  draftgo verify-ui <url>          Deprecated alias for verify --url <url> --ui always.
   draftgo clean [--dry-run|--yes]  Plan or remove all tmp and registered artifacts.
-  draftgo task <operation> [...]   Track sustained work in one authoritative Task.md.
-                                    Operations: create, list, show, add, claim,
-                                    start, complete, block, reopen, accept, finish,
-                                    and explicit legacy migrate.
+  draftgo work start <item>       Add an active item to .draftgo/worklog.md.
+  draftgo work add <item>         Add a pending item.
+  draftgo work start-item <ref>   Mark an item active; ref is number or date#number.
+  draftgo work complete <ref>     Mark an item complete; --note appends evidence.
+  draftgo work show|list          Show the worklog or its structured item list.
 
   draftgo api <query>              Search the live API contract through MCP.
   draftgo api describe <operation_id>
@@ -75,23 +75,14 @@ Usage:
                                     Call one described operation with UTF-8 JSON.
   draftgo delete <operation_id> [id]
                                     Confirm and call a live delete operation.
-                                    Legacy <type> <id> works only when unambiguous.
   draftgo deploy [<type> <id...>]  Check, then diff or commit checked-out content.
                                     --delivery local needs no IDs; preview/deploy
                                     require an explicit type and IDs.
   draftgo auto-push [<type> <id...>]
                                     With config.auto_push=true, check and commit
                                     changed checkouts. Any conflict stops the run.
-  draftgo changelog add <result>   Append one completed result after the task has
-                                    passed unified verification and delivery.
-  draftgo pull                     Migration notice only; always downloads nothing.
-  draftgo push <type> <id...>      Deprecated alias to commit for pages/nav/docs.
-                                    Push-all and structured-resource push are removed.
-
   draftgo local setup|start|stop|logs|status
-                                    Manage the existing local Docker stack. up/down
-                                    remain aliases for start/stop; status also has ps.
-  draftgo local-dev                Compatibility alias for \`draftgo local setup\`.
+                                    Manage the project-local Docker stack.
   draftgo list-targets             List Skill installation targets.
   draftgo -v | --version           Print CLI version.
   draftgo -h | --help              Show this help.
@@ -114,7 +105,6 @@ Important flags:
   --purge                  (uninstall) Also remove the .draftgo/ directory.
   --skip-update-check      (update) Refresh Skills without contacting npm.
   --connect                (init) Continue into DraftGo server connection.
-  --local-dev              (init) Continue into local Docker setup.
   --no-setup               (init) Install the Skill without either setup flow.
   --output json            Print machine-readable output where supported.
   --type <type>            (map) pages | nav/navigations | docs/articles.
@@ -131,21 +121,19 @@ Important flags:
   --side-effect-policy <mode>
                            (custom-service test) deny | mock | live; default deny.
   --delivery <mode>        (deploy) local | preview | deploy.
-  --dry-run                (push) Show diffs without committing.
-  --ui <mode>              (verify) auto | always | never; auto runs with --url.
+  --dry-run                Preview supported cleanup or delivery operations.
+  --ui <mode>              (verify) always | never; default never.
   --remote                 (check/verify) Compare checkout hashes with remote.
   --viewport <mode>        (verify) mobile | desktop | both.
   --frame <mode>           (verify) auto | top | all | <iframe-selector>.
-  --mobile-check <mode>    (verify-ui compatibility) auto | always | never.
   --token <mode>           (verify) auto | never; auto appends the configured
                            SAT to same-origin URLs as the token query parameter.
-  --screenshot <mode>      (verify) on-failure | always | never; default never.
+  --screenshot <mode>      (verify) always | never; always alone captures a screenshot.
   --browser <name>         (verify) chromium | chrome | msedge.
   --browser-path <file>    (verify) Explicit browser executable; environment
                            fallback: DRAFTGO_BROWSER_PATH.
-  --resource <type:id>     (verify compatibility) Assert one remote UI resource.
   --selector <css>         (verify) Require a visible element in top or iframe DOM.
-  --width/--height <px>    (verify) Override the default 390x844 viewport.
+  --width/--height <px>    (verify) Override the default 1440x900 desktop viewport.
 
 Security:
   .draftgo/config.json stores the server and SAT and is gitignored. Host MCP
@@ -163,14 +151,11 @@ Examples:
   draftgo mcp test
   draftgo map --output json
   draftgo checkout pages 42
-  draftgo check --strict
-  draftgo verify pages 42 --remote --url http://localhost:5173/example
+  draftgo verify pages 42
   draftgo diff pages 42
   draftgo commit pages 42
-  draftgo changelog add "Complete document management and role permissions"
-  draftgo task create "Personal growth" --original "Build a Notion-like system" \
-    --clarified "Build goals, habits, notes, and reviews" \
-    --expected-effect "Users manage personal growth in one workspace"
+  draftgo work start "Build document management and role permissions"
+  draftgo work complete 1 --note "Verification and delivery passed"
   draftgo deploy docs 7 --delivery preview
 `);
 }

package/src/commands/init.js

@@ -3,7 +3,7 @@
 const path = require('path');
 const log = require('../logger');
 const { detectTargets } = require('../detect');
-const { resolveTargets, all } = require('../installers');
+const { resolveTargets, all } = require('../targets');
 const { ensureRuntime, getPackageVersion } = require('../skill');
 const { exists } = require('../fsx');
 const { ask } = require('../prompt');
@@ -76,23 +76,17 @@ async function init(projectDir, positional, flags) {
   const cfgPath = path.join(projectDir, '.draftgo', 'config.json');
   const hasConfig = exists(cfgPath);
   const flagConnect = flags.connect === true;
-  const flagLocalDev = flags['local-dev'] === true;
-  const flagSkip = flags['no-local-dev'] === true
-    || flags['skip-local-dev'] === true
-    || flags['no-setup'] === true;
+  const flagSkip = flags['no-setup'] === true;
   const interactive = process.stdin.isTTY && process.stdout.isTTY;
 
   if (!hasConfig && !flagSkip) {
     // 非交互场景下，如果同时给了 --server 和 --token，直接走 connect，不再阻塞在 TTY 提示上。
-    if (flags.server && flags.token && !flagConnect && !flagLocalDev) {
+    if (flags.server && flags.token && !flagConnect) {
       return await require('./connect')(projectDir, [], flags);
     }
     if (flagConnect) {
       return await require('./connect')(projectDir, [], flags);
     }
-    if (flagLocalDev) {
-      return await require('./localDev')(projectDir, [], flags);
-    }
     if (interactive) {
       log.title('选择 DraftGo 基座处理方式');
       log.plain(`  ${log.c.cyan('[A]')} 连接基座服务`);
@@ -106,7 +100,7 @@ async function init(projectDir, positional, flags) {
         return await require('./connect')(projectDir, [], flags);
       }
       if (choice === 'B') {
-        return await require('./localDev')(projectDir, [], { ...flags, yes: true });
+        return await require('../localRuntime').runWizard(projectDir, { yes: true });
       }
       if (choice !== 'C') {
         log.warn('无效选择，已跳过基座处理。');

package/src/commands/listTargets.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { all } = require('../installers');
+const { all } = require('../targets');
 
 function listTargets() {
   console.log('draftgo 支持的 AI 工具（target）:');

package/src/commands/local.js

@@ -4,8 +4,8 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { exists } = require('../fsx');
-const { detectDocker } = require('../localdev/detect');
-const { runWizard } = require('../localdev');
+const { detectDocker } = require('../localRuntime/detect');
+const { runWizard } = require('../localRuntime');
 
 function composeFile(projectDir) {
   return path.join(projectDir, '.draftgo', 'docker', 'docker-compose.yaml');
@@ -58,21 +58,17 @@ function local(projectDir, positional, flags = {}) {
   switch (action) {
     case 'setup':
       return runWizard(projectDir, { yes: !!(flags.yes || flags.y) });
-    case 'up':
     case 'start':
       return runCompose(projectDir, ['up', '-d']);
-    case 'down':
     case 'stop':
       return runCompose(projectDir, ['down']);
     case 'logs':
       return runCompose(projectDir, ['logs', ...(positional.slice(1).length ? positional.slice(1) : ['-f', 'app'])]);
     case 'status':
-    case 'ps':
       return runCompose(projectDir, ['ps']);
     default:
       log.err(`未知 local 子命令：${action}`);
       log.dim('  可用：draftgo local setup | start | stop | logs | status');
-      log.dim('  兼容别名：up | down');
       return 1;
   }
 }

package/src/commands/map.js

@@ -1,7 +1,5 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
 const log = require('../logger');
 const { loadProjectConfig } = require('../projectConfig');
 const { canonicalResourceType } = require('../worktree/types');
@@ -84,11 +82,6 @@ async function listRemoteResources(session, resourceTypes = DEFAULT_REMOTE_RESOU
   return groups.flat();
 }
 
-function legacyCaches(projectDir) {
-  return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
-    .filter((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
-}
-
 function checkoutChanged(entry) {
   if (entry.resource_type === 'custom_services') {
     return ['local_modified', 'diverged', 'committed_unrecorded'].includes(entry.state);
@@ -126,7 +119,6 @@ async function mapCommand(projectDir, flags = {}) {
     overview,
     resources,
     checkouts,
-    legacy_cache: { ignored: true, detected: legacyCaches(projectDir) },
   };
 
   if (flags.output === 'json') {
@@ -149,9 +141,6 @@ async function mapCommand(projectDir, flags = {}) {
       + `version=${entry.manifest_version ?? '-'}->${entry.remote_version ?? '-'} `
       + `(${entry.local_path})`);
   }
-  if (result.legacy_cache.detected.length) {
-    log.warn(`Ignored legacy cache indexes: ${result.legacy_cache.detected.join(', ')}`);
-  }
   return 0;
 }
 

package/src/commands/status.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const log = require('../logger');
-const { all } = require('../installers');
+const { all } = require('../targets');
 const { readInstalledVersion, getPackageVersion } = require('../skill');
 
 function status(projectDir) {

package/src/commands/uninstall.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const log = require('../logger');
-const { all, resolveTargets } = require('../installers');
+const { all, resolveTargets } = require('../targets');
 const { removePath } = require('../fsx');
 const { dgDir } = require('../paths');
 
@@ -38,10 +38,10 @@ async function uninstall(projectDir, positional, flags) {
 
   // Each AI-tool skill directory is self-contained, so per-target uninstall
   // already wiped its content above. Only --purge nukes runtime data under
-  // .draftgo/ (config/changelog/Task/lessons/cache etc.).
+  // .draftgo/ (config/worklog/lessons/cache etc.).
   if (flags.purge) {
     if (removePath(dgDir(projectDir))) {
-      log.warn('已使用 --purge：.draftgo/（含 config/changelog/lessons/Task 等运行时数据）已删除。');
+      log.warn('已使用 --purge：.draftgo/（含 config/worklog/lessons 等运行时数据）已删除。');
     }
   }
 

package/src/commands/update.js

@@ -2,7 +2,7 @@
 
 const { spawnSync } = require('child_process');
 const log = require('../logger');
-const { all, byName, resolveTargets } = require('../installers');
+const { all, byName, resolveTargets } = require('../targets');
 const { ensureRuntime, writeInstalledVersion, readInstalledVersion, getPackageVersion } = require('../skill');
 const { fetchLatestVersion, cmpSemver } = require('../updateCheck');
 const { detectTargets } = require('../detect');

package/src/commands/verify.js

@@ -2,12 +2,12 @@
 
 const log = require('../logger');
 const check = require('./check');
-const verifyUi = require('./verifyUi');
+const visualVerify = require('./visualVerify');
 const { canonicalResourceType } = require('../worktree/types');
 
 function mode(value, fallback, flag) {
   const normalized = String(value == null ? fallback : value).toLowerCase();
-  if (!['auto', 'always', 'never'].includes(normalized)) throw new Error(`${flag} must be auto, always, or never.`);
+  if (!['always', 'never'].includes(normalized)) throw new Error(`${flag} must be always or never.`);
   return normalized;
 }
 
@@ -21,7 +21,11 @@ function resources(positional) {
 
 function viewports(flags) {
   const value = String(flags.viewport || '').toLowerCase();
-  if (!value) return [{ name: 'custom', width: flags.width, height: flags.height }];
+  if (!value) return [{
+    name: flags.width || flags.height ? 'custom' : 'desktop',
+    width: flags.width || 1440,
+    height: flags.height || 900,
+  }];
   if (value === 'mobile') return [{ name: 'mobile', width: 390, height: 844 }];
   if (value === 'desktop') return [{ name: 'desktop', width: 1440, height: 900 }];
   if (value === 'both') return [
@@ -31,13 +35,29 @@ function viewports(flags) {
   throw new Error('--viewport must be mobile, desktop, or both.');
 }
 
+function visualRequest(flags, url) {
+  const uiMode = mode(flags.ui, 'never', '--ui');
+  const screenshotMode = String(flags.screenshot || 'never').toLowerCase();
+  if (!['always', 'never'].includes(screenshotMode)) {
+    throw new Error('--screenshot must be always or never.');
+  }
+  const screenshotRequested = screenshotMode !== 'never';
+  if ((uiMode === 'always' || screenshotRequested) && !url) {
+    throw new Error('Visual verification requires --url <http://localhost:port/path>.');
+  }
+  return {
+    uiMode,
+    screenshotMode,
+    captureOnly: uiMode === 'never' && screenshotMode === 'always',
+    run: Boolean(url) && (uiMode === 'always' || screenshotRequested),
+  };
+}
+
 async function verify(projectDir, positional = [], flags = {}) {
   let selected;
-  let uiMode;
   let remoteMode;
   try {
     selected = resources(positional);
-    uiMode = mode(flags.ui, 'auto', '--ui');
     remoteMode = flags.remote ? 'always' : 'never';
   } catch (error) {
     log.err(error.message);
@@ -55,31 +75,32 @@ async function verify(projectDir, positional = [], flags = {}) {
   if (checkCode !== 0) return checkCode;
 
   const url = String(flags.url || '').trim();
-  const runUi = uiMode === 'always' || (uiMode === 'auto' && Boolean(url));
-  if (!runUi) {
-    if (uiMode === 'always' && !url) {
-      log.err('--ui always requires --url <http://localhost:port/path>.');
-      return 1;
-    }
+  let visual;
+  try { visual = visualRequest(flags, url); }
+  catch (error) { log.err(error.message); return 1; }
+  if (!visual.run) {
+    if (url) log.warn('--url was provided without --screenshot always or --ui always; visual verification was skipped.');
     log.ok('Unified verification passed (UI skipped).');
     return 0;
   }
-  if (selected.length > 1) {
-    log.err('One --url can assert at most one resource. Run verify once per route for UI validation.');
-    return 1;
-  }
-
   let targets;
   try { targets = viewports(flags); }
   catch (error) { log.err(error.message); return 1; }
   for (const viewport of targets) {
-    const uiFlags = { ...flags, url, width: viewport.width, height: viewport.height, 'mobile-check': 'always' };
-    if (remoteMode === 'always' && selected.length === 1 && !uiFlags.resource) {
-      uiFlags.resource = `${selected[0].resourceType}:${selected[0].resourceId}`;
-    }
-    const code = await verifyUi(projectDir, [url], uiFlags);
+    const uiFlags = {
+      ...flags,
+      url,
+      width: viewport.width,
+      height: viewport.height,
+      'capture-only': visual.captureOnly,
+    };
+    const code = await visualVerify(projectDir, [url], uiFlags);
     if (code !== 0) return code;
   }
+  if (visual.captureOnly) {
+    log.ok(`Visual capture completed (${targets.map((item) => item.name).join(', ')}).`);
+    return 0;
+  }
   log.ok(`Unified verification passed (${targets.map((item) => item.name).join(', ')}).`);
   return 0;
 }
@@ -88,3 +109,4 @@ module.exports = verify;
 module.exports.mode = mode;
 module.exports.resources = resources;
 module.exports.viewports = viewports;
+module.exports.visualRequest = visualRequest;

package/src/commands/{verifyUi.js → visualVerify.js}

@@ -3,53 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 const runtimeFiles = require('../runtimeFiles');
-const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { configPath, loadProjectConfig } = require('../projectConfig');
-const { loadManifest, getEntry } = require('../worktree/manifest');
-const { canonicalResourceType } = require('../worktree/types');
-const { resolveMetadata } = require('../worktree/backend');
-const { inspectEntry, openMetadataSession } = require('../worktree/status');
-
-const UI_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte']);
-
-function isUiFile(file) {
-  const normalized = String(file || '').replace(/\\/g, '/').toLowerCase();
-  const ext = path.extname(normalized);
-  if (UI_EXTENSIONS.has(ext)) return true;
-  if (!['.js', '.ts'].includes(ext)) return false;
-  return /(^|\/)(frontend|web|ui|components|pages|views|client)(\/|$)/.test(normalized)
-    || /(^|\/)(app|main|client)\.(js|ts)$/.test(normalized)
-    || normalized.startsWith('.draftgo/worktree/pages/')
-    || normalized.startsWith('.draftgo/worktree/navigations/')
-    || normalized.startsWith('.draftgo/worktree/docs/');
-}
-
-function gitChangedFiles(projectDir) {
-  const r = spawnSync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
-    cwd: projectDir,
-    encoding: 'utf8',
-    shell: false,
-  });
-  if (r.error || r.status !== 0) return null;
-  return String(r.stdout || '').split(/\r?\n/).filter(Boolean).map((line) => {
-    const raw = line.slice(3).trim();
-    const renamed = raw.includes(' -> ') ? raw.split(' -> ').pop() : raw;
-    return renamed.replace(/^"|"$/g, '');
-  });
-}
-
-function decideMobileCheck(projectDir, mode) {
-  if (mode === 'always') return { run: true, reason: 'mobile-check=always' };
-  if (mode === 'never') return { run: false, reason: 'mobile-check=never' };
-  const changed = gitChangedFiles(projectDir);
-  if (changed === null || changed.length === 0) {
-    return { run: true, reason: '无法从 Git diff 确认影响范围，执行单视口 smoke check' };
-  }
-  const uiFiles = changed.filter(isUiFile);
-  if (!uiFiles.length) return { run: false, reason: '本次变更未涉及页面、样式或前端组件' };
-  return { run: true, reason: `检测到 ${uiFiles.length} 个 UI 文件变更` };
-}
 
 function numberFlag(value, fallback, min, max) {
   const n = Number(value);
@@ -154,15 +109,6 @@ async function launchBrowser(chromium, requested, requestedPath) {
     + (lastError ? `；最后错误：${lastError.message.split('\n')[0]}` : ''));
 }
 
-function parseResourceSpec(value) {
-  const raw = String(value || '');
-  const separator = raw.indexOf(':');
-  if (separator <= 0 || separator === raw.length - 1) {
-    throw new Error('--resource 格式必须是 <pages|nav|docs>:<id>。');
-  }
-  return { resourceType: canonicalResourceType(raw.slice(0, separator)), resourceId: raw.slice(separator + 1) };
-}
-
 async function selectFrames(page, mode = 'auto') {
   const top = page.mainFrame ? page.mainFrame() : page;
   const selected = [{ frame: top, label: 'top' }];
@@ -208,50 +154,33 @@ async function inspectFrame(frame) {
   });
 }
 
-async function verifyRemoteResource(projectDir, spec) {
-  const { resourceType, resourceId } = parseResourceSpec(spec);
-  const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
-  if (!entry) throw new Error(`${resourceType} ${resourceId} 未 checkout。`);
-  const config = loadProjectConfig(projectDir);
-  const session = await openMetadataSession(config);
-  const remote = await resolveMetadata(config, resourceType, resourceId, {
-    ...session,
-    clientInitialized: true,
-  });
-  return inspectEntry(projectDir, entry, remote);
+async function captureScreenshot(projectDir, page) {
+  const dir = path.join(projectDir, '.draftgo', 'artifacts', 'ui');
+  fs.mkdirSync(dir, { recursive: true });
+  const screenshotPath = path.join(dir, `ui-check-${process.pid}-${Date.now()}.png`);
+  await page.screenshot({ path: screenshotPath, fullPage: true });
+  runtimeFiles.register(projectDir, screenshotPath, 'ui-artifact', 'verify');
+  return screenshotPath;
 }
 
-async function verifyUi(projectDir, positional, flags = {}) {
+async function visualVerify(projectDir, positional, flags = {}) {
   const rawUrl = String(flags.url || positional[0] || '').trim();
   if (!/^https?:\/\//i.test(rawUrl)) {
-    log.err('用法：draftgo verify-ui <http://localhost:port/path>');
+    log.err('Usage: draftgo verify --url <http://localhost:port/path> --screenshot always|--ui always');
     return 1;
   }
 
   const tokenMode = String(flags.token || 'auto').toLowerCase();
   if (!['auto', 'never'].includes(tokenMode)) {
-    log.err('--token 在 verify-ui 中只支持 auto、never。');
+    log.err('--token in visual verification accepts auto or never.');
     return 1;
   }
 
-  const mode = String(flags['mobile-check'] || 'auto').toLowerCase();
-  if (!['auto', 'always', 'never'].includes(mode)) {
-    log.err('--mobile-check 只支持 auto、always、never。');
-    return 1;
-  }
-  const decision = flags.resource
-    ? { run: true, reason: `resource=${flags.resource}` }
-    : decideMobileCheck(projectDir, mode);
-  if (!decision.run) {
-    log.ok(`跳过 UI smoke check：${decision.reason}`);
-    return 0;
-  }
-
   let url;
   try {
     url = configuredUiUrl(projectDir, rawUrl, tokenMode);
   } catch (err) {
-    log.err(`无法读取 verify-ui 的项目配置：${err.message}`);
+    log.err(`Unable to read visual verification config: ${err.message}`);
     return 1;
   }
 
@@ -263,30 +192,18 @@ async function verifyUi(projectDir, positional, flags = {}) {
     return 1;
   }
 
-  const width = numberFlag(flags.width, 390, 240, 3840);
-  const height = numberFlag(flags.height, 844, 320, 2160);
+  const width = numberFlag(flags.width, 1440, 240, 3840);
+  const height = numberFlag(flags.height, 900, 320, 2160);
   const waitMs = numberFlag(flags['wait-ms'], 500, 0, 10000);
   const screenshotMode = String(flags.screenshot || 'never').toLowerCase();
-  if (!['on-failure', 'always', 'never'].includes(screenshotMode)) {
-    log.err('--screenshot 只支持 on-failure、always、never。');
+  if (!['always', 'never'].includes(screenshotMode)) {
+    log.err('--screenshot accepts always or never.');
     return 1;
   }
 
   let browser;
   try {
-    if (flags.resource) {
-      const resource = await verifyRemoteResource(projectDir, flags.resource);
-      log.info(`UI source: remote committed ${resource.resource_type} ${resource.resource_id}`);
-      log.info(`Remote version: ${resource.remote_version || '-'}; remote hash: ${resource.remote_hash || '-'}`);
-      if (['local_modified', 'diverged'].includes(resource.state)) {
-        log.warn(`Local worktree is not committed (${resource.state}); verify-ui will test the remote version.`);
-      }
-      if (!resource.local_matches_remote && resource.state !== 'local_modified') {
-        throw new Error(`Local and remote content differ (${resource.state}); UI verification stopped.`);
-      }
-    } else {
-      log.info('UI source: remote URL response; no local worktree version was asserted.');
-    }
+    log.info('UI source: requested URL response.');
     const launch = await launchBrowser(
       chromium,
       flags.browser && String(flags.browser),
@@ -302,6 +219,15 @@ async function verifyUi(projectDir, positional, flags = {}) {
 
     const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
     if (waitMs) await page.waitForTimeout(waitMs);
+    let screenshotPath = null;
+    if (screenshotMode === 'always' || flags['capture-only']) {
+      screenshotPath = await captureScreenshot(projectDir, page);
+    }
+    if (flags['capture-only']) {
+      log.ok(`截图已生成：${width}x${height}`);
+      log.info(`截图：${screenshotPath}`);
+      return 0;
+    }
     const frames = await selectFrames(page, String(flags.frame || 'auto'));
     const states = [];
     for (const item of frames) states.push({ ...item, state: await inspectFrame(item.frame) });
@@ -326,16 +252,6 @@ async function verifyUi(projectDir, positional, flags = {}) {
       else log.info(`Selector ${flags.selector}: visible in ${match}`);
     }
 
-    const shouldScreenshot = screenshotMode === 'always' || (screenshotMode === 'on-failure' && issues.length > 0);
-    let screenshotPath = null;
-    if (shouldScreenshot) {
-      const dir = path.join(projectDir, '.draftgo', 'artifacts', 'ui');
-      fs.mkdirSync(dir, { recursive: true });
-      screenshotPath = path.join(dir, `ui-check-${process.pid}-${Date.now()}.png`);
-      await page.screenshot({ path: screenshotPath, fullPage: true });
-      runtimeFiles.register(projectDir, screenshotPath, 'ui-artifact', 'verify-ui');
-    }
-
     if (issues.length) {
       issues.forEach((issue) => log.err(issue));
       if (consoleErrors.length) consoleErrors.slice(0, 5).forEach((msg) => log.dim(`  console: ${msg}`));
@@ -344,7 +260,7 @@ async function verifyUi(projectDir, positional, flags = {}) {
       return 1;
     }
 
-    log.ok(`UI smoke check 通过：${width}x${height}，${frames.length} frame(s)，${decision.reason}`);
+    log.ok(`UI smoke check passed: ${width}x${height}, ${frames.length} frame(s).`);
     if (screenshotPath) log.info(`截图：${screenshotPath}`);
     return 0;
   } catch (err) {
@@ -355,15 +271,11 @@ async function verifyUi(projectDir, positional, flags = {}) {
   }
 }
 
-module.exports = verifyUi;
-module.exports.decideMobileCheck = decideMobileCheck;
-module.exports.gitChangedFiles = gitChangedFiles;
-module.exports.isUiFile = isUiFile;
+module.exports = visualVerify;
 module.exports.configuredUiUrl = configuredUiUrl;
 module.exports.redactUrlTokens = redactUrlTokens;
 module.exports.executableCandidates = executableCandidates;
 module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
-module.exports.parseResourceSpec = parseResourceSpec;
-module.exports.verifyRemoteResource = verifyRemoteResource;
 module.exports.selectFrames = selectFrames;
 module.exports.inspectFrame = inspectFrame;
+module.exports.captureScreenshot = captureScreenshot;