autosnippet 3.2.18 → 3.2.20

package/dist/lib/shared/PathGuard.js

@@ -62,17 +62,17 @@ const PROJECT_WRITE_SCOPE_PREFIXES = [
 const PROJECT_ROOT_WRITABLE_FILES = ['.gitignore', '.env'];
 class PathGuard {
     targetPath;
-    /** @type {string|null} 项目根目录（绝对路径） */
+    /** 项目根目录（绝对路径） */
     #projectRoot = null;
-    /** @type {string|null} AutoSnippet 包自身根目录 */
+    /** AutoSnippet 包自身根目录 */
     #packageRoot = null;
-    /** @type {Set<string>} 额外允许的绝对路径前缀 */
+    /** 额外允许的绝对路径前缀 */
     #allowList = new Set();
-    /** @type {string|null} 知识库目录名（如 'AutoSnippet'） */
+    /** 知识库目录名（如 'AutoSnippet'） */
     #knowledgeBaseDir = null;
-    /** @type {boolean} 是否已配置 */
+    /** 是否已配置 */
     #configured = false;
-    /** @type {boolean} projectRoot 是否是 AutoSnippet 自身的开发仓库 */
+    /** projectRoot 是否是 AutoSnippet 自身的开发仓库 */
     #isDevRepo = false;
     /**
      * 配置 PathGuard（每个进程执行一次）

package/dist/lib/shared/schemas/mcp-tools.js

@@ -18,11 +18,14 @@ export const HealthInput = z.object({});
 //  2. autosnippet_search
 // ══════════════════════════════════════════════════════
 export const SearchInput = z.object({
-    query: z.string().min(1, 'query is required'),
-    mode: z.enum(['auto', 'keyword', 'bm25', 'semantic', 'context']).default('auto'),
-    kind: KindEnum.default('all'),
+    query: z.string().min(1, 'query is required').describe('搜索关键词或自然语言描述'),
+    mode: z
+        .enum(['auto', 'keyword', 'bm25', 'semantic', 'context'])
+        .default('auto')
+        .describe('auto=自动选策略 | keyword=精确匹配 | bm25=全文检索 | semantic=向量语义 | context=综合+上下文'),
+    kind: KindEnum.default('all').describe('过滤知识类型: all/rule/pattern/fact'),
     limit: z.number().int().min(1).max(100).default(10),
-    language: z.string().optional(),
+    language: z.string().optional().describe('按编程语言过滤，如 swift/typescript'),
     sessionId: z.string().optional(),
     sessionHistory: z.array(z.record(z.string(), z.unknown())).optional(),
 });
@@ -31,8 +34,11 @@ export const SearchInput = z.object({
 // ══════════════════════════════════════════════════════
 export const KnowledgeInput = z
     .object({
-    operation: z.enum(['list', 'get', 'insights', 'confirm_usage']).default('list'),
-    id: z.string().optional(),
+    operation: z
+        .enum(['list', 'get', 'insights', 'confirm_usage'])
+        .default('list')
+        .describe('list=列表 | get=单条详情(id) | insights=质量分析(id) | confirm_usage=记录采纳(id)'),
+    id: z.string().optional().describe('get/insights/confirm_usage 时必填'),
     kind: KindEnum.optional(),
     language: z.string().optional(),
     category: z.string().optional(),
@@ -53,8 +59,11 @@ export const KnowledgeInput = z
 //  4. autosnippet_structure
 // ══════════════════════════════════════════════════════
 export const StructureInput = z.object({
-    operation: z.enum(['targets', 'files', 'metadata']).default('targets'),
-    targetName: z.string().optional(),
+    operation: z
+        .enum(['targets', 'files', 'metadata'])
+        .default('targets')
+        .describe('targets=构建目标列表 | files=Target文件列表 | metadata=项目元数据'),
+    targetName: z.string().optional().describe('files 操作时指定目标名'),
     includeSummary: z.boolean().default(true),
     includeContent: z.boolean().default(false),
     contentMaxLines: z.number().int().min(1).default(100),
@@ -64,8 +73,10 @@ export const StructureInput = z.object({
 //  5. autosnippet_graph
 // ══════════════════════════════════════════════════════
 export const GraphInput = z.object({
-    operation: z.enum(['query', 'impact', 'path', 'stats']),
-    nodeId: z.string().optional(),
+    operation: z
+        .enum(['query', 'impact', 'path', 'stats'])
+        .describe('query=节点关系 | impact=影响分析 | path=路径查找 | stats=全局统计'),
+    nodeId: z.string().optional().describe('query/impact 时指定节点 ID'),
     nodeType: z.string().default('recipe'),
     fromId: z.string().optional(),
     toId: z.string().optional(),
@@ -77,8 +88,11 @@ export const GraphInput = z.object({
 //  6. autosnippet_call_context
 // ══════════════════════════════════════════════════════
 export const CallContextInput = z.object({
-    methodName: z.string().min(1, 'methodName is required'),
-    direction: z.enum(['callers', 'callees', 'both', 'impact']).default('both'),
+    methodName: z.string().min(1, 'methodName is required').describe('函数/方法名称，支持部分匹配'),
+    direction: z
+        .enum(['callers', 'callees', 'both', 'impact'])
+        .default('both')
+        .describe('callers=上游调用者 | callees=下游依赖 | both=双向 | impact=影响半径'),
     maxDepth: z.number().int().min(1).max(5).default(2),
 });
 // ══════════════════════════════════════════════════════
@@ -95,21 +109,33 @@ export const GuardInput = z.object({
 // ══════════════════════════════════════════════════════
 export const SubmitKnowledgeInput = z.object({
     // ── 必填字段 ──
-    title: TitleField,
-    language: LanguageField,
-    content: ContentSchema,
-    kind: StrictKindEnum,
-    doClause: z.string().min(1, 'doClause is required'),
-    dontClause: z.string().min(1, 'dontClause is required'),
-    whenClause: z.string().min(1, 'whenClause is required'),
-    coreCode: z.string().min(1, 'coreCode is required'),
-    category: z.string().min(1, 'category is required'),
-    trigger: z.string().min(1, 'trigger is required'),
-    description: z.string().min(1, 'description is required'),
-    headers: z.array(z.string()),
-    usageGuide: z.string().min(1, 'usageGuide is required'),
-    knowledgeType: z.string().min(1, 'knowledgeType is required'),
-    reasoning: ReasoningSchema,
+    title: TitleField.describe('知识标题，简洁明确'),
+    language: LanguageField.describe('编程语言，如 typescript/swift/python'),
+    content: ContentSchema.describe('内容对象: { pattern?: "代码片段", markdown?: "正文", rationale: "设计原理" }。pattern/markdown 至少提供一个，rationale 必填'),
+    kind: StrictKindEnum.describe('rule=规范约束 | pattern=代码模式 | fact=项目事实'),
+    doClause: z
+        .string()
+        .min(1, 'doClause is required')
+        .describe('✅ 应该怎么做（Channel A+B 硬依赖）'),
+    dontClause: z.string().min(1, 'dontClause is required').describe('❌ 不应该怎么做'),
+    whenClause: z.string().min(1, 'whenClause is required').describe('何时适用（Channel B 硬依赖）'),
+    coreCode: z.string().min(1, 'coreCode is required').describe('核心代码片段（Channel B 模板块）'),
+    category: z
+        .string()
+        .min(1, 'category is required')
+        .describe('View/Service/Tool/Model/Network/Storage/UI/Utility'),
+    trigger: z.string().min(1, 'trigger is required').describe('触发关键词，如 @NetworkMonitor'),
+    description: z.string().min(1, 'description is required').describe('一句话描述用途'),
+    headers: z.array(z.string()).describe('完整 import 语句列表'),
+    usageGuide: z
+        .string()
+        .min(1, 'usageGuide is required')
+        .describe('使用指南（Markdown，用 ### 分节：何时用/关键点/何时不用）'),
+    knowledgeType: z
+        .string()
+        .min(1, 'knowledgeType is required')
+        .describe('code-pattern/architecture/best-practice/code-standard 等'),
+    reasoning: ReasoningSchema.describe('推理对象: { whyStandard: "原因", sources: ["来源"], confidence: 0.0-1.0 }'),
     // ── 可选字段 ──
     topicHint: z.string().optional(),
     complexity: ComplexityEnum.optional(),
@@ -130,12 +156,18 @@ export const SubmitKnowledgeInput = z.object({
 //  8. autosnippet_submit_knowledge_batch
 // ══════════════════════════════════════════════════════
 export const SubmitKnowledgeBatchInput = z.object({
-    target_name: z.string().min(1, 'target_name is required'),
-    items: z.array(z.record(z.string(), z.unknown())).min(1, 'items array must not be empty'),
+    target_name: z
+        .string()
+        .min(1, 'target_name is required')
+        .describe('批量来源标识，如 network-module-scan'),
+    items: z
+        .array(z.record(z.string(), z.unknown()))
+        .min(1, 'items array must not be empty')
+        .describe('知识条目数组，每条字段同 submit_knowledge。content/reasoning 必须是对象'),
     source: z.string().default('cursor-scan'),
-    deduplicate: z.boolean().default(true),
+    deduplicate: z.boolean().default(true).describe('基于 title 自动去重，默认开启'),
     client_id: z.string().optional(),
-    dimensionId: z.string().optional(),
+    dimensionId: z.string().optional().describe('冷启动时关联维度 ID'),
 });
 // ══════════════════════════════════════════════════════
 //  9. autosnippet_save_document
@@ -152,12 +184,14 @@ export const SaveDocumentInput = z.object({
 //  10. autosnippet_skill
 // ══════════════════════════════════════════════════════
 export const SkillInput = z.object({
-    operation: z.enum(['list', 'load', 'create', 'update', 'delete', 'suggest']),
-    name: z.string().optional(),
-    skillName: z.string().optional(),
-    section: z.string().optional(),
-    description: z.string().optional(),
-    content: z.string().optional(),
+    operation: z
+        .enum(['list', 'load', 'create', 'update', 'delete', 'suggest'])
+        .describe('list=列表 | load=加载内容(name) | create=创建 | update=更新 | delete=删除 | suggest=推荐'),
+    name: z.string().optional().describe('Skill 名称（kebab-case，如 autosnippet-create）'),
+    skillName: z.string().optional().describe('name 的别名，与 name 等价'),
+    section: z.string().optional().describe('load 时过滤指定章节'),
+    description: z.string().optional().describe('create/update 时的简短描述'),
+    content: z.string().optional().describe('create/update 时的 Markdown 内容'),
     overwrite: z.boolean().default(false),
     createdBy: z.enum(['manual', 'user-ai', 'system-ai', 'external-ai']).default('external-ai'),
 });
@@ -172,7 +206,10 @@ export const DimensionCompleteInput = z.object({
     sessionId: z.string().optional(),
     dimensionId: z.string().min(1, 'dimensionId is required'),
     submittedRecipeIds: z.array(z.string()).optional(),
-    analysisText: z.string().min(1, 'analysisText is required'),
+    analysisText: z
+        .string()
+        .min(1, 'analysisText is required')
+        .describe('维度分析报告（Markdown）。写得越详细，生成的 Skill 质量越高；若过短，系统会自动从候选知识中合成。'),
     referencedFiles: z.array(z.string()).optional(),
     keyFindings: z.array(z.string()).optional(),
     candidateCount: z.number().int().min(0).optional(),
@@ -199,7 +236,8 @@ export const CapabilitiesInput = z.object({});
 //  13. autosnippet_task
 // ══════════════════════════════════════════════════════
 export const TaskInput = z.object({
-    operation: z.enum([
+    operation: z
+        .enum([
         'prime',
         'ready',
         'create',
@@ -219,7 +257,8 @@ export const TaskInput = z.object({
         'revise_decision',
         'unpin_decision',
         'list_decisions',
-    ]),
+    ])
+        .describe('会话: prime(首选) | ready。任务: create/claim/close/fail/defer/progress/show/list/stats/blocked。分解: decompose/dep_add/dep_tree。决策: record_decision/revise_decision/unpin_decision/list_decisions'),
     title: z.string().optional(),
     description: z.string().optional(),
     design: z.string().optional(),
@@ -276,7 +315,8 @@ export const EnrichCandidatesInput = z.object({
 // 15. autosnippet_knowledge_lifecycle
 export const KnowledgeLifecycleInput = z.object({
     id: IdField,
-    action: z.enum([
+    action: z
+        .enum([
         'submit',
         'approve',
         'reject',
@@ -285,8 +325,9 @@ export const KnowledgeLifecycleInput = z.object({
         'reactivate',
         'to_draft',
         'fast_track',
-    ]),
-    reason: z.string().optional(),
+    ])
+        .describe('approve/fast_track=发布 | reject=拒绝 | deprecate=废弃 | reactivate=恢复 | to_draft=回草稿'),
+    reason: z.string().optional().describe('reject/deprecate 时的理由'),
 });
 // 16. autosnippet_validate_candidate
 export const ValidateCandidateInput = z.object({

package/dist/scripts/install-vscode-copilot.js

@@ -151,16 +151,26 @@ function createCopilotInstructions() {
         log(`✓ 项目指令已存在，跳过创建`, 'yellow');
         return true;
     }
-    // 从模板文件读取内容
-    const templatePath = path.join(TEMPLATES_DIR, 'copilot-instructions.md');
+    // 从 conventions 模板生成（读模板 + 包装 HTML markers）
+    const templatePath = path.join(TEMPLATES_DIR, 'instructions/conventions.md');
     if (!fs.existsSync(templatePath)) {
         error(`✗ 模板文件不存在: ${templatePath}`);
         return false;
     }
-    const instructions = fs.readFileSync(templatePath, 'utf8');
+    const body = fs.readFileSync(templatePath, 'utf8').trimEnd();
+    const content = [
+        '<!-- autosnippet:begin -->',
+        '',
+        '# AutoSnippet Conventions',
+        '',
+        body,
+        '',
+        '<!-- autosnippet:end -->',
+        '',
+    ].join('\n');
     try {
         fs.mkdirSync(path.dirname(instructionsPath), { recursive: true });
-        fs.writeFileSync(instructionsPath, instructions, 'utf8');
+        fs.writeFileSync(instructionsPath, content, 'utf8');
         log(`✅ 项目指令生成完成: ${instructionsPath}`, 'green');
         return true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "3.2.18",
+  "version": "3.2.20",
   "description": "Extract code patterns into a knowledge base for AI coding assistants",
   "type": "module",
   "main": "dist/lib/bootstrap.js",

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 |