autosnippet 3.3.4 → 3.3.6

package/dist/lib/service/cleanup/CleanupService.js

@@ -0,0 +1,324 @@
+/**
+ * CleanupService — 统一数据清理策略
+ *
+ * 提供两种清理模式:
+ *   - fullReset(): 全量清理（删除一切知识/缓存/衍生数据），用于 bootstrap 冷启动
+ *   - rescanClean(): Rescan 清理（保留 Recipe，清除衍生缓存），用于增量知识更新
+ *   - snapshotRecipes(): 快照当前活跃 Recipe 信息
+ *
+ * 设计原则:
+ *   - 配置数据 (config.json, constitution.yaml, boxspec.json) 永不清理
+ *   - IDE 集成配置 (.vscode/, .cursor/, .github/) 永不清理
+ *   - 交付物 (.cursor/rules/autosnippet-*) 由 R4 重建，不在此清理
+ *
+ * @module service/cleanup/CleanupService
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CANDIDATES_DIR } from '#infra/config/Defaults.js';
+import { getContextIndexPath, getProjectKnowledgePath, getProjectRecipesPath, getProjectSkillsPath, } from '#infra/config/Paths.js';
+// ── 常量 ────────────────────────────────────────────────────
+/** fullReset 时清除的所有 DB 表（不含 schema_migrations） */
+const ALL_DATA_TABLES = [
+    'knowledge_entries',
+    'knowledge_edges',
+    'guard_violations',
+    'audit_logs',
+    'sessions',
+    'token_usage',
+    'semantic_memories',
+    'bootstrap_snapshots',
+    'bootstrap_dim_files',
+    'code_entities',
+    'remote_commands',
+    'remote_state',
+    'evolution_proposals',
+    'recipe_source_refs',
+];
+/** rescanClean 时清除的 DB 表（保留知识/进化相关表） */
+const RESCAN_CLEAN_TABLES = [
+    'code_entities',
+    'guard_violations',
+    'bootstrap_snapshots',
+    'bootstrap_dim_files',
+    'semantic_memories',
+    'sessions',
+    'audit_logs',
+    'token_usage',
+    'remote_commands',
+    'remote_state',
+    'recipe_source_refs',
+];
+// ── CleanupService ──────────────────────────────────────────
+export class CleanupService {
+    #projectRoot;
+    #logger;
+    #db;
+    constructor(opts) {
+        this.#projectRoot = opts.projectRoot;
+        this.#logger = opts.logger || { info() { }, warn() { } };
+        this.#db = opts.db
+            ? typeof opts.db?.getDb === 'function'
+                ? opts.db.getDb()
+                : opts.db
+            : null;
+    }
+    /** 更新 DB 引用（fullReset 后重连时调用） */
+    setDb(db) {
+        this.#db = db
+            ? typeof db?.getDb === 'function'
+                ? db.getDb()
+                : db
+            : null;
+    }
+    // ─── 需求 A：全量清理（删除一切） ─────────────────────
+    /**
+     * 全量清理 — 用于 bootstrap 冷启动
+     *
+     * 清除: DB 所有数据表、candidates/、recipes/、skills/、wiki/、
+     *       向量索引、bootstrap-report.json、logs/signals/
+     * 保留: config.json、constitution.yaml、boxspec.json、IDE 配置
+     */
+    async fullReset() {
+        const result = {
+            deletedFiles: 0,
+            clearedTables: [],
+            preservedRecipes: 0,
+            errors: [],
+        };
+        this.#logger.info('[CleanupService] Starting fullReset...');
+        // 1. 清除 DB 所有数据表
+        if (this.#db) {
+            for (const table of ALL_DATA_TABLES) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // 表可能不存在（未 migrate），跳过
+                    if (!msg.includes('no such table')) {
+                        result.errors.push(`Failed to clear ${table}: ${msg}`);
+                    }
+                }
+            }
+            // 也清除 tasks 相关表（来自 migration 002）
+            for (const table of ['tasks', 'task_dependencies', 'task_events']) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch {
+                    /* table may not exist */
+                }
+            }
+        }
+        // 2. 清空 candidates/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(this.#projectRoot, CANDIDATES_DIR));
+        // 3. 清空 recipes/ 目录
+        result.deletedFiles += this.#clearDirectory(getProjectRecipesPath(this.#projectRoot));
+        // 4. 清空 skills/ 目录
+        result.deletedFiles += this.#clearDirectory(getProjectSkillsPath(this.#projectRoot));
+        // 5. 清空 wiki/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(getProjectKnowledgePath(this.#projectRoot), 'wiki'));
+        // 6. 删除向量索引
+        result.deletedFiles += this.#clearDirectory(getContextIndexPath(this.#projectRoot));
+        // 7. 删除 bootstrap-report.json
+        result.deletedFiles += this.#deleteFile(path.join(getProjectKnowledgePath(this.#projectRoot), '.autosnippet', 'bootstrap-report.json'));
+        // 8. 清除 logs/signals/
+        result.deletedFiles += this.#clearDirectory(path.join(getProjectKnowledgePath(this.#projectRoot), '.autosnippet', 'logs', 'signals'));
+        this.#logger.info('[CleanupService] fullReset complete', {
+            tables: result.clearedTables.length,
+            files: result.deletedFiles,
+            errors: result.errors.length,
+        });
+        return result;
+    }
+    // ─── 需求 B：Rescan 清理（保留 Recipe） ───────────────
+    /**
+     * Rescan 清理 — 保留 Recipe，清除衍生缓存
+     *
+     * 清除: 衍生 DB 表、pending/rejected/deprecated 知识条目、
+     *       candidates/、skills/、wiki/、向量索引、bootstrap-report
+     * 保留: recipes/、active/published/staging/evolving 知识条目、
+     *       knowledge_edges、evolution_proposals
+     */
+    async rescanClean() {
+        const result = {
+            deletedFiles: 0,
+            clearedTables: [],
+            preservedRecipes: 0,
+            errors: [],
+        };
+        this.#logger.info('[CleanupService] Starting rescanClean...');
+        // 1. 清除衍生 DB 表
+        if (this.#db) {
+            for (const table of RESCAN_CLEAN_TABLES) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (!msg.includes('no such table')) {
+                        result.errors.push(`Failed to clear ${table}: ${msg}`);
+                    }
+                }
+            }
+            // 清除旧候选/废弃条目，保留活跃知识
+            try {
+                this.#db.exec(`DELETE FROM knowledge_entries WHERE lifecycle IN ('pending', 'rejected', 'deprecated')`);
+                result.clearedTables.push('knowledge_entries (pending/rejected/deprecated)');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                result.errors.push(`Failed to clean old entries: ${msg}`);
+            }
+            // 也清除 tasks 相关表
+            for (const table of ['tasks', 'task_dependencies', 'task_events']) {
+                try {
+                    this.#db.exec(`DELETE FROM ${table}`);
+                    result.clearedTables.push(table);
+                }
+                catch {
+                    /* table may not exist */
+                }
+            }
+        }
+        // 2. 清空 candidates/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(this.#projectRoot, CANDIDATES_DIR));
+        // 3. 清空 skills/ 目录
+        result.deletedFiles += this.#clearDirectory(getProjectSkillsPath(this.#projectRoot));
+        // 4. 清空 wiki/ 目录
+        result.deletedFiles += this.#clearDirectory(path.join(getProjectKnowledgePath(this.#projectRoot), 'wiki'));
+        // 5. 删除向量索引
+        result.deletedFiles += this.#clearDirectory(getContextIndexPath(this.#projectRoot));
+        // 6. 删除 bootstrap-report.json
+        result.deletedFiles += this.#deleteFile(path.join(getProjectKnowledgePath(this.#projectRoot), '.autosnippet', 'bootstrap-report.json'));
+        this.#logger.info('[CleanupService] rescanClean complete', {
+            tables: result.clearedTables.length,
+            files: result.deletedFiles,
+            errors: result.errors.length,
+        });
+        return result;
+    }
+    // ─── 快照当前 Recipe ──────────────────────────────────
+    /**
+     * 快照当前活跃 Recipe 信息
+     * 用于 rescan 前记录保留的知识条目
+     */
+    async snapshotRecipes() {
+        if (!this.#db) {
+            return { count: 0, entries: [], coverageByDimension: {} };
+        }
+        try {
+            const rows = this.#db
+                .prepare(`SELECT id, title, trigger, category, knowledgeType, doClause,
+                  sourceFile, lifecycle, content, json_extract(reasoning, '$.sources') AS sourceRefsJson
+           FROM knowledge_entries
+           WHERE lifecycle IN ('active', 'staging', 'evolving')`)
+                .all();
+            const entries = rows.map((r) => {
+                let parsedContent;
+                try {
+                    parsedContent = r.content
+                        ? JSON.parse(r.content)
+                        : undefined;
+                }
+                catch {
+                    parsedContent = undefined;
+                }
+                let parsedSourceRefs;
+                try {
+                    parsedSourceRefs = r.sourceRefsJson
+                        ? JSON.parse(r.sourceRefsJson)
+                        : undefined;
+                }
+                catch {
+                    parsedSourceRefs = undefined;
+                }
+                return {
+                    id: r.id,
+                    title: r.title || '',
+                    trigger: r.trigger || '',
+                    category: r.category || '',
+                    knowledgeType: r.knowledgeType || 'code-pattern',
+                    doClause: r.doClause || '',
+                    sourceFile: r.sourceFile || undefined,
+                    lifecycle: r.lifecycle,
+                    content: parsedContent,
+                    sourceRefs: parsedSourceRefs,
+                };
+            });
+            // 按维度统计覆盖度 (使用 knowledgeType = 维度 id)
+            const coverageByDimension = {};
+            for (const entry of entries) {
+                const dim = entry.knowledgeType || 'unknown';
+                coverageByDimension[dim] = (coverageByDimension[dim] || 0) + 1;
+            }
+            return {
+                count: entries.length,
+                entries,
+                coverageByDimension,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] snapshotRecipes failed: ${msg}`);
+            return { count: 0, entries: [], coverageByDimension: {} };
+        }
+    }
+    // ─── 内部工具方法 ─────────────────────────────────────
+    /**
+     * 清空目录内容（保留目录本身）
+     * @returns 删除的文件数
+     */
+    #clearDirectory(dirPath) {
+        let count = 0;
+        try {
+            if (!fs.existsSync(dirPath)) {
+                return 0;
+            }
+            const entries = fs.readdirSync(dirPath);
+            for (const entry of entries) {
+                const fullPath = path.join(dirPath, entry);
+                try {
+                    const stat = fs.statSync(fullPath);
+                    if (stat.isDirectory()) {
+                        fs.rmSync(fullPath, { recursive: true });
+                    }
+                    else {
+                        fs.unlinkSync(fullPath);
+                    }
+                    count++;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.#logger.warn(`[CleanupService] Failed to delete ${entry}: ${msg}`);
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] clearDirectory failed for ${dirPath}: ${msg}`);
+        }
+        return count;
+    }
+    /**
+     * 删除单个文件
+     * @returns 1 if deleted, 0 otherwise
+     */
+    #deleteFile(filePath) {
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                return 1;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.#logger.warn(`[CleanupService] Failed to delete file ${filePath}: ${msg}`);
+        }
+        return 0;
+    }
+}

