@openprd/cli 0.1.1 → 0.1.9

package/src/benchmark/constants.js

@@ -0,0 +1,107 @@
+/*
+ * 核心功能
+ * 定义 benchmark 子系统共享常量、目录路径和默认 registry 模板。
+ *
+ * 输入
+ * 接收项目根目录、路径片段和用于生成默认 sources/index 的当前时间。
+ *
+ * 输出
+ * 导出 benchmark 工作区路径、采纳阈值常量、slugify 和默认文件内容生成器。
+ *
+ * 定位
+ * 位于 benchmark 模块最底层，不处理业务判断，只提供稳定的共享基座。
+ *
+ * 依赖
+ * 依赖 fs-utils 的路径拼接和 time 的时间戳工具；被 source、storage、operations 复用。
+ *
+ * 维护规则
+ * 修改路径常量或默认模板时必须保持与已有 workspace 文件布局和 CLI 文案兼容。
+ */
+import { cjoin } from '../fs-utils.js';
+import { timestamp } from '../time.js';
+
+const BENCHMARK_DIR = cjoin('.openprd', 'benchmarks');
+const BENCHMARK_INBOX_DIR = cjoin(BENCHMARK_DIR, 'inbox');
+const BENCHMARK_EVIDENCE_DIR = cjoin(BENCHMARK_DIR, 'evidence');
+const BENCHMARK_SOURCES_FILE = cjoin(BENCHMARK_DIR, 'sources.yaml');
+const BENCHMARK_INDEX_FILE = cjoin(BENCHMARK_DIR, 'index.md');
+const DEFAULT_ADOPTION_THRESHOLD = 3;
+const DEFAULT_ADOPTION_WINDOW_DAYS = 7;
+const MAX_ADOPTION_EVIDENCE = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const OVERBROAD_TRIGGER_TOKENS = [
+  'all',
+  'any',
+  'everything',
+  'generic',
+  'general',
+  '所有',
+  '任何',
+  '全部',
+  '通用',
+  '任意任务',
+  '任何任务',
+  '所有任务',
+];
+
+function benchmarkPath(projectRoot, relativePath) {
+  return cjoin(projectRoot, relativePath);
+}
+
+function slugify(value, fallback = 'benchmark') {
+  const slug = String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  return slug || fallback;
+}
+
+function defaultSourcesFile() {
+  return {
+    version: 1,
+    schema: 'openprd.benchmarks.v1',
+    updatedAt: timestamp(),
+    sources: [],
+  };
+}
+
+function defaultIndex() {
+  return [
+    '# OpenPrd Benchmark Registry',
+    '',
+    '## 规则',
+    '',
+    '- 项目级 approved benchmark 优先于 OpenPrd 内置 Source Map。',
+    '- `inbox/` 里的 candidate 只表示待确认线索，不表示长期最佳实践。',
+    '- 被采纳信源先用 `openprd benchmark observe <url|repo|file>` 累计证据，达到阈值后只推荐 approve，不自动晋级。',
+    '- 每次只挑 1-3 个高相关来源；来源目录不是事实来源。',
+    '',
+    '## Approved Sources',
+    '',
+    '- 暂无已批准来源。',
+    '',
+    '## Candidate Sources',
+    '',
+    '- 暂无待确认来源。',
+    '',
+  ].join('\n');
+}
+
+export {
+  BENCHMARK_DIR,
+  BENCHMARK_EVIDENCE_DIR,
+  BENCHMARK_INDEX_FILE,
+  BENCHMARK_INBOX_DIR,
+  BENCHMARK_SOURCES_FILE,
+  DAY_MS,
+  DEFAULT_ADOPTION_THRESHOLD,
+  DEFAULT_ADOPTION_WINDOW_DAYS,
+  MAX_ADOPTION_EVIDENCE,
+  OVERBROAD_TRIGGER_TOKENS,
+  benchmarkPath,
+  defaultIndex,
+  defaultSourcesFile,
+  slugify,
+};

package/src/benchmark/operations.js

