autosnippet 2.6.0 → 2.7.1

package/README.md

@@ -31,11 +31,13 @@ AI 编码助手生成的代码往往脱离项目上下文——不知道团队
 
 | 概念 | 说明 |
 |------|------|
-| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，存储在数据库中，可导出为 Markdown 到 `AutoSnippet/recipes/` |
-| **Candidate** | 待审核的候选知识——来自 AI 扫描、手动提交或剪贴板，经 Dashboard 人工审核后晋升为 Recipe |
-| **Dashboard** | Web 管理后台（`asd ui`），管理 Recipe / Candidate / Guard / 知识图谱等 |
-| **Guard** | 代码审查引擎——基于知识库中的规则对代码做合规检查 |
-| **Skills** | Cursor Agent 技能文件——告诉 AI 何时、如何使用 AutoSnippet 的能力 |
+| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，存储在 SQLite 中，可导出为 Markdown 到 `AutoSnippet/recipes/` |
+| **Candidate** | 待审核的候选知识——来自 AI 扫描、手动提交、剪贴板或 Bootstrap 冷启动，经 Dashboard 人工审核后晋升为 Recipe |
+| **Dashboard** | Web 管理后台（`asd ui`），10 个功能视图：Recipes / Candidates / AI Chat / SPM Explorer / 知识图谱 / 依赖图 / Guard / Skills / Xcode 模拟器 / Help |
+| **Guard** | 代码审查引擎——基于知识库中的规则对代码做合规检查，支持文件 / Target / 项目三级范围 |
+| **Skills** | 13 个 Cursor Agent 技能包——覆盖候选生成、冷启动、Guard 审计、意图路由、生命周期管理等场景 |
+| **Bootstrap** | 冷启动引擎——自动扫描 SPM Target + AST 分析，9 维度启发式提取代码模式，AI 精炼后生成 Candidate |
+| **ChatAgent** | Dual-Agent 对话系统（Analyst + Producer），支持项目感知、信心信号、组合工具链和跨对话轻量记忆 |
 
 ## 快速开始
 
@@ -52,6 +54,9 @@ asd install:full
 
 # 4. 启动 Dashboard
 asd ui             # 启动 Web 后台 + 文件监听 + 语义索引
+
+# 5. 检查环境状态
+asd status         # 自检项目根、AI Provider、索引、Dashboard
 ```
 
 > **注意**：始终在**你的项目目录**中执行 `asd` 命令，而非 AutoSnippet 源码仓库。
@@ -66,7 +71,7 @@ asd ui             # 启动 Web 后台 + 文件监听 + 语义索引
 │   ① 扫描提取                        ② 人工审核             │
 │   Cursor AI 扫描 Target ──→ Candidates ──→ Recipe 入库     │
 │   asd ais <Target>                Dashboard                 │
-│   剪贴板 / 手动提交                                         │
+│   Bootstrap 冷启动 / 剪贴板                                 │
 │                                                             │
 │   ③ AI 按规范生成                    ④ 持续沉淀             │
 │   Cursor/Copilot 检索 Recipe ──→ 生成代码 ──→ 好代码再入库  │
@@ -77,7 +82,7 @@ asd ui             # 启动 Web 后台 + 文件监听 + 语义索引
 
 ### 三种使用方式
 
-**① Cursor AI（推荐）**：自然语言驱动，Cursor 通过 13 个 Skills + 34 个 MCP 工具与知识库交互。
+**① Cursor AI（推荐）**：自然语言驱动，Cursor 通过 13 个 Skills + 36 个 MCP 工具与知识库交互。
 
 ```
 用户：「扫描 NetworkModule 这个 Target，提取最佳实践」
