@openprd/cli 0.1.1 → 0.1.8

package/src/codex-runtime.js

@@ -0,0 +1,324 @@
+/*
+ * 核心功能
+ * 封装 Codex CLI runtime 健康检查、可识别诊断和显式修复流程。
+ *
+ * 输入
+ * 接收 Codex 命令、package manager、cwd/env、是否 repair 以及可注入的 runCommand。
+ *
+ * 输出
+ * 导出 checkCodexCliHealth、repairCodexCli 和 ensureCodexCliReady 等结构化结果。
+ *
+ * 定位
+ * 位于 OpenPrd CLI 的 Agent runtime 边界，只处理本机 Codex 命令健康，不管理 PRD/task 状态。
+ *
+ * 依赖
+ * 使用 node:child_process 启动本地命令；被 doctor 与 loop run 复用。
+ *
+ * 维护规则
+ * 默认路径不得修改全局 Codex 安装；新增修复行为必须保持显式 opt-in 且可测试注入。
+ */
+import { spawn } from 'node:child_process';
+
+export const CODEX_REPAIR_PACKAGE = '@openai/codex@latest';
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+export function formatCommand(command, args = []) {
+  return [command, ...args].map(shellQuote).join(' ');
+}
+
+function windowsShellQuote(value) {
+  const text = String(value);
+  if (!text) {
+    return '""';
+  }
+  if (!/[\s"&<>|^]/.test(text)) {
+    return text;
+  }
+  return `"${text.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
+}
+
+function formatWindowsCommand(command, args = []) {
+  return [command, ...args].map(windowsShellQuote).join(' ');
+}
+
+function hasExplicitPath(command) {
+  return /[\\/]/.test(command) || /^[A-Za-z]:/.test(command);
+}
+
+export function buildProcessInvocation(command, args = [], options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const useWindowsShellWrapper = (
+    platform === 'win32'
+    && options.shell === undefined
+    && !hasExplicitPath(command)
+  );
+
+  if (useWindowsShellWrapper) {
+    return {
+      command: env.ComSpec || 'cmd.exe',
+      args: ['/d', '/s', '/c', formatWindowsCommand(command, args)],
+      display: formatCommand(command, args),
+      shell: false,
+    };
+  }
+
+  return {
+    command,
+    args,
+    display: formatCommand(command, args),
+    shell: Boolean(options.shell),
+  };
+}
+
+function runProcess(command, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const invocation = buildProcessInvocation(command, args, options);
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      shell: invocation.shell,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout = `${stdout}${chunk}`.slice(-64000);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-64000);
+    });
+    child.on('error', (error) => {
+      resolve({
+        ok: false,
+        command,
+        args,
+        display: invocation.display,
+        exitCode: null,
+        stdout,
+        stderr,
+        error: error.message,
+      });
+    });
+    child.on('close', (exitCode) => {
+      resolve({
+        ok: exitCode === 0,
+        command,
+        args,
+        display: invocation.display,
+        exitCode,
+        stdout,
+        stderr,
+        error: null,
+      });
+    });
+  });
+}
+
+function normalizeRunResult(command, args, result = {}) {
+  return {
+    ok: Boolean(result.ok),
+    command: result.command ?? command,
+    args: result.args ?? args,
+    display: result.display ?? formatCommand(command, args),
+    exitCode: result.exitCode ?? result.status ?? null,
+    stdout: String(result.stdout ?? ''),
+    stderr: String(result.stderr ?? ''),
+    error: result.error ? String(result.error) : null,
+  };
+}
+
+function runOutput(result) {
+  return [
+    result.stderr,
+    result.stdout,
+    result.error,
+  ].filter(Boolean).join('\n').trim();
+}
+
+export function buildCodexRepairCommand(options = {}) {
+  const command = options.packageManager ?? 'npm';
+  const args = ['install', '-g', options.package ?? CODEX_REPAIR_PACKAGE];
+  return {
+    command,
+    args,
+    display: formatCommand(command, args),
+  };
+}
+
+function missingOptionalDependency(output) {
+  const direct = output.match(/Missing optional dependency\s+([@A-Za-z0-9/._-]+)/i);
+  if (direct) return direct[1].replace(/[.。:：,，;；]+$/, '');
+  const moduleMissing = output.match(/Cannot find module ['"](@openai\/codex-[^'"]+)['"]/i);
+  if (moduleMissing) return moduleMissing[1];
+  const packageLike = output.match(/(@openai\/codex-[A-Za-z0-9._-]+)/i);
+  if (/optional dependenc/i.test(output) && packageLike) return packageLike[1];
+  return null;
+}
+
+export function diagnoseCodexVersionFailure(result, options = {}) {
+  const output = runOutput(result);
+  const repairCommand = buildCodexRepairCommand(options);
+  const missingPackage = missingOptionalDependency(output);
+  if (missingPackage) {
+    return {
+      type: 'missing-optional-dependency',
+      summary: `Codex CLI 启动失败：缺少平台原生可选依赖 ${missingPackage}。`,
+      missingPackage,
+      repairCommand,
+      manualCommand: repairCommand.display,
+      output,
+    };
+  }
+
+  if (
+    result.exitCode === null
+    && /(ENOENT|not found|command not found|no such file|spawn .*enoent)/i.test(output)
+  ) {
+    return {
+      type: 'command-not-found',
+      summary: 'Codex CLI 不在 PATH 中，OpenPrd 无法启动 Codex 代理子会话。',
+      missingPackage: null,
+      repairCommand,
+      manualCommand: repairCommand.display,
+      output,
+    };
+  }
+
+  return {
+    type: 'version-check-failed',
+    summary: `Codex CLI 健康检查失败：codex --version 退出码 ${result.exitCode ?? 'unknown'}。`,
+    missingPackage: null,
+    repairCommand,
+    manualCommand: repairCommand.display,
+    output,
+  };
+}
+
+export async function checkCodexCliHealth(options = {}) {
+  const command = options.codexCommand ?? 'codex';
+  const args = options.versionArgs ?? ['--version'];
+  const runner = options.runCommand ?? runProcess;
+  const result = normalizeRunResult(
+    command,
+    args,
+    await runner(command, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+    }),
+  );
+  const repairCommand = buildCodexRepairCommand(options);
+  const commandInfo = {
+    command,
+    args,
+    display: formatCommand(command, args),
+  };
+
+  if (result.ok) {
+    return {
+      ok: true,
+      command: commandInfo,
+      result,
+      version: (result.stdout || result.stderr).trim() || null,
+      diagnostic: null,
+      repairCommand,
+      errors: [],
+    };
+  }
+
+  const diagnostic = diagnoseCodexVersionFailure(result, options);
+  return {
+    ok: false,
+    command: commandInfo,
+    result,
+    version: null,
+    diagnostic,
+    repairCommand,
+    errors: [
+      diagnostic.summary,
+      `修复命令: ${repairCommand.display}`,
+    ],
+  };
+}
+
+export async function repairCodexCli(options = {}) {
+  const runner = options.runCommand ?? runProcess;
+  const commandInfo = buildCodexRepairCommand(options);
+  const result = normalizeRunResult(
+    commandInfo.command,
+    commandInfo.args,
+    await runner(commandInfo.command, commandInfo.args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+    }),
+  );
+  const recheck = result.ok ? await checkCodexCliHealth(options) : null;
+  const errors = [];
+  if (!result.ok) {
+    errors.push(result.stderr.trim() || result.error || `Codex 修复命令失败，退出码 ${result.exitCode ?? 'unknown'}。`);
+  }
+  if (result.ok && !recheck?.ok) {
+    errors.push(...(recheck?.errors ?? ['Codex 修复后仍未通过健康检查。']));
+  }
+
+  return {
+    attempted: true,
+    ok: result.ok && recheck?.ok === true,
+    command: commandInfo,
+    result,
+    recheck,
+    errors,
+  };
+}
+
+export async function ensureCodexCliReady(options = {}) {
+  const preflight = await checkCodexCliHealth(options);
+  if (preflight.ok) {
+    return {
+      ok: true,
+      preflight,
+      repair: null,
+      repairAttempted: false,
+      repairCommand: preflight.repairCommand,
+      errors: [],
+    };
+  }
+
+  if (!options.repair) {
+    return {
+      ok: false,
+      preflight,
+      repair: null,
+      repairAttempted: false,
+      repairCommand: preflight.repairCommand,
+      errors: [
+        'Codex CLI 健康检查未通过，OpenPrd 已停止启动 Codex 子会话。',
+        ...preflight.errors,
+        '如需让 OpenPrd 执行修复，请显式运行 openprd doctor . --tools codex --fix 或 openprd loop . --run --agent codex --repair-agent。',
+      ],
+    };
+  }
+
+  const repair = await repairCodexCli(options);
+  return {
+    ok: repair.ok,
+    preflight,
+    repair,
+    repairAttempted: true,
+    repairCommand: preflight.repairCommand,
+    errors: repair.ok
+      ? []
+      : [
+        'Codex CLI 显式修复后仍未通过健康检查。',
+        ...repair.errors,
+        `可手动执行: ${preflight.repairCommand.display}`,
+      ],
+  };
+}

package/src/dev-standards.js

@@ -1,10 +1,14 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { cjoin, exists, readJson } from './fs-utils.js';
 import { buildCodeExtensionCandidate, observeGrowthWorkspace } from './growth.js';
 import { recordKnowledgeReviewSignal, reviewKnowledgeWorkspace } from './knowledge.js';
 
 const DEVELOPMENT_STANDARDS_CONFIG = cjoin('.openprd', 'standards', 'config.json');
+const DEV_CHECK_WRAPUP_COPY_SCRIPT = fileURLToPath(new URL('../scripts/dev-check-wrapup-copy.mjs', import.meta.url));
+const DEV_CHECK_WRAPUP_FIELDS = ['规模信号', '预警原因', '本次处理结果', '后续建议'];
 const CODE_FILE_EXTENSIONS = new Set([
   '.c',
   '.cc',
@@ -209,23 +213,183 @@ function fileStatus(lineCount, lineConfig) {
 
 function nextActionForStatus(status, lineConfig) {
   if (status === 'ok') {
-    return `结构状态正常；最终回复中可简要说明 dev-check 已回顾 touched files。`;
+    return `本轮没有显著维护风险；最终回复可简要说明已回顾本次改动文件。`;
   }
   if (status === 'attention') {
-    return `最终回复说明本轮只触碰的局部职责和影响范围，避免继续新增无关职责。`;
+    return `本轮只做当前目标相关的小范围改动，并说明没有继续扩展该文件职责。`;
   }
   if (status === 'warning') {
-    return `判断本轮是否继续扩大职责或堆叠逻辑；若扩大了，先重构、拆分或解耦后复查；若只是窄 bugfix 或小修且暂不拆，说明原因并留下后续拆分建议。`;
+    return `先判断这次是否新增职责；如果新增了，优先拆分或解耦后再收尾；如果只是小修，说明暂不拆的原因和后续拆分建议。`;
   }
   if (status === 'exempt') {
-    return `豁免治理；只记录行数，不要求拆分。`;
+    return `不纳入本次维护风险判断；只记录行数，不要求拆分。`;
   }
   if (status === 'not-code') {
-    return `不适用；研发期行数规则只约束代码文件。`;
+    return `不适用；维护风险检查只面向代码文件。`;
   }
   return `无法检查；请确认文件路径。`;
 }
 
+function devCheckStatusLabel(status) {
+  if (status === 'ok') return '已检查，无需关注';
+  if (status === 'attention') return '🟡 低风险｜建议留意';
+  if (status === 'warning') return '🟠 中风险｜建议优先关注';
+  if (status === 'exempt') return '不纳入本次判断';
+  if (status === 'not-code') return '不适用';
+  if (status === 'error') return '🔴 高风险｜需要先处理';
+  return String(status || '未知');
+}
+
+function devCheckConcernRank(file) {
+  if (file.status === 'error') return 4;
+  if (file.status === 'warning') return 3;
+  if (file.status === 'attention') return 2;
+  if (file.status === 'ok') return 1;
+  return 0;
+}
+
+function devCheckThresholdText(file) {
+  const thresholds = file.thresholds ?? {};
+  const okMax = thresholds.okMax ?? DEFAULT_DEVELOPMENT_STANDARDS.codeFileLines.okMax;
+  const attentionMax = thresholds.attentionMax ?? DEFAULT_DEVELOPMENT_STANDARDS.codeFileLines.attentionMax;
+  const lineText = file.lineCount === null || file.lineCount === undefined ? '未知行数' : `${file.lineCount} 行`;
+  if (file.status === 'warning') {
+    return `${lineText}；已超过高维护风险线（>${attentionMax} 行）`;
+  }
+  if (file.status === 'attention') {
+    return `${lineText}；已超过建议的单文件舒适区（≤${okMax} 行）`;
+  }
+  return `${lineText}；建议单文件舒适区 ≤${okMax} 行，高维护风险线 >${attentionMax} 行`;
+}
+
+function devCheckReason(file) {
+  const thresholds = file.thresholds ?? {};
+  const okMax = thresholds.okMax ?? DEFAULT_DEVELOPMENT_STANDARDS.codeFileLines.okMax;
+  const attentionMax = thresholds.attentionMax ?? DEFAULT_DEVELOPMENT_STANDARDS.codeFileLines.attentionMax;
+  if (file.status === 'attention') {
+    return `文件已经偏大，继续叠加新职责会提高评审、回归和交接成本；本轮需要说明只改了哪一小块。`;
+  }
+  if (file.status === 'warning') {
+    return `文件已经进入高维护风险区，继续加逻辑容易放大改动范围和回归成本；需要判断是否应先拆分。`;
+  }
+  if (file.status === 'ok') {
+    return `文件规模在建议范围内。`;
+  }
+  if (file.status === 'exempt') {
+    return '命中生成物、依赖、快照或项目配置豁免。';
+  }
+  if (file.status === 'not-code') {
+    return '未识别为代码文件。';
+  }
+  return file.nextAction || '无法完成检查。';
+}
+
+function devCheckSplitIdea(file) {
+  if (file.status === 'attention') {
+    return '后续如果还要继续改这个文件，按入口、状态、渲染或数据处理边界拆出更小模块。';
+  }
+  if (file.status === 'warning') {
+    return '优先把独立职责、测试夹具或输出渲染拆出，降低下一次需求的评审和回归成本。';
+  }
+  if (file.status === 'ok') {
+    return '无需拆分。';
+  }
+  if (file.status === 'exempt') {
+    return '无需拆分，保持豁免原因可追踪。';
+  }
+  if (file.status === 'not-code') {
+    return '不适用研发期代码拆分判断。';
+  }
+  return '先修复检查错误，再重新运行 dev-check。';
+}
+
+function markdownCell(value) {
+  return String(value ?? '')
+    .replace(/\r?\n/g, '<br>')
+    .replace(/\|/g, '\\|');
+}
+
+function renderMarkdownTable(columns, rows) {
+  if (!rows.length) return '';
+  const header = `| ${columns.map(markdownCell).join(' | ')} |`;
+  const divider = `| ${columns.map(() => '---').join(' | ')} |`;
+  const body = rows.map((row) => `| ${columns.map((column) => markdownCell(row[column])).join(' | ')} |`);
+  return [header, divider, ...body].join('\n');
+}
+
+function countDisplayChars(value) {
+  return Array.from(String(value ?? '')).length;
+}
+
+function buildCompactWrapUpRows(files) {
+  const result = spawnSync(process.execPath, [DEV_CHECK_WRAPUP_COPY_SCRIPT], {
+    input: JSON.stringify({
+      files: files.map((file) => ({
+        status: file.status,
+        lineCount: file.lineCount,
+        thresholds: file.thresholds,
+        nextAction: file.nextAction,
+      })),
+    }),
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.trim() || result.stdout?.trim() || 'Failed to generate compact dev-check wrap-up copy.');
+  }
+  let payload = null;
+  try {
+    payload = JSON.parse(result.stdout || '{}');
+  } catch (error) {
+    throw new Error(`Failed to parse compact dev-check wrap-up copy: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const rows = Array.isArray(payload?.rows) ? payload.rows : null;
+  const limit = Number.isInteger(payload?.limit) ? payload.limit : 20;
+  if (!rows || rows.length !== files.length) {
+    throw new Error('Compact dev-check wrap-up copy returned an unexpected row count.');
+  }
+  for (const row of rows) {
+    for (const field of DEV_CHECK_WRAPUP_FIELDS) {
+      if (typeof row[field] !== 'string') {
+        throw new Error(`Compact dev-check wrap-up copy is missing field: ${field}`);
+      }
+      if (countDisplayChars(row[field]) > limit) {
+        throw new Error(`Compact dev-check wrap-up copy exceeded ${limit} chars for field: ${field}`);
+      }
+    }
+  }
+  return rows;
+}
+
+function buildDevCheckWrapUp(files) {
+  const title = '后续建议';
+  const columns = ['影响对象', '关注程度', '规模信号', '预警原因', '本次处理结果', '后续建议'];
+  const attentionFiles = files
+    .filter((file) => ['attention', 'warning', 'error'].includes(file.status))
+    .sort((left, right) => devCheckConcernRank(right) - devCheckConcernRank(left));
+  const compactRows = attentionFiles.length > 0 ? buildCompactWrapUpRows(attentionFiles) : [];
+  const rows = attentionFiles.map((file, index) => ({
+      影响对象: file.path,
+      关注程度: devCheckStatusLabel(file.status),
+      ...compactRows[index],
+    }));
+  const markdownTable = renderMarkdownTable(columns, rows);
+  return {
+    required: rows.length > 0,
+    reason: rows.length > 0
+      ? '存在需要用户关注的影响对象；最终回复需要用“后续建议”说明本次处理结果和后续建议。'
+      : '本轮改动文件未触发影响范围提醒；最终回复可简要说明已完成改动对象回顾。',
+    title,
+    columns,
+    rows,
+    markdownTable,
+    markdownBlock: markdownTable ? `**${title}**\n\n${markdownTable}` : '',
+  };
+}
+
 async function analyzeDevelopmentFile(projectRoot, targetPath, lineConfig) {
   const absolutePath = path.isAbsolute(targetPath)
     ? path.resolve(targetPath)
@@ -295,6 +459,7 @@ async function analyzeDevelopmentFile(projectRoot, targetPath, lineConfig) {
     path: relativePath,
     absolutePath,
     status,
+    statusLabel: devCheckStatusLabel(status),
     fileKind: exempt ? 'exempt' : (codeFile ? 'code' : (candidateCode ? 'candidate-code' : 'non-code')),
     lineCount,
     sizeBytes: stat.size,
@@ -305,6 +470,13 @@ async function analyzeDevelopmentFile(projectRoot, targetPath, lineConfig) {
     growthCandidate,
     growthObservation,
     nextAction,
+    wrapUp: ['attention', 'warning'].includes(status)
+      ? {
+        threshold: devCheckThresholdText({ status, lineCount, thresholds: { okMax: lineConfig.okMax, attentionMax: lineConfig.attentionMax } }),
+        reason: devCheckReason({ status, lineCount, thresholds: { okMax: lineConfig.okMax, attentionMax: lineConfig.attentionMax }, nextAction }),
+        splitIdea: devCheckSplitIdea({ status }),
+      }
+      : null,
   };
 }
 
@@ -366,6 +538,7 @@ export async function checkDevelopmentStandardsWorkspace(projectRoot, options =
       warning: statusCounts.warning ?? 0,
     },
     files,
+    wrapUp: buildDevCheckWrapUp(files),
     knowledgeReview,
     errors,
   };

package/src/diagram-core.js

@@ -355,9 +355,9 @@ function renderArrow(def) {
 }
 
 function resolveProductLayerTitle(productType) {
-  if (productType === 'consumer') return '消费端体验层';
-  if (productType === 'b2b') return 'B2B 工作流层';
-  if (productType === 'agent') return 'Agent 运行层';
+  if (productType === 'consumer') return '个人消费者场景层';
+  if (productType === 'b2b') return '企业服务场景层';
+  if (productType === 'agent') return 'Agent 使用场景层';
   return '产品体验层';
 }
 
@@ -556,7 +556,7 @@ export function renderArchitectureDiagramHtml(model) {
     svgMarkup,
     summaryCards: model.summaryCards,
     sidePanels: model.sidePanels,
-    footer: `负责人: ${model.metadata.owner} · 版本: ${model.metadata.versionId} · 目标: ${model.metadata.targetSystem} · 生成时间: ${model.generatedAt}`,
+    footer: `负责人: ${model.metadata.owner} · 交接去向: ${model.metadata.targetSystem} · 最近生成: ${model.generatedAt}`,
   });
 }
 
