@openprd/cli 0.1.9 → 0.1.11

package/src/openprd.js

@@ -33,7 +33,7 @@ import { doctorOpenPrdAgentIntegration, setupOpenPrdAgentIntegration, updateOpen
 import { finishLoopWorkspace, initLoopWorkspace, nextLoopWorkspace, planLoopWorkspace, promptLoopWorkspace, runLoopWorkspace, statusLoopWorkspace, verifyLoopWorkspace } from './loop.js';
 import { timestamp } from './time.js';
 import { parseCommandArgs, usage } from './cli/args.js';
-import { printAcceptedSpecsResult, printAgentIntegrationResult, printBenchmarkResult, printCaptureResult, printClarifyResult, printClassifyResult, printDevelopmentStandardsResult, printDiagramResult, printDiffResult, printDoctorResult, printFleetResult, printFreezeResult, printGrowthResult, printHandoffResult, printHistoryResult, printInitResult, printInterviewResult, printKnowledgeResult, printLearningResult, printLoopResult, printNextResult, printOpenPrdChangeActionResult, printOpenPrdChangesResult, printOpenSpecChangeValidationResult, printOpenSpecDiscoveryResult, printOpenSpecGenerateResult, printOpenSpecTaskResult, printPlaygroundResult, printQualityResult, printReleaseResult, printReviewResult, printRunResult, printSelfUpdateResult, printStandardsResult, printStatus, printSynthesizeResult, printUpgradeResult, printValidation, printVisualCompareResult } from './cli/print.js';
+import { printAcceptedSpecsResult, printAgentIntegrationResult, printBenchmarkResult, printBrainstormResult, printCaptureResult, printClarifyResult, printClassifyResult, printDesignStarterResult, printDevelopmentStandardsResult, printDiagramResult, printDiffResult, printDoctorResult, printFleetResult, printFreezeResult, printGrowthResult, printHandoffResult, printHistoryResult, printInitResult, printInterviewResult, printKnowledgeResult, printLearningResult, printLoopResult, printNextResult, printOpenPrdChangeActionResult, printOpenPrdChangesResult, printOpenSpecChangeValidationResult, printOpenSpecDiscoveryResult, printOpenSpecGenerateResult, printOpenSpecTaskResult, printPlaygroundResult, printQualityResult, printReleaseResult, printReviewResult, printRunResult, printSelfUpdateResult, printStandardsResult, printStatus, printSynthesizeResult, printUpgradeResult, printValidation, printVisualCompareResult, printVisualPrepareResult } from './cli/print.js';
 import { cjoin, exists, readJson, writeJson, writeText, writeYaml } from './fs-utils.js';
 import { diagramWorkspace } from './diagram-workspace.js';
 import { createOpenSpecDiscoveryWorkspace } from './discovery.js';
@@ -61,11 +61,15 @@ import {
   rejectGrowthCandidateWorkspace,
   reviewGrowthWorkspace,
 } from './growth.js';
+import { brainstormWorkspace } from './brainstorm.js';
+import { buildBrainstormPresentationTemplatePayload, brainstormPresentationWorkspace } from './brainstorm-presentation.js';
+import { designStarterWorkspace } from './design-starter.js';
 import { buildReviewPresentationTemplatePayload, reviewPresentationWorkspace } from './review-presentation.js';
 import { analyzeWorkspaceRegistryHygiene } from './registry-hygiene.js';
 import { syncSessionBindingFromChange } from './session-binding.js';
 import { readSessionRegistry } from './session-registry.js';
 import { visualCompareWorkspace } from './visual-compare.js';
+import { visualPrepareWorkspace } from './visual-prepare.js';
 import { captureWorkspace, clarifyWorkspace, classifyWorkspace, computeWorkspaceGuidance, diffWorkspace, historyWorkspace, interviewWorkspace, nextWorkspace, playgroundWorkspace, reviewWorkspace, synthesizeWorkspace } from './workspace-workflow.js';
 import { appendDecision, appendProgress, appendVerification, appendWorkflowEvent, buildCurrentStateSnapshot, buildWorkflowTaskGraph, computeWorkspaceDigest, CORE_TEMPLATE_FILES, ensureWorkspaceSkeleton, isSupportedProductType, loadCurrentLaneSnapshot, loadLatestVersionSnapshot, loadWorkspace, migrateWorkspaceSkeleton, normalizeVersionId, persistWorkspaceCurrentState, readVersionIndex, resolveActiveTemplatePack, resolveCurrentProductType, validateWorkspace } from './workspace-core.js';
 import { readWorkspaceRegistry } from './workspace-registry.js';
@@ -784,8 +788,10 @@ export async function main(argv = process.argv.slice(2)) {
 
     if (command === 'self-update') {
       const result = await selfUpdateWorkspace({
+        check: flags.check,
         dryRun: flags.dryRun,
         json: flags.json,
+        openprdHome: flags.openprdHome,
       });
       printSelfUpdateResult(result, flags.json);
       return result.ok ? 0 : 1;
@@ -866,6 +872,9 @@ export async function main(argv = process.argv.slice(2)) {
         evidence: flags.evidence,
         notes: flags.notes,
         repairAgent: flags.repairAgent,
+        worktree: flags.worktree,
+        branch: flags.branch,
+        allowDirtyMain: flags.allowDirtyMain,
       };
       if (flags.init) {
         result = await initLoopWorkspace(projectPath, options);
@@ -944,6 +953,20 @@ export async function main(argv = process.argv.slice(2)) {
       return result.ok ? 0 : 1;
     }
 
+    if (command === 'visual-prepare') {
+      const result = await visualPrepareWorkspace(projectPath, {
+        reference: flags.reference,
+        grid: flags.grid,
+        boxes: flags.boxes,
+        include: flags.include,
+        id: flags.id,
+        title: flags.title,
+        out: flags.out,
+      });
+      printVisualPrepareResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
     if (command === 'visual-compare') {
       const result = await visualCompareWorkspace(projectPath, {
         reference: flags.reference,
@@ -962,6 +985,22 @@ export async function main(argv = process.argv.slice(2)) {
       return result.ok ? 0 : 1;
     }
 
+    if (command === 'design-starter') {
+      const result = await designStarterWorkspace(projectPath, {
+        starter: flags.starter,
+        out: flags.out,
+        title: flags.title,
+        brief: flags.brief,
+        sections: flags.sections,
+        noExternalFacts: flags.noExternalFacts,
+        noBrandAssets: flags.noBrandAssets,
+        noRealImages: flags.noRealImages,
+        force: flags.force,
+      });
+      printDesignStarterResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
     if (command === 'grow') {
       const firstArgIsProjectPath = !flags.path && positionals.length > 0 && await isDirectoryPath(positionals[0]);
       const growthProjectPath = path.resolve(flags.path ?? (firstArgIsProjectPath ? positionals[0] : process.cwd()));
@@ -1073,6 +1112,16 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === 'brainstorm') {
+      const result = await brainstormWorkspace(projectPath, {
+        topic: flags.topic,
+        open: flags.open || !flags.json,
+        json: flags.json,
+      });
+      printBrainstormResult(result, flags.json);
+      return 0;
+    }
+
     if (command === 'learn') {
       if (flags.enable || flags.disable) {
         const enabled = flags.enable ? true : false;
@@ -1163,6 +1212,38 @@ export async function main(argv = process.argv.slice(2)) {
       return flags.failOnViolation && !result.ok ? 1 : 0;
     }
 
+    if (command === 'brainstorm-presentation') {
+      if (flags.template) {
+        console.log(JSON.stringify(buildBrainstormPresentationTemplatePayload(), null, 2));
+        return 0;
+      }
+      const result = await brainstormPresentationWorkspace(projectPath, {
+        presentationPath: flags.presentation,
+        write: flags.write,
+      });
+      if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`展示文案校验: ${result.ok ? '通过' : '需要重写'}`);
+        console.log(`主题: ${result.topic}`);
+        console.log(`超限或格式问题: ${result.presentationFeedback.length}`);
+        if (result.presentationFeedback.length > 0) {
+          for (const item of result.presentationFeedback.slice(0, 6)) {
+            const pathHint = item.jsonPath ? `${item.jsonPath}: ` : '';
+            const sizeHint = item.maxChars ? ` 当前 ${item.currentChars} 字，限制 ${item.maxChars} 字。` : '';
+            console.log(`- ${item.area} / ${item.target}: ${pathHint}${item.action}${sizeHint}`);
+          }
+        }
+        if (result.written) {
+          console.log(`已写入: ${result.written}`);
+        }
+        if (result.htmlPath) {
+          console.log(`已更新脑暴页面: ${result.htmlPath}`);
+        }
+      }
+      return flags.failOnViolation && !result.ok ? 1 : 0;
+    }
+
     if (command === 'diagram') {
       const result = await diagramWorkspace(projectPath, { open: flags.open, type: flags.type, input: flags.input, mark: flags.mark });
       printDiagramResult(result, flags.json);
@@ -1384,6 +1465,7 @@ export {
   clarifyWorkspace,
   captureWorkspace,
   playgroundWorkspace,
+  brainstormWorkspace,
   generateLearningReviewWorkspace,
   setLearningReviewModeWorkspace,
   synthesizeWorkspace,
@@ -1392,6 +1474,7 @@ export {
   historyWorkspace,
   releaseWorkspace,
   reviewWorkspace,
+  brainstormPresentationWorkspace,
   reviewPresentationWorkspace,
   freezeWorkspace,
   handoffWorkspace,
@@ -1409,6 +1492,7 @@ export {
   archiveOpenPrdChangeWorkspace,
   listAcceptedSpecsWorkspace,
   diagramWorkspace,
+  designStarterWorkspace,
   classifyWorkspace,
   interviewWorkspace,
   loadWorkspace,
@@ -1423,6 +1507,7 @@ export {
   rejectKnowledgeCandidate,
   archiveKnowledgeCandidate,
   restoreKnowledgeCandidate,
+  visualPrepareWorkspace,
   visualCompareWorkspace,
   checkDevelopmentStandardsWorkspace,
   initGrowthWorkspace,

package/src/openspec/change-validate.js

@@ -210,6 +210,7 @@ export async function validateOpenSpecChangeWorkspace(projectRoot, options = {})
     optional: !(await exists(cjoin(projectRoot, '.openprd'))),
     sourceManuals: options.sourceManuals,
     docsContent: options.docsContent,
+    folderManualModuleName: options.folderManualModuleName,
   });
   if (!standards.skipped) {
     errors.push(...standards.errors);

package/src/prd-core.js

@@ -239,6 +239,30 @@ export function buildPrdSnapshot(ws, options = {}) {
       successMetrics: normalizeArray(pickValue(options.successMetrics, state.successMetrics)),
       acceptanceGoals: normalizeArray(pickValue(options.acceptanceGoals, state.acceptanceGoals)),
     },
+    validation: {
+      community: normalizeArray(pickValue(options.community, state.community)),
+      seedUsers: normalizeArray(pickValue(options.seedUsers, state.seedUsers)),
+      communityFit: normalizeArray(pickValue(options.communityFit, state.communityFit)),
+      currentAlternative: pickValue(options.currentAlternative, state.currentAlternative, state.asIs),
+      painEvidence: normalizeArray(pickValue(options.painEvidence, state.painEvidence)),
+      manualPath: normalizeArray(pickValue(options.manualPath, state.manualPath)),
+      manualPlaybook: normalizeArray(pickValue(options.manualPlaybook, state.manualPlaybook)),
+      commitmentSignals: normalizeArray(pickValue(options.commitmentSignals, state.commitmentSignals)),
+      firstValidationStep: pickValue(options.firstValidationStep, state.firstValidationStep, state.nextStep),
+      defaultAlivePlan: normalizeArray(pickValue(options.defaultAlivePlan, state.defaultAlivePlan)),
+      paymentProof: normalizeArray(pickValue(options.paymentProof, state.paymentProof)),
+      mvpSlice: pickValue(options.mvpSlice, state.mvpSlice),
+      weekendTest: pickValue(options.weekendTest, state.weekendTest),
+      smallestExecution: normalizeArray(pickValue(options.smallestExecution, state.smallestExecution)),
+      productizeGate: normalizeArray(pickValue(options.productizeGate, state.productizeGate)),
+      firstCustomerPath: normalizeArray(pickValue(options.firstCustomerPath, state.firstCustomerPath)),
+      pricingHypothesis: pickValue(options.pricingHypothesis, state.pricingHypothesis),
+      customerOneProfitability: pickValue(options.customerOneProfitability, state.customerOneProfitability),
+      growthDiscipline: normalizeArray(pickValue(options.growthDiscipline, state.growthDiscipline)),
+      reversibility: pickValue(options.reversibility, state.reversibility),
+      customerTruth: pickValue(options.customerTruth, state.customerTruth),
+      valuesFit: pickValue(options.valuesFit, state.valuesFit),
+    },
     scope: {
       inScope: normalizeArray(pickValue(options.inScope, state.inScope)),
       outOfScope: normalizeArray(pickValue(options.outOfScope, state.outOfScope)),
@@ -367,6 +391,30 @@ export function renderPrdMarkdown(snapshot) {
       ['成功指标', sections.goals.successMetrics],
       ['验收目标', sections.goals.acceptanceGoals],
     ]),
+    renderSection('验证与创业闭环', [
+      ['可触达社区', sections.validation.community],
+      ['第一批种子用户', sections.validation.seedUsers],
+      ['社区契合与触达依据', sections.validation.communityFit],
+      ['当前替代方案', sections.validation.currentAlternative],
+      ['痛点与替代证据', sections.validation.painEvidence],
+      ['手工交付路径', sections.validation.manualPath],
+      ['手工作战卡', sections.validation.manualPlaybook],
+      ['承诺信号', sections.validation.commitmentSignals],
+      ['首个低成本验证', sections.validation.firstValidationStep],
+      ['先活下来方案', sections.validation.defaultAlivePlan],
+      ['付费验证信号', sections.validation.paymentProof],
+      ['第一版只做一件事', sections.validation.mvpSlice],
+      ['周末级验证', sections.validation.weekendTest],
+      ['最小工具桥接', sections.validation.smallestExecution],
+      ['产品化门槛', sections.validation.productizeGate],
+      ['第一批客户路径', sections.validation.firstCustomerPath],
+      ['初始收费假设', sections.validation.pricingHypothesis],
+      ['客户 1 盈利路径', sections.validation.customerOneProfitability],
+      ['销售与增长纪律', sections.validation.growthDiscipline],
+      ['可逆性判断', sections.validation.reversibility],
+      ['客户真问题校验', sections.validation.customerTruth],
+      ['价值观一致性', sections.validation.valuesFit],
+    ]),
     renderSection('范围与非目标', [
       ['范围内', sections.scope.inScope],
       ['范围外', sections.scope.outOfScope],
@@ -459,6 +507,32 @@ const BUSINESS_GUARDRAIL_FIELD_DESCRIPTORS = [
   { section: 'businessGuardrails', path: 'businessGuardrails.stopLossActions', label: '止损动作', prompt: '触发异常后，应该降级、暂停、关闭哪些能力，谁来处理？' },
 ];
 
+
+const VALIDATION_REQUIRED_FIELD_DESCRIPTORS = [
+  { section: 'validation', path: 'validation.community', label: '第一批可触达人群', prompt: '第一批最容易触达的社区、渠道或人群是谁？' },
+  { section: 'validation', path: 'validation.seedUsers', label: '种子用户', prompt: '至少 3 到 10 个最该先找的人是谁？' },
+  { section: 'validation', path: 'validation.communityFit', label: '社区契合', prompt: '你为什么算这个社区里的自己人？你现在是否已经在真实参与或贡献，他们为什么愿意先相信你？' },
+  { section: 'validation', path: 'validation.currentAlternative', label: '当前替代方案', prompt: '用户现在主要靠什么替代方案、流程或人工方式在解决？' },
+  { section: 'validation', path: 'validation.painEvidence', label: '痛点证据', prompt: '这个问题到底有多痛，用户已经在为更差的办法花什么时间或金钱？' },
+  { section: 'validation', path: 'validation.manualPath', label: '手工交付路径', prompt: '如果先不做完整产品，怎么靠手工服务或半自动流程把价值跑出来？' },
+  { section: 'validation', path: 'validation.manualPlaybook', label: '手工作战卡', prompt: '触发条件、步骤、工具、耗时和交接点分别是什么？' },
+  { section: 'validation', path: 'validation.commitmentSignals', label: '承诺信号', prompt: '什么真实承诺最能证明这不是口头兴趣？' },
+  { section: 'validation', path: 'validation.firstValidationStep', label: '最低成本验证', prompt: '最低成本先验证哪一步最关键？' },
+  { section: 'validation', path: 'validation.defaultAlivePlan', label: '先活下来方案', prompt: '验证阶段怎样不把成本、复杂度和维护负担一下子做爆？' },
+  { section: 'validation', path: 'validation.paymentProof', label: '付费验证信号', prompt: '有没有 10 个样本、3/10 付费意愿或更强交易信号？' },
+  { section: 'validation', path: 'validation.mvpSlice', label: '一件事 MVP', prompt: '第一版到底只做哪一件事？' },
+  { section: 'validation', path: 'validation.weekendTest', label: '周末级验证', prompt: '能不能压成周末级 MVP、顾问式试跑或更轻验证？' },
+  { section: 'validation', path: 'validation.smallestExecution', label: '最小工具桥接', prompt: '能不能先用 spreadsheet、表单或 no-code 工具把第一版跑起来？如果必须开始做产品，也只自动化最重复的一步并先压成 forms / lists / CRUD 骨架；不要先为假想中的未来客户造复杂能力。' },
+  { section: 'validation', path: 'validation.productizeGate', label: '产品化门槛', prompt: '达到什么条件才允许继续产品化或加功能？先服务今天已经存在的重复需求，不要提前为未来规模开壳。' },
+  { section: 'validation', path: 'validation.firstCustomerPath', label: '第一批客户路径', prompt: '第一批客户最现实的触达顺序是什么？' },
+  { section: 'validation', path: 'validation.pricingHypothesis', label: '初始收费假设', prompt: '从第一个客户开始准备怎么收费？' },
+  { section: 'validation', path: 'validation.customerOneProfitability', label: '客户 1 盈利路径', prompt: '第一个客户如何覆盖时间和交付成本？' },
+  { section: 'validation', path: 'validation.growthDiscipline', label: '增长纪律', prompt: '销售、launch 和增长阶段准备守哪些纪律？' },
+  { section: 'validation', path: 'validation.reversibility', label: '可逆性', prompt: '如果结果一般，这条路是否容易回退？是否在逼你做重招聘、长期绑定或重平台化这类不可逆决策？' },
+  { section: 'validation', path: 'validation.customerTruth', label: '客户真问题', prompt: '这更像在解决客户真问题，还是满足内部冲动？' },
+  { section: 'validation', path: 'validation.valuesFit', label: '价值观一致性', prompt: '这条路是否符合团队想坚持的价值观和长期经营方式？如果连续这样做 3 到 5 年，你还愿意住在这套业务里吗？' },
+];
+
 const TYPE_REQUIRED_FIELD_DESCRIPTORS = {
   consumer: [
     { section: 'consumer', path: 'typeSpecific.fields.persona', label: '用户画像', prompt: '目标用户画像是什么？' },
@@ -517,8 +591,49 @@ function isMissingPrdValue(value) {
   return false;
 }
 
-export function getRequiredFieldDescriptors(productType) {
+function needsValidationLoop(snapshot) {
+  const sections = snapshot?.sections ?? {};
+  const validation = sections.validation ?? {};
+  const explicitValidationSignals = [
+    validation.community,
+    validation.seedUsers,
+    validation.communityFit,
+    validation.painEvidence,
+    validation.manualPath,
+    validation.manualPlaybook,
+    validation.commitmentSignals,
+    validation.defaultAlivePlan,
+    validation.paymentProof,
+    validation.mvpSlice,
+    validation.weekendTest,
+    validation.smallestExecution,
+    validation.productizeGate,
+    validation.firstCustomerPath,
+    validation.pricingHypothesis,
+    validation.customerOneProfitability,
+    validation.growthDiscipline,
+    validation.reversibility,
+    validation.customerTruth,
+    validation.valuesFit,
+  ];
+  if (explicitValidationSignals.some((value) => !isMissingPrdValue(value))) {
+    return true;
+  }
+  const text = flattenForSearch({
+    problem: sections.problem,
+    goals: sections.goals,
+    scope: sections.scope,
+    requirements: sections.requirements,
+    risks: sections.risks,
+  });
+  return /(创业|脑暴|brainstorm|0\s*(到|to)\s*1|值不值得|worth doing|种子用户|第一批(客户|用户)|社区|workaround|手工交付|顾问式|一件事\s*mvp|周末级|首批成交|default alive|productize|no-code|spreadsheet|first customer)/iu.test(text);
+}
+
+export function getRequiredFieldDescriptors(productType, options = {}) {
   const descriptors = [...BASE_REQUIRED_FIELD_DESCRIPTORS];
+  if (options.includeValidation) {
+    descriptors.push(...VALIDATION_REQUIRED_FIELD_DESCRIPTORS);
+  }
   if (TYPE_REQUIRED_FIELD_DESCRIPTORS[productType]) {
     descriptors.push(...TYPE_REQUIRED_FIELD_DESCRIPTORS[productType]);
   }
@@ -550,7 +665,8 @@ export function needsBusinessGuardrails(snapshot) {
 
 export function analyzePrdSnapshot(snapshot) {
   const productType = snapshot.productType ?? null;
-  const descriptors = getRequiredFieldDescriptors(productType);
+  const includeValidation = needsValidationLoop(snapshot);
+  const descriptors = getRequiredFieldDescriptors(productType, { includeValidation });
   if (needsBusinessGuardrails(snapshot)) {
     descriptors.push(...BUSINESS_GUARDRAIL_FIELD_DESCRIPTORS);
   }
@@ -578,6 +694,7 @@ export function analyzePrdSnapshot(snapshot) {
 
   return {
     productType,
+    includeValidation,
     totalRequiredFields,
     completedRequiredFields,
     missingRequiredFields: missingFields.length,

package/src/quality-html-artifact.js

@@ -517,13 +517,38 @@ function exceptionItems(report) {
     }));
 }
 
+const EVIDENCE_SOURCE_LABELS = {
+  'openprd-tasks': '任务清单',
+  'project-scan': '项目扫描',
+  'openprd-knowledge': '项目经验库',
+  'openprd-knowledge-candidate': '待确认经验草案',
+  'openprd-growth-ledger': '成长记录',
+  'openprd-test-report': '测试报告',
+  'openprd-visual-review': '视觉对比记录',
+  evidence: '证据文件',
+};
+
+const EVIDENCE_PATH_LABELS = {
+  'no-active-change': '当前没有进行中的需求改动',
+  'no-cost-risk-detected': '本次没有发现成本相关风险',
+  'business-guardrails-evidence': '成本与滥用护栏证据',
+};
+
+function evidenceSourceLabel(source) {
+  return EVIDENCE_SOURCE_LABELS[source] ?? source;
+}
+
+function evidencePathLabel(path) {
+  return EVIDENCE_PATH_LABELS[path] ?? path;
+}
+
 function evidenceItems(report) {
   return evidenceRows(report)
     .filter((row) => !row.empty)
     .slice(0, 5)
     .map((row) => ({
       summary: gateDisplay(row.gate),
-      detail: `${row.source}，${row.path}`,
+      detail: `${evidenceSourceLabel(row.source)}，${evidencePathLabel(row.path)}`,
     }));
 }
 
@@ -573,8 +598,8 @@ function environmentItems(report) {
     {
       summary: '成长账本',
       detail: Number(growth.summary?.eventCount ?? 0) > 0
-        ? `已记录 ${growth.summary.eventCount} 条事件，completion checkpoint ${growth.summary.completionCheckpoints ?? 0} 条`
-        : '当前还没有成长账本事件；完成态至少应留下 checkpoint 或候选',
+        ? `已记录 ${growth.summary.eventCount} 条成长事件，其中收尾检查记录 ${growth.summary.completionCheckpoints ?? 0} 条`
+        : '当前还没有成长记录；收尾前至少应留下一条收尾检查记录或经验草案',
     },
   ];
 }
@@ -692,8 +717,8 @@ function tableRowsForEvidence(report) {
   return evidenceRows(report).map((row) => `
     <tr>
       <td>${escapeHtml(gateDisplay(row.gate))}</td>
-      <td>${escapeHtml(row.source)}</td>
-      <td><code>${escapeHtml(row.path)}</code></td>
+      <td>${escapeHtml(evidenceSourceLabel(row.source))}</td>
+      <td><code>${escapeHtml(evidencePathLabel(row.path))}</code></td>
       <td>${row.gate.required ? '本期必测' : '按风险确认'}</td>
     </tr>
   `).join('\n');

package/src/quality-learning.js

@@ -575,9 +575,24 @@ function renderList(items, fallback) {
   return list.map((item) => `- ${item}`).join('\n')
 }
 
-function renderEvidenceSources(evidenceSources) {
+function describeEvidenceSource(source, options = {}) {
+  if (!options.genericPaths) {
+    return `${source.kind}: \`${source.path}\``;
+  }
+  const genericLabel = {
+    'quality-report': '当前项目里最新一轮相关的质量报告与 HTML 评估页',
+    'diagnostic-bundle': '当前任务对应的诊断目录',
+    'diagnostic-report': '当前任务对应的 diagnostic-report',
+    'runtime-events': '当前任务对应的 runtime-events',
+    timeline: '当前任务对应的 timeline',
+    'root-cause-candidates': '当前任务对应的 root-cause-candidates',
+  }[source.kind] ?? '当前任务对应的相关证据';
+  return `${source.kind}: ${genericLabel}`;
+}
+
+function renderEvidenceSources(evidenceSources, options = {}) {
   return renderList(
-    evidenceSources.map((source) => `${source.kind}: \`${source.path}\``),
+    evidenceSources.map((source) => describeEvidenceSource(source, options)),
     '当前来源没有显式证据清单，后续应补齐标准诊断目录。',
   )
 }
@@ -608,6 +623,18 @@ function renderCorrelationSection({ correlationFields, extraContextFields, missi
 }
 
 export function renderExperienceSkill({ skillName, source }) {
+  const stableProblemSummary = source.kind === 'quality-report'
+    ? (
+      source.attentionGates.length > 0
+        ? `当前任务的质量收口与门禁闭环（${source.attentionGates.slice(0, 4).join(', ')}）`
+        : '当前任务的质量收口与门禁闭环'
+    )
+    : (
+      source.rootCauseCandidates[0]?.title
+      ?? source.eventNames[0]
+      ?? source.symptoms[0]
+      ?? '当前任务对应的问题症状'
+    );
   const triggers = source.kind === 'quality-report'
     ? [
       '某项任务改动了前端、后端、agent 工作流或错误处理行为。',
@@ -626,9 +653,9 @@ export function renderExperienceSkill({ skillName, source }) {
       : '适用于已经拿到 runtime-events、timeline、root-cause-candidates 或 diagnostic-report 的排查任务。',
   ]
   const typicalInputs = [
-    source.title ? `问题摘要: ${source.title}` : null,
+    stableProblemSummary ? `问题摘要: ${stableProblemSummary}` : null,
     source.evidenceSources.length > 0
-      ? `可直接使用的证据: ${source.evidenceSources.slice(0, 4).map((item) => `${item.kind}:${item.path}`).join('；')}`
+      ? `可直接使用的证据类型: ${source.evidenceSources.slice(0, 4).map((item) => item.kind).join('；')}`
       : null,
     source.eventNames.length > 0 ? `关键事件: ${source.eventNames.join(' -> ')}` : null,
   ]
@@ -637,10 +664,23 @@ export function renderExperienceSkill({ skillName, source }) {
     source.verificationSteps.length > 0 ? `最小验证链路: ${source.verificationSteps[0]}` : null,
     '可复用的项目级 knowledge skill 或后续 candidate / incident / pattern 记录。',
   ]
+  const useWhen = source.kind === 'quality-report'
+    ? 'Use when the current task is entering quality closeout and you should reuse a proven evidence and gate-check path instead of rebuilding the checklist from scratch.'
+    : 'Use when the current task overlaps this verified diagnosis pattern, symptoms, or touched files and you should reuse proven evidence before starting from scratch.'
+  const antiPatterns = [
+    source.kind === 'quality-report'
+      ? '如果当前任务还没进入验证或收尾阶段，不要把这条经验当成通用实现模板直接套用。'
+      : '如果当前问题没有出现相似症状、关键事件或证据入口，不要只因为改到相似文件就直接套用这条经验。',
+    '如果只是文件名、路径或个别词相似，但当前目标、阶段或验证方式不同，不要直接照搬。',
+    source.evidenceSources.length > 0
+      ? '如果本轮已经拿到更新的现场证据，先核对新证据，再决定是否复用这条经验。'
+      : null,
+  ]
 
   return `---
 name: ${skillName}
-description: 由 OpenPrd 从 ${source.kind} 自动沉淀的项目级排查经验。目标是在相似问题再次出现时优先复用现有诊断证据，而不是临时补日志。
+description: ${useWhen}
+use_when: ${useWhen}
 ---
 
 # ${skillName}
@@ -663,7 +703,11 @@ ${renderList(typicalOutputs, '至少产出可复用结论、验证链路和后
 
 ## 先看哪些证据
 
-${renderEvidenceSources(source.evidenceSources)}
+${renderEvidenceSources(source.evidenceSources, { genericPaths: true })}
+
+## 不要直接套用
+
+${renderList(antiPatterns, '如果只是表面相似，但目标和验证方式不一致，不要直接套用。')}
 
 ## 关联字段
 

package/src/quality.js

@@ -115,6 +115,13 @@ const EVIDENCE_TOKENS = {
   growth: ['growth ledger', 'completion checkpoint', 'openprd grow', 'workflow-gotcha', 'code-extension', '自我成长', '账本', '候选'],
 };
 
+const DIAGNOSTIC_SURFACE_LABELS = {
+  'runtime-events': '运行事件记录',
+  timeline: '问题时间线',
+  'root-cause-candidates': '根因排查线索',
+  'diagnostic-report': '诊断报告',
+};
+
 function qualityPath(projectRoot, relativePath) {
   return cjoin(projectRoot, relativePath);
 }
@@ -606,18 +613,21 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
     };
   }
   if (observability.status === 'pass') {
-    const observabilitySignals = [
-      ...observability.centralizedTools,
-      ...(observability.diagnosticSurfaces ?? []),
-    ];
+    const toolCount = observability.centralizedTools.length;
+    const surfaceLabels = (observability.diagnosticSurfaces ?? [])
+      .map((surface) => DIAGNOSTIC_SURFACE_LABELS[surface] ?? surface);
+    const signalSummary = [
+      toolCount > 0 ? `${toolCount} 类日志或追踪工具` : '',
+      surfaceLabels.length > 0 ? `${surfaceLabels.length} 类诊断记录` : '',
+    ].filter(Boolean).join('和');
     ledger.traceability = {
       ...ledger.traceability,
       present: true,
       sources: [
         ...ledger.traceability.sources,
-        { path: 'project-observability-signals', source: observabilitySignals.join(', ') || 'observability' },
+        { path: '项目内的日志与追踪配置', source: signalSummary ? `检测到${signalSummary}` : '日志追踪检查' },
       ].slice(0, 12),
-      summary: `检测到 ${observability.correlationFields.length} 个链路关联字段${observability.diagnosticSurfaces?.length ? `；诊断面: ${observability.diagnosticSurfaces.join(', ')}` : ''}`,
+      summary: `出问题时可以追查：检测到 ${observability.correlationFields.length} 个追踪线索${surfaceLabels.length > 0 ? `，并留有${surfaceLabels.join('、')}` : ''}`,
     };
   }
   if (!businessGuardrails.riskDetected || businessGuardrails.status === 'pass') {
@@ -641,8 +651,8 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
         ...knowledge.candidates.slice(0, 3).map((candidate) => ({ path: candidate, source: 'openprd-knowledge-candidate' })),
       ].slice(0, 12),
       summary: knowledge.candidates.length > 0
-        ? `已有 ${knowledge.skills.length} 个项目经验 Skill，命中 ${knowledge.adoption?.totals?.hit ?? 0} / 引用 ${knowledge.adoption?.totals?.referenced ?? 0} / 注入 ${knowledge.adoption?.totals?.injected ?? 0}，另有 ${knowledge.candidates.length} 个待确认 candidate`
-        : `已有 ${knowledge.skills.length} 个项目经验 Skill，命中 ${knowledge.adoption?.totals?.hit ?? 0} / 引用 ${knowledge.adoption?.totals?.referenced ?? 0} / 注入 ${knowledge.adoption?.totals?.injected ?? 0}`,
+        ? `已沉淀 ${knowledge.skills.length} 条项目经验，近期被实际复用 ${knowledge.adoption?.totals?.referenced ?? 0} 次，另有 ${knowledge.candidates.length} 条经验草案等确认`
+        : `已沉淀 ${knowledge.skills.length} 条项目经验，近期被实际复用 ${knowledge.adoption?.totals?.referenced ?? 0} 次`,
     };
   } else if (knowledge.candidates.length > 0) {
     ledger.knowledge = {
@@ -652,7 +662,7 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
         ...ledger.knowledge.sources,
         ...knowledge.candidates.slice(0, 6).map((candidate) => ({ path: candidate, source: 'openprd-knowledge-candidate' })),
       ].slice(0, 12),
-      summary: `已有 ${knowledge.candidates.length} 个待确认 knowledge candidate`,
+      summary: `已有 ${knowledge.candidates.length} 条经验草案等确认，确认后会成为可复用的项目经验`,
     };
   }
   if (growth?.summary) {
@@ -666,7 +676,7 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
           ...ledger.growth.sources,
           { path: growth.ledgerPath ?? OPENPRD_GROWTH_LEDGER, source: 'openprd-growth-ledger' },
         ].slice(0, 12),
-        summary: `growth 账本已有 ${growth.summary.eventCount ?? 0} 条事件，其中 completion checkpoint ${completionCheckpoints} 条`,
+        summary: `成长记录已有 ${growth.summary.eventCount ?? 0} 条，其中收尾检查记录 ${completionCheckpoints} 条`,
       };
     }
   }
@@ -1019,7 +1029,7 @@ function detectKnowledge({ config, knowledgeFiles, candidateState, knowledgeInde
     warnings.push('本次已经达到可交付状态，但还没有自动生成 knowledge candidate；收工前至少保留一条可审查的项目经验草案。');
   }
   if (config.knowledge.enabled && skills.length > 0 && adoption.totals.referenced === 0) {
-    warnings.push('项目级经验 skill 已产出，但还没有任何 run-context 引用记录；优先接入自动命中与注入链路。');
+    warnings.push('项目级经验 skill 已产出，但还没有任何 run-context 引用记录；优先接入候选召回与判断注入链路。');
   }
   return {
     status: !config.knowledge.enabled || hasReusableArtifact ? 'pass' : 'needs-attention',
@@ -1444,7 +1454,7 @@ export async function learnQualityWorkspace(projectRoot, options = {}) {
     };
   }
   const source = resolved.source;
-  const { incidentId, patternId, skillName } = deriveKnowledgeNames(source);
+  const { incidentId, patternId, skillName } = deriveKnowledgeNames(source, { stablePattern: true });
   const incidentPath = qualityPath(projectRoot, cjoin(KNOWLEDGE_DIR, 'incidents', `${incidentId}.json`));
   const patternPath = qualityPath(projectRoot, cjoin(KNOWLEDGE_DIR, 'patterns', `${patternId}.json`));
   const skillDir = qualityPath(projectRoot, cjoin(KNOWLEDGE_DIR, 'skills', skillName));