autosnippet 3.2.18 → 3.2.21

package/skills/autosnippet-create/SKILL.md

@@ -1,180 +1,180 @@
 ---
 name: autosnippet-create
-description: Guides the agent to submit module usage code (designed/written with Cursor) to the AutoSnippet web (Dashboard) so it is added to the knowledge base (Recipes). Use when the user or Cursor has finished writing usage code and wants to "提交到 web" or "加入知识库".
+description: Submit knowledge to AutoSnippet. Covers single/batch MCP submission, V3 field requirements, quality validation, and lifecycle. Use when user says "提交知识/加入知识库/create recipe" or agent needs to persist code patterns, rules, or facts.
 ---
 
-# AutoSnippet Create — Submit to Web, Add to AutoSnippet
-
-> 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**.
-
-## Instructions for the agent (read this first)
-
-1. **Goal**: When you (Cursor) have **finished writing or refining** module usage code, or the user says "把这段提交到 web / 加入知识库", guide them to **submit that code to the Dashboard** so it becomes a **Recipe** in `AutoSnippet/recipes/`.
-2. **Draft workflow**: Prefer **creating a draft folder** (e.g. `.autosnippet-drafts`), **one .md file per Recipe**, multiple draft files—**do not use one big file**. Call MCP **`autosnippet_submit_knowledge_batch`** with filePaths (the .md files in the draft folder) to submit to Candidates. **After submit, delete the draft folder** (use `deleteAfterSubmit: true` or run `rm -rf .autosnippet-drafts`). Single-item flow can use `_draft_recipe.md` and watch will auto-add to Candidates.
-3. **When user asks for "candidates"**: Use MCP **`autosnippet_submit_knowledge_batch`** for structured items (title/summary/trigger/code/usageGuide); use **`autosnippet_submit_knowledge_batch`** for Markdown draft files (prefer draft folder + multiple files; delete draft folder after submit).
-4. **One Recipe = one scenario**: If you are drafting content, **split** into multiple Recipes by scenario. Never combine multiple usage patterns into one Recipe file or one candidate.
-5. **Recipe candidates can be intro-only**: Intro-only docs (no code block) can be submitted as candidates; after approval they become Recipes and **do not generate a Snippet**—used only for search and Guard context.
-6. **MUST follow V3 Recipe format**: Include all required fields: `title`, `trigger`, `category` (one of 8 standard values), `language`, `kind` (rule/pattern/fact), `doClause`, `dontClause`, `whenClause`, `coreCode`, `description`, `content` (object with markdown, pattern, rationale), `headers` (complete import statements), `usageGuide` (Markdown ### 章节), `knowledgeType`, `reasoning` (whyStandard + sources + confidence).
-   - **MCP 不再使用项目内 AI**: 外部 Agent 必须自行填写所有字段。提交后检查返回值中的 `recipeReadyHints`，缺失字段需补全后重新提交。
-   - **禁止使用旧字段**: 不要使用 `code`、`summary_cn`、`summary_en`，改用 V3 `content` 对象 + `description`。
-   - **Placeholders**: Use IDE-appropriate placeholders in snippets — Xcode format `<#URL#>`, `<#Token#>` (auto-converted to VSCode `${N:...}` on install). Explain each placeholder in the Usage Guide.
-   - **Usage Guide structure (强制格式要求)**: 
-   * **MUST use structured format with clear section headings** (### heading name)：**NEVER put all content in one continuous line**
-   * **MUST use newlines (`\n`) to separate sections and bullet points** — at least 2-3 newlines between major sections
-   * **MUST use bullet lists (`-` or `*`)** for multi-item sections; avoid long paragraphs
-   * Recommended sections (按需包含):
-     - **什么时候用** (必填)：3～5 条适用场景，用 `-` 列表，每行一条
-     - **何时不用** (推荐)：排除场景、易误用情况，用 `-` 列表
-     - **使用步骤** (推荐)：1～3 步操作手册，用 `1.` `2.` `3.` 列表
-     - **关键点** (推荐)：易错点、约束条件、版本限制，用 `-` 列表
-     - **依赖与前置条件** (推荐)：模块、权限、最低版本，用 `-` 列表
-     - **错误处理** (推荐)：常见失败场景、重试/降级策略
-     - **性能与资源** (可选)：缓存、线程安全、内存
-     - **安全与合规** (可选)：敏感信息、日志脱敏
-     - **常见误用** (可选)：反例（❌）与规避方式（✅）
-     - **最佳实践** (可选)：推荐做法、设计模式
-     - **替代方案** (可选)：其他 Recipe 或方案对比
-     - **相关 Recipe** (推荐)：关联 trigger 或补充模式
-   * **BAD Example** (❌ 禁止这样写，AI生成会导致格式混乱)：`何时用：在需要…时；与…配合；或…时。关键点：…内部…；…支持…；…需…。`
-   * **GOOD Example** (✅ 应该这样写，清晰的多行结构)：
-     ```
-     ### 何时用
-     - App 启动时需持续监测网络状态
-     - 在应用生命周期管理类中统一启停
-     
-     ### 关键点
-     - 单例 sharedMonitor，线程安全
-     - startMonitoring 开始，stopMonitoring 停止
-     - 后台自动停止，前台自动恢复
-     ```
-   - 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_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.
-9. **Draft & clipboard auto-add**: When you write to **`_draft_recipe.md`** (project root) or user uses **`// as:create`** with clipboard content, **watch** automatically reads the draft/clipboard, adds it to **Candidates** (target `_draft` or `_watch`), and shows a **friendly prompt** (e.g. "已创建候选「xxx」，请在 Candidates 页审核" in notification and console). User only needs to open Dashboard **Candidates** to review and save — no manual copy-paste required.
-10. **Multiple recipes**: Prefer **one .md file per Recipe** in a draft folder (e.g. `.autosnippet-drafts/`), call **`autosnippet_submit_knowledge_batch`** with the list of file paths, then **delete the draft folder** after submit. Do not use one big file for many Recipes.
-11. **Project root** = directory with `AutoSnippet/AutoSnippet.boxspec.json`. All commands run from the project root.
+# AutoSnippet Create — 知识提交
+
+> 前置：MCP 工具返回统一 JSON Envelope `{ success, errorCode?, message?, data?, meta }`。操作前调用 `autosnippet_health` 确认服务可用。
+
+本 Skill 指导 Agent 将代码模式、规则、事实提交到 AutoSnippet 知识库。提交后的条目进入 **Candidates**（pending 状态），用户在 Dashboard 审核后发布。
+
+关联 Skill：**autosnippet-recipes**（检索已有知识）。
 
 ---
 
-## Submit to web (提交到 web) — main flow
+## 提交路径
 
-**Scenario**: Cursor has just written or refined **module usage code** (e.g. how to use a network API, how to load WebView). The user wants to add it to the **knowledge base** via the **web (Dashboard)**.
+| 路径 | 工具 | 适用场景 |
+|------|------|----------|
+| **单条提交** | `autosnippet_submit_knowledge` | Agent 精心构造一条完整知识 |
+| **批量提交** | `autosnippet_submit_knowledge_batch` | 冷启动维度分析、批量扫描 |
+| **Dashboard** | 浏览器 `http://localhost:3000` | 用户手动粘贴/扫描文件 |
 
-### Step 1: Content is ready
+**Agent 首选 MCP 提交**，无需浏览器。
 
-- **Code scenario**: Usage code is in current file or clipboard. If not copied, prompt user to copy the code block you provide.
-...rated a full Recipe (frontmatter, Snippet, Usage Guide), **prefer writing to draft file** `_draft_recipe.md` at project root. On save, **watch automatically reads the draft**, adds it to **Candidates** (target `_draft`), and shows a **friendly prompt** ("已创建候选「xxx」，请在 Candidates 页审核"). User opens Dashboard **Candidates** to review and save — no manual copy needed. Or output in copyable format in chat and guide user to copy → Dashboard → Use Copied Code → paste → review → save. **Do not write to `AutoSnippet/recipes/` or `AutoSnippet/snippets/`.**
-- **Candidate output rule**: When the user asks for candidates, **do not create files under `AutoSnippet/`**. Use **`autosnippet_submit_knowledge_batch`** for structured items; use **`autosnippet_submit_knowledge_batch`** for draft .md files (prefer draft folder + multiple files; delete draft folder after submit).
+---
 
-### Step 2: Open the web (Dashboard) in browser
+## 单条提交 — autosnippet_submit_knowledge
 
-- **Preferred**: Run in terminal: `open "http://localhost:3000/?action=create&source=clipboard"` (macOS). This opens the browser to the New Recipe page.
-- **Manual fallback**: User opens **`http://localhost:3000`** in browser (Dashboard 需已运行；若未运行，先执行 `asd ui`).
+一次提交一条完整的 V3 知识条目。即使部分字段校验未通过也会入库，返回中附带 `recipeReadyHints` 提示缺失字段。
 
-### Step 3: Submit via Dashboard
+### V3 必填字段（16 个）
 
-1. **Browser**: Run terminal command `open "http://localhost:3000/?action=create&source=clipboard"` (macOS) to open the browser.
-2. **Draft file (preferred for Agent)**: Write full Recipe MD to `_draft_recipe.md` at project root → watch auto-adds to Candidates. Or call MCP **`autosnippet_submit_knowledge_batch`** with draft file paths.
-3. **Manual fallback**: User opens **`http://localhost:3000`** in browser → **New Recipe** → **Use Copied Code** → paste.
-3. Pasted code: **Full Recipe MD** (with `---` frontmatter, `## Snippet / Code Reference`, `## AI Context / Usage Guide`) is parsed directly, **no AI rewrite**. Plain code still goes through AI analysis and fill.
-4. **User reviews and approves** — 人工审核 title/summary/category/trigger 及内容，确认无误后再保存。
-5. User **saves** → Recipe is written to **`AutoSnippet/recipes/`** — i.e. **added to the knowledge base**.
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title` | string | 知识标题，简洁明确 |
+| `description` | string | 一句话描述用途 |
+| `trigger` | string | 触发关键词，如 `@NetworkMonitor` |
+| `language` | string | 编程语言，如 `typescript`、`swift` |
+| `kind` | enum | `rule`（规范）/ `pattern`（模式）/ `fact`（事实） |
+| `category` | string | `View`/`Service`/`Tool`/`Model`/`Network`/`Storage`/`UI`/`Utility` |
+| `knowledgeType` | string | 知识类型标识 |
+| `doClause` | string | ✅ 应该做什么（Channel A+B 硬依赖） |
+| `dontClause` | string | ❌ 不应该做什么 |
+| `whenClause` | string | 何时适用（Channel B 硬依赖） |
+| `coreCode` | string | 核心代码片段 |
+| `headers` | string[] | 完整 import 语句列表 |
+| `usageGuide` | string | 使用指南（Markdown，见下方格式要求） |
+| `content` | object | `{ markdown: string, rationale: string }` 至少提供 markdown |
+| `reasoning` | object | `{ whyStandard: string, sources: string[], confidence: number }` |
 
-### Step 4: Optional — refresh Cursor's project context
+### 可选字段
 
-- After saving, the user can run **`asd install:cursor-skill`** in the project root to regenerate `references/project-recipes-context.md`（轻量索引）so Cursor's recipes skill has the latest index. This is optional and can be done later.
+`topicHint`、`complexity`（beginner/intermediate/advanced）、`scope`（universal/project-specific/target-specific）、`tags`（string[]）、`constraints`、`relations`、`skipDuplicateCheck`（默认 false）
 
----
+### usageGuide 格式要求
 
-## Alternative: Copy then jump to Web (Xcode and Cursor)
+**必须**使用 Markdown 分节，禁止写成一行长文本。
 
-**Option A — MCP Submit (Cursor 首选)**: After user confirms code, Agent calls **`autosnippet_submit_knowledge_batch`** (for .md drafts) or **`autosnippet_submit_knowledge_batch`** (for structured items) to submit directly to Candidates. User reviews in Dashboard.
+```markdown
+### 何时用
+- 场景 A
+- 场景 B
 
-**Option B — Browser (Dashboard)**: Run `open "http://localhost:3000/?action=create&source=clipboard"` to open Dashboard New Recipe page; page reads clipboard and fills.
+### 何时不用
+- 排除场景
 
-**Option B — // as:create (Xcode / in-editor)**: User adds **`// as:create`**, copies code, saves file. Requires **`asd watch`** or **`asd ui`** running. If clipboard has content, watch **automatically adds to Candidates** and shows a **friendly prompt** ("已创建候选「xxx」，请在 Candidates 页审核"); user opens Dashboard **Candidates** to review and save. If no clipboard, watch opens Dashboard with path for manual paste.
+### 使用步骤
+1. 第一步
+2. 第二步
 
----
+### 关键点
+- 注意事项 A
+- 注意事项 B
+```
 
-## Other ways to add to knowledge base (via web)
+可选章节：依赖与前置条件、错误处理、性能与资源、安全与合规、常见误用、替代方案、相关知识。
 
-| Way | When to use |
-|-----|-------------|
-| **New Recipe → Scan File** | Code is already in a project file; user enters relative path (e.g. `Sources/MyMod/Foo.m`) → Scan File → AI extracts → save in Dashboard. |
-| **Module Explorer** | Mine usage from a module Target: select Target → scan → review in Dashboard → save as Recipe (or Snippet + Recipe). |
-| **Candidates** | Batch: run **`asd ais <Target>`** or **`asd ais --all`** → open Dashboard **Candidates** → approve items → saved to knowledge base. |
+---
 
-All of these **submit through the web (Dashboard)** and result in content in **`AutoSnippet/recipes/`** (and optionally Snippet). The main flow above (Use Copied Code) is for **code that Cursor has just written**.
+## 批量提交 — autosnippet_submit_knowledge_batch
 
-**Friendly prompt (友好提示)**: When draft file or `// as:create` with clipboard is used, the system adds content to **Candidates** and shows: ① Console message "已创建候选「xxx」，请在 Candidates 页审核"; ② On macOS, a notification "已创建候选「xxx」，请在 Candidates 页审核". Tell the user: "内容已加入候选池，请打开 Dashboard 的 **Candidates** 页审核并保存即可。"
+一次提交多条知识。每条单独校验，不通过的拒绝但不阻塞其他。
 
-**When generating content**: If Agent has drafted Recipe or Snippet content, prefer writing to `_draft_recipe.md` so watch can auto-add to Candidates with friendly prompt. Or pass the full content to user for Dashboard submission.
+### 参数
 
-**When full copy is difficult**: Long content in chat is hard to copy fully. Agent should **write to draft file** at project root: `_draft_recipe.md` (or `_draft_snippet.md`), outside AutoSnippet/. **Watch automatically reads the draft on save** and adds it to **Candidates** (target `_draft`), then shows a **friendly prompt** ("已创建候选「xxx」，请在 Candidates 页审核"). User opens Dashboard **Candidates** → review and save — no manual copy or Scan File needed. Optional: add `_draft_*.md` to `.gitignore`. Delete draft after save if desired.
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `target_name` | ✅ | string | 批量来源标识（如 `network-module-scan`） |
+| `items` | ✅ | object[] | 知识条目数组，每条结构同单条提交的字段 |
+| `source` | | string | 来源标记，默认 `cursor-scan` |
+| `deduplicate` | | boolean | 基于 title 去重，默认 `true` |
 
-**Multiple recipes in one draft**: To submit **several Recipes at once**, write them in one `_draft_recipe.md`. Each Recipe is a **complete block** starting with `---` (frontmatter). **Separate blocks with a blank line, then the next block starts with `---`**. Example structure:
-```
----
-title: Recipe A
-trigger: @foo
-...
----
+### 返回值
 
-## Snippet / Code Reference
-```objc
-code A
+```json
+{
+  "count": 3,
+  "total": 5,
+  "ids": ["id1", "id2", "id3"],
+  "errors": ["item[2]: missing doClause"],
+  "rejectedItems": [2, 4],
+  "rejectedSummary": { "commonMissingFields": ["doClause", "reasoning"] }
+}
 ```
 
-## AI Context / Usage Guide
-usage A
+**批量提交校验更严格**：单条提交校验不通过仍入库（附 hints），**批量提交校验不通过直接拒绝**。
 
 ---
-title: Recipe B
-...
----
 
-## Snippet / Code Reference
-...
+## 提交工作流
+
+### 标准流程（Agent 通过 MCP）
+
+```
+1. 分析代码 → 构造 V3 字段
+2. autosnippet_submit_knowledge / _batch → 入库为 pending
+3. 检查返回值：
+   - 成功 → 告知用户"已提交，请在 Dashboard Candidates 审核"
+   - 有 rejectedItems → 根据 rejectedSummary.commonMissingFields 补全后重试
+4. [可选] autosnippet_enrich_candidates → 诊断候选字段完整性
 ```
-Watch parses all such blocks and adds each as a separate candidate; prompt may say "已创建 N 条候选".
+
+### 一条知识一个场景
+
+拆分原则：不同使用场景、不同 API 入口、不同配置方式→各自一条知识。禁止将多个模式合并为一条。
 
 ---
 
-## Quick reference
+## 提交后管理
 
-| User / Cursor situation | Action |
-|-------------------------|--------|
-| "把这段提交到 web / 加入知识库" (code just written) | 1) 提示用户复制代码；2) 写入 `_draft_recipe.md` 或调用 **`autosnippet_submit_knowledge_batch`**；3) 若需 Dashboard，运行 `open "http://localhost:3000/?action=create&source=clipboard"`；4) 用户粘贴并保存。 |
-| Agent 起草了 Recipe/Snippet 内容 | **Prefer**: Write to `_draft_recipe.md` (project root) → save → **watch 自动读取并加入候选池**，并给出友好提示 → 用户打开 Dashboard **Candidates** 审核并保存。无需手动复制。 |
-| Code in current file, want to submit from editor | **MCP**：`autosnippet_submit_knowledge_batch`（写草稿 .md 后提交）。或 Add **`// as:create`**, copy, save；确保 **`asd watch`** / **`asd ui`** 运行；有剪贴板时自动加入候选并友好提示。 |
-| Code already in a file (path known) | 打开 **`http://localhost:3000`** → New Recipe → enter path → **Scan File** → review → save. |
-| Agent 起草内容无法完整复制 | Write to `_draft_recipe.md` → save → **watch 自动读取草稿、加入候选并友好提示** → 用户打开 **Candidates** 审核保存。 |
-| Batch from Target | **`asd ais <Target>`** → 打开 **`http://localhost:3000`** → **Candidates** → approve. |
+| 需求 | 工具 |
+|------|------|
+| 查看候选状态 | `autosnippet_knowledge(operation=list)` |
+| 诊断缺失字段 | `autosnippet_enrich_candidates` |
+| 审核/发布 | `autosnippet_knowledge_lifecycle(operation=approve/publish/fast_track)` |
+| 搜索已有知识避免重复 | `autosnippet_search(mode=context, query=...)` |
 
 ---
 
