autosnippet 2.12.0 → 2.14.0

package/README.md

@@ -31,13 +31,15 @@ AI 编码助手生成的代码往往脱离项目上下文——不知道团队
 
 | 概念 | 说明 |
 |------|------|
-| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，存储在 SQLite 中，可导出为 Markdown 到 `AutoSnippet/recipes/` |
+| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，以 Markdown 文件（`AutoSnippet/recipes/*.md`）为 Source of Truth，SQLite 作为检索缓存 |
 | **Candidate** | 待审核的候选知识——来自 AI 扫描、手动提交、剪贴板或 Bootstrap 冷启动，经 Dashboard 人工审核后晋升为 Recipe |
-| **Dashboard** | Web 管理后台（`asd ui`），10 个功能视图：Recipes / Candidates / AI Chat / SPM Explorer / 知识图谱 / 依赖图 / Guard / Skills / Xcode 模拟器 / Help |
+| **Dashboard** | Web 管理后台（`asd ui`），10+ 功能视图：Recipes / Candidates / Knowledge / AI Chat / SPM Explorer / 知识图谱 / 依赖图 / Guard / Skills / Xcode 模拟器 / Help |
 | **Guard** | 代码审查引擎——基于知识库中的规则对代码做合规检查，支持文件 / Target / 项目三级范围 |
 | **Skills** | 13 个 Cursor Agent 技能包——覆盖候选生成、冷启动、Guard 审计、意图路由、生命周期管理等场景 |
-| **Bootstrap** | 冷启动引擎——自动扫描 SPM Target + AST 分析，9 维度启发式提取代码模式，AI 精炼后生成 Candidate |
-| **ChatAgent** | 多 Agent 协作对话系统（Analyst + Producer），支持项目感知、信心信号、组合工具链和跨对话轻量记忆 |
+| **Bootstrap** | 冷启动引擎——自动扫描 SPM Target + AST 分析，9 维度启发式提取代码模式，AI 精炼后生成 Candidate；支持增量模式（IncrementalBootstrap），文件变更检测 + 受影响维度重跑 |
+| **Agent Memory** | 四层记忆架构——WorkingMemory（会话级）→ EpisodicMemory（跨维度共享）→ ProjectSemanticMemory（项目级永久语义记忆）→ ToolResultCache（工具结果去重），支撑 Bootstrap 和 ChatAgent 的跨对话知识积累 |
+| **ChatAgent** | 多 Agent 协作对话系统（Analyst + Producer），支持项目感知、信心信号、组合工具链和跨对话记忆 |
+| **CodeEntityGraph** | 代码实体关系图谱——基于 AST 解析构建 class / protocol / category / module 间的继承、遵循、依赖、数据流等关系，供 Bootstrap 和搜索使用 |
 
 ## 快速开始
 
@@ -63,36 +65,102 @@ asd status         # 自检项目根、AI Provider、索引、Dashboard
 
 ## 工作流
 
