draftgo-cli 3.0.49 → 3.0.52

package/src/commands/task.js

@@ -0,0 +1,408 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const log = require('../logger');
+const runtimeFiles = require('../runtimeFiles');
+
+const TASK_ROOT = path.join('.draftgo', 'Task');
+const TASK_FILENAME = 'Task.md';
+const REQUIRED_ITEM_FIELDS = ['内容', '负责人', '验收'];
+
+function root(projectDir) { return path.join(projectDir, TASK_ROOT); }
+function taskDir(projectDir, id) { return path.join(root(projectDir), String(id)); }
+function markdownFile(projectDir, id) { return path.join(taskDir(projectDir, id), TASK_FILENAME); }
+function legacyFile(projectDir, id) { return path.join(taskDir(projectDir, id), 'task.yaml'); }
+
+function atomicWrite(file, value, options = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temp, value, 'utf8');
+  try { runtimeFiles.replaceFile(temp, file, options.rename, options.wait); } catch (error) {
+    try { fs.rmSync(temp, { force: true }); } catch { /* retain the original rename error */ }
+    throw error;
+  }
+}
+
+function withLock(projectDir, taskId, action) {
+  const file = path.join(taskDir(projectDir, taskId), '.lock');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let descriptor;
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    try { descriptor = fs.openSync(file, 'wx'); break; } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const started = Date.now(); while (Date.now() - started < 20) { /* short lock wait */ }
+    }
+  }
+  if (descriptor === undefined) throw new Error(`Task ${taskId} is locked by another Agent.`);
+  try {
+    fs.writeFileSync(descriptor, `${process.pid}\n`);
+    const target = markdownFile(projectDir, taskId);
+    const before = fs.existsSync(target) ? digest(fs.readFileSync(target)) : null;
+    return action(before);
+  } finally {
+    fs.closeSync(descriptor);
+    fs.rmSync(file, { force: true });
+  }
+}
+
+function digest(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
+function normalizeNewlines(value) { return String(value || '').replace(/\r\n/g, '\n'); }
+function slugify(value) {
+  return String(value || '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48) || 'task';
+}
+function today(flags = {}) { return String(flags.date || new Date().toISOString().slice(0, 10)); }
+function uniqueTaskId(projectDir, title, flags = {}) {
+  const requested = String(flags.id || '').trim();
+  let base;
+  if (/^\[\d{4}-\d{2}-\d{2}\][a-z0-9][a-z0-9-]*$/.test(requested)) base = requested;
+  else base = `[${today(flags)}]${slugify(requested || title)}`;
+  let candidate = base; let suffix = 2;
+  while (fs.existsSync(taskDir(projectDir, candidate))) { candidate = `${base}-${suffix}`; suffix += 1; }
+  return candidate;
+}
+function field(flags, names, fallback = '') {
+  for (const name of names) if (flags[name] !== undefined) return String(flags[name]).trim();
+  return fallback;
+}
+function lines(value, fallback = '- 暂无。') {
+  const text = String(value || '').trim();
+  if (!text) return fallback;
+  return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+    .map((line) => line.startsWith('- ') ? line : `- ${line}`).join('\n');
+}
+
+function template(task) {
+  return `# ${task.title}\n\n`+
+    `- 状态：active\n- 创建时间：${task.created_at}\n- 更新时间：${task.updated_at}\n\n`+
+    `## 用户原始需求\n\n${task.original_requirement}\n\n`+
+    `## 明确后的需求\n\n${task.clarified_requirement}\n\n`+
+    `## 预计效果\n\n${lines(task.expected_effect)}\n\n`+
+    `## 本次范围\n\n${lines(task.scope)}\n\n`+
+    `## 不在本次范围\n\n${lines(task.out_of_scope)}\n\n`+
+    '## 开发清单\n\n' +
+    '暂无。\n\n' +
+    '## 关键决策\n\n- 暂无。\n\n' +
+    '## 阻塞问题\n\n- 暂无。\n\n' +
+    '## 最终验收\n\n' +
+    '- [ ] 所有开发项完成\n' +
+    '- [ ] 完成验证\n' +
+    '- [ ] changelog 已写入\n';
+}
+
+function section(body, name) {
+  const pattern = new RegExp(`^## ${escapeRegExp(name)}\\s*$`, 'm');
+  const match = pattern.exec(body);
+  if (!match) return '';
+  const start = match.index + match[0].length;
+  const rest = body.slice(start);
+  const next = /^##\s+/m.exec(rest);
+  return rest.slice(0, next ? next.index : rest.length).trim();
+}
+function escapeRegExp(value) { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function metadata(body, name) {
+  const match = body.match(new RegExp(`^- ${escapeRegExp(name)}[：:]\\s*(.*)$`, 'm'));
+  return match ? match[1].trim() : '';
+}
+function parseChecklist(text, final = false) {
+  const body = normalizeNewlines(text); const entries = [];
+  const pattern = /^- \[([ xX])\]\s+(.+)$/gm; const matches = [...body.matchAll(pattern)];
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index]; const start = match.index; const end = index + 1 < matches.length ? matches[index + 1].index : body.length;
+    const block = body.slice(start, end).trimEnd();
+    if (final) {
+      entries.push({ title: match[2].trim(), completed: match[1].toLowerCase() === 'x', block });
+      continue;
+    }
+    const heading = match[2].trim().match(/^(DG-\d{3})\s+(.+)$/);
+    if (!heading) continue;
+    const fields = {};
+    for (const line of block.split('\n').slice(1)) {
+      const detail = line.match(/^\s{2,}-\s+([^：:]+)[：:]\s*(.*)$/);
+      if (detail) fields[detail[1].trim()] = detail[2].trim();
+    }
+    entries.push({ id: heading[1], title: heading[2], completed: match[1].toLowerCase() === 'x', status: fields['状态'] || (match[1].toLowerCase() === 'x' ? 'completed' : 'pending'), fields, block });
+  }
+  return entries;
+}
+
+function parseMarkdown(file, id) {
+  const body = normalizeNewlines(fs.readFileSync(file, 'utf8'));
+  const title = (body.match(/^#\s+(.+)$/m) || [null, id])[1].trim();
+  const items = parseChecklist(section(body, '开发清单'));
+  const acceptance = parseChecklist(section(body, '最终验收'), true);
+  return {
+    schema_version: 2, format: 'markdown', id, title, status: metadata(body, '状态') || 'active',
+    created_at: metadata(body, '创建时间'), updated_at: metadata(body, '更新时间'),
+    original_requirement: section(body, '用户原始需求'), clarified_requirement: section(body, '明确后的需求'),
+    expected_effect: section(body, '预计效果'), scope: section(body, '本次范围'), out_of_scope: section(body, '不在本次范围'),
+    decisions: section(body, '关键决策'), blockers: section(body, '阻塞问题'), items, acceptance,
+    completed_items: items.filter((item) => item.completed).length, total_items: items.length,
+    body, file,
+  };
+}
+
+function unquote(value) {
+  const text = String(value || '').trim();
+  if (text === '[]') return [];
+  try { return JSON.parse(text); } catch { return text.replace(/^['"]|['"]$/g, ''); }
+}
+function parseLegacy(file, id) {
+  const body = normalizeNewlines(fs.readFileSync(file, 'utf8')); const result = { schema_version: 1, format: 'legacy', id, items: [], body, file };
+  let current = null;
+  for (const line of body.split('\n')) {
+    const item = line.match(/^\s*-\s+id:\s*(.+)$/);
+    if (item) { current = { id: unquote(item[1]) }; result.items.push(current); continue; }
+    const value = line.match(/^(\w+):\s*(.*)$/) || line.match(/^\s{4}(\w+):\s*(.*)$/);
+    if (!value) continue;
+    if (!line.startsWith('    ') && value[1] === 'items') continue;
+    const target = line.startsWith('    ') && current ? current : result;
+    target[value[1]] = unquote(value[2]);
+  }
+  result.completed_items = result.items.filter((item) => item.status === 'completed').length;
+  result.total_items = result.items.length;
+  return result;
+}
+
+function resolveTaskId(projectDir, value) {
+  const requested = String(value || '').trim();
+  if (!requested) throw new Error('Task id is required.');
+  if (fs.existsSync(taskDir(projectDir, requested))) return requested;
+  const directory = root(projectDir);
+  if (!fs.existsSync(directory)) throw new Error(`Task ${requested} does not exist.`);
+  const shortName = new RegExp(`^\\[\\d{4}-\\d{2}-\\d{2}\\]${escapeRegExp(requested)}(?:-\\d+)?$`);
+  const matches = fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && (entry.name === requested || shortName.test(entry.name)));
+  if (matches.length === 1) return matches[0].name;
+  if (matches.length > 1) throw new Error(`Task ${requested} is ambiguous; use its full directory name.`);
+  throw new Error(`Task ${requested} does not exist.`);
+}
+function loadTask(projectDir, value) {
+  const id = resolveTaskId(projectDir, value);
+  const modern = markdownFile(projectDir, id); const legacy = legacyFile(projectDir, id);
+  if (fs.existsSync(modern)) return parseMarkdown(modern, id);
+  if (fs.existsSync(legacy)) return parseLegacy(legacy, id);
+  throw new Error(`Task ${id} has no ${TASK_FILENAME} or task.yaml.`);
+}
+function publicTask(task) {
+  const result = { ...task }; delete result.body; delete result.file; return result;
+}
+function print(flags, value) {
+  if (flags.output === 'json') console.log(JSON.stringify(Array.isArray(value) ? value.map(publicTask) : publicTask(value), null, 2));
+}
+function taskActor(flags) { return String(flags.owner || flags.assignee || process.env.DRAFTGO_AGENT_ID || '').trim(); }
+function assertModern(task, operation) {
+  if (task.format === 'legacy') throw new Error(`Legacy Task ${task.id} is read-only; run task migrate ${task.id} before ${operation}.`);
+}
+function saveBody(task, body, beforeHash) {
+  const current = fs.readFileSync(task.file);
+  if (beforeHash && digest(current) !== beforeHash) throw new Error(`Task ${task.id} changed while it was being updated; retry the command.`);
+  atomicWrite(task.file, body.endsWith('\n') ? body : `${body}\n`);
+}
+function replaceMetadata(body, name, value) {
+  const pattern = new RegExp(`^- ${escapeRegExp(name)}[：:].*$`, 'm');
+  if (!pattern.test(body)) throw new Error(`Task.md is missing metadata field ${name}.`);
+  return body.replace(pattern, `- ${name}：${value}`);
+}
+function touch(task, body, status) {
+  let result = replaceMetadata(body, '更新时间', new Date().toISOString());
+  if (status) result = replaceMetadata(result, '状态', status);
+  return result;
+}
+function replaceSection(body, name, content) {
+  const pattern = new RegExp(`(^## ${escapeRegExp(name)}\\s*$\\n)([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, 'm');
+  if (!pattern.test(body)) throw new Error(`Task.md is missing section ${name}.`);
+  return body.replace(pattern, `$1\n${content.trim()}\n\n`);
+}
+function replaceItemBlock(task, itemId, replacement) {
+  const checklist = section(task.body, '开发清单'); const item = task.items.find((entry) => entry.id === itemId);
+  if (!item) throw new Error(`Task item ${itemId} does not exist.`);
+  return replaceSection(task.body, '开发清单', checklist.replace(item.block, replacement));
+}
+function upsertItemField(block, name, value) {
+  const pattern = new RegExp(`^  - ${escapeRegExp(name)}[：:].*$`, 'm');
+  if (pattern.test(block)) return block.replace(pattern, `  - ${name}：${value}`);
+  return `${block.trimEnd()}\n  - ${name}：${value}`;
+}
+function validateItemFields(item) {
+  const missing = REQUIRED_ITEM_FIELDS.filter((name) => !String(item.fields[name] || '').trim());
+  if (missing.length) throw new Error(`${item.id} is missing required field(s): ${missing.join(', ')}.`);
+}
+
+function create(projectDir, positional, flags) {
+  const title = field(flags, ['title'], positional.join(' '));
+  if (!title) throw new Error('task create requires a title or --title.');
+  const original = field(flags, ['original', 'original-requirement', 'description']);
+  const clarified = field(flags, ['clarified', 'clarified-requirement'], original);
+  const expected = field(flags, ['expected-effect', 'effect']);
+  if (!original) throw new Error('task create requires --original with the user requirement.');
+  if (!clarified) throw new Error('task create requires --clarified with the executable requirement.');
+  if (!expected) throw new Error('task create requires --expected-effect.');
+  const id = uniqueTaskId(projectDir, title, flags); const now = new Date().toISOString();
+  const task = { id, title, created_at: now, updated_at: now, original_requirement: original, clarified_requirement: clarified,
+    expected_effect: expected, scope: field(flags, ['scope']), out_of_scope: field(flags, ['out-of-scope']) };
+  fs.mkdirSync(taskDir(projectDir, id), { recursive: true }); atomicWrite(markdownFile(projectDir, id), template(task));
+  const loaded = loadTask(projectDir, id); print(flags, loaded); if (flags.output !== 'json') log.ok(`Created task ${id}`); return 0;
+}
+
+function list(projectDir, flags) {
+  const tasks = []; const directory = root(projectDir);
+  if (fs.existsSync(directory)) for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    try { tasks.push(loadTask(projectDir, entry.name)); } catch { /* ignore non-task directories */ }
+  }
+  tasks.sort((left, right) => String(right.updated_at || '').localeCompare(String(left.updated_at || '')));
+  print(flags, tasks);
+  if (flags.output !== 'json') tasks.forEach((task) => log.info(`${task.id} [${task.status}] ${task.title} (${task.completed_items}/${task.total_items})${task.format === 'legacy' ? ' [legacy]' : ''}`));
+  return 0;
+}
+
+function show(projectDir, taskId, flags) {
+  const task = loadTask(projectDir, taskId); print(flags, task);
+  if (flags.output !== 'json') {
+    const next = task.items.find((item) => !item.completed);
+    log.info(`${task.id} [${task.status}] ${task.title}\nProgress: ${task.completed_items}/${task.total_items}\n${next ? `Next: ${next.id} ${next.title}` : 'Next: final acceptance'}`);
+  }
+  return 0;
+}
+
+function nextItemId(items) {
+  const highest = items.reduce((max, item) => Math.max(max, Number(item.id.match(/^DG-(\d+)$/)?.[1] || 0)), 0);
+  return `DG-${String(highest + 1).padStart(3, '0')}`;
+}
+function add(projectDir, taskId, positional, flags) {
+  const resolved = resolveTaskId(projectDir, taskId);
+  return withLock(projectDir, resolved, (before) => {
+    const task = loadTask(projectDir, resolved); assertModern(task, 'add');
+    const title = field(flags, ['title'], positional.join(' ')); const content = field(flags, ['content']); const acceptance = field(flags, ['acceptance']);
+    const owner = field(flags, ['assignee'], taskActor(flags));
+    if (!title) throw new Error('task add requires a title or --title.');
+    if (!content) throw new Error('task add requires --content.');
+    if (!owner) throw new Error('task add requires --assignee or owner identity.');
+    if (!acceptance) throw new Error('task add requires --acceptance.');
+    const id = String(flags.id || nextItemId(task.items));
+    if (!/^DG-\d{3}$/.test(id)) throw new Error('Task item id must use DG-001 format.');
+    if (task.items.some((item) => item.id === id)) throw new Error(`Task item ${id} already exists.`);
+    let block = `- [ ] ${id} ${title}\n  - 内容：${content}\n  - 负责人：${owner}`;
+    const moduleLogic = field(flags, ['module-logic']); const userJourney = field(flags, ['user-journey']);
+    if (moduleLogic) block += `\n  - 模块逻辑：${moduleLogic}`;
+    if (userJourney) block += `\n  - 用户路线：${userJourney}`;
+    block += `\n  - 验收：${acceptance}`;
+    const current = section(task.body, '开发清单'); const contentSection = current === '暂无。' ? block : `${current.trimEnd()}\n\n${block}`;
+    const body = touch(task, replaceSection(task.body, '开发清单', contentSection), 'active'); saveBody(task, body, before);
+    const updated = loadTask(projectDir, resolved); const item = updated.items.find((entry) => entry.id === id); print(flags, item);
+    if (flags.output !== 'json') log.ok(`Added ${id}`); return 0;
+  });
+}
+
+function mutate(projectDir, taskId, itemId, operation, flags, trailing = []) {
+  const resolved = resolveTaskId(projectDir, taskId);
+  return withLock(projectDir, resolved, (before) => {
+    const task = loadTask(projectDir, resolved); assertModern(task, operation); const item = task.items.find((entry) => entry.id === itemId);
+    if (!item) throw new Error(`Task item ${itemId} does not exist.`); validateItemFields(item);
+    const actor = taskActor(flags); if (!actor) throw new Error(`${itemId} requires an owner identity; pass --owner/--assignee or set DRAFTGO_AGENT_ID.`);
+    const assigned = item.fields['负责人']; if (assigned && assigned !== actor && operation !== 'claim') throw new Error(`${itemId} can only be updated by owner ${assigned}.`);
+    if (operation === 'claim' && assigned && assigned !== actor) throw new Error(`${itemId} is already owned by ${assigned}.`);
+    let block = item.block;
+    if (operation === 'complete') {
+      const evidence = field(flags, ['evidence'], trailing.join(' '));
+      if (!evidence) throw new Error(`${itemId} requires --evidence before completion.`);
+      block = block.replace(/^- \[[ xX]\]/, '- [x]'); block = upsertItemField(block, '状态', 'completed'); block = upsertItemField(block, '完成结果', evidence);
+    } else if (operation === 'block') {
+      const reason = field(flags, ['evidence'], trailing.join(' ')); if (!reason) throw new Error(`${itemId} block requires a reason.`);
+      block = block.replace(/^- \[[ xX]\]/, '- [ ]'); block = upsertItemField(block, '状态', 'blocked'); block = upsertItemField(block, '阻塞原因', reason);
+    } else if (operation === 'reopen') {
+      block = block.replace(/^- \[[ xX]\]/, '- [ ]'); block = upsertItemField(block, '状态', 'pending');
+    } else {
+      block = upsertItemField(block, '负责人', actor); block = upsertItemField(block, '状态', operation === 'start' ? 'in_progress' : 'claimed');
+    }
+    let body = replaceItemBlock(task, itemId, block); let reloaded = { ...task, body };
+    const items = parseChecklist(section(body, '开发清单'));
+    if (items.length && items.every((entry) => entry.completed)) body = updateAcceptanceBody(body, '所有开发项完成', true, 'CLI automatically confirmed all development items.');
+    else body = updateAcceptanceBody(body, '所有开发项完成', false, 'Development work is still open.');
+    body = touch(reloaded, body, 'active'); saveBody(task, body, before);
+    const updated = loadTask(projectDir, resolved).items.find((entry) => entry.id === itemId); print(flags, updated);
+    if (flags.output !== 'json') log.ok(`${itemId}: ${updated.status}`); return 0;
+  });
+}
+
+function updateAcceptanceBody(body, title, completed, evidence) {
+  const current = section(body, '最终验收'); const entries = parseChecklist(current, true); const target = entries.find((entry) => entry.title === title);
+  if (!target) throw new Error(`Final acceptance item ${title} does not exist.`);
+  let block = target.block.replace(/^- \[[ xX]\]/, completed ? '- [x]' : '- [ ]');
+  if (evidence) block = upsertItemField(block, '验证结果', evidence);
+  return replaceSection(body, '最终验收', current.replace(target.block, block));
+}
+function accept(projectDir, taskId, positional, flags) {
+  const resolved = resolveTaskId(projectDir, taskId); const title = field(flags, ['item'], positional.join(' '));
+  if (!title) throw new Error('task accept requires a final acceptance item title.');
+  return withLock(projectDir, resolved, (before) => {
+    const task = loadTask(projectDir, resolved); assertModern(task, 'accept');
+    const evidence = field(flags, ['evidence']); if (!evidence) throw new Error('task accept requires --evidence.');
+    const body = touch(task, updateAcceptanceBody(task.body, title, true, evidence), 'active'); saveBody(task, body, before);
+    const updated = loadTask(projectDir, resolved); print(flags, updated.acceptance.find((entry) => entry.title === title));
+    if (flags.output !== 'json') log.ok(`Accepted: ${title}`); return 0;
+  });
+}
+
+function finish(projectDir, taskId, flags) {
+  const resolved = resolveTaskId(projectDir, taskId);
+  return withLock(projectDir, resolved, (before) => {
+    const task = loadTask(projectDir, resolved); assertModern(task, 'finish');
+    if (task.items.some((item) => !item.completed)) throw new Error(`Cannot finish ${task.id}; development items remain incomplete.`);
+    const pending = task.acceptance.filter((item) => !item.completed);
+    if (pending.length) throw new Error(`Cannot finish ${task.id}; final acceptance remains incomplete: ${pending.map((item) => item.title).join(', ')}.`);
+    const body = touch(task, task.body, 'completed'); saveBody(task, body, before);
+    const updated = loadTask(projectDir, resolved); print(flags, updated); if (flags.output !== 'json') log.ok(`Finished task ${resolved}`); return 0;
+  });
+}
+
+function legacyItemDetails(projectDir, task) {
+  return task.items.map((item) => {
+    const file = path.join(taskDir(projectDir, task.id), 'items', `${item.id}.md`);
+    const body = fs.existsSync(file) ? normalizeNewlines(fs.readFileSync(file, 'utf8')) : '';
+    const evidence = section(body, 'Evidence').split('\n').map((line) => line.replace(/^-\s*/, '').trim()).filter(Boolean);
+    return { ...item, title: item.title || item.id, evidence };
+  });
+}
+function migrate(projectDir, taskId, flags) {
+  const resolved = resolveTaskId(projectDir, taskId);
+  return withLock(projectDir, resolved, () => {
+    const task = loadTask(projectDir, resolved);
+    if (task.format !== 'legacy') throw new Error(`Task ${resolved} already uses ${TASK_FILENAME}.`);
+    const items = legacyItemDetails(projectDir, task); const now = new Date().toISOString();
+    const original = field(flags, ['original'], task.title || resolved); const clarified = field(flags, ['clarified'], original);
+    const expected = field(flags, ['expected-effect'], '保留历史任务的目标、进度和验收证据，并使用单文件继续维护。');
+    const defaultOwner = task.owner || taskActor(flags);
+    const modern = { title: task.title || resolved, created_at: task.created_at || now, updated_at: now, original_requirement: original,
+      clarified_requirement: clarified, expected_effect: expected, scope: '', out_of_scope: '' };
+    let body = template(modern); const blocks = items.map((item, index) => {
+      const id = /^DG-\d{3}$/.test(item.id) ? item.id : `DG-${String(index + 1).padStart(3, '0')}`;
+      const owner = item.owner || defaultOwner || 'unassigned'; const evidence = item.evidence.join('; ') || 'Legacy task state migrated.';
+      return `- [${item.status === 'completed' ? 'x' : ' '}] ${id} ${item.title}\n  - 内容：从历史 Task 迁移。\n  - 负责人：${owner}\n  - 验收：保留历史工作项状态与证据。\n  - 状态：${item.status || 'pending'}${item.status === 'completed' ? `\n  - 完成结果：${evidence}` : ''}`;
+    });
+    body = replaceSection(body, '开发清单', blocks.length ? blocks.join('\n\n') : '暂无。');
+    if (blocks.length && items.every((item) => item.status === 'completed')) body = updateAcceptanceBody(body, '所有开发项完成', true, 'Migrated from completed legacy items.');
+    atomicWrite(markdownFile(projectDir, resolved), body);
+    const updated = loadTask(projectDir, resolved); print(flags, updated); if (flags.output !== 'json') log.ok(`Migrated task ${resolved} to ${TASK_FILENAME}; legacy files were retained.`); return 0;
+  });
+}
+
+async function task(projectDir, positional, flags = {}) {
+  const operation = positional[0] || 'list';
+  if (operation === 'create') return create(projectDir, positional.slice(1), flags);
+  if (operation === 'list') return list(projectDir, flags);
+  if (operation === 'show' || operation === 'status') return show(projectDir, positional[1], flags);
+  if (operation === 'add') return add(projectDir, positional[1], positional.slice(2), flags);
+  if (operation === 'accept') return accept(projectDir, positional[1], positional.slice(2), flags);
+  if (operation === 'finish') return finish(projectDir, positional[1], flags);
+  if (operation === 'migrate') return migrate(projectDir, positional[1], flags);
+  if (['claim', 'start', 'complete', 'block', 'reopen'].includes(operation)) return mutate(projectDir, positional[1], positional[2], operation, flags, positional.slice(3));
+  throw new Error(`Unknown task operation ${operation}.`);
+}
+
+module.exports = task;
+module.exports.atomicWrite = atomicWrite;
+module.exports.loadTask = loadTask;
+module.exports.parseMarkdown = parseMarkdown;
+module.exports.uniqueTaskId = uniqueTaskId;

package/src/commands/verify.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const log = require('../logger');
+const check = require('./check');
+const verifyUi = require('./verifyUi');
+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.`);
+  return normalized;
+}
+
+function resources(positional) {
+  if (!positional.length) return [];
+  const [rawType, ...ids] = positional;
+  if (!ids.length) throw new Error('Usage: draftgo verify [<pages|nav|docs> <id...>] [--url <url>]');
+  const resourceType = canonicalResourceType(rawType);
+  return ids.map((resourceId) => ({ resourceType, resourceId: String(resourceId) }));
+}
+
+function viewports(flags) {
+  const value = String(flags.viewport || '').toLowerCase();
+  if (!value) return [{ name: 'custom', width: flags.width, height: flags.height }];
+  if (value === 'mobile') return [{ name: 'mobile', width: 390, height: 844 }];
+  if (value === 'desktop') return [{ name: 'desktop', width: 1440, height: 900 }];
+  if (value === 'both') return [
+    { name: 'mobile', width: 390, height: 844 },
+    { name: 'desktop', width: 1440, height: 900 },
+  ];
+  throw new Error('--viewport must be mobile, desktop, or both.');
+}
+
+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);
+    return 1;
+  }
+
+  log.title('draftgo verify');
+  const checkCode = await check(projectDir, [], {
+    strict: flags.strict,
+    remote: remoteMode === 'always',
+    resourceKeys: selected.length
+      ? selected.map((entry) => `${entry.resourceType}:${entry.resourceId}`)
+      : null,
+  });
+  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;
+    }
+    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);
+    if (code !== 0) return code;
+  }
+  log.ok(`Unified verification passed (${targets.map((item) => item.name).join(', ')}).`);
+  return 0;
+}
+
+module.exports = verify;
+module.exports.mode = mode;
+module.exports.resources = resources;
+module.exports.viewports = viewports;