-## MCP Tools (when Dashboard is running)
+## kind 路由与管线影响
 
-| Tool | Use |
-|------|-----|
-| `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. **严格前置校验**——缺少必要字段（title, language, content, kind, doClause, dontClause, whenClause, coreCode, category, trigger, description, headers, usageGuide, knowledgeType, reasoning, content.rationale）的提交将被直接拒绝，不入库。必须一次性提供所有字段。 |
-| `autosnippet_save_document` | Save a development document (design doc, debug report, ADR) — only needs title + markdown. See **autosnippet-devdocs** skill. |
+| kind | 用途 | 管线产出 |
+|------|------|----------|
+| `rule` | 编码规范、约束 | → Channel A（.mdc 规则文件） |
+| `pattern` | 代码模式、用法 | → Channel B（.mdc 模式文件 + Snippet） |
+| `fact` | 项目事实、架构决策 | → 搜索/Guard 上下文，不直接产出文件 |
 
-**Fallback when Dashboard not open**: Agent can always use `autosnippet_submit_knowledge_batch` or `autosnippet_submit_knowledge_batch` directly via MCP — no browser needed.
+`doClause` 是 Channel A+B 的**硬依赖**——缺少此字段则完全无法生成 .mdc 文件。
 
 ---
 
-## Relation to other skills
-
-- **autosnippet-concepts**: What the knowledge base and Recipe are; where they live.
-- **autosnippet-recipes**: Read or search existing Recipe content; get project context.
-- **autosnippet-structure**: Dependency structure (unrelated to submit flow).
-
+## 示例：提交一条知识
+
+```json
+{
+  "title": "Network Monitor — 网络状态监听",
+  "description": "使用 NWPathMonitor 监听网络连通性变化",
+  "trigger": "@NetworkMonitor",
+  "language": "swift",
+  "kind": "pattern",
+  "category": "Network",
+  "knowledgeType": "api-usage",
+  "doClause": "使用 NWPathMonitor 监听网络状态变化，在主队列回调更新 UI",
+  "dontClause": "不要用 Reachability 旧库，不要在后台线程直接更新 UI",
+  "whenClause": "需要实时感知网络连通性变化时",
+  "coreCode": "let monitor = NWPathMonitor()\nmonitor.pathUpdateHandler = { path in\n  DispatchQueue.main.async {\n    self.isConnected = path.status == .satisfied\n  }\n}\nmonitor.start(queue: DispatchQueue.global())",
+  "headers": ["import Network"],
+  "usageGuide": "### 何时用\n- App 需要实时网络状态\n- 启动时初始化一次\n\n### 关键点\n- 单例模式访问 sharedMonitor\n- start() 开始监听，cancel() 停止\n- 回调在 global queue，更新 UI 需切主线程",
+  "content": {
+    "markdown": "NWPathMonitor 是 iOS 12+ 推荐的网络状态监听方案，替代废弃的 Reachability。",
+    "rationale": "Apple 官方推荐，线程安全，支持蜂窝/WiFi/有线判断。"
+  },
+  "reasoning": {
+    "whyStandard": "Apple Developer Documentation 推荐方案，替代 SCNetworkReachability",
+    "sources": ["Apple Developer Documentation - NWPathMonitor"],
+    "confidence": 0.95
+  }
+}
 ```

package/skills/autosnippet-devdocs/SKILL.md

@@ -80,11 +80,10 @@ Documents are stored as `knowledgeType: 'dev-document'` in the knowledge DB. The
 - For ADRs, use the structure: Context → Decision → Consequences
 - For debug reports: Symptom → Investigation → Root Cause → Fix
 
-## Relation to other skills
+## Related Skills
 
 | Skill | When to use |
 |-------|-------------|
 | `autosnippet-create` | Saving **code patterns/recipes** (needs trigger, doClause, etc.) |
 | `autosnippet-devdocs` (this) | Saving **prose documents** (only needs title + markdown) |
 | `autosnippet-recipes` | Looking up existing knowledge |
-| `autosnippet-concepts` | Understanding AutoSnippet concepts |

package/skills/autosnippet-guard/SKILL.md

@@ -1,122 +1,53 @@
 ---
 name: autosnippet-guard
-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.
+description: Guard checks code against project Recipe standards via 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`；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
-
 **Use this skill when**: The user wants to **check** whether code meets **project standards** (规范 / Audit / Guard / Lint).
 
 ---
 
