@openprd/cli 0.1.11 → 0.1.18

package/src/quality.js

@@ -108,7 +108,7 @@ const EVIDENCE_TOKENS = {
   'test-strategy': ['test-layer', 'test-size', 'test-scope', 'evidence-plan', 'testing pyramid', '测试策略', '测试分流', '单元测试', '集成测试', '端到端'],
   smoke: ['smoke', 'e2e', 'playwright', 'cypress', 'main flow', 'happy path', '冒烟', '主流程'],
   'feature-coverage': ['feature coverage', 'acceptance', 'tasks done', 'openprd tasks', '验收', '功能覆盖', '任务完成'],
-  'visual-review': ['visual-compare', 'visual-before-after', 'visual-focus-board', 'visual-parallel-board', 'reference-actual', 'before-after', 'focus-board', 'parallel-board', '效果图', '实现截图', '修改前', '修改后', '视觉对比', '局部焦点证据板', '并行实验证据板'],
+  'visual-review': ['visual-compare', 'visual-before-after', 'visual-focus-board', 'visual-parallel-board', 'visual-verification-board', 'visual-alignment-board', 'visual-centering-board', 'reference-actual', 'before-after', 'focus-board', 'parallel-board', 'verification-board', 'alignment-board', 'centering-board', 'center-board', '效果图', '实现截图', '修改前', '修改后', '视觉对比', '局部焦点证据板', '并行实验证据板', '截图实测证据板', '对齐辅助线证据板', '内部居中证据板', '内容槽位', '内部槽位', '视觉重心', '主体外接框', '画布中心', '偏心'],
   'normal-performance': ['performance', 'perf', 'benchmark', 'latency', 'p95', 'lighthouse', 'k6', '性能', '耗时'],
   'extreme-performance': ['extreme', 'stress', 'load test', 'large-data', 'pressure', 'k6', '压力', '极端', '大数据'],
   knowledge: ['quality learn', 'incident', 'pattern', 'skill', '复盘', '经验', '沉淀'],
@@ -253,6 +253,10 @@ function defaultQualityConfig() {
       ledgerPath: OPENPRD_GROWTH_LEDGER,
       completionCheckpointRequired: true,
     },
+    reports: {
+      retentionMaxReports: 60,
+      retentionEnabled: true,
+    },
   };
 }
 
@@ -301,6 +305,10 @@ function normalizeQualityConfig(config = {}) {
       ...defaults.growth,
       ...(config.growth ?? {}),
     },
+    reports: {
+      ...defaults.reports,
+      ...(config.reports ?? {}),
+    },
   };
 }
 
