autosnippet 3.2.18 → 3.2.20

package/skills/autosnippet-analysis/SKILL.md

@@ -1,169 +0,0 @@
----
-name: autosnippet-analysis
-description: Deep project analysis — full scan + semantic field enrichment + gap fill before Recipe creation. Both Cursor Agent and internal AI share the same capability set.
----
-
-# AutoSnippet — Deep Project Analysis & Semantic Enrichment
-
-> Self-check & Fallback: MCP 工具返回统一 JSON Envelope（{ success, errorCode?, message?, data?, meta }）。重操作前调用 `autosnippet_health`；失败时不在同一轮重试，转用静态上下文或缩小范围后再试。
-
-## Core Principle
-
-**MCP 工具负责数据采集 + 静态检查；你（Agent）负责语义理解；Agent 直接填写完整字段后通过 `autosnippet_submit_knowledge` 提交。**
-
-**⚠️ 严格提交规则**：`autosnippet_submit_knowledge` 实施严格前置校验——缺少必要字段的提交将被**直接拒绝（不入库）**。必须在单次调用中一次性提供所有必填字段（title, language, content, kind, doClause, dontClause, whenClause, coreCode, category, trigger, description, headers, usageGuide, knowledgeType, reasoning, content.rationale）。不要分步提交或先提交再补全。
-
----
-
-## Capability 1: 全项目扫描 → 提交候选
-
-> **首次接入项目？** 使用 **autosnippet-coldstart** Skill — 完整的 9 维度冷启动流程（含架构分析、项目特征、Agent 注意事项），比本 Skill 的扫描流程更全面。
-> 本 Capability 适用于已有知识库后的**增量补充扫描**。
-
-### When to Use
-用户说："全项目扫描"、"分析我的项目"、"提取架构模式"、"生成知识库"。
-
-### Workflow
-
-#### Phase 1: Collect & Baseline
-1. 调用 `autosnippet_bootstrap`（无参数）获取 Mission Briefing（文件列表 + Guard 审计基线）
-2. 审视 Guard 违规 — 静态规则问题 (命名/API 使用/废弃 API)
-3. 确定高优先级文件 (核心模块/共享工具/Service 层)
-
-#### Phase 2: Semantic Deep-Read
-读取代码文件，逐维度分析：
-
-| 分析维度 | 寻找什么 | knowledgeType | 对应字段 |
-|---------|---------|---------------|---------|
-| **架构模式** | 分层架构、MVVM/MVC、依赖注入 | `architecture` | rationale: 为什么选这种架构 |
-| **代码模式** | 封装方式、公共 API 设计、工厂/单例 | `code-pattern` | steps: 如何采用该模式 |
-| **代码规范** | 命名规范、文件组织、注释风格 | `code-standard` | constraints.preconditions: 前置条件 |
-| **最佳实践** | 错误处理、并发、内存管理 | `best-practice` | rationale: 为什么这是最佳实践 |
-| **调用链** | 关键业务的调用路径 | `call-chain` | steps: 调用顺序 |
-| **数据流** | 状态管理、模块间数据传递 | `data-flow` | steps: 数据流向 |
-| **模块依赖** | 依赖边界、约束 | `module-dependency` | constraints: 边界约束 |
-| **Bug 修复** | 常见修复模式、defensive coding | `solution` | rationale: 为什么这样修 |
-
-#### Phase 3: Submit with Full Semantic Fields
-**每条候选必须填充以下语义字段**（不留空）：
-
-```json
-{
-  "title": "网络层统一错误处理模式",
-  "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",
-  "steps": [
-    { "title": "创建 Error 枚举", "description": "在 Network/ 下创建 NetworkError.swift", "code": "enum NetworkError: Error { ... }" },
-    { "title": "封装请求方法", "description": "所有请求统一通过 APIClient.request()", "code": "" }
-  ],
-  "constraints": {
-    "preconditions": ["iOS 15+", "需引入 Combine framework"],
-    "boundaries": ["不可用于 WebSocket 连接"],
-    "sideEffects": []
-  },
-  "tags": ["networking", "error-handling"],
-  "reasoning": {
-    "whyStandard": "项目中 15 个网络模块均采用此模式",
-    "sources": ["Sources/Network/APIClient.swift", "Sources/Network/ErrorHandler.swift"],
-    "confidence": 0.9
-  }
-}
-```
-
-Use `autosnippet_submit_knowledge_batch` for batch submission.
-
-#### Phase 4: Guard Deep Audit (Optional)
-对特定文件调用 `autosnippet_guard` (files[]) 做深度规范审计。
-
----
-
-## Capability 2: 语义字段补全（需要 AI 理解的字段）
-
-### When to Use
-- 候选已有 title/code/language 但缺少深度语义字段
-- 候选要晋升为 Recipe 前，需要补全
-- 用户说："补全候选字段"、"enrich"、"查漏补缺"
-
-### 需要语义理解的 6 个字段
-
-| 字段 | 为什么需要 AI | 示例 |
-|------|-------------|------|
-| **rationale** | 需理解设计意图，回答"为什么这样做" | "该模式使用 Builder 而非直接构造，因为参数超过 5 个且多数可选" |
-| **knowledgeType** | 需理解知识本质（规范/模式/事实） | `architecture` vs `code-pattern` vs `best-practice` |
-| **complexity** | 需评估使用难度 | `beginner`（一行调用）vs `advanced`（需理解泛型+协议组合） |
-| **scope** | 需判断适用范围 | `universal`（通用 Singleton）vs `project-specific`（依赖项目 Config） |
-| **steps** | 需拆解实施步骤 | `[{title: "创建协议", description: "...", code: "..."}]` |
-| **constraints.preconditions** | 需理解前置条件 | `["iOS 15+", "需先配置 Firebase", "依赖 NetworkModule"]` |
-
-### Workflow for Enrichment
-
-**方式 A: 你（Agent）直接补全**
-在分析代码时，直接填写所有 6 个语义字段到 `autosnippet_submit_knowledge` 调用中。
-
-**方式 B: 对已有候选调用 AI 补全**
-> 注：`autosnippet_enrich_candidates` 已移入 admin 层级，Agent 推荐使用方式 A 直接填写完整字段。
-
-**方式 C: 候选字段诊断**
-```
-autosnippet_enrich_candidates({ candidateIds: ["id1", "id2", ...] })
-```
-诊断候选缺失字段（不使用 AI），Agent 根据诊断结果自行补全。
-
----
-
-## Capability 3: 候选 → Recipe 查漏补缺
-
-### When to Use
-- 用户准备将候选发布为 Recipe
-- 用户说："准备发布"、"候选检查"、"Recipe 就绪检查"
-
-### Workflow
-
-1. 对目标候选做结构补齐（确保所有字段完整）
-2. 调用 `autosnippet_enrich_candidates` 诊断候选缺失字段，根据结果自行补全
-3. 提交时使用 `autosnippet_submit_knowledge`（内置自动校验 + 去重检查）
-4. 报告补全情况 + 缺失字段 + 重复风险
-5. 如缺失字段 AI 无法填充，提示用户手动补充
-
-### Recipe 必备字段检查清单
-
-| 字段 | 重要性 | AI 可填? |
-|------|-------|---------|
-| title | ★★★ 必填 | ✅ |
-| content (markdown+pattern+rationale) | ★★★ 必填 | ✅ |
-| language | ★★★ 必填 | ✅ |
-| kind (rule/pattern/fact) | ★★★ 必填 | ✅ |
-| doClause | ★★★ 必填 | ✅ |
-| category | ★★★ 必填 | ✅ |
-| trigger | ★★★ 必填 | ✅ |
-| description | ★★★ 必填 | ✅ |
-| headers | ★★★ 必填 | ✅ |
-| usageGuide | ★★★ 必填 | ✅ |
-| knowledgeType | ★★★ 必填 | ✅ |
-| reasoning | ★★★ 必填 | Agent 必须自己填 |
-| complexity | ★★☆ 推荐 | ✅ |
-| scope | ★★☆ 推荐 | ✅ |
-| steps | ★★☆ 推荐 | ✅ |
-| constraints.preconditions | ★★☆ 推荐 | ✅ |
-
----
-
-## Related Skills
-
-- **autosnippet-candidates**: 完整候选字段模型 + 提交指南
-- **autosnippet-structure**: 项目结构发现 (targets / files / dependencies)
-- **autosnippet-guard**: Guard 触发机制 (`// as:audit`)
-- **autosnippet-recipes**: Recipe 内容与查询

