autosnippet 1.2.17 → 1.3.0

package/README.md

@@ -1,267 +1,206 @@
 # AutoSnippet
 
-基于 SPM 的 iOS 模块 Snippet 工具。通过 AutoSnippet 可以把模块的使用示范写进 Xcode 的 CodeSnippets，并支持分类检索、链接跳转与（可选）依赖头文件注入。
+基于 SPM 的 iOS 模块 Snippet 与 AI 知识库工具。将模块使用示范写入 Xcode CodeSnippets，支持分类检索、头文件注入，以及基于 AI 的知识沉淀与可视化管理。
 
 [![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)
-[![npm total downloads](https://img.shields.io/npm/dt/autosnippet.svg?style=flat-square)](https://www.npmjs.com/package/autosnippet)
-[![GitHub stars](https://img.shields.io/github/stars/GxFn/AutoSnippet.svg?style=flat-square)](https://github.com/GxFn/AutoSnippet)
-[![GitHub forks](https://img.shields.io/github/forks/GxFn/AutoSnippet.svg?style=flat-square)](https://github.com/GxFn/AutoSnippet)
 [![License](https://img.shields.io/npm/l/autosnippet.svg?style=flat-square)](https://github.com/GxFn/AutoSnippet/blob/main/LICENSE)
 
-## 使用
-
-模块开发者提供了Toast模块，可以将这一段使用代码写入模块的配置文件（参照下文命令）
-
-```objectivec
-[[ASUIKitAlertToast sharedInstance] alertWithMessage:@"<#object#>"];
-```
-
-模块被工程引入时，业务开发者可以在Xcode里，敲击`@toast`来获取这段标准的使用代码
-
-Toast模块添加配置时可以选择分类，使用者可以通过`@view`或者`@tool`联想出同类别模块列表
-
-代码量大的UI模块，能一键获取全部标准代码
+---
 
 ## 安装
 
 ```bash
-$ npm install -g autosnippet
+npm install -g autosnippet
 ```
 
 ## 快速开始
 
-建议在**项目根目录**执行（能找到 `AutoSnippetRoot.boxspec.json`）。
+在**项目根目录**执行（需能找到 `AutoSnippetRoot.boxspec.json`，没有会自己创建，关键是首次创建一定要在根目录）：
 
 ```bash
-# 1) 一键初始化（等价于 init + root）
+# 一键初始化
 asd setup
 
-# 2) 在代码里用新标记圈出 snippet 内容，然后创建
-asd create
-
-# 3) 安装到 Xcode CodeSnippets
-asd install
-
-# 4) 开启监听（用于头文件注入/依赖补齐/ALink 跳转）
-asd watch
+# 启动 Web 管理后台
+asd ui
 ```
 
-## 全局选项（推荐）
+浏览器会自动打开 Dashboard，可在 **使用说明** 页查看完整说明。
+
+---
 
-- **`--preset <path>`**：指定预置输入（非交互/自动化最常用）。
-- **`--yes`**：非交互模式；缺少必要输入会直接报错退出。
+## AI 支持与配置
 
-也支持环境变量（方便 CI / 测试脚本）：
+### 当前支持的 AI
 
-- **`ASD_PRESET` / `ASD_TEST_PRESET`**：预置输入 json 路径（优先级低于 `--preset`）
+| 提供商 | 默认模型 | 说明 |
+|--------|----------|------|
+| **Google Gemini** | `gemini-2.0-flash` | 用于 Snippet 提取、摘要、RAG 问答等 |
 
-## 命令
+当前仅支持 **Google Gemini**。`asd create`、`asd ais`、Dashboard 的「按路径/剪贴板创建」与 AI Assistant 均使用该模型。
 
-请在当前 Xcode 项目文件目录下使用以下所有命令。
+### 配置指南
 
-### root
+**1. 必填：API Key**
 
-在 Xcode 项目的根目录执行此命令以创建工作空间：
+在 [Google AI Studio](https://aistudio.google.com/) 申请 API Key，然后通过环境变量传入（勿写入仓库）：
 
 ```bash
-$ asd root
+export ASD_GOOGLE_API_KEY="你的 API Key"
 ```
 
-创建工作空间时，会将子工作空间的 Snippet 配置信息收集到当前工作空间。
-
-### init
-
-在 Xcode 项目的spm模块目录执行此命令以创建模块工作空间：
+或在项目根目录创建 `.env` 文件（已加入 `.gitignore`，勿提交）：
 
 ```bash
-$ asd init
+# .env
+ASD_GOOGLE_API_KEY=你的API_Key
 ```
 
-### setup（推荐）
+**2. 可选：模型与提供商**
 
-初始化快捷命令，等价于 `asd init` + `asd root`：
+| 环境变量 | 说明 | 默认值 |
+|----------|------|--------|
+| `ASD_GOOGLE_API_KEY` | Google Gemini API Key（必填） | — |
+| `ASD_AI_PROVIDER` | 提供商，目前仅 `google` | `google` |
+| `ASD_AI_MODEL` | 模型名 | `gemini-2.0-flash` |
+
+示例：使用 Pro 模型
 
 ```bash
-$ asd setup
+export ASD_AI_MODEL="gemini-1.5-pro"
 ```
 
-### create
+**3. 可选：代理**
 
-创建 Xcode 代码片段（支持从文件标记提取，或直接从剪贴板生成）。
+若需走代理访问 Google API，可设置：
 
 ```bash
-$ asd create
-# 或短别名
-$ asd c
+export https_proxy="http://127.0.0.1:7890"
+# 或
+export http_proxy="http://127.0.0.1:7890"
 ```
 
-#### 从文件标记提取
+---
 
-在任意 `.m/.h/.swift` 文件中使用标记圈出代码块（推荐短写法）：
+## Web Dashboard（asd ui）
 
-```
-// as:code
-UIView *view = [[UIView alloc] init];
-// as:code
-```
+启动后访问 `http://localhost:3000`，主要能力：
 
-然后在该文件所在目录（或通过 preset 指定文件）执行 `asd create`。
+| 页面 | 说明 |
+|------|------|
+| **Snippets** | 查看、编辑、删除代码片段；同步到 Xcode |
+| **Knowledge Base** | 管理 Markdown 技术文档（Skills），与 Snippet 关联 |
+| **SPM Explorer** | 按 Target 扫描源码，AI 提取候选；从路径/剪贴板创建知识 |
+| **Candidates** | 审核 CLI 批量扫描（`asd ais`）产生的候选，入库或忽略 |
+| **AI Assistant** | 基于本地 Snippets/Skills 的 RAG 问答 |
+| **使用说明** | 本说明的 Web 版，随 Dashboard 常驻 |
 
-#### 从剪贴板创建
+### 新建知识（与 CLI 对齐）
 
-```bash
-# 默认按 objc 处理
-asd create --clipboard
+- **按路径**：输入相对路径（如 `Sources/MyMod/Foo.m`）→ 扫描文件，AI 提取标题/摘要/触发键/头文件，审核后保存。
+- **按剪贴板**：复制代码后点击「Use Copied Code」→ AI 分析并填充；若由 `// as:create` 打开会带当前文件路径，自动解析头文件。
 
-# 短写法
-asd c -p
+### 头文件与标记
 
-# Swift
-asd create --clipboard --lang swift
-```
+保存时可勾选「引入头文件」。会写入 `// as:include <TargetName/Header.h> path` 等标记，配合 `asd watch` 在编辑时自动注入 `#import`。
 
-### install
+---
 
-将共享的代码片段添加到 Xcode 环境：
+## 命令行
 
-```bash
-$ asd install
-# 或短别名
-$ asd i
-```
+### 常用
 
-使用代码片段示例：
+| 命令 | 说明 |
+|------|------|
+| `asd ui` | 启动 Web Dashboard |
+| `asd create` | 从带 `// as:code` 的文件用 **AI** 提取并创建 Snippet（默认 AI 模式） |
+| `asd create --clipboard` | 从剪贴板用 **AI** 创建；可选 `--path 相对路径` 解析头文件 |
+| `asd create --no-ai` | 关闭 AI，使用传统交互/预置输入 |
+| `asd install` / `asd i` | 将 Snippets 同步到 Xcode |
+| `asd ais [Target]` | AI 扫描 SPM Target，结果进 Candidates，在 Dashboard 审核 |
+| `asd watch` / `asd w` | 监听源码，执行头文件注入、ALink、`// as:create` 等 |
 
-```
-// view 是创建时输入的代码键
-@view 
-```
+### create 详解
 
-### share
-
-共享本地代码片段：
+**AI 模式（默认，与 Web 一致）：**
 
 ```bash
-$ asd share
-# 或短别名
-$ asd s
-```
-
-### update
-
-更新已创建的 snippet（按 trigger 查找，例如 `cover` 或 `@cover`）：
-
-```bash
-asd update <word> [key] [value]
-# 或短别名
-asd u <word> [key] [value]
-```
-
-### watch
-
-在模块化项目中监听文件变更，识别 `autosnippet:*` 指令并执行：
-- 头文件注入（ObjC `#import` / Swift `import`）
-- ALink 跳转
--（可选）SPM 依赖自动补齐（见下文）
+# 从文件：选中含 // as:code 的文件，AI 分析代码并带头文件
+asd create
 
-```bash
-$ asd watch
-# 或短别名
-$ asd w
+# 从剪贴板
+asd create --clipboard
+asd create -p --path Sources/MyMod/Foo.m   # 带头文件解析
+asd create --clipboard --lang swift
 ```
 
-常用参数：
+**传统模式（预置或交互）：**
 
 ```bash
-# 只监听某个子目录/文件/后缀
-asd watch --path Services/Services/ASNetworkCheck --ext m,h
-asd watch --file ./Services/Services/ASNetworkCheck/Code/ASSimplePing.m
-
-# 降噪/退出时打印汇总
-asd watch --quiet --summary
+asd create --no-ai
+asd --preset preset.json create
 ```
 
-#### 追加头文件
-
-开启监听后，如果想要追加头文件，请执行以下操作：
-
-1. 向下箭头选择代码片段的 headerVersion
-2. 按 `Enter` 键
-3. `Command + S` 保存文件
-
-在 1 秒内，头文件会自动添加到文件头部。
+**文件内标记：**
 
-#### 新指令格式（重要）
-
-- ObjC / C / C++：注入头文件
-
-```
-// as:include <ModuleName/Header.h> [optional/relative/path/Header.h]
+```text
+// as:code
+UIView *view = [[UIView alloc] init];
+// as:code
 ```
 
-- Swift：注入 import
+### ai-scan（Candidates）
 
+```bash
+asd ais <TargetName>      # 扫描单个 Target
+asd ais --all             # 扫描全部
+asd ais --batch 5         # 每批 5 个未扫描的 Target
 ```
-// as:import ModuleName
-```
-
-#### 浏览器查看
 
-开启监听后，如果想要在浏览器中查看模块的更多信息，请执行以下操作：
+结果写入 `Knowledge/.autosnippet/candidates.json`，在 Dashboard **Candidates** 页审核后入库或删除。
 
-1. 输入 `@` 和 `模块键`
-2. 输入 `#` 和 `ALink`
-3. `Command + S` 保存文件
+### watch 监听
 
-会自动跳转到浏览器打开创建时配置的链接，如果没有链接则打开 README.md 文件。
+- **头文件注入**：在 Xcode 中选中 Snippet 的 headerVersion，保存后自动在文件头部插入对应 `#import`。
+- **ALink**：输入 `#模块键#ALink` 并保存，可打开配置的链接或 README。
+- **// as:create**：在源码中写一行 `// as:create`，复制要提炼的代码到剪贴板并保存；watch 会打开 Dashboard 并带当前文件路径，用剪贴板 + 路径创建（自动解析头文件）。
 
-使用 ALink 示例：
+### 标记格式
 
-```
-@view#ALink
-```
+- ObjC 头文件：`// as:include <ModuleName/Header.h> [相对路径]`
+- Swift：`// as:import ModuleName`
 
-## SPM 依赖自动补齐（可选）
+---
 
-当 `watch` 触发跨 target 引用时，AutoSnippet 可以（按配置）检查/补齐 `Package.swift` 里的依赖关系（target / product / package）。
+## 全局选项
 
-- 开关：通过环境变量控制
-  - **`ASD_FIX_SPM_DEPS_MODE=off`**：只提示（默认行为）
-  - **`ASD_FIX_SPM_DEPS_MODE=suggest`**：输出可复制的补丁建议
-  - **`ASD_FIX_SPM_DEPS_MODE=fix`**：直接修改 `Package.swift` 自动补齐
+- `--preset <path>`：预置输入 JSON（非交互/自动化）。
+- `--yes`：非交互；缺必要输入则报错退出。
+- 环境变量：`ASD_PRESET` / `ASD_TEST_PRESET` 指定预置路径。
 
-- 跨包 product/package 依赖需要映射文件（项目内维护）：
-  - `AutoSnippet.spmmap.json`
+---
 
-## 其他
+## 其他命令
 
-### 占位符快捷键
+- `asd root`：在项目根创建/更新工作空间，聚合子模块 Snippet。
+- `asd init`：在 SPM 模块目录创建模块工作空间。
+- `asd setup`：等价于 `init` + `root`。
+- `asd share`：共享本地 Snippet。
+- `asd u <word> [key] [value]`：按 trigger 更新 Snippet 字段。
 
-您也可以在代码片段中添加占位符，使用以下标签：
-
-```
-<#placeholder#>
-```
-
-例如：上面的占位符可以写成：
-
-```
-<#view: UIView#>
-```
+---
 
-Xcode 会检测 `<#` 和 `#>` 标记，并将它们之间的文本作为占位符。我们可以通过按 `Tab` 键在多个占位符之间切换。
+## 占位符
 
-当有多个相同的占位符时，使用 `⌥⌘E` 连续选择多个占位符：
+在 Snippet 代码中使用 `<#placeholder#>`，Xcode 会识别为占位符，用 Tab 切换。多相同占位符可用 ⌥⌘E 连续选择后统一修改。
 
-1. 选择一个占位符
-2. `⌥⌘E` 选择下一个占位符，`⌥⇧⌘E` 选择上一个占位符
-3. 输入修改的内容，所有选中的占位符都会被修改
+---
 
-## 📝 贡献
+## 贡献
 
-欢迎提交 Issues 和 Pull Requests 来帮助改进 AutoSnippet！
+欢迎提交 Issue 与 Pull Request。
 
-## 📄 许可证
+## 许可证
 
-本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。
+MIT，见 [LICENSE](LICENSE)。