package/dist/lib/service/delivery/AgentInstructionsGenerator.js

@@ -15,7 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { TEMPLATES_DIR } from '../../shared/package-root.js';
-import { checkWriteSafety, safeWriteFile } from './FileProtection.js';
+import { mergeSection } from './FileProtection.js';
 import { estimateTokens } from './TokenBudget.js';
 /**
  * Agent 指令文件 token 预算
@@ -49,6 +49,14 @@ const MCP_TOOLS_SUMMARY = [
     { name: 'autosnippet_graph', desc: 'Knowledge graph query (query/impact/path/stats)' },
     { name: 'autosnippet_skill', desc: 'Skill management (list/load/create/update/delete)' },
     { name: 'autosnippet_bootstrap', desc: 'Project cold-start & scan' },
+    {
+        name: 'autosnippet_rescan',
+        desc: 'Incremental rescan: preserves Recipes, cleans caches, re-analyzes project, runs relevance audit',
+    },
+    {
+        name: 'autosnippet_evolve',
+        desc: 'Batch Recipe evolution decisions (propose_evolution/confirm_deprecation/skip), used per-dimension during rescan or standalone',
+    },
     {
         name: 'autosnippet_panorama',
         desc: 'Project panorama (operation: overview/module/gaps/health)',
@@ -95,8 +103,8 @@ export class AgentInstructionsGenerator {
         const filesWritten = allResults.filter((r) => !r.skipped).length;
         const skippedFiles = allResults.filter((r) => r.skipped);
         if (skippedFiles.length > 0) {
-            this.logger.info?.(`[AgentInstructions] Skipped ${skippedFiles.length} file(s) — ` +
-                `user-owned files will not be overwritten: ${skippedFiles.map((f) => f.filePath).join(', ')}`);
+            this.logger.info?.(`[AgentInstructions] Skipped ${skippedFiles.length} file(s): ` +
+                skippedFiles.map((f) => f.filePath).join(', '));
         }
         this.logger.info?.(`[AgentInstructions] Generated ${filesWritten} files in ${duration}ms — ` +
             `AGENTS.md: ${agents.tokensUsed}t, CLAUDE.md: ${claude.tokensUsed}t, ` +
@@ -159,7 +167,8 @@ export class AgentInstructionsGenerator {
     }
     // ─── AGENTS.md ─────────────────────────────────────
     _writeAgentsMd(sections) {
-        const lines = [
+        // 文件头部（仅用于新建/旧版重写场景）
+        const header = [
             `# ${this.projectName} — Agent Instructions`,
             '',
             '> Auto-generated by [AutoSnippet](https://github.com/GxFn/AutoSnippet). Do not edit manually.',
@@ -167,31 +176,28 @@ export class AgentInstructionsGenerator {
             'This project uses **AutoSnippet** for knowledge management.',
             'Access the knowledge base through MCP tools.',
             '',
-        ];
-        // Coding Standards
+        ].join('\n');
+        // 动态区段内容（始终在 markers 内管理）
+        const sectionLines = [];
         if (sections.ruleLines.length > 0) {
-            lines.push('## Coding Standards', '', ...sections.ruleLines, '');
+            sectionLines.push('## Coding Standards', '', ...sections.ruleLines, '');
         }
-        // Architecture Patterns
         if (sections.patternRows.length > 0) {
-            lines.push('## Architecture Patterns', '', '| Trigger | When | Do |', '|---------|------|----|', ...sections.patternRows, '');
+            sectionLines.push('## Architecture Patterns', '', '| Trigger | When | Do |', '|---------|------|----|', ...sections.patternRows, '');
         }
-        // MCP Tools
-        lines.push('## MCP Tools', '', ...sections.toolLines, '');
-        // Skills
+        sectionLines.push('## MCP Tools', '', ...sections.toolLines, '');
         if (sections.skillLines.length > 0) {
-            lines.push('## Skills', '', 'Load with `autosnippet_skill({ operation: "load", name: "<skill>" })`:', '', ...sections.skillLines, '');
+            sectionLines.push('## Skills', '', 'Load with `autosnippet_skill({ operation: "load", name: "<skill>" })`:', '', ...sections.skillLines, '');
         }
-        // Constraints
-        lines.push('## Constraints', '', '1. Do NOT modify knowledge base files directly (`AutoSnippet/recipes/`, `.autosnippet/`).', '2. Prefer Recipes as project standards; source code is supplementary.', '3. Create or update knowledge only through MCP tools.', '');
-        const content = `${lines.join('\n')}\n`;
+        sectionLines.push('## Constraints', '', '1. Do NOT modify knowledge base files directly (`AutoSnippet/recipes/`, `.autosnippet/`).', '2. Prefer Recipes as project standards; source code is supplementary.', '3. Create or update knowledge only through MCP tools.', '');
+        const sectionContent = sectionLines.join('\n');
         const filePath = path.join(this.projectRoot, 'AGENTS.md');
-        const result = safeWriteFile(filePath, content, { logger: this.logger });
-        return { filePath, tokensUsed: estimateTokens(content), skipped: !result.written };
+        const result = mergeSection(filePath, sectionContent, { header, logger: this.logger });
+        return { filePath, tokensUsed: estimateTokens(sectionContent), skipped: !result.written };
     }
     // ─── CLAUDE.md ─────────────────────────────────────
     _writeClaudeMd(sections) {
-        const lines = [
+        const header = [
             `# ${this.projectName} — Claude Code Instructions`,
             '',
             '> Auto-generated by AutoSnippet. Regenerated when knowledge base changes.',
@@ -199,27 +205,23 @@ export class AgentInstructionsGenerator {
             'This project uses **AutoSnippet** for knowledge management.',
             'Access the knowledge base through MCP tools.',
             '',
-        ];
-        // Coding Standards
+        ].join('\n');
+        const sectionLines = [];
         if (sections.ruleLines.length > 0) {
-            lines.push('## Coding Standards', '', ...sections.ruleLines, '');
+            sectionLines.push('## Coding Standards', '', ...sections.ruleLines, '');
         }
-        // Patterns
         if (sections.patternRows.length > 0) {
-            lines.push('## Key Patterns', '', '| Trigger | When | Do |', '|---------|------|----|', ...sections.patternRows, '');
+            sectionLines.push('## Key Patterns', '', '| Trigger | When | Do |', '|---------|------|----|', ...sections.patternRows, '');
         }
-        // MCP — Claude Code natively supports MCP
-        lines.push('## MCP Tools', '', ...sections.toolLines, '');
-        // Skills
+        sectionLines.push('## MCP Tools', '', ...sections.toolLines, '');
         if (sections.skillLines.length > 0) {
-            lines.push('## Skills', '', ...sections.skillLines, '');
+            sectionLines.push('## Skills', '', ...sections.skillLines, '');
         }
-        // Constraints
-        lines.push('', '## Constraints', '', '1. Do NOT modify knowledge base files directly (`AutoSnippet/recipes/`, `.autosnippet/`).', '2. Prefer Recipes as project standards; source code is supplementary.', '3. Create or update knowledge only through MCP tools.', '');
-        const content = `${lines.join('\n')}\n`;
+        sectionLines.push('', '## Constraints', '', '1. Do NOT modify knowledge base files directly (`AutoSnippet/recipes/`, `.autosnippet/`).', '2. Prefer Recipes as project standards; source code is supplementary.', '3. Create or update knowledge only through MCP tools.', '');
+        const sectionContent = sectionLines.join('\n');
         const filePath = path.join(this.projectRoot, 'CLAUDE.md');
-        const result = safeWriteFile(filePath, content, { logger: this.logger });
-        return { filePath, tokensUsed: estimateTokens(content), skipped: !result.written };
+        const result = mergeSection(filePath, sectionContent, { header, logger: this.logger });
+        return { filePath, tokensUsed: estimateTokens(sectionContent), skipped: !result.written };
     }
     // ─── copilot-instructions.md ───────────────────────
     /**
@@ -228,7 +230,7 @@ export class AgentInstructionsGenerator {
      */
     _writeCopilotInstructions(_sections) {
         const body = this._loadConventionsTemplate();
-        const content = [
+        const section = [
             '<!-- autosnippet:begin -->',
             '',
             '# AutoSnippet Conventions',
@@ -236,16 +238,10 @@ export class AgentInstructionsGenerator {
             body,
             '',
             '<!-- autosnippet:end -->',
-            '',
         ].join('\n');
-        const destDir = path.join(this.projectRoot, '.github');
-        const filePath = path.join(destDir, 'copilot-instructions.md');
-        const { canWrite } = checkWriteSafety(filePath);
-        if (canWrite) {
-            fs.mkdirSync(destDir, { recursive: true });
-        }
-        const result = safeWriteFile(filePath, content, { logger: this.logger });
-        return { filePath, tokensUsed: estimateTokens(content), skipped: !result.written };
+        const filePath = path.join(this.projectRoot, '.github', 'copilot-instructions.md');
+        const result = mergeSection(filePath, section, { logger: this.logger });
+        return { filePath, tokensUsed: estimateTokens(section), skipped: !result.written };
     }
     // ─── 模板读取 ──────────────────────────────────────
     /**

package/dist/lib/service/delivery/FileProtection.d.ts

@@ -61,3 +61,23 @@ export declare function safeCopyFile(srcPath: string, destPath: string, options?
     reason: string;
     filePath: string;
 };
+export type MergeStrategy = 'create' | 'replace-section' | 'rewrite-legacy' | 'append-section';
+/**
+ * 智能合并 AutoSnippet 管理区段到目标文件
+ *
+ * 四种场景：
+ *   1. 文件不存在          → 创建完整文件（header + markers）
+ *   2. 文件有 begin/end 标记 → 仅替换标记区段（增量更新）
+ *   3. 文件有旧版 AutoSnippet 签名但无标记 → 全量重写并加标记（旧版迁移）
+ *   4. 文件无签名无标记（用户文件）→ 追加标记区段到末尾（共存）
+ */
+export declare function mergeSection(filePath: string, section: string, options?: {
+    header?: string;
+    logger?: {
+        info?: (...args: unknown[]) => void;
+    };
+}): {
+    written: boolean;
+    strategy: MergeStrategy;
+    filePath: string;
+};

package/dist/lib/service/delivery/FileProtection.js

@@ -12,6 +12,7 @@
  *   - "auto-generated by autosnippet" (case-insensitive)
  */
 import fs from 'node:fs';
+import path from 'node:path';
 /**
  * AutoSnippet 文件签名模式（case-insensitive）
  * 检查文件前 1024 字节即可——签名总在文件头部
@@ -96,3 +97,56 @@ export function safeCopyFile(srcPath, destPath, options = {}) {
     logger?.info?.(`[FileProtection] Skipped "${destPath}" — ${reason} (file exists and is not AutoSnippet-generated)`);
     return { written: false, reason, filePath: destPath };
 }
+// ─── Section Merge ──────────────────────────────────
+const SECTION_BEGIN = '<!-- autosnippet:begin -->';
+const SECTION_END = '<!-- autosnippet:end -->';
+const SECTION_PATTERN = /<!-- autosnippet:begin -->[\s\S]*?<!-- autosnippet:end -->/;
+/**
+ * 智能合并 AutoSnippet 管理区段到目标文件
+ *
+ * 四种场景：
+ *   1. 文件不存在          → 创建完整文件（header + markers）
+ *   2. 文件有 begin/end 标记 → 仅替换标记区段（增量更新）
+ *   3. 文件有旧版 AutoSnippet 签名但无标记 → 全量重写并加标记（旧版迁移）
+ *   4. 文件无签名无标记（用户文件）→ 追加标记区段到末尾（共存）
+ */
+export function mergeSection(filePath, section, options = {}) {
+    const { header = '', logger } = options;
+    const fileName = path.basename(filePath);
+    // 确保 section 包含 begin/end 标记
+    const wrappedSection = section.includes(SECTION_BEGIN)
+        ? section
+        : `${SECTION_BEGIN}\n\n${section}\n${SECTION_END}`;
+    // Case 1: 文件不存在 → 创建完整文件
+    if (!fs.existsSync(filePath)) {
+        const content = header ? `${header}\n${wrappedSection}\n` : `${wrappedSection}\n`;
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf8');
+        logger?.info?.(`[FileProtection] Created "${fileName}" (new file)`);
+        return { written: true, strategy: 'create', filePath };
+    }
+    const existing = fs.readFileSync(filePath, 'utf8');
+    // Case 2: 文件已有 begin/end 标记 → 仅替换标记区段
+    if (SECTION_PATTERN.test(existing)) {
+        const updated = existing.replace(SECTION_PATTERN, wrappedSection);
+        if (updated === existing) {
+            logger?.info?.(`[FileProtection] "${fileName}" — section unchanged, skipped write`);
+            return { written: false, strategy: 'replace-section', filePath };
+        }
+        fs.writeFileSync(filePath, updated, 'utf8');
+        logger?.info?.(`[FileProtection] Updated "${fileName}" (replaced marker section)`);
+        return { written: true, strategy: 'replace-section', filePath };
+    }
+    // Case 3: 文件有 AutoSnippet 签名但无标记 → 旧版格式，重写并加标记
+    if (SIGNATURE_PATTERN.test(existing.slice(0, 1024))) {
+        const content = header ? `${header}\n${wrappedSection}\n` : `${wrappedSection}\n`;
+        fs.writeFileSync(filePath, content, 'utf8');
+        logger?.info?.(`[FileProtection] Rewrote "${fileName}" (legacy → marker format)`);
+        return { written: true, strategy: 'rewrite-legacy', filePath };
+    }
+    // Case 4: 用户自有文件 → 追加标记区段到末尾
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(filePath, `${existing}${separator}${wrappedSection}\n`, 'utf8');
+    logger?.info?.(`[FileProtection] Appended AutoSnippet section to "${fileName}" (user-owned file preserved)`);
+    return { written: true, strategy: 'append-section', filePath };
+}

package/dist/lib/service/delivery/SkillsSyncer.js

@@ -19,36 +19,31 @@ import { SKILLS_DIR as BUILTIN_SKILLS_DIR } from '../../shared/package-root.js';
  */
 const SKILL_NAME_MAP = {
     'project-architecture': 'autosnippet-architecture',
-    'project-code-standard': 'autosnippet-code-standard',
-    'project-profile': 'autosnippet-profile',
+    'project-coding-standards': 'autosnippet-coding-standards',
     'project-agent-guidelines': 'autosnippet-guidelines',
-    'project-event-and-data-flow': 'autosnippet-data-flow',
-    'project-code-pattern': 'autosnippet-code-pattern',
-    'project-objc-deep-scan': 'autosnippet-objc-deep-scan',
-    'project-category-scan': 'autosnippet-category-scan',
-    'project-best-practice': 'autosnippet-best-practice',
-    // 新语言维度
-    'project-module-exports': 'autosnippet-module-exports',
-    'project-framework-conventions': 'autosnippet-framework-conventions',
+    'project-data-event-flow': 'autosnippet-data-flow',
+    'project-design-patterns': 'autosnippet-design-patterns',
+    'project-error-resilience': 'autosnippet-error-resilience',
+    'project-swift-objc-idiom': 'autosnippet-swift-objc-idiom',
+    // 语言维度
+    'project-ts-js-module': 'autosnippet-ts-js-module',
+    'project-react-patterns': 'autosnippet-react-patterns',
     'project-python-structure': 'autosnippet-python-structure',
-    'project-jvm-annotations': 'autosnippet-jvm-annotations',
+    'project-jvm-annotation': 'autosnippet-jvm-annotation',
 };
 /** 用途描述模板（英文，Cursor 优先） */
 const SKILL_DESC_MAP = {
     'autosnippet-architecture': 'Architecture patterns, module boundaries, and dependency rules for {project}. Use when creating new modules, reviewing architecture, or understanding dependencies.',
-    'autosnippet-code-standard': 'Coding standards and style conventions for {project}. Use when writing new code, reviewing formatting, or enforcing naming conventions.',
-    'autosnippet-profile': 'Project overview and profile for {project}. Use when needing background on the project, its tech stack, or structure.',
+    'autosnippet-coding-standards': 'Coding standards and style conventions for {project}. Use when writing new code, reviewing formatting, or enforcing naming conventions.',
     'autosnippet-guidelines': 'Agent interaction guidelines for {project}. Use when understanding how to work with this specific project.',
     'autosnippet-data-flow': 'Event and data flow patterns for {project}. Use when working with events, state management, or data pipelines.',
-    'autosnippet-code-pattern': 'Common code patterns and idioms for {project}. Use when implementing features following project conventions.',
-    'autosnippet-objc-deep-scan': 'Objective-C deep scan results for {project}. Use when working with Objective-C code, method swizzling, or runtime features.',
-    'autosnippet-category-scan': 'Category and extension analysis for {project}. Use when working with categories or finding existing utility methods.',
-    'autosnippet-best-practice': 'Best practices and proven patterns for {project}. Use when making design decisions or code review.',
-    // 新语言维度
-    'autosnippet-module-exports': 'Module export structure, barrel exports, and public API surface for {project}. Use when working with imports/exports or module boundaries.',
-    'autosnippet-framework-conventions': 'Framework-specific conventions (component structure, routing, state management) for {project}. Use when following framework patterns.',
+    'autosnippet-design-patterns': 'Common code patterns and idioms for {project}. Use when implementing features following project conventions.',
+    'autosnippet-error-resilience': 'Error handling, resilience patterns and defensive coding for {project}. Use when making design decisions or code review.',
+    'autosnippet-swift-objc-idiom': 'Swift/ObjC idioms, categories, method swizzling and interop for {project}. Use when working with Swift or Objective-C code.',
+    'autosnippet-ts-js-module': 'Module export structure, barrel exports, and public API surface for {project}. Use when working with imports/exports or module boundaries.',
+    'autosnippet-react-patterns': 'React component patterns, state management conventions and routing for {project}. Use when following framework patterns.',
     'autosnippet-python-structure': 'Python package structure, __init__.py exports, import patterns and type hint coverage for {project}. Use when working with Python modules.',
-    'autosnippet-jvm-annotations': 'Annotation patterns (DI, ORM, API, custom) and meta-programming for {project}. Use when working with Spring, Jakarta, or framework annotations.',
+    'autosnippet-jvm-annotation': 'Annotation patterns (DI, ORM, API, custom) and meta-programming for {project}. Use when working with Spring, Jakarta, or framework annotations.',
 };
 export class SkillsSyncer {
     knowledgeService;