autosnippet 1.5.9 → 1.6.2

package/README.md

@@ -20,15 +20,30 @@
 
 ## 安装与快速开始
 
+### 1. 安装 AutoSnippet
+
 ```bash
 npm install -g autosnippet
 ```
 
-在**项目根目录**执行：
+### 2. 在你的项目中初始化
+
+**重要**：在**你的项目目录**（不是 AutoSnippet 源码目录）执行：
+
+```bash
+cd /path/to/your-project   # 进入你的项目
+
+asd setup                  # 一键初始化
+                           # ✅ 创建 AutoSnippet/ 目录和配置
+                           # ✅ 自动配置 VSCode (.vscode/settings.json)
+                           # ✅ 自动配置 Cursor (.cursor/mcp.json)
+                           # ✅ 放置 Recipe 模板
+```
+
+### 3. 启动 Dashboard
 
 ```bash
-asd setup      # 初始化
-asd ui         # 启动 Dashboard（建议常驻）
+asd ui                     # 启动 Dashboard + watch
 ```
 
 `asd ui` 会启动 Web 管理后台并后台 watch；首次运行若前端不存在会自动构建。浏览器会自动打开 Dashboard。
@@ -39,7 +54,7 @@ asd ui         # 启动 Dashboard（建议常驻）
 
 1. **组建知识库**：`asd ais <Target>` 或 `asd ais --all` → Dashboard Candidates 审核 → Recipe 入库
 2. **依赖关系**：`asd spm-map` 或 Dashboard 刷新
-3. **Cursor 集成**：`asd install:cursor-skill --mcp`（安装 Skills + Cursor 规则 `.cursor/rules/` + MCP，需 `asd ui` 运行）
+3. **Cursor 集成**：`asd install:cursor-skill --mcp`（安装 Skills + Cursor 规则 `.cursor/rules/` + MCP；MCP 工具使用时需 `asd ui` 运行）
 4. **语义索引**：`asd ui` 启动时自动 embed；也可手动 `asd embed`
 
 ### 闭环
@@ -57,7 +72,7 @@ asd ui         # 启动 Dashboard（建议常驻）
 | 指令 | 作用 |
 |------|------|
 | `// as:create` / `// as:c` | 无选项时只打开 Dashboard（路径已填），由用户点 Scan File 或 Use Copied Code。`-c` 强制用剪切板（静默创建或打开）；`-f` 强制用路径（打开 Dashboard 并自动执行 Scan File） |
-| `// as:guard` / `// as:g` [关键词或规模] | 按知识库 AI 审查；无后缀时仅检查当前文件；后缀 **file** / **target** / **project** 可扩大范围（target=当前 Target 内所有源文件，project=项目内所有源文件）；其他为检索关键词 |
+| `// as:audit` / `// as:a` [关键词或规模] | 按知识库 AI 审查；无后缀时仅检查当前文件；后缀 **file** / **target** / **project** 可扩大范围（target=当前 Target 内所有源文件，project=项目内所有源文件）；其他为检索关键词 |
 | `// as:search` / `// as:s` [关键词] | 从知识库检索并插入 Recipe/Snippet |
 | `// as:include` / `// as:import` | Snippet 内头文件/模块标记，保存时自动注入 |
 
@@ -68,17 +83,17 @@ asd ui         # 启动 Dashboard（建议常驻）
 
 | 命令 | 说明 |
 |------|------|
-| `asd setup` | 初始化项目根（创建 AutoSnippetRoot.boxspec.json） |
+| `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 install` / `asd i` | 同步 Snippets 到 Xcode |
+| `asd extract` / `asd e` | 同步 Snippets 到 Xcode |
 | `asd ais [Target]` | AI 扫描 Target → Candidates |
 | `asd search [keyword] --copy` | 搜索并复制第一条到剪贴板 |
 | `asd search [keyword] --pick` | 交互选择后复制/插入 |
 | `asd install:cursor-skill --mcp` | 安装 Skills、Cursor 规则（`.cursor/rules/*.mdc`）并配置 MCP。配置时可运行；MCP 工具使用时需 `asd ui` 已启动 |
-| `asd install:full` | 全量安装；`--parser` 含 Swift 解析器；`--lancedb` 仅 LanceDB |
+| `asd install:full` | 全量安装；`--parser` 含 Swift 解析器 |
 | `asd embed` | 手动构建语义向量索引（`asd ui` 启动时也会自动执行） |
 | `asd spm-map` | 刷新 SPM 依赖映射（依赖关系图数据来源） |
 
