autosnippet 3.3.5 → 3.3.7

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;

package/dist/lib/service/evolution/ContentPatcher.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ContentPatcher — Proposal suggestedChanges 消费引擎
+ *
+ * 核心职责：
+ *   1. 从 Proposal.evidence 提取 suggestedChanges
+ *   2. 解析为结构化 Patch（JSON 或降级为纯文本）
+ *   3. 创建 Recipe 内容快照（before）
+ *   4. 应用 patch 到 Recipe 字段
+ *   5. 创建快照（after）
+ *   6. 持久化更新
+ *
+ * 安全边界：
+ *   - 只修改 Patch 指定的字段，不擅自变更其他内容
+ *   - suggestedChanges 缺失或格式不合规时降级跳过（不阻塞状态转移）
+ *   - 所有变更在 before/after 快照中可追溯
+ *
+ * @module service/evolution/ContentPatcher
+ */
+import type { ContentPatchResult } from '../../types/evolution.js';
+interface DatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): Record<string, unknown>[];
+        get(...params: unknown[]): Record<string, unknown> | undefined;
+        run(...params: unknown[]): {
+            changes: number;
+        };
+    };
+}
+export declare class ContentPatcher {
+    #private;
+    constructor(db: DatabaseLike);
+    /**
+     * 从 Proposal evidence 提取 suggestedChanges 并应用到 Recipe
+     *
+     * @returns ContentPatchResult — success: 是否成功应用了至少一个 patch
+     */
+    applyProposal(proposal: {
+        id: string;
+        type: string;
+        targetRecipeId: string;
+        evidence: Record<string, unknown>[];
+    }, patchSource?: 'agent-suggestion' | 'correction' | 'merge'): ContentPatchResult;
+}
+export {};

package/dist/lib/service/evolution/ContentPatcher.js