@@ -85,24 +90,32 @@ Cursor → autosnippet_get_targets → autosnippet_get_target_files → 逐文
 → Dashboard Candidates 页面审核 → 保存为 Recipe
 ```
 
-**② Dashboard Web UI**：可视化管理一切——Recipe 编辑器、Candidate 审核、知识图谱、Guard 审查、冷启动向导。
+**② Dashboard Web UI**：可视化管理一切——Recipe 编辑、Candidate 审核、AI Chat 对话、知识图谱、SPM 探索、Guard 审查、冷启动向导。
 
 **③ 命令行 CLI**：`asd` 命令覆盖全部操作，适合自动化和脚本集成。
 
 ## Dashboard
 
-`asd ui` 启动后访问 Web 管理后台：
+`asd ui` 启动后访问 Web 管理后台（默认 http://127.0.0.1:3000）：
 
 ![Dashboard](./resources/ASImage01.png)
 
-**主要功能**：
+**10 个功能视图**：
 
-- **Recipes**：浏览、编辑、发布、弃用知识条目；支持代码高亮编辑器
-- **Candidates**：审核 AI/手动提交的候选，一键入库或批量操作
-- **知识图谱**：可视化 Recipe 之间的关系（依赖 / 扩展 / 冲突等），AI 自动发现关系，按 category 分组布局
-- **Guard**：代码合规审查，查看违规记录与修复建议
-- **Xcode 模拟器**：在浏览器中模拟 `as:search` / `as:create` / `as:audit` 指令
-- **冷启动**：Bootstrap 向导——选择 SPM Target 逐个扫描，AI 提取代码模式生成 Candidate
+| 视图 | 说明 |
+|------|------|
+| **Recipes** | 浏览、编辑、发布、弃用知识条目；详情抽屉支持 Markdown 编辑与关联关系管理 |
+| **Candidates** | 审核 AI / 手动提交的候选，一键入库或批量操作，支持 AI 润色 |
+| **AI Chat** | Dual-Agent 智能对话（Analyst 分析 + Producer 生产），项目感知 + 跨对话记忆 |
+| **SPM Explorer** | SPM Target 浏览与扫描，候选 vs Recipe 对比抽屉，头文件编辑 |
+| **Dep Graph** | 依赖关系图可视化 |
+| **Knowledge Graph** | Recipe 关联关系的知识图谱可视化（依赖 / 扩展 / 冲突等），AI 自动发现关系，按 category 分组 |
+| **Guard** | 代码合规审查，查看违规记录与修复建议 |
+| **Skills** | 浏览与管理 Agent Skill 文档 |
+| **Xcode Simulator** | 在浏览器中模拟 `as:search` / `as:create` / `as:audit` 指令 |
+| **Help** | 使用帮助与快捷键参考 |
+
+**辅助功能**：全局搜索面板、LLM 配置弹窗、Bootstrap 进度视图、实时 WebSocket 更新。
 
 ## IDE 集成
 
@@ -110,9 +123,9 @@ Cursor → autosnippet_get_targets → autosnippet_get_target_files → 逐文
 
 AutoSnippet 为 Cursor 提供完整的 MCP + Skills 集成：
 
-- **34 个 MCP 工具**：搜索、Guard 检查、候选提交、知识图谱查询、Bootstrap 等
-- **13 个 Agent Skills**：`autosnippet-candidates`、`autosnippet-guard`、`autosnippet-coldstart` 等，引导 AI 正确使用工具
-- **写操作 Gateway 保护**：7 个写操作经过权限 / 宪法 / 审计三重检查
+- **36 个 MCP 工具**：搜索（4 种模式）、Guard 检查、候选提交 / 校验 / 查重、知识图谱查询、Bootstrap 冷启动、Skills 管理等
+- **13 个 Agent Skills**：`autosnippet-candidates`、`autosnippet-guard`、`autosnippet-coldstart`、`autosnippet-intent` 等，引导 AI 正确使用工具
+- **写操作 Gateway 保护**：9 个写操作经过权限 / 宪法 / 审计三重检查
 
 ```bash
 asd install:cursor-skill --mcp  # 安装 Skills + MCP 配置
@@ -138,20 +151,36 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 
 ## CLI 命令参考
 
