autosnippet 1.6.1 → 1.6.2

package/README.md

@@ -83,7 +83,7 @@ asd ui                     # 启动 Dashboard + watch
 
 | 命令 | 说明 |
 |------|------|
-| `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 |
@@ -93,7 +93,7 @@ asd ui                     # 启动 Dashboard + watch
 | `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 依赖映射（依赖关系图数据来源） |
 
@@ -139,10 +139,7 @@ npm run build:parser       # 构建 ParsePackage（需本机已安装 Swift）
 | **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
 | **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
 
-**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；或参阅：
-- 📖 **[完整使用说明书](docs/USER_MANUAL.md)**：15,000 字详细文档，涵盖从入门到高级的所有功能
-- 📝 **[使用文档](docs/使用文档.md)**：简明版使用说明（含 Skills 一览、AI 配置、闭环详解等）
-- ⚙️ **[npm 脚本参考](docs/NPM_SCRIPTS_REFERENCE.md)**：所有 npm 命令详细说明和使用示例
+**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；
 
 ## AutoSnippet 目录与 Git
 
@@ -152,7 +149,7 @@ 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/` 或其下 `lancedb/`、`vector_index.json`）。 |
+| **AutoSnippet/.autosnippet/context/index/** | 语义向量索引（embed 生成） | **不跟随 Git**：体积大、机器相关，建议加入 `.gitignore`（如 `AutoSnippet/.autosnippet/context/index/`）。 |
 | **AutoSnippet/.autosnippet/candidates/**（若存在） | 候选数据等 | 视需要：若仅本地缓存可不提交；若团队共享可跟随主仓库或单独子仓库。 |
 | **AutoSnippet/AutoSnippet.spmmap.json**（若存在） | SPM 依赖映射 | **跟随主仓库 Git**：便于依赖关系图一致。 |
 

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-cli.js

@@ -23,10 +23,11 @@ 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') {
-	const msg = 'asd: 未经过完整性校验入口（请使用 asd 命令，勿直接运行 node bin/asd-cli.js）。开发/调试可设 ASD_SKIP_ENTRY_CHECK=1 跳过。';
+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);

package/bin/cli-commands.js

@@ -17,9 +17,10 @@ const create = require('./create-snippet.js');
 const watch = require('../lib/watch/fileWatcher.js');
 const cache = require('../lib/infrastructure/cache/CacheStore.js');
 const pjson = require('../package.json');
+const swiftParserClient = require('../lib/infrastructure/external/spm/swiftParserClient');
 
 function registerCommands(cmd, ctx) {
-	const { CMD_PATH, findPath, install, create, watch, cache, helpers, inquirer, fs, execSync, pjson } = ctx;
+	const { CMD_PATH, findPath, install, create, watch, cache, helpers, inquirer, fs, execSync, pjson, spmDepMapUpdater } = ctx;
 
 	// 配置 version 选项
 	cmd.version(pjson.version, '-v, --version', 'output the current version');
@@ -129,8 +130,8 @@ function registerCommands(cmd, ctx) {
 				}
 			}
 			
-// Step 4: 安装依赖和配置工具链
-		console.log('🔧 步骤 4/4：安装依赖和配置工具链...\n');
+			// Step 4: 安装依赖和配置工具链
+			console.log('🔧 步骤 4/5：安装依赖和配置工具链...\n');
 		
 		// 查找 asd 安装位置（全局或本地）
 		let asdPath;
@@ -229,6 +230,33 @@ function registerCommands(cmd, ctx) {
 				}
 			}
 			
+			// Step 5: 生成 spmmap（依赖 Swift 解析器）
+			console.log('🧭 步骤 5/5：生成依赖图 AutoSnippet.spmmap.json...');
+			const parserBin = swiftParserClient.getParserBin(projectRoot);
+			if (!parserBin) {
+				console.warn('⚠️ 未检测到 Swift 解析器（ParsePackage），已跳过 spmmap 生成。');
+				console.warn('   请先安装解析器：asd install:full --parser');
+				console.warn('   安装完成后请重新执行：asd setup\n');
+			} else {
+				try {
+					const result = await spmDepMapUpdater.updateSpmDepMap(projectRoot, {
+						aggressive: true,
+						requireParser: true
+					});
+					if (result && result.ok) {
+						console.log('✅ spmmap 已生成/更新\n');
+					} else if (result && result.reason === 'parserMissing') {
+						console.warn('⚠️ 未检测到 Swift 解析器（ParsePackage），已跳过 spmmap 生成。');
+						console.warn('   请先安装解析器：asd install:full --parser');
+						console.warn('   安装完成后请重新执行：asd setup\n');
+					} else {
+						console.warn('⚠️ spmmap 生成失败，请检查 Package.swift 或解析器状态\n');
+					}
+				} catch (err) {
+					console.warn(`⚠️ spmmap 生成失败：${err.message}\n`);
+				}
+			}
+
 			console.log('\n========================================');
 			console.log('✅ 工作空间初始化完成！');
 			console.log('========================================\n');
@@ -236,10 +264,27 @@ function registerCommands(cmd, ctx) {
 			console.log('📁 Recipe 目录: AutoSnippet/recipes/');
 			console.log('⚙️  VSCode MCP: .vscode/settings.json');
 			console.log('⚙️  Cursor MCP: .cursor/mcp.json\n');
-			console.log('🚀 后续步骤：');
-			console.log('  1. 重启编辑器 (VSCode/Cursor)');
+			
+			// Step 6: 初始化 Xcode Snippets（仅在 macOS）
+			if (process.platform === 'darwin') {
+				console.log('🚀 步骤 6/6：初始化 Xcode Snippets...');
+				try {
+					const { initialize: initXcodeSnippets } = require('../scripts/init-xcode-snippets.js');
+					const success = await initXcodeSnippets();
+					if (success) {
+						console.log('✅ Xcode Snippets 已添加\n');
+					}
+				} catch (err) {
+					console.warn(`⚠️  Xcode Snippets 初始化失败：${err.message}`);
+					console.warn('   可稍后手动运行：npm run init:snippets\n');
+				}
+			}
+			
+			console.log('🎯 后续步骤：');
+			console.log('  1. 重启编辑器 (VSCode/Cursor/Xcode)');
 			console.log('  2. 测试 MCP: @autosnippet search');
-			console.log('  3. 启动面板: asd ui\n');
+			console.log('  3. 在 Xcode 中输入 "ass" 尝试 Snippet');
+			console.log('  4. 启动面板: asd ui\n');
 		});
 
 
@@ -393,11 +438,26 @@ function registerCommands(cmd, ctx) {
 		.option('-s, --skip-spm', 'skip SPM scanning')
 		.description('recognize that Snippet automatically injects dependency header files')
 		.action((options) => {
-			const args = {
-				skipSpm: options.skipSpm || false,
-				projectRoot: CMD_PATH,
-			};
-			watch.watch(args);
+			// 使用异步版本来确保得到结果或超时
+			const timeoutId = setTimeout(() => {
+				console.error('❌ 未找到 AutoSnippet.boxspec.json 配置文件');
+				console.error('   请在包含 AutoSnippet.boxspec.json 的目录或其子目录中运行此命令');
+				console.error('   或使用 asd init 初始化项目');
+				process.exit(1);
+			}, 3000);
+
+			getSpecFile(function (specFile) {
+				clearTimeout(timeoutId);
+				if (!specFile) {
+					console.error('❌ Watch 启动失败：未找到 AutoSnippet.boxspec.json 配置文件');
+					process.exit(1);
+				}
+				const args = {
+					skipSpm: options.skipSpm || false,
+					projectRoot: CMD_PATH,
+				};
+				watch.watchFileChange(specFile, CMD_PATH, args);
+			});
 		});
 
 	// spm-map 命令
@@ -422,14 +482,14 @@ function registerCommands(cmd, ctx) {
 			}
 		});
 
-	// ui 命令 - 启动 Dashboard Web 界面
+	// ui 命令 - 启动 Dashboard Web 界面（自动包含 watch 功能）
 	cmd
 		.command('ui')
 		.option('-p, --port <port>', 'specify port (default: 3000)', '3000')
 		.option('--no-open', 'do not open browser automatically')
 		.option('-b, --force-build', 'force rebuild dashboard frontend')
 		.option('-d, --dir <directory>', 'specify AutoSnippet project directory (default: current directory)')
-		.description('start AutoSnippet Dashboard web interface')
+		.description('start AutoSnippet Dashboard web interface (includes file watcher)')
 		.action(async (options) => {
 			const ui = ctx.ui;
 			if (!ui || typeof ui.launch !== 'function') {
@@ -441,6 +501,13 @@ function registerCommands(cmd, ctx) {
 				const port = parseInt(options.port, 10);
 				// 使用 -d 选项指定的目录，或 ASD_CWD 环境变量，或当前目录
 				const projectRoot = options.dir || process.env.ASD_CWD || CMD_PATH;
+				
+				// 提示用户 watch 功能已包含
+				const isDebugMode = process.env.ASD_DEBUG_WATCH === '1' || process.env.ASD_DEBUG_SEARCH === '1';
+				if (isDebugMode) {
+					console.log('💡 调试模式已启用，将显示文件监听日志');
+				}
+				
 				await ui.launch(projectRoot, port, {
 					forceBuild: options.forceBuild || false,
 					openBrowser: options.open !== false,
@@ -450,19 +517,105 @@ function registerCommands(cmd, ctx) {
 			}
 		});
 
+	// status 命令 - 环境自检
+	cmd
+		.command('status')
+		.description('check AutoSnippet environment (project root, AI, index, Dashboard, Native UI)')
+		.action(async () => {
+			const { runStatus } = require('../lib/cli/statusCommand');
+			const projectRoot = CMD_PATH;
+			await runStatus(projectRoot);
+		});
+
+	// search 命令 - 搜索知识库
+	cmd
+		.command('search <keyword>')
+		.alias('s')
+		.option('--copy', 'copy first result to clipboard')
+		.option('--pick', 'interactive selection')
+		.option('-m, --semantic', 'use semantic search (requires embed)')
+		.option('--without-agent', 'disable intelligent agent enhancement')
+		.option('--session <id>', 'specify session ID for agent personalization')
+		.description('search Recipes and Snippets')
+		.action(async (keyword, options) => {
+			const { runSearch } = require('../lib/cli/searchCommand');
+			const projectRoot = CMD_PATH;
+			await runSearch(projectRoot, keyword, options);
+		});
+
+	// embed 命令 - 构建语义索引
+	cmd
+		.command('embed')
+		.option('--clear', 'clear and rebuild index')
+		.description('build semantic vector index for Recipes')
+		.action(async (options) => {
+			const { runEmbed } = require('../lib/cli/embedCommand');
+			const projectRoot = CMD_PATH;
+			await runEmbed(projectRoot, options);
+		});
+
+	// candidate 命令 - 从剪贴板创建候选
+	cmd
+		.command('candidate')
+		.option('-t, --title <title>', 'candidate title')
+		.option('-c, --category <category>', 'candidate category')
+		.description('create candidate from clipboard')
+		.action(async (options) => {
+			const { runCandidate } = require('../lib/cli/candidateCommand');
+			const projectRoot = CMD_PATH;
+			await runCandidate(projectRoot, options);
+		});
+
+	// install:full 命令 - 全量安装
+	cmd
+		.command('install:full')
+		.option('--parser', 'install Swift parser')
+		.description('install all optional dependencies')
+		.action(async (options) => {
+			const { execSync } = require('child_process');
+			const path = require('path');
+			const rootDir = path.join(__dirname, '..');
+			const scriptPath = path.join(rootDir, 'scripts/install-full.js');
+			
+			const env = { ...process.env };
+			if (options.parser) env.ASD_INSTALL_PARSER = '1';
+			
+			try {
+				execSync(`node "${scriptPath}"`, { 
+					stdio: 'inherit',
+					env,
+					cwd: rootDir
+				});
+			} catch (err) {
+				console.error('❌ 安装失败');
+				process.exit(1);
+			}
+		});
+
 	cmd.addHelpText('after', `
 
 Examples:
   asd setup               # 初始化工作空间
