autosnippet 2.8.2 → 2.9.0

package/lib/http/routes/ai.js

@@ -27,7 +27,7 @@ function getChatAgent() {
  */
 router.get('/providers', asyncHandler(async (req, res) => {
   const providers = [
-    { id: 'google', label: 'Google Gemini', defaultModel: 'gemini-2.0-flash' },
+    { id: 'google', label: 'Google Gemini', defaultModel: 'gemini-3-flash-preview' },
     { id: 'openai', label: 'OpenAI', defaultModel: 'gpt-4o' },
     { id: 'deepseek', label: 'DeepSeek', defaultModel: 'deepseek-chat' },
     { id: 'claude', label: 'Claude', defaultModel: 'claude-3-5-sonnet-20240620' },
@@ -398,4 +398,20 @@ router.post('/env-config', asyncHandler(async (req, res) => {
   res.json({ success: true, data: result });
 }));
 
+/**
+ * GET /api/v1/ai/token-usage
+ * 近 7 日 Token 消耗报告（按日 + 按来源 + 总计）
+ */
+router.get('/token-usage', asyncHandler(async (req, res) => {
+  const container = getServiceContainer();
+  let tokenStore;
+  try {
+    tokenStore = container.get('tokenUsageStore');
+  } catch {
+    return res.json({ success: true, data: { daily: [], bySource: [], summary: { input_tokens: 0, output_tokens: 0, total_tokens: 0, call_count: 0, avg_per_call: 0 } } });
+  }
+  const report = tokenStore.getLast7DaysReport();
+  res.json({ success: true, data: report });
+}));
+
 export default router;

package/lib/http/routes/skills.js

@@ -5,7 +5,7 @@
 
 import express from 'express';
 import { asyncHandler } from '../middleware/errorHandler.js';
-import { listSkills, loadSkill, createSkill, suggestSkills } from '../../external/mcp/handlers/skill.js';
+import { listSkills, loadSkill, createSkill, deleteSkill, updateSkill, suggestSkills } from '../../external/mcp/handlers/skill.js';
 import { ValidationError } from '../../shared/errors/index.js';
 
 const router = express.Router();
@@ -107,4 +107,47 @@ router.post('/', asyncHandler(async (req, res) => {
   res.status(201).json({ success: true, data: parsed.data });
 }));
 
+/**
+ * PUT /api/v1/skills/:name
+ * 更新项目级 Skill（description / content）
+ */
+router.put('/:name', asyncHandler(async (req, res) => {
+  const { name } = req.params;
+  const { description, content } = req.body;
+
+  if (!description && !content) {
+    throw new ValidationError('At least one of description or content must be provided');
+  }
+
+  const raw = updateSkill(null, { name, description, content });
+  const parsed = JSON.parse(raw);
+
+  if (!parsed.success) {
+    const status = parsed.error?.code === 'SKILL_NOT_FOUND' ? 404
+      : parsed.error?.code === 'BUILTIN_PROTECTED' ? 403 : 500;
+    return res.status(status).json(parsed);
+  }
+
+  res.json({ success: true, data: parsed.data });
+}));
+
+/**
+ * DELETE /api/v1/skills/:name
+ * 删除项目级 Skill
+ */
+router.delete('/:name', asyncHandler(async (req, res) => {
+  const { name } = req.params;
+
+  const raw = deleteSkill(null, { name });
+  const parsed = JSON.parse(raw);
+
+  if (!parsed.success) {
+    const status = parsed.error?.code === 'SKILL_NOT_FOUND' ? 404
+      : parsed.error?.code === 'BUILTIN_PROTECTED' ? 403 : 500;
+    return res.status(status).json(parsed);
+  }
+
+  res.json({ success: true, data: parsed.data });
+}));
+
 export default router;

package/lib/infrastructure/cache/GraphCache.js

@@ -0,0 +1,143 @@
+/**
+ * GraphCache — 基于文件的图数据持久化缓存
+ *
+ * 功能:
+ * 1. 将图数据序列化为 JSON 写入磁盘
+ * 2. 基于 contentHash 判断缓存是否有效（Package.swift / 源文件）
+ * 3. 支持 SPM 依赖图和 AST ProjectGraph 两种场景
+ *
+ * 缓存位置: {projectRoot}/.autosnippet/cache/
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import Logger from '../logging/Logger.js';
+
+export class GraphCache {
+  #cacheDir;
+  #logger;
+
+  /**
+   * @param {string} projectRoot 项目根目录
+   */
+  constructor(projectRoot) {
+    this.#cacheDir = join(projectRoot, '.autosnippet', 'cache');
+    this.#logger = Logger.getInstance();
+  }
+
+  /**
+   * 保存缓存
+   * @param {string} key 缓存键名（生成 {key}.json）
+   * @param {object} data 要缓存的数据
+   * @param {object} meta 元信息（含 hash、timestamp 等）
+   */
+  save(key, data, meta = {}) {
+    try {
+      if (!existsSync(this.#cacheDir)) {
+        mkdirSync(this.#cacheDir, { recursive: true });
+      }
+      const payload = {
+        version: 1,
+        savedAt: new Date().toISOString(),
+        ...meta,
+        data,
+      };
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      writeFileSync(filePath, JSON.stringify(payload), 'utf-8');
+      this.#logger.debug(`[GraphCache] saved: ${key} (${JSON.stringify(payload).length} bytes)`);
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] save failed for ${key}: ${err.message}`);
+    }
+  }
+
+  /**
+   * 加载缓存
+   * @param {string} key 缓存键名
+   * @returns {{ data: object, [key: string]: any } | null}
+   */
+  load(key) {
+    try {
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      if (!existsSync(filePath)) return null;
+      const raw = readFileSync(filePath, 'utf-8');
+      return JSON.parse(raw);
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] load failed for ${key}: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 检查缓存是否有效（hash 匹配）
+   * @param {string} key 缓存键
+   * @param {string} currentHash 当前内容的 hash
+   * @returns {boolean}
+   */
+  isValid(key, currentHash) {
+    const cached = this.load(key);
+    if (!cached) return false;
+    return cached.contentHash === currentHash;
+  }
+
+  /**
+   * 删除缓存
+   * @param {string} key
+   */
+  invalidate(key) {
+    try {
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+        this.#logger.debug(`[GraphCache] invalidated: ${key}`);
+      }
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] invalidate failed for ${key}: ${err.message}`);
+    }
+  }
+
+  /**
+   * 计算文件内容 hash
+   * @param {string} filePath 文件绝对路径
+   * @returns {string} sha256 hex (前 16 字符)
+   */
+  computeFileHash(filePath) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      return this.computeContentHash(content);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * 计算字符串内容 hash
+   * @param {string} content
+   * @returns {string} sha256 hex (前 16 字符)
+   */
+  computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex').substring(0, 16);
+  }
+
+  /**
+   * 批量计算文件 hash 映射
+   * @param {string[]} filePaths 文件绝对路径数组
+   * @param {string} projectRoot 项目根目录
+   * @returns {Object<string, string>} { relativePath: hash }
+   */
+  computeFileHashes(filePaths, projectRoot) {
+    const hashes = {};
+    for (const fp of filePaths) {
+      const rel = relative(projectRoot, fp);
+      hashes[rel] = this.computeFileHash(fp);
+    }
+    return hashes;
+  }
+
+  /**
+   * 获取缓存目录路径
+   */
+  getCacheDir() {
+    return this.#cacheDir;
+  }
+}

package/lib/infrastructure/database/migrations/015_create_token_usage.js

@@ -0,0 +1,27 @@
+/**
+ * Migration 015: Create token_usage table
+ *
+ * 持久化 AI 调用的 Token 消耗记录，支持近 7 日消耗趋势查询。
+ * 每次 ChatAgent.execute() 完成后写入一条记录。
+ */
+export default function migrate(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS token_usage (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp   INTEGER NOT NULL,
+      source      TEXT NOT NULL DEFAULT 'unknown',
+      dimension   TEXT,
+      provider    TEXT,
+      model       TEXT,
+      input_tokens  INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_tokens  INTEGER NOT NULL DEFAULT 0,
+      duration_ms   INTEGER,
+      tool_calls    INTEGER DEFAULT 0,
+      session_id    TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_token_usage_timestamp ON token_usage(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_token_usage_source    ON token_usage(source);
+  `);
+}

package/lib/infrastructure/realtime/RealtimeService.js

@@ -17,6 +17,8 @@ export class RealtimeService {
         methods: ['GET', 'POST'],
       },
       transports: ['websocket', 'polling'],
+      pingInterval: 25000,   // 25s 心跳间隔（默认值，显式声明）
+      pingTimeout: 20000,    // 20s 超时（默认值）
     });
 
     this.setupEventHandlers();
@@ -27,7 +29,7 @@ export class RealtimeService {
    */
   setupEventHandlers() {
     this.io.on('connection', (socket) => {
-      Logger.info(`[Socket.io] Client connected: ${socket.id}`);
+      Logger.debug(`[Socket.io] Client connected: ${socket.id}`);
 
       // 加入通知房间
       socket.on('join-notifications', () => {
@@ -45,7 +47,7 @@ export class RealtimeService {
 
       // 处理断开连接
       socket.on('disconnect', () => {
-        Logger.info(`[Socket.io] Client disconnected: ${socket.id}`);
+        Logger.debug(`[Socket.io] Client disconnected: ${socket.id}`);
       });
 
       // 健康检查
@@ -79,6 +81,16 @@ export class RealtimeService {
     });
   }
 
+  /**
+   * 广播 Token 用量变化事件（Sidebar 指标刷新用）
+   */
+  broadcastTokenUsageUpdated() {
+    this.io.to('notifications').emit('token-usage-updated', {
+      type: 'token_usage_updated',
+      timestamp: Date.now(),
+    });
+  }
+
   /**
    * 广播食谱创建事件
    */

package/lib/injection/ServiceContainer.js

@@ -3,6 +3,8 @@ import Logger from '../infrastructure/logging/Logger.js';
 import AuditStore from '../infrastructure/audit/AuditStore.js';
 import AuditLogger from '../infrastructure/audit/AuditLogger.js';
 import Gateway from '../core/gateway/Gateway.js';
+import { readdirSync, statSync } from 'node:fs';
+import { join as pathJoin, relative as pathRelative, extname as pathExtname } from 'node:path';
 
 import { CandidateRepositoryImpl } from '../repository/candidate/CandidateRepository.impl.js';
 import { RecipeRepositoryImpl } from '../repository/recipe/RecipeRepository.impl.js';
@@ -34,6 +36,9 @@ import { ExclusionManager } from '../service/guard/ExclusionManager.js';
 import { RuleLearner } from '../service/guard/RuleLearner.js';
 import { ViolationsStore } from '../service/guard/ViolationsStore.js';
 
+// ─── P1: Token Usage Tracking ─────────────────────────
+import { TokenUsageStore } from '../repository/token/TokenUsageStore.js';
+
 // ─── P2: Quality ──────────────────────────────────────
 import { QualityScorer } from '../service/quality/QualityScorer.js';
 import { FeedbackCollector } from '../service/quality/FeedbackCollector.js';
@@ -53,6 +58,7 @@ import { SkillHooks } from '../service/skills/SkillHooks.js';
 
 // ─── v3.0: AST ProjectGraph ──────────────────────────
 import ProjectGraph from '../core/ast/ProjectGraph.js';
+import { GraphCache } from '../infrastructure/cache/GraphCache.js';
 
 // ─── P3: Infrastructure ──────────────────────────────
 import { EventBus } from '../infrastructure/event/EventBus.js';
@@ -450,6 +456,15 @@ export class ServiceContainer {
       return this.singletons.violationsStore;
     });
 
+    // Token Usage: 持久化 AI token 消耗
+    this.register('tokenUsageStore', () => {
+      if (!this.singletons.tokenUsageStore) {
+        const db = this.get('database').getDb();
+        this.singletons.tokenUsageStore = new TokenUsageStore(db);
+      }
+      return this.singletons.tokenUsageStore;
+    });
+
     // QualityScorer
     this.register('qualityScorer', () => {
       if (!this.singletons.qualityScorer) {
@@ -566,7 +581,7 @@ export class ServiceContainer {
 
   /**
    * 构建 ProjectGraph (v3.0 AST 结构图)
-   * 应在 bootstrap 流程开始前调用一次
+   * 优先从磁盘缓存加载，支持 per-file hash 增量更新
    * @param {string} projectRoot 项目根目录
    * @param {object} [options] 传递给 ProjectGraph.build() 的选项
    * @returns {Promise<import('../core/ast/ProjectGraph.js').default|null>}
@@ -575,14 +590,70 @@ export class ServiceContainer {
     if (this.singletons.projectGraph) {
       return this.singletons.projectGraph;
     }
+
+    const cache = new GraphCache(projectRoot);
+    const startTime = Date.now();
+
     try {
+      // ── 尝试从缓存恢复 + 增量更新 ──
+      const cached = cache.load('project-graph');
+      if (cached?.data && cached.fileHashes) {
+        const graph = ProjectGraph.fromJSON(cached.data);
+        const currentFiles = this.#collectSourceFilePaths(projectRoot, options);
+        const oldHashes = cached.fileHashes || {};
+
+        // 计算差异：新增 / 变更 / 删除
+        const changedPaths = [];
+        const newHashes = {};
+        for (const fp of currentFiles) {
+          const rel = pathRelative(projectRoot, fp);
+          const h = cache.computeFileHash(fp);
+          newHashes[rel] = h;
+          if (!oldHashes[rel] || oldHashes[rel] !== h) {
+            changedPaths.push(fp);
+          }
+        }
+        const deletedPaths = Object.keys(oldHashes).filter(rel => !newHashes[rel]);
+
+        if (changedPaths.length === 0 && deletedPaths.length === 0) {
+          // 完全命中
+          this.singletons.projectGraph = graph;
+          this.logger.info(
+            `[ServiceContainer] ProjectGraph ⚡ 缓存命中 (${graph.getOverview().totalClasses} classes, ` +
+            `${Date.now() - startTime}ms)`
+          );
+          return graph;
+        }
+
+        // 增量更新
+        const diff = await graph.incrementalUpdate(changedPaths, deletedPaths, options);
+        this.singletons.projectGraph = graph;
+
+        // 写回缓存
+        cache.save('project-graph', graph.toJSON(), { fileHashes: newHashes });
+
+        const overview = graph.getOverview();
+        this.logger.info(
+          `[ServiceContainer] ProjectGraph 增量更新: +${diff.added} ~${diff.updated} -${diff.deleted} ` +
+          `(${overview.totalClasses} classes, ${Date.now() - startTime}ms)`
+        );
+        return graph;
+      }
+
+      // ── 无缓存，全量构建 ──
       const graph = await ProjectGraph.build(projectRoot, options);
       this.singletons.projectGraph = graph;
       const overview = graph.getOverview();
+
+      // 计算文件 hash 并写入缓存
+      const currentFiles = this.#collectSourceFilePaths(projectRoot, options);
+      const fileHashes = cache.computeFileHashes(currentFiles, projectRoot);
+      cache.save('project-graph', graph.toJSON(), { fileHashes });
+
       this.logger.info(
         `[ServiceContainer] ProjectGraph built: ${overview.totalClasses} classes, ` +
         `${overview.totalProtocols} protocols, ${overview.totalCategories} categories ` +
-        `(${overview.buildTimeMs}ms)`
+        `(${overview.buildTimeMs}ms) — 缓存已写入`
       );
       return graph;
     } catch (err) {
@@ -590,6 +661,47 @@ export class ServiceContainer {
       return null;
     }
   }
+
+  /**
+   * 收集项目源码文件路径（用于 hash 计算）
+   * @param {string} projectRoot
+   * @param {object} options
+   * @returns {string[]}
+   */
+  #collectSourceFilePaths(projectRoot, options = {}) {
+    const DEFAULTS_EXT = { '.m': true, '.h': true, '.swift': true };
+    const extSet = new Set(options.extensions || Object.keys(DEFAULTS_EXT));
+    const excludePatterns = options.excludePatterns || [
+      'Pods/', 'Carthage/', 'node_modules/', '.build/', 'build/',
+      'DerivedData/', 'vendor/', '.git/', '__tests__/', 'Tests/',
+    ];
+    const maxFiles = options.maxFiles || 500;
+    const maxFileSizeBytes = options.maxFileSizeBytes || 500_000;
+    const results = [];
+
+    function walk(dir) {
+      if (results.length >= maxFiles) return;
+      let entries;
+      try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (results.length >= maxFiles) return;
+        const fullPath = pathJoin(dir, entry.name);
+        const relativePath = pathRelative(projectRoot, fullPath);
+        if (excludePatterns.some(p => relativePath.includes(p))) continue;
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else if (entry.isFile() && extSet.has(pathExtname(entry.name))) {
+          try {
+            const stat = statSync(fullPath);
+            if (stat.size <= maxFileSizeBytes) results.push(fullPath);
+          } catch { /* skip */ }
+        }
+      }
+    }
+
+    walk(projectRoot);
+    return results;
+  }
 }
 
 let containerInstance = null;

package/lib/repository/token/TokenUsageStore.js

@@ -0,0 +1,162 @@
+/**
+ * TokenUsageStore — Token 消耗持久化存储
+ * 写入 AI 调用的 token 用量记录到 SQLite token_usage 表。
+ * 提供近 7 日按日/按来源的聚合查询。
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+
+const MAX_ROWS = 10000; // 自动清理: 保留最近 10000 条
+
+export class TokenUsageStore {
+  #db;
+  #logger;
+  #insertStmt;
+  #pruneStmt;
+  #dailyStmt;
+  #bySourceStmt;
+  #summaryStmt;
+  /** @type {{ data: object, expireAt: number } | null} */
+  #reportCache = null;
+
+  /**
+   * @param {import('better-sqlite3').Database} db
+   */
+  constructor(db) {
+    this.#db = db;
+    this.#logger = Logger.getInstance();
+
+    // 预编译常用语句
+    this.#insertStmt = this.#db.prepare(`
+      INSERT INTO token_usage (timestamp, source, dimension, provider, model, input_tokens, output_tokens, total_tokens, duration_ms, tool_calls, session_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    this.#pruneStmt = this.#db.prepare(`
+      DELETE FROM token_usage WHERE id NOT IN (
+        SELECT id FROM token_usage ORDER BY timestamp DESC LIMIT ?
+      )
+    `);
+    this.#dailyStmt = this.#db.prepare(`
+      SELECT
+        DATE(timestamp / 1000, 'unixepoch', 'localtime') AS date,
+        SUM(input_tokens)  AS input_tokens,
+        SUM(output_tokens) AS output_tokens,
+        SUM(total_tokens)  AS total_tokens,
+        COUNT(*)           AS call_count
+      FROM token_usage
+      WHERE timestamp >= ?
+      GROUP BY date
+      ORDER BY date ASC
+    `);
+    this.#bySourceStmt = this.#db.prepare(`
+      SELECT
+        source,
+        SUM(input_tokens)  AS input_tokens,
+        SUM(output_tokens) AS output_tokens,
+        SUM(total_tokens)  AS total_tokens,
+        COUNT(*)           AS call_count
+      FROM token_usage
+      WHERE timestamp >= ?
+      GROUP BY source
+      ORDER BY total_tokens DESC
+    `);
+    this.#summaryStmt = this.#db.prepare(`
+      SELECT
+        COALESCE(SUM(input_tokens), 0)  AS input_tokens,
+        COALESCE(SUM(output_tokens), 0) AS output_tokens,
+        COALESCE(SUM(total_tokens), 0)  AS total_tokens,
+        COUNT(*)                        AS call_count
+      FROM token_usage
+      WHERE timestamp >= ?
+    `);
+  }
+
+  // ─── 写入 ─────────────────────────────────────────
+
+  /**
+   * 记录一次 AI 调用的 token 消耗
+   * @param {{ source: string, dimension?: string, provider?: string, model?: string, inputTokens: number, outputTokens: number, durationMs?: number, toolCalls?: number, sessionId?: string }} record
+   */
+  record(record) {
+    try {
+      const now = Date.now();
+      const total = (record.inputTokens || 0) + (record.outputTokens || 0);
+      if (total === 0) return; // 跳过无消耗的调用
+
+      this.#insertStmt.run(
+        now,
+        record.source || 'unknown',
+        record.dimension || null,
+        record.provider || null,
+        record.model || null,
+        record.inputTokens || 0,
+        record.outputTokens || 0,
+        total,
+        record.durationMs || null,
+        record.toolCalls || 0,
+        record.sessionId || null,
+      );
+
+      // 写入后使缓存失效
+      this.#reportCache = null;
+
+      // 定期清理（每 100 次写入检查一次）
+      if (Math.random() < 0.01) {
+        this.#pruneStmt.run(MAX_ROWS);
+      }
+    } catch (err) {
+      this.#logger.debug('[TokenUsageStore] record failed', { error: err.message });
+    }
+  }
+
+  // ─── 查询 ─────────────────────────────────────────
+
+  /**
+   * 近 7 日按日聚合统计
+   * @returns {Array<{ date: string, input_tokens: number, output_tokens: number, total_tokens: number, call_count: number }>}
+   */
+  getLast7DaysDaily() {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    return this.#dailyStmt.all(sevenDaysAgo);
+  }
+
+  /**
+   * 近 7 日按来源 (source) 聚合统计
+   * @returns {Array<{ source: string, input_tokens: number, output_tokens: number, total_tokens: number, call_count: number }>}
+   */
+  getLast7DaysBySource() {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    return this.#bySourceStmt.all(sevenDaysAgo);
+  }
+
+  /**
+   * 近 7 日总计
+   * @returns {{ input_tokens: number, output_tokens: number, total_tokens: number, call_count: number, avg_per_call: number }}
+   */
+  getLast7DaysSummary() {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const row = this.#summaryStmt.get(sevenDaysAgo);
+    return {
+      ...row,
+      avg_per_call: row.call_count > 0 ? Math.round(row.total_tokens / row.call_count) : 0,
+    };
+  }
+
+  /**
+   * 获取完整的 7 日报告（前端一次拉取）
+   * 带 10s 内存缓存，避免高频请求重复查询
+   */
+  getLast7DaysReport() {
+    const now = Date.now();
+    if (this.#reportCache && now < this.#reportCache.expireAt) {
+      return this.#reportCache.data;
+    }
+    const data = {
+      daily: this.getLast7DaysDaily(),
+      bySource: this.getLast7DaysBySource(),
+      summary: this.getLast7DaysSummary(),
+    };
+    this.#reportCache = { data, expireAt: now + 10_000 }; // 10s 缓存
+    return data;
+  }
+}

package/lib/service/candidate/CandidateService.js

@@ -869,6 +869,13 @@ Do NOT wrap in markdown code blocks. Return raw JSON only.`;
     const metadata = { ...this._buildMetadataFromFlat(item), ...extraMeta };
     const reasoning = this._buildReasoning(item);
 
+    // ── 去重: 同标题候选已存在于 DB 中则跳过（删除后可重新生成） ──
+    const title = item.title || metadata.title || '';
+    if (title && this._existsCandidateWithTitle(title)) {
+      this.logger.info('Skipped duplicate candidate (title already exists)', { title, source });
+      return { skipped: true, reason: 'duplicate_title', title };
+    }
+
     // 如果 reasoning 为空对象（缺少 whyStandard），生成默认值
     if (!reasoning.whyStandard) {
       reasoning.whyStandard = item.rationale || item.summary || item.description || `Submitted via ${source}`;
@@ -968,6 +975,27 @@ Do NOT wrap in markdown code blocks. Return raw JSON only.`;
       }
     }
   }
+
+  /**
+   * 检查是否已存在同标题的候选（DB 中当前存在的）
+   * @param {string} title
+   * @returns {boolean}
+   */
+  _existsCandidateWithTitle(title) {
+    try {
+      const db = this.candidateRepository.db;
+      const titleLower = (title || '').toLowerCase().trim();
+      if (!titleLower) return false;
+
+      // metadata_json 中搜索 title 字段
+      const row = db.prepare(
+        "SELECT id FROM candidates WHERE LOWER(json_extract(metadata_json, '$.title')) = ?"
+      ).get(titleLower);
+      return !!row;
+    } catch {
+      return false;
+    }
+  }
 }
 
 export default CandidateService;