-| 命令 | 说明 |
+| 命令 | 说明 | 常用选项 |
+|------|------|----------|
+| `asd setup` | 初始化项目（创建 AutoSnippet/ 目录和配置） | `--force`、`--seed` |
+| `asd ui` | 启动 Dashboard + API 服务 | `-p <port>`、`-b`（浏览器）、`--api-only` |
+| `asd status` | 环境自检（项目根、AI、索引、Dashboard 状态） | — |
+| `asd ais [target]` | AI 扫描 Target → 生成 Candidates | `-m <max-files>`、`--dry-run`、`--json` |
+| `asd search <query>` | 搜索知识库 | `-t <type>`、`-m <mode>`（keyword/bm25/semantic）、`-l <limit>` |
+| `asd guard <file>` | 对文件运行 Guard 规则检查 | `-s <scope>`（file/target/project）、`--json` |
+| `asd watch` | 启动文件监控（`as:c` / `as:s` / `as:a` 指令） | `-e <exts>`、`--guard` |
+| `asd server` | 单独启动 API 服务器 | `-p <port>`、`-H <host>` |
+| `asd sync` | 增量同步 `recipes/*.md` → DB（Markdown = Source of Truth） | `--dry-run`、`--force` |
+| `asd upgrade` | 升级 IDE 集成（MCP / Skills / Cursor Rules） | `--skills-only`、`--mcp-only` |
+| `asd install:full` | 全量安装（Skills + MCP + Native UI + Cursor Rules） | — |
+
+## MCP 工具一览
+
+36 个 MCP 工具按功能分组：
+
+| 分类 | 工具 |
 |------|------|
-| `asd setup` | 初始化项目（创建 AutoSnippet/ 目录和配置） |
-| `asd ui` | 启动 Dashboard + 文件监听 + 语义索引 |
-| `asd status` | 环境自检（项目根、AI、索引、Dashboard 状态） |
-| `asd ais [Target]` | AI 扫描 Target → 生成 Candidates |
-| `asd search <keyword>` | 搜索知识库（`--copy` 复制 / `--pick` 交互选择） |
-| `asd embed` | 手动构建语义向量索引 |
-| `asd spm-map` | 刷新 SPM 依赖映射 |
-| `asd extract` | 同步 Snippet 到 Xcode |
-| `asd sync` | 增量同步 `recipes/*.md` → DB |
-| `asd compliance` | 生成宪法合规评估报告 |
-| `asd upgrade` | 升级 IDE 集成文件 |
-| `asd install:full` | 全量安装（Skills + MCP + Native UI） |
+| **系统** | `autosnippet_health`、`autosnippet_capabilities` |
+| **搜索** | `autosnippet_search`（统合入口）、`autosnippet_context_search`（4 层漏斗）、`autosnippet_keyword_search`、`autosnippet_semantic_search` |
+| **Recipe 浏览** | `autosnippet_list_recipes`、`autosnippet_get_recipe`、`autosnippet_list_rules`、`autosnippet_list_patterns`、`autosnippet_list_facts`、`autosnippet_recipe_insights`、`autosnippet_confirm_usage` |
+| **候选管理** | `autosnippet_validate_candidate`、`autosnippet_check_duplicate`、`autosnippet_submit_candidate`、`autosnippet_submit_candidates`、`autosnippet_submit_draft_recipes`、`autosnippet_enrich_candidates` |
+| **知识图谱** | `autosnippet_graph_query`、`autosnippet_graph_impact`、`autosnippet_graph_path`、`autosnippet_graph_stats` |
+| **项目结构** | `autosnippet_get_targets`、`autosnippet_get_target_files`、`autosnippet_get_target_metadata` |
+| **Guard** | `autosnippet_guard_check`、`autosnippet_guard_audit_files`、`autosnippet_scan_project` |
+| **冷启动** | `autosnippet_bootstrap_knowledge`、`autosnippet_bootstrap_refine` |
+| **Skills** | `autosnippet_list_skills`、`autosnippet_load_skill`、`autosnippet_create_skill`、`autosnippet_suggest_skills` |
+| **治理** | `autosnippet_compliance_report` |
 
 ## 配置
 
@@ -162,22 +191,27 @@ asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
 ```env
 ASD_AI_PROVIDER=gemini          # gemini / openai / anthropic
 ASD_GOOGLE_API_KEY=your-key     # Gemini API Key
+# ASD_OPENAI_API_KEY=your-key   # OpenAI API Key
+# ASD_ANTHROPIC_API_KEY=your-key # Claude API Key
 ```
 
