@openprd/cli 0.1.1 → 0.1.9

package/src/quality-html-artifact.js

@@ -48,6 +48,7 @@ function humanText(value) {
 
 function gateDisplay(gate) {
   if (gate?.id === 'knowledge') return '经验沉淀';
+  if (gate?.id === 'growth') return '成长账本';
   return humanText(gate?.label ?? gate?.id ?? '测试块');
 }
 
@@ -98,20 +99,43 @@ function gateDescription(gate) {
   const descriptions = {
     smoke: '核心路径能否跑通，至少覆盖主流程和关键失败路径',
     'feature-coverage': '需求拆解项是否全部完成，验收点是否有对应回归',
+    'visual-review': '界面改动是否留下效果图对比、局部焦点证据板、并行实验证据板或修改前后自检证据',
     'business-guardrails': '成本、额度、滥用、报警和止损是否讲清楚',
+    'test-strategy': '本次需求该用哪几层测试、证据怎么留下、是否有豁免',
     traceability: '出问题时是否能追到用户动作、请求、任务和错误',
     redaction: '报告、日志和错误信息是否会暴露敏感信息',
     'normal-performance': '普通规模下是否可用、不卡顿、不超时',
     'extreme-performance': '大数据、并发、异常输入或边界规模是否有兜底',
     knowledge: '本次问题是否需要沉淀经验，避免下次重复漏测',
+    growth: '本次收工是否留下成长账本事件，确保自动补齐和规则演进可观察',
   };
   return descriptions[gate.id] ?? '确认这项测试是否和本次需求相关，证据是否来自本次执行';
 }
 
-function gateTreatment(gate) {
+function featureCoverageLedgerMessage(report) {
+  const tasks = activeTasks(report);
+  const pending = Number(tasks.pending ?? 0);
+  if (pending <= 0) {
+    return null;
+  }
+  const total = Number(tasks.total ?? 0);
+  const done = Number(tasks.done ?? 0);
+  const blocked = Number(tasks.blocked ?? 0);
+  const progress = total > 0 ? `${done}/${total}` : `${done}`;
+  const changeLabel = tasks.activeChange ? `当前变更 ${tasks.activeChange}` : '当前任务账本';
+  return `${changeLabel} 还有 ${pending} 个未完成任务（已完成 ${progress}${blocked > 0 ? `，其中 ${blocked} 个因依赖阻塞` : ''}），这是账本未收口，不等于当前实现失败`;
+}
+
+function gateTreatment(gate, report) {
   if (gate.id === 'feature-coverage' && gate.evidence?.summary === '当前没有激活任务清单') {
     return '全项目检查可继续；具体需求交付时要补任务拆解';
   }
+  if (gate.id === 'feature-coverage') {
+    const ledgerMessage = featureCoverageLedgerMessage(report);
+    if (ledgerMessage) {
+      return ledgerMessage;
+    }
+  }
   if (gate.required && gate.status === 'pass') return '保留证据即可继续';
   if (gate.required) return '现在修复或补证据，完成后重新生成报告';
   if (gate.status === 'pass') return '已覆盖，可作为辅助证据保留';
@@ -173,7 +197,7 @@ function actionItems(report) {
   const failing = required.filter((gate) => !['pass', 'waived'].includes(gate.status));
   const advisory = (report.gates ?? []).filter((gate) => !gate.required && gate.status !== 'pass');
   if (failing.length > 0) {
-    return failing.map((gate) => `${gateDisplay(gate)}：${humanText(gate.warnings?.[0] ?? gate.evidence?.summary ?? '补齐证据后再继续')}`);
+    return failing.map((gate) => `${gateDisplay(gate)}：${humanText(gate.warnings?.[0] ?? gateTreatment(gate, report) ?? gate.evidence?.summary ?? '补齐证据后再继续')}`);
   }
   if (advisory.length > 0) {
     return advisory.map((gate) => `${gateDisplay(gate)}：判断是否属于本期，属于就补测，不属于就说明延期原因`);
@@ -477,10 +501,10 @@ function detailList(items, emptyText) {
   `;
 }
 
-function requiredItems(required) {
+function requiredItems(report, required) {
   return required.map((gate) => ({
     summary: gateSummary(gate),
-    detail: `${gate.required ? '本期必测' : '按风险确认'}，${gate.evidence?.summary ?? '等待补充本次证据'}。${gateTreatment(gate)}`,
+    detail: `${gate.required ? '本期必测' : '按风险确认'}，${gate.evidence?.summary ?? '等待补充本次证据'}。${gateTreatment(gate, report)}`,
   }));
 }
 
@@ -489,7 +513,7 @@ function exceptionItems(report) {
     .filter((gate) => gate.status !== 'pass' && gate.status !== 'waived')
     .map((gate) => ({
       summary: gateSummary(gate),
-      detail: humanText(gate.warnings?.[0] ?? gateTreatment(gate)).replace(/[。.]$/u, ''),
+      detail: humanText(gate.warnings?.[0] ?? gateTreatment(gate, report)).replace(/[。.]$/u, ''),
     }));
 }
 
@@ -505,17 +529,32 @@ function evidenceItems(report) {
 
 function environmentItems(report) {
   const evalHarness = report.evalHarness;
+  const strategy = evalHarness.testStrategy ?? {};
   const obs = report.observability;
   const knowledge = report.knowledge;
+  const growth = report.growth ?? { summary: { eventCount: 0, completionCheckpoints: 0 } };
   const businessGuardrails = report.businessGuardrails;
+  const visualReview = report.visualReview ?? { relevant: false, evidence: { present: false, summary: '当前场景未要求视觉评审证据' } };
   return [
+    {
+      summary: '分层测试策略',
+      detail: strategy.total > 0
+        ? `显式 ${strategy.explicit ?? 0} 项，推导 ${strategy.inferred ?? 0} 项，已规划证据 ${strategy.evidencePlanned ?? 0} 项`
+        : '当前没有可分析的任务级测试策略',
+    },
     {
       summary: evalHarness.smoke.present ? '主流程验证可用' : '主流程验证缺失',
       detail: evalHarness.smoke.commands.join(' / ') || '还没有发现可直接复跑的验证入口',
     },
     {
       summary: '任务覆盖',
-      detail: `已完成 ${evalHarness.featureCoverage.activeTasks.done}/${evalHarness.featureCoverage.activeTasks.total}，待处理 ${evalHarness.featureCoverage.activeTasks.pending}`,
+      detail: `已完成 ${evalHarness.featureCoverage.activeTasks.done}/${evalHarness.featureCoverage.activeTasks.total}，待处理 ${evalHarness.featureCoverage.activeTasks.pending}${evalHarness.featureCoverage.activeTasks.blocked > 0 ? `，阻塞 ${evalHarness.featureCoverage.activeTasks.blocked}` : ''}`,
+    },
+    {
+      summary: '视觉证据',
+      detail: visualReview.relevant
+        ? (visualReview.evidence?.summary ?? '需要补充本次视觉对比证据')
+        : '当前场景未要求视觉评审证据',
     },
     {
       summary: '问题追踪',
@@ -527,11 +566,58 @@ function environmentItems(report) {
     },
     {
       summary: '经验沉淀',
-      detail: knowledge.skills.length > 0 ? `已有 ${knowledge.skills.length} 个项目经验` : '首次稳定问题修复后应沉淀经验',
+      detail: knowledge.skills.length > 0
+        ? `已有 ${knowledge.skills.length} 个项目经验${knowledge.candidates.length > 0 ? `，另有 ${knowledge.candidates.length} 个待确认草案` : ''}`
+        : (knowledge.candidates.length > 0 ? `已有 ${knowledge.candidates.length} 个待确认草案` : '首次稳定问题修复后应沉淀经验'),
+    },
+    {
+      summary: '成长账本',
+      detail: Number(growth.summary?.eventCount ?? 0) > 0
+        ? `已记录 ${growth.summary.eventCount} 条事件，completion checkpoint ${growth.summary.completionCheckpoints ?? 0} 条`
+        : '当前还没有成长账本事件；完成态至少应留下 checkpoint 或候选',
     },
   ];
 }
 
+function layerLabel(layer) {
+  const labels = {
+    unit: '单元',
+    integration: '集成',
+    e2e: '端到端',
+    manual: '人工',
+    smoke: '冒烟',
+    visual: '视觉',
+    performance: '性能',
+    security: '安全',
+    weapp: '小程序',
+    none: '无',
+  };
+  return labels[layer] ?? layer;
+}
+
+function strategyItems(report) {
+  const strategy = report.evalHarness?.testStrategy ?? {};
+  const layerCounts = strategy.layerCounts ?? {};
+  const layerSummary = Object.entries(layerCounts)
+    .filter(([, count]) => Number(count) > 0)
+    .map(([layer, count]) => `${layerLabel(layer)} ${count}`)
+    .join('，');
+  const warnings = strategy.warnings ?? [];
+  return [
+    {
+      summary: strategy.total > 0 ? `已分析 ${strategy.total} 个任务` : '暂无任务策略',
+      detail: layerSummary || '没有检测到任务级测试层级',
+    },
+    {
+      summary: `证据计划 ${strategy.evidencePlanned ?? 0}/${strategy.total ?? 0}`,
+      detail: strategy.evidencePresent > 0 ? `已有 ${strategy.evidencePresent} 项证据记录` : '当前重点是确认该测哪一层，再留下本次执行证据',
+    },
+    ...(warnings.length > 0
+      ? warnings.slice(0, 3).map((warning) => ({ summary: '需关注', detail: humanText(warning) }))
+      : [{ summary: '比例规则', detail: '70/20/10 只作健康形状参考，不作为硬阻断' }]),
+  ];
+}
+
 function panel({ kind, title, description, chips, items, emptyText }) {
   return `
     <section class="quality-panel quality-panel-${escapeHtml(kind)}">
@@ -597,7 +683,7 @@ function tableRowsForGates(report) {
         <strong>${gate.evidence?.present ? `${gate.evidence.sources.length} 条` : '缺证据'}</strong>
         <span>${escapeHtml(gate.evidence?.summary ?? '未找到本次执行证据')}</span>
       </td>
-      <td>${escapeHtml(gateTreatment(gate))}</td>
+      <td>${escapeHtml(gateTreatment(gate, report))}</td>
     </tr>
   `).join('\n');
 }
@@ -1260,7 +1346,7 @@ export function renderQualityEvalArtifact({ report }) {
       title: '本期必测结果',
       description: '先看必须覆盖的测试是否通过，没通过就不要继续',
       chips: required.map((gate) => chip(gateSummary(gate), toneForGate(gate))),
-      items: requiredItems(required),
+      items: requiredItems(report, required),
       emptyText: '当前没有被判定为本期必测的测试块。',
     }),
     panel({
@@ -1290,6 +1376,7 @@ export function renderQualityEvalArtifact({ report }) {
       title: '执行环境与覆盖',
       description: '区分项目具备测试能力，和这次是否真的留下证据',
       chips: [
+        chip(`测试策略 ${report.evalHarness.testStrategy?.total ?? 0} 项`, (report.evalHarness.testStrategy?.total ?? 0) > 0 ? 'note' : 'warn'),
         chip(report.evalHarness.smoke.present ? '主流程验证可用' : '缺主流程验证', report.evalHarness.smoke.present ? 'pass' : 'warn'),
         chip(report.observability.correlationFields.length > 0 ? '问题可追踪' : '追踪线索不足', report.observability.correlationFields.length > 0 ? 'pass' : 'warn'),
         chip(report.businessGuardrails.missingEvidence.length > 0 ? '成本护栏待补' : '成本护栏完整', report.businessGuardrails.missingEvidence.length > 0 ? 'warn' : 'pass'),
@@ -1297,6 +1384,18 @@ export function renderQualityEvalArtifact({ report }) {
       items: environmentItems(report),
       emptyText: '还没有检测到执行环境信息。',
     }),
+    panel({
+      kind: 'check',
+      title: '分层测试策略',
+      description: '按需求风险选择最小足够证据，不把固定比例当硬指标',
+      chips: [
+        chip(`显式 ${report.evalHarness.testStrategy?.explicit ?? 0}`, 'note'),
+        chip(`推导 ${report.evalHarness.testStrategy?.inferred ?? 0}`, 'note'),
+        chip(`证据计划 ${report.evalHarness.testStrategy?.evidencePlanned ?? 0}`, (report.evalHarness.testStrategy?.evidencePlanned ?? 0) > 0 ? 'pass' : 'warn'),
+      ],
+      items: strategyItems(report),
+      emptyText: '还没有任务级测试策略。',
+    }),
   ].join('\n');
 
   return `<!DOCTYPE html>

package/src/quality-learning.js

@@ -619,6 +619,24 @@ export function renderExperienceSkill({ skillName, source }) {
       source.eventNames.length > 0 ? `运行态再次出现事件：${source.eventNames.join(', ')}。` : null,
       source.symptoms.length > 0 ? `本次症状包括：${source.symptoms.join('；')}。` : null,
     ]
+  const applicability = [
+    source.abstractPattern ? `优先适用于：${source.abstractPattern}` : null,
+    source.kind === 'quality-report'
+      ? '适用于已经完成一轮实现，需要把质量闭环、证据顺序和防复发要求固定下来的任务。'
+      : '适用于已经拿到 runtime-events、timeline、root-cause-candidates 或 diagnostic-report 的排查任务。',
+  ]
+  const typicalInputs = [
+    source.title ? `问题摘要: ${source.title}` : null,
+    source.evidenceSources.length > 0
+      ? `可直接使用的证据: ${source.evidenceSources.slice(0, 4).map((item) => `${item.kind}:${item.path}`).join('；')}`
+      : null,
+    source.eventNames.length > 0 ? `关键事件: ${source.eventNames.join(' -> ')}` : null,
+  ]
+  const typicalOutputs = [
+    '结论性诊断说明，明确问题症状、根因模式和下一步动作。',
+    source.verificationSteps.length > 0 ? `最小验证链路: ${source.verificationSteps[0]}` : null,
+    '可复用的项目级 knowledge skill 或后续 candidate / incident / pattern 记录。',
+  ]
 
   return `---
 name: ${skillName}
@@ -631,6 +649,18 @@ description: 由 OpenPrd 从 ${source.kind} 自动沉淀的项目级排查经验
 
 ${renderList(triggers, '当同类问题再次出现，先复用这套排查路径。')}
 
+## 适用范围
+
+${renderList(applicability, '适用于相似问题再次出现时，先复用已有排查路径和验证证据。')}
+
+## 典型输入
+
+${renderList(typicalInputs, '至少带上问题摘要、现有证据和关键事件。')}
+
+## 典型输出
+
+${renderList(typicalOutputs, '至少产出可复用结论、验证链路和后续知识沉淀。')}
+
 ## 先看哪些证据
 
 ${renderEvidenceSources(source.evidenceSources)}

package/src/quality-visual-review.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { cjoin, readJson } from './fs-utils.js';
+
+const VISUAL_REVIEW_DIR = cjoin('.openprd', 'harness', 'visual-reviews');
+const VISUAL_REVIEW_SCHEMA = 'openprd.visual-review.v1';
+const VISUAL_REVIEW_IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
+
+function normalizeWorkspacePath(value) {
+  return String(value ?? '').split(path.sep).join('/');
+}
+
+function inferVisualReviewMode(value) {
+  const normalized = normalizeWorkspacePath(value).toLowerCase();
+  if (normalized.includes('visual-focus-board') || normalized.includes('focus-board') || normalized.includes('focus-region')) {
+    return 'focus-board';
+  }
+  if (normalized.includes('visual-parallel-board') || normalized.includes('parallel-board') || normalized.includes('experiment-board')) {
+    return 'parallel-board';
+  }
+  if (normalized.includes('visual-before-after') || normalized.includes('before-after')) {
+    return 'before-after';
+  }
+  if (normalized.includes('visual-compare') || normalized.includes('reference-actual')) {
+    return 'reference-actual';
+  }
+  return null;
+}
+
+async function walkVisualReviewDir(projectRoot, dir, collected) {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const fullPath = cjoin(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkVisualReviewDir(projectRoot, fullPath, collected);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!VISUAL_REVIEW_IMAGE_EXTENSIONS.has(ext) && ext !== '.json') {
+      continue;
+    }
+    const relativePath = normalizeWorkspacePath(path.relative(projectRoot, fullPath));
+    collected.push({ fullPath, relativePath, ext });
+  }
+}
+
+export async function listVisualReviewArtifacts(projectRoot) {
+  const root = cjoin(projectRoot, VISUAL_REVIEW_DIR);
+  const entries = [];
+  await walkVisualReviewDir(projectRoot, root, entries);
+  const artifactsByKey = new Map();
+
+  for (const entry of entries) {
+    if (entry.ext === '.json') {
+      const payload = await readJson(entry.fullPath).catch(() => null);
+      if (payload?.schema !== VISUAL_REVIEW_SCHEMA) {
+        continue;
+      }
+      const key = normalizeWorkspacePath(String(payload.outputPath ?? entry.relativePath).replace(/\.[^.]+$/u, ''));
+      const existing = artifactsByKey.get(key) ?? {};
+      const outputPath = normalizeWorkspacePath(payload.outputPath ?? '');
+      const inferredMode = payload.mode ?? inferVisualReviewMode(outputPath) ?? inferVisualReviewMode(entry.relativePath);
+      if (!inferredMode) {
+        continue;
+      }
+      const stat = await fs.stat(entry.fullPath).catch(() => null);
+      artifactsByKey.set(key, {
+        ...existing,
+        path: outputPath || existing.path || entry.relativePath,
+        metadataPath: entry.relativePath,
+        mode: inferredMode,
+        labels: payload.labels ?? existing.labels ?? null,
+        generatedAt: payload.generatedAt ?? existing.generatedAt ?? null,
+        mtimeMs: stat?.mtimeMs ?? existing.mtimeMs ?? 0,
+      });
+      continue;
+    }
+
+    const key = entry.relativePath.replace(/\.[^.]+$/u, '');
+    const existing = artifactsByKey.get(key) ?? {};
+    const inferredMode = inferVisualReviewMode(entry.relativePath);
+    if (!inferredMode) {
+      continue;
+    }
+    const stat = await fs.stat(entry.fullPath).catch(() => null);
+    artifactsByKey.set(key, {
+      ...existing,
+      path: entry.relativePath,
+      mode: existing.mode ?? inferredMode,
+      mtimeMs: stat?.mtimeMs ?? existing.mtimeMs ?? 0,
+    });
+  }
+
+  return [...artifactsByKey.values()]
+    .filter((artifact) => artifact.path && artifact.mode)
+    .sort((a, b) => (b.mtimeMs ?? 0) - (a.mtimeMs ?? 0))
+    .slice(0, 24);
+}
+
+export function detectVisualReview({ policy, activeChangeContext, activeTasks, visualArtifacts, includesAny }) {
+  const relevant = policy.requiredGates.includes('visual-review');
+  const haystack = [
+    activeChangeContext.text,
+    activeTasks.tasks.map((task) => [
+      task.title,
+      ...Object.entries(task.metadata ?? {}).map(([key, value]) => `${key}: ${value}`),
+    ].join('\n')).join('\n'),
+  ].join('\n');
+  const referenceTokens = [
+    'reference image',
+    'reference design',
+    'design reference',
+    'effect image',
+    'mockup',
+    'figma',
+    '效果图',
+    '设计稿',
+    '视觉稿',
+    '参考图',
+    '用户给图',
+    '图片资产',
+  ];
+  const focusTokens = [
+    'focus board',
+    'focus region',
+    'focus-region',
+    'local compare',
+    'zoom compare',
+    '局部对比',
+    '局部放大',
+    '焦点区域',
+    'focus',
+  ];
+  const parallelTokens = [
+    'parallel board',
+    'parallel experiment',
+    'experiment board',
+    'evidence board',
+    '并行实验',
+    '并行方向',
+    '多方向实验',
+    '方案对比板',
+    '证据板',
+  ];
+  const expectsReferenceCompare = includesAny(haystack, referenceTokens);
+  const expectsFocusBoard = includesAny(haystack, focusTokens);
+  const expectsParallelBoard = includesAny(haystack, parallelTokens);
+  const referenceArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'reference-actual');
+  const beforeAfterArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'before-after');
+  const focusArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'focus-board');
+  const parallelArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'parallel-board');
+  let matchingArtifacts;
+  if (expectsParallelBoard) {
+    matchingArtifacts = parallelArtifacts;
+  } else if (expectsFocusBoard) {
+    matchingArtifacts = focusArtifacts;
+  } else if (expectsReferenceCompare) {
+    matchingArtifacts = referenceArtifacts;
+  } else {
+    matchingArtifacts = [...referenceArtifacts, ...beforeAfterArtifacts, ...focusArtifacts, ...parallelArtifacts];
+  }
+  const evidenceSources = matchingArtifacts.slice(0, 12).map((artifact) => ({
+    path: artifact.path,
+    source: artifact.mode === 'reference-actual'
+      ? 'visual-review/reference-actual'
+      : artifact.mode === 'before-after'
+        ? 'visual-review/before-after'
+        : artifact.mode === 'focus-board'
+          ? 'visual-review/focus-board'
+          : 'visual-review/parallel-board',
+  }));
+  const warnings = [];
+
+  if (relevant && matchingArtifacts.length === 0) {
+    warnings.push(
+      expectsParallelBoard
+        ? '检测到界面视觉改动且用户在比较多方向实验，但未看到本次并行实验证据板。'
+        : expectsFocusBoard
+          ? '检测到界面视觉改动且用户在关注局部细节，但未看到本次局部焦点证据板。'
+          : expectsReferenceCompare
+        ? '检测到界面视觉改动且已有参考图/设计稿语义，但未看到本次“效果图 / 实现截图”对比证据。'
+        : '检测到界面视觉改动，但未看到本次 visual-compare 产出的视觉对比或修改前后自检证据。'
+    );
+  } else if (relevant && expectsReferenceCompare && referenceArtifacts.length === 0 && beforeAfterArtifacts.length > 0) {
+    warnings.push('当前只发现修改前后自检图；如果已有参考图或设计稿，请补一份“效果图 / 实现截图”对比图。');
+  } else if (relevant && expectsFocusBoard && focusArtifacts.length === 0 && matchingArtifacts.length > 0) {
+    warnings.push('当前有视觉证据，但局部细节仍建议补一份局部焦点证据板，方便围绕编号区域复核。');
+  } else if (relevant && expectsParallelBoard && parallelArtifacts.length === 0 && matchingArtifacts.length > 0) {
+    warnings.push('当前有视觉证据，但多方向实验仍建议补一份并行实验证据板，把方案和指标放到同一板里审查。');
+  }
+
+  const summary = !relevant
+    ? '当前场景未要求视觉评审证据'
+    : matchingArtifacts.length > 0
+      ? (
+          expectsParallelBoard
+            ? `已找到 ${matchingArtifacts.length} 份并行实验证据板`
+            : expectsFocusBoard
+              ? `已找到 ${matchingArtifacts.length} 份局部焦点证据板`
+              : expectsReferenceCompare
+            ? `已找到 ${matchingArtifacts.length} 份效果图 / 实现截图对比证据`
+            : `已找到 ${matchingArtifacts.length} 份视觉对比、局部焦点或修改前后自检证据`
+        )
+      : (
+          expectsParallelBoard
+            ? '未找到本次并行实验证据板'
+            : expectsFocusBoard
+              ? '未找到本次局部焦点证据板'
+              : expectsReferenceCompare
+            ? '未找到本次效果图 / 实现截图对比证据'
+            : '未找到本次 visual-compare 视觉证据'
+        );
+
+  return {
+    status: !relevant || matchingArtifacts.length > 0 ? 'pass' : 'needs-evidence',
+    relevant,
+    expectsReferenceCompare,
+    expectsFocusBoard,
+    expectsParallelBoard,
+    artifacts: visualArtifacts,
+    matchingArtifacts,
+    warnings,
+    evidence: {
+      present: matchingArtifacts.length > 0,
+      sources: evidenceSources,
+      summary,
+    },
+  };
+}
+
+export {
+  VISUAL_REVIEW_DIR,
+  VISUAL_REVIEW_SCHEMA,
+};