@@ -442,8 +450,7 @@ async function readActiveChangeContext(projectRoot, activeChange) {
     return { activeChange: null, files: [], text: '' };
   }
   const roots = [
-    cjoin('openprd', 'changes', activeChange),
-    cjoin('openspec', 'changes', activeChange),
+    cjoin('.openprd', 'changes', activeChange),
   ];
   const files = [];
   async function walk(root, dir) {
@@ -904,7 +911,9 @@ async function readActiveTasks(projectRoot) {
     return { activeChange: null, total: 0, done: 0, pending: 0, blocked: 0, tasks: [] };
   }
   const taskFiles = [];
-  for (const root of [cjoin('openprd', 'changes', activeChange), cjoin('openspec', 'changes', activeChange)]) {
+  for (const root of [
+    cjoin('.openprd', 'changes', activeChange),
+  ]) {
     const dir = cjoin(projectRoot, root);
     const entries = await fs.readdir(dir).catch(() => []);
     for (const entry of entries) {
@@ -1283,7 +1292,35 @@ async function buildQualityReport(projectRoot, config, options = {}) {
   };
 }
 
-async function writeReport(projectRoot, report) {
+export async function pruneQualityReports(projectRoot, retainedReports, config) {
+  const retention = config?.reports ?? {};
+  if (retention.retentionEnabled === false) {
+    return { pruned: 0 };
+  }
+  const maxReports = Number.isInteger(retention.retentionMaxReports) && retention.retentionMaxReports > 0
+    ? retention.retentionMaxReports
+    : 60;
+  const reportsDir = qualityPath(projectRoot, QUALITY_REPORTS_DIR);
+  const entries = await fs.readdir(reportsDir).catch(() => []);
+  const keepBases = new Set(
+    retainedReports.slice(0, maxReports).map((item) => String(item.reportId ?? '').replace(/[^a-zA-Z0-9._-]/g, '_')),
+  );
+  let pruned = 0;
+  for (const name of entries) {
+    const match = name.match(/^(eval-[a-zA-Z0-9._-]+)\.(json|html)$/);
+    if (!match) {
+      continue;
+    }
+    if (keepBases.has(match[1])) {
+      continue;
+    }
+    await fs.rm(cjoin(reportsDir, name), { force: true }).catch(() => {});
+    pruned += 1;
+  }
+  return { pruned };
+}
+
+async function writeReport(projectRoot, report, config = null) {
   await ensureQualityDirs(projectRoot);
   const reportBase = report.id.replace(/[^a-zA-Z0-9._-]/g, '_');
   const jsonPath = qualityPath(projectRoot, cjoin(QUALITY_REPORTS_DIR, `${reportBase}.json`));
@@ -1304,7 +1341,8 @@ async function writeReport(projectRoot, report) {
     ...(Array.isArray(index.reports) ? index.reports.filter((item) => item.reportId !== report.id) : []),
   ].slice(0, 100);
   await writeJson(indexPath, { version: 1, updatedAt: timestamp(), reports });
-  return { jsonPath, htmlPath, indexPath };
+  const retention = await pruneQualityReports(projectRoot, reports, config ?? normalizeQualityConfig());
+  return { jsonPath, htmlPath, indexPath, prunedReports: retention.pruned };
 }
 
 export async function initQualityWorkspace(projectRoot, options = {}) {
@@ -1349,7 +1387,7 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
   await ensureQualityDirs(projectRoot);
   const initialReport = await buildQualityReport(projectRoot, config);
   let report = initialReport;
-  let paths = await writeReport(projectRoot, report);
+  let paths = await writeReport(projectRoot, report, config);
   const knowledgeSignal = {
     kind: 'quality-verify',
     ok: report.readiness.productionReady,
@@ -1408,7 +1446,7 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
       reason: 'reusable-knowledge-artifact-already-exists',
     };
   report = await buildQualityReport(projectRoot, config, { reportId: initialReport.id });
-  paths = await writeReport(projectRoot, report);
+  paths = await writeReport(projectRoot, report, config);
   const strict = options.strict === true;
   const blocking = (strict || config.enforcement === 'blocking') && !report.readiness.productionReady;
   const featureCoverageOnly = report.readiness.failingGates.length === 0

package/src/review-presentation.js

@@ -48,6 +48,32 @@ export const REVIEW_PRESENTATION_TEMPLATE = {
       USER_CHANGE_SUMMARY_GUIDE.panelExamples.risk,
     ],
   },
+  designDirections: {
+    note: '可选；只有需求涉及界面/页面/交互时提供。先用 imagegen 生成 3 个差异足够大的交互稿，把图片放到 .openprd/design/active/ 后写入路径；不涉及界面时删除本字段。',
+    directions: [
+      {
+        id: 'direction-1',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-1.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+      {
+        id: 'direction-2',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-2.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+      {
+        id: 'direction-3',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-3.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+    ],
+  },
 };
 
 export function buildReviewPresentationTemplatePayload() {
@@ -182,6 +208,39 @@ function stableStringify(value) {
   return JSON.stringify(value);
 }
 
+const ACTIVE_ARTIFACT_RETAIN_VERSIONS = 12;
+
+export async function archiveStaleActiveArtifacts(projectRoot, options = {}) {
+  const retain = Number.isInteger(options.retain) && options.retain > 0
+    ? options.retain
+    : ACTIVE_ARTIFACT_RETAIN_VERSIONS;
+  const activeDir = path.join(projectRoot, '.openprd', 'artifacts', 'active');
+  const archiveDir = path.join(projectRoot, '.openprd', 'artifacts', 'archive');
+  const entries = await fs.readdir(activeDir, { withFileTypes: true }).catch(() => []);
+  const versioned = entries
+    .filter((entry) => entry.isDirectory() && /^v\d{4}-/.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  const stale = versioned.slice(0, Math.max(0, versioned.length - retain));
+  if (stale.length === 0) {
+    return { archived: [] };
+  }
+  await fs.mkdir(archiveDir, { recursive: true });
+  const archived = [];
+  for (const name of stale) {
+    const from = path.join(activeDir, name);
+    const to = path.join(archiveDir, name);
+    try {
+      await fs.rm(to, { recursive: true, force: true });
+      await fs.rename(from, to);
+      archived.push(name);
+    } catch {
+      // 归档失败不阻断评审生成
+    }
+  }
+  return { archived };
+}
+
 async function renderValidatedReviewPresentation(projectRoot, snapshot) {
   const workspaceRoot = path.join(projectRoot, '.openprd');
   const canonicalReview = canonicalReviewPath({ workspaceRoot }, snapshot.versionId);
@@ -191,6 +250,7 @@ async function renderValidatedReviewPresentation(projectRoot, snapshot) {
     snapshot,
     projectRelease: buildReleaseLedgerSummary(releaseLedger.ledger),
   }));
+  await archiveStaleActiveArtifacts(projectRoot).catch(() => null);
 
   const versionIndexPath = path.join(workspaceRoot, 'state', 'version-index.json');
   const versionIndex = await readJson(versionIndexPath);

package/src/run-harness.js

@@ -19,6 +19,9 @@ const OPENPRD_HARNESS_RUN_STATE = cjoin(OPENPRD_HARNESS_DIR, 'run-state.json');
 const OPENPRD_HARNESS_ITERATIONS = cjoin(OPENPRD_HARNESS_DIR, 'iterations.jsonl');
 const OPENPRD_HARNESS_LEARNINGS = cjoin(OPENPRD_HARNESS_DIR, 'learnings.md');
 const OPENPRD_HARNESS_LOOP_FEATURE_LIST = cjoin(OPENPRD_HARNESS_DIR, 'feature-list.json');
+const OPENPRD_HARNESS_INSTALL_MANIFEST = cjoin(OPENPRD_HARNESS_DIR, 'install-manifest.json');
+const OPENPRD_HARNESS_HOOK_STATE = cjoin(OPENPRD_HARNESS_DIR, 'hook-state.json');
+const OPENPRD_HARNESS_RUNTIME_ENVIRONMENT = cjoin(OPENPRD_HARNESS_DIR, 'runtime-environment.json');
 const OPENPRD_HARNESS_REQUIREMENT_GATE = cjoin(OPENPRD_HARNESS_DIR, 'requirement-gate.json');
 const OPENPRD_HARNESS_REQUIREMENT_GATES_DIR = cjoin(OPENPRD_HARNESS_DIR, 'requirement-gates');
 const OPENPRD_HARNESS_SESSION_BINDINGS_DIR = cjoin(OPENPRD_HARNESS_DIR, 'session-bindings');
@@ -82,6 +85,34 @@ async function ensureRunHarness(projectRoot) {
   }
 }
 
+async function readRuntimeEnvironmentContext(projectRoot) {
+  const [runtimeEnvironment, installManifest, hookState] = await Promise.all([
+    readJson(harnessFile(projectRoot, OPENPRD_HARNESS_RUNTIME_ENVIRONMENT)).catch(() => null),
+    readJson(harnessFile(projectRoot, OPENPRD_HARNESS_INSTALL_MANIFEST)).catch(() => null),
+    readJson(harnessFile(projectRoot, OPENPRD_HARNESS_HOOK_STATE)).catch(() => null),
+  ]);
+  const active = runtimeEnvironment?.active
+    ?? hookState?.runtimeEnvironment
+    ?? {
+      activeClient: 'unknown',
+      surface: 'unknown',
+      confidence: 0,
+      sessionId: null,
+      evidence: [],
+      observedCapabilities: [],
+    };
+  return {
+    active,
+    runtimeDetection: installManifest?.runtimeDetection ?? runtimeEnvironment?.runtimeDetection ?? null,
+    platformCapabilityPacks: installManifest?.platformCapabilityPacks ?? runtimeEnvironment?.platformCapabilityPacks ?? [],
+    files: {
+      runtimeEnvironment: OPENPRD_HARNESS_RUNTIME_ENVIRONMENT,
+      installManifest: OPENPRD_HARNESS_INSTALL_MANIFEST,
+      hookState: OPENPRD_HARNESS_HOOK_STATE,
+    },
+  };
+}
+
 async function readRunState(projectRoot) {
   await ensureRunHarness(projectRoot);
   return readJson(harnessFile(projectRoot, OPENPRD_HARNESS_RUN_STATE)).catch(() => ({
@@ -225,7 +256,7 @@ function executionGate() {
     confirmationChecklistRequired: true,
     allowedIntents: ['开发', '实现', '修复', '继续任务', '落地执行', '深度调研', '深度对标', '复刻落地', '提交'],
     readOnlyIntents: ['看看', '规划', '梳理', '分析', '评估', '预计动哪些文件', '怎么改', '代码审查'],
-    rule: '只有当用户当前明确要求实现、继续、深度调研、对标或提交时，才运行 executionCommand。单纯的“请帮我实现/继续实现”只表示有执行意图，不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review；只有用户明确表示“不需要进行任何确认”时，才允许静默走完整 requirement write path，并对当前精确匹配的稳定 review artifact 记录确认。若还需要向用户索取执行授权，先展示 executionConfirmationChecklist，再请求明确确认；规划、分析、文件影响范围和审查类请求保持只读，并基于证据回答。',
+    rule: '只有当用户当前明确要求实现、继续、深度调研、对标或提交时，才运行 executionCommand。单纯的“请帮我实现/继续实现”只表示有执行意图，不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review；只有用户明确表示“不需要进行任何确认”时，才允许静默走完整 requirement write path，并对当前精确匹配的稳定 review artifact 记录确认。即使用户授权实现，也不等于授权云端热修复、生产远端写入、业务兜底、写死逻辑或缓存补行；这些动作必须由当前用户明确批准，并说明如何同步回本地源码、配置或迁移。若还需要向用户索取执行授权，先展示 executionConfirmationChecklist，再请求明确确认；规划、分析、文件影响范围和审查类请求保持只读，并基于证据回答。',
   };
 }
 
@@ -251,6 +282,7 @@ function buildExecutionConfirmationChecklist(recommendation) {
     outOfScope: [
       '不会默认处理这次范围以外的历史问题。',
       '不会默认顺带做提交、发布或额外的全局调整。',
+      '不会默认做云端热修复、生产远端写入、业务兜底、写死逻辑或缓存补行。',
       '如果真的需要扩大范围，我会先单独说明。',
     ].filter(Boolean),
     verification: [
@@ -261,6 +293,7 @@ function buildExecutionConfirmationChecklist(recommendation) {
     risks: [
       '这一步会正式写入当前工作区。',
       '如果牵出和本次无关的历史遗留问题，我会单列说明，不把它混成本次失败。',
+      '如果确实需要临时兜底或线上热修复，我会先单独说明影响、回滚和本地同步计划，等你明确批准。',
       parallelPlan?.eligible ? '如果多人同时推进，我会避免范围互相踩踏。' : null,
     ],
     confirmationPrompt: '如果你希望我现在就按这次范围继续，我就直接往下做。',
@@ -1816,6 +1849,7 @@ async function buildRunContext(projectRoot, dependencies, options = {}) {
   await ensureRunHarness(projectRoot);
   const runState = await readRunState(projectRoot);
   const currentTurn = await readJson(harnessFile(projectRoot, OPENPRD_HARNESS_TURN_STATE)).catch(() => null);
+  const runtimeEnvironment = await readRuntimeEnvironmentContext(projectRoot);
   const currentTurnPrompt = String(currentTurn?.prompt ?? '').trim();
   const fallbackPrompt = !options.hookInject
     ? (inferPromptDrivenLightweightRecommendation(currentTurnPrompt) ? currentTurnPrompt : null)
@@ -1942,8 +1976,8 @@ async function buildRunContext(projectRoot, dependencies, options = {}) {
     activeChange,
     nextTaskTitle: nextTask?.title,
     relatedFiles: [
-      focusedChangeId ? `openprd/changes/${focusedChangeId}/tasks.md` : null,
-      activeChange ? `openprd/changes/${activeChange}` : null,
+      focusedChangeId ? `.openprd/changes/${focusedChangeId}/tasks.md` : null,
+      activeChange ? `.openprd/changes/${activeChange}` : null,
     ].filter(Boolean),
     limit: options.hookInject ? 4 : 3,
   }).catch(() => ({ matched: [], summary: { matched: 0 } }));
@@ -2035,6 +2069,7 @@ async function buildRunContext(projectRoot, dependencies, options = {}) {
       : null,
     lane,
     recommendation: effectiveRecommendation,
+    runtimeEnvironment,
     knowledgeSkills: {
       matched: renderedKnowledgeSkills,
       mandatoryCheck: knowledgeSkillMatches.mandatoryCheck ?? null,
@@ -2050,6 +2085,7 @@ async function buildRunContext(projectRoot, dependencies, options = {}) {
       runState: OPENPRD_HARNESS_RUN_STATE,
       iterations: OPENPRD_HARNESS_ITERATIONS,
       learnings: OPENPRD_HARNESS_LEARNINGS,
+      runtimeEnvironment: OPENPRD_HARNESS_RUNTIME_ENVIRONMENT,
     },
   };
 
@@ -2065,6 +2101,7 @@ async function buildRunContext(projectRoot, dependencies, options = {}) {
 async function recordRunHook(projectRoot, options = {}) {
   await ensureRunHarness(projectRoot);
   const state = await readRunState(projectRoot);
+  const runtimeEnvironment = await readRuntimeEnvironmentContext(projectRoot);
   const currentIteration = Number(state.currentIteration ?? 0) + 1;
   const event = {
     version: 1,
@@ -2075,6 +2112,7 @@ async function recordRunHook(projectRoot, options = {}) {
     risk: options.risk ?? 'unknown',
     outcome: options.outcome ?? 'unknown',
     preview: options.preview ?? null,
+    runtimeEnvironment: runtimeEnvironment.active,
   };
   await appendJsonl(harnessFile(projectRoot, OPENPRD_HARNESS_ITERATIONS), event);
   await writeRunState(projectRoot, {

package/src/session-evidence.js

@@ -0,0 +1,363 @@
+/*
+ * 核心功能
+ * 从 Codex 原始会话事件中抽取可审查证据，并隔离系统提示、AGENTS 和工具 schema 噪声。
+ *
+ * 输入
+ * 接收 JSONL 事件对象、消息对象或文本片段。
+ *
+ * 输出
+ * 输出带 sourceKind 的 evidence records，以及供 knowledge matching 使用的清理后文本。
+ *
+ * 定位
+ * 位于会话证据层，服务 daily review、knowledge review 和项目经验召回，不直接读写工作区。
+ *
+ * 依赖
+ * 仅依赖标准 JavaScript，不依赖 CLI、文件系统或 OpenPrd workspace 状态。
+ *
+ * 维护规则
+ * 这里负责证据卫生，不负责判断需求类型；新增来源时先补 sourceKind 和污染样例测试。
+ */
+
+const CONTEXT_ONLY_PATTERNS = [
+  /\bAGENTS\.md instructions\b/i,
+  /<INSTRUCTIONS>/i,
+  /<\/INSTRUCTIONS>/i,
+  /<environment_context>/i,
+  /# Tools\b/i,
+  /## Skills\b/i,
+  /### Available skills\b/i,
+  /\bnamespace\s+\w+\s*\{/i,
+  /\btool schema\b/i,
+  /\bYou are Codex\b/i,
+  /\bOpenPrd Harness\b/i,
+  /\bproject-doc\b/i,
+];
+
+const CONTEXT_ROLE_SET = new Set(['system', 'developer']);
+
+const GENERIC_FRAMEWORK_TERMS = new Set([
+  'agent',
+  'agents',
+  'agentruntime',
+  'codex',
+  'context',
+  'developer',
+  'hook',
+  'hooks',
+  'harness',
+  'instruction',
+  'instructions',
+  'openprd',
+  'schema',
+  'skill',
+  'skills',
+  'system',
+  'tool',
+  'tools',
+  'workflow',
+  'workflows',
+  '项目级',
+  '项目经验',
+  '沉淀',
+]);
+
+function normalizeWhitespace(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function trimEvidenceText(value, max = 1200) {
+  const text = normalizeWhitespace(value);
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function normalizeEventType(event = {}) {
+  return String(
+    event.type
+      ?? event.event
+      ?? event.kind
+      ?? event.eventType
+      ?? event.name
+      ?? event.item?.type
+      ?? event.event_msg?.type
+      ?? '',
+  ).trim();
+}
+
+function normalizeRole(event = {}) {
+  return String(
+    event.role
+      ?? event.message?.role
+      ?? event.item?.role
+      ?? event.event_msg?.role
+      ?? '',
+  ).trim().toLowerCase();
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+function extractTextFromContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => firstString(part?.text, part?.content, part?.input, part?.output))
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (content && typeof content === 'object') {
+    return firstString(content.text, content.content, content.input, content.output) ?? '';
+  }
+  return '';
+}
+
+function extractEventText(event = {}) {
+  if (typeof event === 'string') return event;
+  const eventMsg = event.event_msg ?? {};
+  const item = event.item ?? {};
+  const message = event.message ?? {};
+  return firstString(
+    event.text,
+    event.content,
+    event.output,
+    event.final_answer,
+    event.summary,
+    event.prompt,
+    event.user_message,
+    event.agent_message,
+    eventMsg.user_message,
+    eventMsg.agent_message,
+    eventMsg.final_answer,
+    eventMsg.summary,
+    eventMsg.message,
+    item.final_answer,
+    item.summary,
+    item.text,
+    item.output,
+    message.text,
+    extractTextFromContent(message.content),
+    extractTextFromContent(item.content),
+  ) ?? '';
+}
+
+function looksLikeContextOnly(text, event = {}) {
+  const role = normalizeRole(event);
+  if (CONTEXT_ROLE_SET.has(role)) return true;
+  return CONTEXT_ONLY_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function classifyEvent(event = {}, text = '') {
+  const role = normalizeRole(event);
+  const type = normalizeEventType(event).toLowerCase();
+  const eventMsg = event.event_msg ?? {};
+  const item = event.item ?? {};
+  if (looksLikeContextOnly(text, event)) {
+    return { sourceKind: 'context-only', reason: 'system-context' };
+  }
+  if (role === 'user' || eventMsg.user_message) {
+    return { sourceKind: 'user-direct', reason: 'user-message' };
+  }
+  if (
+    role === 'assistant'
+    || eventMsg.agent_message
+    || eventMsg.final_answer
+    || item.final_answer
+    || type.includes('final')
+  ) {
+    return { sourceKind: 'assistant-final', reason: 'assistant-message' };
+  }
+  if (
+    type.includes('task_complete')
+    || event.task_complete
+    || eventMsg.task_complete
+    || item.type === 'task_complete'
+  ) {
+    return { sourceKind: 'assistant-final', reason: 'task-complete' };
+  }
+  if (
+    type.includes('function_call')
+    || type.includes('tool')
+    || event.tool
+    || event.name
+    || item.name
+  ) {
+    return { sourceKind: 'tool-action', reason: 'tool-event' };
+  }
+  if (/\b(git status|npm test|node --test|openprd .*--verify|doctor)\b/i.test(text)) {
+    return { sourceKind: 'tool-action', reason: 'command-evidence' };
+  }
+  return { sourceKind: 'context-only', reason: 'unclassified' };
+}
+
+function normalizeEvidenceRecord(record = {}, index = 0) {
+  const text = trimEvidenceText(record.text);
+  if (!text) return null;
+  const sourceKind = String(record.sourceKind ?? 'context-only').trim() || 'context-only';
+  return {
+    sourceKind,
+    text,
+    reason: String(record.reason ?? '').trim() || null,
+    role: String(record.role ?? '').trim() || null,
+    eventType: String(record.eventType ?? '').trim() || null,
+    eventIndex: Number.isFinite(Number(record.eventIndex)) ? Number(record.eventIndex) : index,
+    confidence: Number.isFinite(Number(record.confidence)) ? Number(record.confidence) : (sourceKind === 'context-only' ? 0.2 : 0.8),
+  };
+}
+
+function extractSessionEvidenceRecords(events = [], options = {}) {
+  const maxRecords = Math.max(1, Number(options.maxRecords ?? 80));
+  return (Array.isArray(events) ? events : [events])
+    .map((event, index) => {
+      const text = extractEventText(event);
+      if (!normalizeWhitespace(text)) return null;
+      const classification = classifyEvent(event, text);
+      return normalizeEvidenceRecord({
+        ...classification,
+        text,
+        role: normalizeRole(event),
+        eventType: normalizeEventType(event),
+        eventIndex: index,
+      }, index);
+    })
+    .filter(Boolean)
+    .slice(0, maxRecords);
+}
+
+function normalizeSessionEvidenceRecords(records = []) {
+  return (Array.isArray(records) ? records : [records])
+    .map((record, index) => normalizeEvidenceRecord(record, index))
+    .filter(Boolean);
+}
+
+function cleanEvidenceRecords(records = [], options = {}) {
+  const includeContextOnly = options.includeContextOnly === true;
+  return normalizeSessionEvidenceRecords(records)
+    .filter((record) => includeContextOnly || record.sourceKind !== 'context-only');
+}
+
+function buildCleanEvidenceText(records = [], options = {}) {
+  const maxRecords = Math.max(1, Number(options.maxRecords ?? 24));
+  return cleanEvidenceRecords(records, options)
+    .slice(0, maxRecords)
+    .map((record) => `[${record.sourceKind}] ${record.text}`)
+    .join('\n');
+}
+
+function normalizeSearchText(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[`"'()[\]{}:;,!?]/g, ' ')
+    .replace(/[_/\\.-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function sanitizeEvidenceText(value) {
+  const text = String(value ?? '');
+  if (!text.trim()) return '';
+  const lines = text.split(/\r?\n/);
+  const kept = [];
+  let skipBlock = false;
+  for (const line of lines) {
+    const startsContextBlock = /<INSTRUCTIONS>|<environment_context>|# Tools\b|### Available skills\b/i.test(line);
+    if (startsContextBlock) {
+      skipBlock = true;
+      continue;
+    }
+    if (skipBlock && /<\/INSTRUCTIONS>|<\/environment_context>/i.test(line)) {
+      skipBlock = false;
+      continue;
+    }
+    if (skipBlock) continue;
+    if (CONTEXT_ONLY_PATTERNS.some((pattern) => pattern.test(line))) continue;
+    kept.push(line);
+  }
+  return normalizeWhitespace(kept.join('\n'));
+}
+
+function isGenericFrameworkTerm(token) {
+  const normalized = normalizeSearchText(token);
+  return !normalized || GENERIC_FRAMEWORK_TERMS.has(normalized);
+}
+
+function filterGenericFrameworkTokens(tokens = []) {
+  return [...new Set(tokens.filter((token) => !isGenericFrameworkTerm(token)))];
+}
+
+function buildSessionEvidenceReviewSource(options = {}) {
+  const records = cleanEvidenceRecords(options.records ?? []);
+  const title = firstString(options.title, records.find((record) => record.sourceKind === 'user-direct')?.text, '只读复盘证据候选');
+  const sourceId = firstString(options.sourceId, title, 'session-evidence-review');
+  const sourcePath = firstString(options.sourcePath, 'session-evidence');
+  const userRecords = records.filter((record) => record.sourceKind === 'user-direct');
+  const assistantRecords = records.filter((record) => record.sourceKind === 'assistant-final');
+  const toolRecords = records.filter((record) => record.sourceKind === 'tool-action');
+  const symptoms = [...userRecords, ...assistantRecords]
+    .map((record) => record.text)
+    .slice(0, 8);
+  const rootCauseCandidates = records
+    .filter((record) => ['assistant-final', 'tool-action', 'repo-state'].includes(record.sourceKind))
+    .slice(0, 6)
+    .map((record) => ({
+      title: record.text,
+      nextSteps: ['把这条证据和用户目标重新核对，只在确认可复用时推荐项目级沉淀。'],
+      sourceKind: record.sourceKind,
+    }));
+  return {
+    kind: 'session-evidence-review',
+    evidenceOnly: true,
+    sourceId,
+    sourcePath,
+    primaryPath: sourcePath,
+    sourcePaths: [sourcePath],
+    title,
+    status: 'needs-review',
+    symptoms,
+    attentionGates: [],
+    correlationFields: [],
+    extraContextFields: [],
+    missingCorrelationFields: [],
+    eventNames: [...new Set(records.map((record) => record.sourceKind))],
+    rootCauseCandidates,
+    evidenceSources: records.map((record) => ({
+      kind: record.sourceKind,
+      path: `${sourcePath}#${record.eventIndex}`,
+      reason: record.reason,
+    })),
+    queryExamples: [
+      '先只看 user-direct、assistant-final、tool-action 证据，不把 AGENTS 或系统提示当成用户诉求。',
+      '如果复盘证据跨多轮重复出现，再推荐用户把它保留为当前项目经验。',
+    ],
+    abstractPattern: '从只读复盘证据中先隔离系统上下文噪声，再把重复摩擦或可复用判断沉淀为项目级候选。',
+    triggers: records
+      .filter((record) => record.sourceKind !== 'context-only')
+      .map((record) => `${record.sourceKind}: ${record.text}`)
+      .slice(0, 8),
+    prevention: [
+      'raw session 先抽取 clean evidence，再进入候选判断。',
+      'AGENTS、system、developer、tool schema 和 skill list 只能作为 context-only 背景，不触发用户诉求或项目经验候选。',
+      '项目级沉淀先作为候选推荐给用户确认，不自动 promote。',
+    ],
+    verificationSteps: [
+      '确认每条证据都有 sourceKind。',
+      '确认候选推荐没有依赖 context-only 命中。',
+      '确认用户确认前只生成候选，不修改正式项目 skill。',
+    ],
+  };
+}
+
+export {
+  buildCleanEvidenceText,
+  buildSessionEvidenceReviewSource,
+  cleanEvidenceRecords,
+  extractSessionEvidenceRecords,
+  filterGenericFrameworkTokens,
+  isGenericFrameworkTerm,
+  normalizeSessionEvidenceRecords,
+  sanitizeEvidenceText,
+};