+支持的 AI Provider：**Gemini**（推荐）、**OpenAI**、**Claude (Anthropic)**。
+
 ### 项目目录结构
 
 ```
 your-project/
 ├── AutoSnippet/              # 知识库目录（建议整体作为 Git 子仓库）
-│   ├── recipes/              # Recipe Markdown 导出
+│   ├── recipes/              # Recipe Markdown 导出（Source of Truth）
+│   ├── skills/               # 项目级 Agent Skills
 │   └── .autosnippet/         # 数据库、索引、Guard 配置等
 ├── .cursor/
-│   ├── mcp.json          # MCP 配置（asd setup 自动生成）
-│   ├── rules/            # Cursor Rules（asd install 生成）
-│   └── skills/           # Agent Skills（asd install 生成）
+│   ├── mcp.json              # MCP 配置（asd setup 自动生成）
+│   ├── rules/                # Cursor Rules（asd install 生成）
+│   └── skills/               # Agent Skills（asd install 生成）
 ├── .vscode/
-│   └── settings.json     # VSCode MCP 配置
-└── .env                  # AI Provider 配置
+│   └── settings.json         # VSCode MCP 配置
+└── .env                      # AI Provider 配置
 ```
 
 ### Git 策略建议
@@ -190,37 +224,49 @@ your-project/
 ## 架构概览
 
 ```
-┌────────────────────────────────────────────────────────┐
-│  IDE Layer                                             │
-│  Cursor (Skills + MCP) │ VSCode (Copilot) │ Xcode     │
-└────────────┬───────────────────┬───────────────────────┘
-             │ MCP (stdio)       │ HTTP API
-┌────────────┴───────────────────┴───────────────────────┐
-│  AutoSnippet Core                                      │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
-│  │ Gateway  │ │ ChatAgent│ │ Bootstrap│ │ Dashboard │ │
-│  │ (权限/   │ │ (ReAct + │ │ (SPM +   │ │ (React +  │ │
-│  │  宪法/   │ │  DAG     │ │  AST +   │ │  Vite)    │ │
-│  │  审计)   │ │  Pipeline│ │  AI)     │ │           │ │
-│  └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
-│  ┌──────────────────────────────────────────────────┐  │
-│  │  Services: Recipe │ Candidate │ Guard │ Search   │  │
-│  │  Knowledge Graph │ SPM │ Indexing │ Compliance   │  │
-│  └──────────────────────────────────────────────────┘  │
-│  ┌──────────────────────────────────────────────────┐  │
-│  │  Storage: SQLite (better-sqlite3) + 向量索引     │  │
-│  └──────────────────────────────────────────────────┘  │
-└────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────┐
+│  IDE Layer                                               │
+│  Cursor (Skills + MCP) │ VSCode (Copilot) │ Xcode        │
+└────────────┬────────────────────┬─────────────────────────┘
+             │ MCP (stdio)        │ HTTP API
+┌────────────┴────────────────────┴─────────────────────────┐
+│  AutoSnippet Core                                         │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
+│  │ Gateway  │ │ ChatAgent│ │ Bootstrap│ │  Dashboard  │  │
+│  │ (权限/   │ │ (Dual    │ │ (SPM +   │ │  (React 19 +│  │
+│  │  宪法/   │ │  Agent + │ │  AST +   │ │   Vite 6 +  │  │
+│  │  审计)   │ │  Memory) │ │  AI)     │ │   Tailwind) │  │
+│  └──────────┘ └──────────┘ └──────────┘ └─────────────┘  │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │  13 Services: Recipe │ Candidate │ Guard │ Search  │   │
+│  │  Knowledge Graph │ SPM │ Bootstrap │ Chat │ Skills  │   │
+│  │  Quality │ Context │ Automation │ Snippet           │   │
+│  └────────────────────────────────────────────────────┘   │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │  Core: Gateway │ Constitution │ Permission │ AST   │   │
+│  │  Session │ Capability                              │   │
+│  └────────────────────────────────────────────────────┘   │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │  Storage: SQLite (better-sqlite3) + 向量索引       │   │
+│  │  Search: InvertedIndex → CoarseRanker →            │   │
+│  │          MultiSignalRanker → RetrievalFunnel       │   │
+│  └────────────────────────────────────────────────────┘   │
+└───────────────────────────────────────────────────────────┘
 ```
 
 ## 技术栈
 
