autosnippet 3.0.1 → 3.0.3

package/README.md

@@ -2,420 +2,327 @@
 
 # AutoSnippet
 
-**Project Knowledge Engine for iOS / Swift Teams**
+**Knowledge Engine for Code — Turn your team's patterns into AI-searchable recipes.**
 
-将团队的代码模式、最佳实践沉淀为 AI 可检索的知识库，<br>
-让 Cursor、Trae、Copilot、Qoder 和 Xcode 都按你的项目规范生成代码。
+Capture code patterns, best practices, and architecture decisions as a structured knowledge base.  
+Then let Cursor, Copilot, Trae, Qoder, Xcode, and VS Code generate code that follows *your* standards.
 
 [![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)
 
+[中文文档](README_CN.md)
+
 </div>
 
 ---
 
-## 为什么需要 AutoSnippet？
+## The Problem
+
+AI coding assistants generate code in a vacuum — they don't know your team's conventions, architecture patterns, or coding standards. Every AI-generated PR becomes a review burden.
 
-AI 编码助手生成的代码往往脱离项目上下文——不知道团队约定、不了解架构模式、也不遵守代码规范。AutoSnippet 在你的项目中建立一个**活的知识库**，让所有 AI 工具都能检索并遵循团队沉淀的最佳实践。
+**AutoSnippet** bridges this gap by building a living knowledge base inside your project, making your team's expertise queryable by any AI tool.
 
 ```
-你的项目代码  ──→  AI 扫描提取  ──→  人工审核  ──→  知识库 (Recipe)
-                                                        │
-                ┌───────────────────────────────────────┘
-                ↓
-        Cursor / Trae / Copilot / Qoder / Xcode  ──→  按规范生成代码
+Your Codebase  ──→  AI Scan & Extract  ──→  Human Review  ──→  Knowledge Base (Recipes)
+                                                                       │
+                 ┌─────────────────────────────────────────────────────┘
+                 ↓
+         Cursor / Copilot / Trae / Qoder / Xcode / VS Code
+                 ↓
+         Code generated following YOUR standards
 ```
 
-## 核心概念
+## Key Concepts
 
-| 概念 | 说明 |
-|------|------|
-| **Recipe** | 知识库的基本单元——一段代码模式 + 使用说明 + 元数据，以 Markdown 文件（`AutoSnippet/recipes/*.md`）为 Source of Truth，SQLite 作为检索缓存 |
-| **Candidate** | 待审核的候选知识——来自 AI 扫描、手动提交、剪贴板或 Bootstrap 冷启动，经 Dashboard 人工审核后晋升为 Recipe |
-| **Dashboard** | Web 管理后台（`asd ui`），10+ 功能视图：Recipes / Candidates / Knowledge / AI Chat / SPM Explorer / 知识图谱 / 依赖图 / Guard / Skills / Xcode 模拟器 / Help |
-| **Guard** | 代码审查引擎——基于知识库中的规则对代码做合规检查，支持文件 / Target / 项目三级范围 |
-| **Skills** | 13 个 Agent 技能包——覆盖候选生成、冷启动、Guard 审计、意图路由、生命周期管理等场景，支持 Cursor 和 Qoder |
-| **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 和搜索使用 |
+| Concept | Description |
+|---------|-------------|
+| **Recipe** | The atomic unit of knowledge — a code pattern + explanation + metadata. Stored as Markdown in `AutoSnippet/recipes/`, cached in SQLite for fast retrieval |
+| **Candidate** | A pending knowledge entry awaiting human review — from AI scans, manual submission, or bootstrap. Promoted to Recipe after approval |
+| **Guard** | Code compliance engine — checks source files against knowledge-derived rules at file, target, or project scope |
+| **Skill** | Agent instruction sets (18 built-in) — guide AI agents to correctly invoke knowledge base operations |
+| **Bootstrap** | Cold-start engine — 9-dimension heuristic scan + dual-agent AI analysis, generating dozens of candidates in one pass |
 
-## 快速开始
+## Quick Start
 
 ```bash
-# 1. 全局安装
+# Install globally
 npm install -g autosnippet
 
-# 2. 在你的项目目录初始化
+# Initialize in your project
 cd /path/to/your-project
-asd setup          # 创建 AutoSnippet/ 目录，配置 VSCode / Cursor / Qoder
-
-# 3. 安装 IDE 集成（Skills + MCP + Cursor Rules）
-asd install:full
+asd setup              # Creates workspace, DB, IDE integrations, installs VS Code extension
 
-# 4. 启动 Dashboard
-asd ui             # 启动 Web 后台 + 文件监听 + 语义索引
+# Cold-start: scan your codebase and extract patterns
+asd coldstart          # 9-dimension AI analysis → Candidates
 
-# 5. 检查环境状态
-asd status         # 自检项目根、AI Provider、索引、Dashboard
+# Launch Dashboard to review and manage knowledge
+asd ui                 # Web dashboard + API server
 ```
 
-> **注意**：始终在**你的项目目录**中执行 `asd` 命令，而非 AutoSnippet 源码仓库。
+> **Important**: Always run `asd` commands inside your project directory, not in the AutoSnippet source repo.
 
-## 工作流
+## How It Works
 
-### 端到端使用流程
-
-从零开始到知识库持续运转的完整路径——以 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 服务 + 文件监听
+┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐
+│  ① Setup   │──→ │ ② Cold     │──→ │ ③ Target   │──→ │ ④ Review   │──→ │ ⑤ IDE      │
+│  asd setup │    │   Start    │    │   Scan     │    │  Dashboard │    │  Delivery  │
+└────────────┘    └────────────┘    └────────────┘    └────────────┘    └─────┬──────┘
+                                                                              │
+      ┌───────────────────────────────────────────────────────────────────────┘
+      ↓
+┌────────────┐    ┌────────────┐
+│ ⑥ AI Codes │──→ │ ⑦ New      │──→  Back to ③
+│ by Rules   │    │  Patterns  │
+└────────────┘    └────────────┘
 ```
 
-完成后，你的项目目录下会生成 `.cursor/mcp.json`、`.cursor/skills/`、`.cursor/rules/` 等集成文件，Cursor 已经可以通过 MCP 与 AutoSnippet 通信。
-
-**② 冷启动——全局扫描建立基线**
-
-在 Cursor 中用自然语言触发冷启动：
+1. **Setup** — `asd setup` creates the workspace structure, SQLite database, MCP configs for Cursor/VS Code/Qoder/Trae, and installs the VS Code extension
+2. **Cold Start** — Bootstrap engine scans your codebase across 9 dimensions (architecture, naming, networking, data flow, error handling, etc.) using a dual-agent system (Analyst → Producer)
+3. **Target Scan** — `asd ais <target>` performs focused extraction on specific modules
+4. **Review** — Dashboard provides card-based review UI with AI confidence scoring, batch approve/reject, and inline editing
+5. **IDE Delivery** — Recipes are delivered via MCP tools (real-time), Cursor Rules (`.cursor/rules/`), and Agent Skills
+6. **AI Generation** — IDE AI assistants query the knowledge base and generate code following your team's patterns
+7. **Continuous Capture** — File watchers detect new patterns, creating a feedback loop
 
-```
-你：「对项目做一次全量冷启动，提取所有代码模式」
-```
-
-Bootstrap 引擎自动完成：SPM Target 发现 → 文件收集 → AST 结构分析 → 9 维度启发式扫描（架构 / 命名 / 网络 / 数据流 / 错误处理等） → Analyst Agent 深度分析 → Producer Agent 格式化提交。
+## Features
 
-冷启动结束后，Dashboard Candidates 页面会出现数十条候选知识条目。
+### 🔍 Multi-Strategy Search Engine
 
-**③ 逐 Target 精细扫描**
+4-layer retrieval funnel with 5 search modes:
 
-冷启动覆盖全局，但每个 Target 的独特模式需要针对性提取：
+| Layer | Strategy | Purpose |
+|-------|----------|---------|
+| L1 | Inverted Index + BM25 | Fast keyword recall with CJK support |
+| L2 | Cross-Encoder Reranker | AI-powered semantic reranking |
+| L2.5 | Coarse Ranker (E-E-A-T) | 5-dimension quality scoring |
+| L3 | Multi-Signal Ranker | 6-signal weighted ranking (relevance, authority, recency, popularity, difficulty, seasonality) |
 
-```
-你：「扫描 NetworkModule 这个 Target，把里面的请求封装模式提取出来」
-你：「分析 UIComponents Target 的自定义控件实现」
-```
+### 🤖 AI Integration (6 Providers)
 
-Cursor 调用 `structure({ operation: "targets" })` → `structure({ operation: "files" })` → 逐文件 AI 分析 → `submit_knowledge_batch`，将发现的代码模式作为 Candidate 提交到知识库。你可以逐个 Target 推进，每个 Target 的扫描结果会独立进入审核队列。
+| Provider | Notes |
+|----------|-------|
+| Google Gemini | Native tool calling + structured output |
+| OpenAI | GPT-4o, GPT-4, etc. |
+| Claude (Anthropic) | Native tool calling |
+| DeepSeek | OpenAI-compatible |
+| Ollama | Local models, no API key needed |
+| Mock | Auto-fallback when no AI configured |
 
-**④ 审核发布——人工把关质量**
+Auto-detection, priority-based fallback, and context window adaptation.
 
-打开 Dashboard（`asd ui`），进入 **Candidates** 页面：
+### 🛡️ Guard — Code Compliance
 
-- 候选按置信度排序，高信心的排在前面
-- 点击候选卡片展开详情：查看代码片段、AI 分析理由、来源文件
-- **接受** → 候选晋升为 Recipe，进入活跃知识库
-- **编辑后接受** → 审核时可修改标题、描述、代码、标签
-- **拒绝** → 低质量或重复的候选直接归档
+- **Regex + AST semantic rules** (mustCallThrough, mustNotUseInContext, mustConformToProtocol)
+- **3 scopes**: file / target / project
+- **CI/CD ready**: `asd guard:ci` with Quality Gate, `asd guard:staged` for pre-commit hooks
+- **Rule learning**: Auto-suggest rules from violation patterns (14-day effectiveness tracking)
+- **Feedback loop**: Guard violations → Recipe usage confirmation
 
-批量操作：一键接受所有高信心候选，或一键拒绝低质量条目。
+### 📊 Dashboard (18 Views)
 
-**⑤ 注入 Cursor——知识即规则**
+Full-featured web UI launched with `asd ui`:
 
-Recipe 发布后，Cursor 立即可以通过三种通道获取知识：
+- **Knowledge Management** — Recipe browser, candidate review, batch operations
+- **AI Chat** — ReAct-loop conversation with 54 internal tools
+- **Knowledge Graph** — Visual relationship explorer
+- **Guard Dashboard** — Rule management, violation tracking, compliance reports
+- **SPM / Module Explorer** — Dependency analysis across language ecosystems
+- **Wiki Generator** — Auto-generated project documentation with Mermaid diagrams
+- **Bootstrap Progress** — Real-time 9-dimension progress with time estimates
+- **Skills Manager** — Browse, create, and manage agent skills
+- **LLM Config** — Visual AI provider/model/key configuration
 
-| 通道 | 机制 | 时效 |
-|------|------|------|
-| **MCP 工具检索** | Cursor 通过 `autosnippet_search` 等 16 个工具实时查询知识库 | 实时 |
-| **Cursor Rules** | `asd upgrade` 将 Recipe 导出为 `.cursor/rules/autosnippet-*.mdc` 文件 | 手动触发 |
-| **Agent Skills** | 13 个 Skill 文档引导 Cursor 在正确场景自动调用知识库 | 常驻 |
+### 🔌 IDE Integrations
 
-**⑥ AI 按规范生成代码**
+#### MCP Server (16 Tools)
 
-当你在 Cursor 中编写代码时，AI 会自动检索知识库：
+Works with any MCP-compatible IDE (Cursor, VS Code Copilot, Qoder, Trae):
 
+```bash
+# Automatically configured by asd setup
+# Or manually: asd setup:mcp
 ```
-你：「写一个网络请求方法，获取用户信息」
-Cursor → 检索知识库 → 命中 Recipe: "Network Layer Pattern"
-     → 按团队封装的 NetworkManager 生成代码，而非裸调 URLSession
-```
-
-Guard 规则也在同步工作——如果生成的代码违反了知识库中的规则（如 `kind=rule` 的条目），会实时提醒和纠正。
-
-**⑦ 持续沉淀——知识库越用越好**
-
-日常开发中发现新的代码模式或团队约定？随时沉淀：
-
-- 在 Cursor 中：`「把这段 error handling 模式提取为知识库条目」`
-- 在 Xcode 中：代码注释写 `// as:create` 然后 `⌘S`
-- 在 Dashboard 中：AI Chat 对话式提交
-- 通过剪贴板：复制代码后自动检测并建议入库
-
-知识库形成飞轮：**代码沉淀 → Recipe 增长 → AI 生成质量提升 → 团队效率提高 → 更多代码模式沉淀**。
 
-## Dashboard
+12 Agent-tier tools (search, knowledge, structure, graph, guard, submit, skills, bootstrap, etc.) + 4 Admin tools.
 
-`asd ui` 启动后访问 Web 管理后台：
+#### VS Code Extension
 
-![Dashboard](./resources/ASImage02.png)
+Installed automatically by `asd setup`. Features:
 
-**功能视图**：
+- **Search & Insert** — `Cmd+Shift+F5` opens QuickPick with code preview, inserts at cursor
+- **Directive Detection** — Auto-detects `// as:s`, `// as:c`, `// as:a` directives on save
+- **CodeLens** — Inline action buttons above directives
+- **Guard Audit** — Run compliance checks on files or entire project
+- **Create Candidate** — Submit selected code as a knowledge candidate
+- **Status Bar** — Real-time API server connection indicator
 
-| 视图 | 说明 |
-|------|------|
-| **Recipes** | 浏览、编辑、发布、弃用知识条目；详情抽屉支持 Markdown 编辑与关联关系管理 |
-| **Candidates** | 审核 AI / 手动提交的候选，一键入库或批量操作，支持 AI 润色 |
-| **Knowledge** | 统一知识条目浏览（V3 格式），双列卡片布局，代码预览 + 详情抽屉 |
-| **AI Chat** | ChatAgent 智能对话（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** | 使用帮助与快捷键参考 |
+#### Xcode Integration
 
-**辅助功能**：全局搜索面板、LLM 配置弹窗、Bootstrap 进度视图、实时 WebSocket 更新。
+- **File Watcher** — `asd watch` monitors files for `// as:` directives
+- **Auto-Insertion** — osascript-driven code insertion preserving Undo history
+- **Header Management** — Automatic `#import`/`@import` deduplication with SPM-aware decisions
+- **Snippet Sync** — Export recipes as native Xcode `.codesnippet` files
 
-## IDE 集成
+### 📝 File Directives
 
-### Cursor（推荐）
+Write directives as comments in any source file:
 
-AutoSnippet 为 Cursor 提供完整的 MCP + Skills 集成：
-
-- **16 个 MCP 工具**（12 agent + 4 admin）：search / knowledge / structure / graph / guard / bootstrap / skill 等参数化统合入口，覆盖搜索、审查、候选管理、冷启动等场景
-- **13 个 Agent Skills**：`autosnippet-candidates`、`autosnippet-guard`、`autosnippet-coldstart`、`autosnippet-intent` 等，引导 AI 正确使用工具
-- **写操作 Gateway 保护**：写操作经过权限 / 宪法 / 审计三重检查
-
-```bash
-asd install:cursor-skill --mcp  # 安装 Skills + MCP 配置
+```objc
+// as:s network request timeout    → Search & insert matching recipe
+// as:c                            → Create candidate from surrounding code
+// as:c -c                         → Create candidate from clipboard
+// as:a                            → Run Guard audit on this file
+// as:include "MyHeader.h"         → ObjC header import
+// as:import UIKit                 → Module import
 ```
 
-### Qoder
-
-AutoSnippet 对 Qoder 的支持通过镜像 Cursor 交付物料到 `.qoder/`：
-
-- **Skills**（`.qoder/skills/`）：与 `.cursor/skills/` 相同的 Agent Skills
-- **Rules**（`.qoder/rules/*.md`）：从 `.cursor/rules/*.mdc` 自动转换为标准 Markdown
-- **MCP**：不支持项目级 `.qoder/mcp.json`，需通过 Qoder IDE 界面 Your Settings → MCP → "+ Add" 配置。
-
-### Trae
+### 🧬 AST Analysis (9 Languages)
 
-AutoSnippet 对 Trae 的支持通过镜像 Cursor 交付物料到 `.trae/`：
+Tree-sitter powered code intelligence:
 
-- **Skills**（`.trae/skills/`）：与 `.cursor/skills/` 相同的 Agent Skills
-- **Rules**（`.trae/rules/*.md`）：从 `.cursor/rules/*.mdc` 自动转换为标准 Markdown
-- **MCP**：不支持项目级 `.trae/mcp.json`，需通过 Trae IDE 界面 设置 → MCP → "+ 添加" 手动配置。
+| Language | Capabilities |
+|----------|-------------|
+| Objective-C, Swift | Full: classes, protocols, categories, extensions, design patterns |
+| TypeScript, JavaScript, TSX | Classes, functions, React components, imports |
+| Python | Classes, functions, decorators, imports |
+| Java, Kotlin | Classes, interfaces, annotations |
+| Go | Structs, interfaces, functions |
 
-### VSCode Copilot
+Plus 11 framework enhancement packs (React, Vue, Spring, Django, FastAPI, gRPC, Android, etc.).
 
-```bash
-asd install:vscode-copilot      # 配置 MCP 和 Copilot 指令
-```
-
-### Xcode
+### 🏛️ Constitution & Governance
 
-通过 Xcode Code Snippet 触发：
+Three-layer permission model:
 
-| 触发关键词 | 作用 |
-|-----------|------|
-| `ass` | 搜索知识库并插入代码（最快捷的联想方式） |
-| `asc` | 创建候选——打开 Dashboard 或从剪贴板静默提交 |
-| `asa` | 按知识库审查当前代码 |
+1. **Capability Layer** — `git push --dry-run` probes write access (physical signal)
+2. **Role Layer** — 3 roles (developer / external_agent / chat_agent) with permission matrix
+3. **Governance Layer** — 4 inviolable rules enforced by Constitution engine
 
-> 执行 `asd setup` 注册 Snippet 后，需**重启 Xcode** 才生效。
+Every write operation passes through the Gateway: role check → constitution rules → audit log.
 
-## CLI 命令参考
+### 🧠 Agent Memory (4 Tiers)
 
-| 命令 | 说明 | 常用选项 |
-|------|------|----------|
-| `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） | — |
+| Tier | Scope | Persistent | Purpose |
+|------|-------|-----------|---------|
+| Working Memory | Session | No | Scratchpad + context compression |
+| Episodic Memory | Cross-dimension | No | Discovery sharing between bootstrap dimensions |
+| Project Semantic Memory | Project | SQLite | Permanent facts, insights, preferences (importance scoring + TTL) |
+| Tool Result Cache | Cross-dimension | No | Deduplication of tool calls |
 
-## MCP 工具一览
+## CLI Reference
 
-16 个 MCP 工具按功能分组（省略了 **autosnippet_** 前缀）：
+| Command | Description |
+|---------|-------------|
+| `asd setup` | Initialize workspace, DB, IDE configs, install VS Code extension |
+| `asd coldstart` | Bootstrap knowledge base (9-dimension AI scan) |
+| `asd ais [target]` | AI scan source files → extract and publish recipes |
+| `asd ui` | Launch Dashboard + API server |
+| `asd watch` | Start Xcode file watcher for directives |
+| `asd search <query>` | Search knowledge base |
+| `asd guard <file>` | Run Guard compliance check |
+| `asd guard:ci` | CI/CD full-project Guard + Quality Gate |
+| `asd guard:staged` | Check git staged files (pre-commit hook) |
+| `asd sync` | Sync `recipes/*.md` → SQLite database |
+| `asd upgrade` | Update IDE integrations (MCP, Skills, Rules) |
+| `asd cursor-rules` | Generate Cursor 4-channel delivery artifacts |
+| `asd server` | Start API server standalone |
+| `asd status` | Check environment health |
 
-**Agent 层（12 个）**——默认对外暴露：
+## Architecture
 
-| 分类 | 工具 | 说明 |
-|------|------|------|
-| **系统** | `health` | 服务健康检查 |
-| **系统** | `capabilities` | 服务能力清单（Agent 自发现） |
-| **搜索** | `search` | 统合入口，`mode` 参数路由 auto / keyword / semantic / context 四种模式 |
-| **知识浏览** | `knowledge` | `operation` 参数路由 list / get / insights / confirm_usage |
-| **项目结构** | `structure` | `operation` 参数路由 targets / files / metadata |
-| **知识图谱** | `graph` | `operation` 参数路由 query / impact / path / stats |
-| **Guard** | `guard` | `code` 参数审查单文件代码，`files` 参数批量审查文件 |
-| **知识提交** | `submit_knowledge` / `submit_knowledge_batch` / `save_document` | 提交候选 / 批量提交 / 保存开发文档 |
-| **Skill 管理** | `skill` | `operation` 参数路由 list / load / create / update / delete / suggest |
-| **冷启动** | `bootstrap` | `operation` 参数路由 knowledge / refine / scan |
-
-**Admin 层（4 个）**——需设置 `ASD_MCP_TIER=admin`：
-
-| 分类 | 工具 | 说明 |
-|------|------|------|
-| **候选管理** | `enrich_candidates` / `validate_candidate` / `check_duplicate` | AI 润色 / 校验 / 查重 |
-| **知识管理** | `knowledge_lifecycle` | 批量生命周期操作 |
+```
+┌─────────────────────────────────────────────────────────┐
+│                      IDE Layer                          │
+│  Cursor │ VS Code │ Trae │ Qoder │ Xcode │ Dashboard   │
+└────────────────────────┬────────────────────────────────┘
+                         │
+              ┌──────────┴──────────┐
+              │   MCP Server (16)   │──── HTTP API (REST + WebSocket)
+              └──────────┬──────────┘
+                         │
+┌────────────────────────┴────────────────────────────────┐
+│                   Service Layer                         │
+│  SearchEngine │ KnowledgeService │ GuardEngine │ Chat   │
+│  Bootstrap    │ WikiGenerator    │ Skills      │ SPM    │
+└────────────────────────┬────────────────────────────────┘
+                         │
+┌────────────────────────┴────────────────────────────────┐
+│                    Core Layer                           │
+│  AstAnalyzer (9 lang) │ KnowledgeGraph │ CodeEntityGraph│
+│  RetrievalFunnel      │ QualityScorer  │ ConfidenceRouter│
+└────────────────────────┬────────────────────────────────┘
+                         │
+┌────────────────────────┴────────────────────────────────┐
+│                Infrastructure Layer                     │
+│  SQLite │ VectorStore │ EventBus │ AuditLog │ Gateway   │
+│  DI Container (40+ services) │ Constitution │ PathGuard │
+└─────────────────────────────────────────────────────────┘
+```
 
-## 配置
+## Configuration
 
-### AI Provider
+### AI Provider Setup
 
-在项目根目录创建 `.env` 文件（参考 `.env.example`）：
+Create `.env` in your project root (or configure via Dashboard → LLM Config):
 
 ```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
+# Pick one (or more for fallback)
+ASD_GOOGLE_API_KEY=your-gemini-key
+ASD_OPENAI_API_KEY=your-openai-key
+ASD_CLAUDE_API_KEY=your-claude-key
+ASD_DEEPSEEK_API_KEY=your-deepseek-key
+
+# Or use local Ollama (no key needed)
+ASD_AI_PROVIDER=ollama
+ASD_AI_MODEL=llama3
 ```
 
-支持的 AI Provider：**Gemini**（推荐）、**OpenAI**、**Claude (Anthropic)**。
-
-### 项目目录结构
+### Project Structure After Setup
 
 ```
 your-project/
-├── AutoSnippet/              # 知识库目录（建议整体作为 Git 子仓库）
-│   ├── recipes/              # Recipe Markdown 导出（Source of Truth）
-│   ├── skills/               # 项目级 Agent Skills
-│   └── .autosnippet/         # 数据库、索引、Guard 配置等
-├── .trae/
-│   ├── rules/                # Trae Rules（从 .cursor/rules/ 镜像）
-│   └── skills/               # Trae Skills（从 .cursor/skills/ 镜像）
-├── .qoder/
-│   ├── rules/                # Qoder Rules（从 .cursor/rules/ 镜像）
-│   └── skills/               # Qoder Skills（从 .cursor/skills/ 镜像）
-├── .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 策略建议
-
-| 路径 | 建议 |
-|------|------|
-| `AutoSnippet/` | **整体作为 Git 子仓库**——独立权限控制，写权限探针（`git push --dry-run`）在此目录执行，仅知识管理员可 push |
-| `AutoSnippet/.autosnippet/context/index/` | 加入 `.gitignore`——体积大、机器相关 |
-
-## 架构概览
-
-```
-┌──────────────────────────────────────────────────────────┐
-│  IDE Layer                                               │
-│  Cursor (Skills + MCP) │ Qoder (Skills + Rules) │ Trae (Skills + Rules + MCP) │ VSCode (Copilot) │ Xcode        │
-└────────────┬────────────────────┬─────────────────────────┘
-             │ MCP (stdio)        │ HTTP API
-┌────────────┴────────────────────┴─────────────────────────┐
-│  AutoSnippet Core                                         │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
-│  │ Gateway  │ │ ChatAgent│ │ Bootstrap│ │  Dashboard  │  │
-│  │ (权限/   │ │ (Dual    │ │ (Incremen│ │  (React 19 +│  │
-│  │  宪法/   │ │  Agent + │ │  tal +   │ │   Vite 6 +  │  │
-│  │  审计)   │ │  Memory) │ │  AST+AI) │ │   Tailwind) │  │
-│  └──────────┘ └──────────┘ └──────────┘ └─────────────┘  │
-│  ┌────────────────────────────────────────────────────┐   │
-│  │  Agent Memory (4-Tier):                            │   │
-│  │  WorkingMemory → EpisodicMemory →                  │   │
-│  │  ProjectSemanticMemory → ToolResultCache           │   │
-│  └────────────────────────────────────────────────────┘   │
-│  ┌────────────────────────────────────────────────────┐   │
-│  │  14 Services: Recipe │ Candidate │ Guard │ Search  │   │
-│  │  Knowledge Graph │ SPM │ Bootstrap │ Chat │ Skills  │   │
-│  │  Quality │ Context │ Automation │ Snippet │ Cursor  │   │
-│  └────────────────────────────────────────────────────┘   │
-│  ┌────────────────────────────────────────────────────┐   │
-│  │  Core: Gateway │ Constitution │ Permission │ AST   │   │
-│  │  Session │ Capability │ CodeEntityGraph             │   │
-│  └────────────────────────────────────────────────────┘   │
-│  ┌────────────────────────────────────────────────────┐   │
-│  │  Storage: SQLite (better-sqlite3) + 向量索引       │   │
-│  │  Search: InvertedIndex → CoarseRanker →            │   │
-│  │          MultiSignalRanker → RetrievalFunnel       │   │
-│  └────────────────────────────────────────────────────┘   │
-└───────────────────────────────────────────────────────────┘
+├── AutoSnippet/           # Core data (git sub-repo = Source of Truth)
+│   ├── constitution.yaml  # Permission rules
+│   ├── recipes/           # Knowledge entries (Markdown)
+│   ├── candidates/        # Pending entries
+│   └── skills/            # Project-specific skills
+├── .autosnippet/          # Runtime (gitignored)
+│   ├── config.json        # Project config
+│   ├── autosnippet.db     # SQLite cache
+│   └── context/           # Vector index cache
+├── .cursor/               # Cursor IDE integration
+│   ├── mcp.json
+│   ├── rules/
+│   └── skills/
+└── .vscode/               # VS Code integration
+    ├── mcp.json           # MCP server config
+    └── extensions.json    # Recommended extensions
 ```
 
-## 技术栈
-
-| 层级 | 技术 |
-|------|------|
-| **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） |
-| **搜索** | 5 层检索管线：InvertedIndex → Semantic Rerank → CoarseRanker (E-E-A-T) → MultiSignalRanker → RetrievalFunnel |
-| **实时通信** | WebSocket（Socket.IO），Dashboard 实时更新 |
-| **动画** | Framer Motion |
-| **代码高亮** | Prism.js + react-syntax-highlighter |
+## Security
 
-## Xcode 深度集成
+- **PathGuard**: 2-layer boundary protection — blocks writes outside project root + whitelist-only allowed paths
+- **Constitution**: 4 inviolable rules enforced on every write operation
+- **Audit Trail**: Full audit logging with 90-day TTL auto-cleanup
+- **No External Calls in postinstall**: Build scripts are purely local (macOS Swift compilation)
+- **Gateway**: Every mutation goes through role verification → constitution check → audit log
 
-AutoSnippet 不依赖 Xcode 插件，通过 **AppleScript + FileWatcher + 原生 macOS UI** 实现深度集成。
+## Requirements
 
-| 能力 | 说明 |
-|------|------|
-| **保存即触发** | 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 生效 |
+- **Node.js** ≥ 20.0.0
+- **macOS** recommended (required for Xcode integration; other platforms work without Xcode features)
+- **SQLite** via better-sqlite3 (bundled)
 
-## 开发
-
-```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       # 补丁版本
-```
+## Contributing
 
-## 贡献
+Contributions are welcome. Please ensure:
 
-欢迎 [Issue](https://github.com/GxFn/AutoSnippet/issues) 与 [PR](https://github.com/GxFn/AutoSnippet/pulls)。
+1. Run `npm test` before submitting
+2. Follow existing code patterns (ESM, domain-driven structure)
+3. Guard rules and knowledge entries go through the standard review process
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE) © gaoxuefeng