-## Two Modes of Guard
-
-### Mode 1: Passive — `// as:audit` trigger (requires `asd watch` or `asd ui`)
-
-When the user wants **quick inline audit**:
-1. Add `// as:audit` (or `// as:audit keyword`) in the file
-2. Save the file → watch detects the save → runs AI review against Recipe standards
-3. Results output to terminal / notification
-
-**Recommendation wording**: "在文件中加 `// as:audit`，保存后 watch 会用知识库标准审查代码，结果输出到终端。"
-
-### Mode 2: Active — MCP tools (Agent-driven, no watch needed)
-
-Agent can directly invoke Guard checks via MCP:
-
-#### Single Code Check: `autosnippet_guard` (with `code` param)
-Check a code snippet against Guard rules. Best for quick inline checks.
+## MCP Tool: `autosnippet_guard`
 
+**Single code check** (`code` param):
 ```json
-{
-  "code": "URLSession.shared.dataTask(with: url) { ... }",
-  "language": "objc",
-  "filePath": "Sources/Network/OldAPI.m"
-}
+{ "code": "URLSession.shared.dataTask(with: url) { ... }", "language": "objc", "filePath": "Sources/Network/OldAPI.m" }
 ```
 
-Returns: List of violations with `{ ruleId, severity, message, line, pattern }`.
-
-**When to use**: 
-- User pastes code and asks "这段符合规范吗？"
-- Agent is reviewing code before suggesting changes
-- Quick single-file compliance check
-
-#### 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).
-
+**Multi-file audit** (`files[]` param):
 ```json
-{
-  "files": [
-    { "path": "/path/to/Sources/Network/APIClient.m" },
-    { "path": "/path/to/Sources/Network/RequestManager.m", "content": "..." }
-  ],
-  "scope": "project"
-}
+{ "files": [{ "path": "Sources/Network/APIClient.m" }, { "path": "Sources/Network/RequestManager.m" }], "scope": "project" }
 ```
 
