autosnippet 1.5.3 → 1.5.5

package/README.md

@@ -11,10 +11,10 @@
 
 | 角色 | 职责 | 能力 |
 |------|------|------|
-| **开发者** | 审核与决策；维护项目标准 | 在 Dashboard 审核 Candidate、保存 Recipe；使用 Snippet 补全、`// as:search` 插入；运行 `asd embed`、`asd ui` |
-| **Cursor Agent** | 按规范生成代码；检索知识库 | 通过 Skills 理解规范；MCP 按需检索、打开新建 Recipe 页；起草内容供人工审核，不直接改 Knowledge |
-| **项目内 AI** | 提取、摘要、扫描、审查 | `asd ais` 扫描；Use Copied Code 分析填充；Guard 审查；Dashboard RAG。由 `.env` 配置 |
-| **知识库** | 存储与提供项目标准 | Recipes、Snippets、语义向量索引；Guard、搜索、两种 AI 的上下文均依赖此 |
+| **开发者** | 审核与决策；维护项目标准 | Dashboard 审核 Candidate，保存 Recipe；使用 Snippet 补全、`// as:search` 插入；运行 `asd embed`、`asd ui` |
+| **Cursor Agent** | 按规范生成代码；检索与提交 | Skills 理解规范；MCP 按需检索、打开新建 Recipe 页；`autosnippet_submit_candidates` 批量提交候选供人工审核；不直接改 Knowledge |
+| **项目内 AI** | 提取、摘要、扫描、审查 | `asd ais` 扫描；Use Copied Code 分析填充；Guard 审查；Dashboard RAG；深度扫描结果可算相似度。由 `.env` 配置 |
+| **知识库** | 存储与提供项目标准 | Recipes、Snippets、语义向量索引；Guard、搜索、质量评估、相似度分析；两种 AI 的上下文均依赖此 |
 
 ---
 
@@ -44,7 +44,7 @@ asd ui         # 启动 Dashboard（建议常驻）
 
 ### 闭环
 
-**扫描 → 审核 → 沉淀 → Cursor/AI 使用 → 再沉淀**：项目 AI 通过扫描 target 批量提交候选，Cursor 完成的代码通过 Skill 提交候选，开发者完成的代码通过剪切板提交候选，Dashboard 中的候选经过人工审核进入知识库；知识库内 Recipe 为第一公民，拥有最高优先级。
+**扫描 → 审核 → 沉淀 → Cursor/AI 使用 → 再沉淀**：项目 AI 通过扫描 Target 批量提交候选，Cursor 完成的代码通过 Skill 提交候选，开发者完成的代码通过剪切板提交候选，Dashboard 中的候选经过人工审核进入知识库；知识库内 Recipe 为第一公民，拥有最高优先级。
 
 开发者通过 Snippet 获取 Recipe 内容插入编辑器， Cursor 通过 Skills 把 Recipe 产生的 context 当做上下文使用，对向量库进行查询；AI 用知识库产生的代码，过审后添加到知识库，成为了 AI 新的上下文，使得 AI 的开发趋于标准化。
 
@@ -57,7 +57,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:guard` / `// as:g` [关键词或规模] | 按知识库 AI 审查；无后缀时仅检查当前文件；后缀 **file** / **target** / **project** 可扩大范围（target=当前 Target 内所有源文件，project=项目内所有源文件）；其他为检索关键词 |
 | `// as:search` / `// as:s` [关键词] | 从知识库检索并插入 Recipe/Snippet |
 | `// as:include` / `// as:import` | Snippet 内头文件/模块标记，保存时自动注入 |
 
@@ -68,15 +68,16 @@ asd ui         # 启动 Dashboard（建议常驻）
 
 | 命令 | 说明 |
 |------|------|
+| `asd setup` | 初始化项目根（创建 AutoSnippetRoot.boxspec.json） |
 | `asd ui` | 启动 Dashboard + watch |
-| `asd status` | 环境自检（项目根、AI、索引、Native UI） |
+| `asd status` | 环境自检（含项目根、AI、索引、Dashboard/Watch、Native UI） |
 | `asd create --clipboard` | 从剪贴板创建 Recipe/Snippet |
 | `asd candidate` | 从剪贴板创建候选（Dashboard 审核） |
 | `asd install` / `asd i` | 同步 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（需 `asd ui` 运行） |
+| `asd install:cursor-skill --mcp` | 安装 Skills、Cursor 规则（`.cursor/rules/*.mdc`）并配置 MCP。配置时可运行；MCP 工具使用时需 `asd ui` 已启动 |
 | `asd install:full` | 全量安装；`--parser` 含 Swift 解析器；`--lancedb` 仅 LanceDB |
 | `asd embed` | 手动构建语义向量索引（`asd ui` 启动时也会自动执行） |
 | `asd spm-map` | 刷新 SPM 依赖映射（依赖关系图数据来源） |
@@ -85,7 +86,7 @@ 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 到候选」。AutoSnippet 将所有能力都通过语义交给 Cursor 了。
 
 ## 全量安装与可选依赖
 