@@ -0,0 +1,235 @@
+/*
+ * 核心功能
+ * 实现 benchmark add/observe/list/approve 等 workspace 级命令动作。
+ *
+ * 输入
+ * 接收项目根目录和 CLI/options 透传的 source、notes、threshold、id 等参数。
+ *
+ * 输出
+ * 导出结构化 benchmark 操作结果，并在需要时写入 candidate、approved、evidence 和 index 文件。
+ *
+ * 定位
+ * 位于 benchmark 应用层，负责编排 source 逻辑与 storage 落盘，不承担 verify 探测职责。
+ *
+ * 依赖
+ * 依赖 render、source、storage 和 fs-utils；由 benchmark.js 作为对外入口复用。
+ *
+ * 维护规则
+ * 修改返回 payload 时必须保持 CLI 与测试依赖的 action/source/files/counts 契约稳定。
+ */
+import fs from 'node:fs/promises';
+import { writeText, writeYaml } from '../fs-utils.js';
+import { timestamp } from '../time.js';
+import {
+  BENCHMARK_INDEX_FILE,
+  BENCHMARK_SOURCES_FILE,
+  benchmarkPath,
+} from './constants.js';
+import { renderEvidence } from './render.js';
+import {
+  benchmarkRecommendations,
+  buildObservationEvidence,
+  buildSourceValue,
+  duplicateSource,
+  normalizeAdoptionEvidence,
+  normalizeAdoptionThreshold,
+  normalizeSourceRecord,
+  resolveSourceInput,
+  withPromotion,
+} from './source.js';
+import {
+  ensureBenchmarkWorkspace,
+  evidenceFilePath,
+  loadApprovedSources,
+  loadCandidateSources,
+  readCandidateById,
+  refreshBenchmarkIndex,
+  sourceFilePath,
+  writeApprovedSources,
+} from './storage.js';
+
+async function addBenchmarkWorkspace(projectRoot, options = {}) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const sourceValue = await resolveSourceInput(projectRoot, options.source ?? options.target ?? options.reference ?? null);
+  const source = buildSourceValue(sourceValue, options.notes ?? null);
+  const approved = await loadApprovedSources(projectRoot);
+  const candidates = await loadCandidateSources(projectRoot);
+  const duplicate = duplicateSource([...approved, ...candidates], source);
+  if (duplicate) {
+    return {
+      ok: false,
+      action: 'benchmark-add',
+      projectRoot,
+      error: `Benchmark source already exists: ${duplicate.id}`,
+      duplicate,
+    };
+  }
+
+  const candidatePath = sourceFilePath(projectRoot, source.id);
+  const evidencePath = evidenceFilePath(projectRoot, source.id);
+  await writeYaml(candidatePath, source);
+  await writeText(evidencePath, `${renderEvidence(source)}\n`);
+  const refreshed = await refreshBenchmarkIndex(projectRoot);
+
+  return {
+    ok: true,
+    action: 'benchmark-add',
+    projectRoot,
+    source,
+    files: {
+      candidate: candidatePath,
+      evidence: evidencePath,
+      index: benchmarkPath(projectRoot, BENCHMARK_INDEX_FILE),
+      sources: benchmarkPath(projectRoot, BENCHMARK_SOURCES_FILE),
+    },
+    summary: {
+      approved: refreshed.approved.length,
+      candidates: refreshed.candidates.length,
+    },
+  };
+}
+
+async function observeBenchmarkSourceWorkspace(projectRoot, options = {}) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const threshold = normalizeAdoptionThreshold(options.threshold);
+  const sourceValue = await resolveSourceInput(projectRoot, options.source ?? options.target ?? options.reference ?? null);
+  const observed = buildSourceValue(sourceValue, options.notes ?? null);
+  const approved = await loadApprovedSources(projectRoot);
+  const candidates = await loadCandidateSources(projectRoot);
+  const duplicate = duplicateSource([...approved, ...candidates], observed);
+  const baseSource = duplicate ?? observed;
+  const evidence = buildObservationEvidence(baseSource, options);
+  const adoptedCount = Math.max(0, Number(baseSource.adoptedCount ?? 0)) + 1;
+  const nextSource = withPromotion({
+    ...baseSource,
+    id: baseSource.id,
+    status: baseSource.status ?? 'candidate',
+    note: baseSource.note ?? observed.note,
+    value: baseSource.value ?? observed.value,
+    adoptedCount,
+    lastUsedAt: evidence.observedAt,
+    evidence: [
+      ...normalizeAdoptionEvidence(baseSource.evidence),
+      evidence,
+    ],
+  }, threshold, baseSource.promotion?.windowDays);
+
+  if (nextSource.status === 'approved') {
+    const nextApproved = approved.filter((source) => source.id !== nextSource.id);
+    nextApproved.push(nextSource);
+    await writeApprovedSources(projectRoot, nextApproved);
+  } else {
+    await writeYaml(sourceFilePath(projectRoot, nextSource.id), nextSource);
+  }
+  await writeText(evidenceFilePath(projectRoot, nextSource.id), `${renderEvidence(nextSource)}\n`);
+  const refreshed = await refreshBenchmarkIndex(projectRoot);
+
+  return {
+    ok: true,
+    action: 'benchmark-observe',
+    projectRoot,
+    source: nextSource,
+    created: !duplicate,
+    evidence,
+    recommended: Boolean(nextSource.promotion?.recommended),
+    recommendation: nextSource.promotion?.recommended
+      ? {
+          id: nextSource.id,
+          title: nextSource.title,
+          adoptedCount: nextSource.recentAdoptedCount,
+          totalAdoptedCount: nextSource.adoptedCount,
+          threshold: nextSource.promotion.threshold,
+          windowDays: nextSource.promotion.windowDays,
+          approveCommand: nextSource.promotion.approveCommand,
+        }
+      : null,
+    files: {
+      candidate: nextSource.status === 'candidate' ? sourceFilePath(projectRoot, nextSource.id) : null,
+      evidence: evidenceFilePath(projectRoot, nextSource.id),
+      index: benchmarkPath(projectRoot, BENCHMARK_INDEX_FILE),
+      sources: benchmarkPath(projectRoot, BENCHMARK_SOURCES_FILE),
+    },
+    summary: {
+      approved: refreshed.approved.length,
+      candidates: refreshed.candidates.length,
+    },
+  };
+}
+
+async function listBenchmarkWorkspace(projectRoot) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const approved = await loadApprovedSources(projectRoot);
+  const candidates = await loadCandidateSources(projectRoot);
+  return {
+    ok: true,
+    action: 'benchmark-list',
+    projectRoot,
+    approved,
+    candidates,
+    counts: {
+      approved: approved.length,
+      candidates: candidates.length,
+    },
+    recommendations: benchmarkRecommendations(candidates),
+  };
+}
+
+async function listBenchmarkRecommendationsWorkspace(projectRoot) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const candidates = await loadCandidateSources(projectRoot);
+  return benchmarkRecommendations(candidates);
+}
+
+async function approveBenchmarkWorkspace(projectRoot, options = {}) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const id = String(options.id ?? '').trim();
+  if (!id) {
+    throw new Error('Benchmark id is required for approve.');
+  }
+  const candidate = await readCandidateById(projectRoot, id);
+  if (!candidate) {
+    throw new Error(`Benchmark candidate not found: ${id}`);
+  }
+
+  const approved = await loadApprovedSources(projectRoot);
+  const approvedSource = normalizeSourceRecord({
+    ...candidate,
+    status: 'approved',
+    approvedAt: timestamp(),
+    promotion: {
+      ...(candidate.promotion ?? {}),
+      recommended: false,
+      recommendedAt: null,
+      approveCommand: null,
+    },
+  });
+  const nextApproved = approved.filter((source) => source.id !== id);
+  nextApproved.push(approvedSource);
+  await writeApprovedSources(projectRoot, nextApproved);
+  await fs.rm(sourceFilePath(projectRoot, id), { force: true });
+  await writeText(evidenceFilePath(projectRoot, id), `${renderEvidence(approvedSource)}\n`);
+  const refreshed = await refreshBenchmarkIndex(projectRoot);
+
+  return {
+    ok: true,
+    action: 'benchmark-approve',
+    projectRoot,
+    source: approvedSource,
+    counts: {
+      approved: refreshed.approved.length,
+      candidates: refreshed.candidates.length,
+    },
+    files: {
+      sources: benchmarkPath(projectRoot, BENCHMARK_SOURCES_FILE),
+      index: benchmarkPath(projectRoot, BENCHMARK_INDEX_FILE),
+    },
+  };
+}
+
+export {
+  addBenchmarkWorkspace,
+  approveBenchmarkWorkspace,
+  listBenchmarkRecommendationsWorkspace,
+  listBenchmarkWorkspace,
+  observeBenchmarkSourceWorkspace,
+};