-Returns: Per-file violation details with severity and suggestions.
-
-**When to use**:
-- User says "审查一下网络模块" / "检查这几个文件"
-- After batch code changes, verify compliance
-- Periodic module-level audit
+Returns violations with `{ ruleId, severity, message, line, pattern }`. Batch results auto-recorded to ViolationsStore.
 
 ---
 
 ## Guard Knowledge Source
 
-Guard uses the **same Recipe content** in `AutoSnippet/recipes/` as the standard:
-- **kind=rule** Recipes are enforced as Guard rules (severity: error/warning/info)
-- **kind=pattern** Recipes serve as best-practice references
-- Guard rules with `constraints.guards[].pattern` define regex patterns for automated detection
-- No separate config needed — Recipe IS the Guard standard
+Guard uses **Recipe content** as the standard — no separate config:
+- **kind=rule** → enforced as Guard rules (severity: error/warning/info)
+- **kind=pattern** → best-practice references
+- `constraints.guards[].pattern` → regex patterns for automated detection
 
 ---
 
-## MCP Tools for Guard
+## Agent Workflow
 
-| Tool | Purpose | Input |
-|------|---------|-------|
-| `autosnippet_guard` | Code Guard check (single or batch — auto-routed by params) | `code` for single, `files[]` for batch, `language`, `filePath`, `scope` |
-| `autosnippet_bootstrap` | Full project scan + Guard audit (no params, returns Mission Briefing) | — |
-| `autosnippet_knowledge(operation=list, kind=rule)` | List all Guard rules (kind=rule) | `limit`, `status`, `language`, `category` |
+### Quick Check ("检查这段代码")
+1. `autosnippet_guard` with code → present violations + fix suggestions
 
----
-
-## Typical Agent Workflow
-
-### Quick Check (user asks "检查这段代码")
-1. Call `autosnippet_guard` with the code
-2. Present violations to user with severity and fix suggestions
-3. If user adopts fixes, optionally `autosnippet_knowledge(operation=confirm_usage)` for the relevant Recipe
-
-### Module Audit (user asks "审查网络模块")
-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_bootstrap` (no params) for full project scan
-2. Present high-severity findings first
+### Module Audit ("审查网络模块")
+1. `autosnippet_structure(operation=files)` → get file list
+2. `autosnippet_guard` with file paths → summarize by severity
 
----
-
-## Audit trigger syntax
-
-- `// as:audit` — audit entire file against all rules
-- `// as:audit keyword` — audit with specific keyword focus  
-- `// as:lint` — **deprecated**, use `// as:audit`
+### Project-wide
+1. `autosnippet_bootstrap` → full project scan including Guard audit
 
 ---
 
 ## Related Skills
 
-- **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_bootstrap`.
-
-```
+- **autosnippet-recipes**: Recipe content IS the Guard standard