@@ -99,36 +100,29 @@ asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
 
 **Swift 解析器**：默认回退 `dump-package`；`--parser` 构建 ParsePackage 后 SPM 解析更准确，需本机已装 Swift。
 
-### Postinstall 脚本说明（npm install 时）
-
-`npm install` 会执行以下**可选**脚本，均为本包内本地构建，**不访问网络、不执行动态代码**：
-
-| 脚本 | 作用 |
-|------|------|
-| `scripts/ensure-parse-package.js` | 仅当 `ASD_BUILD_SWIFT_PARSER=1` 时构建 Swift 解析器并打印「正在安装…」；否则打印跳过说明并退出。 |
-| `scripts/build-native-ui.js` | 仅在 macOS 上用本机 Swift 编译 `resources/native-ui/main.swift` → `resources/native-ui/native-ui`；失败则静默跳过。 |
-
-未安装或跳过不影响核心功能。详见 [npm lifecycle scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-scripts)。
-
 ## 配置
 
-- **AI**：项目根 `.env`，设置 `ASD_GOOGLE_API_KEY` 等（见 `.env.example`）。可选 `ASD_AI_PROVIDER`、代理等。
+- **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，功能正常。
 
-## Recipe 格式
-
-完整 Recipe 为 Markdown 文件，需包含：
-
-- **Frontmatter**（`---` 包裹的 YAML）：`title`、`trigger` 必填；可选 `category`、`language`、`headers` 等
-- **Snippet / Code Reference**：下接代码块，供 Snippet 与检索使用
-- **AI Context / Usage Guide**：使用说明，供 AI 与 Guard 检索
-
 ## 术语
 
-- **Recipe**：`Knowledge/recipes/` 下的 Markdown 知识，供 AI 检索、Guard、搜索
-- **Snippet**：Xcode 代码片段，通过 trigger（默认 `@`）补全
-- **项目根**：含 `AutoSnippetRoot.boxspec.json` 的目录
+| 术语 | 说明 |
+|------|------|
+| **Recipe** | `Knowledge/recipes/` 下的 Markdown 知识（配方）：含代码块 + 使用说明，供 AI 检索、Guard、搜索 |
+| **Snippet** | Xcode 代码片段，通过 trigger（默认 `@`）补全，可与 Recipe 关联 |
+| **Candidate（候选）** | 待审核入库的项；来自 `as:create`、MCP 提交、`asd ais` 扫描等，经 Dashboard 审核后保存为 Recipe/Snippet |
+| **Knowledge** | 项目知识库目录，包含 `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` 触发 |
+| **embed** | 语义向量索引构建；`asd embed` 或 `asd ui` 启动时自动执行，供语义检索与 MCP 使用 |
+| **MCP** | Model Context Protocol；Cursor 通过 MCP 调用 `autosnippet_context_search` 等工具 |
+| **Skills** | Cursor Agent Skills（`.cursor/skills/`），描述何时用、如何用 AutoSnippet 能力 |
+| **trigger** | Snippet 触发前缀，默认 `@`，输入后 Xcode 联想补全 |
+| **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
+| **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
 
 **详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；或参阅 [使用文档](docs/使用文档.md)（含 Skills 一览、AI 配置、闭环详解等）。  
 

package/bin/asnip.js

@@ -1012,7 +1012,7 @@ commander
 			try {
 				const AiFactory = require('../lib/ai/AiFactory');
 				const config = AiFactory.getConfigSync(projectRoot);
-				const hasKey = !!(config.apiKey || config.googleApiKey);
+				const hasKey = config.hasKey;
 				console.log(`   ${hasKey ? ok : fail} AI 配置: ${hasKey ? `provider=${config.provider}` : '未配置 API Key'}`);
 			} catch (_) {
 				console.log(`   ${fail} AI 配置: 无法读取`);
@@ -1021,13 +1021,17 @@ commander
 			console.log(`${fail} .env: 不存在，请从 .env.example 复制并填写 API Key`);
 		}
 
-		// 3. 语义索引
-		const contextDir = path.join(projectRoot, 'Knowledge', '.autosnippet');
-		const hasContext = fs.existsSync(path.join(contextDir, 'context.json')) ||
-			fs.existsSync(path.join(contextDir, 'embeddings'));
+		// 3. 语义索引（JsonAdapter: context/index/vector_index.json，LanceDB: context/index/lancedb/，manifest 由 embed 写入）
+		const paths = require('../lib/infra/paths');
+		const indexPath = paths.getContextIndexPath(projectRoot);
+		const manifestPath = path.join(paths.getContextStoragePath(projectRoot), 'manifest.json');
+		const hasContext = fs.existsSync(path.join(indexPath, 'vector_index.json')) ||
+			fs.existsSync(path.join(indexPath, 'lancedb')) ||
+			fs.existsSync(manifestPath);
 		console.log(`${hasContext ? ok : fail} 语义索引: ${hasContext ? '已构建' : '未构建，运行 asd embed'}`);
 
 		// 4. watch / ui
+		let uiRunning = false;
 		try {
 			const net = require('net');
 			const port = 3000;
@@ -1035,8 +1039,12 @@ commander
 				const s = net.connect(port, '127.0.0.1', () => { s.destroy(); res(true); });
 				s.on('error', () => res(false));
 			});
