autosnippet 2.0.2 → 2.4.0

package/README.md

@@ -1,168 +1,244 @@
-# AutoSnippet — Project Knowledge Engine
+<div align="center">
 
-连接开发者、AI 与项目知识库：人工审核沉淀标准，知识库存储 Recipe + Snippet，AI 按规范生成代码。基于 SPM，打通 Xcode 补全与 Cursor 按需检索。
+# AutoSnippet
+
+**Project Knowledge Engine for iOS / Swift Teams**
+
+将团队的代码模式、最佳实践沉淀为 AI 可检索的知识库，<br>
+让 Cursor、Copilot 和 Xcode 都按你的项目规范生成代码。
 
 [![npm version](https://img.shields.io/npm/v/autosnippet.svg?style=flat-square)](https://www.npmjs.com/package/autosnippet)
 [![License](https://img.shields.io/npm/l/autosnippet.svg?style=flat-square)](https://github.com/GxFn/AutoSnippet/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square)](https://nodejs.org)
+
+</div>
 
 ---
 
-### 开发者、AI 与知识库
+## 为什么需要 AutoSnippet？
 
-| 角色 | 职责 | 能力 |
-|------|------|------|
-| **开发者** | 审核与决策；维护项目标准 | Dashboard 审核 Candidate，保存 Recipe；使用 Snippet 补全、`ass` 快捷联想或 `// as:search` 插入；运行 `asd embed`、`asd ui` |
-| **Cursor Agent** | 按规范生成代码；检索与提交 | Skills 理解规范；MCP 按需检索、打开新建 Recipe 页；`autosnippet_submit_candidates` 批量提交候选供人工审核；不直接改 Knowledge |
-| **项目内 AI** | 提取、摘要、扫描、审查 | `asd ais` 扫描；Use Copied Code 分析填充；Guard 审查；Dashboard RAG；深度扫描结果可算相似度。由 `.env` 配置 |
-| **知识库** | 存储与提供项目标准 | Recipes、Snippets、语义向量索引；Guard、搜索、质量评估、相似度分析；两种 AI 的上下文均依赖此 |
+AI 编码助手生成的代码往往脱离项目上下文——不知道团队约定、不了解架构模式、也不遵守代码规范。AutoSnippet 在你的项目中建立一个**活的知识库**，让所有 AI 工具都能检索并遵循团队沉淀的最佳实践。
 
----
+```
+你的项目代码  ──→  AI 扫描提取  ──→  人工审核  ──→  知识库 (Recipe)
+                                                        │
+                ┌───────────────────────────────────────┘
+                ↓
+        Cursor / Copilot / Xcode  ──→  按规范生成代码
+```
 
-## 安装与快速开始
+## 核心概念
 
-### 1. 安装 AutoSnippet
+| 概念 | 说明 |
+|------|------|
+| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，存储在数据库中，可导出为 Markdown 到 `AutoSnippet/recipes/` |
+| **Candidate** | 待审核的候选知识——来自 AI 扫描、手动提交或剪贴板，经 Dashboard 人工审核后晋升为 Recipe |
+| **Dashboard** | Web 管理后台（`asd ui`），管理 Recipe / Candidate / Guard / 知识图谱等 |
+| **Guard** | 代码审查引擎——基于知识库中的规则对代码做合规检查 |
+| **Skills** | Cursor Agent 技能文件——告诉 AI 何时、如何使用 AutoSnippet 的能力 |
 
-> **要求**：Node.js ≥ 20
+## 快速开始
 
 ```bash
+# 1. 全局安装
 npm install -g autosnippet
+
+# 2. 在你的项目目录初始化
+cd /path/to/your-project
+asd setup          # 创建 AutoSnippet/ 目录，配置 VSCode / Cursor
+
+# 3. 安装 IDE 集成（Skills + MCP + Cursor Rules）
+asd install:full
+
+# 4. 启动 Dashboard
+asd ui             # 启动 Web 后台 + 文件监听 + 语义索引
 ```
 
-### 2. 在你的项目中初始化
+> **注意**：始终在**你的项目目录**中执行 `asd` 命令，而非 AutoSnippet 源码仓库。
 
-**重要**：在**你的项目目录**（不是 AutoSnippet 源码目录）执行：
+## 工作流
 
-```bash
-cd /path/to/your-project   # 进入你的项目
+### 知识沉淀闭环
 
-asd setup                  # 一键初始化
-               # ✅ 创建 AutoSnippet/ 目录和配置
-               # ✅ 自动配置 VSCode (.vscode/settings.json)
-               # ✅ 自动配置 Cursor (.cursor/mcp.json)
-               # ✅ 放置 Recipe 模板
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│   ① 扫描提取                        ② 人工审核             │
+│   Cursor AI 扫描 Target ──→ Candidates ──→ Recipe 入库     │
+│   asd ais <Target>                Dashboard                 │
+│   剪贴板 / 手动提交                                         │
+│                                                             │
+│   ③ AI 按规范生成                    ④ 持续沉淀             │
+│   Cursor/Copilot 检索 Recipe ──→ 生成代码 ──→ 好代码再入库  │
+│   MCP 工具 / Xcode Snippet                                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### 3. 启动 Dashboard
+### 三种使用方式
 
-```bash
-asd ui                     # 启动 Dashboard + watch
+**① Cursor AI（推荐）**：自然语言驱动，Cursor 通过 13 个 Skills + 34 个 MCP 工具与知识库交互。
+
+```
+用户：「扫描 NetworkModule 这个 Target，提取最佳实践」
+Cursor → autosnippet_get_targets → autosnippet_get_target_files → 逐文件提取 → autosnippet_submit_candidates
+→ Dashboard Candidates 页面审核 → 保存为 Recipe
 ```
 
-`asd ui` 会启动 Web 管理后台并后台 watch；首次运行若前端不存在会自动构建。浏览器会自动打开 Dashboard。
+**② Dashboard Web UI**：可视化管理一切——Recipe 编辑器、Candidate 审核、知识图谱、Guard 审查、冷启动向导。
 
-![Dashboard 概览](https://cdn.jsdelivr.net/gh/GxFn/blog-images@main/autosnippet-manual/20260205232116_66_167.png)
+**③ 命令行 CLI**：`asd` 命令覆盖全部操作，适合自动化和脚本集成。
 
+## Dashboard
 
-## 核心流程
+`asd ui` 启动后访问 Web 管理后台：
 
-**智能 AI 优先 → 前端操作 → 命令行补充**
+![Dashboard](./resources/ASImage01.png)
 
-1. **Cursor AI 智能扫描**（推荐）：在 Cursor 中输入自然语言（如「扫描这个 Target」、「批量提取代码候选」），AI 智能触发 `autosnippet-candidates` Skill，通过 MCP 工具 `autosnippet_get_targets` → `autosnippet_get_target_files` → 按文件提取 → `autosnippet_submit_candidates` 一键批量扫描，自动提交候选到 Dashboard Candidates
-2. **前端审核与入库**：Dashboard Candidates 页面人工审核 → 保存 Recipe 入库（优先前端操作，无需命令行）
-3. **依赖关系**（可选）：Dashboard 刷新自动分析，或使用 `asd spm-map` 命令行更新
-4. **语义索引**（自动）：`asd ui` 启动时自动 embed；也可手动 `asd embed`
-5. **Cursor 集成**（首次）：`asd install:cursor-skill --mcp`（安装 Skills + Cursor 规则 `.cursor/rules/` + MCP；MCP 工具使用时需 `asd ui` 运行）
+**主要功能**：
 
-### 闭环
+- **Recipes**：浏览、编辑、发布、弃用知识条目；支持代码高亮编辑器
+- **Candidates**：审核 AI/手动提交的候选，一键入库或批量操作
+- **知识图谱**：可视化 Recipe 之间的关系（依赖 / 扩展 / 冲突等），AI 自动发现关系，按 category 分组布局
+- **Guard**：代码合规审查，查看违规记录与修复建议
+- **Xcode 模拟器**：在浏览器中模拟 `as:search` / `as:create` / `as:audit` 指令
+- **冷启动**：Bootstrap 向导——选择 SPM Target 逐个扫描，AI 提取代码模式生成 Candidate
 
-**AI 扫描 → Dashboard 审核 → 知识库沉淀 → Cursor/AI 按规范生成 → 再沉淀**：Cursor AI 通过自然语言指令智能扫描并批量提交候选，完整代码通过 Skill 智能提交，开发者也可通过 Dashboard Use Copied Code 或剪切板提交候选，所有候选经 Dashboard 人工审核进入知识库；知识库内 Recipe 为第一公民，拥有最高优先级。
+## IDE 集成
 
-Cursor 在编辑器内通过自然语言交互触发 Skill，使用 MCP 工具检索知识库，用 Recipe 作为生成代码的上下文标准；AI 生成的代码遵循 Recipe 规范，过审后成为新 Recipe，持续提升 AI 的开发标准化程度。
+### Cursor（推荐）
 
-知识库随人工审核持续更新，AI 始终基于最新上下文，Recipe 会在使用中获得评级调整。
+AutoSnippet 为 Cursor 提供完整的 MCP + Skills 集成：
 
-## 编辑器内指令
+- **34 个 MCP 工具**：搜索、Guard 检查、候选提交、知识图谱查询、Bootstrap 等
+- **13 个 Agent Skills**：`autosnippet-candidates`、`autosnippet-guard`、`autosnippet-coldstart` 等，引导 AI 正确使用工具
+- **写操作 Gateway 保护**：7 个写操作经过权限 / 宪法 / 审计三重检查
 
-需先运行 `asd watch` 或 `asd ui`。在源码中写入并保存：
+```bash
+asd install:cursor-skill --mcp  # 安装 Skills + MCP 配置
+```
 
-| 指令 | 作用 |
-|------|------|
-| `ass` / `// as:search` [关键词] | 从知识库检索并插入 Recipe/Snippet；`ass` 是最快捷的联想方式，优先推荐 |
-| `asc` / `// as:create` | 无选项时只打开 Dashboard（路径已填），由用户点 Scan File 或 Use Copied Code。`-c` 强制用剪切板（静默创建或打开）；`-f` 强制用路径（打开 Dashboard 并自动执行 Scan File） |
-| `asa` / `// as:audit` [关键词或规模] | 按知识库 AI 审查；无后缀时仅检查当前文件；后缀 **file** / **target** / **project** 可扩大范围（target=当前 Target 内所有源文件，project=项目内所有源文件）；其他为检索关键词 |
-| `// as:include` / `// as:import` | Snippet 内头文件/模块标记，保存时自动注入 |
+### VSCode Copilot
+
+```bash
+asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
+```
+
+### Xcode
+
+通过 Xcode Code Snippet 触发：
 
-**Snippet 生效**：`ass`、`asc`、`asa` 是 Xcode Snippet，需要执行 `asd setup` 将其注册到 Xcode 后，**彻底关闭 Xcode 并重启**才能生效。重启后在源码中输入首字母即可触发自动完成菜单。  
-**静默候选**：在 Cursor 内用户提出保存案例，Cursor 生成草案；后台用草案静默创建候选，无需打开浏览器，到 Dashboard **Candidates** 页审核即可。在 Xcode 等编辑器内也可写 `asc -c`、复制代码后保存，剪贴板内容同样静默入库。  
-**快捷联想**：输入 `ass`（AutoSnippet Search）触发 Snippet 快捷联想，或使用 `// as:search` / `// as:s` 在编辑器内弹窗选择，即选即插，无需跳转 Dashboard，不打断当前编辑。
+| 触发关键词 | 作用 |
+|-----------|------|
+| `ass` | 搜索知识库并插入代码（最快捷的联想方式） |
+| `asc` | 创建候选——打开 Dashboard 或从剪贴板静默提交 |
+| `asa` | 按知识库审查当前代码 |
 
-## 常用命令
+> 执行 `asd setup` 注册 Snippet 后，需**重启 Xcode** 才生效。
+
+## CLI 命令参考
 
 | 命令 | 说明 |
 |------|------|
-| `asd setup` | 初始化项目根（创建 AutoSnippet/AutoSnippet.boxspec.json） |
-| `asd ui` | 启动 Dashboard + watch |
-| `asd status` | 环境自检（含项目根、AI、索引、Dashboard/Watch、Native UI） |
-| `asd create --clipboard` | 从剪贴板创建 Recipe/Snippet |
-| `asd candidate` | 从剪贴板创建候选（Dashboard 审核） |
-| `asd extract` / `asd e` | 同步 Snippets 到 Xcode |
-| `asd ais [Target]` | AI 扫描 Target → Candidates |
-| `asd search [keyword] --copy` | 搜索并复制第一条到剪贴板 |
-| `asd search [keyword] --pick` | 交互选择后复制/插入 |
-| `asd sync` | 增量同步 `recipes/*.md` → DB（.md = Source of Truth） |
-| `asd compliance` | 生成宪法合规评估报告（P1-P4 加权评分） |
-| `asd upgrade` | 升级 IDE 集成文件（MCP/Skills/Cursor Rules/Copilot） |
-| `asd install:cursor-skill --mcp` | 安装 Skills、Cursor 规则（`.cursor/rules/*.mdc`）并配置 MCP。配置时可运行；MCP 工具使用时需 `asd ui` 已启动 |
-| `asd install:full` | 全量安装（Skills、MCP、Native UI） |
-| `asd embed` | 手动构建语义向量索引（`asd ui` 启动时也会自动执行） |
-| `asd spm-map` | 刷新 SPM 依赖映射（依赖关系图数据来源） |
+| `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） |
 
 ## 配置
 
-- **AI**：项目根 `.env`，参考 `.env.example` 配置 `ASD_GOOGLE_API_KEY` 等。可选 `ASD_AI_PROVIDER`、代理等。
-- **Native UI**（可选）：macOS 上 `npm install` 会尝试构建 `resources/native-ui/native-ui`（需本机 Swift）；未构建时回退到 AppleScript/inquirer，功能正常。
-- **权限设置**（可选）：写权限探针（在子仓库执行 `git push --dry-run`，通过才允许保存 Recipe/Snippet，否则 403）+ 完整性校验（`asd` 启动前关键文件 SHA-256）。详见 [权限设置说明](docs/权限设置说明.md)。
+### AI Provider
+
+在项目根目录创建 `.env` 文件（参考 `.env.example`）：
+
+```env
+ASD_AI_PROVIDER=gemini          # gemini / openai / anthropic
+ASD_GOOGLE_API_KEY=your-key     # Gemini API Key
+```
+
+### 项目目录结构
+
+```
+your-project/
+├── AutoSnippet/              # 知识库目录（建议整体作为 Git 子仓库）
+│   ├── recipes/              # Recipe Markdown 导出
+│   └── .autosnippet/         # 数据库、索引、Guard 配置等
+├── .cursor/
+│   ├── mcp.json          # MCP 配置（asd setup 自动生成）
+│   ├── rules/            # Cursor Rules（asd install 生成）
+│   └── skills/           # Agent Skills（asd install 生成）
+├── .vscode/
+│   └── settings.json     # VSCode MCP 配置
+└── .env                  # AI Provider 配置
+```
 
-## 术语
+### Git 策略建议
 
-| 术语 | 说明 |
+| 路径 | 建议 |
 |------|------|
-| **Recipe** | `AutoSnippet/recipes/` 下的 Markdown 知识（配方）：含代码块 + 使用说明，供 AI 检索、Guard、搜索，**默认位置，用户可通过 boxspec `knowledgeBase.dir` 配置改成 `Knowledge/` 等**
-| **Snippet** | Xcode 代码片段，通过 trigger（默认 `@`）补全，可与 Recipe 关联 |
-| **Candidate（候选）** | 待审核入库的项；来自 `as:create`、MCP 提交、`asd ais` 扫描等，经 Dashboard 审核后保存为 Recipe/Snippet |
-| **Knowledge（AutoSnippet）** | 项目知识库目录，包含 `recipes/`、`.autosnippet/`（索引、candidates、guard 配置等）；Snippet 配置在 root spec 的 list 中。|
-| **Dashboard** | Web 管理后台（`asd ui` 启动），含 Recipes、Candidates、Guard、Snippets 等页面 |
-| **watch** | 文件监听进程（`asd ui` 或 `asd watch` 启动），保存时触发 `as:create`、`as:audit`、`as:search` |
-| **Guard** | 按 Recipe 知识库对代码做 AI 审查；`// as:audit` 触发 |
-| **embed** | 语义向量索引构建；`asd embed` 或 `asd ui` 启动时自动执行，供语义检索与 MCP 使用 |
-| **MCP** | Model Context Protocol；Cursor 通过 MCP 调用 31 个工具（7 个写操作经 Gateway 权限保护） |
-| **Skills** | Cursor Agent Skills（`.cursor/skills/`），描述何时用、如何用 AutoSnippet 能力 |
-| **trigger** | Snippet 触发前缀，默认 `@`，输入后 Xcode 联想补全 |
-| **Gateway** | V2 控制平面，统一调度 27 个 Action：validate → permission → constitution → plugin → dispatch → audit |
-| **Constitution** | 宪法体系：6 角色、P1-P4 四优先级、能力探测，见 `config/constitution.yaml` |
-| **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
-| **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
-
-**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；
-
-## AutoSnippet 目录与 Git
-
-AutoSnippet 下各路径与版本控制的关系建议如下（可按项目需要调整）：
-
-| 路径 | 说明 | 建议 |
-|------|------|------|
-| **AutoSnippet/recipes/** | Recipe 的 Markdown 文件 | **Git 子仓库**：单独建远程仓库并 `git submodule add <url> AutoSnippet/recipes`，用于权限拦截（仅能 push 子仓库的人可保存/上传 Recipe）。详见 [权限设置说明](docs/权限设置说明.md) 中「只把 AutoSnippet/recipes 作为子仓库」。 |
-| **AutoSnippet/.autosnippet/** | Guard 规则、违反记录、candidates、recipe-stats、context 配置等 | **跟随主仓库 Git**：规则与配置建议提交到主仓库，便于团队共享。 |
-| **AutoSnippet/.autosnippet/context/index/** | 语义向量索引（embed 生成） | **不跟随 Git**：体积大、机器相关，建议加入 `.gitignore`（如 `AutoSnippet/.autosnippet/context/index/`）。 |
-| **AutoSnippet/.autosnippet/candidates/**（若存在） | 候选数据等 | 视需要：若仅本地缓存可不提交；若团队共享可跟随主仓库或单独子仓库。 |
-| **AutoSnippet/AutoSnippet.spmmap.json**（若存在） | SPM 依赖映射 | **跟随主仓库 Git**：便于依赖关系图一致。 |
-
-- **跟随主仓库 Git**：由主项目 `git add/commit/push` 管理，所有人按主仓库权限读写。
-- **Git 子仓库**：`AutoSnippet/recipes` 为单独仓库（submodule），Recipe 上传（git push）由 Git 服务端权限拦截。配合 `.env` 中 `ASD_RECIPES_WRITE_DIR=AutoSnippet/recipes` 是为了保识管理员（有 push 权限者）能够正确提交 Recipe：探针目录与 Recipe 写入目录一致，保存后可正常推送。
-- **不跟随 Git**：在 `.gitignore` 中忽略，不提交、不推送。
+| `AutoSnippet/` | **整体作为 Git 子仓库**——独立权限控制，写权限探针（`git push --dry-run`）在此目录执行，仅知识管理员可 push |
+| `AutoSnippet/.autosnippet/context/index/` | 加入 `.gitignore`——体积大、机器相关 |
 
----
+## 架构概览
 
-## 为什么推荐 Cursor
+```
+┌────────────────────────────────────────────────────────┐
+│  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) + 向量索引     │  │
+│  └──────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
 
-**Cursor 优先**的原因：
+## 技术栈
 
-- **MCP & Skills 完整支持**：Cursor 对 MCP（Model Context Protocol）的集成完善，Skills 能够正常触发和运行，支持自然语言指令流畅地调用 `autosnippet_get_targets`、`autosnippet_get_target_files`、`autosnippet_submit_candidates` 等工具
-- **候选提交体验流畅**：整个从扫描 → 提取 → 提交的工作流无缝衔接，用户无需手动介入，一键完成批量操作
-- **VSCode Copilot 限制**：目前 VSCode Copilot 的 MCP 集成存在问题，无法直接调用 MCP 工具。降级方案是存储候选为 Draft（本地），然后通过 API 提交，增加了用户额外操作步骤
+- **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 + 关键词三模式搜索
 
-建议优先在 Cursor 中使用 AutoSnippet；如需 VSCode Copilot 支持，欢迎 [Issue](https://github.com/GxFn/AutoSnippet/issues) 讨论降级方案的适配。
+## Xcode 深度集成
 
----
+AutoSnippet 不依赖 Xcode 插件，通过 **AppleScript + FileWatcher + 原生 macOS UI** 实现深度集成。
+
+| 能力 | 说明 |
+|------|------|
+| **保存即触发** | FileWatcher 监听源码目录；在代码中写入 `// as:search`、`// as:create`、`// as:audit` 后按 `⌘S`，自动执行对应操作 |
+| **AppleScript 自动化** | 通过 `osascript` 驱动 Xcode——行号跳转、行选中、剪切/粘贴替换、前台检测；搜索结果直接替换触发行 |
+| **原生 macOS UI** | Swift 原生弹窗展示搜索结果列表（降级为 AppleScript `choose from list`）；系统通知反馈操作结果 |
+| **智能 import 注入** | 插入代码时自动分析所需 `import`，检查 SPM 模块可达性，确认后通过 AppleScript 注入头文件 |
+| **三层防误触** | Self-write 冷却 + 内容哈希去重 + Xcode 焦点检测，区分手动保存与自动保存 |
+| **Code Snippet** | `ass`（搜索插入）、`asc`（创建候选）、`asa`（代码审查），`asd setup` 注册后重启 Xcode 生效 |
+
+## 贡献
+
+欢迎 [Issue](https://github.com/GxFn/AutoSnippet/issues) 与 [PR](https://github.com/GxFn/AutoSnippet/pulls)。
+
+## License
 
-欢迎 [Issue](https://github.com/GxFn/AutoSnippet/issues) 与 [PR](https://github.com/GxFn/AutoSnippet/pulls)。MIT 许可证。
+[MIT](LICENSE)

package/bin/api-server.js

@@ -33,10 +33,7 @@ async function main() {
       db: components.db,
       auditLogger: components.auditLogger,
       gateway: components.gateway,
-      reasoningLogger: components.reasoningLogger,
-      roleDriftMonitor: components.roleDriftMonitor,
-      complianceEvaluator: components.complianceEvaluator,
-      sessionManager: components.sessionManager,
+      constitution: components.constitution,
     });
     logger.info('Service container initialized successfully');
 

package/bin/cli.js

@@ -251,52 +251,6 @@ program
     }
   });
 
-// ─────────────────────────────────────────────────────
-// compliance 命令
-// ─────────────────────────────────────────────────────
-program
-  .command('compliance')
-  .description('运行合规评估')
-  .option('--json', '以 JSON 格式输出')
-  .action(async (opts) => {
-    try {
-      const { bootstrap, container } = await initContainer();
-      const complianceEvaluator = container.get('complianceEvaluator');
-
-      if (!complianceEvaluator) {
-        console.error('ComplianceEvaluator not available');
-        process.exit(1);
-      }
-
-      const report = complianceEvaluator.evaluate();
-
-      if (opts.json) {
-        console.log(JSON.stringify(report, null, 2));
-      } else {
-        console.log('\n📊 Compliance Report\n');
-        console.log(`   Overall Score: ${(report.overallScore * 100).toFixed(1)}%`);
-        console.log(`   Grade: ${report.grade || 'N/A'}\n`);
-
-        for (const [key, metric] of Object.entries(report.priorities || {})) {
-          const pct = ((metric.score || 0) * 100).toFixed(1);
-          console.log(`   ${key}: ${pct}%`);
-        }
-
-        if (report.recommendations?.length) {
-          console.log('\n   Recommendations:');
-          for (const rec of report.recommendations.slice(0, 5)) {
-            console.log(`   • ${rec}`);
-          }
-        }
-      }
-
-      await bootstrap.shutdown();
-    } catch (err) {
-      console.error('Error:', err.message);
-      process.exit(1);
-    }
-  });
-
 // ─────────────────────────────────────────────────────
 // server 命令
 // ─────────────────────────────────────────────────────
@@ -601,10 +555,7 @@ async function initContainer(opts = {}) {
     db: bootstrap.components.db,
     auditLogger: bootstrap.components.auditLogger,
     gateway: bootstrap.components.gateway,
-    reasoningLogger: bootstrap.components.reasoningLogger,
-    roleDriftMonitor: bootstrap.components.roleDriftMonitor,
-    complianceEvaluator: bootstrap.components.complianceEvaluator,
-    sessionManager: bootstrap.components.sessionManager,
+    constitution: bootstrap.components.constitution,
     projectRoot,
   });
   return { bootstrap, container };

package/config/constitution.yaml

@@ -1,69 +1,33 @@
-# ═══════════════════════════════════════════════════════════
-# AutoSnippet Constitution — 权限宪法
-# ═══════════════════════════════════════════════════════════
-#
-# 三层权限架构:
-#   ① 能力层 (capabilities) — git push --dry-run 探测物理写权限
-#   ② 角色层 (roles)        — 角色权限矩阵 (action:resource)
-#   ③ 治理层 (priorities)   — 业务规则引擎
-#
-# 双路径模式:
-#   AUTH_ENABLED=false → 子仓库探针自动决定角色（能力层驱动）
-#   AUTH_ENABLED=true  → 登录后根据用户配置角色（角色层驱动）
-# ═══════════════════════════════════════════════════════════
+# AutoSnippet Constitution
+version: "3.0"
+effective_date: "2026-02-13"
 
-version: "2.0"
-effective_date: "2026-02-10"
-
-# ─── 能力探测 ─────────────────────────────────────────────
 capabilities:
   git_write:
-    description: "子仓库 git push 权限"
+    description: "subrepo git push"
     probe: "git push --dry-run"
-    # 无子仓库 → 个人项目, 视为 admin (全权限)
     no_subrepo: "allow"
-    # 有子仓库但无 remote → 本地开发, 视为 admin
     no_remote: "allow"
     cache_ttl: 86400
 
-# ─── 治理优先级 ───────────────────────────────────────────
-priorities:
-  - id: 1
-    name: "Data Integrity"
-    description: "保护用户项目数据不被破坏"
-    rules:
-      - "所有写操作必须经过备份"
-      - "删除操作必须有确认步骤"
-      - "关键文件修改需要记录审计日志"
-  
-  - id: 2
-    name: "Human Oversight"
-    description: "保持人类对 AI 决策的监督"
-    rules:
-      - "AI 生成的 Candidate 必须经人工审核"
-      - "Guard 规则修改需要人工批准"
-      - "批量操作需要明确授权"
-  
-  - id: 3
-    name: "AI Transparency"
-    description: "AI 决策过程必须可追溯"
-    rules:
-      - "Candidate 必须包含 Reasoning 信息"
-      - "Guard 规则必须关联来源 Recipe"
-      - "所有 AI 操作记录到审计日志"
-  
-  - id: 4
-    name: "Helpfulness"
-    description: "在保证安全前提下尽可能帮助用户"
-    rules:
-      - "提供充分的错误信息和修复建议"
-      - "优先推荐高质量 Recipe"
-      - "自动优化常见操作"
+rules:
+  - id: "destructive_confirm"
+    description: "delete needs confirmation"
+    check: "destructive_needs_confirmation"
+  - id: "content_required"
+    description: "create candidate/recipe needs content"
+    check: "creation_needs_content"
+  - id: "ai_no_direct_recipe"
+    description: "AI cannot directly create/approve recipe"
+    check: "ai_cannot_approve_recipe"
+  - id: "batch_authorized"
+    description: "batch ops need authorization"
+    check: "batch_needs_authorization"
 
 roles:
-  - id: "cursor_agent"
-    name: "Cursor / Copilot Agent"
-    description: "在 IDE 中运行的 AI 助手"
+  - id: "external_agent"
+    name: "External Agent"
+    description: "IDE AI agent (Cursor / Copilot / Claude Code)"
     permissions:
       - "read:recipes"
       - "read:guard_rules"
@@ -71,64 +35,26 @@ roles:
       - "submit:candidates"
       - "read:audit_logs:self"
       - "knowledge:bootstrap"
+      - "create:skills"
     constraints:
-      - "不能直接修改 Recipe"
-      - "不能修改 Guard 规则"
-      - "不能删除任何数据"
-  
-  - id: "asd_ais"
-    name: "ASD AI审查"
-    description: "AutoSnippet 内置的 AI 审查系统"
+      - "cannot modify Recipe directly"
+      - "cannot modify Guard rules"
+      - "cannot delete any data"
+  - id: "chat_agent"
+    name: "ChatAgent"
+    description: "built-in AI agent (Dashboard chat / programmatic)"
     permissions:
       - "read:recipes"
       - "read:candidates"
       - "create:candidates"
       - "read:guard_rules"
     constraints:
-      - "生成的 Candidate 必须包含完整 Reasoning"
-      - "不能绕过 Guard 检查"
-  
-  - id: "guard_engine"
-    name: "Guard 检查引擎"
-    description: "代码质量检查系统"
-    permissions:
-      - "read:candidates"
-      - "read:guard_rules"
-      - "write:audit_logs"
-    constraints:
-      - "只能读取，不能修改数据"
-  
-  - id: "developer_admin"
-    name: "开发者（管理员）"
-    description: "项目管理员"
+      - "candidate must include reasoning"
+      - "cannot bypass Guard check"
+  - id: "developer"
+    name: "Developer"
+    description: "project owner, full access"
     permissions:
-      - "*"  # 全部权限
+      - "*"
     requires_capability:
       - "git_write"
-  
-  - id: "developer_contributor"
-    name: "开发者（贡献者）"
-    description: "项目贡献者"
-    permissions:
-      - "read:*"
-      - "approve:candidates"
-      - "reject:candidates"
-      - "create:recipes"
-    constraints:
-      - "不能删除 Recipe"
-      - "不能禁用 Guard 规则"
-    requires_capability:
-      - "git_write"
-
-  - id: "visitor"
-    name: "访问者"
-    description: "只读访问（无子仓库写权限或未登录）"
-    permissions:
-      - "read:recipes"
-      - "read:snippets"
-      - "read:candidates"
-      - "read:guard_rules"
-      - "search:query"
-    constraints:
-      - "只能查看，不能修改任何数据"
-      - "不能创建 Candidate 或 Recipe"