autosnippet 2.9.0 → 2.10.0

package/lib/service/search/SearchEngine.js

@@ -15,6 +15,8 @@ const BM25_B = 0.75;
 
 /**
  * 分词: 中英文混合分词
+ * 英文: camelCase / PascalCase 拆分 + 小写化
+ * 中文: 单字 + 二元组（bigram）— 无需分词词典即可支持子串匹配
  */
 export function tokenize(text) {
   if (!text) return [];
@@ -23,7 +25,35 @@ export function tokenize(text) {
   // 拆全大写前缀：URLSession → URL Session, UITableView → UI Table View
   expanded = expanded.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
   const normalized = expanded.toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, ' ');
-  const tokens = normalized.split(/[\s_-]+/).filter(t => t.length >= 2);
+  const rawTokens = normalized.split(/[\s_-]+/).filter(t => t.length >= 1);
+
+  const tokens = [];
+  // CJK 正则（中日韩统一表意文字 + 扩展区）
+  const cjkRe = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/;
+
+  for (const raw of rawTokens) {
+    if (cjkRe.test(raw)) {
+      // 中文片段：提取所有 CJK 连续子串，生成单字 + bigram 覆盖
+      const cjkChars = raw.match(/[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]+/g) || [];
+      for (const seg of cjkChars) {
+        // 单字
+        for (const ch of seg) tokens.push(ch);
+        // bigram
+        for (let i = 0; i < seg.length - 1; i++) tokens.push(seg[i] + seg[i + 1]);
+        // 完整片段（≥3 字时额外保留，提升精确匹配权重）
+        if (seg.length >= 3) tokens.push(seg);
+      }
+      // 非 CJK 部分（英文/数字）也保留
+      const nonCjk = raw.replace(/[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]+/g, ' ').trim();
+      if (nonCjk) {
+        for (const t of nonCjk.split(/\s+/)) {
+          if (t.length >= 2) tokens.push(t);
+        }
+      }
+    } else if (raw.length >= 2) {
+      tokens.push(raw);
+    }
+  }
   return [...new Set(tokens)];
 }
 
