autosnippet 2.6.0 → 2.7.1

package/lib/service/guard/ExclusionManager.js

@@ -7,6 +7,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import Logger from '../../infrastructure/logging/Logger.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 export class ExclusionManager {
   #exclusionsPath;
@@ -15,6 +16,7 @@ export class ExclusionManager {
   constructor(projectRoot, options = {}) {
     const kbDir = options.knowledgeBaseDir || 'AutoSnippet';
     this.#exclusionsPath = join(projectRoot, kbDir, 'guard-exclusions.json');
+    pathGuard.assertProjectWriteSafe(this.#exclusionsPath);
     // 迁移旧路径
     this.#migrateOldPath(projectRoot, options.internalDir || '.autosnippet');
     this.#data = this.#load();

package/lib/service/guard/RuleLearner.js

@@ -7,6 +7,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import Logger from '../../infrastructure/logging/Logger.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 const PROBLEMATIC_THRESHOLD = { falsePositiveRate: 0.3, minTriggers: 5 };
 
@@ -17,6 +18,7 @@ export class RuleLearner {
   constructor(projectRoot, options = {}) {
     const kbDir = options.knowledgeBaseDir || 'AutoSnippet';
     this.#learnerPath = join(projectRoot, kbDir, 'guard-learner.json');
+    pathGuard.assertProjectWriteSafe(this.#learnerPath);
     this.#migrateOldPath(projectRoot, options.internalDir || '.autosnippet');
     this.#data = this.#load();
   }

package/lib/service/quality/FeedbackCollector.js

@@ -6,6 +6,7 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import pathGuard from '../../shared/PathGuard.js';
 
 export class FeedbackCollector {
   #feedbackPath;
@@ -15,6 +16,7 @@ export class FeedbackCollector {
   constructor(projectRoot, options = {}) {
     const kbDir = options.knowledgeBaseDir || 'AutoSnippet';
     this.#feedbackPath = join(projectRoot, kbDir, 'feedback.json');
+    pathGuard.assertProjectWriteSafe(this.#feedbackPath);
     this.#maxEvents = options.maxEvents || 1000;
     this.#migrateOldPath(projectRoot, options.internalDir || '.autosnippet');
     this.#events = this.#load();

package/lib/service/recipe/RecipeFileWriter.js

@@ -19,6 +19,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { RECIPES_DIR } from '../../infrastructure/config/Defaults.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 export class RecipeFileWriter {
   /**
@@ -160,6 +161,9 @@ export class RecipeFileWriter {
       const category = (recipe.category || 'general').toLowerCase();
       const categoryDir = path.join(this.recipesDir, category);
 
+      // 路径安全检查 — 阻止 category 含 ../ 导致路径逃逸
+      pathGuard.assertProjectWriteSafe(categoryDir);
+
       if (!fs.existsSync(categoryDir)) {
         fs.mkdirSync(categoryDir, { recursive: true });
       }
@@ -300,7 +304,18 @@ export class RecipeFileWriter {
     }
     if (recipe.content?.steps?.length > 0) {
       parts.push('### 使用步骤\n');
-      recipe.content.steps.forEach((step, i) => { parts.push(`${i + 1}. ${step}`); });
+      recipe.content.steps.forEach((step, i) => {
+        if (typeof step === 'string') {
+          parts.push(`${i + 1}. ${step}`);
+        } else {
+          const title = step.title || '';
+          const desc = step.description || '';
+          const code = step.code || '';
+          const text = [title, desc].filter(Boolean).join(': ');
+          parts.push(`${i + 1}. ${text || '(步骤)'}`);
+          if (code) { parts.push(''); parts.push(`\`\`\`\n${code}\n\`\`\``); }
+        }
+      });
       parts.push('');
     }
     if (recipe.constraints?.boundaries?.length > 0) {

package/lib/service/recipe/RecipeStatsTracker.js

@@ -7,6 +7,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import Logger from '../../infrastructure/logging/Logger.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 const SCHEMA_VERSION = 1;
 const DEFAULT_HEAT_WEIGHTS = { guard: 1.0, human: 2.0, ai: 1.5 };
@@ -19,6 +20,7 @@ export class RecipeStatsTracker {
   constructor(projectRoot, options = {}) {
     const kbDir = options.knowledgeBaseDir || 'AutoSnippet';
     this.#statsPath = join(projectRoot, kbDir, 'recipe-stats.json');
+    pathGuard.assertProjectWriteSafe(this.#statsPath);
     this.#migrateOldPath(projectRoot, options.internalDir || '.autosnippet');
     this.#data = this.#load();
   }

package/lib/service/skills/SignalCollector.js

@@ -42,6 +42,7 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import Logger from '../../infrastructure/logging/Logger.js';
 import { EventAggregator } from './EventAggregator.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 const DEFAULT_INTERVAL_MS = 60 * 60 * 1000;  // 1 小时（初始值，AI 可动态调整）
 const MIN_INTERVAL_MS = 5 * 60 * 1000;       // 最短 5 分钟
@@ -76,14 +77,14 @@ export class SignalCollector {
     projectRoot,
     database = null,
     chatAgent = null,
-    mode = 'suggest',
+    mode = 'auto',
     intervalMs = DEFAULT_INTERVAL_MS,
     onSuggestions = null,
   }) {
     this.#projectRoot = projectRoot;
     this.#db = database;
     this.#chatAgent = chatAgent;
-    this.#mode = ['off', 'suggest', 'auto'].includes(mode) ? mode : 'suggest';
+    this.#mode = ['off', 'suggest', 'auto'].includes(mode) ? mode : 'auto';
     this.#intervalMs = Math.max(Math.min(intervalMs, MAX_INTERVAL_MS), MIN_INTERVAL_MS);
     this.#logger = Logger.getInstance();
     this.#onSuggestions = onSuggestions;
@@ -160,6 +161,16 @@ export class SignalCollector {
   getSnapshot() { return { ...this.#snapshot }; }
   getMode() { return this.#mode; }
 
+  /** 从 pendingSuggestions 中移除已创建的 Skill */
+  removePendingSuggestion(name) {
+    if (!this.#snapshot.pendingSuggestions?.length) return;
+    this.#snapshot.pendingSuggestions = this.#snapshot.pendingSuggestions.filter(s => s.name !== name);
+    if (this.#snapshot.lastResult) {
+      this.#snapshot.lastResult.newSuggestions = this.#snapshot.pendingSuggestions.length;
+    }
+    this.#saveSnapshot();
+  }
+
   setMode(mode) {
     if (!['off', 'suggest', 'auto'].includes(mode)) return;
     this.#mode = mode;
@@ -211,6 +222,17 @@ export class SignalCollector {
         newSuggestions: newSuggestions.length,
         aiToolCalls: toolCalls?.length || 0,
       };
+      // 持久化 AI 生成的建议，供前端直接读取
+      if (newSuggestions.length > 0) {
+        this.#snapshot.pendingSuggestions = newSuggestions.map(s => ({
+          name: s.name,
+          description: s.description || s.reason || '',
+          rationale: s.rationale || s.reason || '',
+          body: s.body || '',
+          source: s.source || 'signal-collector',
+          priority: s.priority || 'medium',
+        }));
+      }
 
       if (newSuggestions.length > 0) {
         for (const s of newSuggestions) {
@@ -403,14 +425,16 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
 
 1. 综合分析以上 6 个维度的信号
 2. 识别重复模式、高频错误、未覆盖的操作
-3. 给出 Skill 推荐建议（名称、原因、优先级、推荐 body）
-4. 根据信号密度判断下次分析应间隔多久（5-1440 分钟）
-5. 给出简要分析摘要
+3. **只推荐项目特有的知识模式**，不要推荐通用编程知识（如 Git 基础、语言语法等）
+4. 推荐的 Skill 应该能固化团队/项目的独有约定、架构决策或反复出现的问题解决方案
+5. 根据信号密度判断下次分析应间隔多久（5-1440 分钟）
+6. 给出简要分析摘要
+7. 如果没有发现值得推荐的项目特有模式，返回空的 suggestions 数组
 
 ## 输出格式
 
 在你的回复最后一行，输出一个 JSON 对象（不要包在 markdown code block 中）：
-{"suggestions":[{"name":"skill-name","reason":"推荐原因","priority":"high|medium|low","body":"推荐的 Skill 内容"}],"nextIntervalMinutes":60,"summary":"一句话分析摘要"}`;
+{"suggestions":[{"name":"skill-name","description":"一句话中文描述","reason":"推荐原因","priority":"high|medium|low","body":"推荐的 Skill 内容"}],"nextIntervalMinutes":60,"summary":"一句话分析摘要"}`;
   }
 
   // ═══════════════════════════════════════════════════════
@@ -473,6 +497,7 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
           lastResult: data.lastResult || null,
           lastAiSummary: data.lastAiSummary || '',
           autoCreated: Array.isArray(data.autoCreated) ? data.autoCreated : [],
+          pendingSuggestions: Array.isArray(data.pendingSuggestions) ? data.pendingSuggestions : [],
         };
       }
     } catch { /* corrupt — reset */ }
@@ -484,6 +509,7 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
       lastResult: null,
       lastAiSummary: '',
       autoCreated: [],
+      pendingSuggestions: [],
     };
   }
 
@@ -500,6 +526,7 @@ ${JSON.stringify(signals.codeChanges, null, 2)}
       }
 
       const dir = path.dirname(this.#snapshotPath);
+      pathGuard.assertProjectWriteSafe(dir);
       if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
       }

package/lib/service/skills/SkillAdvisor.js

@@ -17,6 +17,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { getProjectSkillsPath } from '../../infrastructure/config/Paths.js';
 
 export class SkillAdvisor {
   #projectRoot;
@@ -299,7 +300,7 @@ export class SkillAdvisor {
    */
   #listExistingProjectSkills() {
     const names = new Set();
-    const dir = path.join(this.#projectRoot, '.autosnippet', 'skills');
+    const dir = getProjectSkillsPath(this.#projectRoot);
     try {
       fs.readdirSync(dir, { withFileTypes: true })
         .filter(d => d.isDirectory())

package/lib/service/skills/SkillHooks.js

@@ -10,18 +10,26 @@
  *   - onGuardCheck(violation, ctx) → violation (可修改)
  *   - onBootstrapComplete(stats, ctx) → void
  *
- * 加载顺序: 内置 skills/ → 项目级 .autosnippet/skills/（同名覆盖）
+ * 加载顺序: 内置 skills/ → 项目级 AutoSnippet/skills/（同名覆盖）
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { getProjectSkillsPath } from '../../infrastructure/config/Paths.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = path.resolve(__dirname, '../../..');
-const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
-const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
+const SKILLS_DIR = path.resolve(__dirname, '../../../skills');
+
+/**
+ * 获取项目级 Skills 目录（运行时动态解析）
+ * 路径: {projectRoot}/AutoSnippet/skills/
+ */
+function _getProjectSkillsDir() {
+  const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
+  return getProjectSkillsPath(projectRoot);
+}
 
 const HOOK_NAMES = [
   'onCandidateSubmit',
@@ -48,7 +56,7 @@ export class SkillHooks {
     await this.#loadFromDir(SKILLS_DIR, loaded);
 
     // 2. 项目级 skills（覆盖同名）
-    await this.#loadFromDir(PROJECT_SKILLS_DIR, loaded);
+    await this.#loadFromDir(_getProjectSkillsDir(), loaded);
 
     // 3. 注册所有钩子
     for (const [skillName, mod] of loaded) {

package/lib/service/spm/SpmService.js

@@ -650,7 +650,7 @@ export class SpmService {
     const CODE_EXTS = isDirectoryTarget
       ? new Set(['.swift', '.m', '.mm', '.h', '.c', '.cpp', '.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.vue', '.mjs', '.cjs'])
       : new Set(['.swift', '.m', '.h', '.c', '.cpp', '.mm']);
-    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
+    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', 'Carthage', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
     const MAX_FILES = 300;
 
     const files = [];
@@ -889,7 +889,7 @@ export class SpmService {
       // 非 SPM 项目：直接扫描常见源码目录（fallback）
       this.#logger.info('[SpmService] scanProject: No SPM targets, falling back to directory scan');
       const CODE_EXTS = new Set(['.swift', '.m', '.mm', '.h', '.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.vue', '.mjs', '.cjs']);
-      const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
+      const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', 'Carthage', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
       const srcDirs = ['Sources', 'src', 'lib', 'app', 'pages', 'components', 'modules', 'packages'];
 
       const walkDir = (dir, targetName) => {

package/lib/shared/PathGuard.js

@@ -0,0 +1,314 @@
+/**
+ * PathGuard — 文件写入路径安全守卫（双层防护）
+ *
+ * 防止 AutoSnippet 在项目目录之外 或 项目内非法位置 创建文件。
+ * BiliDemo/data 事件的根因：process.cwd() 解析到非预期目录，DB/日志等写操作
+ * 逃逸到用户项目外，创建了脏数据。
+ *
+ * 双层防护：
+ *  Layer 1 — assertSafe(path):
+ *    边界检查，拦截写到 projectRoot 外的操作
+ *  Layer 2 — assertProjectWriteSafe(path):
+ *    项目内作用域检查，仅允许写入以下前缀：
+ *      .autosnippet/     — 运行时 DB、记忆、对话、信号快照
+ *      {kbDir}/          — 知识库（recipes、candidates、skills、guard 文件）
+ *      .cursor/          — Cursor IDE 集成
+ *      .vscode/          — VSCode 集成
+ *      .github/          — Copilot instructions
+ *      .gitignore        — 追加忽略规则
+ *    项目内其他位置（如 data/、src/ 等）一律拦截
+ *
+ * 设计：
+ *  - 单例模式，通过 configure() 绑定 projectRoot
+ *  - 新建文件/目录前调用 assertProjectWriteSafe() 校验
+ *  - 修改已有文件前调用 assertSafe() 校验（不限制项目内位置）
+ *  - 允许白名单目录（Xcode snippets、全局缓存等）
+ *  - 错误不静默：越界写操作抛出 PathGuardError
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+export class PathGuardError extends Error {
+  /**
+   * @param {string} targetPath - 被拦截的目标路径
+   * @param {string} projectRoot - 当前项目根目录
+   * @param {string} [reason] - 拦截原因
+   */
+  constructor(targetPath, projectRoot, reason) {
+    const msg = reason
+      ? `[PathGuard] ${reason}: "${targetPath}"`
+      : `[PathGuard] 写入路径越界: "${targetPath}" 不在允许范围内。`;
+    super(
+      msg +
+      `\n  projectRoot: ${projectRoot}` +
+      `\n  提示: 检查 process.cwd() 或 projectRoot 配置是否正确`
+    );
+    this.name = 'PathGuardError';
+    this.targetPath = targetPath;
+    this.projectRoot = projectRoot;
+  }
+}
+
+/**
+ * 项目内允许 AutoSnippet 创建新文件/目录的前缀
+ * 注意：这是相对于 projectRoot 的前缀列表
+ */
+const PROJECT_WRITE_SCOPE_PREFIXES = [
+  '.autosnippet',       // 运行时 DB、记忆、对话、信号快照
+  '.cursor',            // Cursor IDE 集成
+  '.vscode',            // VSCode 集成
+  '.github',            // Copilot instructions
+];
+
+/**
+ * 项目根目录下允许直接写入的文件（非目录前缀匹配）
+ */
+const PROJECT_ROOT_WRITABLE_FILES = [
+  '.gitignore',
+  '.env',
+];
+
+class PathGuard {
+  /** @type {string|null} 项目根目录（绝对路径） */
+  #projectRoot = null;
+
+  /** @type {string|null} AutoSnippet 包自身根目录 */
+  #packageRoot = null;
+
+  /** @type {Set<string>} 额外允许的绝对路径前缀 */
+  #allowList = new Set();
+
+  /** @type {string|null} 知识库目录名（如 'AutoSnippet'） */
+  #knowledgeBaseDir = null;
+
+  /** @type {boolean} 是否已配置 */
+  #configured = false;
+
+  constructor() {}
+
+  /**
+   * 配置 PathGuard（每个进程执行一次）
+   * @param {object} opts
+   * @param {string} opts.projectRoot - 用户项目根目录（绝对路径）
+   * @param {string} [opts.packageRoot] - AutoSnippet 包自身根目录
+   * @param {string} [opts.knowledgeBaseDir='AutoSnippet'] - 知识库目录名
+   * @param {string[]} [opts.extraAllowPaths] - 额外允许的路径前缀
+   */
+  configure({ projectRoot, packageRoot, knowledgeBaseDir, extraAllowPaths = [] }) {
+    if (!projectRoot || !path.isAbsolute(projectRoot)) {
+      throw new Error(`[PathGuard] projectRoot 必须是绝对路径，收到: "${projectRoot}"`);
+    }
+
+    this.#projectRoot = path.resolve(projectRoot);
+    this.#packageRoot = packageRoot ? path.resolve(packageRoot) : null;
+    this.#knowledgeBaseDir = knowledgeBaseDir || null;  // 延迟解析
+
+    // 默认白名单：Xcode snippets 目录、全局缓存
+    const HOME = process.env.HOME || process.env.USERPROFILE || '';
+    if (HOME) {
+      this.#allowList.add(path.join(HOME, 'Library/Developer/Xcode/UserData/CodeSnippets'));
+      this.#allowList.add(path.join(HOME, '.autosnippet'));
+    }
+
+    // 用户自定义白名单
+    for (const p of extraAllowPaths) {
+      if (path.isAbsolute(p)) {
+        this.#allowList.add(path.resolve(p));
+      }
+    }
+
+    this.#configured = true;
+  }
+
+  /** 是否已配置 */
+  get configured() {
+    return this.#configured;
+  }
+
+  /** 当前 projectRoot */
+  get projectRoot() {
+    return this.#projectRoot;
+  }
+
+  /**
+   * 设置知识库目录名（可在 configure 之后延迟设置）
+   * @param {string} dirName - 如 'AutoSnippet'、'Knowledge' 等
+   */
+  setKnowledgeBaseDir(dirName) {
+    if (dirName && typeof dirName === 'string') {
+      this.#knowledgeBaseDir = dirName;
+    }
+  }
+
+  /**
+   * Layer 1: 断言路径在允许的边界范围内
+   * 用于修改已有文件的场景（如 XcodeIntegration 插入 header、SpmService 修改 Package.swift）
+   * @param {string} targetPath - 要写入的绝对路径
+   * @throws {PathGuardError}
+   */
+  assertSafe(targetPath) {
+    if (!this.#configured) return;
+
+    if (!targetPath || typeof targetPath !== 'string') {
+      throw new PathGuardError(String(targetPath), this.#projectRoot);
+    }
+
+    const resolved = path.resolve(targetPath);
+
+    // 1. 项目目录内 — 允许
+    if (this.#isUnder(resolved, this.#projectRoot)) return;
+
+    // 2. AutoSnippet 包自身目录内（logs/ 等）— 允许
+    if (this.#packageRoot && this.#isUnder(resolved, this.#packageRoot)) return;
+
+    // 3. 白名单目录 — 允许
+    for (const allowed of this.#allowList) {
+      if (this.#isUnder(resolved, allowed)) return;
+    }
+
+    // 越界
+    throw new PathGuardError(resolved, this.#projectRoot);
+  }
+
+  /**
+   * Layer 2: 断言路径在项目内允许的写入作用域中
+   * 用于创建新目录/新文件的场景（如 mkdirSync、writeFileSync 创建新文件）
+   * 比 assertSafe() 更严格：即使在 projectRoot 内，也只允许写入特定前缀
+   * @param {string} targetPath - 要创建的绝对路径
+   * @throws {PathGuardError}
+   */
+  assertProjectWriteSafe(targetPath) {
+    if (!this.#configured) return;
+
+    // 先做边界检查
+    this.assertSafe(targetPath);
+
+    const resolved = path.resolve(targetPath);
+
+    // 如果不在 projectRoot 内（在白名单/packageRoot 中），跳过项目内检查
+    if (!this.#isUnder(resolved, this.#projectRoot)) return;
+
+    // 计算相对于 projectRoot 的路径
+    const relative = path.relative(this.#projectRoot, resolved);
+    const firstSegment = relative.split(path.sep)[0];
+
+    // 检查是否在允许的前缀中
+    for (const prefix of PROJECT_WRITE_SCOPE_PREFIXES) {
+      if (firstSegment === prefix) return;
+    }
+
+    // 检查知识库目录（动态解析）
+    const kbDir = this.#resolveKnowledgeBaseDir();
+    if (kbDir && firstSegment === kbDir) return;
+
+    // 检查根目录可写文件（如 .gitignore）
+    if (PROJECT_ROOT_WRITABLE_FILES.includes(relative)) return;
+
+    // 不在允许的写入范围内
+    throw new PathGuardError(
+      resolved,
+      this.#projectRoot,
+      `项目内写入范围受限: "${relative}" 不在允许的目录中（允许: ${[...PROJECT_WRITE_SCOPE_PREFIXES, kbDir || 'AutoSnippet'].join(', ')}）`,
+    );
+  }
+
+  /**
+   * 安全检查（不抛错，返回 boolean）
+   * @param {string} targetPath
+   * @returns {boolean}
+   */
+  isSafe(targetPath) {
+    try {
+      this.assertSafe(targetPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 项目内写入范围检查（不抛错，返回 boolean）
+   * @param {string} targetPath
+   * @returns {boolean}
+   */
+  isProjectWriteSafe(targetPath) {
+    try {
+      this.assertProjectWriteSafe(targetPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 将相对路径安全地解析到 projectRoot 下
+   * 替代 path.resolve(relativePath)（后者基于 cwd，不安全）
+   * @param {string} relativePath
+   * @returns {string} 绝对路径
+   */
+  resolveProjectPath(relativePath) {
+    if (!this.#configured || !this.#projectRoot) {
+      // 未配置时 fallback 到 cwd（向后兼容）
+      return path.resolve(relativePath);
+    }
+    const resolved = path.resolve(this.#projectRoot, relativePath);
+    this.assertSafe(resolved);
+    return resolved;
+  }
+
+  /**
+   * 重置状态（仅用于测试）
+   */
+  _reset() {
+    this.#projectRoot = null;
+    this.#packageRoot = null;
+    this.#allowList.clear();
+    this.#knowledgeBaseDir = null;
+    this.#configured = false;
+  }
+
+  /**
+   * resolved 是否在 base 目录下
+   */
+  #isUnder(resolved, base) {
+    return resolved === base || resolved.startsWith(base + path.sep);
+  }
+
+  /**
+   * 解析知识库目录名
+   * 优先使用 configure 阶段传入的值，否则尝试运行时探测
+   */
+  #resolveKnowledgeBaseDir() {
+    if (this.#knowledgeBaseDir) return this.#knowledgeBaseDir;
+
+    // 运行时探测: 查找包含 AutoSnippet.boxspec.json 的子目录
+    try {
+      const entries = fs.readdirSync(this.#projectRoot, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.isDirectory() && !e.name.startsWith('.')) {
+          if (fs.existsSync(path.join(this.#projectRoot, e.name, 'AutoSnippet.boxspec.json'))) {
+            this.#knowledgeBaseDir = e.name;
+            return e.name;
+          }
+        }
+      }
+    } catch { /* ignore */ }
+
+    // 默认
+    return 'AutoSnippet';
+  }
+}
+
+/**
+ * 延迟加载 fs（避免循环依赖）
+ */
+function await_fs() {
+  // eslint-disable-next-line no-eval
+  return eval("require('fs')");
+}
+
+// 单例 — 整个进程共享
+const pathGuard = new PathGuard();
+
+export default pathGuard;

package/package.json

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