-### 知识沉淀闭环
+### 端到端使用流程
+
+从零开始到知识库持续运转的完整路径——以 Cursor 为例：
+
+```
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│ ① 初始化     │──→│ ② 冷启动    │──→│ ③ 逐Target  │──→│ ④ 审核发布   │──→│ ⑤ 注入 IDE  │
+│  asd setup  │   │  Bootstrap  │   │    扫描      │   │  Dashboard  │   │   Cursor    │
+└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘   └──────┬──────┘
+                                                                               │
+       ┌───────────────────────────────────────────────────────────────────────┘
+       ↓
+┌─────────────┐   ┌─────────────┐
+│ ⑥ AI 按      │──→│ ⑦ 新模式    │──→ 回到 ③
+│  规范生成     │   │   再沉淀     │
+└─────────────┘   └─────────────┘
+```
+
+**① 初始化项目**
+
+```bash
+cd /path/to/your-project
+asd setup                # 创建 AutoSnippet/ 目录、数据库、配置文件
+asd install:full         # 安装 Cursor Skills (13个) + MCP 配置 + Cursor Rules
+asd ui                   # 启动 Dashboard + API 服务 + 文件监听
+```
+
+完成后，你的项目目录下会生成 `.cursor/mcp.json`、`.cursor/skills/`、`.cursor/rules/` 等集成文件，Cursor 已经可以通过 MCP 与 AutoSnippet 通信。
+
+**② 冷启动——全局扫描建立基线**
+
+在 Cursor 中用自然语言触发冷启动：
+
+```
+你：「对项目做一次全量冷启动，提取所有代码模式」
+```
+
+Bootstrap 引擎自动完成：SPM Target 发现 → 文件收集 → AST 结构分析 → 9 维度启发式扫描（架构 / 命名 / 网络 / 数据流 / 错误处理等） → Analyst Agent 深度分析 → Producer Agent 格式化提交。
+
+冷启动结束后，Dashboard Candidates 页面会出现数十条候选知识条目。
+
+**③ 逐 Target 精细扫描**
+
+冷启动覆盖全局，但每个 Target 的独特模式需要针对性提取：
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                                                             │
-│   ① 扫描提取                        ② 人工审核             │
-│   Cursor AI 扫描 Target ──→ Candidates ──→ Recipe 入库     │
-│   asd ais <Target>                Dashboard                 │
-│   Bootstrap 冷启动 / 剪贴板                                 │
-│                                                             │
-│   ③ AI 按规范生成                    ④ 持续沉淀             │
-│   Cursor/Copilot 检索 Recipe ──→ 生成代码 ──→ 好代码再入库  │
-│   MCP 工具 / Xcode Snippet                                  │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
+你：「扫描 NetworkModule 这个 Target，把里面的请求封装模式提取出来」
+你：「分析 UIComponents Target 的自定义控件实现」
 ```
 
-### 三种使用方式
+Cursor 调用 `get_targets` → `get_target_files` → 逐文件 AI 分析 → `submit_knowledge_batch`，将发现的代码模式作为 Candidate 提交到知识库。你可以逐个 Target 推进，每个 Target 的扫描结果会独立进入审核队列。
+
+**④ 审核发布——人工把关质量**
+
+打开 Dashboard（`asd ui`），进入 **Candidates** 页面：
+
+- 候选按置信度排序，高信心的排在前面
+- 点击候选卡片展开详情：查看代码片段、AI 分析理由、来源文件
+- **接受** → 候选晋升为 Recipe，进入活跃知识库
+- **编辑后接受** → 审核时可修改标题、描述、代码、标签
+- **拒绝** → 低质量或重复的候选直接归档
+
+批量操作：一键接受所有高信心候选，或一键拒绝低质量条目。
+
+**⑤ 注入 Cursor——知识即规则**
 
-**① Cursor AI（推荐）**：自然语言驱动，Cursor 通过 13 个 Skills + 38 个 MCP 工具与知识库交互。
+Recipe 发布后，Cursor 立即可以通过三种通道获取知识：
+
+| 通道 | 机制 | 时效 |
+|------|------|------|
+| **MCP 工具检索** | Cursor 通过 `autosnippet_search` 等 38 个工具实时查询知识库 | 实时 |
+| **Cursor Rules** | `asd upgrade` 将 Recipe 导出为 `.cursor/rules/autosnippet-*.mdc` 文件 | 手动触发 |
+| **Agent Skills** | 13 个 Skill 文档引导 Cursor 在正确场景自动调用知识库 | 常驻 |
+
+**⑥ AI 按规范生成代码**
+
+当你在 Cursor 中编写代码时，AI 会自动检索知识库：
 
 ```
-用户：「扫描 NetworkModule 这个 Target，提取最佳实践」
-Cursor → get_targets → get_target_files → 逐文件提取 → submit_knowledge_batch
-→ Dashboard Candidates 页面审核 → 保存为 Recipe
+你：「写一个网络请求方法，获取用户信息」
+Cursor → 检索知识库 → 命中 Recipe: "Network Layer Pattern"
+     → 按团队封装的 NetworkManager 生成代码，而非裸调 URLSession
 ```
 
-**② Dashboard Web UI**：可视化管理一切——Recipe 编辑、Candidate 审核、AI Chat 对话、知识图谱、SPM 探索、Guard 审查、冷启动向导。
+Guard 规则也在同步工作——如果生成的代码违反了知识库中的规则（如 `kind=rule` 的条目），会实时提醒和纠正。
+
+**⑦ 持续沉淀——知识库越用越好**
 
-**③ 命令行 CLI**：`asd` 命令覆盖全部操作，适合自动化和脚本集成。
+日常开发中发现新的代码模式或团队约定？随时沉淀：
+
+- 在 Cursor 中：`「把这段 error handling 模式提取为知识库条目」`
+- 在 Xcode 中：代码注释写 `// as:create` 然后 `⌘S`
+- 在 Dashboard 中：AI Chat 对话式提交
+- 通过剪贴板：复制代码后自动检测并建议入库
+
+知识库形成飞轮：**代码沉淀 → Recipe 增长 → AI 生成质量提升 → 团队效率提高 → 更多代码模式沉淀**。
 
 ## Dashboard
 