@@ -752,7 +752,7 @@ export function renderProductFlowDiagramHtml(model) {
     svgMarkup,
     summaryCards: model.summaryCards,
     sidePanels: model.sidePanels,
-    footer: `负责人: ${model.metadata.owner} · 版本: ${model.metadata.versionId} · 目标: ${model.metadata.targetSystem} · 生成时间: ${model.generatedAt}`,
+    footer: `负责人: ${model.metadata.owner} · 交接去向: ${model.metadata.targetSystem} · 最近生成: ${model.generatedAt}`,
   });
 }
 

package/src/discovery.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { analyzePrdSnapshot, buildPrdSnapshot, formatVersionId } from './prd-core.js';
+import { formatProductTypeDisplay } from './product-type-copy.js';
 import { analyzeOpenSpecTaskVolumes } from './openspec/tasks.js';
 import { legacyOpenSpecDiscoveryDir, openPrdDiscoveryDir, readDiscoveryConfig } from './openspec/paths.js';
 import { appendJsonl, cjoin, exists, readJson, readJsonl, writeJson, writeText } from './fs-utils.js';
@@ -194,7 +195,7 @@ function renderDiscoveryContext({ mode, projectRoot, sourceRoot, snapshot, analy
     `- 项目根目录: ${projectRoot}`,
     `- 来源根目录: ${sourceRoot}`,
     `- PRD 版本: ${snapshot.versionId}`,
-    `- 产品类型: ${snapshot.productType ?? '未分类'}`,
+    `- 产品场景: ${formatProductTypeDisplay(snapshot.productType, { fallback: '待确认' })}`,
     `- 必填字段完成度: ${analysis.completedRequiredFields}/${analysis.totalRequiredFields}`,
     `- 覆盖项: ${coverageMatrix.summary.pending}/${coverageMatrix.summary.total} 待处理`,
     next ? `- 下一项: ${next.title}` : '- 下一项: 无',