autosnippet 3.2.18 → 3.2.21

package/dist/lib/cli/SetupService.js

@@ -72,7 +72,7 @@ export class SetupService {
     /** 子仓库远程仓库 URL（为空则 recipes/ 作为普通目录随主仓库提交） */
     subRepoUrl;
     /**
-     * @param {{ projectRoot: string, force?: boolean, seed?: boolean, subRepoDir?: string, subRepoUrl?: string }} options
+     * @param options
      */
     constructor(options) {
         this.projectRoot = resolve(options.projectRoot);
@@ -130,7 +130,7 @@ export class SetupService {
         this._results = results;
         return results;
     }
-    /** @private 格式化步骤结果的简要信息 */
+    /** 格式化步骤结果的简要信息 */
     _formatStepDetail(r) {
         if (!r) {
             return '';
@@ -149,8 +149,21 @@ export class SetupService {
     }
     printSummary() {
         const results = this._results || [];
-        const _ok = results.filter((r) => r.ok).length;
-        const _fail = results.filter((r) => !r.ok).length;
+        const ok = results.filter((r) => r.ok).length;
+        const fail = results.filter((r) => !r.ok).length;
+        console.log('');
+        if (fail === 0) {
+            console.log(`  ✅ Setup 完成（${ok} 步骤全部成功）`);
+        }
+        else {
+            console.log(`  ⚠️  Setup 完成（${ok} 成功，${fail} 失败）`);
+        }
+        console.log('');
+        console.log('  下一步：');
+        console.log('    1. 运行 asd ui 启动后台服务');
+        console.log('    2. 打开 IDE Agent Mode，告诉它「帮我冷启动」');
+        console.log('    3. 所有分析和知识提取都通过 IDE 完成，无需额外配置');
+        console.log('');
     }
     /* ═══ Step 1: 运行时目录与配置 ═══════════════════════ */
     stepRuntime() {
@@ -252,7 +265,7 @@ export class SetupService {
             hasUrl: Boolean(this.subRepoUrl),
         };
     }
-    /** @private 写入 constitution.yaml（优先从模板复制） */
+    /** 写入 constitution.yaml（优先从模板复制） */
     _writeConstitution() {
         const dest = join(this.coreDir, 'constitution.yaml');
         if (existsSync(dest) && !this.force) {
@@ -307,7 +320,7 @@ export class SetupService {
             ].join('\n'));
         }
     }
-    /** @private 写入 boxspec.json */
+    /** 写入 boxspec.json */
     _writeBoxspec() {
         const dest = join(this.coreDir, 'boxspec.json');
         if (existsSync(dest) && !this.force) {
@@ -323,7 +336,7 @@ export class SetupService {
             module: { rootDir: DEFAULT_KNOWLEDGE_BASE_DIR },
         }, null, 2));
     }
-    /** @private 复制 _template.md 到 recipes/ */
+    /** 复制 _template.md 到 recipes/ */
     _copyRecipeTemplate() {
         const src = join(REPO_ROOT, 'templates', 'recipes-setup', '_template.md');
         if (!existsSync(src)) {
@@ -335,7 +348,7 @@ export class SetupService {
         }
         copyFileSync(src, dest);
     }
-    /** @private 复制示例 Recipe（冷启动推荐） */
+    /** 复制示例 Recipe（冷启动推荐） */
     _copySeedRecipes() {
         const seedDir = join(REPO_ROOT, 'templates', 'recipes-setup');
         if (!existsSync(seedDir)) {
@@ -361,7 +374,7 @@ export class SetupService {
         if (count > 0) {
         }
     }
-    /** @private 写入核心目录 README */
+    /** 写入核心目录 README */
     _writeCoreReadme() {
         const dest = join(this.coreDir, 'README.md');
         if (existsSync(dest) && !this.force) {
@@ -485,7 +498,7 @@ export class SetupService {
         return { dbPath: this.dbPath };
     }
     /**
-     * @private 从 AutoSnippet/recipes/*.md + candidates/*.md 同步到 DB 缓存
+     * 从 AutoSnippet/recipes/*.md + candidates/*.md 同步到 DB 缓存
      * 委托 KnowledgeSyncService 执行全字段同步（setup 场景跳过违规记录）
      */
     async _syncRecipesToDB(db) {
@@ -532,7 +545,7 @@ export class SetupService {
     }
     /* ═══ Helpers ════════════════════════════════════════ */
     /**
-     * @private 在项目根目录创建 .env 文件（从 .env.example 复制）
+     * 在项目根目录创建 .env 文件（从 .env.example 复制）
      * 如果 .env 已存在则跳过并提示用户手动配置。
      */
     _ensureEnvFile() {
@@ -557,7 +570,7 @@ export class SetupService {
             ].join('\n'));
         }
     }
-    /** @private 在指定目录执行 git 命令 */
+    /** 在指定目录执行 git 命令 */
     _git(args, cwd) {
         try {
             return execSync(`git ${args.join(' ')}`, {
@@ -573,7 +586,7 @@ export class SetupService {
             throw e;
         }
     }
-    /** @private 检查目录中是否有文件（排除 . 和 ..） */
+    /** 检查目录中是否有文件（排除 . 和 ..） */
     _hasFiles(dirPath) {
         try {
             const entries = readdirSync(dirPath);
@@ -583,7 +596,7 @@ export class SetupService {
             return false;
         }
     }
-    /** @private 确保子仓库的 remote origin 与给定 URL 一致 */
+    /** 确保子仓库的 remote origin 与给定 URL 一致 */
     _ensureRemote(url) {
         try {
             const currentUrl = this._git(['remote', 'get-url', 'origin'], this.subRepoPath);
@@ -597,7 +610,7 @@ export class SetupService {
         }
     }
     /**
-     * @private 备份已有文件 → clone → 合并回来（不覆盖远端文件）
+     * 备份已有文件 → clone → 合并回来（不覆盖远端文件）
      * 适用于 recipes/ 有模板文件但还不是 git 仓库的场景
      */
     _cloneWithMerge(url) {

package/dist/lib/cli/deploy/FileDeployer.d.ts

@@ -42,7 +42,7 @@ export declare class FileDeployer {
     });
     /**
      * 部署所有适用的文件
-     * @param {{ filter?: string[] }} options 可选过滤部署的 category
+     * @param options 可选过滤部署的 category
      * @returns > }}
      */
     deployAll(mode: 'setup' | 'upgrade', { filter }?: {
@@ -79,7 +79,14 @@ export declare class FileDeployer {
     _strategyCreateOnly(entry: ManifestEntry): boolean;
     /** merge-json — 读取现有 JSON，合并 autosnippet 键 */
     _strategyMergeJson(entry: ManifestEntry): boolean;
-    /** merge-gitignore — 增量追加规则 + 迁移旧格式 */
+    /**
+     * merge-gitignore — section-based 管理
+     *
+     * 设计：用 BEGIN/END 标记包裹 AutoSnippet 规则块，整块替换。
+     * - 首次：追加 section 到文件末尾
+     * - 升级：替换已有 section（规则变更自动生效）
+     * - 迁移：清理旧版逐行追加的散落规则
+     */
     _strategyMergeGitignore(_entry: ManifestEntry): boolean;
     /** backup-overwrite — 备份旧文件后覆盖 */
     _strategyBackupOverwrite(entry: ManifestEntry): boolean;

package/dist/lib/cli/deploy/FileDeployer.js

@@ -22,7 +22,7 @@ import { injectAutoApprove } from '../../external/mcp/autoApproveInjector.js';
 import { checkWriteSafety, safeCopyFile } from '../../service/delivery/FileProtection.js';
 import { DEFAULT_KNOWLEDGE_BASE_DIR } from '../../shared/ProjectMarkers.js';
 import { PACKAGE_ROOT, TEMPLATES_DIR } from '../../shared/package-root.js';
-import { buildMcpServerEntry, GITIGNORE_MIGRATIONS, GITIGNORE_RULES, MANIFEST, } from './FileManifest.js';
+import { buildMcpServerEntry, GITIGNORE_MIGRATIONS, GITIGNORE_RULES, GITIGNORE_SECTION_BEGIN, GITIGNORE_SECTION_END, MANIFEST, } from './FileManifest.js';
 /** AutoSnippet 源码仓库根目录 */
 const REPO_ROOT = PACKAGE_ROOT;
 export class FileDeployer {
@@ -38,7 +38,7 @@ export class FileDeployer {
     /* ═══ 公共入口 ═══════════════════════════════════════ */
     /**
      * 部署所有适用的文件
-     * @param {{ filter?: string[] }} options 可选过滤部署的 category
+     * @param options 可选过滤部署的 category
      * @returns > }}
      */
     deployAll(mode, { filter } = {}) {
@@ -227,38 +227,90 @@ export class FileDeployer {
         writeFileSync(dest, JSON.stringify(config, null, 2));
         return true;
     }
-    /** merge-gitignore — 增量追加规则 + 迁移旧格式 */
+    /**
+     * merge-gitignore — section-based 管理
+     *
+     * 设计：用 BEGIN/END 标记包裹 AutoSnippet 规则块，整块替换。
+     * - 首次：追加 section 到文件末尾
+     * - 升级：替换已有 section（规则变更自动生效）
+     * - 迁移：清理旧版逐行追加的散落规则
+     */
     _strategyMergeGitignore(_entry) {
         const giPath = join(this.projectRoot, '.gitignore');
         let content = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
         let changed = false;
-        // 1. 迁移旧格式
+        // 1. 迁移旧格式（regex-based cleanup）
         for (const migration of GITIGNORE_MIGRATIONS) {
             if (migration.find.test(content)) {
                 content = content.replace(migration.find, migration.replace);
                 changed = true;
             }
         }
-        // 2. 追加缺失规则
-        for (const rule of GITIGNORE_RULES) {
-            const pattern = rule.pattern;
-            // 对 negation 规则 (!xxx) 检查原模式
-            const _checkStr = rule.negation ? pattern : pattern.replace(/[[\]*?]/g, '\\$&');
-            if (!content.includes(pattern)) {
-                const prefix = rule.comment ? `\n# ${rule.comment}\n` : '';
-                content += `${prefix}${pattern}\n`;
+        // 2. 迁移：清理旧版散落的 AutoSnippet 规则（无 section marker 时代的残留）
+        const oldPatterns = GITIGNORE_RULES.map((r) => r.pattern);
+        const oldComments = GITIGNORE_RULES.filter((r) => r.comment).map((r) => `# ${r.comment}`);
+        // 也清除旧版注入的通用规则
+        const legacyTokens = [
+            '.DS_Store',
+            'nohup.out',
+            '*.sw[a-p]',
+            '# macOS 元数据',
+            '# AutoSnippet 运行时缓存（不入库）',
+            '# AutoSnippet 环境变量（含 API Key，不入库）',
+            '# AutoSnippet 运行日志',
+        ];
+        const allOldTokens = new Set([...oldPatterns, ...oldComments, ...legacyTokens]);
+        // 只有在 section markers 不存在时才清理散落规则（避免误删 section 内容后重复清理）
+        if (!content.includes(GITIGNORE_SECTION_BEGIN)) {
+            const lines = content.split('\n');
+            const cleaned = lines.filter((line) => !allOldTokens.has(line.trim()));
+            const cleanedContent = cleaned
+                .join('\n')
+                .replace(/\n{3,}/g, '\n\n')
+                .trimEnd();
+            if (cleanedContent !== content.trimEnd()) {
+                content = cleanedContent.endsWith('\n') ? cleanedContent : `${cleanedContent}\n`;
                 changed = true;
             }
         }
-        // 3. 确保 AutoSnippet/ 不被忽略
+        // 3. 构建 AutoSnippet section block
+        const sectionLines = [GITIGNORE_SECTION_BEGIN];
+        for (const rule of GITIGNORE_RULES) {
+            if (rule.comment) {
+                sectionLines.push(`# ${rule.comment}`);
+            }
+            sectionLines.push(rule.pattern);
+        }
+        // 确保 AutoSnippet/ 知识库不被忽略
         const kbDir = DEFAULT_KNOWLEDGE_BASE_DIR;
-        const lines = content.split('\n');
-        const hasIgnoreAS = lines.some((l) => {
+        const contentLines = content.split('\n');
+        const hasIgnoreAS = contentLines.some((l) => {
             const t = l.trim();
             return (t === `${kbDir}/` || t === kbDir) && !t.startsWith('#') && !t.startsWith('!');
         });
-        if (hasIgnoreAS && !lines.some((l) => l.trim() === `!${kbDir}/`)) {
-            content += `\n# ${kbDir} 知识库必须入库（取消上方忽略）\n!${kbDir}/\n`;
+        if (hasIgnoreAS) {
+            sectionLines.push(`# 知识库必须入库`);
+            sectionLines.push(`!${kbDir}/`);
+        }
+        sectionLines.push(GITIGNORE_SECTION_END);
+        const sectionBlock = sectionLines.join('\n');
+        // 4. 插入或替换 section
+        const beginIdx = content.indexOf(GITIGNORE_SECTION_BEGIN);
+        const endIdx = content.indexOf(GITIGNORE_SECTION_END);
+        if (beginIdx !== -1 && endIdx !== -1) {
+            // 替换已有 section
+            const before = content.substring(0, beginIdx);
+            const after = content.substring(endIdx + GITIGNORE_SECTION_END.length);
+            const newContent = `${before}${sectionBlock}${after}`;
+            if (newContent !== content) {
+                content = newContent;
+                changed = true;
+            }
+        }
+        else {
+            // 首次追加
+            const separator = content.endsWith('\n') || content.length === 0 ? '\n' : '\n\n';
+            content += `${separator}${sectionBlock}\n`;
             changed = true;
         }
         if (changed) {
@@ -335,7 +387,71 @@ export class FileDeployer {
     }
     /* ═══ 自定义生成器 ═══════════════════════════════════ */
     _generators = {
-        /** AGENTS.md 静态骨架 */
+        /** .cursor/rules/autosnippet-conventions.mdc — 读 conventions.md + YAML frontmatter */
+        generateConventionsMdc() {
+            const tpl = join(TEMPLATES_DIR, 'instructions/conventions.md');
+            if (!existsSync(tpl)) {
+                return false;
+            }
+            const body = readFileSync(tpl, 'utf8').trimEnd();
+            const content = [
+                '---',
+                'description: AutoSnippet conventions — behavioral rules for task tracking, knowledge guardrails, and MCP usage',
+                'alwaysApply: true',
+                '---',
+                '',
+                '# AutoSnippet Conventions',
+                '',
+                body,
+                '',
+            ].join('\n');
+            const dest = join(this.projectRoot, '.cursor/rules/autosnippet-conventions.mdc');
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, content);
+            return true;
+        },
+        /** .github/copilot-instructions.md — 读 conventions.md + HTML markers */
+        generateCopilotInstructions() {
+            const tpl = join(TEMPLATES_DIR, 'instructions/conventions.md');
+            if (!existsSync(tpl)) {
+                return false;
+            }
+            const body = readFileSync(tpl, 'utf8').trimEnd();
+            const content = [
+                '<!-- autosnippet:begin -->',
+                '',
+                '# AutoSnippet Conventions',
+                '',
+                body,
+                '',
+                '<!-- autosnippet:end -->',
+                '',
+            ].join('\n');
+            const dest = join(this.projectRoot, '.github/copilot-instructions.md');
+            const destDir = dirname(dest);
+            mkdirSync(destDir, { recursive: true });
+            // 如果文件已存在且包含 begin/end markers，仅替换标记间内容
+            if (existsSync(dest)) {
+                const existing = readFileSync(dest, 'utf8');
+                const BEGIN = '<!-- autosnippet:begin -->';
+                const END = '<!-- autosnippet:end -->';
+                if (existing.includes(BEGIN) && existing.includes(END)) {
+                    const snippet = content.trimEnd();
+                    const updated = existing.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}`), snippet);
+                    writeFileSync(dest, updated);
+                    return true;
+                }
+                // 用户文件无 markers 且无 AutoSnippet 签名 → 追加
+                const { canWrite } = checkWriteSafety(dest);
+                if (!canWrite) {
+                    writeFileSync(dest, `${existing}\n\n${content}`);
+                    return true;
+                }
+            }
+            writeFileSync(dest, content);
+            return true;
+        },
+        /** AGENTS.md 静态骨架 — 读 agent-static.md 模板 */
         generateAgentsMd() {
             const claudePath = join(this.projectRoot, 'CLAUDE.md');
             if (existsSync(claudePath)) {
@@ -349,34 +465,11 @@ export class FileDeployer {
             if (!canWrite) {
                 return false;
             }
-            const content = [
-                `# ${this.projectName} — Agent Instructions`,
-                '',
-                '> Auto-generated by AutoSnippet.',
-                '',
-                '## AutoSnippet Integration',
-                '',
-                'This project uses **AutoSnippet** for knowledge management and decision tracking.',
-                '',
-                '### MCP Tools',
-                '',
-                '- `autosnippet_search` — Search knowledge',
-                '- `autosnippet_knowledge` — Browse/get recipes',
-                '- `autosnippet_submit_knowledge` — Submit candidate',
-                '- `autosnippet_guard` — Code compliance check',
-                '- `autosnippet_health` — Service health & KB stats',
-                '- `autosnippet_task` — Unified task & decision management (prime/create/claim/close/record_decision/revise_decision/unpin_decision/list_decisions)',
-                '',
-                '### VS Code Agent Mode',
-                '',
-                'Type `#asd` before your message in Agent Mode to activate project memory.',
-                '',
-                '### Constraints',
-                '',
-                '1. Do NOT modify knowledge base files directly.',
-                '2. Create or update knowledge only through MCP tools.',
-                '',
-            ].join('\n');
+            const tpl = join(TEMPLATES_DIR, 'instructions/agent-static.md');
+            if (!existsSync(tpl)) {
+                return false;
+            }
+            const content = readFileSync(tpl, 'utf8').replace(/\{\{projectName\}\}/g, this.projectName);
             writeFileSync(agentsPath, content);
             return true;
         },

package/dist/lib/cli/deploy/FileManifest.d.ts

@@ -32,25 +32,23 @@ export declare const MANIFEST: ({
     on: string;
     category: string;
     jsonKey: string;
+    generate?: undefined;
     src?: undefined;
     chmod?: undefined;
     cleanup?: undefined;
-    fallback?: undefined;
-    generate?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 } | {
     id: string;
-    src: string;
-    dest: string;
     strategy: string;
+    generate: string;
+    dest: string;
     on: string;
     category: string;
     jsonKey?: undefined;
+    src?: undefined;
     chmod?: undefined;
     cleanup?: undefined;
-    fallback?: undefined;
-    generate?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 } | {
@@ -60,11 +58,10 @@ export declare const MANIFEST: ({
     strategy: string;
     on: string;
     category: string;
-    chmod: boolean;
     jsonKey?: undefined;
-    cleanup?: undefined;
-    fallback?: undefined;
     generate?: undefined;
+    chmod?: undefined;
+    cleanup?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 } | {
@@ -75,10 +72,9 @@ export declare const MANIFEST: ({
     on: string;
     category: string;
     chmod: boolean;
-    cleanup: string[];
     jsonKey?: undefined;
-    fallback?: undefined;
     generate?: undefined;
+    cleanup?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 } | {
@@ -88,27 +84,12 @@ export declare const MANIFEST: ({
     strategy: string;
     on: string;
     category: string;
-    fallback: string;
+    chmod: boolean;
+    cleanup: string[];
     jsonKey?: undefined;
-    chmod?: undefined;
-    cleanup?: undefined;
     generate?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
-} | {
-    id: string;
-    strategy: string;
-    generate: string;
-    dest: string;
-    on: string;
-    category: string;
-    jsonKey?: undefined;
-    src?: undefined;
-    chmod?: undefined;
-    cleanup?: undefined;
-    fallback?: undefined;
-    resolveDest?: undefined;
-    requireDir?: undefined;
 } | {
     id: string;
     src: string;
@@ -119,9 +100,8 @@ export declare const MANIFEST: ({
     chmod: boolean;
     resolveDest: string;
     jsonKey?: undefined;
-    cleanup?: undefined;
-    fallback?: undefined;
     generate?: undefined;
+    cleanup?: undefined;
     requireDir?: undefined;
 } | {
     id: string;
@@ -132,10 +112,9 @@ export declare const MANIFEST: ({
     category: string;
     requireDir: string;
     jsonKey?: undefined;
+    generate?: undefined;
     chmod?: undefined;
     cleanup?: undefined;
-    fallback?: undefined;
-    generate?: undefined;
     resolveDest?: undefined;
 } | {
     id: string;
@@ -144,11 +123,10 @@ export declare const MANIFEST: ({
     on: string;
     category: string;
     jsonKey?: undefined;
+    generate?: undefined;
     src?: undefined;
     chmod?: undefined;
     cleanup?: undefined;
-    fallback?: undefined;
-    generate?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 } | {
@@ -162,7 +140,6 @@ export declare const MANIFEST: ({
     src?: undefined;
     chmod?: undefined;
     cleanup?: undefined;
-    fallback?: undefined;
     resolveDest?: undefined;
     requireDir?: undefined;
 })[];
@@ -170,6 +147,17 @@ export declare const MANIFEST: ({
  * .gitignore 规则清单 — Setup 和 Upgrade 共用
  * 每条规则：{ pattern, comment, negation? }
  */
+/**
+ * Section markers for the AutoSnippet block inside .gitignore.
+ * merge-gitignore uses these to insert/replace the entire block atomically.
+ */
+export declare const GITIGNORE_SECTION_BEGIN = "# >>> AutoSnippet (managed block \u2014 do not edit) >>>";
+export declare const GITIGNORE_SECTION_END = "# <<< AutoSnippet <<<";
+/**
+ * AutoSnippet-specific .gitignore rules.
+ * Only patterns that are AutoSnippet runtime/build artifacts belong here.
+ * Generic OS/editor patterns (.DS_Store, *.swp, nohup.out) are NOT our business.
+ */
 export declare const GITIGNORE_RULES: ({
     pattern: string;
     comment: string;
@@ -178,10 +166,6 @@ export declare const GITIGNORE_RULES: ({
     pattern: string;
     negation: boolean;
     comment?: undefined;
-} | {
-    pattern: string;
-    comment?: undefined;
-    negation?: undefined;
 })[];
 /** .gitignore 迁移规则 — 升级时清理旧格式 */
 export declare const GITIGNORE_MIGRATIONS: {

package/dist/lib/cli/deploy/FileManifest.js

@@ -47,9 +47,9 @@ export const MANIFEST = [
     // ═══ Cursor Rules（AutoSnippet 完全拥有） ═══════════
     {
         id: 'cursor-conventions',
-        src: 'cursor-rules/autosnippet-conventions.mdc',
+        strategy: 'generate',
+        generate: 'generateConventionsMdc',
         dest: '.cursor/rules/autosnippet-conventions.mdc',
-        strategy: 'overwrite',
         on: 'both',
         category: 'cursor-rules',
     },
@@ -61,14 +61,6 @@ export const MANIFEST = [
         on: 'both',
         category: 'cursor-rules',
     },
-    {
-        id: 'cursor-workflow',
-        src: 'cursor-rules/autosnippet-workflow.mdc',
-        dest: '.cursor/rules/autosnippet-workflow.mdc',
-        strategy: 'overwrite',
-        on: 'both',
-        category: 'cursor-rules',
-    },
     // ═══ Cursor Hooks ═════════════════════════════════════
     {
         id: 'cursor-hooks-json',
@@ -107,15 +99,14 @@ export const MANIFEST = [
         chmod: true,
         cleanup: ['.claude/hooks.yaml'], // 清理旧格式文件
     },
-    // ═══ Agent Instructions（签名保护）════════════════════
+    // ═══ Agent Instructions（全部从模板生成）═══════════════
     {
         id: 'copilot-instructions',
-        src: 'copilot-instructions.md',
+        strategy: 'generate',
+        generate: 'generateCopilotInstructions',
         dest: '.github/copilot-instructions.md',
-        strategy: 'signature-safe',
         on: 'both',
         category: 'copilot-instructions',
-        fallback: 'inject-marker', // 签名保护失败时，用标记注入
     },
     {
         id: 'agents-md',
@@ -210,29 +201,27 @@ export const MANIFEST = [
  * .gitignore 规则清单 — Setup 和 Upgrade 共用
  * 每条规则：{ pattern, comment, negation? }
  */
+/**
+ * Section markers for the AutoSnippet block inside .gitignore.
+ * merge-gitignore uses these to insert/replace the entire block atomically.
+ */
+export const GITIGNORE_SECTION_BEGIN = '# >>> AutoSnippet (managed block — do not edit) >>>';
+export const GITIGNORE_SECTION_END = '# <<< AutoSnippet <<<';
+/**
+ * AutoSnippet-specific .gitignore rules.
+ * Only patterns that are AutoSnippet runtime/build artifacts belong here.
+ * Generic OS/editor patterns (.DS_Store, *.swp, nohup.out) are NOT our business.
+ */
 export const GITIGNORE_RULES = [
-    // 核心运行时
-    { pattern: '.autosnippet/*', comment: 'AutoSnippet 运行时缓存（不入库）' },
+    // Runtime cache
+    { pattern: '.autosnippet/*', comment: '运行时缓存（不入库）' },
     { pattern: '!.autosnippet/config.json', negation: true },
-    // 环境变量
-    { pattern: '.env', comment: 'AutoSnippet 环境变量（含 API Key，不入库）' },
-    // 日志
-    { pattern: 'logs/', comment: 'AutoSnippet 运行日志' },
-    // AI 草稿
-    { pattern: '.autosnippet-drafts/', comment: 'AutoSnippet AI 草稿（临时）' },
-    { pattern: '_draft_*.md', comment: 'AutoSnippet AI 草稿文件（项目根目录临时文件）' },
-    // 系统 / 编辑器临时文件
-    { pattern: '.DS_Store', comment: 'macOS 元数据' },
-    { pattern: 'nohup.out' },
-    { pattern: '*.sw[a-p]' },
+    // Environment (contains API keys created by `asd setup`)
+    { pattern: '.env', comment: '环境变量（含 API Key）' },
+    // Logs（已收纳到 .autosnippet/ 下，由 .autosnippet/* 统一覆盖）
 ];
 /** .gitignore 迁移规则 — 升级时清理旧格式 */
-export const GITIGNORE_MIGRATIONS = [
-    // v2.4.0: ".autosnippet/" → ".autosnippet/*"
-    { find: /^\.autosnippet\/$/m, replace: '.autosnippet/*' },
-    // Skills 已迁移到 AutoSnippet/skills/，清理旧 negation
-    { find: /^!?\.autosnippet\/skills\/.*\n?/gm, replace: '' },
-];
+export const GITIGNORE_MIGRATIONS = [];
 /** MCP Server 配置生成器 */
 export function buildMcpServerEntry(projectRoot, ide) {
     const base = {

package/dist/lib/core/AstAnalyzer.d.ts

@@ -197,7 +197,7 @@ export declare function registerLanguage(langId: string, plugin: LangPlugin): vo
 declare function analyzeFile(source: string, lang: string, options?: AnalyzeFileOptions): AstFileSummary | null;
 /**
  * 批量分析多文件，返回项目级汇总
- * @param {{ name: string, relativePath: string, content: string }[]} files
+ * @param files
  * @param | null }} [options]
  */
 declare function analyzeProject(files: FileInput[], lang: string, options: AnalyzeProjectOptions): ProjectAnalysisResult;
@@ -234,7 +234,7 @@ declare function findCallExpressions(source: string, lang: string, targetCallee:
  * @param source 源代码
  * @param lang 'objectivec' | 'swift'
  * @param pattern 要查找的文本模式（普通字符串匹配）
- * @param {{ forbiddenContext?: string, requiredContext?: string }} contextFilter
+ * @param contextFilter
  *   forbiddenContext: 如果在此上下文中出现则报告 (如 'dealloc')
  *   requiredContext: 如果不在此上下文中出现则报告
  * @returns >}