autosnippet 2.8.3 → 2.10.0

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',
@@ -574,7 +453,7 @@ 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。',
@@ -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,112 @@ export const TOOLS = [
       required: [],
     },
   },
+  // ═══ V3 知识条目（统一实体） ═══════════════════════════════
+  // 36. 单条知识提交（V3 wire format 直通）
+  {
+    name: 'autosnippet_submit_knowledge',
+    description:
+      '提交单条知识条目到 AutoSnippet 知识库（V3 统一实体）。\n' +
+      '参数即 wire format — 直接构造 KnowledgeEntry，无需字段映射。\n' +
+      '根据 ConfidenceRouter 自动路由：高置信度自动入库(active)，低置信度待审核(pending)，极低置信度自动驳回(rejected)。\n' +
+      '⚠️ content 对象必须有 pattern 或 markdown。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        // ── 必填 ──
+        title:            { type: 'string', description: '中文标题（≤20字）' },
+        language:         { type: 'string', description: '编程语言（swift/objectivec，小写）' },
+        content: {
+          type: 'object',
+          description: '内容值对象（必须有 pattern 或 markdown）',
+          properties: {
+            pattern:      { type: 'string', description: '代码片段（等同旧 code 字段）' },
+            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' },
+            }}},
+            code_changes: { type: 'array', items: { type: 'object' } },
+            verification: { type: 'object' },
+          },
+        },
+        // ── 分类 ──
+        category:         { type: 'string', description: '分类: View/Service/Tool/Model/Network/Storage/UI/Utility' },
+        knowledge_type:   { 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' } },
+        // ── 描述双语 ──
+        trigger:          { type: 'string', description: '触发关键词（@开头，小写）' },
+        description:      { type: 'string' },
+        summary_cn:       { type: 'string', description: '中文摘要' },
+        summary_en:       { type: 'string', description: '英文摘要' },
+        usage_guide_cn:   { type: 'string', description: '中文使用指南（Markdown）' },
+        usage_guide_en:   { type: 'string', description: '英文使用指南（Markdown）' },
+        // ── 约束与关系 ──
+        constraints:      { type: 'object', description: '约束 {guards[], boundaries[], preconditions[], side_effects[]}' },
+        relations:        { type: 'object', description: '关系分桶 {inherits[], extends[], depends_on[], conflicts[], related[], ...}' },
+        // ── 推理 ──
+        reasoning: {
+          type: 'object',
+          description: '推理依据（必须提供）',
+          properties: {
+            why_standard: { type: 'string', description: '为什么值得沉淀为知识' },
+            sources:      { type: 'array', items: { type: 'string' }, description: '来源列表' },
+            confidence:   { type: 'number', description: '置信度 0-1' },
+            quality_signals: { type: 'object' },
+            alternatives: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['why_standard', 'sources'],
+        },
+        // ── 头文件 ──
+        headers:          { type: 'array', items: { type: 'string' }, description: '完整 import 语句' },
+        header_paths:     { type: 'array', items: { type: 'string' } },
+        module_name:      { type: 'string' },
+        include_headers:  { type: 'boolean' },
+        // ── 控制 ──
+        source:           { type: 'string', description: '来源标识（默认 mcp）' },
+        client_id:        { type: 'string', description: '客户端标识（用于限流）' },
+      },
+      required: ['title', 'language', 'content'],
+    },
+  },
+  // 37. 批量知识提交
+  {
+    name: 'autosnippet_submit_knowledge_batch',
+    description:
+      '批量提交知识条目到知识库（V3 统一实体）。\n' +
+      '每条 item 使用与 autosnippet_submit_knowledge 相同的 wire format。\n' +
+      '支持去重。返回逐条结果与 recipeReadyHints。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target_name:  { type: 'string', description: 'Target 名称' },
+        items:        { type: 'array', description: '知识条目数组，每项字段同 submit_knowledge', 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,9 @@ export class HttpServer {
     // 违规记录路由
     this.app.use(`${apiPrefix}/violations`, violationsRouter);
 
+    // 知识条目路由 (V3)
+    this.app.use(`${apiPrefix}/knowledge`, knowledgeRouter);
+
     // 404 处理
     this.app.use('*', (req, res) => {
       res.status(404).json({

package/lib/http/middleware/requestLogger.js

@@ -8,7 +8,7 @@
  */
 
 // 轮询/心跳路径 — 完全静默
-const SILENT_PATHS = ['/api/health', '/api/realtime/events', '/api/sse'];
+const SILENT_PATHS = ['/api/health', '/api/realtime/events', '/api/sse', '/socket.io'];
 
 export function requestLogger(logger) {
   return (req, res, next) => {
@@ -27,8 +27,8 @@ export function requestLogger(logger) {
         duration: `${duration}ms`,
       };
 
-      // 非 GET / 非 2xx / 慢请求 → info; 其余 → debug
-      const isNoisy = req.method === 'GET' && res.statusCode >= 200 && res.statusCode < 300 && duration < 2000;
+      // 非 GET / 非 2xx / 慢请求 → info; GET + 2xx/304 → debug（304 是缓存命中，与 200 同级）
+      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);

package/lib/http/routes/ai.js

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

package/lib/http/routes/extract.js

@@ -52,6 +52,7 @@ router.post('/path', asyncHandler(async (req, res) => {
       const aiResult = await chatAgent.executeTool('extract_recipes', {
         targetName: fileName,
         files: [{ name: fileName, content: file.code || '' }],
+        comprehensive: true,
       });
 
       if (aiResult && !aiResult.error && Array.isArray(aiResult.recipes) && aiResult.recipes.length > 0) {
@@ -82,6 +83,7 @@ router.post('/path', asyncHandler(async (req, res) => {
 /**
  * POST /api/v1/extract/text
  * 从文本内容提取代码片段（剪贴板等）
+ * 管线: RecipeParser(MD解析) → AI 提取(ChatAgent) → 基础兜底
  */
 router.post('/text', asyncHandler(async (req, res) => {
   const { text, language, relativePath, projectRoot: bodyRoot } = req.body;
@@ -94,21 +96,63 @@ router.post('/text', asyncHandler(async (req, res) => {
   const recipeParser = container.get('recipeParser');
   const projectRoot = bodyRoot || container.singletons?._projectRoot || process.cwd();
 
-  // 先尝试解析为 Recipe Markdown 格式
+  // 1. 先尝试解析为 Recipe Markdown 格式
   let result;
   try {
     result = await recipeParser.parseFromText(text, {
       language,
       relativePath,
     });
+    // 解析成功，直接返回
+    return res.json({
+      success: true,
+      data: {
+        result: Array.isArray(result) ? result : [result],
+        source: 'text',
+      },
+    });
   } catch (error) {
-    logger.debug('Recipe MD parse failed, falling back to AI extraction', {
+    logger.debug('Recipe MD parse failed, trying AI extraction', {
       error: error.message,
     });
-    // 回退到 AI 提取
-    result = await recipeParser.extractFromText(text, { language });
   }
 
+  // 2. Recipe MD 解析失败 → 尝试 ChatAgent AI 提取
+  try {
+    const chatAgent = container.get('chatAgent');
+    if (chatAgent) {
+      const lang = language || (relativePath && /\.swift$/i.test(relativePath) ? 'swift' : 'objc');
+      const fileName = relativePath ? basename(relativePath) : `clipboard.${lang === 'swift' ? 'swift' : 'm'}`;
+      const aiResult = await chatAgent.executeTool('extract_recipes', {
+        targetName: fileName,
+        files: [{ name: fileName, content: text }],
+        comprehensive: true,
+      });
+
+      if (aiResult && !aiResult.error && Array.isArray(aiResult.recipes) && aiResult.recipes.length > 0) {
+        logger.info('extract/text: AI extraction succeeded', { count: aiResult.recipes.length });
+
+        // 多条 Recipe 时在第一条上标记总数（供前端提示）
+        if (aiResult.recipes.length > 1) {
+          aiResult.recipes[0]._multipleCount = aiResult.recipes.length;
+        }
+
+        return res.json({
+          success: true,
+          data: {
+            result: aiResult.recipes,
+            source: 'text',
+          },
+        });
+      }
+    }
+  } catch (err) {
+    logger.debug('extract/text: AI extraction failed, using basic fallback', { error: err.message });
+  }
+
+  // 3. AI 也失败 → 基础代码块提取兜底
+  result = await recipeParser.extractFromText(text, { language });
+
   res.json({
     success: true,
     data: {