@@ -86,24 +101,23 @@ asd ui         # 启动 Dashboard（建议常驻）
 
 除 `asd ais [Target]`（项目内 AI）外，可用 **Cursor 作为批量扫描工具**：在 Cursor 里让 Agent 通过 **MCP 工具**（`autosnippet_get_targets` → `autosnippet_get_target_files` → 按文件提取 → `autosnippet_submit_candidates`）扫描指定 Target，用 Cursor 模型提取候选并提交到 Dashboard，再到 **Candidates** 页审核入库。
 
-简单一句：「扫描 BDNetwork ，生成 Recipes 到候选」。AutoSnippet 将所有能力都通过语义交给 Cursor 了。
+简单一句：「扫描 BDNetwork ，生成 Recipes 到候选」。话又说回来，最好还是详细点，先候选一两个文件，确认 cursor 认清字段，就可以在当前会话多文件执行了。
+
+## 可选依赖
 
-## 全量安装与可选依赖
+### Swift 解析器（可选）
 
-克隆或需完整能力时，**任意目录**执行：
+AutoSnippet 默认使用 `swift package dump-package` 解析 SPM 依赖。如需更准确的解析，可安装 Swift 解析器：
 
 ```bash
-asd install:full           # 核心 + 可选依赖 + Dashboard（前端不存在时构建）
-asd install:full --parser  # 上述 + Swift 解析器（ParsePackage，SPM 解析更准确）
-asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
+npm run build:parser       # 构建 ParsePackage（需本机已安装 Swift）
 ```
 
-**Swift 解析器**：默认回退 `dump-package`；`--parser` 构建 ParsePackage 后 SPM 解析更准确，需本机已装 Swift。
+构建后会在 `tools/parse-package/.build/release/` 生成解析器，SPM 解析将更准确可靠。未安装时自动回退到 `dump-package`，功能正常。
 
 ## 配置
 
 - **AI**：项目根 `.env`，参考 `.env.example` 配置 `ASD_GOOGLE_API_KEY` 等。可选 `ASD_AI_PROVIDER`、代理等。
-- **LanceDB**：`asd install:full --lancedb`，在 boxspec 的 `context.storage.adapter` 中配置 `"lance"`。
 - **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)。
 
@@ -111,13 +125,13 @@ asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
 
 | 术语 | 说明 |
 |------|------|
-| **Recipe** | `Knowledge/recipes/` 下的 Markdown 知识（配方）：含代码块 + 使用说明，供 AI 检索、Guard、搜索 |
+| **Recipe** | `AutoSnippet/recipes/` 下的 Markdown 知识（配方）：含代码块 + 使用说明，供 AI 检索、Guard、搜索，**默认位置，用户可通过 boxspec `knowledgeBase.dir` 配置改成 `Knowledge/` 等**
 | **Snippet** | Xcode 代码片段，通过 trigger（默认 `@`）补全，可与 Recipe 关联 |
 | **Candidate（候选）** | 待审核入库的项；来自 `as:create`、MCP 提交、`asd ais` 扫描等，经 Dashboard 审核后保存为 Recipe/Snippet |