-			const uiRunning = await Promise.race([check(), new Promise(r => setTimeout(() => r(false), 500))]);
-			console.log(`${uiRunning ? ok : fail} Dashboard: ${uiRunning ? 'http://localhost:3000 已运行' : '未运行，执行 asd ui'}`);
+			uiRunning = await Promise.race([check(), new Promise(r => setTimeout(() => r(false), 500))]);
+			const uiIcon = uiRunning ? ok : 'ℹ️';
+			console.log(`${uiIcon} Dashboard/Watch: ${uiRunning ? 'http://localhost:3000 已运行' : '未运行，需时请执行 asd ui'}`);
+			if (!uiRunning) {
+				console.log(`   as:create、as:guard、as:search 依赖 watch，需时请执行: asd ui`);
+			}
 		} catch (_) {
 			console.log(`${fail} Dashboard: 无法检测`);
 		}
@@ -1046,6 +1054,23 @@ commander
 		const hasNative = !!nativeUi.getNativeUiPath();
 		console.log(`${hasNative ? ok : fail} Native UI: ${hasNative ? '已就绪 (Swift Helper)' : '未构建，执行 npm run build:native-ui (macOS)'}`);
 
+		// 6. 下一步建议
+		console.log('\n--- 下一步建议 ---');
+		const suggestions = [];
+		if (!projectRoot) {
+			suggestions.push('asd root 或 asd setup — 初始化项目根');
+		} else {
+			if (!uiRunning) suggestions.push('asd ui — 启动 Dashboard 与 watch（编辑器内指令才能生效）');
+			if (!hasContext) suggestions.push('asd embed — 构建语义索引（as:search 语义检索、MCP 需要）');
+			if (!fs.existsSync(envPath)) suggestions.push('复制 .env.example 为 .env 并填写 API Key（AI 功能需要）');
+			const cursorSkillDir = path.join(projectRoot, '.cursor', 'skills', 'autosnippet-recipes');
+			if (!fs.existsSync(cursorSkillDir)) suggestions.push('asd install:cursor-skill --mcp — 安装 Cursor Skills 与 MCP');
+		}
+		if (suggestions.length > 0) {
+			suggestions.forEach((s, i) => console.log(`   ${i + 1}. ${s}`));
+		} else {
+			console.log('   环境就绪，可以正常使用。');
+		}
 		console.log('');
 	});
 
@@ -1063,6 +1088,12 @@ commander
 		if (res.map && res.map.ok && res.map.created) {
 			console.log(`✅ 已创建 SPM 映射文件: ${res.map.path}`);
 		}
+		console.log('\n下一步建议:');
+		console.log('  1. asd ui — 启动 Dashboard 与 watch（编辑器内 as:create、as:search、as:guard 需要）');
+		console.log('  2. 复制 .env.example 为 .env 并填写 API Key（AI 功能需要）');
+		console.log('  3. asd embed — 构建语义索引');
+		console.log('  4. asd install:cursor-skill --mcp — 安装 Cursor Skills 与 MCP');
+		console.log('');
 	});
 
 commander

package/bin/ui.js

@@ -545,6 +545,37 @@ function launch(projectRoot, port = 3000, options = {}) {
 		}
 	});
 
+	// API: AI 翻译（中文 → 英文，用于 Recipe summary/usageGuide）
+	app.post('/api/ai/translate', async (req, res) => {
+		try {
+			const { summary, usageGuide } = req.body;
+			if (!summary && !usageGuide) {
+				return res.json({ summary_en: '', usageGuide_en: '' });
+			}
+			const ai = await AiFactory.getProvider(projectRoot);
+			const sys = 'You are a technical translator. Translate the following from Chinese to English. Keep technical terms (e.g. API names, class names) unchanged. Return ONLY valid JSON: { "summary_en": "...", "usageGuide_en": "..." }. Use empty string for missing input. Preserve Markdown in usageGuide.';
+			const parts = [];
+			if (summary) parts.push(`summary (摘要):\n${summary}`);
+			if (usageGuide) parts.push(`usageGuide (使用指南):\n${usageGuide}`);
+			const prompt = parts.join('\n\n');
+			const text = await ai.chat(prompt, [], sys);
+			const raw = (text || '').replace(/```json?\s*/gi, '').replace(/```\s*$/g, '').trim();
+			let out = { summary_en: '', usageGuide_en: '' };
+			try {
+				const parsed = JSON.parse(raw);
+				if (parsed.summary_en != null) out.summary_en = String(parsed.summary_en);
+				if (parsed.usageGuide_en != null) out.usageGuide_en = String(parsed.usageGuide_en);
+			} catch (_) {
+				// 若解析失败，尝试提取第一段作为 summary_en
+				if (summary) out.summary_en = raw.split('\n')[0] || summary;
+			}
+			res.json(out);
+		} catch (err) {
+			console.error(`[API Error]`, err);
+			res.status(500).json({ error: err.message });
+		}
+	});
+
 	// API: AI 聊天
 	app.post('/api/ai/chat', async (req, res) => {
 		try {