@openprd/cli 0.1.8 → 0.1.10

package/src/knowledge.js

@@ -170,6 +170,10 @@ function normalizeSkillIndexEntry(entry = {}) {
     ]),
     categories: normalizeStringList(skill.categories),
     triggerHints: normalizeStringList(skill.triggerHints),
+    useWhen: firstString(skill.useWhen, skill.use_when),
+    applicability: normalizeStringList(skill.applicability),
+    antiPatterns: normalizeStringList(skill.antiPatterns),
+    reviewFirst: normalizeStringList(skill.reviewFirst),
     touchedFiles: normalizeStringList(skill.touchedFiles),
     evidencePaths: normalizeStringList(skill.evidencePaths),
     rootCauseLabels: normalizeStringList(skill.rootCauseLabels),
@@ -213,6 +217,37 @@ function sortByLength(items = []) {
   return [...items].sort((left, right) => String(right).length - String(left).length);
 }
 
+function isGenericKnowledgeDescription(value) {
+  const normalized = normalizeSearchText(value);
+  if (!normalized) {
+    return true;
+  }
+  return [
+    '自动沉淀的项目级排查经验',
+    '待确认项目经验草案',
+    '自动生成的待确认项目经验草案',
+    '项目级排查经验',
+    '项目经验草案',
+  ].some((needle) => normalized.includes(normalizeSearchText(needle)));
+}
+
+function stripUseWhenPrefix(value) {
+  return String(value ?? '').trim().replace(/^use when\b[:：]?\s*/i, '').trim();
+}
+
+function deriveSkillUseWhen({ useWhen, description, applicability = [], triggerHints = [] }) {
+  const explicit = firstString(useWhen);
+  if (explicit) {
+    return explicit;
+  }
+  const desc = firstString(description);
+  if (desc && !isGenericKnowledgeDescription(desc)) {
+    return desc;
+  }
+  const fallback = firstString(applicability[0], triggerHints[0], desc);
+  return fallback ? `Use when ${stripUseWhenPrefix(fallback)}` : null;
+}
+
 function scoreQueryAgainstFields(queryText, queryTokens, fields = []) {
   let score = 0;
   const matchedOn = [];
@@ -264,22 +299,47 @@ function parseMarkdownSectionList(markdown, headings = []) {
   return uniq(collected);
 }
 
-function parseSkillMetadataFromText(markdown) {
+function parseFrontmatterValue(markdown, key) {
   const text = String(markdown ?? '');
   const frontmatter = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
-  const descriptionLine = frontmatter?.[1]
-    ?.split(/\r?\n/)
-    .map((line) => line.trim())
-    .find((line) => line.startsWith('description:'));
-  const description = descriptionLine ? descriptionLine.replace(/^description:\s*/, '').trim() : null;
-  const triggerHints = parseMarkdownSectionList(text, ['触发场景', '常见误判', '先看什么', '收尾顺序', '反模式', '下次触发时先看什么']);
-  const rootCauseLabels = parseMarkdownSectionList(text, ['可复用模式']);
+  if (!frontmatter) {
+    return null;
+  }
+  const pattern = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:\\s*(.+?)\\s*$`);
+  const line = frontmatter[1]
+    .split(/\r?\n/)
+    .map((item) => item.trim())
+    .find((item) => pattern.test(item));
+  if (!line) {
+    return null;
+  }
+  const match = line.match(pattern);
+  return match?.[1]?.trim() ?? null;
+}
+
+function parseSkillMetadataFromText(markdown) {
+  const text = String(markdown ?? '');
+  const description = parseFrontmatterValue(text, 'description');
+  const useWhen = firstString(
+    parseFrontmatterValue(text, 'use_when'),
+    parseFrontmatterValue(text, 'use-when'),
+    /^use when\b/i.test(String(description ?? '')) ? description : null,
+  );
+  const triggerHints = parseMarkdownSectionList(text, ['触发场景', '触发条件', '同步触发条件', '收尾顺序']);
+  const applicability = parseMarkdownSectionList(text, ['适用范围', '适用时机', 'When to Use', 'When to use']);
+  const antiPatterns = parseMarkdownSectionList(text, ['不要直接套用', '不要在这些情况使用', '不要在这些情况直接套用', 'When Not to Use', 'Do Not Use When', '反模式', '常见误判']);
+  const reviewFirst = parseMarkdownSectionList(text, ['下次触发时先看什么', '先看什么', '先看哪些证据', '判断前先看', '排查顺序']);
+  const rootCauseLabels = parseMarkdownSectionList(text, ['可复用模式', '常见根因']);
   const evidencePaths = uniq((text.match(/`([^`]+)`/g) ?? [])
     .map((entry) => entry.replace(/`/g, '').trim())
     .filter((entry) => entry.includes('/') || entry.endsWith('.md') || entry.endsWith('.js') || entry.endsWith('.ts')));
   return {
     description,
+    useWhen,
     triggerHints,
+    applicability,
+    antiPatterns,
+    reviewFirst,
     rootCauseLabels,
     evidencePaths,
   };
@@ -377,6 +437,18 @@ async function hydrateKnowledgeSkillEntry(projectRoot, entry, cache = new Map())
       ...parsedSkill.triggerHints,
       ...candidateBundles.flatMap((bundle) => bundle.triggerHints),
     ]).slice(0, 24),
+    applicability: uniq([
+      ...current.applicability,
+      ...parsedSkill.applicability,
+    ]).slice(0, 24),
+    antiPatterns: uniq([
+      ...current.antiPatterns,
+      ...parsedSkill.antiPatterns,
+    ]).slice(0, 24),
+    reviewFirst: uniq([
+      ...current.reviewFirst,
+      ...parsedSkill.reviewFirst,
+    ]).slice(0, 24),
     touchedFiles: uniq([
       ...current.touchedFiles,
       ...candidateBundles.flatMap((bundle) => bundle.touchedFiles),
@@ -391,6 +463,19 @@ async function hydrateKnowledgeSkillEntry(projectRoot, entry, cache = new Map())
       ...parsedSkill.rootCauseLabels,
       ...candidateBundles.flatMap((bundle) => bundle.rootCauseLabels),
     ]).slice(0, 24),
+    useWhen: deriveSkillUseWhen({
+      useWhen: current.useWhen ?? parsedSkill.useWhen,
+      description: current.description ?? parsedSkill.description,
+      applicability: uniq([
+        ...current.applicability,
+        ...parsedSkill.applicability,
+      ]),
+      triggerHints: uniq([
+        ...current.triggerHints,
+        ...parsedSkill.triggerHints,
+        ...candidateBundles.flatMap((bundle) => bundle.triggerHints),
+      ]),
+    }),
     description: current.description ?? parsedSkill.description,
     summary: current.summary ?? candidateBundles.map((bundle) => bundle.summary).find(Boolean) ?? null,
     adoption: normalizeSkillAdoption(current.adoption),
@@ -644,6 +729,29 @@ function summarizeReviewSignalKinds(reviewSignals = []) {
   return uniq(reviewSignals.map((signal) => signal.kind).filter(Boolean)).slice(0, 6);
 }
 
+function summarizeKnowledgeScenario(source = {}, candidate = null) {
+  if (source.kind === 'quality-report') {
+    return source.attentionGates.length > 0
+      ? `任务场景: 质量门禁收口（${source.attentionGates.slice(0, 4).join('、')}）`
+      : '任务场景: 质量门禁收口';
+  }
+  const topRootCause = source.rootCauseCandidates?.[0]?.title ?? null;
+  if (topRootCause) {
+    return `任务场景: ${topRootCause}`;
+  }
+  const topTrigger = normalizeStringList(source.triggers)[0] ?? null;
+  if (topTrigger) {
+    return `任务场景: ${topTrigger}`;
+  }
+  const fallbackTitle = firstString(candidate?.title, source.title);
+  return fallbackTitle ? `任务场景: ${fallbackTitle}` : null;
+}
+
+function summarizeEvidenceKinds(evidenceSources = []) {
+  const kinds = uniq(evidenceSources.map((item) => firstString(item.kind)).filter(Boolean));
+  return kinds.length > 0 ? `已有证据类型: ${kinds.join('、')}` : null;
+}
+
 function buildKnowledgeAbstraction({
   candidate,
   source,
@@ -670,27 +778,35 @@ function buildKnowledgeAbstraction({
     ...source.verificationSteps,
   ]).slice(0, 8);
   const typicalInputs = uniq([
-    firstString(source.title, candidate.title) ? `任务摘要: ${firstString(source.title, candidate.title)}` : null,
+    summarizeKnowledgeScenario(source, candidate),
     touchedFiles.length > 0 ? `相关文件: ${touchedFiles.slice(0, 6).join('、')}` : null,
-    source.evidenceSources.length > 0
-      ? `已有证据: ${source.evidenceSources.slice(0, 4).map((item) => `${item.kind}:${item.path}`).join('；')}`
-      : null,
+    summarizeEvidenceKinds(source.evidenceSources),
     reviewSignals.length > 0
       ? `验证信号: ${summarizeReviewSignalKinds(reviewSignals).join('、')}`
       : null,
   ]).slice(0, 6);
   const typicalOutputs = uniq([
-    relativeCandidateDir ? `knowledge candidate: ${relativeCandidateDir}/candidate.json` : null,
-    relativeCandidateDir ? `诊断报告: ${relativeCandidateDir}/diagnostic-report.json` : null,
-    relativeDraftSkillPath ? `draft skill: ${relativeDraftSkillPath}` : null,
+    relativeCandidateDir ? '项目经验候选与诊断包' : null,
+    relativeDraftSkillPath ? '待确认的项目经验草案' : null,
     verificationSteps[0] ? `验证结论: ${verificationSteps[0]}` : null,
+    '可复用的验证链路与收尾动作',
   ]).slice(0, 6);
+  const antiPatterns = uniq([
+    '如果只是文件名、路径或个别词相似，但当前目标和验证方式不同，不要直接套用。',
+    source.kind === 'quality-report'
+      ? '如果当前任务还没进入验证或收尾阶段，不要把这条经验当成通用实现模板。'
+      : '如果当前问题没有出现相似症状、事件或证据入口，不要因为改到相似模块就直接照搬旧结论。',
+    source.evidenceSources.length > 0
+      ? '如果本轮已经有更新的现场证据，先核对新证据，再决定是否复用旧经验。'
+      : null,
+  ]).slice(0, 4);
   return {
     triggerConditions,
     applicability,
     verificationSteps,
     typicalInputs,
     typicalOutputs,
+    antiPatterns,
   };
 }
 
@@ -707,13 +823,37 @@ function categoryReason(category) {
   return '这次实现已经具备沉淀项目经验的价值。';
 }
 
-function deriveKnowledgeNames(source) {
+function deriveStablePatternKey(source = {}) {
+  if (source.kind === 'quality-report') {
+    const gates = normalizeStringList(source.attentionGates);
+    if (gates.length > 0) {
+      return gates.slice(0, 4).join('-');
+    }
+    return 'quality-closeout';
+  }
+  const rootCauseLabels = normalizeStringList(source.rootCauseCandidates?.map((item) => item.title));
+  if (rootCauseLabels.length > 0) {
+    return rootCauseLabels.slice(0, 3).join('-');
+  }
+  const triggers = normalizeStringList(source.triggers);
+  if (triggers.length > 0) {
+    return triggers.slice(0, 4).join('-');
+  }
+  if (source.abstractPattern) {
+    return source.abstractPattern;
+  }
+  return firstString(source.title, source.sourceId, source.status, 'diagnostic') ?? 'diagnostic';
+}
+
+function deriveKnowledgeNames(source, options = {}) {
   const sourceRef = source?.sourceId ?? source?.title ?? source?.status ?? 'diagnostic';
   const sourceKind = source?.kind === 'quality-report' ? 'quality' : 'diagnostic';
+  const stablePattern = options.stablePattern !== false;
   const incidentId = source?.kind === 'quality-report'
     ? `incident-${sourceRef}`
     : `incident-${slugify(sourceRef, 'diagnostic')}`;
-  const patternId = `${sourceKind}-${slugify(sourceRef, sourceKind)}`;
+  const patternSeed = stablePattern ? deriveStablePatternKey(source) : sourceRef;
+  const patternId = `${sourceKind}-${slugify(patternSeed, sourceKind)}`;
   const skillName = `openprd-experience-${slugify(patternId)}`;
   return { incidentId, patternId, skillName };
 }
@@ -898,9 +1038,11 @@ function renderKnowledgeDraftSkill({ skillName, candidate, source, relativeCandi
     ...candidate.touchedFiles.map((file) => `\`${file}\``),
     ...source.evidenceSources.map((item) => `\`${item.path}\``),
   ]);
+  const useWhen = 'Use when the current task overlaps this draft project experience and you should verify fit before reusing it.';
   return `---
 name: ${skillName}
-description: OpenPrd 在本轮回顾时自动生成的待确认项目经验草案。
+description: ${useWhen}
+use_when: ${useWhen}
 ---
 
 # ${skillName}
@@ -929,6 +1071,10 @@ ${renderList(abstraction.typicalOutputs ?? [], '至少产出 knowledge candidate
 
 ${renderList(inspectItems, '先看本轮 touched files 和已有诊断证据。')}
 
+## 不要直接套用
+
+${renderList(abstraction.antiPatterns ?? [], '如果只是文件名相似，但当前目标、阶段或验证方式不同，不要直接套用。')}
+
 ## 可复用模式
 
 ${renderList(source.rootCauseCandidates.map((candidateItem) => candidateItem.title), '先按本轮诊断线索复走一次，再补最小必要证据。')}
@@ -1000,10 +1146,11 @@ function buildKnowledgeCandidateMeta({
   existingCandidate,
   abstraction,
 }) {
+  const existingStatus = normalizeCandidateStatus(existingCandidate?.status);
   return {
     version: 1,
     candidateId,
-    status: existingCandidate?.status === 'promoted' ? 'promoted' : 'pending-review',
+    status: isReviewedKnowledgeCandidateStatus(existingStatus) ? existingStatus : 'pending-review',
     createdAt: existingCandidate?.createdAt ?? timestamp(),
     updatedAt: timestamp(),
     sourceKind: source.kind,
@@ -1025,6 +1172,140 @@ function buildKnowledgeCandidateMeta({
   };
 }
 
+function cleanUserFacingExperienceText(value, fallback = null, max = 160) {
+  let text = String(value ?? '').replace(/\s+/g, ' ').trim();
+  if (!text) {
+    return fallback;
+  }
+  const replacements = [
+    [/\bknowledge candidate\b/gi, '候选经验'],
+    [/\bdraft skill\b/gi, '项目经验'],
+    [/\bskill\b/gi, '经验'],
+    [/\bpromote\b/gi, '保留'],
+    [/\breject\b/gi, '暂不保留'],
+    [/\barchive\b/gi, '先归档'],
+    [/\bhook\b/gi, '收尾流程'],
+    [/\bharness\b/gi, '项目流程'],
+    [/\bturn-state\b/gi, '本轮记录'],
+    [/\brun-state\b/gi, '当前状态'],
+    [/\bOpenPrd\b/gi, '当前流程'],
+    [/\.openprd\/[^\s，。；]+/g, ''],
+    [/[A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+/g, ''],
+  ];
+  for (const [pattern, replacement] of replacements) {
+    text = text.replace(pattern, replacement);
+  }
+  text = text
+    .replace(/[()]/g, '')
+    .replace(/[;；]+/g, '，')
+    .replace(/\s+,/g, '，')
+    .replace(/,+/g, '，')
+    .replace(/\s+/g, ' ')
+    .replace(/^[，,。\s]+|[，,。\s]+$/g, '')
+    .trim();
+  if (!text) {
+    return fallback;
+  }
+  return trimPreview(text, max) ?? fallback;
+}
+
+function observedSituationFromSource({ source, reviewSignals, touchedFiles }) {
+  const direct = [
+    source.symptoms[0],
+    reviewSignals.find((signal) => signal.summary)?.summary,
+    source.abstractPattern,
+    source.title,
+  ]
+    .map((item) => cleanUserFacingExperienceText(item))
+    .find(Boolean);
+  if (direct) {
+    return direct;
+  }
+  if (touchedFiles.length > 0) {
+    return `这次任务在 ${touchedFiles.slice(0, 3).join('、')} 这些位置形成了一套后续可能会重复用到的处理方式。`;
+  }
+  return '这次任务里已经形成了一种以后可能重复出现的处理方式。';
+}
+
+function plannedExperienceFromContext({ source, categories, touchedFiles }) {
+  const touchesDocs = touchedFiles.some((file) => String(file).startsWith('docs/basic/'));
+  const touchesTests = touchedFiles.some((file) => /^(test|tests)\//.test(String(file)));
+  if (categories.includes('agent-misjudgment')) {
+    return '以后做类似任务收尾时，我会先把本次情况、准备保留的经验和适用场景整理清楚，再用人话确认是否保留为当前项目经验。';
+  }
+  if (categories.includes('hidden-debug-knowledge')) {
+    return '以后再遇到类似问题时，我会优先复用这次已经验证过的判断依据、排查顺序和收尾检查方式，而不是从零开始重新摸索。';
+  }
+  if (touchesDocs && touchesTests) {
+    return '以后再遇到类似任务时，我会把处理方式、相关说明和验证方式一起整理成可复用经验，减少重复补充。';
+  }
+  if (touchesTests) {
+    return '以后再遇到类似任务时，我会连同这次已经跑通的验证方式一起复用，避免只记住改法、忘记检查方式。';
+  }
+  const prevention = cleanUserFacingExperienceText(source.prevention[0]);
+  if (prevention) {
+    return prevention;
+  }
+  return '以后再遇到类似任务时，我会把这次已经验证过的处理顺序和注意事项保留下来，作为当前项目的默认经验。';
+}
+
+function futureHandlingFromContext({ categories, touchedFiles }) {
+  const touchesDocs = touchedFiles.some((file) => String(file).startsWith('docs/basic/'));
+  if (categories.includes('agent-misjudgment')) {
+    return '以后如果再遇到类似任务，我会优先按这套说法和处理顺序来收尾，减少重复解释和重复判断。';
+  }
+  if (touchesDocs) {
+    return '以后如果再遇到类似任务，我会优先把处理方式和相关说明一起整理，减少来回补充。';
+  }
+  return '以后如果再遇到类似任务，我会优先按这套经验来处理，减少重复解释和重复判断。';
+}
+
+function knowledgeReviewStateNote(status) {
+  const normalized = normalizeCandidateStatus(status);
+  if (normalized === 'rejected') {
+    return '这条经验之前已经标记为暂不保留，本轮不会再次向用户追问。';
+  }
+  if (normalized === 'archived') {
+    return '这条经验之前已经先归档，本轮不会再次向用户追问。';
+  }
+  if (normalized === 'promoted' || normalized === 'merged') {
+    return '这条经验已经保留为当前项目经验，本轮不需要再次确认。';
+  }
+  return null;
+}
+
+function buildKnowledgeUserFacingExperience({ candidate, source, touchedFiles, reviewSignals, categories }) {
+  const observedSituation = observedSituationFromSource({ source, reviewSignals, touchedFiles });
+  const plannedExperience = plannedExperienceFromContext({ source, categories, touchedFiles });
+  const futureHandling = futureHandlingFromContext({ categories, touchedFiles });
+  const scopeNote = '这条经验只会保留在当前项目里。';
+  const reviewStateNote = knowledgeReviewStateNote(candidate.status);
+  const shouldAskUser = normalizeCandidateStatus(candidate.status) === 'pending-review';
+  const question = shouldAskUser ? '要我把它一起保留下来吗？' : null;
+  const messageLines = [
+    '这次我观察到一个以后可能重复出现的情况：',
+    observedSituation,
+    '',
+    '我计划保留一条项目经验：',
+    plannedExperience,
+    '',
+    futureHandling,
+    scopeNote,
+    question ?? reviewStateNote,
+  ].filter(Boolean);
+  return {
+    observedSituation,
+    plannedExperience,
+    futureHandling,
+    scopeNote,
+    question,
+    reviewStateNote,
+    shouldAskUser,
+    projectOnly: true,
+    message: messageLines.join('\n'),
+  };
+}
+
 export async function recordKnowledgeReviewSignal(projectRoot, signal = {}) {
   const statePath = knowledgePath(projectRoot, OPENPRD_HARNESS_TURN_STATE);
   const normalized = normalizeReviewSignal(projectRoot, signal);
@@ -1157,7 +1438,7 @@ export async function reviewKnowledgeWorkspace(projectRoot, options = {}) {
     ? (rawCandidateRef.startsWith('candidate-') ? rawCandidateRef : `candidate-${slugify(rawCandidateRef, 'knowledge')}`)
     : `candidate-${slugify(source.sourceId ?? title, 'knowledge')}`;
   const promotedSource = { ...source, sourceId: candidateId };
-  const names = deriveKnowledgeNames(promotedSource);
+  const names = deriveKnowledgeNames(promotedSource, { stablePattern: false });
   const candidateDir = knowledgePath(projectRoot, cjoin(KNOWLEDGE_CANDIDATES_DIR, candidateId));
   const candidatePath = path.join(candidateDir, 'candidate.json');
   const diagnosticReportPath = path.join(candidateDir, 'diagnostic-report.json');
@@ -1202,6 +1483,13 @@ export async function reviewKnowledgeWorkspace(projectRoot, options = {}) {
     ...draftCandidate,
     abstraction,
   };
+  const userFacingExperience = buildKnowledgeUserFacingExperience({
+    candidate,
+    source,
+    touchedFiles: substantiveTouchedFiles,
+    reviewSignals,
+    categories,
+  });
   await writeJson(candidatePath, candidate);
   await writeJson(diagnosticReportPath, buildCandidateDiagnosticReport({
     candidateId,
@@ -1245,6 +1533,17 @@ export async function reviewKnowledgeWorkspace(projectRoot, options = {}) {
       status: candidate.status,
     }),
   });
+  if (turnStateSource && await exists(knowledgePath(projectRoot, turnStateSource))) {
+    const turnState = await readJson(knowledgePath(projectRoot, turnStateSource)).catch(() => null);
+    const currentTurnState = readJsonObject(turnState);
+    if (currentTurnState) {
+      await writeJson(knowledgePath(projectRoot, turnStateSource), {
+        ...currentTurnState,
+        knowledgeCandidateId: candidateId,
+        updatedAt: timestamp(),
+      }).catch(() => null);
+    }
+  }
 
   return {
     ok: true,
@@ -1257,7 +1556,9 @@ export async function reviewKnowledgeWorkspace(projectRoot, options = {}) {
     skillName: names.skillName,
     categories,
     reasons,
+    status: candidate.status,
     summary: reviewSummary,
+    userFacingExperience,
     suggestedLearnCommand: candidate.suggestedLearnCommand,
     files: {
       candidate: candidatePath,
@@ -1401,6 +1702,54 @@ function buildKnowledgeMatchQuery(options = {}) {
   };
 }
 
+function trimPromptList(items = [], limit = 3, max = 96) {
+  return uniq(
+    normalizeStringList(items)
+      .map((item) => trimPreview(item, max))
+      .filter(Boolean),
+  ).slice(0, limit);
+}
+
+function buildKnowledgeMatchCandidateCard(skill) {
+  return {
+    skillName: skill.skillName,
+    useWhen: firstString(skill.useWhen, skill.description),
+    applicability: trimPromptList(skill.applicability, 2, 96),
+    reviewFirst: trimPromptList(skill.reviewFirst, 3, 96),
+    antiPatterns: trimPromptList(skill.antiPatterns, 2, 96),
+    touchedFiles: trimPromptList(skill.touchedFiles, 4, 80),
+    matchedOn: trimPromptList(skill.matchedOn, 3, 96),
+    matchSummary: trimPreview(skill.matchSummary, 160),
+  };
+}
+
+function buildKnowledgeMandatoryCheck(matches, options = {}) {
+  if (!Array.isArray(matches) || matches.length === 0) {
+    return null;
+  }
+  const focusSignals = trimPromptList([
+    options.recommendationTitle ? `当前目标: ${options.recommendationTitle}` : null,
+    options.recommendationReason ? `目标原因: ${options.recommendationReason}` : null,
+    options.activeChange ? `当前变更: ${options.activeChange}` : null,
+    options.nextTaskTitle ? `下一任务: ${options.nextTaskTitle}` : null,
+    ...normalizeStringList(options.relatedFiles).map((file) => `相关文件: ${file}`),
+  ], 6, 120);
+  return {
+    required: true,
+    mode: 'prompt-rerank',
+    title: '先做项目经验检查，再决定是否复用',
+    summary: '这些项目经验只是候选，不代表都要复用；先按当前目标、阶段和验证方式判断。',
+    instructions: [
+      '先判断当前任务真正要解决什么，再看候选经验。',
+      '只有当适用时机、范围或证据入口与当前任务一致时，才复用对应经验。',
+      '如果只是文件名、路径或个别词重合，但任务目标、阶段或验证方式不一致，就不要套用。',
+      '最多选择 0 到 3 条最相关经验；如果都不贴切，可以明确本轮不复用项目经验。',
+    ],
+    focusSignals,
+    candidates: matches.map((skill) => buildKnowledgeMatchCandidateCard(skill)).slice(0, Math.max(1, Number(options.limit ?? 3))),
+  };
+}
+
 function scoreKnowledgeSkillMatch(skill, query) {
   const fileHints = uniq([
     ...skill.touchedFiles,
@@ -1410,10 +1759,13 @@ function scoreKnowledgeSkillMatch(skill, query) {
   ]);
   const fields = [
     skill.skillName,
-    skill.description,
+    skill.useWhen,
+    ...(!isGenericKnowledgeDescription(skill.description) ? [skill.description] : []),
     skill.summary,
     ...skill.categories,
     ...skill.triggerHints,
+    ...skill.applicability,
+    ...skill.reviewFirst,
     ...skill.rootCauseLabels,
     ...fileHints,
   ];
@@ -1458,14 +1810,18 @@ export async function resolveKnowledgeSkillMatches(projectRoot, options = {}) {
     .filter(Boolean)
     .sort((left, right) => right.score - left.score || left.skillName.localeCompare(right.skillName))
     .slice(0, Math.max(1, Number(options.limit ?? 3)));
+  const mandatoryCheck = buildKnowledgeMandatoryCheck(matches, options);
   return {
     ok: true,
     action: 'knowledge-match',
     projectRoot,
     query: trimPreview(query.text, 320),
     matched: matches,
+    mandatoryCheck,
     summary: {
       matched: matches.length,
+      reviewRequired: Boolean(mandatoryCheck?.required),
+      reviewMode: mandatoryCheck?.mode ?? null,
     },
   };
 }

package/src/learning-review.js

@@ -161,10 +161,10 @@ const STYLE_PROMPT_PACKS = {
         titlePatterns: [
           '《{topic}》修行札记',
           '《{topic}》证道小卷',
-          '《{topic}》归藏篇',
+          '《{topic}》藏录篇',
         ],
         outlineArc: ['筑基立卷', '观脉识图', '破雾辨源', '传功成谱', '归元再启'],
-        imageryBank: ['灵根', '经脉', '法门', '玉简', '破境', '归藏', '心法', '炉火'],
+        imageryBank: ['灵根', '经脉', '法门', '玉简', '破境', '藏录', '心法', '炉火'],
         sentenceRhythm: '长短句交错；每段先给意象，再落回事实、路径或证据。',
         taboo: [
           '不要把证据不存在的内容写成神迹或事实。',
@@ -179,7 +179,7 @@ const STYLE_PROMPT_PACKS = {
         titlePrompt: [
           '输入: topic、genre、substyle、agent-context、evidence summary。',
           '输出: 一个像书名的标题和一个短副题。',
-          '要求: 标题可带“札记/小卷/归藏/心法”等书籍意象，但必须保留 topic 的核心名词。',
+          '要求: 标题可带“札记/小卷/藏录/心法”等书籍意象，但必须保留 topic 的核心名词。',
         ].join('\n'),
         outlinePrompt: [
           '输入: 章节目标、证据类别、读者学习路径。',