@@ -100,13 +168,14 @@ Cursor → get_targets → get_target_files → 逐文件提取 → submit_knowl
 
 ![Dashboard](./resources/ASImage02.png)
 
-**10 个功能视图**：
+**功能视图**：
 
 | 视图 | 说明 |
 |------|------|
 | **Recipes** | 浏览、编辑、发布、弃用知识条目；详情抽屉支持 Markdown 编辑与关联关系管理 |
 | **Candidates** | 审核 AI / 手动提交的候选，一键入库或批量操作，支持 AI 润色 |
-| **AI Chat** | ChatAgent 智能对话（Analyst 分析 + Producer 生产），项目感知 + 跨对话记忆 |
+| **Knowledge** | 统一知识条目浏览（V3 格式），双列卡片布局，代码预览 + 详情抽屉 |
+| **AI Chat** | ChatAgent 智能对话（Analyst 分析 + Producer 生产），项目感知 + 四层记忆架构 |
 | **SPM Explorer** | SPM Target 浏览与扫描，候选 vs Recipe 对比抽屉，头文件编辑 |
 | **Dep Graph** | 依赖关系图可视化 |
 | **Knowledge Graph** | Recipe 关联关系的知识图谱可视化（依赖 / 扩展 / 冲突等），AI 自动发现关系，按 category 分组 |
@@ -123,9 +192,9 @@ Cursor → get_targets → get_target_files → 逐文件提取 → submit_knowl
 
 AutoSnippet 为 Cursor 提供完整的 MCP + Skills 集成：
 
-- **38 个 MCP 工具**：搜索（4 种模式）、Guard 检查、候选提交 / 校验 / 查重、知识图谱查询、Bootstrap 冷启动、Skills 管理等
+- **38 个 MCP 工具**：搜索（4 种模式）、Guard 检查、候选提交 / 校验 / 查重、知识图谱查询、Bootstrap 冷启动、Skills 管理、知识生命周期等
 - **13 个 Agent Skills**：`autosnippet-candidates`、`autosnippet-guard`、`autosnippet-coldstart`、`autosnippet-intent` 等，引导 AI 正确使用工具
