@openprd/cli 0.1.9 → 0.1.10

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,15 @@ 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)),
+      currentAlternative: pickValue(options.currentAlternative, state.currentAlternative, state.asIs),
+      manualPath: normalizeArray(pickValue(options.manualPath, state.manualPath)),
+      commitmentSignals: normalizeArray(pickValue(options.commitmentSignals, state.commitmentSignals)),
+      firstValidationStep: pickValue(options.firstValidationStep, state.firstValidationStep, state.nextStep),
+      defaultAlivePlan: normalizeArray(pickValue(options.defaultAlivePlan, state.defaultAlivePlan)),
+    },
     scope: {
       inScope: normalizeArray(pickValue(options.inScope, state.inScope)),
       outOfScope: normalizeArray(pickValue(options.outOfScope, state.outOfScope)),
@@ -367,6 +376,15 @@ export function renderPrdMarkdown(snapshot) {
       ['成功指标', sections.goals.successMetrics],
       ['验收目标', sections.goals.acceptanceGoals],
     ]),
+    renderSection('验证与创业闭环', [
+      ['可触达社区', sections.validation.community],
+      ['第一批种子用户', sections.validation.seedUsers],
+      ['当前替代方案', sections.validation.currentAlternative],
+      ['手工交付路径', sections.validation.manualPath],
+      ['承诺信号', sections.validation.commitmentSignals],
+      ['首个低成本验证', sections.validation.firstValidationStep],
+      ['先活下来方案', sections.validation.defaultAlivePlan],
+    ]),
     renderSection('范围与非目标', [
       ['范围内', sections.scope.inScope],
       ['范围外', sections.scope.outOfScope],

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

@@ -1019,7 +1019,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 +1444,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));