autosnippet 2.13.0 → 2.15.0

package/README.md

@@ -240,7 +240,7 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 
 ## MCP 工具一览
 
-38 个 MCP 工具按功能分组（省略了 **autosnippet_** 前缀）：
+39 个 MCP 工具按功能分组（省略了 **autosnippet_** 前缀）：
 
 | 分类 | 工具 |
 |------|------|
@@ -248,6 +248,7 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 | **搜索** | `search`（统合入口）、`context_search`（4 层漏斗）、`keyword_search`、`semantic_search` |
 | **Recipe 浏览** | `list_recipes`、`get_recipe`、`list_rules`、`patterns`、`list_facts`、`recipe_insights`、`confirm_usage` |
 | **候选管理** | `validate_candidate`、`check_duplicate`、`submit_knowledge`、`submit_knowledge_batch`、`enrich_candidates` |
+| **开发文档** | `save_document` |
 | **知识图谱** | `graph_query`、`graph_impact`、`graph_path`、`graph_stats` |
 | **项目结构** | `get_targets`、`get_target_files`、`get_target_metadata` |
 | **Guard** | `guard_check`、`guard_audit_files`、`scan_project` |

package/bin/cli.js

@@ -658,6 +658,7 @@ program
       console.log(`   Channel A (Always-On Rules): ${result.channelA.rulesCount} 条规则 (${result.channelA.tokensUsed} tokens)`);
       console.log(`   Channel B (Smart Rules):     ${result.channelB.topicCount} 个主题, ${result.channelB.patternsCount} 个模式 (${result.channelB.totalTokens} tokens)`);
       console.log(`   Channel C (Agent Skills):    ${result.channelC.synced} 个 Skills 已同步`);
+      console.log(`   Channel D (Dev Documents):   ${result.channelD?.documentsCount || 0} 篇文档`);
       if (result.channelC.errors > 0) {
         console.log(`   ⚠️  ${result.channelC.errors} 个错误`);
       }

package/lib/cli/UpgradeService.js

