autosnippet 2.7.0 → 2.7.1

package/lib/external/mcp/handlers/bootstrap/pipeline/orchestrator.js

@@ -12,6 +12,7 @@
  */
 
 import path from 'node:path';
+import fs from 'node:fs/promises';
 import { AnalystAgent } from '../../../../../service/chat/AnalystAgent.js';
 import { ProducerAgent } from '../../../../../service/chat/ProducerAgent.js';
 import { TierScheduler } from './tier-scheduler.js';
@@ -20,6 +21,69 @@ import Logger from '../../../../../infrastructure/logging/Logger.js';
 
 const logger = Logger.getInstance();
 
+// ──────────────────────────────────────────────────────────────────
+// P3: 断点续传 — Checkpoint 存储/恢复
+// ──────────────────────────────────────────────────────────────────
+
+const CHECKPOINT_TTL_MS = 3600_000; // 1小时内有效
+
+/**
+ * 保存维度级 checkpoint
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @param {string} dimId
+ * @param {object} result — 维度执行结果
+ * @param {object} [digest] — DimensionDigest
+ */
+async function saveDimensionCheckpoint(projectRoot, sessionId, dimId, result, digest = null) {
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    await fs.mkdir(checkpointDir, { recursive: true });
+    await fs.writeFile(
+      path.join(checkpointDir, `${dimId}.json`),
+      JSON.stringify({ dimId, sessionId, ...result, digest, completedAt: Date.now() }),
+    );
+  } catch (err) {
+    logger.warn(`[Bootstrap-v3] checkpoint save failed for "${dimId}": ${err.message}`);
+  }
+}
+
+/**
+ * 加载有效的 checkpoints
+ * @param {string} projectRoot
+ * @returns {Promise<Map<string, object>>} dimId → checkpoint data
+ */
+async function loadCheckpoints(projectRoot) {
+  const checkpoints = new Map();
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    const files = await fs.readdir(checkpointDir).catch(() => []);
+    const now = Date.now();
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      try {
+        const content = await fs.readFile(path.join(checkpointDir, file), 'utf-8');
+        const data = JSON.parse(content);
+        if (data.completedAt && (now - data.completedAt) < CHECKPOINT_TTL_MS) {
+          checkpoints.set(data.dimId, data);
+        }
+      } catch { /* skip corrupt checkpoint */ }
+    }
+  } catch { /* checkpoint dir doesn't exist */ }
+  return checkpoints;
+}
+
+/**
+ * 清理 checkpoint 目录
+ * @param {string} projectRoot
+ */
+async function clearCheckpoints(projectRoot) {
+  try {
+    const checkpointDir = path.join(projectRoot, '.autosnippet', 'bootstrap-checkpoint');
+    await fs.rm(checkpointDir, { recursive: true, force: true });
+  } catch { /* ignore */ }
+}
+
 // ──────────────────────────────────────────────────────────────────
 // v3.0 维度配置 (增加 focusAreas 用于 Analyst prompt)
 // ──────────────────────────────────────────────────────────────────