@@ -126,13 +156,33 @@ export class SearchEngine {
     this._cache.clear();
 
     try {
-      // 索引 Recipes（统一模型，包含所有知识类型）
-      const recipes = this.db.prepare(
-        `SELECT id, title, description, language, category, knowledge_type, kind, content_json, status, tags_json, "trigger"
-         FROM recipes WHERE status != 'deprecated'`
-      ).all();
+      let entries = [];
+
+      // V3: 优先从 knowledge_entries 表索引
+      try {
+        entries = this.db.prepare(
+          `SELECT id, title, description, language, category, knowledge_type, kind,
+                  content AS content_json, lifecycle, tags AS tags_json, trigger_key
+           FROM knowledge_entries WHERE lifecycle != 'deprecated'`
+        ).all();
+        // 标准化字段名以便后续处理
+        entries = entries.map(e => ({
+          ...e,
+          trigger: e.trigger_key,
+          status: e.lifecycle,
+        }));
+      } catch {
+        // V3 表不存在，回退到 V2 recipes 表
+        try {
+          entries = this.db.prepare(
+            `SELECT id, title, description, language, category, knowledge_type, kind,
+                    content_json, status, tags_json, "trigger"
+             FROM recipes WHERE status != 'deprecated'`
+          ).all();
+        } catch { /* neither table exists */ }
+      }
 
-      for (const r of recipes) {
+      for (const r of entries) {
         let contentText = '';
         try {
           const content = JSON.parse(r.content_json || '{}');
@@ -143,12 +193,12 @@ export class SearchEngine {
         try { tagText = JSON.parse(r.tags_json || '[]').join(' '); } catch { /* ignore */ }
         const text = [r.title, r.description, r.trigger, r.language, r.category, r.knowledge_type, tagText, contentText]
           .filter(Boolean).join(' ');
-        this.scorer.addDocument(r.id, text, { type: 'recipe', title: r.title, trigger: r.trigger || '', status: r.status, knowledgeType: r.knowledge_type, kind: r.kind || 'pattern', language: r.language || '', category: r.category || '' });
+        this.scorer.addDocument(r.id, text, { type: 'knowledge', title: r.title, trigger: r.trigger || '', status: r.status, knowledgeType: r.knowledge_type, kind: r.kind || 'pattern', language: r.language || '', category: r.category || '' });
       }
 
       this._indexed = true;
       this.logger.info('Search index built', {
-        recipes: recipes.length,
+        entries: entries.length,
         total: this.scorer.totalDocs,
       });
     } catch (err) {
@@ -229,14 +279,26 @@ export class SearchEngine {
     const escaped = query.replace(/[%_\\]/g, ch => `\\${ch}`);
     const pattern = `%${escaped}%`;
 
-    if (type === 'all' || type === 'recipe' || type === 'rule' || type === 'solution') {
+    if (type === 'all' || type === 'recipe' || type === 'knowledge' || type === 'rule' || type === 'solution') {
       try {
-        const rows = this.db.prepare(
-          `SELECT id, title, description, language, category, knowledge_type, kind, status, content_json, dimensions_json, "trigger", 'recipe' as type
-           FROM recipes
-           WHERE status != 'deprecated' AND (title LIKE ? ESCAPE '\\' OR description LIKE ? ESCAPE '\\' OR "trigger" LIKE ? ESCAPE '\\' OR content_json LIKE ? ESCAPE '\\')
-           LIMIT ?`
-        ).all(pattern, pattern, pattern, pattern, limit);
+        let rows = [];
+        // V3: 优先 knowledge_entries
+        try {
+          rows = this.db.prepare(
+            `SELECT id, title, description, language, category, knowledge_type, kind, lifecycle as status, content AS content_json, trigger_key as "trigger", headers, module_name, 'knowledge' as type
+             FROM knowledge_entries
+             WHERE lifecycle != 'deprecated' AND (title LIKE ? ESCAPE '\\' OR description LIKE ? ESCAPE '\\' OR trigger_key LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\')
+             LIMIT ?`
+          ).all(pattern, pattern, pattern, pattern, limit);
+        } catch {
+          // V3 表不存在，回退到 V2
+          rows = this.db.prepare(
+            `SELECT id, title, description, language, category, knowledge_type, kind, status, content_json, dimensions_json, "trigger", 'recipe' as type
+             FROM recipes
+             WHERE status != 'deprecated' AND (title LIKE ? ESCAPE '\\' OR description LIKE ? ESCAPE '\\' OR "trigger" LIKE ? ESCAPE '\\' OR content_json LIKE ? ESCAPE '\\')
+             LIMIT ?`
+          ).all(pattern, pattern, pattern, pattern, limit);
+        }
         // 基础相关性排序：trigger 精确 > 标题匹配 > 描述匹配 > 内容匹配
         const lowerQ = query.toLowerCase();
         results.push(...rows.map(r => {
@@ -349,9 +411,17 @@ export class SearchEngine {
     try {
       const ids = items.map(it => it.id);
       const placeholders = ids.map(() => '?').join(',');
-      const rows = this.db.prepare(
-        `SELECT id, content_json, dimensions_json, description, "trigger" FROM recipes WHERE id IN (${placeholders})`
-      ).all(...ids);
+      let rows = [];
+      // V3: 优先 knowledge_entries
+      try {
+        rows = this.db.prepare(
+          `SELECT id, content AS content_json, description, trigger_key as "trigger", headers, module_name FROM knowledge_entries WHERE id IN (${placeholders})`
+        ).all(...ids);
+      } catch {
+        rows = this.db.prepare(
+          `SELECT id, content_json, dimensions_json, description, "trigger" FROM recipes WHERE id IN (${placeholders})`
+        ).all(...ids);
+      }
       const rowMap = new Map(rows.map(r => [r.id, r]));
       for (const item of items) {
         const row = rowMap.get(item.id);
@@ -360,6 +430,9 @@ export class SearchEngine {
           item.dimensions_json = row.dimensions_json || null;
           item.description = item.description || row.description || '';
           item.trigger = item.trigger || row.trigger || '';
+          // V3: headers & module_name 是独立列
+          if (row.headers) item.headers = row.headers;
+          if (row.module_name) item.module_name = row.module_name;
         }
       }
     } catch { /* DB may not be available */ }

package/lib/service/skills/SignalCollector.js

@@ -336,11 +336,16 @@ export class SignalCollector {
   #collectRecipeSignals() {
     try {
       if (!this.#db) return [];
+      // V3: knowledge_entries 统一表，统计字段在 stats/quality JSON 中
       const rows = this.#db.prepare(
         `SELECT id, title, knowledge_type, category, language,
-                adoption_count, application_count, success_count,
-                quality_overall, updated_at
-         FROM recipes ORDER BY updated_at DESC LIMIT 30`
+                json_extract(stats, '$.adoptions') as adoption_count,
+                json_extract(stats, '$.applications') as application_count,
+                json_extract(quality, '$.overall') as quality_overall,
+                updated_at
+         FROM knowledge_entries
+         WHERE lifecycle = 'active'
+         ORDER BY updated_at DESC LIMIT 30`
       ).all();
       return rows;
     } catch { return []; }
@@ -349,11 +354,11 @@ export class SignalCollector {
   #collectCandidateSignals() {
     try {
       if (!this.#db) return [];
+      // V3: candidates 已合并到 knowledge_entries，lifecycle='pending' 即为候选
       const rows = this.#db.prepare(
-        `SELECT id, source, status, language, category,
-                json_extract(metadata_json, '$.title') as title,
-                created_at
-         FROM candidates WHERE status = 'pending'
+        `SELECT id, source, lifecycle as status, language, category,
+                title, created_at
+         FROM knowledge_entries WHERE lifecycle = 'pending'
          ORDER BY created_at DESC LIMIT 30`
       ).all();
       return rows;

package/lib/service/skills/SkillAdvisor.js

@@ -202,8 +202,8 @@ export class SkillAdvisor {
       // 按 category 分布
       const categories = this.#db.prepare(`
         SELECT category, COUNT(*) as cnt
-        FROM recipes
-        WHERE category IS NOT NULL AND category != ''
+        FROM knowledge_entries
+        WHERE lifecycle = 'active' AND category IS NOT NULL AND category != ''
         GROUP BY category
         ORDER BY cnt DESC
       `).all();
@@ -211,8 +211,8 @@ export class SkillAdvisor {
       // 按 language 分布
       const languages = this.#db.prepare(`
         SELECT language, COUNT(*) as cnt
-        FROM recipes
-        WHERE language IS NOT NULL AND language != ''
+        FROM knowledge_entries
+        WHERE lifecycle = 'active' AND language IS NOT NULL AND language != ''
         GROUP BY language
         ORDER BY cnt DESC
       `).all();
@@ -231,14 +231,15 @@ export class SkillAdvisor {
         });
       }
 
-      // 高使用量 Recipe 统计（adoption_count + application_count >= 5）
+      // 高使用量 Recipe 统计（V3: stats JSON 中的 adoptions + applications）
       let hotRecipes = [];
       try {
         hotRecipes = this.#db.prepare(`
           SELECT title, category,
-                 (adoption_count + application_count) as total_usage
-          FROM recipes
-          WHERE (adoption_count + application_count) >= 5
+                 (COALESCE(json_extract(stats, '$.adoptions'), 0) + COALESCE(json_extract(stats, '$.applications'), 0)) as total_usage
+          FROM knowledge_entries
+          WHERE lifecycle = 'active'
+            AND (COALESCE(json_extract(stats, '$.adoptions'), 0) + COALESCE(json_extract(stats, '$.applications'), 0)) >= 5
           ORDER BY total_usage DESC
           LIMIT 10
         `).all();
@@ -262,12 +263,13 @@ export class SkillAdvisor {
     if (!this.#db) return { summary: 'DB 不可用', suggestions };
 
     try {
+      // V3: candidates 已合并到 knowledge_entries，ifecycle='pending' 即为候选
       const stats = this.#db.prepare(`
         SELECT
           COUNT(*) as total,
-          SUM(CASE WHEN status='pending' THEN 1 ELSE 0 END) as pending,
-          SUM(CASE WHEN status='rejected' THEN 1 ELSE 0 END) as rejected
-        FROM candidates
+          SUM(CASE WHEN lifecycle='pending' THEN 1 ELSE 0 END) as pending,
+          SUM(CASE WHEN lifecycle='deprecated' THEN 1 ELSE 0 END) as rejected
+        FROM knowledge_entries
       `).get();
 
       // 大量被拒绝 → 提示候选质量 Skill

package/lib/service/snippet/SnippetFactory.js

@@ -45,16 +45,16 @@ const SNIPPET_TEMPLATE = `<?xml version="1.0" encoding="UTF-8"?>
 
 export class SnippetFactory {
   /**
-   * @param {object} [recipeRepository] — RecipeRepositoryImpl (可选，用于列表查询)
+   * @param {object} [knowledgeRepository] — KnowledgeRepositoryImpl（可选，用于列表查询）
    */
-  constructor(recipeRepository) {
-    this._recipeRepo = recipeRepository || null;
+  constructor(knowledgeRepository) {
+    this._recipeRepo = knowledgeRepository || null;
   }
 
   /**
-   * 运行时注入 recipeRepository（用于延迟绑定场景）
+   * 运行时注入 knowledgeRepository（用于延迟绑定场景）
    */
-  setRecipeRepository(repo) {
+  setKnowledgeRepository(repo) {
     this._recipeRepo = repo;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "AutoSnippet - 连接开发者、AI 与项目知识库的工具",
   "type": "module",
   "main": "lib/bootstrap.js",

package/scripts/install-cursor-skill.js

@@ -22,7 +22,6 @@ const require = createRequire(import.meta.url);
 import fs from 'node:fs';
 import path from 'node:path';
 import * as defaults from '../lib/infrastructure/config/Defaults.js';
-import { RecipeStatsTracker } from '../lib/service/recipe/RecipeStatsTracker.js';
 
 const autoSnippetRoot = path.join(__dirname, '..');
 const skillsSource = path.join(autoSnippetRoot, 'skills');
@@ -156,11 +155,6 @@ function buildProjectRecipesContext(projectRoot) {
   if (!fs.existsSync(recipesDir)) return null;
   const mdFiles = collectMdFiles(recipesDir, recipesDir).sort();
   if (mdFiles.length === 0) return null;
-  let stats = { byFile: {} };
-  try {
-    const tracker = new RecipeStatsTracker(projectRoot);
-    stats = tracker.getStats();
-  } catch (_) {}
 
   const lines = [
     '# Project Recipes Index\n\n',

package/scripts/migrate-md-to-knowledge.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+/**
+ * migrate-md-to-knowledge.mjs — 将旧格式 .md 文件迁移为统一 Knowledge 格式
+ *
+ * 扫描 AutoSnippet/candidates/ 和 AutoSnippet/recipes/ 下的旧格式 .md 文件，
+ * 用旧 parser 解析 → 转换为 KnowledgeEntry → 用 KnowledgeFileWriter 重新序列化。
+ *
+ * 旧文件会备份到 AutoSnippet/_backup/{candidates|recipes}/ 目录下。
+ *
+ * 用法:
+ *   node scripts/migrate-md-to-knowledge.mjs [projectRoot]
+ *
+ *   --dry-run    只报告，不写入
+ *   --no-backup  不创建备份
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ── 解析命令行 ──
+const args = process.argv.slice(2);
+const dryRun   = args.includes('--dry-run');
+const noBackup = args.includes('--no-backup');
+const projectRoot = args.find(a => !a.startsWith('--')) || process.cwd();
+
+// ── 动态导入（兼容 ESM） ──
+const { parseRecipeMarkdown }    = await import('../lib/service/recipe/RecipeFileWriter.js');
+const { parseCandidateMarkdown } = await import('../lib/service/candidate/CandidateFileWriter.js');
+const { KnowledgeEntry }         = await import('../lib/domain/knowledge/KnowledgeEntry.js');
+const { KnowledgeFileWriter }    = await import('../lib/service/knowledge/KnowledgeFileWriter.js');
+const { Lifecycle }              = await import('../lib/domain/knowledge/Lifecycle.js');
+const { inferKind: inferKindV3 } = await import('../lib/domain/knowledge/Lifecycle.js');
+
+const RECIPES_DIR    = 'AutoSnippet/recipes';
+const CANDIDATES_DIR = 'AutoSnippet/candidates';
+const BACKUP_DIR     = 'AutoSnippet/_backup';
+
+const recipesDir    = path.join(projectRoot, RECIPES_DIR);
+const candidatesDir = path.join(projectRoot, CANDIDATES_DIR);
+const backupDir     = path.join(projectRoot, BACKUP_DIR);
+
+const report = {
+  recipes:    { total: 0, migrated: 0, skipped: 0, errors: [] },
+  candidates: { total: 0, migrated: 0, skipped: 0, errors: [] },
+};
+
+// ── 工具函数 ──
+
+function collectMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  const walk = (curDir, base) => {
+    for (const entry of fs.readdirSync(curDir, { withFileTypes: true })) {
+      const full = path.join(curDir, entry.name);
+      const rel  = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(full, rel);
+      } else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
+        results.push({ absPath: full, relPath: rel });
+      }
+    }
+  };
+  walk(dir, '');
+  return results;
+}
+
+function backupFile(absPath, type) {
+  if (noBackup || dryRun) return;
+  const rel = path.relative(
+    type === 'recipe' ? recipesDir : candidatesDir,
+    absPath
+  );
+  const dest = path.join(backupDir, type === 'recipe' ? 'recipes' : 'candidates', rel);
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(absPath, dest);
+}
+
+/**
+ * 判断文件是否已经是新格式（包含 lifecycle 和 _content 字段）
+ */
+function isAlreadyNewFormat(content) {
+  const fm = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return false;
+  return fm[1].includes('lifecycle:') && fm[1].includes('_content:');
+}
+
+// ═══ Recipe 迁移 ═══
+
+function migrateRecipe(absPath, relPath) {
+  const content = fs.readFileSync(absPath, 'utf8');
+
+  // 跳过已迁移的文件
+  if (isAlreadyNewFormat(content)) {
+    report.recipes.skipped++;
+    return;
+  }
+
+  const parsed = parseRecipeMarkdown(content, relPath);
+
+  // 映射旧 Recipe 字段 → KnowledgeEntry wire format
+  const statusMap = {
+    active:     Lifecycle.ACTIVE,
+    deprecated: Lifecycle.DEPRECATED,
+    draft:      Lifecycle.DRAFT,
+  };
+
+  // 提取旧 dimensions
+  const quality = parsed.quality || {};
+  const stats   = parsed.statistics || {};
+
+  const wireData = {
+    id:                  parsed.id,
+    title:               parsed.title,
+    trigger:             parsed.trigger || '',
+    description:         parsed.summaryCn || parsed.summaryEn || '',
+    lifecycle:           statusMap[parsed.status] || Lifecycle.ACTIVE,
+    lifecycle_history:   [],
+    probation:           false,
+    language:            parsed.language || 'swift',
+    category:            parsed.category || 'general',
+    kind:                parsed.kind || inferKindV3(parsed.knowledgeType || 'code-pattern'),
+    knowledge_type:      parsed.knowledgeType || 'code-pattern',
+    complexity:          parsed.complexity || 'intermediate',
+    scope:               parsed.scope || 'universal',
+    difficulty:          parsed.difficulty || null,
+    tags:                parsed.tags || [],
+    summary_cn:          parsed.summaryCn || '',
+    summary_en:          parsed.summaryEn || '',
+    usage_guide_cn:      parsed.usageGuideCn || '',
+    usage_guide_en:      parsed.usageGuideEn || '',
+    content:             {
+      pattern:   '',
+      markdown:  '',
+      rationale: '',
+      steps:     [],
+      code_changes: [],
+      verification: null,
+    },
+    relations:           parsed.relations || {},
+    constraints:         parsed.constraints || {},
+    reasoning:           {},
+    quality: {
+      completeness:  quality.codeCompleteness  ?? quality.completeness  ?? 0,
+      adaptation:    quality.projectAdaptation  ?? quality.adaptation    ?? 0,
+      documentation: quality.documentationClarity ?? quality.documentation ?? 0,
+      overall:       quality.overall ?? 0,
+      grade:         quality.grade   || 'F',
+    },
+    stats: {
+      views:        stats.viewCount        ?? stats.views        ?? 0,
+      adoptions:    stats.adoptionCount    ?? stats.adoptions    ?? 0,
+      applications: stats.applicationCount ?? stats.applications ?? 0,
+      guard_hits:   stats.guardHitCount    ?? stats.guard_hits   ?? 0,
+      search_hits:  stats.searchHits       ?? stats.search_hits  ?? 0,
+      authority:    parsed.authority        ?? stats.authority    ?? 0,
+    },
+    headers:             parsed.headers || [],
+    header_paths:        [],
+    module_name:         '',
+    include_headers:     false,
+    agent_notes:         null,
+    ai_insight:          null,
+    reviewed_by:         null,
+    reviewed_at:         null,
+    rejection_reason:    parsed.deprecationReason || null,
+    source:              'migration',
+    source_file:         `${RECIPES_DIR}/${relPath}`,
+    source_candidate_id: parsed.sourceCandidate || null,
+    created_by:          parsed.createdBy || 'system',
+    created_at:          parsed.createdAt || Math.floor(Date.now() / 1000),
+    updated_at:          parsed.updatedAt || Math.floor(Date.now() / 1000),
+    published_at:        parsed.publishedAt || null,
+    published_by:        parsed.publishedBy || null,
+  };
+
+  // 提取 body 内容到 content
+  const bodyMatch = content.match(/^---[\s\S]*?---\s*\r?\n([\s\S]*)$/);
+  if (bodyMatch) {
+    const body = bodyMatch[1].trim();
+    const codeMatch = body.match(/```\w*\n([\s\S]*?)```/);
+    if (codeMatch) {
+      wireData.content.pattern = codeMatch[1].trimEnd();
+    }
+    // 如果有完整 markdown 内容（项目特写）
+    if (body.includes('— 项目特写') || (body.length > 500 && body.startsWith('#'))) {
+      wireData.content.markdown = body;
+      wireData.content.pattern = '';
+    }
+  }
+
+  // 构建实体并重新序列化
+  const entry = KnowledgeEntry.fromJSON(wireData);
+  const writer = new KnowledgeFileWriter(projectRoot);
+  const newMarkdown = writer.serialize(entry);
+
+  if (!dryRun) {
+    backupFile(absPath, 'recipe');
+    fs.writeFileSync(absPath, newMarkdown, 'utf8');
+  }
+
+  report.recipes.migrated++;
+}
+
+// ═══ Candidate 迁移 ═══
+
+function migrateCandidate(absPath, relPath) {
+  const content = fs.readFileSync(absPath, 'utf8');
+
+  // 跳过已迁移的文件
+  if (isAlreadyNewFormat(content)) {
+    report.candidates.skipped++;
+    return;
+  }
+
+  const parsed = parseCandidateMarkdown(content, relPath);
+
+  // 映射旧 Candidate 状态 → lifecycle
+  const statusMap = {
+    pending:  Lifecycle.PENDING,
+    approved: Lifecycle.APPROVED,
+    rejected: Lifecycle.REJECTED,
+    applied:  Lifecycle.ACTIVE,
+    draft:    Lifecycle.DRAFT,
+  };
+
+  const meta      = parsed._metadata || {};
+  const reasoning = parsed._reasoning || {};
+  const code      = parsed._bodyCode || '';
+
+  // 判断内容类型
+  const isMarkdown = code && (
+    code.includes('— 项目特写') || /^#{1,3}\s/.test(code.trimStart())
+  );
+
+  const wireData = {
+    id:                  parsed.id,
+    title:               meta.title || meta.description || (code ? code.substring(0, 60) : ''),
+    trigger:             meta.trigger || '',
+    description:         meta.description || '',
+    lifecycle:           statusMap[parsed.status] || Lifecycle.PENDING,
+    lifecycle_history:   parsed._statusHistory || [],
+    probation:           false,
+    language:            parsed.language || 'swift',
+    category:            meta.category || parsed.category || 'general',
+    kind:                inferKindV3(meta.knowledgeType || 'code-pattern'),
+    knowledge_type:      meta.knowledgeType || 'code-pattern',
+    complexity:          meta.complexity || 'intermediate',
+    scope:               meta.scope || 'universal',
+    difficulty:          meta.difficulty || null,
+    tags:                meta.tags || [],
+    summary_cn:          meta.summary || meta.summary_cn || '',
+    summary_en:          meta.summary_en || '',
+    usage_guide_cn:      meta.usageGuide || meta.usageGuide_cn || '',
+    usage_guide_en:      meta.usageGuide_en || '',
+    content: {
+      pattern:      isMarkdown ? '' : code,
+      markdown:     isMarkdown ? code : '',
+      rationale:    meta.rationale || (typeof reasoning === 'object' ? reasoning.whyStandard : '') || '',
+      steps:        meta.steps || [],
+      code_changes: meta.codeChanges || [],
+      verification: meta.verification || null,
+    },
+    relations: Array.isArray(meta.relations)
+      ? { related: meta.relations.map(r => typeof r === 'string' ? { target: r, description: '' } : r) }
+      : (meta.relations || {}),
+    constraints:         meta.constraints || {},
+    reasoning: {
+      why_standard:    (typeof reasoning === 'object' ? reasoning.whyStandard : '') || '',
+      sources:         (typeof reasoning === 'object' ? reasoning.sources : []) || [],
+      confidence:      (typeof reasoning === 'object' ? reasoning.confidence : 0.7) ?? 0.7,
+      quality_signals: (typeof reasoning === 'object' ? reasoning.qualitySignals : {}) || {},
+      alternatives:    (typeof reasoning === 'object' ? reasoning.alternatives : []) || [],
+    },
+    quality:             meta.quality || {},
+    stats:               {},
+    headers:             meta.headers || [],
+    header_paths:        [],
+    module_name:         '',
+    include_headers:     false,
+    agent_notes:         null,
+    ai_insight:          null,
+    reviewed_by:         parsed.approvedBy || parsed.rejectedBy || null,
+    reviewed_at:         parsed.approvedAt || null,
+    rejection_reason:    parsed.rejectionReason || null,
+    source:              parsed.source || 'migration',
+    source_file:         `${CANDIDATES_DIR}/${relPath}`,
+    source_candidate_id: null,
+    created_by:          parsed.createdBy || 'system',
+    created_at:          parsed.createdAt || Math.floor(Date.now() / 1000),
+    updated_at:          parsed.updatedAt || Math.floor(Date.now() / 1000),
+    published_at:        null,
+    published_by:        null,
+  };
+
+  // 构建实体并重新序列化
+  const entry = KnowledgeEntry.fromJSON(wireData);
+  const writer = new KnowledgeFileWriter(projectRoot);
+  const newMarkdown = writer.serialize(entry);
+
+  if (!dryRun) {
+    backupFile(absPath, 'candidate');
+    fs.writeFileSync(absPath, newMarkdown, 'utf8');
+  }
+
+  report.candidates.migrated++;
+}
+
+// ═══ 主流程 ═══
+
+console.log(`\n🔄 Knowledge .md Migration`);
+console.log(`  Project: ${projectRoot}`);
+console.log(`  Mode: ${dryRun ? 'DRY RUN' : 'LIVE'}`);
+console.log(`  Backup: ${noBackup ? 'disabled' : 'enabled'}`);
+console.log('');
+
+// ── 迁移 Recipes ──
+const recipeFiles = collectMdFiles(recipesDir);
+report.recipes.total = recipeFiles.length;
+console.log(`📦 Recipes: ${recipeFiles.length} files found`);
+
+for (const { absPath, relPath } of recipeFiles) {
+  try {
+    migrateRecipe(absPath, relPath);
+  } catch (err) {
+    report.recipes.errors.push({ file: relPath, error: err.message });
+    console.error(`  ❌ ${relPath}: ${err.message}`);
+  }
+}
+
+// ── 迁移 Candidates ──
+const candidateFiles = collectMdFiles(candidatesDir);
+report.candidates.total = candidateFiles.length;
+console.log(`📦 Candidates: ${candidateFiles.length} files found`);
+
+for (const { absPath, relPath } of candidateFiles) {
+  try {
+    migrateCandidate(absPath, relPath);
+  } catch (err) {
+    report.candidates.errors.push({ file: relPath, error: err.message });
+    console.error(`  ❌ ${relPath}: ${err.message}`);
+  }
+}
+
+// ── 报告 ──
+console.log('\n═══ Migration Report ═══');
+console.log(`  Recipes:    ${report.recipes.migrated}/${report.recipes.total} migrated, ${report.recipes.skipped} already new format, ${report.recipes.errors.length} errors`);
+console.log(`  Candidates: ${report.candidates.migrated}/${report.candidates.total} migrated, ${report.candidates.skipped} already new format, ${report.candidates.errors.length} errors`);
+
+if (!noBackup && !dryRun) {
+  console.log(`\n  Backups saved to: ${backupDir}`);
+}
+
+if (report.recipes.errors.length + report.candidates.errors.length > 0) {
+  console.log('\n  Errors:');
+  for (const e of [...report.recipes.errors, ...report.candidates.errors]) {
+    console.log(`    - ${e.file}: ${e.error}`);
+  }
+}
+
+console.log('');