-| **Knowledge** | 项目知识库目录，包含 `recipes/`、`.autosnippet/`（索引、candidates、guard 配置等）；Snippet 配置在 root spec 的 list 中。其下各路径与 Git 的关系见 [Knowledge 目录与 Git](#knowledge-目录与-git)。 |
+| **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:guard`、`as:search` |
-| **Guard** | 按 Recipe 知识库对代码做 AI 审查；`// as:guard` 触发 |
+| **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 调用 `autosnippet_context_search` 等工具 |
 | **Skills** | Cursor Agent Skills（`.cursor/skills/`），描述何时用、如何用 AutoSnippet 能力 |
@@ -125,22 +139,22 @@ asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
 | **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
 | **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
 
-**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；或参阅 [使用文档](docs/使用文档.md)（含 Skills 一览、AI 配置、闭环详解等）。
+**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；
 
-## Knowledge 目录与 Git
+## AutoSnippet 目录与 Git
 
-Knowledge 下各路径与版本控制的关系建议如下（可按项目需要调整）：
+AutoSnippet 下各路径与版本控制的关系建议如下（可按项目需要调整）：
 
 | 路径 | 说明 | 建议 |
 |------|------|------|
-| **Knowledge/recipes/** | Recipe 的 Markdown 文件 | **Git 子仓库**：单独建远程仓库并 `git submodule add <url> Knowledge/recipes`，用于权限拦截（仅能 push 子仓库的人可保存/上传 Recipe）。详见 [权限设置说明](docs/权限设置说明.md) 中「只把 Knowledge/recipes 作为子仓库」。 |
-| **Knowledge/.autosnippet/** | Guard 规则、违反记录、candidates、recipe-stats、context 配置等 | **跟随主仓库 Git**：规则与配置建议提交到主仓库，便于团队共享。 |
-| **Knowledge/.autosnippet/context/index/** | 语义向量索引（embed 生成） | **不跟随 Git**：体积大、机器相关，建议加入 `.gitignore`（如 `Knowledge/.autosnippet/context/index/` 或其下 `lancedb/`、`vector_index.json`）。 |
-| **Knowledge/.autosnippet/candidates/**（若存在） | 候选数据等 | 视需要：若仅本地缓存可不提交；若团队共享可跟随主仓库或单独子仓库。 |
-| **Knowledge/AutoSnippet.spmmap.json**（若存在） | SPM 依赖映射 | **跟随主仓库 Git**：便于依赖关系图一致。 |
+| **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 子仓库**：`Knowledge/recipes` 为单独仓库（submodule），Recipe 上传（git push）由 Git 服务端权限拦截。配合 `.env` 中 `ASD_RECIPES_WRITE_DIR=Knowledge/recipes` 是为了保证管理员（有 push 权限者）能够正确提交 Recipe：探针目录与 Recipe 写入目录一致，保存后可正常推送。
+- **Git 子仓库**：`AutoSnippet/recipes` 为单独仓库（submodule），Recipe 上传（git push）由 Git 服务端权限拦截。配合 `.env` 中 `ASD_RECIPES_WRITE_DIR=AutoSnippet/recipes` 是为了保识管理员（有 push 权限者）能够正确提交 Recipe：探针目录与 Recipe 写入目录一致，保存后可正常推送。
 - **不跟随 Git**：在 `.gitignore` 中忽略，不提交、不推送。
 
 ---

package/bin/api-server.js

@@ -0,0 +1,84 @@
+/**
+ * API Server 启动脚本
+ * 
+ * 用法：
+ *   node bin/api-server.js [options]
+ * 
+ * 选项：
+ *   --port <port>     API 服务器端口 (默认: 8080)
+ *   --host <host>     API 服务器主机 (默认: localhost)
+ *   --config <path>   配置文件路径
+ */
+
+const { APIGateway } = require('../lib/api/APIGateway');
+const { Agent } = require('../lib/agent/Agent');
+const { RecipeHub } = require('../lib/business/recipe/RecipeHub');
+const { SearchHub } = require('../lib/business/search/SearchHub');
+const { MetricsHub } = require('../lib/business/metrics/MetricsHub');
+
+/**
+ * 解析命令行参数
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    port: 8080,
+    host: 'localhost',
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--port') {
+      options.port = parseInt(args[++i], 10);
+    } else if (args[i] === '--host') {
+      options.host = args[++i];
+    }
+  }
+
+  return options;
+}
+
+/**
+ * 启动 API 服务器
+ */
+async function startServer() {
+  const options = parseArgs();
+
+  // 创建 Agent
+  const agent = new Agent({ name: 'APIAgent' });
+
+  // 注册 Hub
+  agent.registerHub('recipe', new RecipeHub());
+  agent.registerHub('search', new SearchHub());
+  agent.registerHub('metric', new MetricsHub());
+
+  // 创建 API Gateway
+  const gateway = new APIGateway(agent, {
+    port: options.port,
+    host: options.host,
+  });
+
+  // 启动服务器
+  try {
+    await gateway.start();
+    console.log(`✨ API 服务器运行中...`);
+    console.log(`📝 API 文档: http://${options.host}:${options.port}/api/docs`);
+    console.log(`🏥 健康检查: http://${options.host}:${options.port}/api/health`);
+    console.log(`\n按 Ctrl+C 停止服务器`);
+  } catch (error) {
+    console.error('❌ 启动服务器失败:', error);
+    process.exit(1);
+  }
+
+  // 处理信号
+  process.on('SIGINT', async () => {
+    console.log('\n🛑 停止服务器...');
+    await gateway.stop();
+    console.log('✅ 服务器已停止');
+    process.exit(0);
+  });
+}
+
+startServer().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/bin/asd

@@ -1,5 +1,5 @@
 #!/usr/bin/env sh
-# AutoSnippet 入口：优先使用原生校验入口（bin/asd-verify），否则回退到 node bin/asnip.js
+# AutoSnippet 入口：优先使用原生校验入口（bin/asd-verify），否则回退到 node bin/asd-cli.js
 # 解析 $0 的符号链接，使 DIR 指向包内 bin 目录（npm install -g 时 $0 可能是 global bin 下的 symlink）
 SCRIPT="$0"
 while [ -L "$SCRIPT" ]; do
@@ -17,5 +17,5 @@ export ASD_CWD
 if [ -x "$DIR/asd-verify" ]; then
 	exec "$DIR/asd-verify" "$@"
 else
-	exec node "$DIR/asnip.js" "$@"
+	exec node "$DIR/asd-cli.js" "$@"
 fi

package/bin/asd-cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * 职责：
+ * - AutoSnippet CLI 入口（命令行 asd）
+ * - 负责解析参数/路由子命令，并串联 install/create/extract/watch 等能力
+ *
+ * 核心流程：
+ * - commander 解析命令与全局参数（--preset/--yes）
+ * - 读取/查找 spec（AutoSnippet.boxspec.json）
+ * - 调用对应模块执行实际逻辑（create/install/extract/watch/...）
+ *
+ * 核心方法：
+ * - loadPresetConfig(presetPath): 读取预置输入 JSON（用于非交互）
+ * - getSpecFile(callback): 向上查找 AutoSnippet.boxspec.json
+ *
+ * 主要命令：
+ * - setup / init
+ * - install(i) / create(c) / extract(e) / watch(w)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// 入口校验：包内存在 checksums.json 且未经过 asd-verify（无 ASD_VERIFIED）时，可拒跑或警告，避免绕过完整性校验直接运行 node bin/asd-cli.js
+// 开发环境可设 ASD_SKIP_CHECKSUMS=1 或 ASD_SKIP_ENTRY_CHECK=1 来跳过检查
+const pkgRoot = path.join(__dirname, '..');
+const checksumsPath = path.join(pkgRoot, 'checksums.json');
+if (fs.existsSync(checksumsPath) && process.env.ASD_VERIFIED !== '1' && process.env.ASD_SKIP_CHECKSUMS !== '1') {
+	const msg = 'asd: 未经过完整性校验入口（请使用 asd 命令，勿直接运行 node bin/asd-cli.js）。开发/调试可设 ASD_SKIP_CHECKSUMS=1 或 ASD_SKIP_ENTRY_CHECK=1 跳过。';
+	if (process.env.ASD_STRICT_ENTRY === '1') {
+		console.error(msg);
+		process.exit(1);
+	}
+	if (process.env.ASD_SKIP_ENTRY_CHECK !== '1') {
+		console.warn('⚠️  ' + msg);
+	}
+}
+
+// 读取输入命令
+const inquirer = require('inquirer');
+// 命令行工具
+const commander = require('commander');
+// 全局路径：优先用 shell 传入的 ASD_CWD（asd 脚本里 $(pwd)），避免 dev:link / 符号链接等场景下 process.cwd() 与用户所在目录不一致
+const CMD_PATH = process.env.ASD_CWD || process.cwd();
+const pjson = require('../package.json');
+const findPath = require('../lib/infrastructure/paths/PathFinder');
+const install = require('../lib/snippet/snippetInstaller.js');
+const create = require('./create-snippet.js');
+const watch = require('../lib/watch/fileWatcher.js');
+const cache = require('../lib/infrastructure/cache/CacheStore.js');
+const ui = require('./dashboard-server.js');
+const defaults = require('../lib/infrastructure/config/Defaults');
+const spmDepMapUpdater = require('../lib/spm/spmDepMapUpdater.js');
+const { execSync } = require('child_process');
+const { createCliHelpers } = require('./cli-helpers');
+const { registerCommands } = require('./cli-commands');
+const helpers = createCliHelpers({
+	CMD_PATH,
+	findPath,
+	cache,
+	create,
+	inquirer,
+	defaults,
+	commander,
+	execSync,
+});
+
+registerCommands(commander, {
+	pjson,
+	CMD_PATH,
+	findPath,
+	install,
+	create,
+	watch,
+	cache,
+	ui,
+	defaults,
+	spmDepMapUpdater,
+	helpers,
+	inquirer,
+	fs,
+	path,
+});
+
+commander.parse(process.argv);