package/skills/autosnippet-candidates/SKILL.md

@@ -1,367 +0,0 @@
----
-name: autosnippet-candidates
-description: Generate Recipe candidates with full V3 structured information. Single file scan or batch Target scan. Agent extracts rich metadata matching the complete Recipe schema. Agent submits candidates only; Recipe creation/modification is human-only.
----
-
-# AutoSnippet - Generate Candidates with Structured Content (v3.1)
-
-> 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
-
-**Agent CANNOT directly produce or modify Recipes.** Agent can only:
-- Submit Recipe **candidates** (submit_candidate / submit_candidates / submit_draft_recipes)
-- **Validate/enhance** candidates (validate_candidate / check_duplicate)
-- **Search/query** existing Recipes for context and dedup
-
-Recipe creation, review, publish, update, deprecate, delete are **human-only via Dashboard**.
-
----
-
-## ⚠️ Recipe-Ready Checklist (CRITICAL — STRICT ENFORCEMENT)
-
-**MCP 不再使用项目内 AI**——外部 Agent 必须自行提供所有字段。**缺少必要字段的提交将被直接拒绝（不入库）**，不会降级处理。
-
-**严格规则**：
-- 所有必填字段必须在**单次调用**中一次性提供
-- 缺字段的提交会返回 `errorCode: INCOMPLETE_SUBMISSION`，不会创建任何记录
-- **禁止**先提交不完整数据再补全重新提交 — 这会浪费 Token 和时间
-- 提交前自行确认所有字段齐全，一次通过
-
-| 字段 | 级别 | 要求 | 示例 |
-|------|------|------|------|
-| `title` | 必填 | 中文简短标题（≤20字） | "视频封面 Cell 16:9 布局与时长格式化" |
-| `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` |
-| `description` | 必填 | 中文摘要 ≤80字 | "封面图片 16:9 自适应布局…" |
-| `headers` | 必填 | 完整 import 语句数组 | `["#import <UIKit/UIKit.h>"]` |
-| `usageGuide` | 必填 | Markdown ### 章节格式 | 描述何时/如何使用此知识 |
-| `knowledgeType` | 必填 | 知识维度 | `code-pattern` / `architecture` / `best-practice` 等 |
-| `reasoning` | 强烈建议 | whyStandard + sources + confidence | 见 Layer 6 |
-
-**工作流程**：
-1. Agent 提取候选时**一次性填写全部必填字段**
-2. 调用 `autosnippet_submit_knowledge` 提交
-3. 若返回 `INCOMPLETE_SUBMISSION` → 检查 `missingFields`，补齐后重新提交
-4. 提交成功 = 候选可直接审核为 Recipe
-
----
-
-## Quick Start
-
-**Scenario 1: User says "scan a module/file to generate candidates"**
-1. Read target file/module (including README or examples)
-2. Extract public APIs, usage examples, doc comments
-3. Generate multiple candidates (one pattern per candidate)
-4. Parallel query existing Recipes -> mark similarity/conflicts
-5. Score and rank -> submit Candidates
-
-**Scenario 2: User says "batch scan Target"**
-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
-
----
-
-## V3 Complete Candidate Field Model
-
-Every candidate submitted via `submit_candidate` or `submit_candidates` supports the following fields. **The richer the information, the higher the quality of the resulting Recipe.**
-
-### Layer 1: Core Identity (required — submission fails without these)
-
-| Field | Type | Example |
-|-------|------|---------|
-| **title** | string | "网络请求统一封装 - APIClient" |
-| **content** | object | `{ markdown: "≥200字 Markdown 正文", pattern: "核心代码模式", rationale: "设计原理" }` |
-| **language** | string | swift / objc / javascript / python etc. |
-| **kind** | string | `rule` / `pattern` / `fact` |
-| **doClause** | string | 英文祈使句正向指令（≠60 tokens）|
-| **trigger** | string | `@` 开头 kebab-case，如 `@api-client` |
-| **description** | string | 中文摘要 ≤80字 |
-| **category** | string | View / Service / Tool / Model / Network / Storage / UI / Utility |
-| **headers** | string[] | 完整 import 语句数组，无 import 传 `[]` |
-| **usageGuide** | string | Markdown ### 章节格式的使用指南 |
-| **knowledgeType** | string | `code-pattern` / `architecture` / `best-practice` 等 |
-
-### Layer 2: Classification (strongly recommended — enables filtering & search)
-
-| Field | Type | Values / Example |
-|-------|------|-----------------|
-| **category** | string | View / Service / Tool / Model / Network / Storage / UI / Utility |
-| **knowledgeType** | string | `code-pattern` \| `architecture` \| `best-practice` \| `code-standard` \| `code-relation` \| `inheritance` \| `call-chain` \| `data-flow` \| `module-dependency` \| `boundary-constraint` \| `code-style` \| `solution` \| `dev-document` |
-| **complexity** | string | `beginner` \| `intermediate` \| `advanced` |
-| **scope** | string | `universal` (通用) \| `project-specific` (本项目) \| `target-specific` (特定 Target) |
-| **tags** | string[] | `["networking", "async-await", "error-handling"]` |
-
-### Layer 3: Structured Content (high value — 代码变更与实施步骤)
-
-> **注意**: Layer 1 已包含 V3 全部必填字段（title, content, language, kind, doClause, dontClause, whenClause, coreCode, trigger, description, category, headers, usageGuide, knowledgeType, reasoning）。本层为可选的高价值补充字段。
-
-| Field | Type | Structure |
-|-------|------|-----------|
-| **rationale** | string | 设计原理：为什么选择这种模式、优于其他方案的原因 |
-| **steps** | array | 实施步骤：`[{title: "创建 Service", description: "在 Services/ 下创建…", code: "class MyService { ... }"}]` |
-| **codeChanges** | array | 代码变更：`[{file: "APIClient.swift", before: "URLSession.shared...", after: "apiClient.request(...)", explanation: "替换为统一封装"}]` |
-| **verification** | object | 验证方式：`{method: "unit-test", expectedResult: "所有请求通过 apiClient", testCode: "func testAPI() {...}"}` |
-| **headers** | string[] | 需要的 import/include：`["import Foundation", "import Combine"]` |
-
-### Layer 5: Constraints & Relations (high value — enables dependency analysis & Guard rules)
-
-| Field | Type | Structure |
-|-------|------|-----------|
-| **constraints** | object | `{boundaries: ["仅限 iOS 15+"], preconditions: ["需先初始化 NetworkConfig"], sideEffects: ["修改全局代理设置"], guards: [{pattern: "URLSession\\.shared", severity: "warning", message: "请使用 APIClient"}]}` |
-| **relations** | object | `{dependsOn: [{target: "NetworkConfig", description: "依赖网络配置"}], extends: [...], conflicts: [...], related: [...], inherits: [...], implements: [...], calls: [...], dataFlow: [...]}` — 每项 `{target, description}` |
-
-### Layer 6: Reasoning 推理依据 (required — Agent 必填，缺少将被拒绝)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **reasoning.whyStandard** | string | 为什么这段代码值得沉淀为知识。必须回答：“它解决了什么问题”“为什么是标准做法”“不用会怎样” |
-| **reasoning.sources** | string[] | 来源列表：文件路径、文档链接、上下文引用。如 `["Sources/Network/BiliAPI.swift", "README.md#networking"]` |
-| **reasoning.confidence** | number | 置信度 0-1。`0.9`=明确的项目标准，`0.7`=常见模式但未明确规定，`0.5`=可能有用但不确定 |
-| reasoning.qualitySignals | object | 质量信号（可选）：`{clarity: 0.9, reusability: 0.8, importance: 0.7}` |
-| reasoning.alternatives | string[] | 备选方案（可选）：如果存在替代实现，简要描述 |
-
-> **Reasoning 为什么重要？** 它是审核员判断候选质量的关键依据。没有 Reasoning 的候选无法通过校验。
-
-### Layer 7: Quality & Source (optional — helps prioritize review)
-
-| Field | Type | Structure |
-|-------|------|-----------|
-| **quality** | object | `{codeCompleteness: 0.9, projectAdaptation: 0.8, documentationClarity: 0.85}` (0-1) |
-| **sourceFile** | string | 来源文件路径（相对于项目根目录） |
-
----
-
-## Information Extraction Strategy
-
-### Per-File Analysis Checklist
-
-When scanning a source file, systematically extract:
-
-1. **What does it do?** → `title`, `description`, `summary`, `category`
-2. **How to use it?** → `code` (complete usage example), `trigger`, `usageGuide`, `headers`
-3. **Why this design?** → `rationale`, `knowledgeType`
-4. **Why is it worth extracting?** → `reasoning.whyStandard` (解决了什么问题？不用会怎样？), `reasoning.confidence`
-5. **Where does it come from?** → `reasoning.sources` (文件路径), `sourceFile`
-6. **How to implement step by step?** → `steps`, `codeChanges`
-7. **What are the constraints?** → `constraints` (boundaries, preconditions, sideEffects)
-8. **Any inline rules to enforce?** → `constraints.guards` (regex pattern + severity + message)
-9. **What's the difficulty?** → `complexity`
-10. **What does it depend on / relate to?** → `relations`, `headers`
-11. **How to verify correctness?** → `verification`
-12. **Quality assessment** → `quality` (code completeness, project adaptation, doc clarity)
-
-### Knowledge Type Decision Tree
-
-```
-Is it a coding rule/standard/naming convention?
-  → code-standard | code-style | boundary-constraint
-
-Is it a reusable code pattern/template?
-  → code-pattern | solution | best-practice
-
-Is it describing code structure/relationships?
-  → code-relation | inheritance | call-chain | data-flow | module-dependency
-
-Is it an architectural decision or design pattern?
-  → architecture
-```
-
-### Extracting Reasoning (MANDATORY for every candidate)
-
-Agent must answer three questions for every candidate:
-
-1. **whyStandard** — "Why is this code worth documenting as project knowledge?"
-   - "This pattern is used in 5+ places and inconsistent implementations cause bugs"
-   - "This is the team's agreed-upon approach; deviations lead to maintenance issues"
-   - "New contributors frequently make mistakes here without guidance"
-   
-2. **sources** — "What evidence supports this?"
-   - File paths where the pattern is defined or used
-   - README sections or doc comments that describe the convention
-   - Code review comments or commit messages (if available)
-
-3. **confidence** — "How sure am I?"
-   - `0.85-1.0`: Explicit project standard, documented convention, or widely used pattern
-   - `0.6-0.85`: Common pattern, reasonable to standardize but not explicitly documented
-   - `0.3-0.6`: Potentially useful but context is limited; may need human review
-   - Below `0.3`: Do not submit — confidence too low
-
-### Extracting Guards (inline enforcement rules)
-
-When you identify patterns that **should be enforced** (e.g., "always use X instead of Y"), create a `constraints.guards` entry:
-
-```json
-{
-  "constraints": {
-    "guards": [
-      {
-        "pattern": "URLSession\\.shared\\.dataTask",
-        "severity": "warning",
-        "message": "请使用 APIClient.request() 代替直接 URLSession 调用"
-      }
-    ]
-  }
-}
-```
-
-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_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_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**
-
-## Draft File Flow (alternative)
-1. Create draft folder (e.g. `.autosnippet-drafts/`) outside `AutoSnippet/`
-2. Generate one .md per pattern in draft folder
-3. Call `autosnippet_submit_knowledge_batch` with filePaths and `deleteAfterSubmit: true`
-4. Delete draft folder after submit
-
----
-
-## MCP Tools for Candidate Workflow
-
-| Tool | Usage |
-|------|-------|
-| `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**) |
-
----
-
-## Key Principles
-
-1. **One candidate per pattern** — no "catch-all" candidates
-2. **Maximize information density** — Agent's primary value is extracting structured metadata that humans would skip
-3. **Always fill Layer 1-3 + Reasoning + Recipe-Ready Checklist** at minimum; Layer 4-7 for complex patterns
-4. **Reasoning is mandatory** — Every candidate MUST include `reasoning.whyStandard` + `reasoning.sources` + `reasoning.confidence`. No exceptions.
-5. **V3 必填字段** — title, content(markdown+pattern+rationale), trigger, kind, doClause, dontClause, whenClause, coreCode, description, language, category, headers, knowledgeType, usageGuide, reasoning
-6. **Check `recipeReadyHints` in submit response** — If not empty, supplement fields and resubmit
-7. **Parallel query existing Recipes** during generation to reduce duplicates and fill `relations`
-6. **Code examples**: use Xcode placeholders (`<#URL#>`, `<#Token#>`), explain in `usageGuide`
-7. **Failure**: do not retry same turn; narrow scope or use static context
-
----
-
-## Usage Guide Format (CRITICAL)
-
-**MUST use Markdown format:**
-- **MUST use `###` section headings** for each major content block
-- **MUST use `-` bullet lists** with each item on its own line
-- **NEVER** put all content in one continuous line
-
-**BAD:**
-```
-When to use: Scenario A; Scenario B. Key points: Point 1; Point 2.
-```
-
-**GOOD:**
-```
-### When to use
-- Scenario A
-- Scenario B
-
-### Key points
-- Point 1: details
-- Point 2: details
-```
-
-Recommended sections: When to use / When not to use / Key points / Dependencies / Core steps / Error handling / Performance / Security / Common pitfalls / Related Recipes.
-
----
-
-## Semantic Field Enrichment (Two-Pass Workflow)
-
-**重要：MCP 不再使用项目内 AI。**外部 Agent 必须自行填写所有字段。
-
-### 首选：一次性提交全字段
-
-按上述 Layer 1-7 + Recipe-Ready Checklist，提交时尽量填充全部字段。
-
-### 备选：二次补全流程
-
-Step 1: 提交基本字段（title, content, language）→ 获得 candidate ID（`autosnippet_submit_knowledge` 内置自动校验 + 去重检查）
-Step 2: 根据提交返回的校验结果补全缺失字段
-Step 3: 重新提交完整候选
-
-> 注：`autosnippet_enrich_candidates` / `autosnippet_validate_candidate` / `autosnippet_check_duplicate` 已移入 admin 层级。Agent 层级的 `autosnippet_submit_knowledge` 已内置自动校验 + 去重，无需额外调用。
-
-需要补全的字段：
-- **语义字段**: content.rationale, knowledgeType, complexity, scope, steps, constraints
-- **Recipe 必填**: kind, doClause, category, trigger, description, headers, usageGuide, reasoning
-
----
-
-## Submit Example (batch)
-
-```json
-{
-  "targetName": "BiliKit",
-  "items": [
-    {
-      "title": "BiliAPI 网络请求封装",
-      "content": {
-        "markdown": "## BiliAPI 网络请求统一封装\n\n### ✅ 标准用法\n```swift\nclass BiliAPI {\n  static func request<T: Decodable>(_ endpoint: Endpoint) async throws -> T {\n    let (data, response) = try await URLSession.shared.data(for: endpoint.urlRequest)\n    guard let http = response as? HTTPURLResponse, 200..<300 ~= http.statusCode else {\n      throw BiliError.invalidResponse\n    }\n    return try JSONDecoder().decode(T.self, from: data)\n  }\n}\n```\n\n### 使用示例\n```swift\nlet user: UserInfo = try await BiliAPI.request(UserInfoEndpoint(uid: uid))\n```\n\n### 要点\n- 所有网络请求统一通过 BiliAPI.request()\n- 支持泛型解码，自动 JSON → Model\n- 统一错误处理和响应验证",
-        "pattern": "class BiliAPI {\n  static func request<T: Decodable>(_ endpoint: Endpoint) async throws -> T {\n    let (data, response) = try await URLSession.shared.data(for: endpoint.urlRequest)\n    guard let http = response as? HTTPURLResponse, 200..<300 ~= http.statusCode else {\n      throw BiliError.invalidResponse\n    }\n    return try JSONDecoder().decode(T.self, from: data)\n  }\n}",
-        "rationale": "统一网络层避免各模块各自实现 URLSession 调用，减少重复代码并统一错误处理策略。"
-      },
-      "description": "统一的 API 请求封装，支持泛型解码和错误处理",
-      "kind": "pattern",
-      "doClause": "Use BiliAPI.request() for all network calls with type-safe Decodable responses",
-      "language": "swift",
-      "category": "Network",
-      "trigger": "@bili-api-request",
-      "headers": ["import Foundation", "import BiliKit"],
-      "knowledgeType": "code-pattern",
-      "usageGuide": "### When to use\n- 所有 B 站 API 调用\n- 需要类型安全的响应解码\n\n### Dependencies\n- Foundation\n- BiliKit/Models (Endpoint, BiliError)\n\n### Core steps\n1. 定义 Endpoint\n2. 调用 BiliAPI.request(endpoint)\n3. 处理 Result",
-      "complexity": "intermediate",
-      "scope": "project-specific",
-      "tags": ["networking", "async-await", "generic", "decodable"],
-      "steps": [
-        {"title": "定义 Endpoint", "description": "创建符合 Endpoint 协议的请求描述", "code": "struct UserInfoEndpoint: Endpoint { ... }"},
-        {"title": "发起请求", "description": "调用统一 API 方法", "code": "let user: UserInfo = try await BiliAPI.request(UserInfoEndpoint(uid: uid))"}
-      ],
-      "codeChanges": [
-        {"file": "Sources/Network/OldAPI.swift", "before": "URLSession.shared.dataTask(with: url) { ... }", "after": "let result: T = try await BiliAPI.request(endpoint)", "explanation": "替换回调式为 async/await"}
-      ],
-      "constraints": {
-        "preconditions": ["需要有效的网络连接", "Endpoint 必须实现 urlRequest 属性"],
-        "sideEffects": ["发起网络请求"],
-        "guards": [{"pattern": "URLSession\\.shared\\.dataTask", "severity": "warning", "message": "请使用 BiliAPI.request() 统一封装"}]
-      },
-      "quality": {"codeCompleteness": 0.9, "projectAdaptation": 0.85, "documentationClarity": 0.8},
-      "sourceFile": "Sources/BiliKit/Network/BiliAPI.swift",
-      "reasoning": {
-        "whyStandard": "项目中所有模块都通过 BiliAPI 发起请求，新人经常直接使用 URLSession.shared 导致错误处理不统一和重复代码。沉淀为标准后可通过 Guard 自动检查。",
-        "sources": ["Sources/BiliKit/Network/BiliAPI.swift", "Sources/BiliKit/Network/Endpoint.swift", "README.md#networking"],
-        "confidence": 0.9,
-        "qualitySignals": {"clarity": 0.9, "reusability": 0.85, "importance": 0.9},
-        "alternatives": ["直接使用 Alamofire 封装，但项目已选择轻量原生方案"]
-      }
-    }
-  ],
-  "source": "cursor-scan",
-  "deduplicate": true
-}
-```