autosnippet 1.3.0 → 1.3.2

package/.editorconfig

@@ -1,7 +1,13 @@
 root = true
 
-[*.js]
+[*]
 indent_style = tab
 indent_size = 4
 tab_width = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
 

package/.env.example

@@ -0,0 +1,124 @@
+# AutoSnippet 环境变量配置文件示例
+#
+# 使用方式：
+#   1. 将本文件复制到「项目根目录」（即 AutoSnippetRoot.boxspec.json 所在目录）
+#   2. 重命名为 .env（注意没有 .example 后缀）
+#   3. 根据下方说明填写 API Key 等配置
+# 可从本仓库下载： https://github.com/GxFn/AutoSnippet/blob/main/.env.example
+#
+# 配置生效范围：asd ui、asd create、asd ais、asd watch 的 Guard、asd embed、asd search -m 等
+# 会优先读取项目根目录下的 .env；未配置 API Key 时，上述依赖 AI 的功能会报错或提示。
+#
+# =============================================================================
+# --- 1. AI 提供商配置 ---
+# =============================================================================
+# 必填其一：根据所选提供商填写对应的 API Key；Ollama 本地 AI 通常不需要 Key。
+
+# 当前使用的 AI 提供商
+# 可选值: google, openai, deepseek, claude, ollama, mock
+#   google   - Google Gemini，需填写 ASD_GOOGLE_API_KEY
+#   openai  - OpenAI（含兼容接口），需填写 ASD_OPENAI_API_KEY
+#   deepseek - DeepSeek，需填写 ASD_DEEPSEEK_API_KEY
+#   claude  - Anthropic Claude，需填写 ASD_CLAUDE_API_KEY
+#   ollama  - 本地 Ollama，默认 http://localhost:11434/v1，一般不需 Key
+#   mock    - 模拟模式，用于测试，无真实请求
+ASD_AI_PROVIDER=google
+
+# 模型名称，根据上面 ASD_AI_PROVIDER 选择对应厂商的模型 ID
+# 常用示例：
+#   google:  gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash
+#   openai:  gpt-4o, gpt-4-turbo, gpt-4o-mini
+#   deepseek: deepseek-chat, deepseek-coder
+#   claude:  claude-3-5-sonnet-20240620, claude-3-opus-20240229
+#   ollama:  填写本机已安装的模型名，如 llama3, qwen2, mistral
+ASD_AI_MODEL=gemini-2.0-flash
+
+# 各提供商的 API Key（只填当前使用的提供商即可，其余可留空）
+ASD_GOOGLE_API_KEY=
+ASD_OPENAI_API_KEY=
+ASD_DEEPSEEK_API_KEY=
+ASD_CLAUDE_API_KEY=
+
+# 自定义 API 地址（可选）
+# 适用于：自建代理、国内镜像、或 Ollama 等本地服务不在默认端口时
+# 未设置时使用各厂商官方默认地址
+# ASD_OPENAI_BASE_URL=https://api.openai.com/v1
+# ASD_DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+# ASD_CLAUDE_BASE_URL=https://api.anthropic.com/v1
+# ASD_OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
+
+# =============================================================================
+# --- 2. Dashboard 与构建配置 ---
+# =============================================================================
+
+# 是否在启动 asd ui 时强制重新构建前端（0=否，1=是）
+# 设为 1 时，每次 asd ui 都会先执行 npm run build:dashboard，适合本地改完 dashboard 代码后预览
+# 正常使用保持 0 即可
+ASD_UI_BUILD=0
+ASD_UI_REBUILD=0
+
+# =============================================================================
+# --- 3. 监听与文件系统配置 ---
+# =============================================================================
+
+# 是否使用轮询方式监听文件变化（true / false）
+# 默认 false 使用系统原生 watch；若项目在 NFS、网络盘或部分虚拟机上监听不生效，可改为 true
+ASD_WATCH_POLLING=false
+
+# Xcode Code Snippets 的存储路径（留空则使用默认）
+# 默认: ~/Library/Developer/Xcode/UserData/CodeSnippets
+# asd install 会把 Snippet 同步到此目录，Xcode 从这里加载
+ASD_SNIPPETS_PATH=
+
+# AutoSnippet 缓存目录（留空则使用默认）
+# 用于缓存索引、临时数据等，一般无需修改
+ASD_CACHE_PATH=
+
+# 当工具发现「当前 Target 缺少对某模块的依赖」时，是否自动在 Package.swift 里插入依赖
+# 典型场景：头文件注入（as:include）时，若当前 Target 的 dependencies 里没有对应模块，可自动补上
+# 插入内容包含：同包内 .target 依赖、跨包 .product 依赖、以及 Package 级的 .package(path/url)
+#
+# ASD_FIX_SPM_DEPS：设为 1 或 true 时，启用自动插入（等价于 MODE=fix）
+# ASD_FIX_SPM_DEPS_MODE：更细粒度控制，可选：
+#   off    - 不自动改 Package.swift，仅给出修改建议（默认）
+#   suggest - 同上，仅建议
+#   fix    - 自动在 Package.swift 中插入缺失的 target/product/package 依赖
+# 日常使用建议保持 off；确认需要自动补依赖时再改为 fix
+ASD_FIX_SPM_DEPS=false
+ASD_FIX_SPM_DEPS_MODE=
+
+# Package.swift 解析：npm install 时会尝试构建 ParsePackage（swift-syntax）；成功则默认用它，失败则用 dump-package，再失败用 AST-lite
+# ASD_USE_DUMP_PACKAGE=1（默认）- ParsePackage 不可用时用系统 dump-package；=0 则跳过 dump-package，仅 AST-lite
+# ASD_SWIFT_PARSER_BIN - 指定 ParsePackage 可执行文件路径；未设置时使用 npm install 构建的 tools/parse-package/.build/release/ParsePackage
+# ASD_SWIFT_PARSER_DISABLE=1 - 强制禁用 ParsePackage，仅用 dump-package 或 AST-lite
+# ASD_SWIFT_PARSER_TIMEOUT_MS - 解析超时毫秒数，默认 5000
+# ASD_USE_DUMP_PACKAGE=1
+# ASD_SWIFT_PARSER_BIN=
+# ASD_SWIFT_PARSER_DISABLE=
+# ASD_SWIFT_PARSER_TIMEOUT_MS=5000
+
+# =============================================================================
+# --- 4. 开发与测试配置 ---
+# =============================================================================
+# 以下多为自动化测试或脚本调用时使用，日常使用可忽略。
+
+# 预置输入 JSON 路径，用于非交互式 create 等（自动化/CI）
+ASD_PRESET=
+ASD_TEST_PRESET=
+
+# 测试运行器使用的「模拟项目根目录」，默认指向 ../AutoSnippetTestHome/BiliDiliForTest
+ASD_TEST_HOME=
+
+# AI 提取时指定的源码文件路径（脚本/自动化用）
+ASD_ACODE_FILE=
+
+# 增量测试时传入的变更文件列表，供 test/runner.js --changed 使用
+ASD_TEST_CHANGED_FILES=
+
+# =============================================================================
+# --- 5. 网络代理（可选） ---
+# =============================================================================
+# 访问 Google / OpenAI 等 API 时走代理时设置；仅在有代理需求时取消注释并修改地址。
+
+# https_proxy=http://127.0.0.1:7890
+# http_proxy=http://127.0.0.1:7890

