autosnippet 2.14.0 → 2.15.0

package/lib/external/mcp/McpServer.js

@@ -20,6 +20,7 @@ import {
 import Logger from '../../infrastructure/logging/Logger.js';
 import { envelope } from './envelope.js';
 import { TOOLS, TOOL_GATEWAY_MAP } from './tools.js';
+import { wrapHandler } from './errorHandler.js';
 
 // ─── Handler 模块 ─────────────────────────────────────────────
 
@@ -116,56 +117,70 @@ export class McpServer {
     await this._gatewayGate(name, args);
 
     const ctx = this._ctx;
-    switch (name) {
+
+    // 查找 handler 并通过 wrapHandler 统一错误处理
+    const handler = this._resolveHandler(name);
+    if (!handler) throw new Error(`Unknown tool: ${name}`);
+
+    const wrapped = wrapHandler(name, handler);
+    return wrapped(ctx, args);
+  }
+
+  /**
+   * 解析工具名到 handler 函数
+   * @private
+   */
+  _resolveHandler(name) {
+    const HANDLER_MAP = {
       // 系统
-      case 'autosnippet_health':            return systemHandlers.health(ctx);
-      case 'autosnippet_capabilities':      return systemHandlers.capabilities();
+      autosnippet_health:              (ctx) => systemHandlers.health(ctx),
+      autosnippet_capabilities:        () => systemHandlers.capabilities(),
       // 搜索
-      case 'autosnippet_search':            return searchHandlers.search(ctx, args);
-      case 'autosnippet_context_search':    return searchHandlers.contextSearch(ctx, args);
-      case 'autosnippet_keyword_search':    return searchHandlers.keywordSearch(ctx, args);
-      case 'autosnippet_semantic_search':   return searchHandlers.semanticSearch(ctx, args);
+      autosnippet_search:              (ctx, args) => searchHandlers.search(ctx, args),
+      autosnippet_context_search:      (ctx, args) => searchHandlers.contextSearch(ctx, args),
+      autosnippet_keyword_search:      (ctx, args) => searchHandlers.keywordSearch(ctx, args),
+      autosnippet_semantic_search:     (ctx, args) => searchHandlers.semanticSearch(ctx, args),
       // 知识浏览
-      case 'autosnippet_list_rules':        return browseHandlers.listByKind(ctx, 'rule', args);
-      case 'autosnippet_list_patterns':     return browseHandlers.listByKind(ctx, 'pattern', args);
-      case 'autosnippet_list_facts':        return browseHandlers.listByKind(ctx, 'fact', args);
-      case 'autosnippet_list_recipes':      return browseHandlers.listRecipes(ctx, args);
-      case 'autosnippet_get_recipe':        return browseHandlers.getRecipe(ctx, args);
-      case 'autosnippet_recipe_insights':   return browseHandlers.recipeInsights(ctx, args);
-      case 'autosnippet_confirm_usage':     return browseHandlers.confirmUsage(ctx, args);
+      autosnippet_list_rules:          (ctx, args) => browseHandlers.listByKind(ctx, 'rule', args),
+      autosnippet_list_patterns:       (ctx, args) => browseHandlers.listByKind(ctx, 'pattern', args),
+      autosnippet_list_facts:          (ctx, args) => browseHandlers.listByKind(ctx, 'fact', args),
+      autosnippet_list_recipes:        (ctx, args) => browseHandlers.listRecipes(ctx, args),
+      autosnippet_get_recipe:          (ctx, args) => browseHandlers.getRecipe(ctx, args),
+      autosnippet_recipe_insights:     (ctx, args) => browseHandlers.recipeInsights(ctx, args),
+      autosnippet_confirm_usage:       (ctx, args) => browseHandlers.confirmUsage(ctx, args),
       // 项目结构 & 图谱
-      case 'autosnippet_get_targets':       return structureHandlers.getTargets(ctx);
-      case 'autosnippet_get_target_files':  return structureHandlers.getTargetFiles(ctx, args);
-      case 'autosnippet_get_target_metadata': return structureHandlers.getTargetMetadata(ctx, args);
-      case 'autosnippet_graph_query':       return structureHandlers.graphQuery(ctx, args);
-      case 'autosnippet_graph_impact':      return structureHandlers.graphImpact(ctx, args);
-      case 'autosnippet_graph_path':        return structureHandlers.graphPath(ctx, args);
-      case 'autosnippet_graph_stats':       return structureHandlers.graphStats(ctx);
-      // 候选校验 & AI 补全（提交已移至 V3 knowledge handlers）
-      case 'autosnippet_validate_candidate':  return candidateHandlers.validateCandidate(ctx, args);
-      case 'autosnippet_check_duplicate':   return candidateHandlers.checkDuplicate(ctx, args);
-      case 'autosnippet_enrich_candidates': return candidateHandlers.enrichCandidates(ctx, args);
+      autosnippet_get_targets:         (ctx) => structureHandlers.getTargets(ctx),
+      autosnippet_get_target_files:    (ctx, args) => structureHandlers.getTargetFiles(ctx, args),
+      autosnippet_get_target_metadata: (ctx, args) => structureHandlers.getTargetMetadata(ctx, args),
+      autosnippet_graph_query:         (ctx, args) => structureHandlers.graphQuery(ctx, args),
+      autosnippet_graph_impact:        (ctx, args) => structureHandlers.graphImpact(ctx, args),
+      autosnippet_graph_path:          (ctx, args) => structureHandlers.graphPath(ctx, args),
+      autosnippet_graph_stats:         (ctx) => structureHandlers.graphStats(ctx),
+      // 候选校验 & AI 补全
+      autosnippet_validate_candidate:  (ctx, args) => candidateHandlers.validateCandidate(ctx, args),
+      autosnippet_check_duplicate:     (ctx, args) => candidateHandlers.checkDuplicate(ctx, args),
+      autosnippet_enrich_candidates:   (ctx, args) => candidateHandlers.enrichCandidates(ctx, args),
       // Guard & 扫描
-      case 'autosnippet_guard_check':       return guardHandlers.guardCheck(ctx, args);
-      case 'autosnippet_guard_audit_files': return guardHandlers.guardAuditFiles(ctx, args);
-      case 'autosnippet_scan_project':      return guardHandlers.scanProject(ctx, args);
+      autosnippet_guard_check:         (ctx, args) => guardHandlers.guardCheck(ctx, args),
+      autosnippet_guard_audit_files:   (ctx, args) => guardHandlers.guardAuditFiles(ctx, args),
+      autosnippet_scan_project:        (ctx, args) => guardHandlers.scanProject(ctx, args),
       // Bootstrap 冷启动
-      case 'autosnippet_bootstrap_knowledge': return bootstrapHandlers.bootstrapKnowledge(ctx, args);
-      case 'autosnippet_bootstrap_refine':    return bootstrapHandlers.bootstrapRefine(ctx, args);
-      // Skills 加载 & 创建 & 管理 & 推荐
-      case 'autosnippet_list_skills':         return skillHandlers.listSkills();
-      case 'autosnippet_load_skill':          return skillHandlers.loadSkill(ctx, args);
-      case 'autosnippet_create_skill':        return skillHandlers.createSkill(ctx, args);
-      case 'autosnippet_delete_skill':        return skillHandlers.deleteSkill(ctx, args);
-      case 'autosnippet_update_skill':        return skillHandlers.updateSkill(ctx, args);
-      case 'autosnippet_suggest_skills':      return skillHandlers.suggestSkills(ctx);
+      autosnippet_bootstrap_knowledge: (ctx, args) => bootstrapHandlers.bootstrapKnowledge(ctx, args),
+      autosnippet_bootstrap_refine:    (ctx, args) => bootstrapHandlers.bootstrapRefine(ctx, args),
+      // Skills
+      autosnippet_list_skills:         () => skillHandlers.listSkills(),
+      autosnippet_load_skill:          (ctx, args) => skillHandlers.loadSkill(ctx, args),
+      autosnippet_create_skill:        (ctx, args) => skillHandlers.createSkill(ctx, args),
+      autosnippet_delete_skill:        (ctx, args) => skillHandlers.deleteSkill(ctx, args),
+      autosnippet_update_skill:        (ctx, args) => skillHandlers.updateSkill(ctx, args),
+      autosnippet_suggest_skills:      (ctx) => skillHandlers.suggestSkills(ctx),
       // V3 知识条目
-      case 'autosnippet_submit_knowledge':        return knowledgeHandlers.submitKnowledge(ctx, args);
-      case 'autosnippet_submit_knowledge_batch':  return knowledgeHandlers.submitKnowledgeBatch(ctx, args);
-      case 'autosnippet_knowledge_lifecycle':      return knowledgeHandlers.knowledgeLifecycle(ctx, args);
-      case 'autosnippet_save_document':            return knowledgeHandlers.saveDocument(ctx, args);
-      default: throw new Error(`Unknown tool: ${name}`);
-    }
+      autosnippet_submit_knowledge:       (ctx, args) => knowledgeHandlers.submitKnowledge(ctx, args),
+      autosnippet_submit_knowledge_batch: (ctx, args) => knowledgeHandlers.submitKnowledgeBatch(ctx, args),
+      autosnippet_knowledge_lifecycle:    (ctx, args) => knowledgeHandlers.knowledgeLifecycle(ctx, args),
+      autosnippet_save_document:          (ctx, args) => knowledgeHandlers.saveDocument(ctx, args),
+    };
+    return HANDLER_MAP[name] || null;
   }
 
   /**

package/lib/external/mcp/errorHandler.js

@@ -0,0 +1,106 @@
+/**
+ * MCP 工具统一错误处理
+ *
+ * 提供 wrapHandler() 包装函数，将所有 handler 的异常统一转换为
+ * envelope 格式的错误响应，确保：
+ *   1. 已知业务错误 → 结构化 errorCode + message
+ *   2. 未知异常 → 通用 INTERNAL_ERROR + 原始 message
+ *   3. 一致的 meta.tool + meta.responseTimeMs
+ *
+ * @module external/mcp/errorHandler
+ */
+
+import { envelope } from './envelope.js';
+import {
+  ValidationError,
+  NotFoundError,
+  ConflictError,
+  PermissionDenied,
+  ConstitutionViolation,
+} from '../../shared/errors/index.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+const logger = Logger.getInstance();
+
+/**
+ * 从已知错误类型推断 errorCode
+ * @param {Error} err
+ * @returns {string}
+ */
+function inferErrorCode(err) {
+  if (err instanceof ValidationError)       return 'VALIDATION_ERROR';
+  if (err instanceof NotFoundError)         return 'NOT_FOUND';
+  if (err instanceof ConflictError)         return 'CONFLICT';
+  if (err instanceof PermissionDenied)      return 'PERMISSION_DENIED';
+  if (err instanceof ConstitutionViolation) return 'CONSTITUTION_VIOLATION';
+  if (err.code)                             return err.code;
+  return 'INTERNAL_ERROR';
+}
+
+/**
+ * 包装 MCP handler 函数，提供统一错误处理
+ *
+ * @param {string} toolName — 工具名（用于 meta.tool）
+ * @param {Function} handlerFn — 原始 handler: (ctx, args) => Promise<any>
+ * @returns {Function} — 包装后的 handler，保证 *不会* throw
+ *
+ * @example
+ *   import { wrapHandler } from '../errorHandler.js';
+ *   export const search = wrapHandler('autosnippet_search', async (ctx, args) => {
+ *     // ... 正常返回 envelope(...)
+ *   });
+ */
+export function wrapHandler(toolName, handlerFn) {
+  return async function wrappedHandler(ctx, args) {
+    const t0 = Date.now();
+    try {
+      return await handlerFn(ctx, args);
+    } catch (err) {
+      const elapsed = Date.now() - t0;
+      const errorCode = inferErrorCode(err);
+      const message = err.message || 'Unknown error';
+
+      logger.error(`[MCP:${toolName}] ${errorCode}: ${message}`, {
+        tool: toolName,
+        errorCode,
+        durationMs: elapsed,
+        ...(err.details ? { details: err.details } : {}),
+      });
+
+      return envelope({
+        success: false,
+        message,
+        errorCode,
+        meta: {
+          tool: toolName,
+          responseTimeMs: elapsed,
+        },
+      });
+    }
+  };
+}
+
+/**
+ * 批量包装一个模块的所有 handler 函数
+ *
+ * @param {string} prefix — 工具名前缀（如 'autosnippet_search'）
+ * @param {Record<string, Function>} handlersModule — handler 模块 exports
+ * @returns {Record<string, Function>} — 包装后的 handlers
+ *
+ * @example
+ *   import * as rawSearchHandlers from './handlers/search.js';
+ *   const searchHandlers = wrapHandlers('autosnippet', rawSearchHandlers);
+ */
+export function wrapHandlers(prefix, handlersModule) {
+  const wrapped = {};
+  for (const [key, fn] of Object.entries(handlersModule)) {
+    if (typeof fn === 'function') {
+      wrapped[key] = wrapHandler(`${prefix}_${key}`, fn);
+    } else {
+      wrapped[key] = fn; // 非函数属性原样透传
+    }
+  }
+  return wrapped;
+}
+
+export default { wrapHandler, wrapHandlers };

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

@@ -6,7 +6,7 @@
  *
  * 设计:
  *   - 缓存粒度: 完整工具调用 (key = toolName + normalized args)
- *   - 失效策略: 仅 Bootstrap 会话内有效，无 TTL
+ *   - 失效策略: TTL 过期 + 手动清理 (默认 30 分钟)
  *   - 内存管理: 文件内容缓存上限 200 个，搜索结果上限 500 个
  *
  * 使用方式:
@@ -17,10 +17,13 @@
  */
 
 import Logger from '../../../../../infrastructure/logging/Logger.js';
+import { CACHE } from '../../../../../shared/constants.js';
 
 /** 最大缓存条目 */
-const MAX_FILE_CACHE = 200;
-const MAX_SEARCH_CACHE = 500;
+const MAX_FILE_CACHE = CACHE.MAX_FILE_ENTRIES;
+const MAX_SEARCH_CACHE = CACHE.MAX_SEARCH_ENTRIES;
+/** 缓存 TTL（毫秒），超过此时间的条目视为过期 */
+const DEFAULT_TTL_MS = CACHE.DEFAULT_TTL_MS;
 
 export class ToolResultCache {
   /** @type {Map<string, {result: any, cachedAt: number, hitCount: number}>} */
@@ -32,11 +35,31 @@ export class ToolResultCache {
   /** @type {import('../../../../../lib/infrastructure/logging/Logger.js').default} */
   #logger;
 
-  /** @type {{hits: number, misses: number}} */
-  #stats = { hits: 0, misses: 0 };
+  /** @type {{hits: number, misses: number, evictions: number}} */
+  #stats = { hits: 0, misses: 0, evictions: 0 };
 
-  constructor() {
+  /** @type {number} TTL in ms */
+  #ttlMs;
+
+  /** @type {ReturnType<typeof setInterval>|null} cleanup timer */
+  #cleanupTimer = null;
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.ttlMs] — 缓存 TTL（毫秒），默认取 CACHE.DEFAULT_TTL_MS
+   * @param {number} [options.cleanupIntervalMs] — 清理周期（毫秒），默认 5 分钟
+   */
+  constructor(options = {}) {
     this.#logger = Logger.getInstance();
+    this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+
+    // 定期清理过期条目，避免内存膨胀
+    const cleanupInterval = options.cleanupIntervalMs ?? 5 * 60 * 1000;
+    if (this.#ttlMs > 0 && cleanupInterval > 0) {
+      this.#cleanupTimer = setInterval(() => this.#evictExpired(), cleanupInterval);
+      // 允许进程退出时不被 timer 阻塞
+      if (this.#cleanupTimer.unref) this.#cleanupTimer.unref();
+    }
   }
 
   // ─── 搜索结果缓存 ────────────────────────────────────
@@ -67,6 +90,13 @@ export class ToolResultCache {
   getCachedSearch(pattern) {
     const entry = this.#searchCache.get(pattern);
     if (entry) {
+      // TTL 检查
+      if (this.#ttlMs > 0 && (Date.now() - entry.cachedAt) > this.#ttlMs) {
+        this.#searchCache.delete(pattern);
+        this.#stats.evictions++;
+        this.#stats.misses++;
+        return null;
+      }
       entry.hitCount++;
       this.#stats.hits++;
       return entry.result;
@@ -102,6 +132,13 @@ export class ToolResultCache {
   getCachedFile(filePath) {
     const entry = this.#fileCache.get(filePath);
     if (entry) {
+      // TTL 检查
+      if (this.#ttlMs > 0 && (Date.now() - entry.cachedAt) > this.#ttlMs) {
+        this.#fileCache.delete(filePath);
+        this.#stats.evictions++;
+        this.#stats.misses++;
+        return null;
+      }
       entry.hitCount++;
       this.#stats.hits++;
       return entry.content;
@@ -182,7 +219,49 @@ export class ToolResultCache {
   clear() {
     this.#searchCache.clear();
     this.#fileCache.clear();
-    this.#stats = { hits: 0, misses: 0 };
+    this.#stats = { hits: 0, misses: 0, evictions: 0 };
+  }
+
+  /**
+   * 销毁缓存实例，释放定时器
+   * 应在 Bootstrap 会话结束时调用
+   */
+  dispose() {
+    this.clear();
+    if (this.#cleanupTimer) {
+      clearInterval(this.#cleanupTimer);
+      this.#cleanupTimer = null;
+    }
+  }
+
+  // ─── 内部 ─────────────────────────────────────────────
+
+  /**
+   * 清理两个 Map 中的过期条目
+   * @private
+   */
+  #evictExpired() {
+    if (this.#ttlMs <= 0) return;
+    const now = Date.now();
+    let evicted = 0;
+
+    for (const [key, entry] of this.#searchCache) {
+      if ((now - entry.cachedAt) > this.#ttlMs) {
+        this.#searchCache.delete(key);
+        evicted++;
+      }
+    }
+    for (const [key, entry] of this.#fileCache) {
+      if ((now - entry.cachedAt) > this.#ttlMs) {
+        this.#fileCache.delete(key);
+        evicted++;
+      }
+    }
+
+    if (evicted > 0) {
+      this.#stats.evictions += evicted;
+      this.#logger.debug(`[ToolResultCache] evicted ${evicted} expired entries`);
+    }
   }
 }
 

package/lib/http/HttpServer.js

@@ -26,6 +26,7 @@ import violationsRouter from './routes/violations.js';
 import authRouter from './routes/auth.js';
 import skillsRouter from './routes/skills.js';
 import knowledgeRouter from './routes/knowledge.js';
+import recipesRouter from './routes/recipes.js';
 import apiSpec from './api-spec.js';
 import { initRedisService } from '../infrastructure/cache/RedisService.js';
 import { initCacheAdapter } from '../infrastructure/cache/UnifiedCacheAdapter.js';
@@ -264,6 +265,9 @@ export class HttpServer {
     // 知识条目路由 (V3)
     this.app.use(`${apiPrefix}/knowledge`, knowledgeRouter);
 
+    // Recipe 操作路由（关系发现等）
+    this.app.use(`${apiPrefix}/recipes`, recipesRouter);
+
     // 根路径 — 返回 API 元信息（避免外部探测产生无意义 404）
     this.app.all('/', (req, res) => {
       res.json({

package/lib/http/middleware/requestLogger.js

@@ -5,24 +5,41 @@
  * 精简策略:
  *   - GET 请求 + 2xx 状态码: 降为 debug（Dashboard 轮询高频噪音）
  *   - 非 GET / 非 2xx / 慢请求(>2s): 保留 info 级别
+ *
+ * ⚠️ 重要: 使用 req.originalUrl 而非 req.path。
+ *    Express 4 子路由器 (app.use('/api/v1/x', router)) 会在执行
+ *    handler 期间临时修改 req.url / req.path 为相对路径 (e.g. '/')。
+ *    当 res.on('finish') 同步触发时 req.url 尚未恢复，导致日志中
+ *    所有子路由请求都显示为 'GET / ...'，SILENT_PATHS 匹配也失效。
+ *    req.originalUrl 始终保持请求的原始 URL，不受路由挂载影响。
  */
 
 // 轮询/心跳路径 — 完全静默
-const SILENT_PATHS = ['/api/health', '/api/realtime/events', '/api/sse', '/socket.io'];
+const SILENT_PATHS = ['/api/v1/health', '/api/health', '/api/realtime/events', '/api/sse', '/socket.io'];
+
+/**
+ * 从 originalUrl 中提取 pathname（去除 query string）
+ */
+function extractPath(originalUrl) {
+  const idx = originalUrl.indexOf('?');
+  return idx === -1 ? originalUrl : originalUrl.slice(0, idx);
+}
 
 export function requestLogger(logger) {
   return (req, res, next) => {
     const startTime = Date.now();
+    // 在中间件进入时捕获 originalUrl — 此值不会被 Express 路由修改
+    const originalPath = extractPath(req.originalUrl);
 
     res.on('finish', () => {
       const duration = Date.now() - startTime;
 
       // 完全静默的路径
-      if (SILENT_PATHS.some(p => req.path.startsWith(p))) return;
+      if (SILENT_PATHS.some(p => originalPath.startsWith(p))) return;
 
       const logData = {
         method: req.method,
-        path: req.path,
+        path: originalPath,
         statusCode: res.statusCode,
         duration: `${duration}ms`,
       };
@@ -31,7 +48,7 @@ export function requestLogger(logger) {
       const isNoisy = req.method === 'GET' && (res.statusCode >= 200 && res.statusCode < 300 || res.statusCode === 304) && duration < 2000;
       const isSlow = duration >= 1000;
       if (isSlow) {
-        logger.warn(`🐌慢请求： ${req.method} ${req.path} - ${duration}ms`, logData);
+        logger.warn(`🐌慢请求： ${req.method} ${originalPath} - ${duration}ms`, logData);
       } else if (isNoisy) {
         logger.debug('HTTP', logData);
       } else {

package/lib/http/routes/recipes.js

@@ -0,0 +1,163 @@
+/**
+ * Recipes API 路由
+ * 提供 Recipe 知识图谱关系发现等操作
+ *
+ * 说明: Recipe 的 CRUD 已由 knowledge.js 统一提供，
+ * 此路由仅处理 Recipe 特有的批量 AI 操作。
+ */
+
+import express from 'express';
+import { asyncHandler } from '../middleware/errorHandler.js';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+const router = express.Router();
+const logger = Logger.getInstance();
+
+/* ═══ 进程内任务状态（单实例足够） ═══════════════════════ */
+
+let discoverTask = {
+  status: 'idle',       // idle | running | done | error
+  startedAt: null,
+  finishedAt: null,
+  discovered: 0,
+  totalPairs: 0,
+  batchErrors: 0,
+  error: null,
+  elapsed: 0,
+  message: null,
+};
+
+function resetTask() {
+  discoverTask = {
+    status: 'idle',
+    startedAt: null,
+    finishedAt: null,
+    discovered: 0,
+    totalPairs: 0,
+    batchErrors: 0,
+    error: null,
+    elapsed: 0,
+    message: null,
+  };
+}
+
+/* ═══ POST /api/v1/recipes/discover-relations ═══════════ */
+
+/**
+ * 异步启动 AI 批量发现 Recipe 知识图谱关系
+ * Body: { batchSize?: number }
+ *
+ * 立即返回 { status: 'started' }，后台执行。
+ * Dashboard 通过 GET /discover-relations/status 轮询进度。
+ */
+router.post('/discover-relations', asyncHandler(async (req, res) => {
+  const { batchSize = 20 } = req.body;
+
+  // 如果已有任务在运行，返回当前状态
+  if (discoverTask.status === 'running') {
+    const elapsed = Math.round((Date.now() - new Date(discoverTask.startedAt).getTime()) / 1000);
+    return res.json({
+      success: true,
+      data: {
+        status: 'running',
+        startedAt: discoverTask.startedAt,
+        elapsed,
+        message: 'AI 分析仍在进行中',
+      },
+    });
+  }
+
+  // 检查 ChatAgent 是否可用
+  const container = getServiceContainer();
+  let chatAgent;
+  try {
+    chatAgent = container.get('chatAgent');
+  } catch {
+    return res.json({
+      success: true,
+      data: { status: 'error', error: 'ChatAgent 不可用，请检查 AI Provider 配置' },
+    });
+  }
+
+  // 快速检查：至少需要 2 条活跃 Recipe
+  try {
+    const knowledgeService = container.get('knowledgeService');
+    const { items = [], data = [] } = await knowledgeService.list(
+      { lifecycle: 'active' }, { page: 1, pageSize: 5 },
+    );
+    const count = items.length || data.length;
+    if (count < 2) {
+      return res.json({
+        success: true,
+        data: {
+          status: 'empty',
+          message: `只有 ${count} 条活跃 Recipe，至少需要 2 条才能分析关系`,
+        },
+      });
+    }
+  } catch {
+    // 如果 list 失败，继续尝试（让 runTask 给出具体错误）
+  }
+
+  // 重置并启动后台任务
+  resetTask();
+  discoverTask.status = 'running';
+  discoverTask.startedAt = new Date().toISOString();
+
+  // 异步执行，不 await
+  (async () => {
+    try {
+      const result = await chatAgent.runTask('discover_all_relations', { batchSize });
+      discoverTask.status = 'done';
+      discoverTask.finishedAt = new Date().toISOString();
+      discoverTask.discovered = result.discovered || 0;
+      discoverTask.totalPairs = result.totalPairs || 0;
+      discoverTask.batchErrors = result.batchErrors || 0;
+      discoverTask.elapsed = Math.round(
+        (new Date(discoverTask.finishedAt).getTime() - new Date(discoverTask.startedAt).getTime()) / 1000,
+      );
+      logger.info('Discover relations completed', {
+        discovered: discoverTask.discovered,
+        totalPairs: discoverTask.totalPairs,
+        batchErrors: discoverTask.batchErrors,
+        elapsed: discoverTask.elapsed,
+      });
+    } catch (err) {
+      discoverTask.status = 'error';
+      discoverTask.finishedAt = new Date().toISOString();
+      discoverTask.error = err.message;
+      discoverTask.elapsed = Math.round(
+        (new Date(discoverTask.finishedAt).getTime() - new Date(discoverTask.startedAt).getTime()) / 1000,
+      );
+      logger.error('Discover relations failed', { error: err.message });
+    }
+  })();
+
+  res.json({
+    success: true,
+    data: {
+      status: 'started',
+      startedAt: discoverTask.startedAt,
+      message: 'AI 分析已启动，正在后台运行',
+    },
+  });
+}));
+
+/* ═══ GET /api/v1/recipes/discover-relations/status ═════ */
+
+/**
+ * 查询关系发现任务状态
+ */
+router.get('/discover-relations/status', asyncHandler(async (req, res) => {
+  const data = { ...discoverTask };
+
+  // 计算实时 elapsed
+  if (data.status === 'running' && data.startedAt) {
+    data.elapsed = Math.round((Date.now() - new Date(data.startedAt).getTime()) / 1000);
+  }
+
+  res.json({ success: true, data });
+}));
+
+export default router;

package/lib/repository/base/BaseRepository.js

@@ -1,4 +1,5 @@
 import Logger from '../../infrastructure/logging/Logger.js';
+import { unixNow } from '../../shared/utils/common.js';
 
 /** Only allow safe SQL identifier characters: letters, digits, underscore */
 const SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -180,7 +181,7 @@ export class BaseRepository {
       `;
 
       const stmt = this.db.prepare(query);
-      stmt.run(...updateValues, Math.floor(Date.now() / 1000), id);
+      stmt.run(...updateValues, unixNow(), id);
 
       return this.findById(id);
     } catch (error) {

package/lib/repository/knowledge/KnowledgeRepository.impl.js

@@ -1,6 +1,7 @@
 import { BaseRepository } from '../base/BaseRepository.js';
 import { KnowledgeEntry, Lifecycle, inferKind } from '../../domain/knowledge/index.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { safeJsonParse, safeJsonStringify, unixNow } from '../../shared/utils/common.js';
 
 /**
  * KnowledgeRepositoryImpl — 统一知识实体仓储实现
@@ -57,7 +58,7 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
         const row = this._entityToRow(updates);
         delete row.id;
         delete row.createdAt;
-        row.updatedAt = Math.floor(Date.now() / 1000);
+        row.updatedAt = unixNow();
 
         const setClauses = Object.keys(row).map(k => `${k} = ?`).join(', ');
         this.db.prepare(`UPDATE knowledge_entries SET ${setClauses} WHERE id = ?`)
@@ -69,7 +70,7 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
       const merged = KnowledgeEntry.fromJSON({
         ...existing.toJSON(),
         ...updates,
-        updatedAt: Math.floor(Date.now() / 1000),
+        updatedAt: unixNow(),
       });
       const row = this._entityToRow(merged);
       delete row.id;
@@ -248,17 +249,17 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
     return new KnowledgeEntry({
       ...row,
       // JSON 列需要 parse
-      lifecycleHistory: this._parseJson(row.lifecycleHistory, []),
-      tags:             this._parseJson(row.tags, []),
-      content:          this._parseJson(row.content, {}),
-      relations:        this._parseJson(row.relations, {}),
-      constraints:      this._parseJson(row.constraints, {}),
-      reasoning:        this._parseJson(row.reasoning, {}),
-      quality:          this._parseJson(row.quality, {}),
-      stats:            this._parseJson(row.stats, {}),
-      headers:          this._parseJson(row.headers, []),
-      headerPaths:      this._parseJson(row.headerPaths, []),
-      agentNotes:       this._parseJson(row.agentNotes, null),
+      lifecycleHistory: safeJsonParse(row.lifecycleHistory, []),
+      tags:             safeJsonParse(row.tags, []),
+      content:          safeJsonParse(row.content, {}),
+      relations:        safeJsonParse(row.relations, {}),
+      constraints:      safeJsonParse(row.constraints, {}),
+      reasoning:        safeJsonParse(row.reasoning, {}),
+      quality:          safeJsonParse(row.quality, {}),
+      stats:            safeJsonParse(row.stats, {}),
+      headers:          safeJsonParse(row.headers, []),
+      headerPaths:      safeJsonParse(row.headerPaths, []),
+      agentNotes:       safeJsonParse(row.agentNotes, null),
       // SQLite INTEGER → boolean
       autoApprovable:   !!row.autoApprovable,
       includeHeaders:   !!row.includeHeaders,
@@ -271,13 +272,13 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
    * @returns {Object}
    */
   _entityToRow(e) {
-    const now = Math.floor(Date.now() / 1000);
+    const now = unixNow();
     return {
       id:                e.id,
       title:             e.title,
       description:       e.description || '',
       lifecycle:         e.lifecycle,
-      lifecycleHistory:  JSON.stringify(e.lifecycleHistory || []),
+      lifecycleHistory:  safeJsonStringify(e.lifecycleHistory || [], '[]'),
       autoApprovable:    e.autoApprovable ? 1 : 0,
       language:          e.language,
       category:          e.category,
@@ -286,24 +287,24 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
       complexity:        e.complexity || 'intermediate',
       scope:             e.scope || null,
       difficulty:        e.difficulty || null,
-      tags:              JSON.stringify(e.tags || []),
+      tags:              safeJsonStringify(e.tags || [], '[]'),
       trigger:           e.trigger || '',
       topicHint:         e.topicHint || '',
       whenClause:        e.whenClause || '',
       doClause:          e.doClause || '',
       dontClause:        e.dontClause || '',
       coreCode:          e.coreCode || '',
-      content:           JSON.stringify(typeof e.content?.toJSON === 'function' ? e.content.toJSON() : (e.content || {})),
-      relations:         JSON.stringify(typeof e.relations?.toJSON === 'function' ? e.relations.toJSON() : (e.relations || {})),
-      constraints:       JSON.stringify(typeof e.constraints?.toJSON === 'function' ? e.constraints.toJSON() : (e.constraints || {})),
-      reasoning:         JSON.stringify(typeof e.reasoning?.toJSON === 'function' ? e.reasoning.toJSON() : (e.reasoning || {})),
-      quality:           JSON.stringify(typeof e.quality?.toJSON === 'function' ? e.quality.toJSON() : (e.quality || {})),
-      stats:             JSON.stringify(typeof e.stats?.toJSON === 'function' ? e.stats.toJSON() : (e.stats || {})),
-      headers:           JSON.stringify(e.headers || []),
-      headerPaths:       JSON.stringify(e.headerPaths || []),
+      content:           safeJsonStringify(e.content || {}),
+      relations:         safeJsonStringify(e.relations || {}),
+      constraints:       safeJsonStringify(e.constraints || {}),
+      reasoning:         safeJsonStringify(e.reasoning || {}),
+      quality:           safeJsonStringify(e.quality || {}),
+      stats:             safeJsonStringify(e.stats || {}),
+      headers:           safeJsonStringify(e.headers || [], '[]'),
+      headerPaths:       safeJsonStringify(e.headerPaths || [], '[]'),
       moduleName:        e.moduleName || null,
       includeHeaders:    e.includeHeaders ? 1 : 0,
-      agentNotes:        e.agentNotes ? JSON.stringify(e.agentNotes) : null,
+      agentNotes:        e.agentNotes ? safeJsonStringify(e.agentNotes) : null,
       aiInsight:         e.aiInsight || null,
       reviewedBy:        e.reviewedBy || null,
       reviewedAt:        e.reviewedAt || null,
@@ -326,13 +327,6 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
   _mapRowToEntity(row) {
     return this._rowToEntity(row);
   }
-
-  /** @private 安全解析 JSON */
-  _parseJson(value, fallback) {
-    if (!value || value === 'null') return fallback;
-    if (typeof value === 'object') return value;
-    try { return JSON.parse(value); } catch { return fallback; }
-  }
 }
 
 export default KnowledgeRepositoryImpl;

package/lib/service/automation/FileWatcher.js

@@ -14,6 +14,7 @@ import { readFileSync, accessSync, statSync } from 'node:fs';
 import { basename, join, normalize } from 'node:path';
 import { detectTriggers, REGEX } from './DirectiveDetector.js';
 import { saveEventFilter } from './SaveEventFilter.js';
+import { FILE_WATCHER } from '../../shared/constants.js';
 
 /* ── Handler imports ── */
 import { handleCreate } from './handlers/CreateHandler.js';
@@ -31,7 +32,7 @@ const IGNORED = [
   '**/xcuserdata/**', '**/.build/**', '**/*.swp', '**/*.tmp', '**/*~.m', '**/*~.h',
   '**/DerivedData/**', '**/Pods/**', '**/Carthage/**',
 ];
-const DEBOUNCE_DELAY = 300;
+const DEBOUNCE_DELAY = FILE_WATCHER.DEBOUNCE_DELAY_MS;
 
 /* ────────── FileWatcher ────────── */
 
@@ -76,10 +77,10 @@ export class FileWatcher {
       ignored: IGNORED,
       ignoreInitial: true,
       persistent: true,
-      awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+      awaitWriteFinish: { stabilityThreshold: FILE_WATCHER.STABILITY_THRESHOLD_MS, pollInterval: FILE_WATCHER.POLL_INTERVAL_MS },
       usePolling: process.env.ASD_WATCH_POLLING === 'true',
-      interval: 100,
-      binaryInterval: 300,
+      interval: FILE_WATCHER.POLL_INTERVAL_MS,
+      binaryInterval: FILE_WATCHER.BINARY_INTERVAL_MS,
     });
 
     const handleEvent = (relativePath) => {
@@ -115,17 +116,29 @@ export class FileWatcher {
   }
 
   /**
-   * 停止监听
+   * 停止监听，释放所有资源
    */
   async stop() {
     if (this._watcher) {
+      // 移除所有事件监听器，避免泄漏
+      this._watcher.removeAllListeners();
       await this._watcher.close();
       this._watcher = null;
     }
+    // 清理所有防抖定时器
     for (const timer of this._debounceTimers.values()) {
       clearTimeout(timer);
     }
     this._debounceTimers.clear();
+    // 清理 handler 级别的延时定时器
+    if (this._timeoutLink) {
+      clearTimeout(this._timeoutLink);
+      this._timeoutLink = null;
+    }
+    if (this._timeoutHead) {
+      clearTimeout(this._timeoutHead);
+      this._timeoutHead = null;
+    }
   }
 
   /* ────────── 内部：文件处理（分派到 handlers） ────────── */
@@ -134,7 +147,7 @@ export class FileWatcher {
     try {
       accessSync(fullPath);
       const stat = statSync(fullPath);
-      if (stat.isDirectory() || stat.size > 1024 * 1024) return;
+      if (stat.isDirectory() || stat.size > FILE_WATCHER.MAX_FILE_SIZE_BYTES) return;
     } catch {
       return;
     }

package/lib/service/chat/WorkingMemory.js

@@ -284,6 +284,17 @@ export class WorkingMemory {
       .sort((a, b) => b.importance - a.importance);
   }
 
+  /**
+   * 清空 WorkingMemory — 释放内存
+   * 在 Agent execute 结束后调用，避免残留引用导致内存泄漏
+   */
+  clear() {
+    this.#recentObservations.length = 0;
+    this.#compressedObservations.length = 0;
+    this.#scratchpad.length = 0;
+    this.#totalObservations = 0;
+  }
+
   // ─── 内部 ─────────────────────────────────────────────
 
   /**

package/lib/service/cursor/CursorDeliveryPipeline.js

@@ -15,6 +15,7 @@ import { TopicClassifier } from './TopicClassifier.js';
 import { RulesGenerator } from './RulesGenerator.js';
 import { SkillsSyncer } from './SkillsSyncer.js';
 import { estimateTokens, BUDGET } from './TokenBudget.js';
+import { KNOWLEDGE_CONFIDENCE, DELIVERY_RANK } from '../../shared/constants.js';
 import path from 'node:path';
 import fs from 'node:fs';
 
@@ -127,10 +128,10 @@ export class CursorDeliveryPipeline {
         { page: 1, pageSize: 200 }
       );
       const pendingItems = this._extractItems(pending);
-      // 过滤高置信度 pending（quality.confidence >= 0.7 或无 quality 字段）
+      // 过滤高置信度 pending（quality.confidence >= PENDING_MIN 或无 quality 字段）
       const highConfPending = pendingItems.filter(e => {
         const conf = e.quality?.confidence;
-        return conf === undefined || conf === null || conf >= 0.7;
+        return conf === undefined || conf === null || conf >= KNOWLEDGE_CONFIDENCE.PENDING_MIN;
       });
       allEntries.push(...highConfPending);
     } catch (e) {
@@ -190,10 +191,10 @@ export class CursorDeliveryPipeline {
    */
   _rankScore(entry) {
     let score = 0;
-    score += (entry.quality?.confidence || 0.5) * 50;
-    score += (entry.quality?.authorityScore || 0) * 30;
-    score += Math.min(entry.stats?.useCount || 0, 10) * 2;
-    if (entry.lifecycle === 'active') score += 10;
+    score += (entry.quality?.confidence || KNOWLEDGE_CONFIDENCE.RANK_DEFAULT) * DELIVERY_RANK.CONFIDENCE_WEIGHT;
+    score += (entry.quality?.authorityScore || 0) * DELIVERY_RANK.AUTHORITY_WEIGHT;
+    score += Math.min(entry.stats?.useCount || 0, DELIVERY_RANK.USE_COUNT_MAX) * DELIVERY_RANK.USE_COUNT_WEIGHT;
+    if (entry.lifecycle === 'active') score += DELIVERY_RANK.ACTIVE_BONUS;
     return score;
   }
 

package/lib/service/guard/ComplianceReporter.js

@@ -14,6 +14,7 @@
 
 import Logger from '../../infrastructure/logging/Logger.js';
 import { collectSourceFilesWithContent } from './SourceFileCollector.js';
+import { COMPLIANCE_SCORING, QUALITY_GATE } from '../../shared/constants.js';
 
 /**
  * Quality Gate 评分算法
@@ -21,20 +22,20 @@ import { collectSourceFilesWithContent } from './SourceFileCollector.js';
 function computeScore(summary, ruleHealth = []) {
   let score = 100;
 
-  // 扣分：每个 error -5，每个 warning -1，info -0.2
-  score -= summary.errors * 5;
-  score -= summary.warnings * 1;
-  score -= (summary.infos || 0) * 0.2;
+  // 扣分：每个 error/warning/info 按常量权重扣分
+  score -= summary.errors * COMPLIANCE_SCORING.ERROR_PENALTY;
+  score -= summary.warnings * COMPLIANCE_SCORING.WARNING_PENALTY;
+  score -= (summary.infos || 0) * COMPLIANCE_SCORING.INFO_PENALTY;
 
-  // 加分：规则平均 F1 > 0.8 加 5 分
+  // 加分：规则平均 F1 > 阈值加分
   if (ruleHealth.length > 0) {
     const avgF1 = ruleHealth.reduce((s, r) => s + (r.f1 || 0), 0) / ruleHealth.length;
-    if (avgF1 > 0.8) score += 5;
+    if (avgF1 > COMPLIANCE_SCORING.HIGH_F1_THRESHOLD) score += COMPLIANCE_SCORING.HIGH_F1_BONUS;
   }
 
-  // 扣分：高误报规则每条 -3
-  const problematic = ruleHealth.filter(r => (r.precision || 1) < 0.5);
-  score -= problematic.length * 3;
+  // 扣分：高误报规则每条扣分
+  const problematic = ruleHealth.filter(r => (r.precision || 1) < COMPLIANCE_SCORING.LOW_PRECISION_THRESHOLD);
+  score -= problematic.length * COMPLIANCE_SCORING.PROBLEMATIC_RULE_PENALTY;
 
   return Math.max(0, Math.min(100, Math.round(score)));
 }
@@ -43,7 +44,7 @@ function computeScore(summary, ruleHealth = []) {
  * 判定 Quality Gate 状态
  */
 function evaluateGate(summary, score, thresholds) {
-  const { maxErrors = 0, maxWarnings = 20, minScore = 70 } = thresholds;
+  const { maxErrors = QUALITY_GATE.MAX_ERRORS, maxWarnings = QUALITY_GATE.MAX_WARNINGS, minScore = QUALITY_GATE.MIN_SCORE } = thresholds;
 
   if (summary.errors > maxErrors) return 'FAIL';
   if (score < minScore) return 'FAIL';
@@ -65,9 +66,9 @@ export class ComplianceReporter {
     this.ruleLearner = ruleLearner;
     this.exclusionManager = exclusionManager;
     this.qualityGateConfig = {
-      maxErrors: 0,
-      maxWarnings: 20,
-      minScore: 70,
+      maxErrors: QUALITY_GATE.MAX_ERRORS,
+      maxWarnings: QUALITY_GATE.MAX_WARNINGS,
+      minScore: QUALITY_GATE.MIN_SCORE,
       ...qualityGateConfig,
     };
     this.logger = Logger.getInstance();

package/lib/service/guard/GuardService.js

@@ -1,5 +1,6 @@
 import Logger from '../../infrastructure/logging/Logger.js';
 import { ValidationError, ConflictError, NotFoundError } from '../../shared/errors/index.js';
+import { unixNow } from '../../shared/utils/common.js';
 import { v4 as uuidv4 } from 'uuid';
 
 /**
@@ -65,7 +66,7 @@ export class GuardService {
         resourceId: created.id,
         actor: context.userId,
         details: `Created guard rule: ${data.name}`,
-        timestamp: Math.floor(Date.now() / 1000),
+        timestamp: unixNow(),
       });
 
       return created;
@@ -94,7 +95,7 @@ export class GuardService {
         resourceId: ruleId,
         actor: context.userId,
         details: `Enabled guard rule: ${entry.title}`,
-        timestamp: Math.floor(Date.now() / 1000),
+        timestamp: unixNow(),
       });
 
       return this.knowledgeRepository.findById(ruleId);
@@ -130,7 +131,7 @@ export class GuardService {
         resourceId: ruleId,
         actor: context.userId,
         details: `Disabled guard rule: ${reason}`,
-        timestamp: Math.floor(Date.now() / 1000),
+        timestamp: unixNow(),
       });
 
       return this.knowledgeRepository.findById(ruleId);

package/lib/service/guard/RuleLearner.js

@@ -8,8 +8,12 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from '
 import { join, dirname } from 'node:path';
 import Logger from '../../infrastructure/logging/Logger.js';
 import pathGuard from '../../shared/PathGuard.js';
+import { RULE_LEARNER } from '../../shared/constants.js';
 
-const PROBLEMATIC_THRESHOLD = { falsePositiveRate: 0.3, minTriggers: 5 };
+const PROBLEMATIC_THRESHOLD = {
+  falsePositiveRate: RULE_LEARNER.PROBLEMATIC_FALSE_POSITIVE_RATE,
+  minTriggers: RULE_LEARNER.PROBLEMATIC_MIN_TRIGGERS,
+};
 
 export class RuleLearner {
   #learnerPath;
@@ -142,7 +146,7 @@ export class RuleLearner {
           type: 'tune_existing',
           ruleId: p.ruleId,
           message: `规则 ${p.ruleId} 误报率 ${(p.metrics.falsePositiveRate * 100).toFixed(0)}%，建议调整正则或收窄语言范围`,
-          confidence: 0.7,
+          confidence: RULE_LEARNER.CONFIDENCE_TUNE,
           evidence: p.metrics,
         });
       } else if (p.recommendation === 'disable') {
@@ -150,7 +154,7 @@ export class RuleLearner {
           type: 'disable',
           ruleId: p.ruleId,
           message: `规则 ${p.ruleId} 误报率 ${(p.metrics.falsePositiveRate * 100).toFixed(0)}%，建议禁用`,
-          confidence: 0.8,
+          confidence: RULE_LEARNER.CONFIDENCE_DISABLE,
           evidence: p.metrics,
         });
       }
@@ -159,12 +163,12 @@ export class RuleLearner {
     // 策略 2: 高触发 + 高精度内置规则 → 建议创建项目定制版
     const allStats = this.getAllStats();
     for (const [ruleId, stat] of Object.entries(allStats)) {
-      if (stat.triggers > 50 && (stat.metrics?.precision ?? 1) > 0.8) {
+      if (stat.triggers > RULE_LEARNER.HIGH_TRIGGER_COUNT && (stat.metrics?.precision ?? 1) > RULE_LEARNER.HIGH_PRECISION) {
         suggestions.push({
           type: 'specialize',
           ruleId,
           message: `规则 ${ruleId} 触发 ${stat.triggers} 次且精准度高 (${((stat.metrics?.precision ?? 1) * 100).toFixed(0)}%)，建议创建项目定制版本`,
-          confidence: 0.6,
+          confidence: RULE_LEARNER.CONFIDENCE_SPECIALIZE,
           evidence: stat.metrics,
         });
       }
@@ -174,12 +178,12 @@ export class RuleLearner {
     for (const [ruleId, stat] of Object.entries(allStats)) {
       if (stat.triggers === 0 && stat.lastTriggered) {
         const daysSinceLastTrigger = (Date.now() - new Date(stat.lastTriggered).getTime()) / 86400000;
-        if (daysSinceLastTrigger > 30) {
+        if (daysSinceLastTrigger > RULE_LEARNER.UNUSED_DAYS_THRESHOLD) {
           suggestions.push({
             type: 'review_unused',
             ruleId,
-            message: `规则 ${ruleId} 超过 30 天未触发，建议审查是否仍需保留`,
-            confidence: 0.4,
+            message: `规则 ${ruleId} 超过 ${RULE_LEARNER.UNUSED_DAYS_THRESHOLD} 天未触发，建议审查是否仍需保留`,
+            confidence: RULE_LEARNER.CONFIDENCE_REVIEW,
             evidence: { daysSinceLastTrigger: Math.round(daysSinceLastTrigger), triggers: stat.triggers },
           });
         }
@@ -218,7 +222,7 @@ export class RuleLearner {
     const metrics = this.getMetrics(ruleId);
 
     // 14 天后判定
-    if (metrics.precision < 0.5 && stat.triggers >= PROBLEMATIC_THRESHOLD.minTriggers) {
+    if (metrics.precision < RULE_LEARNER.LOW_PRECISION && stat.triggers >= PROBLEMATIC_THRESHOLD.minTriggers) {
       return {
         status: 'ineffective',
         triggers: stat.triggers,

package/lib/service/quality/QualityScorer.js

@@ -4,13 +4,9 @@
  * 每个维度评分 0-1，加权求和
  */
 
-const DEFAULT_WEIGHTS = {
-  completeness: 0.35,
-  format: 0.25,
-  codeQuality: 0.25,
-  metadata: 0.15,
-  engagement: 0.00,
-};
+import { QUALITY_WEIGHTS, QUALITY_GRADES, CODE_LENGTH } from '../../shared/constants.js';
+
+const DEFAULT_WEIGHTS = QUALITY_WEIGHTS;
 
 export class QualityScorer {
   #weights;
@@ -102,9 +98,9 @@ export class QualityScorer {
     let s = 0;
     const code = r.code;
 
-    // 长度适中 (10-5000)
-    if (code.length >= 10 && code.length <= 5000) s += 0.3;
-    else if (code.length > 5000) s += 0.15;
+    // 长度适中
+    if (code.length >= CODE_LENGTH.MIN && code.length <= CODE_LENGTH.MAX) s += 0.3;
+    else if (code.length > CODE_LENGTH.MAX) s += 0.15;
 
     // 无 TODO/FIXME/HACK
     if (!/\b(TODO|FIXME|HACK|XXX)\b/.test(code)) s += 0.2;
@@ -144,10 +140,10 @@ export class QualityScorer {
    * 分数转等级
    */
   #toGrade(score) {
-    if (score >= 0.9) return 'A';
-    if (score >= 0.75) return 'B';
-    if (score >= 0.6) return 'C';
-    if (score >= 0.4) return 'D';
+    if (score >= QUALITY_GRADES.A) return 'A';
+    if (score >= QUALITY_GRADES.B) return 'B';
+    if (score >= QUALITY_GRADES.C) return 'C';
+    if (score >= QUALITY_GRADES.D) return 'D';
     return 'F';
   }
 }

package/lib/shared/constants.js

@@ -0,0 +1,161 @@
+/**
+ * 全局常量注册表 — 集中管理所有魔法数字和阈值
+ *
+ * 取代散落在各模块中的硬编码数字，方便统一调参和文档化。
+ *
+ * @module shared/constants
+ */
+
+// ─── 质量评分 ───────────────────────────────────────────
+
+/** QualityScorer 维度权重 */
+export const QUALITY_WEIGHTS = Object.freeze({
+  completeness: 0.35,
+  format:       0.25,
+  codeQuality:  0.25,
+  metadata:     0.15,
+  engagement:   0.00,
+});
+
+/** QualityScorer 等级分界线 */
+export const QUALITY_GRADES = Object.freeze({
+  A: 0.9,
+  B: 0.75,
+  C: 0.6,
+  D: 0.4,
+});
+
+/** 代码质量评估 — 合理长度范围 */
+export const CODE_LENGTH = Object.freeze({
+  MIN: 10,
+  MAX: 5000,
+});
+
+// ─── Guard 规则学习 ──────────────────────────────────────
+
+/** RuleLearner 规则健康阈值 */
+export const RULE_LEARNER = Object.freeze({
+  /** 触发高误报规则的条件 */
+  PROBLEMATIC_FALSE_POSITIVE_RATE: 0.3,
+  PROBLEMATIC_MIN_TRIGGERS: 5,
+  /** 规则建议置信度 */
+  CONFIDENCE_TUNE:        0.7,
+  CONFIDENCE_DISABLE:     0.8,
+  CONFIDENCE_SPECIALIZE:  0.6,
+  CONFIDENCE_REVIEW:      0.4,
+  /** 触发数阈值 */
+  HIGH_TRIGGER_COUNT:     50,
+  HIGH_PRECISION:         0.8,
+  /** 闲置天数阈值 */
+  UNUSED_DAYS_THRESHOLD:  30,
+  /** 精度下限 */
+  LOW_PRECISION:          0.5,
+});
+
+// ─── 合规报告 ────────────────────────────────────────────
+
+/** ComplianceReporter 默认 Quality Gate */
+export const QUALITY_GATE = Object.freeze({
+  MAX_ERRORS:   0,
+  MAX_WARNINGS: 20,
+  MIN_SCORE:    70,
+});
+
+/** ComplianceReporter 扣分权重 */
+export const COMPLIANCE_SCORING = Object.freeze({
+  ERROR_PENALTY:            5,
+  WARNING_PENALTY:          1,
+  INFO_PENALTY:             0.2,
+  PROBLEMATIC_RULE_PENALTY: 3,
+  HIGH_F1_BONUS:            5,
+  HIGH_F1_THRESHOLD:        0.8,
+  LOW_PRECISION_THRESHOLD:  0.5,
+  MAX_FILES_DEFAULT:        500,
+});
+
+// ─── 知识置信度 ──────────────────────────────────────────
+
+/** 知识条目默认置信度和阈值 */
+export const KNOWLEDGE_CONFIDENCE = Object.freeze({
+  /** 默认 confidence（Reasoning VO） */
+  DEFAULT:              0.7,
+  /** pending 条目纳入交付的最低 confidence */
+  PENDING_MIN:          0.7,
+  /** rankScore 中 confidence 缺省值 */
+  RANK_DEFAULT:         0.5,
+  /** Bootstrap refine 时的 AI 默认 confidence */
+  BOOTSTRAP_DEFAULT:    0.6,
+  /** 自动提交时的 bootstrap confidence */
+  BOOTSTRAP_SUBMIT:     0.8,
+});
+
+// ─── 搜索管线 ────────────────────────────────────────────
+
+/** SearchEngine 配置 */
+export const SEARCH = Object.freeze({
+  DEFAULT_LIMIT:  10,
+  MAX_RESULTS:    100,
+});
+
+// ─── 文件监听器 ──────────────────────────────────────────
+
+/** FileWatcher 配置 */
+export const FILE_WATCHER = Object.freeze({
+  DEBOUNCE_DELAY_MS:           300,
+  STABILITY_THRESHOLD_MS:      500,
+  POLL_INTERVAL_MS:            100,
+  BINARY_INTERVAL_MS:          300,
+  MAX_FILE_SIZE_BYTES:         1024 * 1024,
+});
+
+// ─── AI Provider ─────────────────────────────────────────
+
+/** AiProvider 熔断配置 */
+export const AI_CIRCUIT_BREAKER = Object.freeze({
+  FAILURE_THRESHOLD: 5,
+});
+
+// ─── 缓存 ────────────────────────────────────────────────
+
+/** ToolResultCache 配置 */
+export const CACHE = Object.freeze({
+  MAX_FILE_ENTRIES:   200,
+  MAX_SEARCH_ENTRIES: 500,
+  /** 缓存条目默认 TTL（毫秒），0 = 不过期 */
+  DEFAULT_TTL_MS:     30 * 60 * 1000,   // 30 分钟
+});
+
+// ─── 性能监控 ────────────────────────────────────────────
+
+/** PerformanceMonitor 配置 */
+export const MONITORING = Object.freeze({
+  SLOW_REQUEST_THRESHOLD_MS: 1000,
+  ERROR_ALERT_THRESHOLD:     10,
+});
+
+// ─── Cursor 交付 ─────────────────────────────────────────
+
+/** CursorDeliveryPipeline 排序权重 */
+export const DELIVERY_RANK = Object.freeze({
+  CONFIDENCE_WEIGHT:  50,
+  AUTHORITY_WEIGHT:   30,
+  USE_COUNT_MAX:      10,
+  USE_COUNT_WEIGHT:   2,
+  ACTIVE_BONUS:       10,
+});
+
+export default {
+  QUALITY_WEIGHTS,
+  QUALITY_GRADES,
+  CODE_LENGTH,
+  RULE_LEARNER,
+  QUALITY_GATE,
+  COMPLIANCE_SCORING,
+  KNOWLEDGE_CONFIDENCE,
+  SEARCH,
+  FILE_WATCHER,
+  AI_CIRCUIT_BREAKER,
+  CACHE,
+  MONITORING,
+  DELIVERY_RANK,
+};

package/lib/shared/utils/common.js

@@ -0,0 +1,68 @@
+/**
+ * 通用工具函数 — 消除跨模块重复代码
+ *
+ * @module shared/utils/common
+ */
+
+// ─── JSON 安全解析 ──────────────────────────────────────
+
+/**
+ * 安全解析 JSON 字符串，失败时返回 fallback
+ * 消除各 Repository / handler 中重复的 try-catch JSON.parse
+ *
+ * @param {string|object|null|undefined} value — 值（可能是 JSON 字符串、对象或空值）
+ * @param {*} [fallback=null] — 解析失败时的回退值
+ * @returns {*}
+ */
+export function safeJsonParse(value, fallback = null) {
+  if (value == null || value === 'null' || value === '') return fallback;
+  if (typeof value === 'object') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * 安全序列化到 JSON，处理 toJSON() 方法和空值
+ * 消除 _entityToRow 中重复的 JSON.stringify 逻辑
+ *
+ * @param {*} value — 需要序列化的值
+ * @param {*} [fallback='{}'] — 值为空时的回退
+ * @returns {string}
+ */
+export function safeJsonStringify(value, fallback = '{}') {
+  if (value == null) return fallback;
+  if (typeof value?.toJSON === 'function') {
+    return JSON.stringify(value.toJSON());
+  }
+  return JSON.stringify(value);
+}
+
+// ─── 时间 ────────────────────────────────────────────────
+
+/**
+ * 返回当前 Unix 时间戳（秒）
+ * 消除各处 Math.floor(Date.now() / 1000) 的重复
+ *
+ * @returns {number}
+ */
+export function unixNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+// ─── 安全默认值 ──────────────────────────────────────────
+
+/**
+ * 返回非空字符串值或 fallback
+ * @param {*} value
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function strOr(value, fallback = '') {
+  if (typeof value === 'string' && value.trim()) return value;
+  return fallback;
+}
+
+export default { safeJsonParse, safeJsonStringify, unixNow, strOr };

package/package.json

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