@openprd/cli 0.1.18 → 0.1.21

package/src/cli/args.js

@@ -19,7 +19,7 @@
  */
 function parseCommandArgs(argv) {
   const args = [...argv];
-  const flags = { json: false, force: false, fix: false, open: false, append: false, init: false, check: false, review: false, reject: false, resume: false, advance: false, verify: false, evidenceRequired: false, next: false, generate: false, validate: false, apply: false, archive: false, activate: false, close: false, keep: false, write: false, dryRun: false, repairAgent: false, allowDirtyMain: false, fleet: false, updateOpenprd: false, backfillWorkUnits: false, syncRegistry: false, setupMissing: false, doctor: false, context: false, recordHook: false, hookInject: false, plan: false, prompt: false, loopRun: false, finish: false, commit: false, html: false, template: false, failOnViolation: false, noExternalFacts: false, noBrandAssets: false, noRealImages: false, daemon: false, stop: false, bridgeOutbox: false, bridgeSent: false, bridgeFailed: false, mark: null, direction: null, autoRefactor: null, type: 'architecture', mode: 'auto', input: null, field: null, value: null, set: null, jsonFile: null, artifactMarkdown: null, contentJson: null, presentation: null, source: null, reference: null, actual: null, before: null, after: null, board: null, grid: null, boxes: null, out: null, format: null, quality: null, maxPanelWidth: null, referenceLabel: null, actualLabel: null, locale: null, classifyExternal: null, maxIterations: null, maxDepth: null, include: null, exclude: null, report: null, item: null, id: null, status: null, claim: null, notes: null, reason: null, confidence: null, threshold: null, change: null, starter: null, sections: null, brief: null, tools: 'all', hookProfile: null, templatePack: null, target: 'openprd', targetRoot: null, path: null, productType: null, title: null, owner: null, problem: null, whyNow: null, evidence: null, from: null, to: null, version: null, digest: null, workUnit: null, event: null, risk: null, outcome: null, preview: null, learn: null, genre: null, style: null, topic: null, enable: false, disable: false, agent: 'codex', agentCommand: null, worktree: null, branch: null, message: null, thread: null, threadTitle: null, conversationTitle: null, session: null, sessionTitle: null, host: null, port: null, openTarget: 'auto' };
+  const flags = { json: false, force: false, fix: false, open: false, append: false, init: false, check: false, review: false, reject: false, resume: false, advance: false, verify: false, evidenceRequired: false, next: false, generate: false, validate: false, apply: false, archive: false, activate: false, close: false, keep: false, write: false, dryRun: false, repairAgent: false, allowDirtyMain: false, fleet: false, updateOpenprd: false, backfillWorkUnits: false, syncRegistry: false, setupMissing: false, doctor: false, context: false, recordHook: false, hookInject: false, plan: false, prompt: false, loopRun: false, finish: false, commit: false, html: false, template: false, failOnViolation: false, noExternalFacts: false, noBrandAssets: false, noRealImages: false, daemon: false, stop: false, bridgeOutbox: false, bridgeSent: false, bridgeFailed: false, mark: null, direction: null, autoRefactor: null, type: 'architecture', mode: 'auto', input: null, field: null, value: null, set: null, jsonFile: null, artifactMarkdown: null, contentJson: null, presentation: null, source: null, reference: null, actual: null, before: null, after: null, board: null, grid: null, boxes: null, out: null, format: null, quality: null, maxPanelWidth: null, referenceLabel: null, actualLabel: null, locale: null, classifyExternal: null, maxIterations: null, maxDepth: null, include: null, exclude: null, report: null, item: null, id: null, status: null, claim: null, notes: null, reason: null, confidence: null, threshold: null, change: null, starter: null, sections: null, brief: null, tools: 'all', hookProfile: null, templatePack: null, target: 'openprd', targetRoot: null, path: null, productType: null, title: null, owner: null, problem: null, whyNow: null, evidence: null, from: null, to: null, version: null, digest: null, workUnit: null, event: null, risk: null, outcome: null, preview: null, learn: null, genre: null, style: null, topic: null, enable: false, disable: false, agent: 'codex', agentCommand: null, worktree: null, branch: null, message: null, thread: null, threadTitle: null, conversationTitle: null, session: null, sessionTitle: null, host: null, port: null, openTarget: 'auto', runtimeAction: null, lane: null, task: null, claimId: null, client: null, leaseMs: null, expectedRevision: null, expectedLaneRevision: null, writeSet: null, baseCommit: null, gateId: null, approvalId: null, symlinkStrategy: null, installSafetyBackupRoot: null };
   const positionals = [];
 
   while (args.length > 0) {
@@ -28,6 +28,62 @@ function parseCommandArgs(argv) {
       flags.json = true;
       continue;
     }
+    if (arg === '--runtime-action' || arg === '--action') {
+      flags.runtimeAction = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--lane') {
+      flags.lane = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--task') {
+      flags.task = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--claim-id') {
+      flags.claimId = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--client') {
+      flags.client = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--lease-ms') {
+      flags.leaseMs = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--expected-revision') {
+      flags.expectedRevision = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--expected-lane-revision') {
+      flags.expectedLaneRevision = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--write-set') {
+      flags.writeSet = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--base-commit') {
+      flags.baseCommit = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--gate' || arg === '--gate-id') {
+      flags.gateId = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--approval-id') {
+      flags.approvalId = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--symlink-strategy') {
+      flags.symlinkStrategy = args.shift() ?? null;
+      continue;
+    }
+    if (arg === '--install-safety-backup-root') {
+      flags.installSafetyBackupRoot = args.shift() ?? null;
+      continue;
+    }
     if (arg === '--force') {
       flags.force = true;
       continue;
@@ -581,14 +637,16 @@ function usage() {
     'OpenPrd CLI',
     '',
     'Usage:',
-    '  openprd init [path] [--template-pack <base|consumer|b2b|agent>] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--force]',
-    '  openprd setup [path] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--force] [--json]',
-    '  openprd update [path] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--force] [--json]',
+    '  openprd init [path] [--template-pack <base|consumer|b2b|agent>] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--symlink-strategy <block|materialize>] [--install-safety-backup-root <path>] [--force]',
+    '  openprd setup [path] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--symlink-strategy <block|materialize>] [--install-safety-backup-root <path>] [--force] [--json]',
+    '  openprd update [path] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--symlink-strategy <block|materialize>] [--install-safety-backup-root <path>] [--force] [--json]',
     '  openprd self-update [--check] [--dry-run] [--json]',
     '  openprd upgrade [path] [--fleet] [--dry-run] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--max-depth <n>] [--include <csv>] [--exclude <csv>] [--report <file>] [--force] [--json]',
     '  openprd doctor [path] [--tools <all|codex,claude,cursor>] [--hook-profile <lite|guarded|full>] [--fix] [--json]',
     '  openprd fleet <root> [--dry-run|--doctor|--update-openprd|--backfill-work-units|--sync-registry|--setup-missing] [--hook-profile <lite|guarded|full>] [--max-depth <n>] [--include <csv>] [--exclude <csv>] [--report <file>] [--json]',
     '  openprd run [path] [--context|--verify|--record-hook --event <name> --risk <level> --outcome <text> --preview <text>] [--message <text>] [--json]',
+    '  openprd runtime [path] --action <status|create-lane|ensure-lane|add-task|claim|heartbeat|release|finish|recover> [--lane <id>] [--task <id>] [--claim-id <id>] [--write-set <csv>] [--lease-ms <n>] [--expected-revision <n>] [--expected-lane-revision <n>] [--client <codex|claude|cursor>] [--session <id>] [--thread <id>] [--worktree <path>] [--branch <name>] [--base-commit <sha>] [--evidence <ref>] [--json]',
+    '  openprd gate [path] --action <status|define|evidence|approve|evaluate> [--json-file <record.json>] [--gate <id>] [--approval-id <id>] [--json]',
     '  openprd loop [path] [--init|--plan|--next|--prompt|--run|--verify|--finish] [--change <id>] [--item <task-id-or-handle>] [--agent <codex|claude>] [--agent-command <cmd>] [--repair-agent] [--worktree <path>] [--branch <name>] [--allow-dirty-main] [--commit] [--dry-run] [--message <text>] [--json]',
     '  openprd canvas [path] [--thread <id> [--thread-title <name>]|--session <id> [--session-title <name>]] [--host <host>] [--port <number>] [--daemon|--stop] [--open] [--open-target <auto|system|codex-browser>] [--dry-run] [--json]',
     '  openprd canvas [path] --bridge-outbox [--thread <id>|--session <id>] [--claim <next|id>] [--json]',
@@ -607,6 +665,7 @@ function usage() {
     '    --board modes: focus-board, parallel-board, verification-board, alignment-board, centering-board',
     '  openprd design-starter [path] [--starter <content-home|product-launch|ops-dashboard>] [--out <index.html>] [--title <name>] [--brief <text>] [--sections <a|b|c>] [--no-external-facts] [--no-brand-assets] [--no-real-images] [--force] [--json]',
     '  openprd dev-check [path] <file...> [--auto-refactor <on|off>] [--json]',
+    '  openprd i18n-init [path] [--locale <zh-Hans|en|...>] [--json]',
     '  openprd grow [path] [--review|--apply --id <candidate-id>|--reject --id <candidate-id>|--init|--check] [--notes <text>] [--json]',
     '  openprd benchmark <add|observe|list|approve|verify> [target-or-id] [path-for-list-or-verify] [--path <project>] [--notes <text>] [--threshold <n>] [--id <benchmark-id>] [--json]',
     '  openprd synthesize [path] [--title <text>] [--owner <text>] [--problem <text>] [--why-now <text>] [--work-unit <id>] [--target-root <path>] [--open] [--json]',

package/src/cli/gate-print.js

@@ -0,0 +1,17 @@
+function printGateResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (!result.ok) {
+    console.log(`OpenPrd 操作门禁：未完成（${result.error?.code ?? 'unknown'}）`);
+    console.log(result.error?.message ?? '门禁操作失败。');
+    return;
+  }
+  const status = result.result?.status;
+  console.log(`OpenPrd 操作门禁：${status === 'pass' ? '通过' : status === 'blocked' ? '已阻断' : '已记录'}`);
+  if (result.result?.decisionId) console.log(`决策编号：${result.result.decisionId}`);
+  for (const reason of result.result?.reasons ?? []) console.log(`- ${reason.code}`);
+}
+
+export { printGateResult };

package/src/cli/quality-commands.js

@@ -218,5 +218,23 @@ export async function runQualityCommand(command, { projectPath, flags, positiona
     return result.ok ? 0 : 1;
   }
 
+  if (command === 'i18n-init') {
+    const initProjectPath = path.resolve(flags.path ?? positionals[0] ?? process.cwd());
+    const { initI18nConfig } = await import('../dev-standards.js');
+    const result = await initI18nConfig(initProjectPath, {
+      defaultLanguage: flags.locale ?? undefined,
+    });
+    if (flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`OpenPrd i18n: ${result.created ? '已创建' : '配置已存在'} ${result.configPath}`);
+      console.log(`基准语言: ${result.config.defaultLanguage}`);
+      console.log(`支持语种: ${result.config.supportedLanguages.join(', ')}`);
+      console.log(`dev-check 检查: ${result.config.enforceOnDevCheck ? '开启' : '关闭'}`);
+      console.log(`最佳实践文档: docs/basic/i18n-guidelines.md`);
+    }
+    return 0;
+  }
+
   return null;
 }

package/src/cli/quality-print.js

@@ -123,6 +123,16 @@ function printDevelopmentStandardsResult(result, json) {
   } else if (result.visualEvidence?.uiFiles?.length > 0) {
     console.log(`- 视觉证据: 最近 24 小时已有证据板（${result.visualEvidence.freshEvidence.join(', ')}）；确认覆盖本轮改动并把证据图嵌入对话流。`);
   }
+  if (result.i18nReminder?.required) {
+    console.log(`- 多语言提醒: ${result.i18nReminder.reason}`);
+    console.log(`  涉及文件: ${result.i18nReminder.textFiles.join(', ')}`);
+    if (result.i18nReminder.guideline) {
+      console.log(`  最佳实践: ${result.i18nReminder.guideline}`);
+    }
+    if (!result.i18nReminder.configExists) {
+      console.log('  建议: 创建 .openprd/i18n-config.json 启用项目级多语言检查。');
+    }
+  }
   printKnowledgeReview(result.knowledgeReview);
   for (const error of result.errors ?? []) {
     console.log(`- ${error}`);

package/src/cli/runtime-print.js

@@ -0,0 +1,24 @@
+function printTaskRuntimeResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (!result.ok) {
+    console.log(`OpenPrd 并行任务运行时：未完成（${result.error?.code ?? 'unknown'}）`);
+    console.log(result.error?.message ?? '运行时操作失败。');
+    return;
+  }
+  console.log(`OpenPrd 并行任务运行时：${result.action.replace(/^runtime-/, '')}`);
+  if (result.laneId) console.log(`处理通道：${result.laneId}`);
+  if (result.taskId) console.log(`任务：${result.taskId}`);
+  const task = result.result?.task;
+  if (task) {
+    console.log(`状态：${task.status}`);
+    console.log(`修订：${task.revision}`);
+    if (task.claim?.leaseExpiresAt) console.log(`占用有效期至：${task.claim.leaseExpiresAt}`);
+  } else if (Array.isArray(result.result)) {
+    console.log(`处理通道数：${result.result.length}`);
+  }
+}
+
+export { printTaskRuntimeResult };

package/src/codex-hook-runner-template.mjs

@@ -765,45 +765,22 @@ function detectExecutionSignals(eventName, payload) {
   };
 }
 
-function latestSessionRegistryEntry(root, sessionId) {
-  if (!sessionId) {
-    return null;
-  }
-  const filePath = sessionRegistryPath();
-  if (!fs.existsSync(filePath)) {
-    return null;
-  }
-  const workspaceRoot = path.resolve(root);
-  let latest = null;
-  for (const line of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
-    if (!line.trim()) {
-      continue;
-    }
-    try {
-      const entry = JSON.parse(line);
-      if (entry?.sessionId !== sessionId) {
-        continue;
-      }
-      const entryRoot = entry?.workspaceRoot ? path.resolve(String(entry.workspaceRoot)) : null;
-      if (entryRoot && entryRoot !== workspaceRoot) {
-        continue;
-      }
-      latest = entry;
-    } catch {}
-  }
-  return latest;
-}
-
 function rememberAutomationMode(root, sessionId, payload, signals, laneKind) {
   if (!sessionId) {
     return null;
   }
-  return writeSessionRegistryEntry(root, sessionId, {
+  const gateStatus = laneKind === 'automation' ? 'automation-safe-mode' : 'openprd-opt-in';
+  const existing = readSessionBinding(root, sessionId);
+  // 每个 hook 事件都会经过这里；同一会话的 lane 记忆只需要落一次盘。
+  if (existing?.laneKind === laneKind && existing?.gateStatus === gateStatus) {
+    return existing;
+  }
+  return writeSessionBinding(root, sessionId, {
     laneKind,
     tool: 'openprd-hook',
     promptPreview: preview(promptText(payload) || payloadText(payload), 500),
     gateActive: false,
-    gateStatus: laneKind === 'automation' ? 'automation-safe-mode' : 'openprd-opt-in',
+    gateStatus,
     title: laneKind === 'automation'
       ? 'Unattended automation bypassed OpenPrd'
       : 'Unattended automation explicitly enabled OpenPrd',
@@ -820,7 +797,7 @@ function automationBypassDecision(root, eventName, payload, sessionId) {
   if (signals.isAutomation) {
     return { bypass: true, optIn: false, remembered: false, signals };
   }
-  const remembered = eventName === 'UserPromptSubmit' ? null : latestSessionRegistryEntry(root, sessionId);
+  const remembered = eventName === 'UserPromptSubmit' ? null : readSessionBinding(root, sessionId);
   if (remembered?.laneKind === 'automation' && remembered?.gateStatus === 'automation-safe-mode') {
     return { bypass: true, optIn: false, remembered: true, signals };
   }
@@ -912,44 +889,68 @@ function readSessionBinding(root, sessionId = null) {
   return readJsonSync(sessionBindingPath(root, sessionId), null);
 }
 
-function appendJsonLine(filePath, value) {
+function appendJsonLineAtomic(filePath, value) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.appendFileSync(filePath, JSON.stringify(value) + '\n');
+  const fd = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.writeSync(fd, `${JSON.stringify(value)}\n`);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
 }
 
-function writeSessionRegistryEntry(root, sessionId, patch = {}) {
+function sessionRegistryProjection(entry = {}) {
+  return {
+    sessionId: entry.sessionId ?? null,
+    workspaceRoot: entry.workspaceRoot ?? null,
+    laneKind: entry.laneKind ?? 'requirement',
+    tool: entry.tool ?? 'codex',
+    threadId: entry.threadId ?? null,
+    changeId: entry.changeId ?? null,
+    taskHandle: entry.taskHandle ?? null,
+    workUnitId: entry.workUnitId ?? null,
+    versionId: entry.versionId ?? null,
+    digest: entry.digest ?? null,
+    title: entry.title ?? null,
+    targetRoot: entry.targetRoot ?? null,
+    promptPreview: entry.promptPreview ?? null,
+    reviewStatus: entry.reviewStatus ?? null,
+    gateStatus: entry.gateStatus ?? null,
+    gateActive: entry.gateActive === true,
+  };
+}
+
+function writeSessionRegistryEntry(root, sessionId, binding, previous = null) {
   if (!sessionId) {
     return null;
   }
   const workspaceRoot = path.resolve(root);
-  const recordedAt = patch.recordedAt || now();
-  const entry = {
-    version: 1,
+  const projection = sessionRegistryProjection({
+    ...binding,
     sessionId,
     workspaceRoot,
+  });
+  const previousProjection = previous
+    ? sessionRegistryProjection({ ...previous, sessionId, workspaceRoot })
+    : null;
+  if (previousProjection && JSON.stringify(previousProjection) === JSON.stringify(projection)) {
+    return null;
+  }
+  const recordedAt = binding.updatedAt || now();
+  const entry = {
+    version: 1,
+    ...projection,
     realpath: workspaceRoot,
-    laneKind: patch.laneKind || 'requirement',
-    tool: patch.tool || 'codex',
-    threadId: patch.threadId || null,
-    changeId: patch.changeId || null,
-    taskHandle: patch.taskHandle || null,
-    workUnitId: patch.workUnitId || null,
-    versionId: patch.versionId || null,
-    digest: patch.digest || null,
-    title: patch.title || null,
-    targetRoot: patch.targetRoot ? path.resolve(patch.targetRoot) : null,
-    promptPreview: patch.promptPreview || null,
-    reviewStatus: patch.reviewStatus || null,
-    gateStatus: patch.gateStatus || null,
-    gateActive: patch.gateActive === true,
-    statePath: patch.statePath || sessionStatePath(root, sessionId),
-    bindingPath: patch.bindingPath || sessionBindingPath(root, sessionId),
-    firstRegisteredAt: patch.firstRegisteredAt || recordedAt,
+    targetRoot: projection.targetRoot ? path.resolve(projection.targetRoot) : null,
+    statePath: sessionStatePath(root, sessionId),
+    bindingPath: sessionBindingPath(root, sessionId),
+    firstRegisteredAt: previous?.createdAt || binding.createdAt || recordedAt,
     lastRegisteredAt: recordedAt,
-    lastUpdatedAt: patch.updatedAt || recordedAt,
+    lastUpdatedAt: recordedAt,
     recordedAt,
   };
-  appendJsonLine(sessionRegistryPath(), entry);
+  appendJsonLineAtomic(sessionRegistryPath(), entry);
   return entry;
 }
 
@@ -968,25 +969,7 @@ function writeSessionBinding(root, sessionId, patch = {}) {
     updatedAt: patch.updatedAt ?? now(),
   };
   writeJsonSync(filePath, next);
-  writeSessionRegistryEntry(root, sessionId, {
-    laneKind: patch.laneKind ?? previous?.laneKind ?? 'requirement',
-    tool: patch.tool ?? previous?.tool ?? 'codex',
-    threadId: patch.threadId ?? previous?.threadId ?? null,
-    changeId: patch.changeId ?? next.changeId ?? null,
-    taskHandle: patch.taskHandle ?? next.taskHandle ?? null,
-    workUnitId: patch.workUnitId ?? next.workUnitId ?? null,
-    versionId: patch.versionId ?? next.versionId ?? null,
-    digest: patch.digest ?? next.digest ?? null,
-    title: patch.title ?? next.title ?? null,
-    targetRoot: patch.targetRoot ?? next.targetRoot ?? null,
-    promptPreview: patch.promptPreview ?? next.promptPreview ?? null,
-    reviewStatus: patch.reviewStatus ?? next.reviewStatus ?? null,
-    gateStatus: patch.gateStatus ?? next.gateStatus ?? null,
-    gateActive: patch.gateActive ?? next.gateActive ?? false,
-    bindingPath: filePath,
-    statePath: sessionStatePath(root, sessionId),
-    updatedAt: next.updatedAt,
-  });
+  writeSessionRegistryEntry(root, sessionId, next, previous);
   return next;
 }
 
@@ -1561,6 +1544,9 @@ function knowledgeSkillContextLines(knowledgeSkills) {
 }
 
 function renderRunContextText(result) {
+  if (String(result?.contextText || '').trim()) {
+    return String(result.contextText).trim();
+  }
   const lines = [
     '当前进展参考',
     '当前项目: ' + result.projectRoot,
@@ -1935,6 +1921,8 @@ function analyzePromptIntent(prompt) {
     && !codeVisualArtifactRequested;
   const learningMaterialIntent = detectLearningMaterialIntent(text);
   const learningMaterialRequest = learningMaterialIntent.requested;
+  const canvasCollaborationRequest = /(画布|canvas|excalidraw)/i.test(text)
+    && /(标注|批注|协同|改图|回填|贴到画布|放到画布|插入画布|插到画布|画布评审|画布反馈|一起看|openprd\s*canvas|annotation)/i.test(text);
   const visualReview = /效果图|实现截图|视觉对比|视觉评审|对标效果图|复刻|不一致|好丑|没对齐|对不上|不像/i.test(text);
   const directBugfixExecution = explicitExecution && bugfixOrDiagnostic;
   const newFeatureVerbMatched = /(新增|增加|新建)/.test(text);
@@ -2043,6 +2031,7 @@ function analyzePromptIntent(prompt) {
     learningMaterialRequest,
     learningGenre: learningMaterialIntent.genre,
     learningMaterialReason: learningMaterialIntent.reason,
+    canvasCollaborationRequest,
     shouldInject: requiresIntake
       || requirementTier === 'l1'
       || explicitExecution
@@ -2059,6 +2048,7 @@ function analyzePromptIntent(prompt) {
       || browserSafetyRequest
       || productCopyRequest
       || learningMaterialRequest
+      || canvasCollaborationRequest
       || /openprd/i.test(normalized)
       || /\bprd\b/i.test(normalized),
   };
@@ -3461,6 +3451,21 @@ function visualMockupMessage(intent, root = null) {
   ].join('\n');
 }
 
+function canvasCollaborationMessage(intent) {
+  if (!intent?.canvasCollaborationRequest) {
+    return null;
+  }
+  return [
+    '当前请求涉及 OpenPrd 画布协同（生图上画布、人在画布上标注、标注结果回到对话继续改）。',
+    '打开或复用画布：运行 `openprd canvas .`；无法自动识别当前对话时用 `--thread <id> --thread-title <name>` 或 `--session <id> --session-title <name>` 显式绑定，画布必须绑定当前对话。',
+    '结构化读画布：需要知道用户正在圈哪些元素时，优先 `GET /api/selection` 读取选中元素的 ID、类型、坐标、尺寸和文本，不要只靠截图猜；需要全量场景再读 `GET /api/scene`。',
+    '结构化写画布：把生成的新图放上画布时，优先 `POST /api/insert-image`，用 `anchorElementId` + `placement`（right/left/below/above）把新图放到指定元素旁边，不要覆盖原图；回填 AI 生图占位卡时继续用 `POST /api/images` 带 `placeholderId`。',
+    '标注改图闭环：如果交接记录（handoff）的 `selection` 是 `annotation-edit`，或带有 `sourceImageElementIds` / `annotationElementIds`，说明用户在原图上画了标注要求改图。把截图里的标注当修改指令，生成修改后的新图，再用 `POST /api/insert-image` 以原图为 anchor 放到旁边，方便用户对比原图和新版。',
+    '生图尺寸契约：handoff 或占位卡带 `sizeContract`（width/height/aspectRatio）时，生成图片必须按这个宽高比出图，避免回填时变形拉伸。',
+    '每轮改图后主动确认：新图是否符合标注意图、是否继续下一轮标注迭代；用户可以继续在新图上标注，形成多轮改图闭环。',
+  ].join('\n');
+}
+
 function learningGenreFlag(intent = null) {
   return intent?.learningGenre ? ` --genre ${intent.learningGenre}` : '';
 }
@@ -3488,7 +3493,9 @@ function largeUiVisualDirectionMessage() {
     'OpenPrd 大界面改动视觉方案评审:',
     '位置: 需求分流之后、PRD 定稿或实现开工之前；它不同于 review.html，也不同于实现后的 visual-compare。',
     '判断: 先从用户目标、信息架构变化、视觉决策成本和验收风险判断是否需要方向评审，不用关键词触发。会决定首屏、核心布局、主视觉、关键路径、组件层级/密度，或用户需要先选设计方向时触发。',
-    '步骤: 已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户画像、第一版切片和视觉目标写设计 brief。brief 必须写清用途、受众、气质端点、约束和记忆点，3 个方向要分别说明审美主张和主动避开的模板味。然后按生图路由调用内置生图工具（Codex=`imagegen`/Image 2，Cursor=`GenerateImage`；都不可用时按 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好，没有偏好先问用户）生成至少 3 个不同设计思想方向；把效果图横向拼成一张带 1/2/3 序号的大图，先作为候选效果图给用户评审，不要默认写入 `.openprd/harness/visual-reviews/` 当验收参考。',
+    '自动性: 用户不需要额外提出“请生图”。只要语义判断命中大界面改动或视觉决策成本高，就主动完成 3 方向生成；卡片宽度、间距、对齐、颜色、圆角、字号等轻量微调不触发。',
+    '步骤: 已有界面时，Codex 原生 App 用 Computer Use，Codex 网页环境用 Chrome 插件的任务专用窗口，Cursor 用当前可用的浏览器或项目预览能力，进入对应功能并截当前真实界面。三个方向必须把同一张截图作为 image-to-image 参考；除非用户明确要求换风格，否则锁定现有字体角色、色彩系统、明暗模式、表面语言、圆角/边框/阴影、图标语言、平台框架和信息密度，只探索布局、信息层级、导航、关键路径和空间构图。冷启动没有现有界面时，基于已确认 PRD、用户画像、第一版切片和视觉目标写 design brief，不伪造修改前截图。brief 必须写清用途、受众、气质端点、约束和记忆点，3 个方向要分别说明审美主张和主动避开的模板味。然后按生图路由调用内置生图工具（Codex=`imagegen`/Image 2，Cursor=`GenerateImage`；都不可用时按 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好，没有偏好先问用户）生成至少 3 个不同设计思想方向；把效果图横向拼成一张带 1/2/3 序号的大图，先作为候选效果图给用户评审，不要默认写入 `.openprd/harness/visual-reviews/` 当验收参考。',
+    '质量: 每个方向都要从用途、用户、业务约束、核心动作和唯一记忆点出发，同时检查字体角色、色彩、空间构图、信息层级、表面/图标语言和动效含义；拒绝无依据蓝紫渐变、默认字体、等权白卡堆叠、过量大圆角、无语境装饰和只换颜色的伪方向。',
     '交互: 主动追问三件事：是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续后续实现。只有用户确认纳入后续对比或继续实现后，才把选定方向、整张图或其中子图整理成 reference-set 并写入 `.openprd/harness/visual-reviews/`；用户确认前，不进入大 UI 实现，也不要声称界面方案已定。',
     '多对象参考处理: 如果候选效果图是一张图里包含多个子图、网格、多对象或多方向，不要拿整板直接硬比；先运行 `openprd visual-prepare . --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，检查 contact sheet，确认 reference-set 后再逐项进入实现和验收。',
   ].join('\n');
@@ -3651,6 +3658,7 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
         'OpenPrd 上下文只是建议，不是自动执行指令。请先判断用户当前意图。',
         lightweightRequirementMessage(intent),
         visualMockupMessage(intent, cwd),
+        canvasCollaborationMessage(intent),
         learningReviewMessage(intent),
         largeUiVisualDirectionMessage(),
         visualLocalAdjustmentMessage(),
@@ -3673,6 +3681,7 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
       'OpenPrd 上下文只是建议，不是自动执行指令。请先判断用户当前意图。',
       lightweightRequirementMessage(intent),
       visualMockupMessage(intent, cwd),
+      canvasCollaborationMessage(intent),
       learningReviewMessage(intent),
       largeUiVisualDirectionMessage(),
       visualLocalAdjustmentMessage(),
@@ -3700,6 +3709,7 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
     gateMessage,
     lightweightRequirementMessage(intent),
     visualMockupMessage(intent, cwd),
+    canvasCollaborationMessage(intent),
     learningReviewMessage(intent),
     largeUiVisualDirectionMessage(intent),
     requirementRoutingSummary(),

package/src/codex-runtime.js

@@ -89,6 +89,29 @@ function runProcess(command, args = [], options = {}) {
     });
     let stdout = '';
     let stderr = '';
+    let settled = false;
+    let timedOut = false;
+    const timeoutMs = Number.isFinite(options.timeoutMs)
+      ? Math.max(1, Number(options.timeoutMs))
+      : 15000;
+    const killGraceMs = Number.isFinite(options.killGraceMs)
+      ? Math.max(1, Number(options.killGraceMs))
+      : 1000;
+    let killTimer = null;
+    const timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), killGraceMs);
+      killTimer.unref?.();
+    }, timeoutMs);
+    timeoutTimer.unref?.();
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve(payload);
+    };
     child.stdout.on('data', (chunk) => {
       stdout = `${stdout}${chunk}`.slice(-64000);
     });
@@ -96,7 +119,7 @@ function runProcess(command, args = [], options = {}) {
       stderr = `${stderr}${chunk}`.slice(-64000);
     });
     child.on('error', (error) => {
-      resolve({
+      finish({
         ok: false,
         command,
         args,
@@ -104,19 +127,22 @@ function runProcess(command, args = [], options = {}) {
         exitCode: null,
         stdout,
         stderr,
+        timedOut,
         error: error.message,
       });
     });
-    child.on('close', (exitCode) => {
-      resolve({
-        ok: exitCode === 0,
+    child.on('close', (exitCode, signal) => {
+      finish({
+        ok: !timedOut && exitCode === 0,
         command,
         args,
         display: invocation.display,
         exitCode,
+        signal,
         stdout,
         stderr,
-        error: null,
+        timedOut,
+        error: timedOut ? `Command timed out after ${timeoutMs}ms.` : null,
       });
     });
   });
@@ -131,6 +157,8 @@ function normalizeRunResult(command, args, result = {}) {
     exitCode: result.exitCode ?? result.status ?? null,
     stdout: String(result.stdout ?? ''),
     stderr: String(result.stderr ?? ''),
+    timedOut: Boolean(result.timedOut),
+    signal: result.signal ? String(result.signal) : null,
     error: result.error ? String(result.error) : null,
   };
 }
@@ -178,6 +206,17 @@ export function diagnoseCodexVersionFailure(result, options = {}) {
     };
   }
 
+  if (result.timedOut) {
+    return {
+      type: 'version-check-timeout',
+      summary: `Codex CLI 健康检查超时：codex --version 在 ${options.timeoutMs ?? 15000}ms 内没有返回。`,
+      missingPackage: null,
+      repairCommand,
+      manualCommand: repairCommand.display,
+      output,
+    };
+  }
+
   if (
     result.exitCode === null
     && /(ENOENT|not found|command not found|no such file|spawn .*enoent)/i.test(output)
@@ -212,6 +251,8 @@ export async function checkCodexCliHealth(options = {}) {
     await runner(command, args, {
       cwd: options.cwd,
       env: options.env ?? process.env,
+      timeoutMs: options.timeoutMs ?? 15000,
+      killGraceMs: options.killGraceMs,
     }),
   );
   const repairCommand = buildCodexRepairCommand(options);
@@ -257,6 +298,8 @@ export async function repairCodexCli(options = {}) {
     await runner(commandInfo.command, commandInfo.args, {
       cwd: options.cwd,
       env: options.env ?? process.env,
+      timeoutMs: options.repairTimeoutMs ?? 300000,
+      killGraceMs: options.killGraceMs,
     }),
   );
   const recheck = result.ok ? await checkCodexCliHealth(options) : null;