@@ -0,0 +1,310 @@
+/**
+ * ContentPatcher — Proposal suggestedChanges 消费引擎
+ *
+ * 核心职责：
+ *   1. 从 Proposal.evidence 提取 suggestedChanges
+ *   2. 解析为结构化 Patch（JSON 或降级为纯文本）
+ *   3. 创建 Recipe 内容快照（before）
+ *   4. 应用 patch 到 Recipe 字段
+ *   5. 创建快照（after）
+ *   6. 持久化更新
+ *
+ * 安全边界：
+ *   - 只修改 Patch 指定的字段，不擅自变更其他内容
+ *   - suggestedChanges 缺失或格式不合规时降级跳过（不阻塞状态转移）
+ *   - 所有变更在 before/after 快照中可追溯
+ *
+ * @module service/evolution/ContentPatcher
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+/* ────────────────────── Patchable Fields ────────────────────── */
+/** 允许 patch 的顶层字段白名单 */
+const PATCHABLE_FIELDS = new Set([
+    'coreCode',
+    'doClause',
+    'dontClause',
+    'whenClause',
+    'content.markdown',
+    'content.rationale',
+    'sourceRefs',
+    'headers',
+]);
+/* ────────────────────── Class ────────────────────── */
+export class ContentPatcher {
+    #db;
+    #logger = Logger.getInstance();
+    constructor(db) {
+        this.#db = db;
+    }
+    /**
+     * 从 Proposal evidence 提取 suggestedChanges 并应用到 Recipe
+     *
+     * @returns ContentPatchResult — success: 是否成功应用了至少一个 patch
+     */
+    applyProposal(proposal, patchSource = 'agent-suggestion') {
+        const recipeId = proposal.targetRecipeId;
+        // 1. 获取 Recipe 当前内容
+        const recipe = this.#getRecipe(recipeId);
+        if (!recipe) {
+            return this.#skipResult(recipeId, patchSource, 'Recipe not found');
+        }
+        // 2. 提取 suggestedChanges
+        const rawChanges = this.#extractSuggestedChanges(proposal.evidence);
+        if (!rawChanges) {
+            return this.#skipResult(recipeId, patchSource, 'No suggestedChanges in proposal evidence');
+        }
+        // 3. 解析为结构化 Patch
+        const patch = this.#parsePatch(rawChanges);
+        if (!patch || patch.changes.length === 0) {
+            return this.#skipResult(recipeId, patchSource, 'suggestedChanges could not be parsed or empty');
+        }
+        // 4. 创建 before 快照
+        const beforeSnapshot = this.#createSnapshot(recipe);
+        // 5. 应用 patch
+        const fieldsPatched = this.#applyPatch(recipe, patch.changes);
+        if (fieldsPatched.length === 0) {
+            return this.#skipResult(recipeId, patchSource, 'No valid fields to patch');
+        }
+        // 6. 持久化
+        this.#persistRecipe(recipe);
+        // 7. 创建 after 快照
+        const afterSnapshot = this.#createSnapshot(recipe);
+        this.#logger.info(`[ContentPatcher] Applied ${fieldsPatched.length} patches to recipe ${recipeId}: ${fieldsPatched.join(', ')}`);
+        return {
+            success: true,
+            recipeId,
+            fieldsPatched,
+            beforeSnapshot,
+            afterSnapshot,
+            patchSource,
+            skipped: false,
+        };
+    }
+    /* ═══════════════════ Extract ═══════════════════ */
+    #extractSuggestedChanges(evidence) {
+        for (const ev of evidence) {
+            const cast = ev;
+            if (cast.suggestedChanges &&
+                typeof cast.suggestedChanges === 'string' &&
+                cast.suggestedChanges.trim().length > 0) {
+                return cast.suggestedChanges;
+            }
+        }
+        return null;
+    }
+    /* ═══════════════════ Parse ═══════════════════ */
+    /**
+     * 解析 suggestedChanges — 优先 JSON，降级为纯文本全量替换
+     */
+    #parsePatch(raw) {
+        // 尝试 JSON 解析
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('{')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed.changes && Array.isArray(parsed.changes)) {
+                    // JSON 有效但 changes 为空 → 视为无 patch
+                    if (parsed.changes.length === 0) {
+                        return null;
+                    }
+                    return {
+                        patchVersion: parsed.patchVersion ?? 1,
+                        changes: parsed.changes,
+                        reasoning: parsed.reasoning ?? '',
+                    };
+                }
+            }
+            catch {
+                // JSON 解析失败，降级到纯文本
+            }
+        }
+        // 降级：纯文本视为 content.markdown 全量替换（适用于旧格式 Agent 输出）
+        if (trimmed.length >= 20) {
+            return {
+                patchVersion: 1,
+                changes: [
+                    {
+                        field: 'content.markdown',
+                        action: 'replace',
+                        newValue: trimmed,
+                    },
+                ],
+                reasoning: 'Fallback: raw text treated as content.markdown replacement',
+            };
+        }
+        return null;
+    }
+    /* ═══════════════════ Apply ═══════════════════ */
+    #applyPatch(recipe, changes) {
+        const patched = [];
+        for (const change of changes) {
+            if (!PATCHABLE_FIELDS.has(change.field)) {
+                this.#logger.warn(`[ContentPatcher] Skipping non-patchable field: ${change.field}`);
+                continue;
+            }
+            const success = this.#applyOneChange(recipe, change);
+            if (success) {
+                patched.push(change.field);
+            }
+        }
+        return patched;
+    }
+    #applyOneChange(recipe, change) {
+        const { field, action } = change;
+        // content.* 嵌套字段
+        if (field.startsWith('content.')) {
+            return this.#applyContentChange(recipe, change);
+        }
+        // 顶层字段
+        if (field === 'sourceRefs' || field === 'headers') {
+            return this.#applyArrayChange(recipe, field, change);
+        }
+        // 简单字符串字段
+        const key = field;
+        if (action === 'replace' && change.newValue !== undefined) {
+            recipe[key] = change.newValue;
+            return true;
+        }
+        if (action === 'append' && change.newValue !== undefined) {
+            recipe[key] = `${recipe[key]}\n${change.newValue}`;
+            return true;
+        }
+        return false;
+    }
+    #applyContentChange(recipe, change) {
+        const contentObj = safeJsonParse(recipe.content, {});
+        const subField = change.field.split('.')[1]; // 'markdown' | 'rationale'
+        if (!subField) {
+            return false;
+        }
+        if (change.action === 'replace' && change.newValue !== undefined) {
+            contentObj[subField] = change.newValue;
+            recipe.content = JSON.stringify(contentObj);
+            return true;
+        }
+        if (change.action === 'replace-section' && change.section && change.newContent) {
+            const current = contentObj[subField] ?? '';
+            const updated = this.#replaceSection(current, change.section, change.newContent);
+            if (updated !== current) {
+                contentObj[subField] = updated;
+                recipe.content = JSON.stringify(contentObj);
+                return true;
+            }
+            return false;
+        }
+        if (change.action === 'append' && change.newValue !== undefined) {
+            const current = contentObj[subField] ?? '';
+            contentObj[subField] = `${current}\n${change.newValue}`;
+            recipe.content = JSON.stringify(contentObj);
+            return true;
+        }
+        return false;
+    }
+    #applyArrayChange(recipe, field, change) {
+        if (change.action === 'replace' && change.newValue !== undefined) {
+            try {
+                const newArr = JSON.parse(change.newValue);
+                if (Array.isArray(newArr)) {
+                    recipe[field] = JSON.stringify(newArr);
+                    return true;
+                }
+            }
+            catch {
+                // invalid JSON array
+            }
+            return false;
+        }
+        return false;
+    }
+    /**
+     * 替换 Markdown 中指定 section（基于标题行匹配）
+     */
+    #replaceSection(markdown, sectionTitle, newContent) {
+        const lines = markdown.split('\n');
+        const titleLine = lines.findIndex((line) => line.trim() === sectionTitle.trim());
+        if (titleLine === -1) {
+            // Section 不存在 → 追加
+            return `${markdown}\n\n${newContent}`;
+        }
+        // 找到 section 结尾（下一个同级或更高级标题）
+        const headingLevel = (sectionTitle.match(/^#+/) ?? [''])[0].length;
+        let endLine = lines.length;
+        for (let i = titleLine + 1; i < lines.length; i++) {
+            const match = lines[i].match(/^(#+)\s/);
+            if (match && match[1].length <= headingLevel) {
+                endLine = i;
+                break;
+            }
+        }
+        const before = lines.slice(0, titleLine);
+        const after = lines.slice(endLine);
+        return [...before, newContent, ...after].join('\n');
+    }
+    /* ═══════════════════ Snapshot ═══════════════════ */
+    #createSnapshot(recipe) {
+        const contentObj = safeJsonParse(recipe.content, {});
+        return {
+            coreCode: recipe.coreCode,
+            doClause: recipe.doClause,
+            dontClause: recipe.dontClause,
+            whenClause: recipe.whenClause,
+            content: {
+                markdown: contentObj.markdown ?? undefined,
+                rationale: contentObj.rationale ?? undefined,
+            },
+            sourceRefs: safeJsonParse(recipe.sourceRefs, []),
+            headers: safeJsonParse(recipe.headers, []),
+        };
+    }
+    /* ═══════════════════ DB ═══════════════════ */
+    #getRecipe(recipeId) {
+        const row = this.#db
+            .prepare(`SELECT id, title, coreCode, doClause, dontClause, whenClause, content, sourceRefs, headers
+         FROM knowledge_entries WHERE id = ?`)
+            .get(recipeId);
+        return row ?? null;
+    }
+    #persistRecipe(recipe) {
+        this.#db
+            .prepare(`UPDATE knowledge_entries
+         SET coreCode = ?, doClause = ?, dontClause = ?, whenClause = ?,
+             content = ?, sourceRefs = ?, headers = ?, updatedAt = ?
+         WHERE id = ?`)
+            .run(recipe.coreCode, recipe.doClause, recipe.dontClause, recipe.whenClause, recipe.content, recipe.sourceRefs, recipe.headers, Date.now(), recipe.id);
+    }
+    /* ═══════════════════ Helpers ═══════════════════ */
+    #skipResult(recipeId, patchSource, reason) {
+        this.#logger.info(`[ContentPatcher] Skipped for ${recipeId}: ${reason}`);
+        const emptySnapshot = {
+            coreCode: '',
+            doClause: '',
+            dontClause: '',
+            whenClause: '',
+            content: {},
+            sourceRefs: [],
+            headers: [],
+        };
+        return {
+            success: false,
+            recipeId,
+            fieldsPatched: [],
+            beforeSnapshot: emptySnapshot,
+            afterSnapshot: emptySnapshot,
+            patchSource,
+            skipped: true,
+            skipReason: reason,
+        };
+    }
+}
+/* ────────────────────── Util ────────────────────── */
+function safeJsonParse(json, fallback) {
+    if (!json) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}