package/src/commands/verifyUi.js

@@ -2,6 +2,7 @@
 
 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');
@@ -162,6 +163,51 @@ function parseResourceSpec(value) {
   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' }];
+  if (mode === 'top') return selected;
+  if (!['auto', 'all'].includes(mode)) {
+    const handle = await page.locator(mode).first().elementHandle().catch(() => null);
+    const frame = handle && await handle.contentFrame().catch(() => null);
+    if (!frame) throw new Error(`Frame not found: ${mode}`);
+    return [{ frame, label: `selector:${mode}` }];
+  }
+  const frames = page.frames ? page.frames() : [];
+  for (let index = 0; index < frames.length; index += 1) {
+    const frame = frames[index];
+    if (frame === top) continue;
+    let visible = true;
+    if (mode === 'auto') {
+      const element = await frame.frameElement().catch(() => null);
+      visible = Boolean(element && await element.isVisible().catch(() => false));
+    }
+    if (visible) selected.push({
+      frame,
+      label: `frame:${frame.name && frame.name() ? frame.name() : index}`,
+    });
+  }
+  return selected;
+}
+
+async function inspectFrame(frame) {
+  return frame.evaluate(() => {
+    const body = document.body;
+    const root = document.documentElement;
+    return {
+      bodyTextLength: body ? (body.innerText || '').trim().length : 0,
+      bodyHeight: body ? body.getBoundingClientRect().height : 0,
+      hasVisibleMedia: body ? Array.from(body.querySelectorAll('img,svg,canvas,video,iframe,input,button')).some((element) => {
+        const rect = element.getBoundingClientRect();
+        return rect.width > 1 && rect.height > 1;
+      }) : false,
+      horizontalOverflow: root.scrollWidth > window.innerWidth + 1,
+      scrollWidth: root.scrollWidth,
+      viewportWidth: window.innerWidth,
+    };
+  });
+}
+
 async function verifyRemoteResource(projectDir, spec) {
   const { resourceType, resourceId } = parseResourceSpec(spec);
   const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
@@ -220,7 +266,7 @@ async function verifyUi(projectDir, positional, flags = {}) {
   const width = numberFlag(flags.width, 390, 240, 3840);
   const height = numberFlag(flags.height, 844, 320, 2160);
   const waitMs = numberFlag(flags['wait-ms'], 500, 0, 10000);
-  const screenshotMode = String(flags.screenshot || 'on-failure').toLowerCase();
+  const screenshotMode = String(flags.screenshot || 'never').toLowerCase();
   if (!['on-failure', 'always', 'never'].includes(screenshotMode)) {
     log.err('--screenshot 只支持 on-failure、always、never。');
     return 1;
@@ -256,41 +302,38 @@ async function verifyUi(projectDir, positional, flags = {}) {
 
     const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
     if (waitMs) await page.waitForTimeout(waitMs);
-    const state = await page.evaluate(() => {
-      const body = document.body;
-      const root = document.documentElement;
-      return {
-        title: document.title,
-        bodyTextLength: body ? (body.innerText || '').trim().length : 0,
-        bodyHeight: body ? body.getBoundingClientRect().height : 0,
-        hasVisibleMedia: body ? Array.from(body.querySelectorAll('img,svg,canvas,video,iframe,input,button')).some((element) => {
-          const rect = element.getBoundingClientRect();
-          return rect.width > 1 && rect.height > 1;
-        }) : false,
-        horizontalOverflow: root.scrollWidth > window.innerWidth + 1,
-        scrollWidth: root.scrollWidth,
-        viewportWidth: window.innerWidth,
-      };
-    });
+    const frames = await selectFrames(page, String(flags.frame || 'auto'));
+    const states = [];
+    for (const item of frames) states.push({ ...item, state: await inspectFrame(item.frame) });
 
     const issues = [];
     if (response && response.status() >= 400) issues.push(`页面返回 HTTP ${response.status()}`);
-    if (!state.bodyHeight || (!state.bodyTextLength && !state.hasVisibleMedia)) issues.push('页面疑似空白');
-    if (state.horizontalOverflow) issues.push(`页面横向溢出：scrollWidth=${state.scrollWidth}, viewport=${state.viewportWidth}`);
+    if (!states.some(({ state }) => state.bodyHeight && (state.bodyTextLength || state.hasVisibleMedia))) issues.push('页面疑似空白');
+    for (const { label, state } of states) {
+      if (state.horizontalOverflow) issues.push(`${label} 横向溢出：scrollWidth=${state.scrollWidth}, viewport=${state.viewportWidth}`);
+    }
     if (consoleErrors.length) issues.push(`console error ${consoleErrors.length} 条`);
     if (pageErrors.length) issues.push(`page error ${pageErrors.length} 条`);
     if (flags.selector) {
-      const visible = await page.locator(String(flags.selector)).first().isVisible().catch(() => false);
-      if (!visible) issues.push(`关键元素不可见：${flags.selector}`);
+      let match = null;
+      for (const item of frames) {
+        if (await item.frame.locator(String(flags.selector)).first().isVisible().catch(() => false)) {
+          match = item.label;
+          break;
+        }
+      }
+      if (!match) issues.push(`关键元素在已检查 frame 中不可见：${flags.selector}`);
+      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');
+      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) {
@@ -301,7 +344,7 @@ async function verifyUi(projectDir, positional, flags = {}) {
       return 1;
     }
 
-    log.ok(`UI smoke check 通过：${width}x${height}，${decision.reason}`);
+    log.ok(`UI smoke check 通过：${width}x${height}，${frames.length} frame(s)，${decision.reason}`);
     if (screenshotPath) log.info(`截图：${screenshotPath}`);
     return 0;
   } catch (err) {
@@ -322,3 +365,5 @@ module.exports.executableCandidates = executableCandidates;
 module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
 module.exports.parseResourceSpec = parseResourceSpec;
 module.exports.verifyRemoteResource = verifyRemoteResource;
+module.exports.selectFrames = selectFrames;
+module.exports.inspectFrame = inspectFrame;

package/src/commands/verifyUiCompat.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const log = require('../logger');
+const verify = require('./verify');
+
+async function verifyUiCompat(projectDir, positional = [], flags = {}) {
+  const url = String(flags.url || positional[0] || '').trim();
+  log.warn('`draftgo verify-ui` is deprecated; use `draftgo verify --url <url> --ui always`.');
+  return verify(projectDir, [], {
+    ...flags,
+    url,
+    ui: 'always',
+  });
+}
+
+module.exports = verifyUiCompat;