-- **写操作 Gateway 保护**：9 个写操作经过权限 / 宪法 / 审计三重检查
+- **写操作 Gateway 保护**：11 个写操作经过权限 / 宪法 / 审计三重检查
 
 ```bash
 asd install:cursor-skill --mcp  # 安装 Skills + MCP 配置
@@ -171,20 +240,21 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 
 ## MCP 工具一览
 
-38 个 MCP 工具按功能分组（省略了 **autosnippet_** 前缀）：
+39 个 MCP 工具按功能分组（省略了 **autosnippet_** 前缀）：
 
 | 分类 | 工具 |
 |------|------|
 | **系统** | `health`、`capabilities` |
 | **搜索** | `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`、`submit_knowledge_batch`、`enrich_candidates` |
+| **候选管理** | `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` |
 | **冷启动** | `bootstrap_knowledge`、`bootstrap_refine` |
 | **Skills** | `list_skills`、`load_skill`、`create_skill`、`delete_skill`、`update_skill`、`suggest_skills` |
-| **治理** | `compliance_report` |
+| **知识管理** | `knowledge_lifecycle`、`compliance_report` |
 
 ## 配置
 
@@ -237,18 +307,23 @@ your-project/
 │  AutoSnippet Core                                         │
 │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
 │  │ Gateway  │ │ ChatAgent│ │ Bootstrap│ │  Dashboard  │  │
-│  │ (权限/   │ │ (Dual    │ │ (SPM +   │ │  (React 19 +│  │
-│  │  宪法/   │ │  Agent + │ │  AST +   │ │   Vite 6 +  │  │
-│  │  审计)   │ │  Memory) │ │  AI)     │ │   Tailwind) │  │
+│  │ (权限/   │ │ (Dual    │ │ (Incremen│ │  (React 19 +│  │
+│  │  宪法/   │ │  Agent + │ │  tal +   │ │   Vite 6 +  │  │
+│  │  审计)   │ │  Memory) │ │  AST+AI) │ │   Tailwind) │  │
 │  └──────────┘ └──────────┘ └──────────┘ └─────────────┘  │
 │  ┌────────────────────────────────────────────────────┐   │
-│  │  13 Services: Recipe │ Candidate │ Guard │ Search  │   │
+│  │  Agent Memory (4-Tier):                            │   │
+│  │  WorkingMemory → EpisodicMemory →                  │   │
+│  │  ProjectSemanticMemory → ToolResultCache           │   │
+│  └────────────────────────────────────────────────────┘   │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │  14 Services: Recipe │ Candidate │ Guard │ Search  │   │
 │  │  Knowledge Graph │ SPM │ Bootstrap │ Chat │ Skills  │   │
-│  │  Quality │ Context │ Automation │ Snippet           │   │
+│  │  Quality │ Context │ Automation │ Snippet │ Cursor  │   │
 │  └────────────────────────────────────────────────────┘   │
 │  ┌────────────────────────────────────────────────────┐   │
 │  │  Core: Gateway │ Constitution │ Permission │ AST   │   │
-│  │  Session │ Capability                              │   │
+│  │  Session │ Capability │ CodeEntityGraph             │   │
 │  └────────────────────────────────────────────────────┘   │
 │  ┌────────────────────────────────────────────────────┐   │
 │  │  Storage: SQLite (better-sqlite3) + 向量索引       │   │
@@ -267,7 +342,7 @@ your-project/
 | **前端** | React 19 + TypeScript 5 + Vite 6 + Tailwind CSS 4 |
 | **AI** | Gemini / OpenAI / Claude（通过 AiProvider 抽象层） |
 | **AST** | Tree-sitter（Swift / ObjC） |
-| **搜索** | 4 层检索管线：InvertedIndex → CoarseRanker → MultiSignalRanker → RetrievalFunnel |
+| **搜索** | 5 层检索管线：InvertedIndex → Semantic Rerank → CoarseRanker (E-E-A-T) → MultiSignalRanker → RetrievalFunnel |
 | **实时通信** | WebSocket（Socket.IO），Dashboard 实时更新 |
 | **动画** | Framer Motion |
 | **代码高亮** | Prism.js + react-syntax-highlighter |

package/bin/cli.js

@@ -221,6 +221,150 @@ program
     }
   });
 
+// ─────────────────────────────────────────────────────
+// guard:ci 命令
+// ─────────────────────────────────────────────────────
+program
+  .command('guard:ci [path]')
+  .description('CI/CD 模式运行全项目 Guard 检查')
+  .option('--fail-on-error', '有 error 级违规时 exit 1', true)
+  .option('--fail-on-warning', '超过 warning 阈值时 exit 2')
+  .option('--max-warnings <n>', 'warning 阈值', '20')
+  .option('--report <format>', '报告格式: json | text | markdown', 'text')
+  .option('--output <file>', '报告输出文件')
+  .option('--min-score <n>', 'Quality Gate 最低分', '70')
+  .option('--max-files <n>', '最大扫描文件数', '500')
+  .action(async (scanPath, opts) => {
+    try {
+      const projectRoot = resolve(scanPath || '.');
+      const { bootstrap, container } = await initContainer({ projectRoot });
+      const reporter = container.get('complianceReporter');
+
+      const report = await reporter.generate(projectRoot, {
+        qualityGate: {
+          maxErrors: 0,
+          maxWarnings: parseInt(opts.maxWarnings, 10),
+          minScore: parseInt(opts.minScore, 10),
+        },
+        maxFiles: parseInt(opts.maxFiles, 10),
+      });
+
+      // 输出报告
+      if (opts.report === 'json') {
+        const output = JSON.stringify(report, null, 2);
+        if (opts.output) {
+          const { writeFileSync } = await import('fs');
+          writeFileSync(opts.output, output, 'utf8');
+          console.log(`Report written to ${opts.output}`);
+        } else {
+          console.log(output);
+        }
+      } else {
+        reporter.printReport(report, { format: opts.report });
+      }
+
+      // 如果也要写文件（非 JSON 格式）
+      if (opts.output && opts.report !== 'json') {
+        const { writeFileSync } = await import('fs');
+        writeFileSync(opts.output, JSON.stringify(report, null, 2), 'utf8');
+        console.log(`Report data written to ${opts.output}`);
+      }
+
+      await bootstrap.shutdown();
+
+      // Exit code
+      if (report.qualityGate.status === 'FAIL') {
+        process.exit(report.summary.errors > 0 ? 1 : 2);
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      if (process.env.ASD_DEBUG === '1') console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+// ─────────────────────────────────────────────────────
+// guard:staged 命令
+// ─────────────────────────────────────────────────────
+program
+  .command('guard:staged')
+  .description('检查 git staged 文件')
+  .option('--fail-on-error', '有 error 时 exit 1', true)
+  .option('--json', '以 JSON 格式输出')
+  .action(async (opts) => {
+    try {
+      const { execSync } = await import('child_process');
+
+      // 获取 staged 文件列表
+      let stagedFiles;
+      try {
+        stagedFiles = execSync('git diff --cached --name-only --diff-filter=ACM', { encoding: 'utf8' })
+          .trim().split('\n').filter(Boolean);
+      } catch (err) {
+        console.error('❌ 无法获取 git staged 文件（是否在 git 仓库中？）');
+        process.exit(1);
+      }
+
+      if (stagedFiles.length === 0) {
+        console.log('✅ No staged files');
+        process.exit(0);
+      }
+
+      // 过滤源文件
+      const { SOURCE_EXTS } = await import('../lib/service/guard/SourceFileCollector.js');
+      const { extname: _extname } = await import('path');
+      const sourceFiles = stagedFiles.filter(f => SOURCE_EXTS.has(_extname(f).toLowerCase()));
+
+      if (sourceFiles.length === 0) {
+        console.log('✅ No source files in staged changes');
+        process.exit(0);
+      }
+
+      const { bootstrap, container } = await initContainer();
+      const engine = container.get('guardCheckEngine');
+      const { detectLanguage } = await import('../lib/service/guard/GuardCheckEngine.js');
+
+      // 读取文件内容并检查
+      const files = [];
+      for (const f of sourceFiles) {
+        const filePath = resolve(f);
+        if (existsSync(filePath)) {
+          files.push({ path: filePath, content: readFileSync(filePath, 'utf8') });
+        }
+      }
+
+      const result = engine.auditFiles(files, { scope: 'file' });
+      const { summary } = result;
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (summary.totalViolations === 0) {
+        console.log(`✅ ${summary.filesChecked} staged files passed Guard check`);
+      } else {
+        console.log(`\n🛡️  Guard check on ${summary.filesChecked} staged files:`);
+        console.log(`   ${summary.totalErrors} errors, ${summary.totalViolations - summary.totalErrors} warnings\n`);
+
+        const filesWithIssues = result.files.filter(f => f.summary.total > 0);
+        for (const file of filesWithIssues.slice(0, 10)) {
+          console.log(`  📄 ${basename(file.filePath)}  (${file.summary.errors}E / ${file.summary.warnings}W)`);
+          for (const v of file.violations.slice(0, 5)) {
+            const icon = v.severity === 'error' ? '❌' : '⚠️';
+            console.log(`     ${icon} L${v.line} [${v.ruleId}] ${v.message}`);
+          }
+          if (file.violations.length > 5) console.log(`     ... ${file.violations.length - 5} more`);
+        }
+      }
+
+      await bootstrap.shutdown();
+      process.exit(summary.totalErrors > 0 ? 1 : 0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      if (process.env.ASD_DEBUG === '1') console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
 // ─────────────────────────────────────────────────────
 // watch 命令
 // ─────────────────────────────────────────────────────
@@ -514,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/config/default.json

@@ -47,5 +47,10 @@
     "enabled": true,
     "dimensions": 1536,
     "indexPath": "./data/vector-index"
+  },
+  "qualityGate": {
+    "maxErrors": 0,
+    "maxWarnings": 20,
+    "minScore": 70
   }
 }

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/core/AstAnalyzer.js

@@ -981,6 +981,181 @@ function _findIdentifier(node) {
   return null;
 }
 
+// ──────────────────────────────────────────────────────────────────
+// Guard AST 查询 API — 供 GuardCheckEngine AST 规则使用
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 在 AST 中搜索特定调用表达式
+ * @param {string} source  源代码
+ * @param {string} lang    'objectivec' | 'swift'
+ * @param {string} targetCallee  目标调用，如 'URLSession.shared', 'dispatch_sync'
+ * @returns {Array<{ line: number, snippet: string, enclosingClass: string|null }>}
+ */
+function findCallExpressions(source, lang, targetCallee) {
+  const parser = _getParser(lang);
+  if (!parser) return [];
+
+  const tree = parser.parse(source);
+  const results = [];
+  const lines = source.split(/\r?\n/);
+
+  function walk(node, enclosingClass) {
+    // 更新当前所处的类
+    let currentClass = enclosingClass;
+    if (['class_declaration', 'struct_declaration', 'class_interface', 'class_implementation'].includes(node.type)) {
+      currentClass = _findIdentifier(node) || enclosingClass;
+    }
+
+    // 检查调用表达式
+    const isCallLike = ['call_expression', 'message_expression', 'function_call_expression'].includes(node.type);
+    if (isCallLike) {
+      const nodeText = node.text || '';
+      if (nodeText.includes(targetCallee)) {
+        results.push({
+          line: node.startPosition.row + 1,
+          snippet: lines[node.startPosition.row]?.trim().slice(0, 120) || '',
+          enclosingClass: currentClass,
+        });
+      }
+    }
+
+    // 对 Swift，也检查 member_access + call 的组合，如 URLSession.shared.data(...)
+    if (node.type === 'navigation_expression' || node.type === 'member_expression') {
+      const nodeText = node.text || '';
+      if (nodeText.includes(targetCallee)) {
+        // 只有当父节点是 call 时才算
+        const parent = node.parent;
+        if (parent && ['call_expression', 'function_call_expression'].includes(parent.type)) {
+          // 已在 call_expression 中处理，跳过避免重复
+        } else {
+          results.push({
+            line: node.startPosition.row + 1,
+            snippet: lines[node.startPosition.row]?.trim().slice(0, 120) || '',
+            enclosingClass: currentClass,
+          });
+        }
+      }
+    }
+
+    for (let i = 0; i < node.childCount; i++) {
+      walk(node.child(i), currentClass);
+    }
+  }
+
+  walk(tree.rootNode, null);
+  return results;
+}
+
+/**
+ * 搜索特定模式在特定上下文中的出现
+ * @param {string} source  源代码
+ * @param {string} lang    'objectivec' | 'swift'
+ * @param {string} pattern  要查找的文本模式（普通字符串匹配）
+ * @param {{ forbiddenContext?: string, requiredContext?: string }} contextFilter
+ *   forbiddenContext: 如果在此上下文中出现则报告 (如 'dealloc')
+ *   requiredContext: 如果不在此上下文中出现则报告
+ * @returns {Array<{ line: number, snippet: string, context: string|null }>}
+ */
+function findPatternInContext(source, lang, pattern, contextFilter = {}) {
+  const parser = _getParser(lang);
+  if (!parser) return [];
+
+  const tree = parser.parse(source);
+  const results = [];
+  const lines = source.split(/\r?\n/);
+
+  function getEnclosingMethodName(node) {
+    let current = node.parent;
+    while (current) {
+      if (['method_definition', 'method_declaration', 'function_declaration', 'function_definition'].includes(current.type)) {
+        return _findIdentifier(current) || null;
+      }
+      current = current.parent;
+    }
+    return null;
+  }
+
+  function getEnclosingClassName(node) {
+    let current = node.parent;
+    while (current) {
+      if (['class_declaration', 'struct_declaration', 'class_interface', 'class_implementation'].includes(current.type)) {
+        return _findIdentifier(current) || null;
+      }
+      current = current.parent;
+    }
+    return null;
+  }
+
+  function walk(node) {
+    const nodeText = node.text || '';
+    if (nodeText.includes(pattern) && node.childCount === 0) {
+      // 叶节点匹配
+      const methodName = getEnclosingMethodName(node);
+      const className = getEnclosingClassName(node);
+
+      if (contextFilter.forbiddenContext) {
+        // 在禁止上下文中出现 → 报告
+        if (methodName === contextFilter.forbiddenContext || className === contextFilter.forbiddenContext) {
+          results.push({
+            line: node.startPosition.row + 1,
+            snippet: lines[node.startPosition.row]?.trim().slice(0, 120) || '',
+            context: methodName || className,
+          });
+        }
+      } else if (contextFilter.requiredContext) {
+        // 不在要求的上下文中 → 报告
+        if (className !== contextFilter.requiredContext && methodName !== contextFilter.requiredContext) {
+          results.push({
+            line: node.startPosition.row + 1,
+            snippet: lines[node.startPosition.row]?.trim().slice(0, 120) || '',
+            context: className || methodName,
+          });
+        }
+      }
+    }
+
+    for (let i = 0; i < node.childCount; i++) {
+      walk(node.child(i));
+    }
+  }
+
+  walk(tree.rootNode);
+  return results;
+}
+
+/**
+ * 检查类是否遵循指定协议
+ * @param {string} source  源代码
+ * @param {string} lang    'objectivec' | 'swift'
+ * @param {string} className  类名
+ * @param {string} protocolName  协议名
+ * @returns {{ conforms: boolean, classFound: boolean, classDeclLine: number|null }}
+ */
+function checkProtocolConformance(source, lang, className, protocolName) {
+  const summary = analyzeFile(source, lang);
+  if (!summary) return { conforms: false, classFound: false, classDeclLine: null };
+
+  // 在 classes 中查找
+  const cls = summary.classes.find(c => c.name === className);
+  if (!cls) return { conforms: false, classFound: false, classDeclLine: null };
+
+  // 直接遵循
+  if (cls.protocols?.includes(protocolName)) {
+    return { conforms: true, classFound: true, classDeclLine: cls.line };
+  }
+
+  // 通过 extension/category 遵循
+  const catConforms = summary.categories.some(
+    cat => cat.className === className && cat.protocols?.includes(protocolName)
+  );
+  if (catConforms) {
+    return { conforms: true, classFound: true, classDeclLine: cls.line };
+  }
+
+  return { conforms: false, classFound: true, classDeclLine: cls.line };
+}
+
 // ──────────────────────────────────────────────────────────────────
 // 导出
 // ──────────────────────────────────────────────────────────────────
@@ -991,4 +1166,8 @@ export {
   generateContextForAgent,
   isAvailable,
   supportedLanguages,
+  // Guard AST 查询 API
+  findCallExpressions,
+  findPatternInContext,
+  checkProtocolConformance,
 };

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

@@ -163,6 +163,7 @@ export class McpServer {
       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}`);
     }
   }

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/guard.js

@@ -65,7 +65,7 @@ export async function guardAuditFiles(ctx, args) {
 
   const result = engine.auditFiles(filesToAudit, { scope });
 
-  // 写入 ViolationsStore
+  // 写入 ViolationsStore + GuardFeedbackLoop
   try {
     const violationsStore = ctx.container.get('violationsStore');
     for (const fileResult of (result.files || [])) {
@@ -76,6 +76,12 @@ export async function guardAuditFiles(ctx, args) {
           summary: `MCP audit (${scope}): ${fileResult.summary.errors}E ${fileResult.summary.warnings}W`,
         });
       }
+
+      // Guard ↔ Recipe 闭环：检测修复并自动确认使用
+      try {
+        const feedbackLoop = ctx.container.get('guardFeedbackLoop');
+        feedbackLoop.processFixDetection(fileResult, fileResult.filePath);
+      } catch { /* guardFeedbackLoop not available */ }
     }
   } catch { /* ViolationsStore not available */ }