package/src/benchmark/registry.js

@@ -0,0 +1,64 @@
+/*
+ * 核心功能
+ * 生成提供给 Agent 集成层的 benchmark registry 摘要片段。
+ *
+ * 输入
+ * 接收项目根目录，并读取当前 approved benchmark sources。
+ *
+ * 输出
+ * 导出 Project Benchmark Registry Markdown section，供技能模板和上下文拼装复用。
+ *
+ * 定位
+ * 位于 benchmark 展示适配层，连接 storage 读取结果与 agent-facing 文本输出。
+ *
+ * 依赖
+ * 依赖 storage 提供的 workspace 初始化与 approved source 读取能力。
+ *
+ * 维护规则
+ * 文案必须保持面向 Agent 使用场景，避免把 candidate 当成已确认事实来源写入摘要。
+ */
+import { ensureBenchmarkWorkspace, loadApprovedSources } from './storage.js';
+
+async function renderApprovedBenchmarkRegistrySection(projectRoot) {
+  await ensureBenchmarkWorkspace(projectRoot);
+  const approved = await loadApprovedSources(projectRoot);
+  if (approved.length === 0) {
+    return [
+      '## Project Benchmark Registry',
+      '',
+      '- 当前项目还没有 approved benchmark source。',
+      '- 如需补充，用 `openprd benchmark add <url|repo|file>` 添加 candidate，再用 `openprd benchmark approve <id>` 纳入项目级 registry。',
+      '- 被用户采纳过的外部信源可用 `openprd benchmark observe <url|repo|file> --notes <text>` 累计证据；达到阈值后仍需要用户确认 approve。',
+      '- Agent 仍应先读取 `.openprd/benchmarks/index.md` 和 `.openprd/benchmarks/sources.yaml`，但 candidate inbox 不能当成长期事实来源。',
+      '',
+    ].join('\n');
+  }
+
+  const lines = [
+    '## Project Benchmark Registry',
+    '',
+    '- 先读取 `.openprd/benchmarks/index.md` 和 `.openprd/benchmarks/sources.yaml`。',
+    '- 项目级 approved benchmark 优先于 OpenPrd 内置 Source Map；`inbox/` candidate 只能作为待确认线索。',
+    '- `benchmark observe` 只累计被采纳信源的证据；达到阈值后仍需用户确认 approve。',
+    '- 每次最多优先挑 1-3 个与当前任务最相关的 approved source。',
+    '',
+    '### Approved Sources',
+    '',
+  ];
+
+  for (const source of approved.slice(0, 20)) {
+    const location = source.repo ? `${source.repo} (${source.url})` : (source.url ?? source.path ?? 'unknown');
+    lines.push(`- \`${source.id}\` ${source.title}`);
+    lines.push(`  - 场景: ${source.scenarios.join(', ') || '未分类'}`);
+    lines.push(`  - 触发: ${source.triggerWhen.join('；') || '待补充'}`);
+    lines.push(`  - 不适用: ${source.notFor.join('；') || '待补充'}`);
+    lines.push(`  - 研究方式: ${source.researchMethod}`);
+    lines.push(`  - 来源: ${location}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export {
+  renderApprovedBenchmarkRegistrySection,
+};

package/src/benchmark/render.js

@@ -0,0 +1,115 @@
+/*
+ * 核心功能
+ * 负责 benchmark registry、source card 和 evidence 文本渲染。
+ *
+ * 输入
+ * 接收已经归一化的 approved/candidate source 数据。
+ *
+ * 输出
+ * 导出 index.md 和 evidence.md 所需的稳定 Markdown 片段。
+ *
+ * 定位
+ * 位于 benchmark 展示层，只做字符串组装，不参与 IO、校验或业务状态变更。
+ *
+ * 依赖
+ * 无外部业务依赖；由 storage、operations 和 registry 复用。
+ *
+ * 维护规则
+ * 修改渲染文案时必须保持现有字段含义不变，避免影响生成 skill、CLI 输出和历史 benchmark 文件阅读。
+ */
+function renderSourceCard(source) {
+  const location = source.url ?? source.path ?? 'unknown';
+  const scenarios = source.scenarios.length > 0 ? source.scenarios.join(', ') : '未分类';
+  const triggerWhen = source.triggerWhen.length > 0 ? source.triggerWhen.join('；') : '待补充';
+  const notFor = source.notFor.length > 0 ? source.notFor.join('；') : '待补充';
+  const lines = [
+    `### ${source.title} \`${source.id}\``,
+    '',
+    `- 状态: ${source.status}`,
+    `- 来源类型: ${source.sourceType}`,
+    `- 场景: ${scenarios}`,
+    `- 触发: ${triggerWhen}`,
+    `- 不适用: ${notFor}`,
+    `- 研究方式: ${source.researchMethod}`,
+    `- 来源: ${location}`,
+    `- 规范化信源: ${source.sourceKey ?? source.id}`,
+    `- 最近 ${source.promotion.windowDays} 天采纳: ${source.recentAdoptedCount}`,
+    `- 累计采纳: ${source.adoptedCount}`,
+  ];
+  if (source.lastUsedAt) {
+    lines.push(`- 最近采纳时间: ${source.lastUsedAt}`);
+  }
+  if (source.promotion?.recommended) {
+    lines.push(`- 推荐: 最近 ${source.promotion.windowDays} 天已达到 ${source.recentAdoptedCount}/${source.promotion.threshold} 次采纳，建议确认后运行 \`${source.promotion.approveCommand}\``);
+  }
+  if (source.note) {
+    lines.push(`- 备注: ${source.note}`);
+  }
+  if (source.value) {
+    lines.push(`- 价值: ${source.value}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderBenchmarkIndex(approved, candidates) {
+  const lines = [
+    '# OpenPrd Benchmark Registry',
+    '',
+    '## 规则',
+    '',
+    '- 项目级 approved benchmark 优先于 OpenPrd 内置 Source Map。',
+    '- `inbox/` 里的 candidate 只表示待确认线索，不表示长期最佳实践。',
+    '- 被采纳信源先累计证据，达到阈值后只推荐 approve，不自动晋级。',
+    '- 每次只挑 1-3 个高相关来源；来源目录不是事实来源。',
+    '',
+    '## Approved Sources',
+    '',
+  ];
+  if (approved.length === 0) {
+    lines.push('- 暂无已批准来源。', '');
+  } else {
+    for (const source of approved) {
+      lines.push(renderSourceCard(source));
+    }
+  }
+
+  lines.push('## Candidate Sources', '');
+  if (candidates.length === 0) {
+    lines.push('- 暂无待确认来源。', '');
+  } else {
+    for (const source of candidates) {
+      lines.push(renderSourceCard(source));
+    }
+  }
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+function renderEvidence(source) {
+  return [
+    `# ${source.title}`,
+    '',
+    `- ID: ${source.id}`,
+    `- 状态: ${source.status}`,
+    `- 场景: ${source.scenarios.join(', ') || '未分类'}`,
+    `- 触发: ${source.triggerWhen.join('；') || '待补充'}`,
+    `- 不适用: ${source.notFor.join('；') || '待补充'}`,
+    `- 研究方式: ${source.researchMethod}`,
+    `- 来源: ${source.url ?? source.path ?? 'unknown'}`,
+    `- 规范化信源: ${source.sourceKey ?? source.id}`,
+    `- 最近 ${source.promotion.windowDays} 天采纳: ${source.recentAdoptedCount}`,
+    `- 累计采纳: ${source.adoptedCount}`,
+    source.lastUsedAt ? `- 最近采纳时间: ${source.lastUsedAt}` : null,
+    source.promotion?.recommended ? `- 推荐命令: ${source.promotion.approveCommand}` : null,
+    '',
+    '## 备注',
+    '',
+    source.note ?? '待补充',
+    '',
+  ].filter((line) => line !== null).join('\n');
+}
+
+export {
+  renderBenchmarkIndex,
+  renderEvidence,
+};