autosnippet 3.0.10 → 3.0.13

package/lib/service/cursor/AgentInstructionsGenerator.js

@@ -0,0 +1,395 @@
+/**
+ * AgentInstructionsGenerator — 通用 AI Agent 指令文件生成器
+ *
+ * Channel F: 为多种 AI 编码工具生成项目指令文件
+ *   - AGENTS.md      → OpenAI Codex / 通用 Agent
+ *   - CLAUDE.md       → Claude Code
+ *   - .github/copilot-instructions.md → GitHub Copilot（动态版，替代静态模板）
+ *
+ * 设计原则：
+ *   1. 内容来源统一 — 从 _loadEntries() 已加载的知识条目中提取
+ *   2. 格式差异化 — 同一数据按目标工具特性适配输出
+ *   3. 轻量索引 — 只输出摘要和规则，详细内容引导至 MCP 工具
+ *   4. 幂等生成 — 每次 deliver 重写全部文件，不做增量 diff
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkWriteSafety, safeWriteFile } from './FileProtection.js';
+import { estimateTokens } from './TokenBudget.js';
+
+/**
+ * Agent 指令文件 token 预算
+ * AGENTS.md / CLAUDE.md 不受 Cursor 200K 限制，但需控制体积以便 Agent 快速消化
+ */
+const AGENT_BUDGET = Object.freeze({
+  MAX_RULES: 15,
+  MAX_PATTERNS: 10,
+  MAX_SKILLS: 10,
+  MAX_TOTAL_TOKENS: 3000,
+});
+
+/**
+ * MCP 工具清单 — 精简版（跟随实际 MCP handler 注册名称）
+ */
+const MCP_TOOLS_SUMMARY = [
+  { name: 'autosnippet_search', desc: 'Search knowledge base (mode: auto/context/keyword/semantic)' },
+  { name: 'autosnippet_knowledge', desc: 'Knowledge CRUD (operation: list/get/insights/confirm_usage)' },
+  { name: 'autosnippet_submit_knowledge', desc: 'Submit a knowledge candidate (strict validation)' },
+  { name: 'autosnippet_submit_knowledge_batch', desc: 'Batch submit candidates (with dedup + throttle)' },
+  { name: 'autosnippet_guard', desc: 'Code compliance check (single file or batch audit)' },
+  { name: 'autosnippet_structure', desc: 'Project structure discovery (targets/files/metadata)' },
+  { name: 'autosnippet_graph', desc: 'Knowledge graph query (query/impact/path/stats)' },
+  { name: 'autosnippet_skill', desc: 'Skill management (list/load/create/update/delete/suggest)' },
+  { name: 'autosnippet_save_document', desc: 'Save development document (auto-publish)' },
+  { name: 'autosnippet_bootstrap', desc: 'Project cold-start & scan (knowledge/refine/scan)' },
+  { name: 'autosnippet_health', desc: 'Service health & KB statistics' },
+  { name: 'autosnippet_capabilities', desc: 'List all available MCP tools (self-discovery)' },
+];
+
+export class AgentInstructionsGenerator {
+  /**
+   * @param {string} projectRoot
+   * @param {string} projectName
+   * @param {Object} [logger]
+   */
+  constructor(projectRoot, projectName = 'Project', logger = console) {
+    this.projectRoot = projectRoot;
+    this.projectName = projectName;
+    this.logger = logger;
+  }
+
+  /**
+   * 生成所有 Agent 指令文件
+   *
+   * @param {Object} params
+   * @param {Array<Object>} params.rules - kind='rule' 的条目（已排序）
+   * @param {Array<Object>} params.patterns - kind='pattern' 的条目（已排序）
+   * @param {string[]} params.skills - 可用 Skill 名称列表
+   * @returns {{ agents: Object, claude: Object, copilot: Object }}
+   */
+  generate({ rules = [], patterns = [], skills = [] }) {
+    const startTime = Date.now();
+
+    // 构建共享内容块
+    const sections = this._buildSections({ rules, patterns, skills });
+
+    // 生成 3 个目标文件
+    const agents = this._writeAgentsMd(sections);
+    const claude = this._writeClaudeMd(sections);
+    const copilot = this._writeCopilotInstructions(sections);
+
+    const duration = Date.now() - startTime;
+    const filesWritten = [agents, claude, copilot].filter((r) => !r.skipped).length;
+    const skippedFiles = [agents, claude, copilot].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] Generated ${filesWritten} files in ${duration}ms — ` +
+        `AGENTS.md: ${agents.tokensUsed}t, CLAUDE.md: ${claude.tokensUsed}t, ` +
+        `copilot-instructions: ${copilot.tokensUsed}t`
+    );
+
+    return {
+      agents,
+      claude,
+      copilot,
+      stats: {
+        filesWritten,
+        filesSkipped: skippedFiles.length,
+        totalTokens: agents.tokensUsed + claude.tokensUsed + copilot.tokensUsed,
+        duration,
+      },
+    };
+  }
+
+  // ─── 内容构建 ──────────────────────────────────────
+
+  /**
+   * 从知识条目构建共享内容段
+   * @private
+   */
+  _buildSections({ rules, patterns, skills }) {
+    // 编码规则（Channel A 格式，一行一条）
+    const ruleLines = rules
+      .slice(0, AGENT_BUDGET.MAX_RULES)
+      .filter((e) => e.doClause)
+      .map((e) => {
+        const langPrefix = e.language && e.scope !== 'universal' ? `[${e.language}] ` : '';
+        const doText = e.doClause.replace(/\.+$/, '');
+        let line = `${langPrefix}${doText}`;
+        if (e.dontClause) {
+          // 有明确否定词的统一为 "Do NOT"，否则保留原文（如 "Avoid ..."）
+          const hasNegPrefix = /^(Don't|Do not|Never)\s+/i.test(e.dontClause);
+          if (hasNegPrefix) {
+            const stripped = e.dontClause.replace(/^(Don't|Do not|Never)\s+/i, '').replace(/\.+$/, '');
+            line += `. Do NOT ${stripped}`;
+          } else {
+            line += `. ${e.dontClause.replace(/\.+$/, '')}`;
+          }
+        }
+        return `- ${line}.`;
+      });
+
+    // 架构模式（摘要表格行）
+    const patternRows = patterns
+      .slice(0, AGENT_BUDGET.MAX_PATTERNS)
+      .filter((e) => e.trigger && e.doClause)
+      .map((e) => {
+        const trigger = e.trigger.startsWith('@') ? e.trigger : `@${e.trigger}`;
+        const when = (e.whenClause || '').substring(0, 60);
+        const doText = (e.doClause || '').substring(0, 80);
+        return `| ${trigger} | ${when} | ${doText} |`;
+      });
+
+    // Skills 列表
+    const skillLines = skills
+      .slice(0, AGENT_BUDGET.MAX_SKILLS)
+      .map((s) => `- \`${s}\``);
+
+    // MCP 工具列表
+    const toolLines = MCP_TOOLS_SUMMARY.map(
+      (t) => `- \`${t.name}\` — ${t.desc}`
+    );
+
+    return { ruleLines, patternRows, skillLines, toolLines };
+  }
+
+  // ─── AGENTS.md ─────────────────────────────────────
+
+  /**
+   * @private
+   */
+  _writeAgentsMd(sections) {
+    const lines = [
+      `# ${this.projectName} — Agent Instructions`,
+      '',
+      '> Auto-generated by [AutoSnippet](https://github.com/anthropic/autosnippet). Do not edit manually.',
+      '> This file is regenerated when the knowledge base changes.',
+      '',
+      '## Project Knowledge Base',
+      '',
+      `This project uses **AutoSnippet** as its knowledge management system.`,
+      `The knowledge base contains coding standards, architecture patterns, and best practices`,
+      `accessible through MCP tools.`,
+      '',
+      ...this._renderConstraints(),
+      '',
+    ];
+
+    // Coding Standards
+    if (sections.ruleLines.length > 0) {
+      lines.push('## Coding Standards', '');
+      lines.push(...sections.ruleLines);
+      lines.push('');
+    }
+
+    // Architecture Patterns
+    if (sections.patternRows.length > 0) {
+      lines.push('## Architecture Patterns', '');
+      lines.push('| Trigger | When | Do |');
+      lines.push('|---------|------|----|');
+      lines.push(...sections.patternRows);
+      lines.push('');
+    }
+
+    // MCP Tools
+    lines.push('## MCP Tools (AutoSnippet)', '');
+    lines.push('Use these MCP tools to access the full knowledge base:', '');
+    lines.push(...sections.toolLines);
+    lines.push('');
+
+    // Skills
+    if (sections.skillLines.length > 0) {
+      lines.push('## Available Skills', '');
+      lines.push('Load with `autosnippet_skill({ operation: "load", name: "<skill>" })`:', '');
+      lines.push(...sections.skillLines);
+      lines.push('');
+    }
+
+    // Workflow
+    lines.push(...this._renderWorkflow());
+
+    const content = `${lines.join('\n')}\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 };
+  }
+
+  // ─── CLAUDE.md ─────────────────────────────────────
+
+  /**
+   * @private
+   */
+  _writeClaudeMd(sections) {
+    const lines = [
+      `# ${this.projectName} — Claude Code Instructions`,
+      '',
+      '> Auto-generated by AutoSnippet. Regenerated when knowledge base changes.',
+      '',
+    ];
+
+    // Constraints (Claude prefers clear bullet points)
+    lines.push(...this._renderConstraints());
+    lines.push('');
+
+    // Coding Standards
+    if (sections.ruleLines.length > 0) {
+      lines.push('## Coding Standards', '');
+      lines.push('These are mandatory project rules extracted from the knowledge base:', '');
+      lines.push(...sections.ruleLines);
+      lines.push('');
+    }
+
+    // Patterns (Claude benefits from When/Do format)
+    if (sections.patternRows.length > 0) {
+      lines.push('## Key Patterns', '');
+      lines.push('| Trigger | When | Do |');
+      lines.push('|---------|------|----|');
+      lines.push(...sections.patternRows);
+      lines.push('');
+    }
+
+    // MCP — Claude Code natively supports MCP
+    lines.push('## MCP Integration', '');
+    lines.push(
+      'This project has an AutoSnippet MCP server configured. ',
+      'Use the following tools to access project knowledge:',
+      ''
+    );
+    lines.push(...sections.toolLines);
+    lines.push('');
+
+    // Key tools highlight for Claude
+    lines.push('### Recommended Workflow', '');
+    lines.push('1. **Before writing code**: `autosnippet_search({ query: "<topic>" })` to find relevant patterns');
+    lines.push('2. **Check compliance**: `autosnippet_guard({ code: "<your code>" })` before committing');
+    lines.push('3. **Record knowledge**: `autosnippet_submit_knowledge({ ... })` when discovering reusable patterns');
+    lines.push('4. **Confirm adoption**: `autosnippet_knowledge({ operation: "confirm_usage", id: "<id>" })`');
+    lines.push('');
+
+    // Skills
+    if (sections.skillLines.length > 0) {
+      lines.push('## Skills', '');
+      lines.push(...sections.skillLines);
+      lines.push('');
+    }
+
+    const content = `${lines.join('\n')}\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 };
+  }
+
+  // ─── copilot-instructions.md ───────────────────────
+
+  /**
+   * 动态生成 copilot-instructions.md
+   * 替代原有的静态模板复制
+   * @private
+   */
+  _writeCopilotInstructions(sections) {
+    const lines = [
+      '# AutoSnippet Copilot Instructions',
+      '',
+      '## Project Overview',
+      `- Project: **${this.projectName}**`,
+      '- Knowledge System: AutoSnippet V3 (ESM, SQLite, MCP)',
+      '- Knowledge Base: `AutoSnippet/` directory (recipes, skills, constitution)',
+      '',
+      ...this._renderConstraints(),
+      '',
+    ];
+
+    // Coding Standards
+    if (sections.ruleLines.length > 0) {
+      lines.push('## Coding Standards', '');
+      lines.push(...sections.ruleLines);
+      lines.push('');
+    }
+
+    // MCP Tools (compact for Copilot)
+    lines.push('## MCP Tools', '');
+    lines.push('Access the knowledge base through MCP:', '');
+    // Copilot: show fewer, most essential tools
+    const essentialTools = [
+      '- `autosnippet_search` — Search knowledge (mode: auto/context/keyword/semantic)',
+      '- `autosnippet_knowledge` — Browse/get recipes (operation: list/get/insights)',
+      '- `autosnippet_submit_knowledge` — Submit candidate (strict validation, all fields required)',
+      '- `autosnippet_guard` — Code compliance check',
+      '- `autosnippet_skill` — Load project skills (list/load)',
+      '- `autosnippet_health` — Service health & KB stats',
+    ];
+    lines.push(...essentialTools);
+    lines.push('');
+
+    // Knowledge Types
+    lines.push('## Knowledge Types', '');
+    lines.push('- **rule** — Coding standards, enforced by Guard');
+    lines.push('- **pattern** — Reusable code patterns and architecture');
+    lines.push('- **fact** — Structural knowledge (relations, data flow)');
+    lines.push('');
+
+    // Workflow
+    lines.push('## Workflow', '');
+    lines.push('1. Search before coding: `autosnippet_search({ query: "..." })`');
+    lines.push('2. Prefer Recipe over raw source code');
+    lines.push('3. Submit discoveries: `autosnippet_submit_knowledge({ ... })`');
+    lines.push('4. Do NOT directly modify `AutoSnippet/` or `.autosnippet/` files');
+    lines.push('');
+
+    const content = `${lines.join('\n')}\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 };
+  }
+
+  // ─── 共享模板片段 ──────────────────────────────────
+
+  /**
+   * 核心约束（所有 Agent 共享）
+   * @private
+   */
+  _renderConstraints() {
+    return [
+      '## Mandatory Constraints',
+      '',
+      '1. **Do NOT modify** knowledge base files directly (`AutoSnippet/recipes/`, `.autosnippet/`).',
+      '2. Create or update knowledge **only** through MCP tools (`autosnippet_submit_knowledge`).',
+      '3. **Prefer Recipes** as project standards; source code is supplementary.',
+      '4. Use `autosnippet_search` for knowledge retrieval; do not retry on failure in the same turn.',
+      '5. Skills handle semantics and workflow; MCP handles capabilities — do not hardcode URLs in Skills.',
+    ];
+  }
+
+  /**
+   * 推荐工作流（AGENTS.md 用）
+   * @private
+   */
+  _renderWorkflow() {
+    return [
+      '## Recommended Workflow',
+      '',
+      '1. **Search first**: `autosnippet_search({ query: "<topic>" })` before writing code',
+      '2. **Check patterns**: Look for existing `@trigger` patterns before implementing',
+      '3. **Guard check**: `autosnippet_guard({ code: "<code>" })` to validate compliance',
+      '4. **Submit discoveries**: `autosnippet_submit_knowledge({ ... })` for reusable patterns',
+      '5. **Confirm adoption**: `autosnippet_knowledge({ operation: "confirm_usage" })`',
+      '',
+    ];
+  }
+}
+
+export default AgentInstructionsGenerator;

