autosnippet 3.0.10 → 3.0.13

package/dashboard/dist/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>AutoSnippet Dashboard</title>
-    <script type="module" crossorigin src="/assets/index-I2ySoCmF.js"></script>
+    <script type="module" crossorigin src="/assets/index-Bnm26ulL.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/yaml-qRaU8Ldn.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-CEnWn7aV.js">
     <link rel="modulepreload" crossorigin href="/assets/axios-C0Zqfgkc.js">

package/lib/cli/SetupService.js

@@ -53,6 +53,7 @@ import {
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { checkWriteSafety, safeCopyFile, safeWriteFile } from '../service/cursor/FileProtection.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -451,10 +452,10 @@ export class SetupService {
     this._configureVSCodeMCP(mcpServerPath);
     this._configureCursorMCP(mcpServerPath);
     this._copyCopilotInstructions();
+    this._generateAgentInstructionFiles();
     this._copyCursorRules();
     this._copySkillsTemplate();
-    this._mirrorCursorToIDE('.qoder');
-    this._mirrorCursorToIDE('.trae');
+    // NOTE: .qoder/ .trae/ 不再自动创建，用户可通过 `asd mirror` 按需生成
 
     const extResult = this._installVSCodeExtension();
 
@@ -462,10 +463,9 @@ export class SetupService {
       'vscode-mcp',
       'cursor-mcp',
       'copilot-instructions',
+      'agent-instructions',
       'cursor-rules',
       'skills-template',
-      'qoder-rules',
-      'trae-rules',
     ];
     if (extResult) {
       configured.push(...extResult);
@@ -706,7 +706,7 @@ export class SetupService {
     writeFileSync(configPath, JSON.stringify(existing, null, 2));
   }
 
-  /** @private .github/copilot-instructions.md */
+  /** @private .github/copilot-instructions.md (static template fallback) */
   _copyCopilotInstructions() {
     const src = join(REPO_ROOT, 'templates', 'copilot-instructions.md');
     if (!existsSync(src)) {
@@ -719,10 +719,97 @@ export class SetupService {
       return;
     }
 
+    // 即使 --force，也不覆盖用户原有的非 AutoSnippet 文件
+    const { canWrite, reason } = checkWriteSafety(dest);
+    if (!canWrite) {
+      console.log(`   ⏭️  copilot-instructions.md — 跳过（${reason}，非 AutoSnippet 生成）`);
+      return;
+    }
+
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
   }
 
+  /**
+   * @private 生成 AGENTS.md + CLAUDE.md 静态骨架
+   * setup 阶段没有知识库数据，所以只生成指向 MCP 的基础版本。
+   * bootstrap / delivery pipeline 完成后会用动态版本覆盖。
+   */
+  _generateAgentInstructionFiles() {
+    const projectName = this.projectRoot.split('/').pop();
+
+    // AGENTS.md
+    const agentsPath = join(this.projectRoot, 'AGENTS.md');
+    if (!existsSync(agentsPath) || this.force) {
+      const { canWrite } = checkWriteSafety(agentsPath);
+      if (canWrite) {
+        const agentsContent = [
+          `# ${projectName} — Agent Instructions`,
+          '',
+          '> Auto-generated by AutoSnippet. Will be enriched after `asd bootstrap`.',
+          '',
+          '## Project Knowledge Base',
+          '',
+          'This project uses **AutoSnippet** for knowledge management.',
+          'Run `asd bootstrap` to populate the knowledge base, then this file will be',
+          'regenerated with coding standards, patterns, and tool references.',
+          '',
+          '## MCP Tools',
+          '',
+          'Use these MCP tools to access the full knowledge base:',
+          '- `autosnippet_search` — Search knowledge (mode: auto/context/keyword/semantic)',
+          '- `autosnippet_knowledge` — Browse/get recipes (operation: list/get/insights)',
+          '- `autosnippet_submit_knowledge` — Submit candidate (strict validation)',
+          '- `autosnippet_guard` — Code compliance check',
+          '- `autosnippet_health` — Service health & KB stats',
+          '',
+          '## Mandatory Constraints',
+          '',
+          '1. **Do NOT modify** knowledge base files directly (`AutoSnippet/`, `.autosnippet/`).',
+          '2. Create or update knowledge **only** through MCP tools.',
+          '3. **Prefer Recipes** as project standards; source code is supplementary.',
+          '',
+        ].join('\n');
+        writeFileSync(agentsPath, agentsContent);
+      } else {
+        console.log('   ⏭️  AGENTS.md — 跳过（用户文件，非 AutoSnippet 生成）');
+      }
+    }
+
+    // CLAUDE.md
+    const claudePath = join(this.projectRoot, 'CLAUDE.md');
+    if (!existsSync(claudePath) || this.force) {
+      const { canWrite } = checkWriteSafety(claudePath);
+      if (canWrite) {
+        const claudeContent = [
+          `# ${projectName} — Claude Code Instructions`,
+          '',
+          '> Auto-generated by AutoSnippet. Will be enriched after `asd bootstrap`.',
+          '',
+          '## MCP Integration',
+          '',
+          'This project has an AutoSnippet MCP server configured.',
+          'Use the following tools to access project knowledge:',
+          '- `autosnippet_search` — Search knowledge (mode: auto/context/keyword/semantic)',
+          '- `autosnippet_knowledge` — Browse/get recipes (operation: list/get/insights)',
+          '- `autosnippet_submit_knowledge` — Submit candidate (strict validation)',
+          '- `autosnippet_guard` — Code compliance check',
+          '- `autosnippet_health` — Service health & KB stats',
+          '',
+          '## Mandatory Constraints',
+          '',
+          '1. **Do NOT modify** knowledge base files directly (`AutoSnippet/`, `.autosnippet/`).',
+          '2. Create or update knowledge **only** through MCP tools.',
+          '3. **Prefer Recipes** as project standards; source code is supplementary.',
+          '',
+        ].join('\n');
+        writeFileSync(claudePath, claudeContent);
+      } else {
+        console.log('   ⏭️  CLAUDE.md — 跳过（用户文件，非 AutoSnippet 生成）');
+      }
+    }
+  }
+
   /** @private .cursor/rules/autosnippet-conventions.mdc */
   _copyCursorRules() {
     const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-conventions.mdc');

package/lib/cli/UpgradeService.js

@@ -5,7 +5,7 @@
  *   ① MCP 配置（.cursor/mcp.json + .vscode/mcp.json）
  *   ② Cursor Skills（.cursor/skills/）
  *   ③ Cursor Rules（.cursor/rules/autosnippet-conventions.mdc + autosnippet-skills.mdc）
- *   ④ Copilot Instructions（.github/copilot-instructions.md）
+ *   ④ Agent Instructions（AGENTS.md + CLAUDE.md + .github/copilot-instructions.md — 通过 Channel F 动态生成）
  *   ⑤ Constitution（AutoSnippet/constitution.yaml）
  *   ⑥ .gitignore（升级规则 + 清理旧版本残留）
  *   ⑦ Skills 路径迁移（.autosnippet/skills/ → AutoSnippet/skills/）
@@ -24,6 +24,7 @@ import {
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { safeCopyFile } from '../service/cursor/FileProtection.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -47,8 +48,7 @@ export class UpgradeService {
     }
     if (!skillsOnly && !mcpOnly) {
       results.push(this._upgradeCursorRules());
-      results.push(this._upgradeMirrorIDE('.qoder'));
-      results.push(this._upgradeMirrorIDE('.trae'));
+      // NOTE: .qoder/ .trae/ 不再自动镜像，用户可通过 `asd mirror` 按需同步
       results.push(this._upgradeSkillsTemplate());
       results.push(this._upgradeCopilotInstructions());
       results.push(this._upgradeConstitution());
@@ -169,6 +169,7 @@ export class UpgradeService {
 
   /**
    * 触发 Cursor Delivery Pipeline 动态生成
+   * 包含 Channel A-D + Channel F (AGENTS.md / CLAUDE.md / copilot-instructions)
    * 非阻塞 — 失败不影响 upgrade 流程
    */
   _triggerCursorDelivery() {
@@ -247,8 +248,13 @@ export class UpgradeService {
     }
   }
 
-  /* ═══ Copilot Instructions ══════════════════════════ */
+  /* ═══ Copilot Instructions (fallback static copy) ══════════════════ */
 
+  /**
+   * 静态模板回退 — 当 _triggerCursorDelivery() 无法运行时
+   * （无 DB 环境），至少保证有一份基础模板。
+   * Channel F 动态生成会覆盖此文件。
+   */
   _upgradeCopilotInstructions() {
     const src = join(REPO_ROOT, 'templates', 'copilot-instructions.md');
     if (!existsSync(src)) {
@@ -258,7 +264,10 @@ export class UpgradeService {
     const destDir = join(this.projectRoot, '.github');
     const dest = join(destDir, 'copilot-instructions.md');
     mkdirSync(destDir, { recursive: true });
-    copyFileSync(src, dest);
+    const { written } = safeCopyFile(src, dest);
+    if (!written) {
+      console.log('   ⏭️  copilot-instructions.md — 跳过（用户文件，非 AutoSnippet 生成）');
+    }
   }
 
   /* ═══ Constitution ══════════════════════════════════ */

package/lib/core/discovery/GenericDiscoverer.js

@@ -9,7 +9,7 @@
 
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, extname, join, relative } from 'node:path';
-import { inferLang } from '../../external/mcp/handlers/LanguageExtensions.js';
+import { LanguageService } from '../../shared/LanguageService.js';
 import { ProjectDiscoverer } from './ProjectDiscoverer.js';
 
 const EXCLUDE_DIRS = new Set([
@@ -33,31 +33,7 @@ const EXCLUDE_DIRS = new Set([
   '.cache',
 ]);
 
-const SOURCE_EXTENSIONS = new Set([
-  '.ts',
-  '.tsx',
-  '.js',
-  '.jsx',
-  '.mjs',
-  '.cjs',
-  '.py',
-  '.java',
-  '.kt',
-  '.kts',
-  '.swift',
-  '.m',
-  '.h',
-  '.mm',
-  '.go',
-  '.dart',
-  '.rs',
-  '.rb',
-  '.c',
-  '.cpp',
-  '.cs',
-  '.vue',
-  '.svelte',
-]);
+const SOURCE_EXTENSIONS = LanguageService.sourceExts;
 
 export class GenericDiscoverer extends ProjectDiscoverer {
   #projectRoot = null;
@@ -178,7 +154,7 @@ export class GenericDiscoverer extends ProjectDiscoverer {
         } else if (entry.isFile()) {
           const ext = extname(entry.name);
           if (SOURCE_EXTENSIONS.has(ext)) {
-            const lang = inferLang(entry.name) || 'unknown';
+            const lang = LanguageService.inferLang(entry.name) || 'unknown';
             stats[lang] = (stats[lang] || 0) + 1;
           }
         }
@@ -208,7 +184,7 @@ export class GenericDiscoverer extends ProjectDiscoverer {
         } else if (entry.isFile()) {
           const ext = extname(entry.name);
           if (SOURCE_EXTENSIONS.has(ext)) {
-            const lang = inferLang(entry.name) || 'unknown';
+            const lang = LanguageService.inferLang(entry.name) || 'unknown';
             files.push({
               name: entry.name,
               path: fullPath,

package/lib/external/mcp/handlers/bootstrap/base-dimensions.js

@@ -0,0 +1,246 @@
+/**
+ * Bootstrap 基础维度定义 + 维度条件化过滤
+ *
+ * 从 bootstrap.js 提取，包含 9+ 维度的完整定义（通用维度 + 语言条件维度）
+ */
+
+// ═══════════════════════════════════════════════════════════
+// 基础维度定义
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * 9+ 维度定义（Phase 4 响应 + Phase 5 候选创建共用）
+ * skillWorthy 维度会在 Phase 5.5 自动生成 Project Skill（宏观叙事性知识）
+ * 注意：anti-pattern 已移除 — 代码问题由 Guard 独立处理，bootstrap 不做错误检测
+ *
+ * 执行顺序优化（v5.1）：
+ *   ⑧ ⑨ 提前到 ⑥ 前面执行 → deep-scan / category-scan 的中间结果
+ *   通过 PipelineContext 缓存，供 project-profile 复用，避免重复扫描
+ */
+export const baseDimensions = [
+  // ── 通用维度（所有语言共享）──────────────────────────────────
+
+  // ① 代码规范（Dual: Skill + Candidate）
+  {
+    id: 'code-standard',
+    label: '代码规范',
+    guide:
+      '命名约定（类名前缀/方法签名风格/API 命名）、注释风格（语言/格式/MARK 分段）、文件组织规范',
+    knowledgeTypes: ['code-standard', 'code-style'],
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-code-standard',
+      description:
+        'Project coding standards and naming conventions (auto-generated by bootstrap)',
+    },
+  },
+  // ② 代码模式（Candidate）
+  {
+    id: 'code-pattern',
+    label: '设计模式与代码惯例',
+    guide: '单例/委托/Category·Extension/工厂/Builder/观察者/Coordinator 模式、继承关系',
+    knowledgeTypes: ['code-pattern', 'code-relation', 'inheritance'],
+  },
+  // ③ 架构模式（Dual: Skill + Candidate）
+  {
+    id: 'architecture',
+    label: '架构模式',
+    guide: '分层架构、模块职责与边界、依赖图、导入约束规则',
+    knowledgeTypes: ['architecture', 'module-dependency', 'boundary-constraint'],
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-architecture',
+      description:
+        'Project architecture layers, module boundaries and dependency graph (auto-generated by bootstrap)',
+    },
+  },
+  // ④ 最佳实践（Candidate）
+  {
+    id: 'best-practice',
+    label: '最佳实践',
+    guide: '错误处理、并发安全、内存管理、日志规范、测试模式',
+    knowledgeTypes: ['best-practice'],
+  },
+  // ⑤ 事件与数据流（Candidate）
+  {
+    id: 'event-and-data-flow',
+    label: '事件与数据流',
+    guide:
+      '事件传播（Delegate/Notification/Block·Closure/Target-Action）、数据状态管理（KVO/属性观察/响应式/持久化）',
+    knowledgeTypes: ['call-chain', 'data-flow'],
+  },
+  // ⑥ 项目特征（Dual: Skill + Candidate）
+  {
+    id: 'project-profile',
+    label: '项目特征',
+    guide:
+      '技术栈、目录结构、三方依赖枚举与用途、Extension/Category 分类聚合、自定义基类层级与全局定义（宏/typealias/PCH）、系统事件 hook 与生命周期入口、基础设施服务注册表、Runtime 与语言互操作',
+    knowledgeTypes: ['architecture'],
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-profile',
+      description:
+        'Project tech stack, module structure, third-party dependencies, base extensions/classes, event hooks, infrastructure services, and runtime/interop features (auto-generated by bootstrap)',
+    },
+  },
+  // ⑦ Agent 开发注意事项（Skill）
+  {
+    id: 'agent-guidelines',
+    label: 'Agent开发注意事项',
+    guide:
+      '三大核心原则（严谨性/深度特征挖掘/完整性）、命名强制、线程安全、内存约束、已废弃 API 标记、架构约束注释、TODO/FIXME',
+    knowledgeTypes: ['boundary-constraint', 'code-standard'],
+    skillWorthy: true,
+    skillMeta: {
+      name: 'project-agent-guidelines',
+      description:
+        'Mandatory coding rules, deprecated APIs and agent constraints for this project (auto-generated by bootstrap)',
+    },
+  },
+
+  // ── 语言条件维度（按 conditions 过滤）──────────────────────
+
+  // ⑧ ObjC/Swift 深度扫描
+  {
+    id: 'objc-deep-scan',
+    label: '深度扫描（常量/Hook）',
+    guide:
+      '全量扫描 #define 值宏/函数宏、extern/static 常量、Method Swizzling hook 对（Agent 必须使用项目常量，修改被 hook 方法前必须查阅 hook 清单）',
+    knowledgeTypes: ['code-standard', 'code-pattern'],
+    conditions: { languages: ['objectivec', 'swift'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-objc-deep-scan',
+      description:
+        'Project #define macros, static constants, and Method Swizzling hooks (auto-generated by bootstrap)',
+    },
+  },
+  // ⑨ Foundation/UIKit Category/Extension 专项扫描
+  {
+    id: 'category-scan',
+    label: '基础类分类方法扫描',
+    guide:
+      'Foundation/UIKit Category/Extension 逐方法清单（含完整实现代码与项目使用频次），仅扫描基础类分类、不含业务代码（Agent 遇到同等功能必须使用项目已有分类方法，禁止重复实现）',
+    knowledgeTypes: ['code-standard', 'code-pattern'],
+    conditions: { languages: ['objectivec', 'swift'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-category-scan',
+      description:
+        'Foundation/UIKit Category and Extension methods with implementations and usage patterns — base classes only, no business code (auto-generated by bootstrap)',
+    },
+  },
+
+  // ⑩ TS/JS 模块导出分析
+  {
+    id: 'module-export-scan',
+    label: '模块导出分析',
+    guide: 'barrel export 结构、re-export 链路、public API surface、tree-shaking 合规性',
+    knowledgeTypes: ['code-standard', 'architecture'],
+    conditions: { languages: ['typescript', 'javascript'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-module-exports',
+      description: 'Module export structure and public API surface (auto-generated by bootstrap)',
+    },
+  },
+  // ⑪ TS/JS 框架约定扫描
+  {
+    id: 'framework-convention-scan',
+    label: '框架约定扫描',
+    guide: '组件目录结构、状态管理约定、路由约定、样式约定、数据获取模式',
+    knowledgeTypes: ['code-standard', 'architecture'],
+    conditions: {
+      languages: ['typescript', 'javascript'],
+      frameworks: ['react', 'vue', 'angular', 'nextjs', 'nuxt'],
+    },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-framework-conventions',
+      description: 'Framework-specific conventions and patterns (auto-generated by bootstrap)',
+    },
+  },
+
+  // ⑫ Python 包结构分析
+  {
+    id: 'python-package-scan',
+    label: 'Python 包结构分析',
+    guide:
+      '__init__.py 导出策略、相对/绝对导入风格、type hints 覆盖率、decorator 使用模式、__all__ 定义',
+    knowledgeTypes: ['code-standard', 'architecture'],
+    conditions: { languages: ['python'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-python-structure',
+      description:
+        'Python package structure, import patterns and type hint coverage (auto-generated by bootstrap)',
+    },
+  },
+
+  // ⑬ Java/Kotlin 注解扫描
+  {
+    id: 'jvm-annotation-scan',
+    label: '注解/Annotation 扫描',
+    guide:
+      'DI 注解（@Inject/@Autowired/@Component）、ORM 注解（@Entity/@Table）、API 注解（@RestController/@RequestMapping）、自定义注解、元编程模式',
+    knowledgeTypes: ['code-pattern', 'architecture'],
+    conditions: { languages: ['java', 'kotlin'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-jvm-annotations',
+      description:
+        'Annotation/DI usage patterns and meta-programming (auto-generated by bootstrap)',
+    },
+  },
+
+  // ⑭ Go 模块结构分析
+  {
+    id: 'go-module-scan',
+    label: 'Go 模块结构分析',
+    guide:
+      'go.mod 依赖图、internal 包隔离边界、cmd/ 入口点枚举、build tags/constraints、interface 分布与实现关系、init() 函数清单',
+    knowledgeTypes: ['architecture', 'code-pattern'],
+    conditions: { languages: ['go'] },
+    skillWorthy: true,
+    dualOutput: true,
+    skillMeta: {
+      name: 'project-go-module-structure',
+      description:
+        'Go module structure, internal packages, build tags and interface distribution (auto-generated by bootstrap)',
+    },
+  },
+];
+
+// ═══════════════════════════════════════════════════════════
+// 维度条件化过滤
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * 根据项目主语言和检测到的框架过滤条件维度
+ * @param {Array} allDimensions  所有维度定义（含 conditions 字段）
+ * @param {string} primaryLang   主语言
+ * @param {string[]} detectedFrameworks 检测到的框架
+ * @returns {Array} 适用的维度列表
+ */
+export function resolveActiveDimensions(allDimensions, primaryLang, detectedFrameworks = []) {
+  return allDimensions.filter((dim) => {
+    if (!dim.conditions) {
+      return true; // 无条件 → 通用维度
+    }
+    const langMatch = !dim.conditions.languages || dim.conditions.languages.includes(primaryLang);
+    const fwMatch =
+      !dim.conditions.frameworks ||
+      dim.conditions.frameworks.some((f) => detectedFrameworks.includes(f));
+    // languages 必须匹配；frameworks 为可选增强（有 frameworks 条件时必须至少命中一个）
+    return langMatch && (dim.conditions.frameworks ? fwMatch : true);
+  });
+}

package/lib/external/mcp/handlers/bootstrap/pipeline/checkpoint.js

@@ -0,0 +1,80 @@
+/**
+ * checkpoint.js — Bootstrap 断点续传 (Checkpoint) 存储/恢复
+ *
+ * 在维度级粒度保存/加载/清理执行进度，支持意外中断后恢复。
+ *
+ * @module pipeline/checkpoint
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import Logger from '../../../../../infrastructure/logging/Logger.js';
+
+const logger = Logger.getInstance();
+
+const CHECKPOINT_TTL_MS = 3600_000; // 1小时内有效
+
+/**
+ * 保存维度级 checkpoint
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @param {string} dimId
+ * @param {object} result — 维度执行结果
+ * @param {object} [digest] — DimensionDigest
+ */
+export async function saveDimensionCheckpoint(projectRoot, sessionId, dimId, result, digest = null) {
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    await fs.mkdir(checkpointDir, { recursive: true });
+    await fs.writeFile(
+      path.join(checkpointDir, `${dimId}.json`),
+      JSON.stringify({ dimId, sessionId, ...result, digest, completedAt: Date.now() })
+    );
+  } catch (err) {
+    logger.warn(`[Bootstrap-v3] checkpoint save failed for "${dimId}": ${err.message}`);
+  }
+}
+
+/**
+ * 加载有效的 checkpoints
+ * @param {string} projectRoot
+ * @returns {Promise<Map<string, object>>} dimId → checkpoint data
+ */
+export async function loadCheckpoints(projectRoot) {
+  const checkpoints = new Map();
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    const files = await fs.readdir(checkpointDir).catch(() => []);
+    const now = Date.now();
+    for (const file of files) {
+      if (!file.endsWith('.json')) {
+        continue;
+      }
+      try {
+        const content = await fs.readFile(path.join(checkpointDir, file), 'utf-8');
+        const data = JSON.parse(content);
+        if (data.completedAt && now - data.completedAt < CHECKPOINT_TTL_MS) {
+          checkpoints.set(data.dimId, data);
+        }
+      } catch {
+        /* skip corrupt checkpoint */
+      }
+    }
+  } catch {
+    /* checkpoint dir doesn't exist */
+  }
+  return checkpoints;
+}
+
+/**
+ * 清理 checkpoint 目录
+ * @param {string} projectRoot
+ */
+export async function clearCheckpoints(projectRoot) {
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    await fs.rm(checkpointDir, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+}