autosnippet 2.19.7 → 3.0.0

package/lib/service/cursor/RulesGenerator.js

@@ -129,8 +129,8 @@ export class RulesGenerator {
       ...ruleLines,
       '',
       'For detailed patterns and recipes, AutoSnippet MCP tools are available:',
-      '- `autosnippet_search(query)` — search knowledge base',
-      '- `autosnippet_context_search(query)` — context-aware search with history',
+      '- `autosnippet_search({ query })` — search knowledge base (auto mode: BM25 + semantic)',
+      '- `autosnippet_search({ query, mode: "context" })` — context-aware search with history',
     ];
     return lines.join('\n') + '\n';
   }

package/lib/service/skills/SkillAdvisor.js

@@ -98,7 +98,7 @@ export class SkillAdvisor {
       existingProjectSkills: [...existingSkills],
       analysisContext,
       hint: suggestions.length > 0
-        ? `发现 ${suggestions.length} 个 Skill 创建建议。你可以使用 autosnippet_create_skill 工具直接创建，也可以根据 rationale 自行判断是否需要。`
+        ? `发现 ${suggestions.length} 个 Skill 创建建议。你可以使用 autosnippet_skill({ operation: "create" }) 直接创建，也可以根据 rationale 自行判断是否需要。`
         : '当前项目使用模式暂无明确的 Skill 创建建议。继续使用后会积累更多信号。',
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "2.19.7",
+  "version": "3.0.0",
   "description": "AutoSnippet - 连接开发者、AI 与项目知识库的工具",
   "type": "module",
   "main": "lib/bootstrap.js",

package/scripts/install-cursor-skill.js

@@ -4,10 +4,10 @@
  * 将 AutoSnippet 自带的 Agent Skills 安装到「当前项目根」的 Cursor 环境（项目根/.cursor/skills/）。
  * 项目根：从当前工作目录向上查找含 AutoSnippet.boxspec.json 的目录的父级；未找到则用当前目录。
  *
- * V2 策略：静态索引 + MCP 按需检索
+ * V3 策略：静态索引 + MCP 按需检索
  * - project-recipes-context.md：轻量索引（title | trigger | category | summary），不再塞全文
- * - Agent 需要详情时调用 MCP: autosnippet_get_recipe / autosnippet_search / autosnippet_context_search
- * - guard-context.md：同为轻量索引（fallback 用），Guard 主路径走 MCP guard_check / guard_audit_files
+ * - Agent 需要详情时调用 MCP: autosnippet_knowledge({ operation: "get" }) / autosnippet_search
+ * - guard-context.md：同为轻量索引（fallback 用），Guard 主路径走 MCP autosnippet_guard
  *
  * 运行方式：在项目根目录执行 npm run install:cursor-skill，或 asd install:cursor-skill，或 node scripts/install-cursor-skill.js
  */
@@ -148,7 +148,7 @@ function extractFrontmatterFields(content) {
 
 /**
  * V2: 生成轻量 Recipe 索引（title | trigger | category | summary）
- * Agent 需要详情时调用 MCP: autosnippet_get_recipe / autosnippet_search
+ * Agent 需要详情时调用 MCP: autosnippet_knowledge({ operation: "get" }) / autosnippet_search
  */
 function buildProjectRecipesContext(projectRoot) {
   const recipesDir = getRecipesDir(projectRoot);
@@ -159,7 +159,7 @@ function buildProjectRecipesContext(projectRoot) {
   const lines = [
     '# Project Recipes Index\n\n',
     'Generated by `asd install:cursor-skill`. **轻量索引** — 只含摘要信息。\n',
-    'Agent 需要 Recipe 全文时请调用 MCP: `autosnippet_get_recipe(id)` / `autosnippet_search(query)` / `autosnippet_context_search(query)`\n\n',
+    'Agent 需要 Recipe 全文时请调用 MCP: `autosnippet_knowledge({ operation: "get", id })` / `autosnippet_search(query)`\n\n',
     `Total: ${mdFiles.length} recipes\n\n`,
     '| # | File | Title | Trigger | Category | Language | Kind | Summary |\n',
     '|---|------|-------|---------|----------|----------|------|---------|\n',
@@ -200,10 +200,10 @@ function buildProjectRecipesContext(projectRoot) {
   }
 
   lines.push('\n## Usage Tips\n\n');
-  lines.push('- 查找 Recipe: `autosnippet_search(query)` 或 `autosnippet_context_search(query)`\n');
-  lines.push('- 获取详情: `autosnippet_get_recipe(id)` — 返回完整 Recipe 内容、关系、约束\n');
-  lines.push('- 按类型浏览: `autosnippet_list_rules()` / `autosnippet_list_patterns()` / `autosnippet_list_facts()`\n');
-  lines.push('- Guard 检查: `autosnippet_guard_check(code)` / `autosnippet_guard_audit_files(files)`\n');
+  lines.push('- 查找 Recipe: `autosnippet_search({ query })` 或 `autosnippet_search({ query, mode: "context" })`\n');
+  lines.push('- 获取详情: `autosnippet_knowledge({ operation: "get", id })` — 返回完整 Recipe 内容、关系、约束\n');
+  lines.push('- 按类型浏览: `autosnippet_knowledge({ operation: "list", kind: "rule" })` / `kind: "pattern"` / `kind: "fact"`\n');
+  lines.push('- Guard 检查: `autosnippet_guard({ code })` / `autosnippet_guard({ files })`\n');
 
   return lines.join('');
 }
@@ -307,7 +307,7 @@ if (fs.existsSync(cursorRulesSource)) {
   }
 }
 
-// 可选：写入 MCP 配置，使 autosnippet_context_search 等工具可用（连接层封装在此）
+// 可选：写入 MCP 配置，使 autosnippet_search 等工具可用（连接层封装在此）
 const mcpPath = path.join(projectRoot, '.cursor', 'mcp.json');
 const mcpServerScript = path.join(autoSnippetRoot, 'bin', 'mcp-server.js');
 const addMcp = process.argv.includes('--mcp');

package/skills/autosnippet-analysis/SKILL.md

@@ -5,11 +5,13 @@ description: Deep project analysis — full scan + semantic field enrichment + g
 
 # AutoSnippet — Deep Project Analysis & Semantic Enrichment
 
-> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 autosnippet_health/autosnippet_capabilities；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
+> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 `autosnippet_health`；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
 
 ## Core Principle
 
-**MCP 工具负责数据采集 + 静态检查；你（Agent）负责语义理解；`autosnippet_enrich_candidates` 负责 AI 补全缺失字段。**
+**MCP 工具负责数据采集 + 静态检查；你（Agent）负责语义理解；Agent 直接填写完整字段后通过 `autosnippet_submit_knowledge` 提交。**
+
+**⚠️ 严格提交规则**：`autosnippet_submit_knowledge` 实施严格前置校验——缺少必要字段的提交将被**直接拒绝（不入库）**。必须在单次调用中一次性提供所有必填字段（title, language, content, kind, doClause, category, trigger, description, headers, usageGuide, knowledgeType, content.rationale）。不要分步提交或先提交再补全。
 
 ---
 
@@ -24,7 +26,7 @@ description: Deep project analysis — full scan + semantic field enrichment + g
 ### Workflow
 
 #### Phase 1: Collect & Baseline
-1. 调用 `autosnippet_scan_project` 获取文件列表 + Guard 审计基线
+1. 调用 `autosnippet_bootstrap(operation=scan)` 获取文件列表 + Guard 审计基线
 2. 审视 Guard 违规 — 静态规则问题 (命名/API 使用/废弃 API)
 3. 确定高优先级文件 (核心模块/共享工具/Service 层)
 
@@ -48,13 +50,21 @@ description: Deep project analysis — full scan + semantic field enrichment + g
 ```json
 {
   "title": "网络层统一错误处理模式",
-  "code": "<实际代码模式>",
+  "content": {
+    "pattern": "<实际代码模式>",
+    "rationale": "统一错误处理避免分散的 try-catch，便于日志收集和错误上报"
+  },
   "language": "swift",
+  "kind": "pattern",
+  "doClause": "Use centralized error handling via APIClient.request() for all network calls",
   "category": "Network",
+  "trigger": "@network-error-handling",
+  "description": "网络层统一错误处理——所有请求通过 APIClient.request() 封装，统一 catch + 日志上报",
+  "headers": ["import Combine", "import Foundation"],
+  "usageGuide": "### 何时使用\n发起网络请求时统一通过 APIClient\n### 如何使用\n1. 创建 NetworkError 枚举 2. 调用 APIClient.request()",
   "knowledgeType": "code-pattern",
   "complexity": "intermediate",
   "scope": "project-specific",
-  "rationale": "统一错误处理避免分散的 try-catch，便于日志收集和错误上报",
   "steps": [
     { "title": "创建 Error 枚举", "description": "在 Network/ 下创建 NetworkError.swift", "code": "enum NetworkError: Error { ... }" },
     { "title": "封装请求方法", "description": "所有请求统一通过 APIClient.request()", "code": "" }
@@ -76,7 +86,7 @@ description: Deep project analysis — full scan + semantic field enrichment + g
 Use `autosnippet_submit_knowledge_batch` for batch submission.
 
 #### Phase 4: Guard Deep Audit (Optional)
-对特定文件调用 `autosnippet_guard_audit_files` 做深度规范审计。
+对特定文件调用 `autosnippet_guard` (files[]) 做深度规范审计。
 
 ---
 
@@ -104,17 +114,13 @@ Use `autosnippet_submit_knowledge_batch` for batch submission.
 在分析代码时，直接填写所有 6 个语义字段到 `autosnippet_submit_knowledge` 调用中。
 
 **方式 B: 对已有候选调用 AI 补全**
-```
-autosnippet_enrich_candidates({ candidateIds: ["id1", "id2", ...] })
-```
-AI 会分析每条候选的代码，自动填充缺失字段（已有字段不会被覆盖）。
+> 注：`autosnippet_enrich_candidates` 已移入 admin 层级，Agent 推荐使用方式 A 直接填写完整字段。
 
 **方式 C: Bootstrap 候选 AI 润色**
 ```
-autosnippet_bootstrap_refine({ candidateIds: ["id1", "id2", ...] })
+autosnippet_bootstrap(operation=refine, candidateIds: ["id1", "id2", ...])
 ```
 使用 AI 对 Bootstrap 候选做内容润色（改善 summary、补充 insight、推断 relations、调整 confidence）。
-必须在 `autosnippet_enrich_candidates` 之后调用（确保字段完整后再润色）。
 
 ---
 
@@ -126,12 +132,11 @@ autosnippet_bootstrap_refine({ candidateIds: ["id1", "id2", ...] })
 
 ### Workflow
 
-1. 调用 `autosnippet_enrich_candidates` 对目标候选做结构补齐（诊断缺失字段）
-2. 调用 `autosnippet_bootstrap_refine` 对候选做 AI 润色（summary/insight/relations）
-3. 调用 `autosnippet_validate_candidate` 检查结构完整性
-4. 调用 `autosnippet_check_duplicate` 检查重复
-5. 报告补全情况 + 缺失字段 + 重复风险
-6. 如缺失字段 AI 无法填充，提示用户手动补充
+1. 对目标候选做结构补齐（确保所有字段完整）
+2. 调用 `autosnippet_bootstrap(operation=refine)` 对候选做 AI 润色（summary/insight/relations）
+3. 提交时使用 `autosnippet_submit_knowledge`（内置自动校验 + 去重检查）
+4. 报告补全情况 + 缺失字段 + 重复风险
+5. 如缺失字段 AI 无法填充，提示用户手动补充
 
 ### Recipe 必备字段检查清单
 

package/skills/autosnippet-candidates/SKILL.md

@@ -5,7 +5,7 @@ description: Generate Recipe candidates with full V3 structured information. Sin
 
 # AutoSnippet - Generate Candidates with Structured Content (v3.1)
 
-> Self-check and Fallback: MCP tools return unified JSON Envelope. Before heavy ops call autosnippet_health/autosnippet_capabilities. On failure do not retry in same turn; use static context or narrow scope.
+> Self-check and Fallback: MCP tools return unified JSON Envelope. Before heavy ops call `autosnippet_health`. On failure do not retry in same turn; use static context or narrow scope.
 
 ## Core Rule: Agent Permission Boundary
 
@@ -18,33 +18,37 @@ Recipe creation, review, publish, update, deprecate, delete are **human-only via
 
 ---
 
-## ⚠️ Recipe-Ready Checklist (CRITICAL)
+## ⚠️ Recipe-Ready Checklist (CRITICAL — STRICT ENFORCEMENT)
 
-**MCP 不再使用项目内 AI**——外部 Agent 必须自行提供所有字段。候选字段不全将导致 Recipe 审核时缺失重要信息。
+**MCP 不再使用项目内 AI**——外部 Agent 必须自行提供所有字段。**缺少必要字段的提交将被直接拒绝（不入库）**，不会降级处理。
 
-提交前必须检查以下字段（缺少任何一项，返回的 `recipeReadyHints` 会提示）：
+**严格规则**：
+- 所有必填字段必须在**单次调用**中一次性提供
+- 缺字段的提交会返回 `errorCode: INCOMPLETE_SUBMISSION`，不会创建任何记录
+- **禁止**先提交不完整数据再补全重新提交 — 这会浪费 Token 和时间
+- 提交前自行确认所有字段齐全，一次通过
 
 | 字段 | 级别 | 要求 | 示例 |
 |------|------|------|------|
 | `title` | 必填 | 中文简短标题（≤20字） | "视频封面 Cell 16:9 布局与时长格式化" |
-| `code` | 必填 | 代码片段 | 完整可运行的使用示例 |
+| `content.pattern` / `content.markdown` | 必填 | 代码片段或 Markdown 正文 | 完整可运行的使用示例 |
+| `content.rationale` | 必填 | 设计原理说明 | "统一封面布局避免手动计算" |
 | `language` | 必填 | `swift` / `objectivec` | 小写，不要用 `objc` |
+| `kind` | 必填 | `rule` / `pattern` / `fact` | 知识类型 |
+| `doClause` | 必填 | 英文祈使句正向指令（≤60 tokens） | "Use AspectRatioContainer for 16:9 layout" |
 | `category` | 必填 | 8 选 1 | View/Service/Tool/Model/Network/Storage/UI/Utility |
 | `trigger` | 必填 | @ 开头小写 | `@video-cover-cell` |
-| `summary_cn` | 必填 | 中文摘要 ≤100字 | "封面图片 16:9 自适应布局…" |
-| `summary_en` | 强烈建议 | 英文摘要 ≤100 words | "Cover image 16:9 adaptive layout…" |
+| `description` | 必填 | 中文摘要 ≤80字 | "封面图片 16:9 自适应布局…" |
 | `headers` | 必填 | 完整 import 语句数组 | `["#import <UIKit/UIKit.h>"]` |
-| `usageGuide` | 强烈建议 | Markdown ### 章节 | 见下方格式要求 |
-| `usageGuide_en` | 推荐 | 英文使用指南 | 提升 AI 理解与检索 |
-| `reasoning` | 必填 | whyStandard + sources + confidence | 见 Layer 6 |
-| `knowledgeType` | 强烈建议 | 12 维度之一 | `code-pattern` |
-| `rationale` | 强烈廚议 | 设计原理 | "统一封面布局避免手动计算" |
+| `usageGuide` | 必填 | Markdown ### 章节格式 | 描述何时/如何使用此知识 |
+| `knowledgeType` | 必填 | 知识维度 | `code-pattern` / `architecture` / `best-practice` 等 |
+| `reasoning` | 强烈建议 | whyStandard + sources + confidence | 见 Layer 6 |
 
 **工作流程**：
-1. Agent 提取候选时填写全部字段
-2. 提交后检查返回值中的 `recipeReadyHints`
-3. 若有缺失→ Agent 补全后重新提交（或调用 `autosnippet_enrich_candidates` 查漏）
-4. `recipeReadyHints` 为空 = 候选可直接审核为 Recipe
+1. Agent 提取候选时**一次性填写全部必填字段**
+2. 调用 `autosnippet_submit_knowledge` 提交
+3. 若返回 `INCOMPLETE_SUBMISSION` → 检查 `missingFields`，补齐后重新提交
+4. 提交成功 = 候选可直接审核为 Recipe
 
 ---
 
@@ -58,8 +62,8 @@ Recipe creation, review, publish, update, deprecate, delete are **human-only via
 5. Score and rank -> submit Candidates
 
 **Scenario 2: User says "batch scan Target"**
-1. Call `autosnippet_get_targets` -> select targetName
-2. Call `autosnippet_get_target_files(targetName)`
+1. Call `autosnippet_structure(operation=targets)` -> select targetName
+2. Call `autosnippet_structure(operation=files, targetName)`
 3. Batch extract candidates (parallel)
 4. Dedup, score, similarity mark -> submit Candidates
 
@@ -218,14 +222,13 @@ Severity: `error` (must fix) | `warning` (should fix) | `info` (suggestion)
 ## Single File / Module Scan Flow
 1. Read file → find public classes/functions/common patterns
 2. Per-file checklist extraction (10 dimensions above)
-3. Call `autosnippet_context_search` to mark similarity and fill `relations`
-4. (Optional) `autosnippet_validate_candidate` pre-validate
-5. (Optional) `autosnippet_check_duplicate` dedup hint
+3. Call `autosnippet_search(mode=context)` to mark similarity and fill `relations`
+4. `autosnippet_submit_knowledge` submit single (built-in auto-validate + dedup)
 6. `autosnippet_submit_knowledge` or `autosnippet_submit_knowledge_batch` to submit
 
 ## Batch Target Scan Flow
-1. `autosnippet_get_targets` → select targetName
-2. `autosnippet_get_target_files(targetName)`
+1. `autosnippet_structure(operation=targets)` → select targetName
+2. `autosnippet_structure(operation=files, targetName)`
 3. Parallel scan → per-file checklist extraction → aggregate / dedup / score
 4. `autosnippet_submit_knowledge_batch` batch submit — **all V3 fields are preserved**
 
@@ -241,15 +244,12 @@ Severity: `error` (must fix) | `warning` (should fix) | `info` (suggestion)
 
 | Tool | Usage |
 |------|-------|
-| `autosnippet_get_targets` | List project Targets for batch scan |
-| `autosnippet_get_target_files` | Get files for a Target |
-| `autosnippet_get_target_metadata` | Get Target metadata (dependencies, path) |
-| `autosnippet_context_search` | Find similar existing Recipes → fill `relations` |
-| `autosnippet_validate_candidate` | Pre-validate candidate fields |
-| `autosnippet_check_duplicate` | Cosine similarity dedup check |
-| `autosnippet_submit_knowledge` | Submit single candidate (**all V3 fields**) |
+| `autosnippet_structure(operation=targets)` | List project Targets for batch scan |
+| `autosnippet_structure(operation=files)` | Get files for a Target |
+| `autosnippet_structure(operation=metadata)` | Get Target metadata (dependencies, path) |
+| `autosnippet_search(mode=context)` | Find similar existing Recipes → fill `relations` |
+| `autosnippet_submit_knowledge` | Submit single candidate (**all V3 fields**, built-in auto-validate + dedup) |
 | `autosnippet_submit_knowledge_batch` | Batch submit candidates (**all V3 fields preserved**) |
-| `autosnippet_submit_knowledge_batch` | Submit .md draft files as candidates |
 
 ---
 
@@ -304,16 +304,15 @@ Recommended sections: When to use / When not to use / Key points / Dependencies
 
 ### 备选：二次补全流程
 
-Step 1: 提交基本字段（title, code, language）→ 获得 candidate ID
-Step 2: 调用 `autosnippet_enrich_candidates({ candidateIds: ["id1", "id2"] })` 查漏
-Step 3: 根据返回的 `missingFields` + `recipeReadyMissing` 补全字段
-Step 4: 重新提交完整候选
+Step 1: 提交基本字段（title, code, language）→ 获得 candidate ID（`autosnippet_submit_knowledge` 内置自动校验 + 去重检查）
+Step 2: 根据提交返回的校验结果补全缺失字段
+Step 3: 重新提交完整候选
 
-`autosnippet_enrich_candidates` 检查两层：
-- **语义字段** (missingFields): rationale, knowledgeType, complexity, scope, steps, constraints
-- **Recipe 必填** (recipeReadyMissing): category, trigger, summary_cn, summary_en, headers, usageGuide
+> 注：`autosnippet_enrich_candidates` / `autosnippet_validate_candidate` / `autosnippet_check_duplicate` 已移入 admin 层级。Agent 层级的 `autosnippet_submit_knowledge` 已内置自动校验 + 去重，无需额外调用。
 
-已填写的字段**不会被覆盖**。使用此流程在候选 → Recipe 之前查漏补缺。
+需要补全的两层字段：
+- **语义字段**: rationale, knowledgeType, complexity, scope, steps, constraints
+- **Recipe 必填**: category, trigger, summary_cn, summary_en, headers, usageGuide
 
 ---
 

package/skills/autosnippet-coldstart/SKILL.md

@@ -16,13 +16,13 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 | 已有知识库，查/用 Recipe | → autosnippet-recipes |
 | 只扫描单个文件/模块 | → autosnippet-candidates |
 | 只做 Guard 审计 | → autosnippet-guard |
-| 快速看看项目结构 | → autosnippet-structure（用 scan_project） |
+| 快速看看项目结构 | → autosnippet-structure（用 `autosnippet_bootstrap(operation=scan)`） |
 
 ---
 
 ## Phase 0: 启动扫描
 
-调用 `autosnippet_bootstrap_knowledge` 收集项目结构化数据：
+调用 `autosnippet_bootstrap(operation=knowledge)` 收集项目结构化数据：
 
 ```json
 { "aiMode": "external", "maxFiles": 500, "contentMaxLines": 150 }
@@ -226,7 +226,7 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 
 ## Phase 5: 批量提交
 
-将所有分析结果通过 `autosnippet_submit_knowledge_batch` 批量提交：
+将所有分析结果通过 `autosnippet_submit_knowledge_batch` 批量提交（内置自动校验 + 去重）：
 
 ```json
 {
@@ -283,7 +283,7 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 
 ## scan_project vs bootstrap_knowledge
 
-| | scan_project | bootstrap_knowledge |
+| | `bootstrap(op=scan)` | `bootstrap(op=knowledge)` |
 |---|---|---|
 | **用途** | 快速结构探查（不写库） | 完整知识库初始化（写 knowledge_edges） |
 | **SPM 图谱写入** | ❌ | ✅ |
@@ -447,17 +447,14 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 
 | Tool | 用途 |
 |------|------|
-| `autosnippet_bootstrap_knowledge` | 启动冷启动扫描（本 Skill 核心工具） |
-| `autosnippet_enrich_candidates` | ① 结构补齐：诊断候选字段缺失 |
-| `autosnippet_bootstrap_refine` | ② 内容润色：AI 精炼候选质量（summary/insight/relations） |
+| `autosnippet_bootstrap(operation=knowledge)` | 启动冷启动扫描（本 Skill 核心工具） |
+| `autosnippet_bootstrap(operation=refine)` | AI 精炼候选质量（summary/insight/relations） |
+| `autosnippet_bootstrap(operation=scan)` | 轻量探查（不写库） |
 | `autosnippet_submit_knowledge_batch` | 批量提交候选 |
-| `autosnippet_submit_knowledge` | 提交单条候选 |
-| `autosnippet_validate_candidate` | 校验候选字段 |
-| `autosnippet_check_duplicate` | 去重检查 |
-| `autosnippet_context_search` | 查找已有知识（避免重复） |
-| `autosnippet_scan_project` | 轻量探查（不写库） |
-| `autosnippet_list_skills` | 列出可用 Skill 列表 |
-| `autosnippet_load_skill` | 加载指定 Skill 文档获取指引 |
+| `autosnippet_submit_knowledge` | 提交单条候选（内置自动校验 + 去重检查） |
+| `autosnippet_search(mode=context)` | 查找已有知识（避免重复） |
+| `autosnippet_skill(operation=list)` | 列出可用 Skill 列表 |
+| `autosnippet_skill(operation=load)` | 加载指定 Skill 文档获取指引 |
 
 ## Related Skills
 

package/skills/autosnippet-concepts/SKILL.md

@@ -15,7 +15,7 @@ This skill explains [AutoSnippet](https://github.com/GxFn/AutoSnippet)'s **knowl
 4. For **project structure** (targets/dep graph), use **autosnippet-structure**.
 
 5. **Self-check & Fallback (统一 Envelope)**
-  - Before heavy operations, call `autosnippet_health` and `autosnippet_capabilities`.
+  - Before heavy operations, call `autosnippet_health`.
   - All MCP tools return a JSON Envelope: `{ success, errorCode?, message?, data?, meta }`.
   - On failure or empty results, do NOT retry within the same cycle; fall back to static context or ask user for minimal confirmation, then continue with reduced scope.
 
@@ -36,12 +36,12 @@ In AutoSnippet, the **知识库** is the set of project-owned artifacts under **
 
 ## Context Storage and Vector Store
 
-The knowledge base has **context storage** capability: Recipes, docs, etc. are embedded and support semantic search. The agent queries on demand via MCP tool `autosnippet_context_search` without preloading all content.
+The knowledge base has **context storage** capability: Recipes, docs, etc. are embedded and support semantic search. The agent queries on demand via MCP tool `autosnippet_search(mode=context)` without preloading all content.
 
 **Safety and role statement**:
 - Context storage and vector store are **safe** external storage; they only hold project knowledge (Recipes, docs, etc.), with no user privacy or sensitive data exposure risk.
 - **Skills express semantics** (when to query, what to query, how to use); **MCP provides capability** (connection, retrieval, response).
-- **Cursor can use Context storage and vector store as external context**: call `autosnippet_context_search` on demand to fetch relevant chunks instead of loading all knowledge into the conversation, thus **saving context space** (tokens/context window).
+- **Cursor can use Context storage and vector store as external context**: call `autosnippet_search(mode=context)` on demand to fetch relevant chunks instead of loading all knowledge into the conversation, thus **saving context space** (tokens/context window).
 
 | Item | Description |
 |------|-------------|
@@ -49,12 +49,12 @@ The knowledge base has **context storage** capability: Recipes, docs, etc. are e
 | **Build command** | Run `asd embed` from project root |
 | **Index sources** | `recipe` (AutoSnippet/recipes/*.md), `doc` (docs dir), `target-readme` (SPM target READMEs) |
 | **Storage adapter** | Default `json` |
-| **Usage** | With `asd ui` running, MCP tool `autosnippet_context_search` takes `query`, `limit?` for semantic search |
+| **Usage** | With `asd ui` running, MCP tool `autosnippet_search(mode=context)` takes `query`, `limit?` for semantic search |
 | **Use cases** | On-demand lookup of relevant Recipe/docs; Guard review against knowledge base; Dashboard semantic search |
 
 **Prerequisites**: `asd embed` run, `asd ui` started, MCP configured.
 
-**Usage guidance for Cursor**: Assume `asd ui` is kept running when calling MCP tools (`autosnippet_context_search`, `autosnippet_search`, etc.). If a call fails (e.g. connection refused, API error), do **not** retry within the current agent cycle; fall back to static index (`references/project-recipes-context.md` 轻量索引) or in-context lookup instead.
+**Usage guidance for Cursor**: Assume `asd ui` is kept running when calling MCP tools (`autosnippet_search`, etc.). If a call fails (e.g. connection refused, API error), do **not** retry within the current agent cycle; fall back to static index (`references/project-recipes-context.md` 轻量索引) or in-context lookup instead.
 
 **Envelope reading guidance**:
 - Parse Envelope fields:
@@ -67,7 +67,6 @@ The knowledge base has **context storage** capability: Recipes, docs, etc. are e
 
 **Self-check & safety**:
 - Use `autosnippet_health` to verify UI and service availability before heavy operations.
-- Use `autosnippet_capabilities` to list available tools and inputs/outputs.
 - Authentication and HTTP wiring live in MCP, not in Skills. Do not hardcode URLs/HTTP in Skills.
 
 ---
@@ -78,24 +77,20 @@ This is a conceptual map. Skills stay semantic; MCP provides capability.
 
 | Intent | Primary tool(s) |
 |---|---|
-| 统合搜索 | `autosnippet_search`（auto 模式融合 BM25+语义） |
-| 语义检索 | `autosnippet_context_search` |
-| 精确检索 | `autosnippet_keyword_search` |
-| 向量搜索 | `autosnippet_semantic_search` |
-| 知识浏览 | `autosnippet_list_recipes`, `autosnippet_get_recipe`, `autosnippet_list_rules`, `autosnippet_list_patterns`, `autosnippet_list_facts` |
-| 结构发现 | `autosnippet_get_targets`, `autosnippet_get_target_files`, `autosnippet_get_target_metadata` |
-| 知识图谱 | `autosnippet_graph_query`, `autosnippet_graph_impact`, `autosnippet_graph_path`, `autosnippet_graph_stats` |
-| 候选预检 | `autosnippet_validate_candidate` |
-| 去重建议 | `autosnippet_check_duplicate` |
-| 候选提交 | `autosnippet_submit_knowledge`, `autosnippet_submit_knowledge_batch`, `autosnippet_submit_knowledge_batch` |
-| AI 补全 | `autosnippet_enrich_candidates` |
-| Guard 检查 | `autosnippet_guard_check`, `autosnippet_guard_audit_files` |
-| 合规报告 | `autosnippet_compliance_report`, `autosnippet_recipe_insights` |
-| 使用确认 | `autosnippet_confirm_usage` |
-| 项目扫描 | `autosnippet_scan_project` |
-| 冷启动 | `autosnippet_bootstrap_knowledge`, `autosnippet_bootstrap_refine` |
-| Skills 管理 | `autosnippet_list_skills`, `autosnippet_load_skill`, `autosnippet_create_skill`, `autosnippet_update_skill`, `autosnippet_delete_skill`, `autosnippet_suggest_skills` |
-| 自检/能力 | `autosnippet_health`, `autosnippet_capabilities` |
+| 统合搜索 | `autosnippet_search`（mode=auto 融合 BM25+语义） |
+| 语义检索 | `autosnippet_search(mode=context)` |
+| 精确检索 | `autosnippet_search(mode=keyword)` |
+| 向量搜索 | `autosnippet_search(mode=semantic)` |
+| 知识浏览 | `autosnippet_knowledge(operation=list/get/insights)` |
+| 结构发现 | `autosnippet_structure(operation=targets/files/metadata)` |
+| 知识图谱 | `autosnippet_graph(operation=query/impact/path/stats)` |
+| 候选提交 | `autosnippet_submit_knowledge`, `autosnippet_submit_knowledge_batch` |
+| Guard 检查 | `autosnippet_guard`（code 单条 / files[] 批量 — 自动路由） |
+| 使用确认 | `autosnippet_knowledge(operation=confirm_usage)` |
+| 项目扫描 | `autosnippet_bootstrap(operation=scan)` |
+| 冷启动 | `autosnippet_bootstrap(operation=knowledge/refine)` |
+| Skills 管理 | `autosnippet_skill(operation=list/load/create/update/delete/suggest)` |
+| 自检 | `autosnippet_health` |
 
 ### Failure Handling (Examples)
 - 检索失败（`SEARCH_FAILED`）：改用静态 Recipe 目录或缩小关键词后再试（下一轮）。
@@ -367,7 +362,7 @@ When both Recipe and project source code have relevant implementations, **prefer
 ## On-Demand Context (when asd ui is running)
 
 When `asd ui` is running in the project root, use the HTTP API for on-demand semantic search:
-- MCP tool `autosnippet_context_search` (pass `query`, `limit?`) → returns relevant Recipe/docs
+- MCP tool `autosnippet_search(mode=context)` (pass `query`, `limit?`) → returns relevant Recipe/docs
 - Used to fetch Recipe/docs relevant to the current task dynamically instead of loading all at once.
 
 ---
@@ -376,13 +371,13 @@ When `asd ui` is running in the project root, use the HTTP API for on-demand sem
 
 | Capability | Description | Skill |
 |------------|-------------|-------|
-| **Recipe lookup** | Read `references/project-recipes-context.md` 轻量索引，需全文调 MCP `autosnippet_get_recipe(id)` / `autosnippet_context_search`. Recipe over source | autosnippet-recipes |
+| **Recipe lookup** | Read `references/project-recipes-context.md` 轻量索引，需全文调 MCP `autosnippet_knowledge(operation=get, id)` / `autosnippet_search(mode=context)`. Recipe over source | autosnippet-recipes |
 | **Create Recipe** | Dashboard New Recipe; or write to `_draft_recipe.md` and watch auto-adds; or MCP `autosnippet_submit_knowledge_batch` | autosnippet-create |
 | **Search & insert** | `ass` shortcut or `// as:search`, `asd search`, Dashboard search | autosnippet-search |
 | **Audit review** | `// as:audit`; watch runs AI review against knowledge base | autosnippet-guard |
 | **Dependency graph** | `AutoSnippet/AutoSnippet.spmmap.json`; `asd spm-map` to update; MCP graph tools for querying | autosnippet-structure |
-| **Vector store** | Built by `asd embed`; `autosnippet_context_search` for on-demand lookup. Use as context storage to save space | autosnippet-concepts / autosnippet-recipes |
-| **MCP tools** | `autosnippet_search` (统合搜索), `autosnippet_context_search` (智能语义搜索), `autosnippet_guard_check` (Guard 检查) | — |
+| **Vector store** | Built by `asd embed`; `autosnippet_search(mode=context)` for on-demand lookup. Use as context storage to save space | autosnippet-concepts / autosnippet-recipes |
+| **MCP tools** | `autosnippet_search` (统合搜索), `autosnippet_guard` (Guard 检查) | — |
 
 **Principles**: Recipe is project standard, over project implementation; do not modify AutoSnippet/ directly, submit via Dashboard or MCP candidate submission. Context storage is safe; Skills express semantics, MCP provides capability; Cursor calls on demand to save space.
 
@@ -600,9 +595,9 @@ authority: 3
 
 ### How to use knowledge once it’s in the base
 
-- **Search**: MCP `autosnippet_context_search` / `autosnippet_search`, or terminal `asd search`, Dashboard search, `ass` shortcut or `// as:search`.
-- **Audit**: `// as:audit` runs Guard against Recipe standards. Or call `autosnippet_guard_check` / `autosnippet_guard_audit_files` via MCP for on-demand checking.
-- **Record adoption**: When the user confirms use, call `autosnippet_confirm_usage` to record human usage (affects authority and ranking).
+- **Search**: MCP `autosnippet_search` (mode=context/keyword/semantic/auto), or terminal `asd search`, Dashboard search, `ass` shortcut or `// as:search`.
+- **Audit**: `// as:audit` runs Guard against Recipe standards. Or call `autosnippet_guard` via MCP for on-demand checking (with `code` for single snippet or `files[]` for batch).
+- **Record adoption**: When the user confirms use, call `autosnippet_knowledge(operation=confirm_usage)` to record human usage (affects authority and ranking).
 
 ---
 

package/skills/autosnippet-create/SKILL.md

@@ -5,7 +5,7 @@ description: Guides the agent to submit module usage code (designed/written with
 
 # AutoSnippet Create — Submit to Web, Add to AutoSnippet
 
-> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 autosnippet_health/autosnippet_capabilities；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
+> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 `autosnippet_health`；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
 
 This skill tells the agent how to **submit module usage code** (that Cursor has designed or the user has written) to the **AutoSnippet web (Dashboard)** so it is **added to the knowledge base (Recipes)**. For concepts (knowledge base, Recipe), use **autosnippet-concepts**. For looking up existing Recipes, use **autosnippet-recipes**.
 
@@ -50,7 +50,7 @@ This skill tells the agent how to **submit module usage code** (that Cursor has
      - 后台自动停止，前台自动恢复
      ```
    - See [templates/recipes-setup/README.md](../../templates/recipes-setup/README.md) for detailed format guide & examples.
-7. **Auto-fill headers from project context**: Before submitting, **check `references/project-recipes-context.md`** (轻量索引) to find similar Recipes by title/trigger/category, then call MCP **`autosnippet_get_recipe(id)`** to get full content including headers. Copy the exact import format for `headers` field. If needed, call MCP **`autosnippet_context_search`** with the module name to find similar Recipes and extract their header patterns. This ensures consistency and correctness.
+7. **Auto-fill headers from project context**: Before submitting, **check `references/project-recipes-context.md`** (轻量索引) to find similar Recipes by title/trigger/category, then call MCP **`autosnippet_knowledge(operation=get, id)`** to get full content including headers. Copy the exact import format for `headers` field. If needed, call MCP **`autosnippet_search(mode=context)`** with the module name to find similar Recipes and extract their header patterns. This ensures consistency and correctness.
 8. **Primary flow (MCP preferred)**: Code is ready → Agent writes to `_draft_recipe.md` or calls `autosnippet_submit_knowledge_batch` / `autosnippet_submit_knowledge_batch` → candidates appear in Dashboard Candidates → user reviews and approves → Recipe is added to the knowledge base.
 9. **Alternative (Dashboard browser)**: Code is ready → user opens Dashboard (`asd ui` running) → **New Recipe** → **Use Copied Code** (paste the code) → AI fills title/summary/trigger/headers → **user reviews and approves** → saved to knowledge base.
 10. **Alternative (in editor)**: User adds **`// as:create`** in the source file, copies the code, saves → **watch** (from `asd watch` or `asd ui`) auto-adds to Candidates → user opens Dashboard **Candidates** to review and save.
@@ -161,13 +161,11 @@ Watch parses all such blocks and adds each as a separate candidate; prompt may s
 
 | Tool | Use |
 |------|-----|
-| `autosnippet_context_search` | On-demand semantic search of knowledge base; pass `query`, `limit?` |
+| `autosnippet_search(mode=context)` | On-demand semantic search of knowledge base; pass `query`, `limit?` |
 | `autosnippet_submit_knowledge_batch` | Submit draft .md as candidates: prefer draft folder + multiple files (not one big file); supports intro-only docs (no code—no Snippet). Pass `filePaths`, optional `targetName`, `deleteAfterSubmit`. **Delete the draft folder after submit** (e.g. `deleteAfterSubmit: true` or `rm -rf .autosnippet-drafts`). |
 | `autosnippet_submit_knowledge_batch` | Submit structured items (title, summary, trigger, language, code, usageGuide) for batch scan, etc. |
-| `autosnippet_submit_knowledge` | Submit single structured candidate with full V3 fields. |
+| `autosnippet_submit_knowledge` | Submit single structured candidate with full V3 fields. **严格前置校验**——缺少必要字段（title, language, content, kind, doClause, category, trigger, description, headers, usageGuide, knowledgeType, content.rationale）的提交将被直接拒绝，不入库。必须一次性提供所有字段。 |
 | `autosnippet_save_document` | Save a development document (design doc, debug report, ADR) — only needs title + markdown. See **autosnippet-devdocs** skill. |
-| `autosnippet_validate_candidate` | Pre-validate candidate quality before submission. |
-| `autosnippet_check_duplicate` | Check for duplicate Recipes before submission. |
 
 **Fallback when Dashboard not open**: Agent can always use `autosnippet_submit_knowledge_batch` or `autosnippet_submit_knowledge_batch` directly via MCP — no browser needed.
 

package/skills/autosnippet-guard/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: autosnippet-guard
-description: Guard checks code against project Recipe standards. Passive (// as:audit + watch) or active (MCP tools autosnippet_guard_check / autosnippet_guard_audit_files). Use when the user wants to audit, lint, or verify code compliance.
+description: Guard checks code against project Recipe standards. Passive (// as:audit + watch) or active (MCP tool autosnippet_guard — auto-routes by code/files params). Use when the user wants to audit, lint, or verify code compliance.
 ---
 
 # AutoSnippet Guard — Code Compliance Checking
 
-> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 autosnippet_health/autosnippet_capabilities；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
+> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 `autosnippet_health`；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
 
 **Use this skill when**: The user wants to **check** whether code meets **project standards** (规范 / Audit / Guard / Lint).
 
@@ -26,7 +26,7 @@ When the user wants **quick inline audit**:
 
 Agent can directly invoke Guard checks via MCP:
 
-#### Single Code Check: `autosnippet_guard_check`
+#### Single Code Check: `autosnippet_guard` (with `code` param)
 Check a code snippet against Guard rules. Best for quick inline checks.
 
 ```json
@@ -44,7 +44,7 @@ Returns: List of violations with `{ ruleId, severity, message, line, pattern }`.
 - Agent is reviewing code before suggesting changes
 - Quick single-file compliance check
 
-#### Multi-file Audit: `autosnippet_guard_audit_files`
+#### Multi-file Audit: `autosnippet_guard` (with `files[]` param)
 Batch audit multiple files against Guard rules. Results are automatically recorded to ViolationsStore (visible in Dashboard Guard page).
 
 ```json
@@ -80,31 +80,28 @@ Guard uses the **same Recipe content** in `AutoSnippet/recipes/` as the standard
 
 | Tool | Purpose | Input |
 |------|---------|-------|
-| `autosnippet_guard_check` | Single code Guard check | `code` (required), `language`, `filePath` |
-| `autosnippet_guard_audit_files` | Multi-file batch audit | `files[]` (path + optional content), `scope` |
-| `autosnippet_scan_project` | Full project scan + Guard audit | `maxFiles`, `includeContent` |
-| `autosnippet_compliance_report` | Compliance assessment report | `period` (all/daily/weekly/monthly) |
-| `autosnippet_list_rules` | List all Guard rules (kind=rule) | `limit`, `status`, `language`, `category` |
+| `autosnippet_guard` | Code Guard check (single or batch — auto-routed by params) | `code` for single, `files[]` for batch, `language`, `filePath`, `scope` |
+| `autosnippet_bootstrap(operation=scan)` | Full project scan + Guard audit | `maxFiles`, `includeContent` |
+| `autosnippet_knowledge(operation=list, kind=rule)` | List all Guard rules (kind=rule) | `limit`, `status`, `language`, `category` |
 
 ---
 
 ## Typical Agent Workflow
 
 ### Quick Check (user asks "检查这段代码")
-1. Call `autosnippet_guard_check` with the code
+1. Call `autosnippet_guard` with the code
 2. Present violations to user with severity and fix suggestions
-3. If user adopts fixes, optionally `autosnippet_confirm_usage` for the relevant Recipe
+3. If user adopts fixes, optionally `autosnippet_knowledge(operation=confirm_usage)` for the relevant Recipe
 
 ### Module Audit (user asks "审查网络模块")
-1. Call `autosnippet_get_target_files` to get file list
-2. Call `autosnippet_guard_audit_files` with the file paths
+1. Call `autosnippet_structure(operation=files)` to get file list
+2. Call `autosnippet_guard` with the file paths
 3. Summarize violations grouped by severity
 4. Suggest fixes based on Recipe standards
 
 ### Project-wide Compliance
-1. Call `autosnippet_scan_project` for full project scan
-2. Call `autosnippet_compliance_report` for compliance summary
-3. Present high-severity findings first
+1. Call `autosnippet_bootstrap(operation=scan)` for full project scan
+2. Present high-severity findings first
 
 ---
 
@@ -120,6 +117,6 @@ Guard uses the **same Recipe content** in `AutoSnippet/recipes/` as the standard
 
 - **autosnippet-recipes**: Recipe content IS the Guard standard. Use for looking up what the standard says.
 - **autosnippet-intent**: General router; may route Guard-related intents here.
-- **autosnippet-analysis**: Deep project scan + Guard baseline via `autosnippet_scan_project`.
+- **autosnippet-analysis**: Deep project scan + Guard baseline via `autosnippet_bootstrap(operation=scan)`.
 
 ```