package/lib/service/cursor/CursorDeliveryPipeline.js

@@ -1,7 +1,14 @@
 /**
- * CursorDeliveryPipeline — 4 通道交付主入口
+ * CursorDeliveryPipeline — 6 通道交付主入口
  *
- * 读取知识库 → 筛选 + 分类 + 排序 + 压缩 → 写入 4 个 Cursor 通道
+ * 读取知识库 → 筛选 + 分类 + 排序 + 压缩 → 写入 6 个通道
+ *
+ * Channel A: .cursor/rules/autosnippet-project-rules.mdc (alwaysApply rules)
+ * Channel B: .cursor/rules/autosnippet-patterns-{topic}.mdc (smart rules)
+ * Channel C: .cursor/skills/ (project skills sync)
+ * Channel D: .cursor/skills/autosnippet-devdocs/ (dev documents)
+ * Channel F: AGENTS.md + CLAUDE.md + .github/copilot-instructions.md (agent instructions)
+ * + Mirror: .qoder/ .trae/ (IDE mirror)
  *
  * 触发时机：
  *   1. bootstrap 完成后自动触发
@@ -13,6 +20,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { DELIVERY_RANK, KNOWLEDGE_CONFIDENCE } from '../../shared/constants.js';
+import { AgentInstructionsGenerator } from './AgentInstructionsGenerator.js';
 import { KnowledgeCompressor } from './KnowledgeCompressor.js';
 import { RulesGenerator } from './RulesGenerator.js';
 import { SkillsSyncer } from './SkillsSyncer.js';
@@ -38,11 +46,12 @@ export class CursorDeliveryPipeline {
     this.topicClassifier = new TopicClassifier(this.projectName);
     this.rulesGenerator = new RulesGenerator(projectRoot, this.projectName);
     this.skillsSyncer = new SkillsSyncer(projectRoot, this.projectName, knowledgeService);
+    this.agentInstructions = new AgentInstructionsGenerator(projectRoot, this.projectName, logger);
   }
 
   /**
-   * 完整交付流程 — 生成 4 通道 Cursor 消费物料
-   * @returns {Promise<{ channelA: Object, channelB: Object, channelC: Object, stats: Object }>}
+   * 完整交付流程 — 生成 6 通道消费物料
+   * @returns {Promise<{ channelA: Object, channelB: Object, channelC: Object, channelD: Object, channelF: Object, stats: Object }>}
    */
   async deliver() {
     const startTime = Date.now();
@@ -51,6 +60,7 @@ export class CursorDeliveryPipeline {
       channelB: { topicCount: 0, patternsCount: 0, totalTokens: 0 },
       channelC: { synced: 0, skipped: 0, errors: 0 },
       channelD: { documentsCount: 0, filesWritten: 0 },
+      channelF: { filesWritten: 0, totalTokens: 0 },
       totalTokensUsed: 0,
       duration: 0,
     };
@@ -85,12 +95,13 @@ export class CursorDeliveryPipeline {
       const channelD = this._generateChannelD(documents);
       stats.channelD = channelD;
 
-      // 统计
-      // ── Mirror to .qoder/ & .trae/ ──
-      this._mirrorToIDE('.qoder');
-      this._mirrorToIDE('.trae');
+      // ── Channel F: Agent Instructions (AGENTS.md / CLAUDE.md / copilot-instructions) ──
+      const channelF = this._generateChannelF(rules, patterns);
+      stats.channelF = channelF;
+
+      // NOTE: .qoder/ .trae/ 镜像不再自动执行，由 `asd mirror` 按需触发
 
-      stats.totalTokensUsed = channelA.tokensUsed + channelB.totalTokens;
+      stats.totalTokensUsed = channelA.tokensUsed + channelB.totalTokens + (channelF.totalTokens || 0);
       stats.duration = Date.now() - startTime;
 
       this.logger.info?.(
@@ -98,10 +109,11 @@ export class CursorDeliveryPipeline {
           `A: ${channelA.rulesCount} rules (${channelA.tokensUsed} tokens), ` +
           `B: ${channelB.topicCount} topics (${channelB.totalTokens} tokens), ` +
           `C: ${channelC.synced} skills synced, ` +
-          `D: ${channelD.documentsCount} documents`
+          `D: ${channelD.documentsCount} documents, ` +
+          `F: ${channelF.filesWritten} agent files`
       );
 
-      return { channelA, channelB, channelC, channelD, stats };
+      return { channelA, channelB, channelC, channelD, channelF, stats };
     } catch (error) {
       this.logger.error?.(`[CursorDelivery] Error: ${error.message}`);
       throw error;
@@ -403,6 +415,53 @@ export class CursorDeliveryPipeline {
     return result;
   }
 
+  /**
+   * Channel F — Agent Instructions 生成
+   * 生成 AGENTS.md / CLAUDE.md / .github/copilot-instructions.md
+   * @private
+   */
+  _generateChannelF(rules, patterns) {
+    try {
+      // 收集可用 Skills 名称
+      const skillsDir = path.join(this.projectRoot, 'AutoSnippet', 'skills');
+      let skills = [];
+      if (fs.existsSync(skillsDir)) {
+        skills = fs
+          .readdirSync(skillsDir, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+          .map((d) => d.name);
+      }
+
+      // 排序后传入
+      const rankedRules = this._rank(rules);
+      const rankedPatterns = this._rank(patterns);
+
+      const result = this.agentInstructions.generate({
+        rules: rankedRules,
+        patterns: rankedPatterns,
+        skills,
+      });
+
+      this.logger.info?.(
+        `[CursorDelivery] Channel F: ${result.stats.filesWritten} agent instruction files ` +
+          `(${result.stats.totalTokens} tokens)`
+      );
+
+      return {
+        filesWritten: result.stats.filesWritten,
+        totalTokens: result.stats.totalTokens,
+        files: {
+          agents: result.agents.filePath,
+          claude: result.claude.filePath,
+          copilot: result.copilot.filePath,
+        },
+      };
+    } catch (err) {
+      this.logger.warn?.(`[CursorDelivery] Channel F error (non-blocking): ${err.message}`);
+      return { filesWritten: 0, totalTokens: 0, files: {} };
+    }
+  }
+
   /**
    * 文件名安全 slug 化
    * @private

package/lib/service/cursor/FileProtection.js

@@ -0,0 +1,116 @@
+/**
+ * FileProtection — 非 AutoSnippet 独有文件的写入保护
+ *
+ * 保护逻辑：
+ *   - 如果目标文件不存在 → 直接写入（首次生成）
+ *   - 如果目标文件存在且包含 AutoSnippet 签名 → 允许覆盖（我们生成的）
+ *   - 如果目标文件存在但不包含 AutoSnippet 签名 → 拒绝覆盖（用户原有文件）
+ *
+ * 签名标记（任意一个匹配即视为 AutoSnippet 所有）：
+ *   - "Auto-generated by AutoSnippet"
+ *   - "Auto-generated by [AutoSnippet]"
+ *   - "auto-generated by autosnippet" (case-insensitive)
+ */
+
+import fs from 'node:fs';
+
+/**
+ * AutoSnippet 文件签名模式（case-insensitive）
+ * 检查文件前 1024 字节即可——签名总在文件头部
+ */
+const SIGNATURE_PATTERN = /auto-generated by (?:\[)?autosnippet(?:\])?/i;
+
+/**
+ * 检查文件是否可以被 AutoSnippet 安全写入
+ *
+ * @param {string} filePath - 目标文件绝对路径
+ * @returns {{ canWrite: boolean, reason: string }}
+ *   - canWrite: true  → 可以安全写入
+ *   - canWrite: false → 文件存在且非 AutoSnippet 生成，不应覆盖
+ */
+export function checkWriteSafety(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { canWrite: true, reason: 'file-not-exist' };
+  }
+
+  try {
+    // 只读前 1024 字节检测签名，避免大文件全量读取
+    const fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(1024);
+    const bytesRead = fs.readSync(fd, buf, 0, 1024, 0);
+    fs.closeSync(fd);
+
+    const header = buf.toString('utf8', 0, bytesRead);
+    if (SIGNATURE_PATTERN.test(header)) {
+      return { canWrite: true, reason: 'autosnippet-owned' };
+    }
+
+    return { canWrite: false, reason: 'user-owned' };
+  } catch {
+    // 读取失败（权限等问题），保守处理：不覆盖
+    return { canWrite: false, reason: 'read-error' };
+  }
+}
+
+/**
+ * 安全写入文件 — 带保护机制
+ *
+ * @param {string} filePath - 目标文件绝对路径
+ * @param {string} content - 文件内容
+ * @param {Object} [options]
+ * @param {boolean} [options.force=false] - 强制覆盖（忽略保护）
+ * @param {Object} [options.logger] - 日志器
+ * @returns {{ written: boolean, reason: string, filePath: string }}
+ */
+export function safeWriteFile(filePath, content, options = {}) {
+  const { force = false, logger } = options;
+
+  if (force) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    return { written: true, reason: 'force', filePath };
+  }
+
+  const { canWrite, reason } = checkWriteSafety(filePath);
+
+  if (canWrite) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    return { written: true, reason, filePath };
+  }
+
+  // 用户原有文件 → 跳过
+  logger?.info?.(
+    `[FileProtection] Skipped "${filePath}" — ${reason} (file exists and is not AutoSnippet-generated)`
+  );
+  return { written: false, reason, filePath };
+}
+
+/**
+ * 安全复制文件 — 带保护机制
+ *
+ * @param {string} srcPath - 源文件路径
+ * @param {string} destPath - 目标文件路径
+ * @param {Object} [options]
+ * @param {boolean} [options.force=false] - 强制覆盖
+ * @param {Object} [options.logger] - 日志器
+ * @returns {{ written: boolean, reason: string, filePath: string }}
+ */
+export function safeCopyFile(srcPath, destPath, options = {}) {
+  const { force = false, logger } = options;
+
+  if (force) {
+    fs.copyFileSync(srcPath, destPath);
+    return { written: true, reason: 'force', filePath: destPath };
+  }
+
+  const { canWrite, reason } = checkWriteSafety(destPath);
+
+  if (canWrite) {
+    fs.copyFileSync(srcPath, destPath);
+    return { written: true, reason, filePath: destPath };
+  }
+
+  logger?.info?.(
+    `[FileProtection] Skipped "${destPath}" — ${reason} (file exists and is not AutoSnippet-generated)`
+  );
+  return { written: false, reason, filePath: destPath };
+}