@dommaker/harness 1.6.0 → 1.8.0

package/src/cli/commands/scaffold.ts

@@ -0,0 +1,302 @@
+/**
+ * 脚手架落盘模块（harness#132，架构评审候选3）
+ *
+ * 一个决策只写一次：受管文件（managed file — harness 模板拥有正本、用户也可能
+ * 持有的落盘文件）在不在场、在场时算跳过还是算请用户手工合并、要不要建父目录、
+ * 打什么颜色的哪句话，全部收在本模块。此前这段判定复印在 init 6 处 + validate 2 处。
+ *
+ * 三态：
+ * - `created` 不在场 → 落盘模板正文
+ * - `exists`  在场 → 灰字告知跳过（**不细分内容是否等于模板**，内容比较是独立特性）
+ * - `manual`  在场 → 打印片段请用户手工合并
+ *
+ * 纪律：本模块不持有覆盖/跳过策略——「哪些文件要落」由命令层翻成 plan 列表传进来，
+ * 本模块只见 plan；模板正文住在 `scaffold-templates.ts`。
+ */
+
+import * as path from 'path';
+import chalk from 'chalk';
+import * as nodeFs from 'fs/promises';
+import type { CiPlatform } from '../../types/project-config';
+import { log, type CommandIO } from '../command-contract';
+import {
+  CUSTOM_CONSTRAINTS_TEMPLATE,
+  DEFAULT_CHECKPOINT_FILE,
+  HARNESS_CHECK_WORKFLOW,
+  PRE_COMMIT_SNIPPET,
+  PRE_PUSH_SNIPPET,
+  renderChangelog,
+  renderCheckpoints,
+  renderContextDoc,
+  renderGitLabCiFile,
+  renderGitLabCiJobs,
+  renderGovernanceWorkflow,
+  renderPreCommitHook,
+  renderPrePushHook,
+  renderResolutions,
+} from './scaffold-templates';
+
+/** 三态判定结果 */
+export type ScaffoldOutcome = 'created' | 'exists' | 'manual';
+
+/**
+ * 落盘注入面（缺省 node fs；测试注入内存替身即可断言「真写出了什么内容」）
+ */
+export interface ScaffoldFileSystem {
+  exists(target: string): Promise<boolean>;
+  mkdir(dir: string): Promise<void>;
+  writeFile(target: string, content: string): Promise<void>;
+  chmod(target: string, mode: number): Promise<void>;
+}
+
+export const nodeScaffoldFs: ScaffoldFileSystem = {
+  async exists(target) {
+    try {
+      await nodeFs.access(target);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async mkdir(dir) {
+    await nodeFs.mkdir(dir, { recursive: true });
+  },
+  async writeFile(target, content) {
+    await nodeFs.writeFile(target, content, 'utf-8');
+  },
+  async chmod(target, mode) {
+    await nodeFs.chmod(target, mode);
+  },
+};
+
+/**
+ * 在场处置：
+ * - `skip`  harness 不再主张这份正文，灰字告知即可
+ * - `merge` 用户可能持有自己的内容，打印片段（与落盘正文同源）请其手工合并
+ */
+export type OnPresent =
+  | { outcome: 'skip'; notice: string }
+  | {
+      outcome: 'merge';
+      notice: string;
+      /** 提示与指引之间的灰字补充行（如冲突来源清单） */
+      detail?: string[];
+      instruction: string;
+      snippet: string;
+    };
+
+/** 一个受管文件 = 三态判定所需的全部数据 */
+export interface ManagedFile {
+  /** 落盘目标（绝对路径） */
+  target: string;
+  /** harness 拥有的模板正文 */
+  content: string;
+  /** 落盘态绿字 */
+  created: string;
+  /** 在场态处置 */
+  onPresent: OnPresent;
+  /** 在场判定覆写，缺省 = target 自身在场（冲突面可以宽于 target，如 CI 配置目录） */
+  present?: () => Promise<boolean>;
+  /** 落盘权限位（Git hook 需要可执行位） */
+  mode?: number;
+}
+
+/**
+ * 落一个受管文件：判定 → 建目录 → 写盘 → 上色打印
+ */
+export async function writeManagedFile(
+  file: ManagedFile,
+  io: CommandIO,
+  fs: ScaffoldFileSystem = nodeScaffoldFs,
+): Promise<ScaffoldOutcome> {
+  const present = file.present ? await file.present() : await fs.exists(file.target);
+
+  if (!present) {
+    await fs.mkdir(path.dirname(file.target));
+    await fs.writeFile(file.target, file.content);
+    if (file.mode !== undefined) await fs.chmod(file.target, file.mode);
+    log(io, chalk.green(file.created));
+    return 'created';
+  }
+
+  if (file.onPresent.outcome === 'skip') {
+    log(io, chalk.gray(file.onPresent.notice));
+    return 'exists';
+  }
+
+  log(io, chalk.yellow(file.onPresent.notice));
+  for (const line of file.onPresent.detail ?? []) {
+    log(io, chalk.gray(line));
+  }
+  log(io, chalk.gray(file.onPresent.instruction));
+  log(io);
+  log(io, chalk.cyan(file.onPresent.snippet));
+  return 'manual';
+}
+
+/** 按顺序落一组受管文件 */
+export async function runPlan(
+  plan: readonly ManagedFile[],
+  io: CommandIO,
+  fs: ScaffoldFileSystem = nodeScaffoldFs,
+): Promise<ScaffoldOutcome[]> {
+  const outcomes: ScaffoldOutcome[] = [];
+  for (const file of plan) {
+    outcomes.push(await writeManagedFile(file, io, fs));
+  }
+  return outcomes;
+}
+
+// ── 站点：init 的 7 处 + 原住 validate 的 2 处 ──────────────────────────
+
+/** .git/hooks/pre-commit（冲突片段 = 落盘正文去掉 shebang 头，逐字同源） */
+export function preCommitHookFile(projectPath: string): ManagedFile {
+  return {
+    target: path.join(projectPath, '.git', 'hooks', 'pre-commit'),
+    content: renderPreCommitHook(),
+    created: '✅ 已创建 .git/hooks/pre-commit',
+    mode: 0o755,
+    onPresent: {
+      outcome: 'merge',
+      notice: '⚠️  .git/hooks/pre-commit 已存在',
+      instruction: '💡 请手动添加以下内容到文件末尾：',
+      snippet: PRE_COMMIT_SNIPPET,
+    },
+  };
+}
+
+/**
+ * .git/hooks/pre-push（harness#144 的第 9 站点，冲突片段与落盘正文逐字同源）
+ *
+ * 与 pre-commit 的分工：那道查暂存的（增量、快反馈），这道查整仓的（全量、兜底）。
+ * 本地 hook 是自检与提醒，门禁真正的落点仍是服务端 CI。
+ */
+export function prePushHookFile(projectPath: string): ManagedFile {
+  return {
+    target: path.join(projectPath, '.git', 'hooks', 'pre-push'),
+    content: renderPrePushHook(),
+    created: '✅ 已创建 .git/hooks/pre-push',
+    mode: 0o755,
+    onPresent: {
+      outcome: 'merge',
+      notice: '⚠️  .git/hooks/pre-push 已存在',
+      instruction: '💡 请手动添加以下内容到文件末尾：',
+      snippet: PRE_PUSH_SNIPPET,
+    },
+  };
+}
+
+/**
+ * 服务端 CI 门禁站点（平台维度，harness#143）
+ *
+ * - `github` → `.github/workflows/harness-check.yml`；冲突判定宽于 target 自身：
+ *   工作流目录里已有任何 CI 配置就算冲突，片段是完整 workflow 正文（打印的即落盘的，#103 判据）
+ * - `gitlab` → `.gitlab-ci.yml`；冲突面就是该文件自身在场，片段是 harness 拥有的任务正文。
+ *   GitLab 没有「第二个 CI 文件位」，所以 `-g` 档的治理任务并入同一份正文
+ *   ——这也是 `governanceLevel` 只对 gitlab 形有意义的原因（GH 侧治理站是独立的
+ *   `governanceWorkflowFile`）。
+ *
+ * `none`（不接线）不进来：那是命令层的 plan 里没有这个站点，scaffold 不持有跳过策略。
+ */
+export function harnessCheckCiFile(
+  projectPath: string,
+  platform: CiPlatform,
+  existingCiWorkflows: string[],
+  governanceLevel?: string,
+): ManagedFile {
+  if (platform === 'gitlab') {
+    const content = renderGitLabCiFile(governanceLevel);
+    return {
+      target: path.join(projectPath, '.gitlab-ci.yml'),
+      content,
+      created: '✅ 已创建 .gitlab-ci.yml',
+      onPresent: {
+        outcome: 'merge',
+        notice: '⚠️  .gitlab-ci.yml 已存在',
+        instruction: '💡 请手动添加以下内容到文件中：',
+        snippet: renderGitLabCiJobs(governanceLevel),
+      },
+    };
+  }
+
+  const target = path.join(projectPath, '.github', 'workflows', 'harness-check.yml');
+  return {
+    target,
+    content: HARNESS_CHECK_WORKFLOW,
+    created: '✅ 已创建 .github/workflows/harness-check.yml',
+    present: async () => existingCiWorkflows.length > 0,
+    onPresent: {
+      outcome: 'merge',
+      notice: '⚠️  检测到已存在的 CI 配置：',
+      detail: existingCiWorkflows.map(f => `  - .github/workflows/${f}`),
+      instruction: '💡 请手动添加以下内容到 jobs 中：',
+      snippet: HARNESS_CHECK_WORKFLOW,
+    },
+  };
+}
+
+/** .harness/custom-constraints.yml 示例 */
+export function customConstraintsFile(projectPath: string): ManagedFile {
+  return {
+    target: path.join(projectPath, '.harness', 'custom-constraints.yml'),
+    content: CUSTOM_CONSTRAINTS_TEMPLATE,
+    created: '✅ 已创建自定义约束示例: custom-constraints.yml',
+    onPresent: { outcome: 'skip', notice: 'custom-constraints.yml 已存在' },
+  };
+}
+
+/** .harness/checkpoints.yml 示例（原住 validate.ts，路径约定与 validate 共用） */
+export function checkpointsFile(projectPath: string): ManagedFile {
+  const target = path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
+  return {
+    target,
+    content: renderCheckpoints(),
+    created: `✅ 已创建示例检查点文件: ${target}`,
+    onPresent: { outcome: 'skip', notice: 'checkpoints.yml 已存在，跳过' },
+  };
+}
+
+/** .harness/resolutions.json（RKB 狗粮 — 约束 → 已知解法映射，原住 validate.ts） */
+export function resolutionsFile(projectPath: string): ManagedFile {
+  const target = path.join(projectPath, '.harness', 'resolutions.json');
+  return {
+    target,
+    content: renderResolutions(),
+    created: `✅ 已创建 Resolutions 文件: ${target}`,
+    onPresent: { outcome: 'skip', notice: 'resolutions.json 已存在，跳过' },
+  };
+}
+
+/** CHANGELOG.md 骨架 */
+export function changelogFile(projectPath: string, format: string): ManagedFile {
+  return {
+    target: path.join(projectPath, 'CHANGELOG.md'),
+    content: renderChangelog(format),
+    created: '✅ 已创建 CHANGELOG.md',
+    onPresent: { outcome: 'skip', notice: 'CHANGELOG.md 已存在' },
+  };
+}
+
+/** `<dir>/CONTEXT.md` 骨架 */
+export function contextDocFile(projectPath: string, dir: string): ManagedFile {
+  return {
+    target: path.join(projectPath, dir, 'CONTEXT.md'),
+    content: renderContextDoc(dir),
+    created: `✅ 已创建 ${dir}/CONTEXT.md`,
+    onPresent: { outcome: 'skip', notice: `${dir}/CONTEXT.md 已存在` },
+  };
+}
+
+/**
+ * .github/workflows/harness-governance.yml（治理 CI 面，仅 github 形）
+ *
+ * gitlab 形的治理任务并入 `.gitlab-ci.yml`（见 `harnessCheckCiFile`），无本站点。
+ */
+export function governanceWorkflowFile(projectPath: string, level: string): ManagedFile {
+  return {
+    target: path.join(projectPath, '.github', 'workflows', 'harness-governance.yml'),
+    content: renderGovernanceWorkflow(level, 'github'),
+    created: '✅ 已创建 .github/workflows/harness-governance.yml',
+    onPresent: { outcome: 'skip', notice: 'harness-governance.yml 已存在' },
+  };
+}

package/src/cli/commands/security.ts

@@ -7,6 +7,7 @@
 import chalk from 'chalk';
 import { SecurityGate } from '../../gates/security';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { reportGateDecision } from '../gate-command';
 
 export interface SecurityOptions {
   /** 项目路径 */
@@ -40,29 +41,32 @@ export async function security(
       ignoreDevDependencies: options.ignoreDevDeps,
     });
 
-    const result = await gate.scan({ projectPath, projectId: 'default' });
+    const decision = await gate.evaluate({ projectPath });
 
-    log(io);
-    if (result.passed) {
-      log(io, chalk.green('✅ 安全门控检查通过'));
-      if (result.details) {
-        log(io, chalk.gray(`   critical: ${result.details.critical}, high: ${result.details.high}, moderate: ${result.details.moderate}, low: ${result.details.low}`));
-      }
-    } else {
-      log(io, chalk.red('❌ 安全门控检查失败'));
-      log(io, chalk.red(`   ${result.message}`));
-      if (result.details?.vulnerabilities) {
-        log(io);
-        (result.details.vulnerabilities as Array<{ name: string; severity: string; via: string }>).forEach((v, i) => {
-          const severityColor = getSeverityColor(v.severity);
-          log(io, severityColor(`  ${i + 1}. [${v.severity.toUpperCase()}] ${v.name}`));
-          log(io, chalk.gray(`     via: ${v.via}`));
-        });
-      }
-      log(io, chalk.gray('\n   运行 harness security audit 查看详情'));
-      return { kind: 'fail', reason: `security gate denied (threshold ${options.severity || 'high'}): ${result.message}` };
-    }
-    return { kind: 'ok' };
+    return reportGateDecision(
+      io,
+      {
+        gateId: 'security',
+        label: '安全门控',
+        onPass: (r) =>
+          r.details
+            ? [chalk.gray(`   critical: ${r.details.critical}, high: ${r.details.high}, moderate: ${r.details.moderate}, low: ${r.details.low}`)]
+            : [],
+        onFail: (r) => {
+          const lines = [chalk.gray(`   阈值: ${options.severity || 'high'}`)];
+          if (r.details?.vulnerabilities) {
+            lines.push('');
+            (r.details.vulnerabilities as Array<{ name: string; severity: string; via: string }>).forEach((v, i) => {
+              lines.push(getSeverityColor(v.severity)(`  ${i + 1}. [${v.severity.toUpperCase()}] ${v.name}`));
+              lines.push(chalk.gray(`     via: ${v.via}`));
+            });
+          }
+          lines.push(chalk.gray('\n   运行 harness security audit 查看详情'));
+          return lines;
+        },
+      },
+      decision
+    );
   } catch (error) {
     log(io);
     log(io, chalk.red(`❌ 安全检查异常: ${error instanceof Error ? error.message : String(error)}`));
@@ -105,7 +109,7 @@ export async function auditDetails(
       scanCommand: options.scanCommand,
     });
 
-    const result = await gate.scan({ projectPath, projectId: 'default' });
+    const result = await gate.scan({ projectPath });
 
     if (result.passed && !result.details?.total) {
       log(io, chalk.green('✅ 未发现安全漏洞'));

package/src/cli/commands/spec-baseline-check.ts

@@ -81,6 +81,133 @@ export function extractBaselineSection(content: string): string[] {
   return prerequisites;
 }
 
+// ============================================
+// 命令级共享索引
+// ============================================
+
+/** package.json 依赖面的一次解析结果（失败态同样入库，不重试） */
+type DependencySnapshot = { ok: true; deps: Record<string, string> } | { ok: false };
+
+/**
+ * 共享索引的驻留上限（#162，统一复审遗留项 3）：
+ * #146 把全仓源文件内容常驻一个 Map，排除面只有 node_modules/dist/隐藏目录与后缀，
+ * 无任何容量上限——峰值内存由 O(单文件) 变 O(全仓源码)，大 monorepo 会承担这个峰值。
+ * 超出任一上限即放弃驻留、回落逐文件流式读（峰值回到 O(单文件)），
+ * 正常规模仓仍保留「一次遍历」收益。
+ */
+export const SOURCE_INDEX_MAX_ENTRIES = 5000;
+export const SOURCE_INDEX_MAX_BYTES = 64 * 1024 * 1024;
+
+/** 驻留上限（测试可注入小值走回落路径；生产一律缺省常量） */
+export interface SourceIndexLimits {
+  maxEntries: number;
+  maxBytes: number;
+}
+
+/**
+ * 一次 spec-baseline-check 运行内的取数面（工单 #146，母票 #140 A 票）：
+ * 全仓内容扫描、`package.json` 解析、同一落点的存在性探测各至多一遍，
+ * 逐条前置只在索引上重放判定——此前是「前置条件数 × 关键词数 × 源文件数」的逐条重扫。
+ *
+ * 懒建：没有任何前置需要某类数据时，该类读取一次都不发生（口径与改前一致）。
+ * 运行结束即弃，不跨命令、不扩 `RunEnv` 公共面（#140 triage 裁决 5）。
+ */
+interface BaselineIndex {
+  /**
+   * 内容含 keyword 的源文件数。上限内走驻留索引重放（一次运行全仓至多读一遍）；
+   * 超 SOURCE_INDEX_MAX_ENTRIES / SOURCE_INDEX_MAX_BYTES 即放弃驻留，
+   * 每个关键词回落逐文件流式读（#162：驻留条目数有上界，峰值 O(单文件)）。
+   */
+  countFilesContaining(keyword: string): number;
+  /** package.json 的 dependencies + devDependencies 合并面 */
+  dependencies(): DependencySnapshot;
+  /** 绝对路径是否在世（同一落点一次运行内只 stat 一次） */
+  exists(fullPath: string): boolean;
+}
+
+export function createBaselineIndex(
+  projectPath: string,
+  limits: SourceIndexLimits = { maxEntries: SOURCE_INDEX_MAX_ENTRIES, maxBytes: SOURCE_INDEX_MAX_BYTES }
+): BaselineIndex {
+  /** undefined = 未建（懒建）；null = 超上限放弃驻留（回落流式读） */
+  let sources: Map<string, string> | null | undefined;
+  let dependencySnapshot: DependencySnapshot | undefined;
+  const stats = new Map<string, boolean>();
+
+  const walkSourceFiles = () =>
+    walkFiles(projectPath, {
+      skipDirs: ['node_modules', 'dist'],
+      skipHidden: true,
+      filter: (_name, filePath) => filePath.endsWith('.ts') || filePath.endsWith('.js'),
+    });
+
+  /** 遍历与内容读取各一次建驻留索引；超任一上限即弃表返回 null（#162 驻留上界） */
+  function buildIndex(): Map<string, string> | null {
+    const map = new Map<string, string>();
+    let totalBytes = 0;
+    for (const fullPath of walkSourceFiles()) {
+      try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        map.set(fullPath, content);
+        totalBytes += Buffer.byteLength(content);
+        if (map.size > limits.maxEntries || totalBytes > limits.maxBytes) {
+          return null; // 已读内容随 map 一起弃，驻留峰值 ≤ 上限
+        }
+      } catch {
+        /* skip：读失败的文件不入表（与改前逐文件 try/catch 跳过同义） */
+      }
+    }
+    return map;
+  }
+
+  return {
+    countFilesContaining(keyword) {
+      if (sources === undefined) sources = buildIndex();
+      if (sources !== null) {
+        let count = 0;
+        for (const content of sources.values()) {
+          if (content.includes(keyword)) count++;
+        }
+        return count;
+      }
+      // 回落：逐文件流式读、读完即弃，驻留 O(单文件)（改前逐关键词重读同形）
+      let count = 0;
+      for (const fullPath of walkSourceFiles()) {
+        try {
+          if (fs.readFileSync(fullPath, 'utf-8').includes(keyword)) count++;
+        } catch {
+          /* skip */
+        }
+      }
+      return count;
+    },
+    dependencies() {
+      if (!dependencySnapshot) {
+        try {
+          const pkgJson = JSON.parse(
+            fs.readFileSync(path.join(projectPath, 'package.json'), 'utf-8')
+          );
+          dependencySnapshot = {
+            ok: true,
+            deps: { ...pkgJson.dependencies, ...pkgJson.devDependencies },
+          };
+        } catch {
+          dependencySnapshot = { ok: false };
+        }
+      }
+      return dependencySnapshot;
+    },
+    exists(fullPath) {
+      let hit = stats.get(fullPath);
+      if (hit === undefined) {
+        hit = fs.existsSync(fullPath);
+        stats.set(fullPath, hit);
+      }
+      return hit;
+    },
+  };
+}
+
 // ============================================
 // 验证器
 // ============================================
@@ -88,7 +215,11 @@ export function extractBaselineSection(content: string): string[] {
 /**
  * 检查文件/目录是否存在
  */
-function checkFileExists(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+function checkFileExists(
+  pattern: string,
+  projectPath: string,
+  index: BaselineIndex
+): { exists: boolean; evidence: string } {
   // 提取路径引用（反引号中的路径、引号中的路径、或直接的路径模式）
   const pathPatterns = [
     /`([^`]+\.[a-z]+)`/g,           // `src/foo.ts`
@@ -115,7 +246,7 @@ function checkFileExists(pattern: string, projectPath: string): { exists: boolea
 
   for (const p of paths) {
     const fullPath = path.resolve(projectPath, p);
-    if (fs.existsSync(fullPath)) {
+    if (index.exists(fullPath)) {
       found.push(p);
     } else {
       missing.push(p);
@@ -134,7 +265,7 @@ function checkFileExists(pattern: string, projectPath: string): { exists: boolea
 /**
  * 检查代码中是否存在特定模式
  */
-function checkCodePattern(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+function checkCodePattern(pattern: string, index: BaselineIndex): { exists: boolean; evidence: string } {
   // 从描述中提取关键词
   const keywords: string[] = [];
 
@@ -162,21 +293,9 @@ function checkCodePattern(pattern: string, projectPath: string): { exists: boole
   const found: string[] = [];
   const notFound: string[] = [];
 
-  // 遍历一次，供所有关键词复用（工单 19：walkFiles 收敛）
-  const sourceFiles = walkFiles(projectPath, {
-    skipDirs: ['node_modules', 'dist'],
-    skipHidden: true,
-    filter: (_name, fullPath) => fullPath.endsWith('.ts') || fullPath.endsWith('.js'),
-  });
-
+  // 一次运行一份索引：全仓扫描与内容读取已在索引里发生一遍（超上限则回落流式），这里只做匹配
   for (const kw of keywords) {
-    let count = 0;
-    for (const fullPath of sourceFiles) {
-      try {
-        const content = fs.readFileSync(fullPath, 'utf-8');
-        if (content.includes(kw)) count++;
-      } catch { /* skip */ }
-    }
+    const count = index.countFilesContaining(kw);
     if (count > 0) {
       found.push(`${kw} (${count} files)`);
     } else {
@@ -196,7 +315,11 @@ function checkCodePattern(pattern: string, projectPath: string): { exists: boole
 /**
  * 检查包依赖是否安装
  */
-function checkDependency(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+function checkDependency(
+  pattern: string,
+  projectPath: string,
+  index: BaselineIndex
+): { exists: boolean; evidence: string } {
   // 提取包名
   const pkgPatterns = [
     /`(@?[\w-]+\/[\w-]+)`/g,      // `@scope/pkg` or `pkg-name`
@@ -223,15 +346,12 @@ function checkDependency(pattern: string, projectPath: string): { exists: boolea
   const found: string[] = [];
   const missing: string[] = [];
 
-  const pkgJsonPath = path.join(projectPath, 'package.json');
-  let deps: Record<string, string> = {};
-
-  try {
-    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
-    deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
-  } catch {
+  // 一次运行只读解析一遍 package.json（失败态同样入库）
+  const snapshot = index.dependencies();
+  if (!snapshot.ok) {
     return { exists: false, evidence: '无法读取 package.json' };
   }
+  const deps = snapshot.deps;
 
   for (const pkg of packages) {
     if (deps[pkg] || deps[`@types/${pkg}`]) {
@@ -239,7 +359,7 @@ function checkDependency(pattern: string, projectPath: string): { exists: boolea
     } else {
       // 检查 node_modules
       const nmPath = path.join(projectPath, 'node_modules', pkg);
-      if (fs.existsSync(nmPath)) {
+      if (index.exists(nmPath)) {
         found.push(pkg);
       } else {
         missing.push(pkg);
@@ -257,15 +377,19 @@ function checkDependency(pattern: string, projectPath: string): { exists: boolea
 }
 
 /**
- * 综合验证一条前置条件
+ * 综合验证一条前置条件（取数一律经命令级共享索引 `index`）
  */
-function verifyPrerequisite(prereq: string, projectPath: string): PrerequisiteResult {
+function verifyPrerequisite(
+  prereq: string,
+  projectPath: string,
+  index: BaselineIndex
+): PrerequisiteResult {
   const lower = prereq.toLowerCase();
 
   // 路径/文件存在性检查
   if (lower.includes('文件') || lower.includes('file') || lower.includes('目录') || lower.includes('directory')
     || /`[^`]+\.[a-z]+`/.test(prereq) || /\//.test(prereq)) {
-    const { exists, evidence } = checkFileExists(prereq, projectPath);
+    const { exists, evidence } = checkFileExists(prereq, projectPath, index);
     if (exists || evidence.includes('文件不存在')) {
       return { prerequisite: prereq, satisfied: exists, evidence };
     }
@@ -273,7 +397,7 @@ function verifyPrerequisite(prereq: string, projectPath: string): PrerequisiteRe
 
   // 依赖检查
   if (lower.includes('依赖') || lower.includes('install') || lower.includes('package') || lower.includes('npm')) {
-    const { exists, evidence } = checkDependency(prereq, projectPath);
+    const { exists, evidence } = checkDependency(prereq, projectPath, index);
     return { prerequisite: prereq, satisfied: exists, evidence };
   }
 
@@ -281,7 +405,7 @@ function verifyPrerequisite(prereq: string, projectPath: string): PrerequisiteRe
   if (lower.includes('实现') || lower.includes('implement') || lower.includes('exist')
     || lower.includes('已') || lower.includes('必须')
     || /`[^`]+`/.test(prereq)) {
-    const { exists, evidence } = checkCodePattern(prereq, projectPath);
+    const { exists, evidence } = checkCodePattern(prereq, index);
     return { prerequisite: prereq, satisfied: exists, evidence };
   }
 
@@ -360,8 +484,9 @@ export async function specBaselineCheck(
     return { kind: 'skip', reason: '未找到 Baseline / 前置条件 section，无可判定项' };
   }
 
-  // 验证每条前置条件
-  const results = prerequisites.map(p => verifyPrerequisite(p, projectPath));
+  // 验证每条前置条件（全仓扫描与 package.json 解析在本次运行内各至多一遍）
+  const index = createBaselineIndex(projectPath);
+  const results = prerequisites.map(p => verifyPrerequisite(p, projectPath, index));
 
   // 输出
   if (options.json) {