autosnippet 2.11.0 → 2.13.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 配置
@@ -178,13 +247,13 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 | **系统** | `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` |
 | **知识图谱** | `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 +306,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 +341,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 命令
 // ─────────────────────────────────────────────────────

package/config/default.json

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