package/README.md

@@ -2,6 +2,8 @@
 
 基于 SPM 的 iOS 模块 Snippet 与 AI 知识库工具。将模块使用示范写入 Xcode CodeSnippets，支持分类检索、头文件注入，以及基于 AI 的知识沉淀与可视化管理。
 
+开发者与 AI 生产的代码，通过人工评审之后沉淀为 Snippet + Recipe 知识库，开发者通过 Snippets 得到标准代码与依赖注入，AI 通过 Recipes 得到标准代码与项目上下文，项目被迅速解构，产出可视化交互的知识库。
+
 [![npm version](https://img.shields.io/npm/v/autosnippet.svg?style=flat-square)](https://www.npmjs.com/package/autosnippet)
 [![npm downloads](https://img.shields.io/npm/dm/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)
@@ -14,19 +16,86 @@
 npm install -g autosnippet
 ```
 
+---
+
 ## 快速开始
 
-在**项目根目录**执行（需能找到 `AutoSnippetRoot.boxspec.json`，没有会自己创建，关键是首次创建一定要在根目录）：
+**项目根目录**：即将在此目录创建 `AutoSnippetRoot.boxspec.json` 的目录（单仓库用仓库根即可）。后续 `asd ui`、编辑器内指令、命令行等均以此目录为基准。
+
+在**你的业务项目根目录**执行：
 
 ```bash
-# 一键初始化
+# 1) 一键初始化（创建 AutoSnippetRoot.boxspec.json 等）
 asd setup
 
-# 启动 Web 管理后台
+# 2) 启动 Web 管理后台（会同时启动 watch，编辑器内指令才会生效）
 asd ui
 ```
 
-浏览器会自动打开 Dashboard，可在 **使用说明** 页查看完整说明。
+**首次运行 `asd ui`** 时，若未检测到 Dashboard 前端，会自动在 AutoSnippet 安装目录执行构建（约 1–2 分钟）。浏览器会自动打开 Dashboard，可在 **使用说明** 页查看完整说明。
+
+### 界面预览
+
+![Dashboard 概览](images/20260131014718_38_167.png)
+
+![依赖关系 / 搜索](images/20260131014843_41_167.png)
+
+![Recipes / 候选](images/20260131014812_40_167.png)
+
+---
+
+## 新项目：AI 扫描 + 人工审核 → 知识库与依赖 → 与 Cursor/AI 形成闭环
+
+新项目在完成「快速开始」后，可按以下方式**用 AI 扫描 + 人工审核**快速组建知识库和依赖关系，再配合 Cursor 与其他 AI 形成闭环：
+
+1. **组建知识库**：在项目根执行 **`asd ais <Target>`** 或 **`asd ais --all`**，对 SPM Target 做批量 AI 扫描；结果进入 Dashboard 的 **Candidates** 页。在 Dashboard 中逐条审核，通过则入库为 Recipe（或 Snippet+Recipe），不需要的删除。反复几轮即可把现有代码中的「标准用法」沉淀到 `Knowledge/recipes/`。
+2. **组建依赖关系**：在项目根执行 **`asd spm-map`**（或 Dashboard 内刷新依赖关系图），生成 `Knowledge/AutoSnippet.spmmap.json`，供后续查阅「谁依赖谁」、模块边界。
+3. **可选：语义索引**：执行 **`asd embed`**，为 Recipes 构建语义向量索引，便于 **as:guard** 语义检索、**as:search** 与 Dashboard 内语义搜索。
+4. **配合 Cursor**：在项目根执行 **`asd install:cursor-skill`**，将 AutoSnippet 的 skills 安装到项目的 `.cursor/skills/`。Cursor Agent 即可获得「项目 Recipe 上下文」「依赖结构」「创建流程」等说明，按项目规范回答与改代码。
+5. **闭环**：日常开发中，用 Cursor 或其他 AI 基于知识库与依赖结构写代码；写完的模块使用代码通过 **`// as:create`** 或 Dashboard **New Recipe** 提交到 web、加入知识库；用 **`// as:guard`** 按知识库做合规审查；插入标准代码可通过 **`// as:search`** 从知识库检索并插入，或通过 Xcode 内 **Snippet 联想（补全）** 获取。知识库与依赖随人工审核和提交持续更新，AI 始终基于最新上下文，形成「扫描 → 审核 → 沉淀 → Cursor/AI 使用 → 再沉淀」的闭环。
+
+---
+
+## 编辑器内指令
+
+在源码中写入以下 **as:** 指令并**保存**，由 **watch** 或 **CLI** 解析执行。**需先运行 `asd watch` 或 `asd ui`**（`asd ui` 会在后台启动 watch），编辑器内指令才会在保存时生效。
+
+| 指令 | 作用 | 触发时机 |
+|------|------|----------|
+| **`// as:create`** | 用剪贴板 + 当前文件路径创建 Recipe，打开 Dashboard | 保存文件后 watch 检测到 |
+| **`// as:guard`** [关键字] | 按知识库（Recipes）用 AI 审查当前文件，结果输出终端 | 保存文件后 watch 检测到 |
+| **`// as:search`** [关键词] | 从知识库检索 Recipe/Snippet 并插入 | 保存后 watch 检测到 |
+| **`// as:include`** &lt;Module/Header.h&gt; [path] | Snippet 体内的头文件标记，watch 在文件头部注入 `#import` | 保存文件后 watch 检测到 |
+| **`// as:import`** ModuleName | Snippet 体内的 Swift 模块导入标记，watch 注入 `import` | 保存文件后 watch 检测到 |
+
+### // as:create
+
+在源码中写一行 **`// as:create`**，把要沉淀的代码**复制到剪贴板**，保存文件。watch 检测到后会**打开 Dashboard** 并带当前文件路径；若剪贴板有内容，会走「Use Copied Code」流程并自动解析头文件。适合：在编辑器里写完模块使用代码后，直接提交到 web、加入知识库。
+
+### // as:guard
+
+在源码中写 **`// as:guard`** 或 **`// as:guard 关键字`**，保存文件。watch 会按 **知识库（Recipes）** 用 AI 审查当前文件是否符合项目规范，**结果输出到终端**。若已执行 `asd embed`，会优先用语义检索选取相关 Recipe。
+
+### // as:search
+
+在源码中写 **`// as:search`** 或 **`// as:search 关键词`**，保存文件。watch 检测到后会**打开 Dashboard**，展示从知识库（Recipes）中按关键词检索到的候选；不写关键词则展示全部。在列表中点选一条 Recipe 并点击「插入」，该 Recipe 的代码块会**替换当前行**（即 `// as:search` 所在行）并写回文件，实现「选即插」。插入标准代码也可在 Xcode 中通过 **Snippet 联想（trigger 补全）** 直接选用已同步的 Snippet。
+
+### // as:include 与 // as:import（头文件/模块标记）
+
+用于 **Snippet 体内**（写入 `.codesnippet` 的 body），表示插入该 Snippet 时需要的头文件/模块；**watch** 在用户保存文件时，会在**文件头部**自动注入对应的 `#import` 或 `import`。
+
+- **ObjC 头文件**：`// as:include <ModuleName/Header.h> [相对路径]`
+- **Swift**：`// as:import ModuleName`
+
+保存时可勾选「引入头文件」，会写入上述标记；在项目根运行 `asd watch`（或 `asd ui`）后，在 Xcode 中选中 Snippet 的 headerVersion 并保存，即可在文件头部注入依赖。
+
+---
+
+## 术语
+
+- **Snippet**：写入 Xcode 的代码片段，通过 trigger（补全键）或库面板使用。
+- **Recipe（配方）**：存放在 `Knowledge/recipes/` 下的 Markdown 知识，供 AI 检索、Guard 审查与搜索。
+- **项目根**：含 `AutoSnippetRoot.boxspec.json` 的目录。
 
 ---
 
@@ -37,143 +106,103 @@ asd ui
 | 提供商 | 默认模型 | 说明 |
 |--------|----------|------|
 | **Google Gemini** | `gemini-2.0-flash` | 用于 Snippet 提取、摘要、RAG 问答等 |
-
-当前仅支持 **Google Gemini**。`asd create`、`asd ais`、Dashboard 的「按路径/剪贴板创建」与 AI Assistant 均使用该模型。
+| **OpenAI** | `gpt-4o` | 支持 OpenAI 标准接口 |
+| **DeepSeek** | `deepseek-chat` | 深度求索系列模型 |
+| **Anthropic Claude** | `claude-3-5-sonnet-20240620` | 支持 Claude 系列模型 |
+| **Ollama** | `llama3` | **本地 AI 支持**，默认地址 `http://localhost:11434/v1` |
 
 ### 配置指南
 
 **1. 必填：API Key**
 
-在 [Google AI Studio](https://aistudio.google.com/) 申请 API Key，然后通过环境变量传入（勿写入仓库）：
+在**项目根目录**创建 `.env` 文件（可复制 `.env.example`），或通过环境变量传入 API Key：
 
 ```bash
-export ASD_GOOGLE_API_KEY="你的 API Key"
+export ASD_GOOGLE_API_KEY="你的 API Key"   # 或 ASD_OPENAI_API_KEY、ASD_DEEPSEEK_API_KEY、ASD_CLAUDE_API_KEY
 ```
 
-或在项目根目录创建 `.env` 文件（已加入 `.gitignore`，勿提交）：
+在项目根执行 `asd ai-test` 可验证当前配置是否可用。未配置时，依赖 AI 的功能会报错或提示。
 
-```bash
-# .env
-ASD_GOOGLE_API_KEY=你的API_Key
-```
+**2. 可选**：`ASD_AI_PROVIDER`、`ASD_AI_MODEL`、各提供商 `_BASE_URL` 等，见项目内 `.env.example`。
 
-**2. 可选：模型与提供商**
+**3. 可选：代理**：设置 `https_proxy` / `http_proxy` 访问外网 API。国内直连 Google/OpenAI 易失败，建议在 `.env` 中配置代理（如 `https_proxy=http://127.0.0.1:7890`）或改用国内可用的 `ASD_AI_PROVIDER=deepseek` 等。
 
-| 环境变量 | 说明 | 默认值 |
-|----------|------|--------|
-| `ASD_GOOGLE_API_KEY` | Google Gemini API Key（必填） | — |
-| `ASD_AI_PROVIDER` | 提供商，目前仅 `google` | `google` |
-| `ASD_AI_MODEL` | 模型名 | `gemini-2.0-flash` |
+**4. 若出现 `TypeError: fetch failed`**：多为网络/代理问题。请确认：① 在**项目根**（含 `AutoSnippetRoot.boxspec.json` 和 `.env`）执行 `asd ui`，确保 `.env` 被加载；② 国内使用 Google 时在 `.env` 中设置 `https_proxy` 与 `http_proxy`，并保证代理进程可用；③ 或改用 DeepSeek/OpenAI 等，在 `.env` 中设置 `ASD_AI_PROVIDER=deepseek` 并配置 `ASD_DEEPSEEK_API_KEY`。
 
-示例：使用 Pro 模型
+**5. 切换 DeepSeek 后报「API Key is missing for provider: deepseek」**：说明当前已使用 deepseek（可能来自 boxspec 的 `ai.provider` 或 `.env` 的 `ASD_AI_PROVIDER`），但**项目根** `.env` 里未配置 Key。请在**项目根**（即运行 `asd ui` 的目录）的 `.env` 中增加一行：`ASD_DEEPSEEK_API_KEY=你的DeepSeek密钥`，保存后重启 `asd ui`。Key 仅从项目根 `.env` 读取，不会用 AutoSnippet 安装目录下的 `.env`。
 
-```bash
-export ASD_AI_MODEL="gemini-1.5-pro"
-```
+---
+
+## Cursor 集成
 
-**3. 可选：代理**
+若使用 [Cursor](https://cursor.com) 编辑项目，可将 AutoSnippet 自带的 skills 安装到**当前项目**的 Cursor 环境（项目根 `.cursor/skills/`），让 Agent 识别 Recipe、知识库与创建流程。
 
-若需走代理访问 Google API，可设置：
+在**项目根目录**执行：
 
 ```bash
-export https_proxy="http://127.0.0.1:7890"
-# 或
-export http_proxy="http://127.0.0.1:7890"
+asd install:cursor-skill
 ```
 
+或 `npm run install:cursor-skill`（在 AutoSnippet 安装目录）。安装后重启 Cursor 或新开 Agent 对话即可生效。升级 AutoSnippet 后重新执行可更新 skill 内容。
+
 ---
 
 ## Web Dashboard（asd ui）
 
-启动后访问 `http://localhost:3000`，主要能力：
+启动后访问 `http://localhost:3000`。**若已运行 `asd ui`，watch 会在后台启动，编辑器内指令（as:create、as:guard、头文件注入等）在保存时生效。**
+
+- **macOS**：再次运行 `asd ui` 会复用已有 `localhost:3000` 标签并聚焦（Chromium 系浏览器）。
 
 | 页面 | 说明 |
 |------|------|
 | **Snippets** | 查看、编辑、删除代码片段；同步到 Xcode |
-| **Knowledge Base** | 管理 Markdown 技术文档（Skills），与 Snippet 关联 |
-| **SPM Explorer** | 按 Target 扫描源码，AI 提取候选；从路径/剪贴板创建知识 |
+| **Recipes** | 管理配方（Recipes）文档，与 Snippet 关联 |
+| **SPM Explorer** | 按 Target 扫描源码，AI 提取候选；从路径/剪贴板创建 Recipe |
 | **Candidates** | 审核 CLI 批量扫描（`asd ais`）产生的候选，入库或忽略 |
-| **AI Assistant** | 基于本地 Snippets/Skills 的 RAG 问答 |
-| **使用说明** | 本说明的 Web 版，随 Dashboard 常驻 |
-
-### 新建知识（与 CLI 对齐）
+| **依赖关系图** | 展示 SPM 包依赖（packages + edges） |
+| **AI Assistant** | 基于本地 Snippets/Recipes 的 RAG 问答 |
+| **使用说明** | 本说明的 Web 版 |
 
-- **按路径**：输入相对路径（如 `Sources/MyMod/Foo.m`）→ 扫描文件，AI 提取标题/摘要/触发键/头文件，审核后保存。
-- **按剪贴板**：复制代码后点击「Use Copied Code」→ AI 分析并填充；若由 `// as:create` 打开会带当前文件路径，自动解析头文件。
+### 新建 Recipe
 
-### 头文件与标记
-
-保存时可勾选「引入头文件」。会写入 `// as:include <TargetName/Header.h> path` 等标记，配合 `asd watch` 在编辑时自动注入 `#import`。
+- **按路径**：输入相对路径（如 `Sources/MyMod/Foo.m`）→ **Scan File** → AI 提取标题/摘要/触发键/头文件，审核后保存到 `Knowledge/recipes/`。
+- **按剪贴板**：复制代码后点击 **Use Copied Code** → AI 分析并填充；若由 `// as:create` 打开会带当前文件路径，自动解析头文件。
 
 ---
 
 ## 命令行
 
-### 常用
+以下命令均在**项目根目录**执行。**编辑器内指令**已在上文优先说明；此处为 CLI 能力速查与补充。
+
+### 常用命令
 
 | 命令 | 说明 |
 |------|------|
-| `asd ui` | 启动 Web Dashboard |
-| `asd create` | 从带 `// as:code` 的文件用 **AI** 提取并创建 Snippet（默认 AI 模式） |
-| `asd create --clipboard` | 从剪贴板用 **AI** 创建；可选 `--path 相对路径` 解析头文件 |
-| `asd create --no-ai` | 关闭 AI，使用传统交互/预置输入 |
+| `asd ui` | 启动 Web Dashboard（并后台启动 watch，使编辑器内指令生效） |
+| `asd watch` / `asd w` | 仅启动 watch，不打开浏览器；用于头文件注入、`// as:create`、`// as:guard` |
+| `asd create --clipboard` | 从剪贴板用 AI 创建 Snippet；可选 `--path`、`--lang` |
+| `asd create` | 从带 `// as:code` 的文件用 AI 提取并创建 Snippet |
 | `asd install` / `asd i` | 将 Snippets 同步到 Xcode |
-| `asd ais [Target]` | AI 扫描 SPM Target，结果进 Candidates，在 Dashboard 审核 |
-| `asd watch` / `asd w` | 监听源码，执行头文件注入、ALink、`// as:create` 等 |
+| `asd ais [Target]` / `asd ais --all` | AI 扫描 SPM Target，结果进 Candidates，在 Dashboard 审核 |
+| `asd search [keyword]` | 关键词搜索 Snippets 与 Recipes；加 `-m` 为语义搜索（需先 `asd embed`） |
+| `asd embed` | 重建语义索引；语义搜索与 Guard 语义检索依赖此命令 |
+| `asd install:cursor-skill` | 将 AutoSnippet skills 安装到项目 `.cursor/skills/` |
 
-### create 详解
+### create 补充
 
-**AI 模式（默认，与 Web 一致）：**
+- **剪贴板**：`asd create --clipboard`，可选 `asd create --clipboard --path Sources/MyMod/Foo.m`、`--lang swift`。
+- **从文件**：源码中用 `// as:code` 包裹要提炼的片段，再执行 `asd create` 并选择该文件。
+- **传统模式**：`asd create --no-ai`、`asd --preset preset.json create`。
 
-```bash
-# 从文件：选中含 // as:code 的文件，AI 分析代码并带头文件
-asd create
-
-# 从剪贴板
-asd create --clipboard
-asd create -p --path Sources/MyMod/Foo.m   # 带头文件解析
-asd create --clipboard --lang swift
-```
+### 其他命令
 
-**传统模式（预置或交互）：**
-
-```bash
-asd create --no-ai
-asd --preset preset.json create
-```
-
-**文件内标记：**
-
-```text
-// as:code
-UIView *view = [[UIView alloc] init];
-// as:code
-```
-
-### ai-scan（Candidates）
-
-```bash
-asd ais <TargetName>      # 扫描单个 Target
-asd ais --all             # 扫描全部
-asd ais --batch 5         # 每批 5 个未扫描的 Target
-```
-
-结果写入 `Knowledge/.autosnippet/candidates.json`，在 Dashboard **Candidates** 页审核后入库或删除。
-
-### watch 监听
-
-- **头文件注入**：在 Xcode 中选中 Snippet 的 headerVersion，保存后自动在文件头部插入对应 `#import`。
-- **ALink**：输入 `#模块键#ALink` 并保存，可打开配置的链接或 README。
-- **// as:create**：在源码中写一行 `// as:create`，复制要提炼的代码到剪贴板并保存；watch 会打开 Dashboard 并带当前文件路径，用剪贴板 + 路径创建（自动解析头文件）。
-
-### 标记格式
-
-- ObjC 头文件：`// as:include <ModuleName/Header.h> [相对路径]`
-- Swift：`// as:import ModuleName`
-
----
+- `asd setup`：等价于 init + root，推荐在单仓库根执行一次。
+- `asd root`：在当前目录创建/更新项目根标记（`AutoSnippetRoot.boxspec.json`）。
+- `asd init`：在 SPM 模块目录创建模块工作空间。
+- `asd share`：共享本地 Snippet。
+- `asd u <word> [key] [value]`：按 trigger 更新 Snippet 字段。
 
-## 全局选项
+### 全局选项
 
 - `--preset <path>`：预置输入 JSON（非交互/自动化）。
 - `--yes`：非交互；缺必要输入则报错退出。
@@ -181,19 +210,9 @@ asd ais --batch 5         # 每批 5 个未扫描的 Target
 
 ---
 
-## 其他命令
-
-- `asd root`：在项目根创建/更新工作空间，聚合子模块 Snippet。
-- `asd init`：在 SPM 模块目录创建模块工作空间。
-- `asd setup`：等价于 `init` + `root`。
-- `asd share`：共享本地 Snippet。
-- `asd u <word> [key] [value]`：按 trigger 更新 Snippet 字段。
-
----
-
-## 占位符
+## install 之后
 
-在 Snippet 代码中使用 `<#placeholder#>`，Xcode 会识别为占位符，用 Tab 切换。多相同占位符可用 ⌥⌘E 连续选择后统一修改。
+执行 `asd install` 后，Snippets 会同步到 Xcode 的 **Code Snippets** 库。在 Xcode 中通过触发词（completion）或库面板使用；若未生效可尝试重启 Xcode。Snippet 代码中可使用 `<#placeholder#>`，Xcode 会识别为占位符，用 Tab 切换。
 
 ---
 
@@ -203,4 +222,4 @@ asd ais --batch 5         # 每批 5 个未扫描的 Target
 
 ## 许可证
 
-MIT，见 [LICENSE](LICENSE)。
+MIT，见 [LICENSE](LICENSE).