@@ -222,7 +286,7 @@ export async function fillDimensionsV3(fillContext) {
   // ═══════════════════════════════════════════════════════════
   // Step 2: 按维度分层执行 (Analyst → Gate → Producer)
   // ═══════════════════════════════════════════════════════════
-  const concurrency = parseInt(process.env.ASD_PARALLEL_CONCURRENCY || '2', 10);
+  const concurrency = parseInt(process.env.ASD_PARALLEL_CONCURRENCY || '3', 10);
   const enableParallel = process.env.ASD_PARALLEL_BOOTSTRAP !== 'false';
   const scheduler = new TierScheduler();
 
@@ -233,13 +297,52 @@ export async function fillDimensionsV3(fillContext) {
 
   logger.info(`[Bootstrap-v3] Active dimensions: [${activeDimIds.join(', ')}], concurrency=${enableParallel ? concurrency : 1}`);
 
+  // ── P3: 断点续传 — 加载有效 checkpoints ──
+  const completedCheckpoints = await loadCheckpoints(projectRoot);
+  const skippedDims = [];
+  for (const [dimId, checkpoint] of completedCheckpoints) {
+    if (activeDimIds.includes(dimId)) {
+      // 恢复 DimensionContext 中的 digest
+      if (checkpoint.digest) {
+        dimContext.addDimensionDigest(dimId, checkpoint.digest);
+      }
+      taskManager?.markTaskCompleted(dimId, {
+        type: 'checkpoint-restored',
+        ...checkpoint,
+      });
+      skippedDims.push(dimId);
+      logger.info(`[Bootstrap-v3] ⏩ 跳过已完成维度 (checkpoint): "${dimId}"`);
+    }
+  }
+
   const candidateResults = { created: 0, failed: 0, errors: [] };
   const dimensionCandidates = {};
+  const dimensionStats = {}; // P4.2: 维度级统计
 
   /**
    * 执行单个维度: Analyst → Gate → Producer
    */
   async function executeDimension(dimId) {
+    // P3: 跳过已有 checkpoint 的维度
+    if (skippedDims.includes(dimId)) {
+      const cp = completedCheckpoints.get(dimId);
+      const cpResult = {
+        candidateCount: cp?.candidateCount || 0,
+        rejectedCount: cp?.rejectedCount || 0,
+        analysisChars: cp?.analysisChars || 0,
+        referencedFiles: cp?.referencedFiles || 0,
+        durationMs: cp?.durationMs || 0,
+        toolCallCount: cp?.toolCallCount || 0,
+        tokenUsage: cp?.tokenUsage || { input: 0, output: 0 },
+        skipped: true,
+        restoredFromCheckpoint: true,
+      };
+      // P4.2: 将恢复的维度也记入统计
+      dimensionStats[dimId] = cpResult;
+      candidateResults.created += cpResult.candidateCount;
+      return cpResult;
+    }
+
     const dim = dimensions.find(d => d.id === dimId);
     const v3Config = DIMENSION_CONFIGS_V3[dimId];
     if (!dim || !v3Config) {
@@ -270,7 +373,7 @@ export async function fillDimensionsV3(fillContext) {
     try {
       // ── Phase 1: Analyst ──
       const analysisReport = await Promise.race([
-        analystAgent.analyze(dimConfig, projectInfo, { sessionId }),
+        analystAgent.analyze(dimConfig, projectInfo, { sessionId, dimensionContext: dimContext }),
         new Promise((_, reject) =>
           setTimeout(() => reject(new Error(`Analyst timeout for "${dimId}"`)), 180_000)),
       ]);
@@ -333,13 +436,32 @@ export async function fillDimensionsV3(fillContext) {
         toolCallCount: (analysisReport.metadata?.toolCallCount || 0) + (producerResult.toolCalls?.length || 0),
       });
 
-      return {
+      // P4.1: 聚合 token 用量
+      const analystTokens = analysisReport.metadata?.tokenUsage || { input: 0, output: 0 };
+      const producerTokens = producerResult.tokenUsage || { input: 0, output: 0 };
+      const dimTokenUsage = {
+        input: (analystTokens.input || 0) + (producerTokens.input || 0),
+        output: (analystTokens.output || 0) + (producerTokens.output || 0),
+      };
+
+      const dimResult = {
         candidateCount: producerResult.candidateCount,
+        rejectedCount: producerResult.rejectedCount || 0,
         analysisChars: analysisReport.analysisText.length,
         referencedFiles: analysisReport.referencedFiles.length,
         durationMs: Date.now() - dimStartTime,
+        toolCallCount: (analysisReport.metadata?.toolCallCount || 0) + (producerResult.toolCalls?.length || 0),
+        tokenUsage: dimTokenUsage,
       };
 
+      // P4.2: 记录维度统计
+      dimensionStats[dimId] = dimResult;
+
+      // P3: 保存 checkpoint
+      await saveDimensionCheckpoint(projectRoot, sessionId, dimId, dimResult, digest);
+
+      return dimResult;
+
     } catch (err) {
       logger.error(`[Bootstrap-v3] Dimension "${dimId}" failed: ${err.message}`);
       candidateResults.errors.push({ dimId, error: err.message });
@@ -449,16 +571,83 @@ export async function fillDimensionsV3(fillContext) {
   }
 
   // ═══════════════════════════════════════════════════════════
-  // Summary
+  // Summary + P4.2: Bootstrap Report
   // ═══════════════════════════════════════════════════════════
   const totalTimeMs = Date.now() - t0;
+
+  // P4.1: 汇总所有维度 token 用量
+  const totalTokenUsage = { input: 0, output: 0 };
+  const totalToolCalls = Object.values(dimensionStats).reduce((sum, s) => sum + (s.toolCallCount || 0), 0);
+  for (const stat of Object.values(dimensionStats)) {
+    if (stat.tokenUsage) {
+      totalTokenUsage.input += stat.tokenUsage.input || 0;
+      totalTokenUsage.output += stat.tokenUsage.output || 0;
+    }
+  }
+
   logger.info([
     `[Bootstrap-v3] ═══ Pipeline complete ═══`,
     `  Candidates: ${candidateResults.created} created, ${candidateResults.errors.length} errors`,
     `  Skills: ${skillResults.created} created, ${skillResults.failed} failed`,
     `  Time: ${totalTimeMs}ms (${(totalTimeMs / 1000).toFixed(1)}s)`,
     `  Mode: ${enableParallel ? `parallel (concurrency=${concurrency})` : 'serial'}`,
-  ].join('\n'));
+    `  Tokens: input=${totalTokenUsage.input}, output=${totalTokenUsage.output}`,
+    `  Tool calls: ${totalToolCalls}`,
+    skippedDims.length > 0 ? `  Checkpoints restored: [${skippedDims.join(', ')}]` : '',
+  ].filter(Boolean).join('\n'));
+
+  // P4.2: 生成冷启动报告
+  try {
+    const report = {
+      version: '2.7.0',
+      timestamp: new Date().toISOString(),
+      project: {
+        name: projectInfo.name,
+        files: projectInfo.fileCount,
+        lang: projectInfo.lang,
+      },
+      duration: {
+        totalMs: totalTimeMs,
+        totalSec: Math.round(totalTimeMs / 1000),
+      },
+      dimensions: {},
+      totals: {
+        candidates: candidateResults.created,
+        skills: skillResults.created,
+        toolCalls: totalToolCalls,
+        tokenUsage: totalTokenUsage,
+        errors: candidateResults.errors.length,
+      },
+      checkpoints: {
+        restored: skippedDims,
+      },
+    };
+
+    for (const [dimId, stat] of Object.entries(dimensionStats)) {
+      report.dimensions[dimId] = {
+        candidatesSubmitted: stat.candidateCount || 0,
+        candidatesRejected: stat.rejectedCount || 0,
+        analysisChars: stat.analysisChars || 0,
+        referencedFiles: stat.referencedFiles || 0,
+        durationMs: stat.durationMs || 0,
+        toolCallCount: stat.toolCallCount || 0,
+        tokenUsage: stat.tokenUsage || { input: 0, output: 0 },
+      };
+    }
+
+    const reportDir = path.join(projectRoot, '.autosnippet');
+    await fs.mkdir(reportDir, { recursive: true });
+    await fs.writeFile(
+      path.join(reportDir, 'bootstrap-report.json'),
+      JSON.stringify(report, null, 2),
+    );
+    logger.info(`[Bootstrap-v3] 📊 Bootstrap report saved to .autosnippet/bootstrap-report.json`);
+  } catch (reportErr) {
+    logger.warn(`[Bootstrap-v3] Bootstrap report generation failed: ${reportErr.message}`);
+  }
+
+  // P3: 成功完成后清理 checkpoints
+  await clearCheckpoints(projectRoot);
 
   // 释放文件缓存
   allFiles = null;

package/lib/external/mcp/handlers/bootstrap/pipeline/tier-scheduler.js

@@ -1,11 +1,10 @@
 /**
  * TierScheduler.js — 维度分层并行调度器
  *
- * 按维度间信息依赖关系分 4 层执行:
+ * 按维度间信息依赖关系分 3 层执行:
  * - Tier 1: 基础数据层 (project-profile, objc-deep-scan, category-scan) — 可并行
- * - Tier 2: 规范+架构 (code-standard, architecture) — 依赖 Tier 1
- * - Tier 3: 模式+流转 (code-pattern, event-and-data-flow) — 依赖 Tier 2
- * - Tier 4: 总结层 (best-practice, agent-guidelines) — 依赖全部
+ * - Tier 2: 规范+架构+模式 (code-standard, architecture, code-pattern) — 依赖 Tier 1
+ * - Tier 3: 流转+实践+总结 (event-and-data-flow, best-practice, agent-guidelines) — 依赖 Tier 2
  *
  * 每层内部可并行 (受 concurrency 限制)，层间串行。
  *
@@ -21,10 +20,9 @@ const logger = Logger.getInstance();
 // ──────────────────────────────────────────────────────────────────
 
 const DEFAULT_TIERS = [
-  ['project-profile', 'objc-deep-scan', 'category-scan'],     // Tier 1: 基础数据
-  ['code-standard', 'architecture'],                            // Tier 2: 规范+架构
-  ['code-pattern', 'event-and-data-flow'],                      // Tier 3: 模式+流转
-  ['best-practice', 'agent-guidelines'],                        // Tier 4: 总结
+  ['project-profile', 'objc-deep-scan', 'category-scan'],                   // Tier 1: 基础数据
+  ['code-standard', 'architecture', 'code-pattern'],                        // Tier 2: 规范+架构+模式
+  ['event-and-data-flow', 'best-practice', 'agent-guidelines'],             // Tier 3: 流转+实践+总结
 ];
 
 // ──────────────────────────────────────────────────────────────────
@@ -79,13 +77,13 @@ export class TierScheduler {
    *
    * @param {Function} executeDimension — async (dimId) => DimensionResult
    * @param {object} [options]
-   * @param {number} [options.concurrency=2] — Tier 内最大并行数
+   * @param {number} [options.concurrency=3] — Tier 内最大并行数
    * @param {Function} [options.onTierComplete] — (tierIndex, tierResults) => void
    * @param {Function} [options.shouldAbort] — () => boolean — 外部中止信号
    * @returns {Promise<Map<string, any>>} — dimId → result
    */
   async execute(executeDimension, options = {}) {
-    const { concurrency = 2, onTierComplete, shouldAbort } = options;
+    const { concurrency = 3, onTierComplete, shouldAbort } = options;
     const results = new Map();
 
     for (let tierIndex = 0; tierIndex < this.#tiers.length; tierIndex++) {

package/lib/external/mcp/handlers/bootstrap.js

@@ -41,6 +41,7 @@ import { envelope } from '../envelope.js';
 import { inferLang, detectPrimaryLanguage, buildLanguageExtension } from './LanguageExtensions.js';
 import { inferTargetRole, inferFilePriority } from './TargetClassifier.js';
 import { analyzeProject, generateContextForAgent, isAvailable as astIsAvailable } from '../../../core/AstAnalyzer.js';
+import pathGuard from '../../../shared/PathGuard.js';
 
 // ── Sub-modules ──
 import { loadBootstrapSkills, extractSkillDimensionGuides, enhanceDimensions } from './bootstrap/skills.js';
@@ -67,6 +68,13 @@ export { loadBootstrapSkills };
 export async function bootstrapKnowledge(ctx, args) {
   const t0 = Date.now();
   const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
+
+  // 路径安全守卫 — 确保所有写操作限制在项目目录内
+  if (!pathGuard.configured) {
+    const { default: Bootstrap } = await import('../../../bootstrap.js');
+    Bootstrap.configurePathGuard(projectRoot);
+  }
+
   const maxFiles = args.maxFiles || 500;
   const skipGuard = args.skipGuard || false;
   const contentMaxLines = args.contentMaxLines || 120;

package/lib/external/mcp/handlers/skill.js

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getProjectSkillsPath } from '../../../infrastructure/config/Paths.js';
+import pathGuard from '../../../shared/PathGuard.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SKILLS_DIR = path.resolve(__dirname, '../../../../skills');
@@ -282,6 +283,8 @@ export function createSkill(_ctx, args) {
 
   // ── 写入 SKILL.md ──
   try {
+    // 路径安全检查 — name 来自用户输入，可能含路径字符
+    pathGuard.assertProjectWriteSafe(skillDir);
     fs.mkdirSync(skillDir, { recursive: true });
 
     // 自动推断 title: 优先使用传入参数，否则从 content 的第一个 # heading 提取
@@ -385,6 +388,7 @@ function _regenerateEditorIndex() {
     ].join('\n');
 
     // 写入 .cursor/rules/
+    pathGuard.assertProjectWriteSafe(rulesDir);
     fs.mkdirSync(rulesDir, { recursive: true });
     const indexPath = path.join(rulesDir, 'autosnippet-skills.mdc');
     fs.writeFileSync(indexPath, mdcContent, 'utf8');

package/lib/http/routes/ai.js

@@ -1,9 +1,11 @@
 /**
  * AI API 路由
- * AI 提供商管理、摘要、翻译、对话
+ * AI 提供商管理、摘要、翻译、对话、.env LLM 配置
  */
 
 import express from 'express';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { createProvider } from '../../external/ai/AiFactory.js';
@@ -244,4 +246,156 @@ router.post('/format-usage-guide', asyncHandler(async (req, res) => {
   res.json({ success: true, data: { formatted } });
 }));
 
+// ═══════════════════════════════════════════════════════
+//  .env LLM 配置读写
+// ═══════════════════════════════════════════════════════
+
+/** 获取用户项目目录下 .env 的路径 */
+function _getProjectEnvPath() {
+  const container = getServiceContainer();
+  const projectRoot = container.singletons?._projectRoot || process.env.ASD_PROJECT_DIR || process.cwd();
+  return join(projectRoot, '.env');
+}
+
+/** LLM 相关的 env 变量名 → 标签映射 */
+const LLM_ENV_KEYS = [
+  'ASD_AI_PROVIDER',
+  'ASD_AI_MODEL',
+  'ASD_GOOGLE_API_KEY',
+  'ASD_OPENAI_API_KEY',
+  'ASD_CLAUDE_API_KEY',
+  'ASD_DEEPSEEK_API_KEY',
+  'ASD_AI_PROXY',
+];
+
+/**
+ * 解析 .env 内容为 key-value（仅提取 LLM 相关变量）
+ * 返回 { vars, hasEnvFile, llmReady }
+ *   llmReady: provider + 至少一个对应 API Key 已配置
+ */
+function parseLlmEnv(envPath) {
+  if (!existsSync(envPath)) {
+    return { vars: {}, hasEnvFile: false, llmReady: false };
+  }
+
+  const raw = readFileSync(envPath, 'utf8');
+  const vars = {};
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    // 跳过注释和空行
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (LLM_ENV_KEYS.includes(key)) {
+      vars[key] = val;
+    }
+  }
+
+  // 判断 LLM 是否可用：有 provider + 对应的 API Key
+  const provider = vars.ASD_AI_PROVIDER || '';
+  const keyMap = {
+    google: 'ASD_GOOGLE_API_KEY',
+    openai: 'ASD_OPENAI_API_KEY',
+    claude: 'ASD_CLAUDE_API_KEY',
+    deepseek: 'ASD_DEEPSEEK_API_KEY',
+    ollama: '', // ollama 不需要 key
+    mock: '',   // mock 不需要 key
+  };
+  const neededKey = keyMap[provider] || '';
+  const llmReady = !!provider && (!neededKey || !!vars[neededKey]);
+
+  return { vars, hasEnvFile: true, llmReady };
+}
+
+/**
+ * GET /api/v1/ai/env-config
+ * 读取用户项目 .env 中的 LLM 配置
+ */
+router.get('/env-config', asyncHandler(async (req, res) => {
+  const envPath = _getProjectEnvPath();
+  const result = parseLlmEnv(envPath);
+  res.json({ success: true, data: result });
+}));
+
+/**
+ * POST /api/v1/ai/env-config
+ * 写入 / 更新用户项目 .env 中的 LLM 配置
+ *
+ * Body: { provider, model, apiKey, proxy? }
+ */
+router.post('/env-config', asyncHandler(async (req, res) => {
+  const { provider, model, apiKey, proxy } = req.body;
+  if (!provider || typeof provider !== 'string') {
+    throw new ValidationError('provider is required');
+  }
+
+  const envPath = _getProjectEnvPath();
+  let content = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+
+  // 构建 key-value 更新列表
+  const updates = {
+    ASD_AI_PROVIDER: provider,
+  };
+  if (model) updates.ASD_AI_MODEL = model;
+  if (proxy) updates.ASD_AI_PROXY = proxy;
+
+  // 根据 provider 决定写入哪个 API Key 变量
+  const providerKeyMap = {
+    google: 'ASD_GOOGLE_API_KEY',
+    openai: 'ASD_OPENAI_API_KEY',
+    claude: 'ASD_CLAUDE_API_KEY',
+    deepseek: 'ASD_DEEPSEEK_API_KEY',
+  };
+  const keyName = providerKeyMap[provider];
+  if (keyName && apiKey) {
+    updates[keyName] = apiKey;
+  }
+
+  // 逐条合并到 .env 内容
+  for (const [k, v] of Object.entries(updates)) {
+    // 匹配已有行（包括被注释的行）
+    const activeRe = new RegExp(`^${k}\\s*=.*$`, 'm');
+    const commentedRe = new RegExp(`^#\\s*${k}\\s*=.*$`, 'm');
+
+    if (activeRe.test(content)) {
+      // 替换已有活动行
+      content = content.replace(activeRe, `${k}=${v}`);
+    } else if (commentedRe.test(content)) {
+      // 取消注释并赋值
+      content = content.replace(commentedRe, `${k}=${v}`);
+    } else {
+      // 追加到末尾
+      if (!content.endsWith('\n')) content += '\n';
+      content += `${k}=${v}\n`;
+    }
+  }
+
+  writeFileSync(envPath, content);
+  logger.info('LLM env config updated', { provider, model });
+
+  // 同步到当前进程环境变量（热生效）
+  for (const [k, v] of Object.entries(updates)) {
+    process.env[k] = v;
+  }
+
+  // 尝试热切换 AI Provider
+  try {
+    const newProvider = createProvider({
+      provider: provider.toLowerCase(),
+      model: model || undefined,
+    });
+    const container = getServiceContainer();
+    container.singletons.aiProvider = newProvider;
+    logger.info('AI provider hot-swapped after env update', { provider, model: newProvider.model });
+  } catch (err) {
+    logger.debug('Hot-swap AI provider failed (will take effect on restart)', { error: err.message });
+  }
+
+  const result = parseLlmEnv(envPath);
+  res.json({ success: true, data: result });
+}));
+
 export default router;

package/lib/infrastructure/config/Paths.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import pathGuard from '../../shared/PathGuard.js';
 
 /**
  * Paths — 项目路径解析工具
@@ -14,6 +15,8 @@ const USER_HOME = process.env.HOME || process.env.USERPROFILE || '';
 /** 确保目录存在（静默处理异常） */
 function ensureDir(dirPath) {
   try {
+    // 双层路径安全检查 — 阻止在项目允许范围外创建文件夹
+    pathGuard.assertProjectWriteSafe(dirPath);
     if (!fs.existsSync(dirPath)) {
       fs.mkdirSync(dirPath, { recursive: true });
     }

package/lib/infrastructure/database/DatabaseConnection.js

@@ -2,6 +2,7 @@ import Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import pathGuard from '../../shared/PathGuard.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -20,9 +21,13 @@ export class DatabaseConnection {
    */
   async connect() {
     const dbPath = this.config.path;
+
+    // 路径安全检查 — 防止 DB 文件创建到项目允许范围外
+    const resolvedDbPath = path.resolve(dbPath);
+    pathGuard.assertProjectWriteSafe(resolvedDbPath);
     
     // 确保数据目录存在
-    const dbDir = path.dirname(dbPath);
+    const dbDir = path.dirname(resolvedDbPath);
     if (!fs.existsSync(dbDir)) {
       fs.mkdirSync(dbDir, { recursive: true });
     }

package/lib/infrastructure/vector/JsonVectorAdapter.js

@@ -7,6 +7,7 @@
 import { VectorStore } from './VectorStore.js';
 import { writeFileSync, readFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import pathGuard from '../../shared/PathGuard.js';
 
 export class JsonVectorAdapter extends VectorStore {
   #indexPath;
@@ -238,6 +239,7 @@ export class JsonVectorAdapter extends VectorStore {
     if (!this.#dirty) return;
     try {
       const dir = dirname(this.#indexPath);
+      pathGuard.assertProjectWriteSafe(dir);
       if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
       const items = [...this.#data.values()];
       writeFileSync(this.#indexPath, JSON.stringify(items, null, 2));

package/lib/service/candidate/CandidateFileWriter.js

@@ -19,6 +19,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { CANDIDATES_DIR } from '../../infrastructure/config/Defaults.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import pathGuard from '../../shared/PathGuard.js';
 
 export { CANDIDATES_DIR };
 
@@ -175,6 +176,9 @@ export class CandidateFileWriter {
       const category = (candidate.category || 'general').toLowerCase();
       const categoryDir = path.join(this.candidatesDir, category);
 
+      // 路径安全检查 — 阻止 category 含 ../ 导致路径逃逸
+      pathGuard.assertProjectWriteSafe(categoryDir);
+
       if (!fs.existsSync(categoryDir)) {
         fs.mkdirSync(categoryDir, { recursive: true });
       }