+  asd status              # 环境自检
   asd install             # 安装依赖/skills/MCP
   asd extract             # 同步 snippets 到 Xcode
   asd create              # 创建 snippet
-  asd watch               # 监听文件变化
-  asd ui                  # 启动 Dashboard Web 界面
+  asd watch               # 监听文件变化（单独运行）
+  asd ui                  # 启动 Dashboard（自动包含 watch）
+  asd search <keyword>    # 搜索知识库
+  asd embed               # 构建语义索引
+  asd candidate           # 从剪贴板创建候选
+
+Advanced:
   asd ui -d /path/to/AutoSnippet  # 启动 Dashboard，操作指定项目
+  asd install:full --parser       # 全量安装 + Swift 解析器
+
+Debug modes:
+  ASD_DEBUG_WATCH=1 asd ui         # Dashboard + 文件监听日志
+  ASD_DEBUG_SEARCH=1 asd ui        # Dashboard + 搜索调试日志
 
 Notes:
-  - 老命令仍可用：i/c/e/u/w 只是别名，不会破坏现有脚本。
+  - 老命令仍可用：i/c/e/u/w/s 只是别名，不会破坏现有脚本。
   - 在非 AutoSnippet 目录中，使用 -d 或 ASD_CWD 环境变量指定项目路径。
 `);
 }