autosnippet 2.9.0 → 2.11.0

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

@@ -262,40 +262,41 @@ export async function graphImpact(ctx, args) {
 }
 
 /**
- * 降级：从 Recipe.relations_json 提取关系（不依赖 knowledge_edges 表）
+ * 降级：从 knowledge_entries.relations 提取关系（不依赖 knowledge_edges 表）
  */
 async function _fallbackRelationsFromRecipe(ctx, nodeId, relation, direction) {
-  const recipeService = ctx.container.get('recipeService');
   try {
-    const recipe = await recipeService.getRecipe(nodeId);
-    if (!recipe) return { outgoing: [], incoming: [] };
+    const knowledgeService = ctx.container.get('knowledgeService');
+    const entry = await knowledgeService.get(nodeId);
+    if (!entry) return { outgoing: [], incoming: [] };
 
+    const relJson = typeof entry.relations?.toJSON === 'function' ? entry.relations.toJSON() : (entry.relations || {});
     const outgoing = [];
     if (direction === 'both' || direction === 'out') {
-      for (const [relType, targets] of Object.entries(recipe.relations || {})) {
+      for (const [relType, targets] of Object.entries(relJson)) {
         if (relation && relType !== relation) continue;
         for (const t of (Array.isArray(targets) ? targets : [])) {
-          outgoing.push({ fromId: nodeId, fromType: 'recipe', toId: t.target || t.id || t, toType: 'recipe', relation: relType });
+          outgoing.push({ fromId: nodeId, fromType: 'knowledge', toId: t.target || t.id || t, toType: 'knowledge', relation: relType });
         }
       }
     }
 
-    // 反向查找：其他 Recipe 中 relations_json 包含当前 nodeId
+    // 反向查找：其他条目中 relations 包含当前 nodeId
     const incoming = [];
     if (direction === 'both' || direction === 'in') {
-      const recipeRepo = ctx.container.get('recipeRepository');
-      const reverseRows = recipeRepo.db.prepare(
-        `SELECT id, relations_json FROM recipes WHERE relations_json LIKE ? AND id != ?`
+      const knowledgeRepo = ctx.container.get('knowledgeRepository');
+      const reverseRows = knowledgeRepo.db.prepare(
+        `SELECT id, relations FROM knowledge_entries WHERE relations LIKE ? AND id != ?`
       ).all(`%${nodeId}%`, nodeId);
       for (const row of reverseRows) {
         try {
-          const rels = JSON.parse(row.relations_json || '{}');
+          const rels = JSON.parse(row.relations || '{}');
           for (const [relType, targets] of Object.entries(rels)) {
             if (relation && relType !== relation) continue;
             for (const t of (Array.isArray(targets) ? targets : [])) {
               const targetId = t.target || t.id || t;
               if (targetId === nodeId) {
-                incoming.push({ fromId: row.id, fromType: 'recipe', toId: nodeId, toType: 'recipe', relation: relType });
+                incoming.push({ fromId: row.id, fromType: 'knowledge', toId: nodeId, toType: 'knowledge', relation: relType });
               }
             }
           }
@@ -308,23 +309,23 @@ async function _fallbackRelationsFromRecipe(ctx, nodeId, relation, direction) {
 }
 
 /**
- * 降级：从 relations_json 反查受影响的 Recipe
+ * 降级：从 knowledge_entries.relations 反查受影响的条目
  */
 async function _fallbackImpactFromRecipe(ctx, nodeId) {
   try {
-    const recipeRepo = ctx.container.get('recipeRepository');
-    const rows = recipeRepo.db.prepare(
-      `SELECT id, title, relations_json FROM recipes WHERE relations_json LIKE ? AND id != ?`
+    const knowledgeRepo = ctx.container.get('knowledgeRepository');
+    const rows = knowledgeRepo.db.prepare(
+      `SELECT id, title, relations FROM knowledge_entries WHERE relations LIKE ? AND id != ?`
     ).all(`%${nodeId}%`, nodeId);
 
     const impacted = [];
     for (const row of rows) {
       try {
-        const rels = JSON.parse(row.relations_json || '{}');
+        const rels = JSON.parse(row.relations || '{}');
         for (const [relType, targets] of Object.entries(rels)) {
           for (const t of (Array.isArray(targets) ? targets : [])) {
             if ((t.target || t.id || t) === nodeId) {
-              impacted.push({ id: row.id, title: row.title, type: 'recipe', relation: relType, depth: 1 });
+              impacted.push({ id: row.id, title: row.title, type: 'knowledge', relation: relType, depth: 1 });
             }
           }
         }
@@ -364,17 +365,18 @@ export async function graphPath(ctx, args) {
  */
 async function _fallbackPathFromRecipe(ctx, fromId, toId) {
   try {
-    const recipeService = ctx.container.get('recipeService');
-    const recipe = await recipeService.getRecipe(fromId);
-    if (!recipe) return { found: false, path: [], depth: -1 };
+    const knowledgeService = ctx.container.get('knowledgeService');
+    const entry = await knowledgeService.get(fromId);
+    if (!entry) return { found: false, path: [], depth: -1 };
 
-    for (const [relType, targets] of Object.entries(recipe.relations || {})) {
+    const relJson = typeof entry.relations?.toJSON === 'function' ? entry.relations.toJSON() : (entry.relations || {});
+    for (const [relType, targets] of Object.entries(relJson)) {
       for (const t of (Array.isArray(targets) ? targets : [])) {
         const targetId = t.target || t.id || t;
         if (targetId === toId) {
           return {
             found: true,
-            path: [{ from: { id: fromId, type: 'recipe' }, to: { id: toId, type: 'recipe' }, relation: relType }],
+            path: [{ from: { id: fromId, type: 'knowledge' }, to: { id: toId, type: 'knowledge' }, relation: relType }],
             depth: 1,
           };
         }

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

@@ -30,22 +30,23 @@ export async function health(ctx) {
       checks.database = true;
       // 知识库统计（轻量聚合查询）
       try {
+        // V3: knowledge_entries 统一表（lifecycle 替代 status）
         const rStats = db.prepare(`
           SELECT COUNT(*) as total,
-            SUM(CASE WHEN status='active' THEN 1 ELSE 0 END) as active,
+            SUM(CASE WHEN lifecycle='active' THEN 1 ELSE 0 END) as active,
             SUM(CASE WHEN kind='rule' THEN 1 ELSE 0 END) as rules,
             SUM(CASE WHEN kind='pattern' THEN 1 ELSE 0 END) as patterns,
             SUM(CASE WHEN kind='fact' THEN 1 ELSE 0 END) as facts
-          FROM recipes
+          FROM knowledge_entries
         `).get();
-        const cStats = db.prepare(`
+        const cPending = db.prepare(`
           SELECT COUNT(*) as total,
-            SUM(CASE WHEN status='pending' THEN 1 ELSE 0 END) as pending
-          FROM candidates
+            SUM(CASE WHEN lifecycle='pending' THEN 1 ELSE 0 END) as pending
+          FROM knowledge_entries
         `).get();
         knowledgeBase = {
           recipes: { total: rStats.total, active: rStats.active, rules: rStats.rules, patterns: rStats.patterns, facts: rStats.facts },
-          candidates: { total: cStats.total, pending: cStats.pending },
+          candidates: { total: cPending.total, pending: cPending.pending },
         };
       } catch { /* 统计查询失败不影响 health */ }
     }
@@ -132,9 +133,6 @@ export function capabilities() {
     autosnippet_get_target_metadata: 'structure',
     autosnippet_validate_candidate: 'validate',
     autosnippet_check_duplicate: 'validate',
-    autosnippet_submit_candidate: 'submit',
-    autosnippet_submit_candidates: 'submit',
-    autosnippet_submit_draft_recipes: 'submit',
     autosnippet_guard_check: 'guard',
     autosnippet_guard_audit_files: 'guard',
     autosnippet_scan_project: 'scan',
@@ -191,9 +189,9 @@ export function capabilities() {
       tools,
       workflows: [
         { name: '知识查询', steps: ['search（推荐首选，auto mode 融合）', 'get_recipe', 'confirm_usage'], tips: '精确匹配用 keyword_search，需意图+会话上下文用 context_search' },
-        { name: '单文件候选提交', steps: ['check_duplicate', 'validate_candidate', 'submit_candidate'] },
-        { name: '批量 Target 扫描', steps: ['get_targets', 'get_target_files', '(Agent 分析)', 'submit_candidates'] },
-        { name: '全项目深度扫描', steps: ['scan_project', '(Agent 语义分析)', 'submit_candidates', 'enrich_candidates'] },
+        { name: '单条知识提交', steps: ['check_duplicate', 'validate_candidate', 'submit_knowledge'] },
+        { name: '批量 Target 扫描', steps: ['get_targets', 'get_target_files', '(Agent 分析)', 'submit_knowledge_batch'] },
+        { name: '全项目深度扫描', steps: ['scan_project', '(Agent 语义分析)', 'submit_knowledge_batch', 'enrich_candidates'] },
         { name: '候选就绪检查', steps: ['enrich_candidates', 'validate_candidate', 'check_duplicate'] },
       ],
     },

package/lib/external/mcp/tools.js

@@ -1,7 +1,9 @@
 /**
- * MCP 工具定义（38 个）+ Gateway 映射
+ * MCP 工具定义（35 个）+ Gateway 映射
  *
  * 只包含 JSON Schema 级别的声明，不含任何业务逻辑。
+ * V3: 旧 submit_candidate / submit_candidates / submit_draft_recipes 已移除，
+ *     统一使用 submit_knowledge / submit_knowledge_batch / knowledge_lifecycle。
  */
 
 /**
@@ -9,9 +11,6 @@
  * 只读工具不在此映射中，跳过 Gateway 以保持性能
  */
 export const TOOL_GATEWAY_MAP = {
-  autosnippet_submit_candidate: { action: 'candidate:create', resource: 'candidates' },
-  autosnippet_submit_candidates: { action: 'candidate:create', resource: 'candidates' },
-  autosnippet_submit_draft_recipes: { action: 'candidate:create', resource: 'candidates' },
   autosnippet_guard_audit_files: { action: 'guard_rule:check_code', resource: 'guard_rules' },
   autosnippet_scan_project: { action: 'guard_rule:check_code', resource: 'guard_rules' },
   autosnippet_enrich_candidates: { action: 'candidate:update', resource: 'candidates' },
@@ -20,6 +19,10 @@ export const TOOL_GATEWAY_MAP = {
   autosnippet_create_skill: { action: 'create:skills', resource: 'skills' },
   autosnippet_delete_skill: { action: 'delete:skills', resource: 'skills' },
   autosnippet_update_skill: { action: 'update:skills', resource: 'skills' },
+  // V3 知识条目
+  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' },
 };
 
 export const TOOLS = [
@@ -283,132 +286,8 @@ export const TOOLS = [
       required: ['candidate'],
     },
   },
-  // 18. 单条候选提交（支持结构化 content）
-  {
-    name: 'autosnippet_submit_candidate',
-    description:
-      '提交单条代码片段候选供审核。支持 V2 结构化全字段。含限流保护。Agent 必须提供 reasoning（推理依据）。\n' +
-      '⚠️ Recipe-Ready 要求：为使候选直接审核通过为 Recipe，请尽量填写以下字段：\n' +
-      '  必填: title, code, language, category, trigger(@开头), summary_cn, headers(完整import语句)\n' +
-      '  强烈建议: summary_en, usageGuide(Markdown ### 章节), reasoning, knowledgeType, complexity\n' +
-      '  推荐: usageGuide_en, rationale, steps, constraints, relations\n' +
-      '如字段不全，返回值中 recipeReadyHints 会提示缺失字段，Agent 应据此补全后重新提交或调用 enrich_candidates 查漏。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        // ── 核心（必填）──
-        title: { type: 'string', description: '中文简短标题（≤20字）' },
-        code: { type: 'string', description: '代码片段（映射到 content.pattern），使用 Xcode 占位符 <#name#>' },
-        language: { type: 'string', description: '编程语言：swift / objectivec（必须小写）' },
-        // ── 分类 ──
-        category: { type: 'string', description: '分类（必填）：View/Service/Tool/Model/Network/Storage/UI/Utility' },
-        knowledgeType: { type: 'string', description: '知识维度：code-pattern|architecture|best-practice|code-standard|code-relation|inheritance|call-chain|data-flow|module-dependency|boundary-constraint|code-style|solution' },
-        complexity: { type: 'string', enum: ['beginner', 'intermediate', 'advanced'] },
-        scope: { type: 'string', enum: ['universal', 'project-specific', 'target-specific'], description: '适用范围' },
-        tags: { type: 'array', items: { type: 'string' }, description: '可搜索标签' },
-        // ── 描述与文档（双语） ──
-        description: { type: 'string', description: '一句话功能描述' },
-        summary: { type: 'string', description: '中文详细摘要（等同 summary_cn，Markdown）' },
-        summary_cn: { type: 'string', description: '中文摘要（≤100字）。与 summary 二选一' },
-        summary_en: { type: 'string', description: '英文摘要（≤100 words）。强烈建议提供，提升检索与 AI 理解' },
-        trigger: { type: 'string', description: '触发关键词（必填，@开头，小写，如 @video-cover-cell）' },
-        usageGuide: { type: 'string', description: '中文使用指南（等同 usageGuide_cn，Markdown ### 章节格式）' },
-        usageGuide_cn: { type: 'string', description: '中文使用指南。与 usageGuide 二选一' },
-        usageGuide_en: { type: 'string', description: '英文使用指南（Markdown ### 章节格式）。推荐提供' },
-        // ── 结构化内容 ──
-        rationale: { type: 'string', description: '设计原理/为什么这样做' },
-        steps: { type: 'array', items: { type: 'object' }, description: '实施步骤 [{title, description, code}]' },
-        codeChanges: { type: 'array', items: { type: 'object' }, description: '代码变更 [{file, before, after, explanation}]' },
-        verification: { type: 'object', description: '验证方式 {method, expectedResult, testCode}' },
-        headers: { type: 'array', items: { type: 'string' }, description: '完整 import/include 语句（必填）如 ["#import <Module/Header.h>"] 或 ["import Foundation"]' },
-        // ── 约束与关系 ──
-        constraints: { type: 'object', description: '约束 {boundaries[], preconditions[], sideEffects[], guards[{pattern,severity,message}]}' },
-        relations: { type: 'object', description: '关系 {dependsOn[], extends[], conflicts[], related[], inherits[], implements[], calls[], dataFlow[]}，每项 {target, description}' },
-        // ── 质量 & 来源 ──
-        quality: { type: 'object', description: '质量评分 {codeCompleteness, projectAdaptation, documentationClarity} (0-1)' },
-        sourceFile: { type: 'string', description: '来源文件路径' },
-        // ── 推理依据（Reasoning）— 必填 ──
-        reasoning: {
-          type: 'object',
-          description: '推理依据：为什么提取这段代码。Agent 必须填写。',
-          properties: {
-            whyStandard: { type: 'string', description: '为什么这段代码值得沉淀为知识——如"该模式在项目中被反复使用且新人容易写错"' },
-            sources: { type: 'array', items: { type: 'string' }, description: '来源列表：文件路径、文档链接、上下文引用等' },
-            confidence: { type: 'number', description: '置信度 0-1，表示 Agent 对这条候选质量的确信程度' },
-            qualitySignals: { type: 'object', description: '质量信号 {clarity, reusability, importance} 等自由 KV' },
-            alternatives: { type: 'array', items: { type: 'string' }, description: '备选方案描述（如果有替代实现）' },
-          },
-          required: ['whyStandard', 'sources', 'confidence'],
-        },
-        source: { type: 'string', description: '来源标识（默认 mcp）' },
-        clientId: { type: 'string', description: '客户端标识（用于限流）' },
-      },
-      required: ['title', 'code', 'language'],
-    },
-  },
-  // 19. 批量候选提交
-  {
-    name: 'autosnippet_submit_candidates',
-    description:
-      '批量提交候选到 Candidates，支持去重与限流。每个 item 支持 V2 全字段。返回逐条结果与 recipeReadyHints。\n' +
-      '⚠️ Recipe-Ready：请尽量每条填写 category, trigger(@开头), summary_cn, summary_en, headers, reasoning。缺失字段会在 recipeReadyHints 中提示。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        targetName: { type: 'string', description: 'Target 名称' },
-        items: {
-          type: 'array',
-          description: '候选数组，每项字段详见 submit_candidate。尽量填充全部 Recipe-Ready 字段。',
-          items: {
-            type: 'object',
-            properties: {
-              title: { type: 'string' }, code: { type: 'string' }, language: { type: 'string' },
-              category: { type: 'string' }, knowledgeType: { type: 'string' },
-              complexity: { type: 'string' }, scope: { type: 'string' },
-              tags: { type: 'array', items: { type: 'string' } },
-              description: { type: 'string' },
-              summary: { type: 'string', description: '中文摘要（等同 summary_cn）' },
-              summary_cn: { type: 'string', description: '中文摘要' },
-              summary_en: { type: 'string', description: '英文摘要（强烈建议）' },
-              trigger: { type: 'string', description: '触发词（@开头）' },
-              usageGuide: { type: 'string', description: '中文使用指南（等同 usageGuide_cn）' },
-              usageGuide_cn: { type: 'string', description: '中文使用指南' },
-              usageGuide_en: { type: 'string', description: '英文使用指南' },
-              rationale: { type: 'string' },
-              steps: { type: 'array', items: { type: 'object' } },
-              codeChanges: { type: 'array', items: { type: 'object' } },
-              verification: { type: 'object' },
-              headers: { type: 'array', items: { type: 'string' }, description: '完整 import 语句' },
-              constraints: { type: 'object' }, relations: { type: 'object' },
-              quality: { type: 'object' }, sourceFile: { type: 'string' },
-              reasoning: { type: 'object', description: '{whyStandard, sources[], confidence}（必填）' },
-            },
-            required: ['title', 'code', 'language'],
-          },
-        },
-        source: { type: 'string', default: 'cursor-scan' },
-        deduplicate: { type: 'boolean', default: true },
-        clientId: { type: 'string' },
-      },
-      required: ['targetName', 'items'],
-    },
-  },
-  // 20. 草稿 Recipe 提交
-  {
-    name: 'autosnippet_submit_draft_recipes',
-    description: '解析草稿 Markdown 文件为 Recipe 候选并提交。支持完整 Recipe 和纯介绍。保留解析出的全部结构化字段（trigger/usageGuide/headers 等）。自动生成默认 reasoning。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filePaths: { description: '草稿文件路径（字符串或数组）' },
-        targetName: { type: 'string', default: '_draft' },
-        source: { type: 'string', default: 'copilot-draft' },
-        deleteAfterSubmit: { type: 'boolean', default: false },
-        clientId: { type: 'string' },
-      },
-      required: ['filePaths'],
-    },
-  },
+  // 18-20: [已移除] 旧 submit_candidate / submit_candidates / submit_draft_recipes
+  //        统一使用 V3 submit_knowledge / submit_knowledge_batch / knowledge_lifecycle
   // 21. 能力声明
   {
     name: 'autosnippet_capabilities',
@@ -542,7 +421,7 @@ export const TOOLS = [
     description:
       '① 结构补齐（诊断模式）— 检查候选的字段完整性，返回缺失清单。\n' +
       '检查两层：\n' +
-      '  • Recipe 必填：category、trigger(@开头)、summary_cn、summary_en、headers\n' +
+      '  • Recipe 必填：category、trigger(@开头)、description、headers\n' +
       '  • 语义字段：rationale、knowledgeType、complexity、scope、steps、constraints\n' +
       '不调用内置 AI，仅做诊断。返回每条候选的 missingFields 列表。\n' +
       '\n' +
@@ -574,10 +453,10 @@ export const TOOLS = [
       '⚠️ 产出为启发式初稿，必须执行后续步骤提升质量：\n' +
       '  Step 1: autosnippet_enrich_candidates — 诊断字段缺失，逐条补全必填字段\n' +
       '  Step 2: autosnippet_bootstrap_refine — AI 润色 summary/insight/relations/confidence\n' +
-      '  Step 3: 逐 Target 深入分析，补充更细粒度候选（autosnippet_submit_candidates）\n' +
+      '  Step 3: 逐 Target 深入分析，补充更细粒度知识条目（autosnippet_submit_knowledge_batch）\n' +
       '  Step 4: 对新候选重复 Step 1-2\n' +
       '\n' +
-      '质量标准：每条必须包含 title/code/language/category/trigger/summary_cn/headers/reasoning。',
+      '质量标准：每条必须包含 title/code/language/category/trigger/description/headers/reasoning。',
     inputSchema: {
       type: 'object',
       properties: {
@@ -589,7 +468,7 @@ export const TOOLS = [
       required: [],
     },
   },
-  // 33. Skills 发现：列出所有可用 Agent Skill 及其适用场景
+  // 32. Skills 发现：列出所有可用 Agent Skill 及其适用场景
   {
     name: 'autosnippet_list_skills',
     description:
@@ -603,7 +482,7 @@ export const TOOLS = [
       '  • 执行具体任务前，加载对应的 Skill 获取操作指南和最佳实践',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
-  // 34. Skills 加载：按需获取指定 Skill 的完整操作指南
+  // 33. Skills 加载：按需获取指定 Skill 的完整操作指南
   {
     name: 'autosnippet_load_skill',
     description:
@@ -627,7 +506,7 @@ export const TOOLS = [
       required: ['skillName'],
     },
   },
-  // 35. 创建项目级 Skill
+  // 34. 创建项目级 Skill
   {
     name: 'autosnippet_create_skill',
     description:
@@ -671,7 +550,7 @@ export const TOOLS = [
       required: ['name', 'description', 'content'],
     },
   },
-  // 36. Skill 推荐：基于使用模式分析，推荐创建 Skill
+  // 35. Skill 推荐：基于使用模式分析，推荐创建 Skill
   {
     name: 'autosnippet_suggest_skills',
     description:
@@ -686,7 +565,7 @@ export const TOOLS = [
       '  • 候选被大量驳回时',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
-  // 37. 删除项目级 Skill
+  // 36. 删除项目级 Skill
   {
     name: 'autosnippet_delete_skill',
     description:
@@ -707,7 +586,7 @@ export const TOOLS = [
       required: ['name'],
     },
   },
-  // 38. 更新项目级 Skill
+  // 37. 更新项目级 Skill
   {
     name: 'autosnippet_update_skill',
     description:
@@ -737,7 +616,7 @@ export const TOOLS = [
       required: ['name'],
     },
   },
-  // 36. ② 内容润色：Bootstrap 候选 AI 精炼（Phase 6）
+  // 38. ② 内容润色：Bootstrap 候选 AI 精炼（Phase 6）
   {
     name: 'autosnippet_bootstrap_refine',
     description:
@@ -757,4 +636,119 @@ export const TOOLS = [
       required: [],
     },
   },
+  // ═══ V3 知识条目（统一实体） ═══════════════════════════════
+  // 36. 单条知识提交（V3 wire format 直通）
+  {
+    name: 'autosnippet_submit_knowledge',
+    description:
+      '提交单条知识条目到 AutoSnippet 知识库（V3 统一实体）。\n' +
+      '参数即 wire format — 直接构造 KnowledgeEntry。\n' +
+      '⚠️ Cursor Delivery 字段（kind/doClause/topicHint）直接影响 .mdc 规则文件生成质量，请务必填写。\n' +
+      '\n' +
+      '核心必填: title + language + content(pattern 或 markdown) + kind + doClause\n' +
+      '推荐填写: trigger, topicHint, whenClause, dontClause, coreCode, reasoning, tags\n' +
+      '\n' +
+      '根据 ConfidenceRouter 自动路由：高置信度自动入库(active)，低置信度待审核(pending)。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        // ── 必填 ──
+        title:            { type: 'string', description: '中文标题（≤20字）' },
+        language:         { type: 'string', description: '编程语言（swift/objectivec/javascript/typescript/python，小写）' },
+        content: {
+          type: 'object',
+          description: '内容值对象（必须有 pattern 或 markdown）',
+          properties: {
+            pattern:      { type: 'string', description: '完整代码片段（函数/方法/类实现）' },
+            markdown:     { type: 'string', description: '项目特写 Markdown（技术说明文档）' },
+            rationale:    { type: 'string', description: '设计原理（英文）' },
+            steps:        { type: 'array', items: { type: 'object', properties: {
+              title: { type: 'string' }, description: { type: 'string' }, code: { type: 'string' },
+            }}},
+            codeChanges: { type: 'array', items: { type: 'object' } },
+            verification: { type: 'object' },
+          },
+        },
+        // ── Cursor Delivery（关键字段，影响 .mdc 规则生成） ──
+        kind:             { type: 'string', enum: ['rule', 'pattern', 'fact'], description: '知识类型: rule=必须遵守的规则, pattern=可复用代码模板, fact=参考信息' },
+        doClause:         { type: 'string', description: '正向指令: 英文祈使句 ≤60 tokens（e.g. "Use dependency injection via constructor"）' },
+        dontClause:       { type: 'string', description: '反向约束: 英文（不以 Don\'t 开头），e.g. "Instantiate services with new directly"' },
+        whenClause:       { type: 'string', description: '触发场景: 英文描述何时应用此知识（e.g. "When creating a new ViewController subclass"）' },
+        topicHint:        { type: 'string', description: '主题分组标签，用于 .mdc 文件归类（e.g. "networking", "ui-layout", "error-handling", "data-model"）' },
+        coreCode:         { type: 'string', description: '3-8 行精华代码骨架，可直接复制使用（无 Markdown 格式）' },
+        trigger:          { type: 'string', description: '触发关键词（@前缀 kebab-case，e.g. "@json-parse"）' },
+        // ── 分类 ──
+        category:         { type: 'string', description: '分类: View/Service/Tool/Model/Network/Storage/UI/Utility' },
+        knowledgeType:    { type: 'string', description: '知识维度: code-pattern|architecture|best-practice|boundary-constraint|...' },
+        complexity:       { type: 'string', enum: ['beginner', 'intermediate', 'advanced'] },
+        scope:            { type: 'string', enum: ['universal', 'project-specific', 'target-specific'] },
+        difficulty:       { type: 'string' },
+        tags:             { type: 'array', items: { type: 'string' } },
+        // ── 描述 ──
+        description:      { type: 'string', description: '中文简述 ≤80 字（引用真实类名/方法名）' },
+        // ── 约束与关系 ──
+        constraints:      { type: 'object', description: '约束 {guards[], boundaries[], preconditions[], sideEffects[]}' },
+        relations:        { type: 'object', description: '关系分桶 {inherits[], extends[], depends_on[], conflicts[], related[], ...}' },
+        // ── 推理 ──
+        reasoning: {
+          type: 'object',
+          description: '推理依据',
+          properties: {
+            whyStandard:  { type: 'string', description: '为什么值得沉淀为知识' },
+            sources:      { type: 'array', items: { type: 'string' }, description: '来源文件列表' },
+            confidence:   { type: 'number', description: '置信度 0-1' },
+            qualitySignals: { type: 'object' },
+            alternatives: { type: 'array', items: { type: 'string' } },
+          },
+        },
+        // ── 头文件 ──
+        headers:          { type: 'array', items: { type: 'string' }, description: '完整 import/include 语句' },
+        headerPaths:      { type: 'array', items: { type: 'string' } },
+        moduleName:       { type: 'string' },
+        includeHeaders:   { type: 'boolean' },
+        // ── 控制 ──
+        source:           { type: 'string', description: '来源标识（默认 mcp）' },
+        client_id:        { type: 'string', description: '客户端标识（用于限流）' },
+      },
+      required: ['title', 'language', 'content', 'kind', 'doClause'],
+    },
+  },
+  // 37. 批量知识提交
+  {
+    name: 'autosnippet_submit_knowledge_batch',
+    description:
+      '批量提交知识条目到知识库（V3 统一实体）。\n' +
+      '每条 item 使用与 autosnippet_submit_knowledge 相同的 wire format。\n' +
+      '每条 item 必须包含 Cursor Delivery 字段（kind/doClause），否则生成的 .mdc 规则质量低。\n' +
+      '支持去重。返回逐条结果与 recipeReadyHints。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target_name:  { type: 'string', description: 'Target 名称' },
+        items:        { type: 'array', description: '知识条目数组，每项字段同 submit_knowledge（必须含 kind/doClause）', items: { type: 'object' } },
+        source:       { type: 'string', default: 'cursor-scan', description: '来源标识' },
+        deduplicate:  { type: 'boolean', default: true, description: '是否去重' },
+        client_id:    { type: 'string', description: '客户端标识（用于限流）' },
+      },
+      required: ['target_name', 'items'],
+    },
+  },
+  // 38. 知识条目生命周期操作
+  {
+    name: 'autosnippet_knowledge_lifecycle',
+    description:
+      '知识条目生命周期操作。\n' +
+      '可用操作: submit(draft→pending), approve(pending→approved), reject(pending→rejected),\n' +
+      'publish(approved→active), deprecate(active→deprecated), reactivate(deprecated→active),\n' +
+      'to_draft(rejected→draft), fast_track(draft→active 一键发布)。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:     { type: 'string', description: '知识条目 ID' },
+        action: { type: 'string', enum: ['submit', 'approve', 'reject', 'publish', 'deprecate', 'reactivate', 'to_draft', 'fast_track'], description: '生命周期操作' },
+        reason: { type: 'string', description: 'reject/deprecate 时必须提供原因' },
+      },
+      required: ['id', 'action'],
+    },
+  },
 ];

package/lib/http/HttpServer.js

@@ -13,8 +13,6 @@ import { requestLogger } from './middleware/requestLogger.js';
 import { gatewayMiddleware } from './middleware/gatewayMiddleware.js';
 import { roleResolverMiddleware } from './middleware/roleResolver.js';
 import { CapabilityProbe } from '../core/capability/CapabilityProbe.js';
-import candidateRouter from './routes/candidates.js';
-import recipeRouter from './routes/recipes.js';
 import guardRuleRouter from './routes/guardRules.js';
 import searchRouter from './routes/search.js';
 import healthRouter from './routes/health.js';
@@ -27,6 +25,7 @@ import spmRouter from './routes/spm.js';
 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 apiSpec from './api-spec.js';
 import { initRedisService } from '../infrastructure/cache/RedisService.js';
 import { initCacheAdapter } from '../infrastructure/cache/UnifiedCacheAdapter.js';
@@ -235,12 +234,6 @@ export class HttpServer {
       this.app.use(`${apiPrefix}/monitoring`, monitoringRouter);
     }
 
-    // 候选项路由
-    this.app.use(`${apiPrefix}/candidates`, candidateRouter);
-
-    // 配方路由
-    this.app.use(`${apiPrefix}/recipes`, recipeRouter);
-
     // 守护规则路由
     this.app.use(`${apiPrefix}/rules`, guardRuleRouter);
 
@@ -268,6 +261,19 @@ export class HttpServer {
     // 违规记录路由
     this.app.use(`${apiPrefix}/violations`, violationsRouter);
 
+    // 知识条目路由 (V3)
+    this.app.use(`${apiPrefix}/knowledge`, knowledgeRouter);
+
+    // 根路径 — 返回 API 元信息（避免外部探测产生无意义 404）
+    this.app.all('/', (req, res) => {
+      res.json({
+        name: 'AutoSnippet API',
+        version: '2.0',
+        docs: '/api-spec',
+        health: `${apiPrefix}/health`,
+      });
+    });
+
     // 404 处理
     this.app.use('*', (req, res) => {
       res.status(404).json({

package/lib/http/routes/ai.js

@@ -126,7 +126,7 @@ router.post('/translate', asyncHandler(async (req, res) => {
   if (!summary && !usageGuide) {
     return res.json({
       success: true,
-      data: { summary_en: '', usageGuide_en: '' },
+      data: { summaryEn: '', usageGuideEn: '' },
     });
   }
 
@@ -139,7 +139,7 @@ router.post('/translate', asyncHandler(async (req, res) => {
       logger.warn('AI translate tool returned error', { error: result.error });
       return res.json({
         success: true,
-        data: { summary_en: summary || '', usageGuide_en: usageGuide || '' },
+        data: { summaryEn: summary || '', usageGuideEn: usageGuide || '' },
         warning: result.error,
       });
     }
@@ -149,7 +149,7 @@ router.post('/translate', asyncHandler(async (req, res) => {
     logger.warn('AI translate failed, returning original text', { error: err.message });
     res.json({
       success: true,
-      data: { summary_en: summary || '', usageGuide_en: usageGuide || '' },
+      data: { summaryEn: summary || '', usageGuideEn: usageGuide || '' },
       warning: `Translation failed: ${err.message}`,
     });
   }
@@ -175,6 +175,7 @@ router.post('/chat', asyncHandler(async (req, res) => {
       reply: result.reply,
       hasContext: result.hasContext,
       toolCalls: result.toolCalls,
+      reasoningQuality: result.reasoningQuality || null,
     },
   });
 }));