-- **Runtime**：Node.js ≥ 20，ESM
-- **后端**：Express + better-sqlite3 + MCP SDK
-- **前端**：React + TypeScript + Vite + Tailwind CSS
-- **AI**：Gemini / OpenAI / Anthropic（通过 AiProvider 抽象层）
-- **AST**：Tree-sitter（Swift / ObjC / JS / TS）
-- **索引**：语义向量 + BM25 + 关键词三模式搜索
+| 层级 | 技术 |
+|------|------|
+| **Runtime** | Node.js ≥ 20，ESM |
+| **后端** | Express + better-sqlite3 + MCP SDK + Socket.IO |
+| **前端** | React 19 + TypeScript 5 + Vite 6 + Tailwind CSS 4 |
+| **AI** | Gemini / OpenAI / Claude（通过 AiProvider 抽象层） |
+| **AST** | Tree-sitter（Swift / ObjC） |
+| **搜索** | 4 层检索管线：InvertedIndex → CoarseRanker → MultiSignalRanker → RetrievalFunnel |
+| **实时通信** | WebSocket（Socket.IO），Dashboard 实时更新 |
+| **动画** | Framer Motion |
+| **代码高亮** | Prism.js + react-syntax-highlighter |
 
 ## Xcode 深度集成
 
@@ -235,6 +281,32 @@ AutoSnippet 不依赖 Xcode 插件，通过 **AppleScript + FileWatcher + 原生
 | **三层防误触** | Self-write 冷却 + 内容哈希去重 + Xcode 焦点检测，区分手动保存与自动保存 |
 | **Code Snippet** | `ass`（搜索插入）、`asc`（创建候选）、`asa`（代码审查），`asd setup` 注册后重启 Xcode 生效 |
 
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/GxFn/AutoSnippet.git
+cd AutoSnippet
+npm install
+
+# 链接开发版到全局
+npm run dev:link
+
+# 运行测试
+npm test                    # 全部测试
+npm run test:unit           # 单元测试
+npm run test:integration    # 集成测试
+npm run test:e2e            # 端到端测试
+npm run test:coverage       # 覆盖率报告
+
+# 构建 Dashboard
+npm run build:dashboard
+
+# 发布
+npm run release:check       # 发布前检查
+npm run release:patch       # 补丁版本
+```
+
 ## 贡献
 
 欢迎 [Issue](https://github.com/GxFn/AutoSnippet/issues) 与 [PR](https://github.com/GxFn/AutoSnippet/pulls)。

package/bin/api-server.js

@@ -22,6 +22,10 @@ async function main() {
       timestamp: new Date().toISOString(),
     });
 
+    // 配置路径安全守卫 — 阻止写操作逃逸到项目外
+    const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
+    Bootstrap.configurePathGuard(projectRoot);
+
     // 初始化应用程序引导
     const bootstrap = new Bootstrap({ env: process.env.NODE_ENV || 'development' });
     const components = await bootstrap.initialize();
@@ -34,6 +38,7 @@ async function main() {
       auditLogger: components.auditLogger,
       gateway: components.gateway,
       constitution: components.constitution,
+      projectRoot,
     });
     logger.info('Service container initialized successfully');
 

package/bin/cli.js

@@ -321,7 +321,7 @@ program
           projectRoot,
           database: db,
           chatAgent,
-          mode: process.env.ASD_SIGNAL_MODE || 'suggest',
+          mode: process.env.ASD_SIGNAL_MODE || 'auto',
           intervalMs: parseInt(process.env.ASD_SIGNAL_INTERVAL || '3600000', 10),
           onSuggestions: (suggestions) => {
             try {
@@ -583,6 +583,11 @@ async function initBootstrap() {
  */
 async function initContainer(opts = {}) {
   const projectRoot = opts.projectRoot || process.cwd();
+
+  // 配置路径安全守卫 — 阻止写操作逃逸到项目外
+  const { default: Bootstrap } = await import('../lib/bootstrap.js');
+  Bootstrap.configurePathGuard(projectRoot);
+
   const bootstrap = await initBootstrap();
   const { getServiceContainer } = await import('../lib/injection/ServiceContainer.js');
   const container = getServiceContainer();