@@ -181,7 +181,8 @@ export class UpgradeService {
           pipeline.deliver()
             .then(result => {
               console.log(`   ✅ Cursor Delivery: ${result.channelA.rulesCount} rules, ` +
-                `${result.channelB.topicCount} topics, ${result.channelC.synced} skills`);
+                `${result.channelB.topicCount} topics, ${result.channelC.synced} skills, ` +
+                `${result.channelD?.documentsCount || 0} documents`);
             })
             .catch(err => {
               console.log(`   ⚠️  Cursor Delivery 跳过: ${err.message}`);

package/lib/domain/knowledge/Lifecycle.js

@@ -85,6 +85,7 @@ const KIND_MAP = {
   'call-chain':          'fact',
   'data-flow':           'fact',
   'module-dependency':   'fact',
+  'dev-document':        'fact',
 };
 
 /**

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,55 +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);
-      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/external/mcp/handlers/bootstrap/pipeline/orchestrator.js

@@ -1108,7 +1108,8 @@ export async function fillDimensionsV3(fillContext) {
       logger.info(`[Bootstrap-v3] 🚀 Cursor Delivery complete — ` +
         `A: ${deliveryResult.channelA.rulesCount} rules, ` +
         `B: ${deliveryResult.channelB.topicCount} topics, ` +
-        `C: ${deliveryResult.channelC.synced} skills`);
+        `C: ${deliveryResult.channelC.synced} skills, ` +
+        `D: ${deliveryResult.channelD?.documentsCount || 0} documents`);
     }
   } catch (deliveryErr) {
     logger.warn(`[Bootstrap-v3] Cursor Delivery failed (non-blocking): ${deliveryErr.message}`);

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

@@ -237,6 +237,80 @@ export async function knowledgeLifecycle(ctx, args) {
 
 // ─── 内部辅助 ──────────────────────────────────────────────
 
+/**
+ * 保存开发文档 (autosnippet_save_document)
+ *
+ * 精简入口：仅需 title + markdown。
+ * 自动设置 knowledgeType='dev-document', kind='fact', source='agent'。
+ * 不走 RecipeReadiness 检查（文档无需 doClause/trigger）。
+ * 支持 autoApprove — 文档直接进入 active 状态。
+ */
+export async function saveDocument(ctx, args) {
+  if (!args.title || !args.title.trim()) {
+    throw new Error('title 必填');
+  }
+  if (!args.markdown || !args.markdown.trim()) {
+    throw new Error('markdown 必填');
+  }
+
+  // 限流
+  const blocked = await _checkRateLimit('autosnippet_save_document', args.client_id);
+  if (blocked) return blocked;
+
+  const service = ctx.container.get('knowledgeService');
+
+  const data = {
+    title:         args.title.trim(),
+    description:   args.description || '',
+    knowledgeType: 'dev-document',
+    kind:          'fact',
+    source:        args.source || 'agent',
+    scope:         args.scope || 'project-specific',
+    tags:          args.tags || [],
+    content: {
+      markdown: args.markdown,
+      pattern:  '',
+    },
+    // 文档不需要 Cursor Delivery 字段
+    trigger:    '',
+    doClause:   '',
+    dontClause: '',
+    whenClause: '',
+    topicHint:  '',
+    coreCode:   '',
+    // 基础推理
+    reasoning: {
+      whyStandard: 'Agent development document — preserved for team knowledge',
+      sources:     ['agent'],
+      confidence:  0.8,
+    },
+  };
+
+  const entry = await service.create(data, { userId: 'mcp' });
+
+  // 自动发布（dev-document 不需要人工审核）
+  try {
+    await service.publish(entry.id, { userId: 'mcp' });
+  } catch {
+    // 发布失败保持 pending — 非阻塞
+  }
+
+  return envelope({
+    success: true,
+    data: {
+      id:        entry.id,
+      lifecycle: 'active',
+      title:     entry.title,
+      kind:      'fact',
+      knowledgeType: 'dev-document',
+    },
+    message: `文档「${entry.title}」已保存到知识库。`,
+    meta: { tool: 'autosnippet_save_document' },
+  });
+}
+
+// ─── 内部辅助 ──────────────────────────────────────────────
+
 /**
  * V3 wire format → RecipeReadinessChecker 兼容格式
  */

package/lib/external/mcp/tools.js

@@ -23,6 +23,7 @@ export const TOOL_GATEWAY_MAP = {
   autosnippet_submit_knowledge: { action: 'knowledge:create', resource: 'knowledge' },
   autosnippet_submit_knowledge_batch: { action: 'knowledge:create', resource: 'knowledge' },
   autosnippet_knowledge_lifecycle: { action: 'knowledge:update', resource: 'knowledge' },
+  autosnippet_save_document: { action: 'knowledge:create', resource: 'knowledge' },
 };
 
 export const TOOLS = [
@@ -751,4 +752,26 @@ export const TOOLS = [
       required: ['id', 'action'],
     },
   },
+  // 39. 保存开发文档
+  {
+    name: 'autosnippet_save_document',
+    description:
+      '保存开发文档到知识库（架构设计、排查报告、决策记录、调研笔记等）。\n' +
+      '仅需 title + markdown，无需填写 kind/doClause/trigger 等 Cursor Delivery 字段。\n' +
+      '文档自动以 dev-document 类型存储，不参与 Cursor Rules 压缩，保持原文完整性。\n' +
+      '交付路径: Channel D → .cursor/skills/autosnippet-devdocs/references/*.md。\n' +
+      'Agent 可通过 autosnippet_search 全文检索已保存的文档。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title:       { type: 'string', description: '文档标题（中英文皆可）' },
+        markdown:    { type: 'string', description: '文档 Markdown 全文' },
+        description: { type: 'string', description: '一句话摘要（可选）' },
+        tags:        { type: 'array', items: { type: 'string' }, description: '标签列表，如 ["adr", "debug-report", "design-doc", "research"]' },
+        scope:       { type: 'string', enum: ['universal', 'project-specific'], default: 'project-specific', description: '适用范围' },
+        source:      { type: 'string', description: '来源标识（默认 agent）' },
+      },
+      required: ['title', 'markdown'],
+    },
+  },
 ];

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 {