autosnippet 3.1.6 → 3.1.8

package/dashboard/dist/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>AutoSnippet Dashboard</title>
-    <script type="module" crossorigin src="/assets/index-D9fV5GGQ.js"></script>
+    <script type="module" crossorigin src="/assets/index-Ciz4nd_4.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/yaml-qRaU8Ldn.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-CEnWn7aV.js">
     <link rel="modulepreload" crossorigin href="/assets/axios-C0Zqfgkc.js">

package/lib/external/mcp/handlers/bootstrap/shared/dimension-sop.js

@@ -55,7 +55,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只扫描 1 个文件就提交 — 至少读 5+ 个文件验证模式一致性',
       '不要把"类名前缀"和"方法签名风格"合并成一个候选 — 每种规范应独立成条',
@@ -94,7 +94,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只列出模式名称而不分析实现 — 必须展示项目的具体实现代码',
       '不要把 Singleton 和 Factory 合并成一个候选 — 每种模式独立提交',
@@ -132,7 +132,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只描述目录名 — 要分析每层的职责和通信方式',
       '不要忽略依赖方向 — 是 Controller→Service 还是双向依赖？',
@@ -170,7 +170,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要笼统写"项目有错误处理" — 必须说明具体的处理策略（Result/throw/错误码）',
       '不要忽略反模式 — dontClause 要具体说明禁止的做法',
@@ -208,7 +208,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只列出"项目使用 Notification" — 要说明具体的通知名、发送者、接收者',
       '不要混淆事件传播和数据流 — Delegate 是事件机制，CoreData 是数据流',
@@ -247,7 +247,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要直接复制依赖列表 — 要说明每个关键依赖的用途和版本',
       '不要只写"项目使用 MVC" — 要说明具体的分层职责和文件组织方式',
@@ -285,7 +285,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '8-12 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '【重要】不要在标题或内容中使用 "Agent" 字样 — 这是项目编码规范，不是 Agent 说明书',
       '不要只写通用编程建议 — 必须是此项目特有的约束',
@@ -330,7 +330,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只列出宏名 — 必须包含宏定义的完整值和使用场景',
       'Hook 必须说明 hook 的目的和潜在风险',
@@ -369,7 +369,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要遗漏任何 Category 方法 — 要做到全量扫描',
       '不要只列出方法名不含实现 — Agent 需要实现代码才能正确使用',
@@ -407,7 +407,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只说"项目使用 named export" — 要展示具体的 export 模式和约定',
       '不要忽略 re-export 链路 — barrel export 结构对项目维护很重要',
@@ -446,7 +446,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '12-18 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要假设框架版本 — 从 package.json 确认具体版本再分析',
       '不要只分析组件结构忽略状态管理 — 状态管理模式对项目开发至关重要',
@@ -485,7 +485,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要忽略 __all__ 定义 — 它决定了 from pkg import * 的行为',
       '不要假设所有包都有 type hints — 先统计覆盖率再分析',
@@ -524,7 +524,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要只扫描 Spring 注解 — 项目可能使用 Guice/Dagger/Hilt',
       '不要忽略自定义注解 — 它们编码了项目特有的规则',
@@ -563,7 +563,7 @@ export const DIMENSION_SOP = {
         ],
       },
     ],
-    timeEstimate: '10-15 min',
+    timeEstimate: '1-5 min',
     commonMistakes: [
       '不要忽略 internal/ 包的隔离边界 — 这是 Go 的强制约束',
       '不要只列出依赖不说明用途',

package/lib/external/mcp/handlers/bootstrap/shared/dimension-text.js

@@ -230,8 +230,8 @@ export function buildInternalNextSteps(dimensions) {
     '',
     '== 完成后可执行的后续操作 ==',
     '1. 调用 autosnippet_enrich_candidates(candidateIds) 补全候选缺失字段',
-    '2. 调用 autosnippet_bootstrap({ operation: "refine" }) 对候选进行 AI 精炼',
-    '3. 使用 autosnippet_submit_knowledge_batch 手动提交更多知识条目',
+    '2. 使用 autosnippet_submit_knowledge_batch 手动提交更多知识条目',
+    '3. 使用 autosnippet_submit_knowledge 逐条提交高质量知识',
     '4. 使用 autosnippet_skill({ operation: "load", name }) 加载自动生成的 Project Skills',
     '',
     '== 宏观维度 → Project Skills ==',

package/lib/external/mcp/handlers/system.js

@@ -106,6 +106,22 @@ export async function health(ctx) {
   const allCritical = checks.database; // DB 是唯一硬性依赖
   const status = allCritical ? 'ok' : 'degraded';
 
+  // 如果 DB 不可用但冷启动仍可执行，附加提示避免 Agent 浪费时间修复 DB
+  const actionHints = [];
+  if (!checks.database) {
+    actionHints.push(
+      'DB 不可用不影响冷启动：autosnippet_bootstrap 不依赖数据库（纯文件系统分析），可直接调用。DB 会在首次 submit_knowledge 时自动重试初始化。'
+    );
+  }
+  if (!knowledgeBase || knowledgeBase.recipes.total === 0) {
+    actionHints.push(
+      '知识库为空，建议执行冷启动：(1) 调用 autosnippet_bootstrap 获取 Mission Briefing → (2) 按维度分析代码并提交知识 → (3) 调用 autosnippet_dimension_complete 完成每个维度。'
+    );
+    actionHints.push(
+      '💡 冷启动前建议先加载 Skill 获取详细指引：autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })'
+    );
+  }
+
   return envelope({
     success: true,
     data: {
@@ -118,6 +134,7 @@ export async function health(ctx) {
       services: ctx.container.getServiceNames(),
       knowledgeBase,
       ...(issues.length ? { issues } : {}),
+      ...(actionHints.length ? { actionHints } : {}),
     },
     meta: { tool: 'autosnippet_health' },
   });
@@ -224,8 +241,10 @@ export function capabilities() {
         {
           name: '冷启动（外部 Agent）',
           steps: [
-            'bootstrap（获取 Mission Briefing）',
-            'Agent 分析代码 + submit_knowledge × N',
+            '⚠️ 先加载 Skill 获取详细指引: autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })',
+            'bootstrap（获取 Mission Briefing，无参数直接调用）',
+            '按 Briefing 中的 submissionSchema.example 格式提交知识（注意: content 和 reasoning 都是 JSON 对象）',
+            'Agent 分析代码 + submit_knowledge / submit_knowledge_batch × N',
             'dimension_complete × N',
             'wiki_plan → Agent 写文章 → wiki_finalize（可选）',
           ],

package/lib/external/mcp/tools.js

@@ -230,7 +230,9 @@ export const TOOLS = [
     description:
       '提交单条知识到知识库（V3 统一实体）。严格前置校验，缺少必要字段将被直接拒绝（不入库）。\n' +
       '所有必填字段必须在单次调用中一次性提供，不要分步提交。\n' +
-      '必填: title, language, content(pattern或markdown + rationale), kind, doClause, dontClause, whenClause, coreCode, category, trigger, description, headers, usageGuide, knowledgeType, reasoning',
+      '⚠️ content 必须是对象: { "pattern": "代码片段", "markdown": "## 标题\\n正文...", "rationale": "设计原理" }（pattern/markdown 至少一个 + rationale 必填）\n' +
+      '⚠️ reasoning 必须是对象: { "whyStandard": "原因", "sources": ["file.ts"], "confidence": 0.85 }\n' +
+      '必填: title, language, content, kind, doClause, dontClause, whenClause, coreCode, category, trigger, description, headers, usageGuide, knowledgeType, reasoning',
     inputSchema: {
       type: 'object',
       properties: {
@@ -239,15 +241,18 @@ export const TOOLS = [
         language: { type: 'string', description: '编程语言（小写）' },
         content: {
           type: 'object',
-          description: '内容值对象（必须有 pattern 或 markdown + rationale）',
+          description:
+            '内容值对象（JSON 对象，不是字符串！）。必须包含: pattern(代码片段) 或 markdown(Markdown正文) 至少一个 + rationale(设计原理) 必填。' +
+            '示例: { "pattern": "func example() { ... }", "markdown": "## 标题\\n正文≥200字...", "rationale": "为什么这样设计" }',
           properties: {
-            pattern: { type: 'string' },
-            markdown: { type: 'string' },
+            pattern: { type: 'string', description: '核心代码片段（与 markdown 至少提供一个）' },
+            markdown: { type: 'string', description: 'Markdown 正文（≥200字符，与 pattern 至少提供一个）' },
             rationale: { type: 'string', description: '设计原理说明（必填）' },
             steps: { type: 'array', items: { type: 'object' } },
             codeChanges: { type: 'array', items: { type: 'object' } },
             verification: { type: 'object' },
           },
+          required: ['rationale'],
         },
         kind: {
           type: 'string',
@@ -289,14 +294,16 @@ export const TOOLS = [
         relations: { type: 'object', description: '关系' },
         reasoning: {
           type: 'object',
-          description: '推理依据（必填）{whyStandard, sources[], confidence}',
+          description:
+            '推理依据（JSON 对象，必填）。示例: { "whyStandard": "28/30 files follow this pattern", "sources": ["src/UserService.ts"], "confidence": 0.85 }',
           properties: {
-            whyStandard: { type: 'string' },
-            sources: { type: 'array', items: { type: 'string' } },
-            confidence: { type: 'number' },
+            whyStandard: { type: 'string', description: '为什么这是标准做法（必填）' },
+            sources: { type: 'array', items: { type: 'string' }, description: '参考的文件路径数组（必填，至少 1 个）' },
+            confidence: { type: 'number', description: '置信度 0.0-1.0（推荐 0.7-0.9）' },
             qualitySignals: { type: 'object' },
             alternatives: { type: 'array', items: { type: 'string' } },
           },
+          required: ['whyStandard', 'sources', 'confidence'],
         },
         headerPaths: { type: 'array', items: { type: 'string' } },
         moduleName: { type: 'string' },
@@ -330,7 +337,11 @@ export const TOOLS = [
   {
     name: 'autosnippet_submit_knowledge_batch',
     tier: 'agent',
-    description: '批量提交知识条目（V3 统一实体）。每条须含 kind/doClause/dontClause/whenClause/coreCode。支持去重。',
+    description:
+      '批量提交知识条目（V3 统一实体）。每条字段要求同 submit_knowledge。支持去重。\n' +
+      '⚠️ items 数组中每条的 content 和 reasoning 都必须是 JSON 对象（不是字符串）。\n' +
+      'content 格式: { "pattern": "代码...", "markdown": "正文...", "rationale": "原理..." }\n' +
+      'reasoning 格式: { "whyStandard": "原因", "sources": ["file.ts"], "confidence": 0.85 }',
     inputSchema: {
       type: 'object',
       properties: {
@@ -408,7 +419,9 @@ export const TOOLS = [
     name: 'autosnippet_bootstrap',
     tier: 'agent',
     description:
-      '冷启动 Mission Briefing — 自动分析项目结构、AST、依赖图和 Guard 审计，返回完整的执行计划和维度任务清单。无需任何参数，直接调用即可。',
+      '冷启动 Mission Briefing — 自动分析项目结构、AST、依赖图和 Guard 审计，返回完整的执行计划和维度任务清单。无需任何参数，直接调用即可。不依赖数据库，DB 不可用时也能正常工作。\n' +
+      '💡 建议先加载 Skill 获取详细冷启动指引: autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })\n' +
+      '返回的 submissionSchema.example 包含完整的提交 JSON 示例，请严格按其格式提交知识。',
     inputSchema: {
       type: 'object',
       properties: {},

package/lib/shared/RecipeReadinessChecker.js

@@ -46,15 +46,21 @@ export function checkRecipeReadiness(item) {
   }
 
   // content 有效性（pattern/markdown/rationale 至少有实质内容）
-  const hasCode = !!(item.code || item.content?.pattern || item.content?.markdown);
-  if (!hasCode) {
+  // 先检查 content 是否为对象（Agent 常犯错误：传字符串而非对象）
+  if (item.content && typeof item.content !== 'object') {
     missing.push('content');
-    suggestions.push('content 需包含 pattern 或 markdown（代码片段或正文）');
+    suggestions.push('⚠️ content 必须是 JSON 对象（不是字符串！）。正确格式: { "pattern": "代码片段", "markdown": "## 标题\\n正文...", "rationale": "设计原理" }');
+  } else {
+    const hasCode = !!(item.code || item.content?.pattern || item.content?.markdown);
+    if (!hasCode) {
+      missing.push('content');
+      suggestions.push('content 必须是 JSON 对象且包含 pattern 或 markdown 至少一个。格式: { "pattern": "代码片段...", "rationale": "设计原理..." }');
+    }
   }
 
   if (!item.content?.rationale && !item.rationale) {
     missing.push('rationale');
-    suggestions.push('content.rationale 必须提供设计原理说明');
+    suggestions.push('content.rationale 必须提供设计原理说明（在 content 对象中: { ..., "rationale": "为什么这样设计" }）');
   }
 
   if (!item.language) {
@@ -130,13 +136,15 @@ export function checkRecipeReadiness(item) {
   // reasoning 检查
   if (!item.reasoning || typeof item.reasoning !== 'object') {
     missing.push('reasoning');
-    suggestions.push('reasoning 必须包含 whyStandard + sources + confidence');
+    suggestions.push('⚠️ reasoning 必须是 JSON 对象（不是字符串！）。正确格式: { "whyStandard": "为什么是标准做法", "sources": ["file1.ts", "file2.ts"], "confidence": 0.85 }');
   } else {
     if (!item.reasoning.whyStandard?.trim()) {
       missing.push('reasoning.whyStandard');
+      suggestions.push('reasoning.whyStandard 必须说明为什么这是标准做法');
     }
     if (!Array.isArray(item.reasoning.sources) || item.reasoning.sources.length === 0) {
       missing.push('reasoning.sources');
+      suggestions.push('reasoning.sources 必须是文件路径数组且至少包含 1 个来源');
     }
   }
 

package/package.json

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

package/skills/autosnippet-analysis/SKILL.md

@@ -26,7 +26,7 @@ description: Deep project analysis — full scan + semantic field enrichment + g
 ### Workflow
 
 #### Phase 1: Collect & Baseline
-1. 调用 `autosnippet_bootstrap(operation=scan)` 获取文件列表 + Guard 审计基线
+1. 调用 `autosnippet_bootstrap`（无参数）获取 Mission Briefing（文件列表 + Guard 审计基线）
 2. 审视 Guard 违规 — 静态规则问题 (命名/API 使用/废弃 API)
 3. 确定高优先级文件 (核心模块/共享工具/Service 层)
 
@@ -116,11 +116,11 @@ Use `autosnippet_submit_knowledge_batch` for batch submission.
 **方式 B: 对已有候选调用 AI 补全**
 > 注：`autosnippet_enrich_candidates` 已移入 admin 层级，Agent 推荐使用方式 A 直接填写完整字段。
 
-**方式 C: Bootstrap 候选 AI 润色**
+**方式 C: 候选字段诊断**
 ```
-autosnippet_bootstrap(operation=refine, candidateIds: ["id1", "id2", ...])
+autosnippet_enrich_candidates({ candidateIds: ["id1", "id2", ...] })
 ```
-使用 AI 对 Bootstrap 候选做内容润色（改善 summary、补充 insight、推断 relations、调整 confidence）。
+诊断候选缺失字段（不使用 AI），Agent 根据诊断结果自行补全。
 
 ---
 
@@ -133,7 +133,7 @@ autosnippet_bootstrap(operation=refine, candidateIds: ["id1", "id2", ...])
 ### Workflow
 
 1. 对目标候选做结构补齐（确保所有字段完整）
-2. 调用 `autosnippet_bootstrap(operation=refine)` 对候选做 AI 润色（summary/insight/relations）
+2. 调用 `autosnippet_enrich_candidates` 诊断候选缺失字段，根据结果自行补全
 3. 提交时使用 `autosnippet_submit_knowledge`（内置自动校验 + 去重检查）
 4. 报告补全情况 + 缺失字段 + 重复风险
 5. 如缺失字段 AI 无法填充，提示用户手动补充

package/skills/autosnippet-coldstart/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: autosnippet-coldstart
-description: Cold-start knowledge base initialization. Full 9-dimension analysis workflow — works with both external Agent and internal AI. Call bootstrap_knowledge, then systematically analyze code and submit candidates.
+description: Cold-start knowledge base initialization (V3). Full 9-dimension analysis workflow for external Agent. Call autosnippet_bootstrap (no params) → analyze code → submit_knowledge → dimension_complete.
 ---
 
-# AutoSnippet — Cold Start (知识库冷启动)
+# AutoSnippet — Cold Start (知识库冷启动) V3
 
 > 首次接入项目 / 知识库重建 / 大版本升级后使用。目标：从零建立完整知识库，覆盖 9 大知识维度。
 > Self-check & Fallback: MCP 工具返回 JSON Envelope（{ success, errorCode?, data?, meta }）。失败时不在同一轮重试，缩小范围再试。
+> **DB 不可用不影响冷启动**: autosnippet_bootstrap 不依赖数据库（纯文件系统分析），可直接调用。
 
 ## Quick Decision
 
@@ -16,51 +17,62 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 | 已有知识库，查/用 Recipe | → autosnippet-recipes |
 | 只扫描单个文件/模块 | → autosnippet-candidates |
 | 只做 Guard 审计 | → autosnippet-guard |
-| 快速看看项目结构 | → autosnippet-structure（用 `autosnippet_bootstrap(operation=scan)`） |
+| 快速看看项目结构 | → autosnippet-structure（用 `autosnippet_structure(operation=targets)`） |
 
 ---
 
 ## Phase 0: 启动扫描
 
-调用 `autosnippet_bootstrap(operation=knowledge)` 收集项目结构化数据：
+调用 `autosnippet_bootstrap`（**无参数**）获取 Mission Briefing：
 
-```json
-{ "aiMode": "external", "maxFiles": 500, "contentMaxLines": 150 }
 ```
+autosnippet_bootstrap()
+```
+
+> 💡 Bootstrap 不依赖数据库，DB 不可用时也能正常工作。
 
-返回数据（你需要的上下文）：
+### Mission Briefing 返回数据
 
 | 字段 | 内容 |
 |------|------|
-| `targets` | 所有模块 Target（含 `inferredRole`: core/service/ui/networking/…） |
-| `filesByTarget` | 按 Target 分组的文件内容（含 `priority`: high/medium/low） |
+| `projectMeta` | 项目元数据（name, primaryLanguage, fileCount, projectType） |
+| `ast` | AST 分析摘要（classes, protocols, functions, imports） |
+| `codeEntityGraph` | 代码实体图谱（类/协议/函数之间的关系） |
 | `dependencyGraph` | `{ nodes, edges }` 模块间依赖关系 |
-| `guardViolationFiles` | Guard 规则违规列表 |
-| `languageStats` | 文件扩展名统计 |
-| `primaryLanguage` | 推断的主语言（swift/objectivec/typescript/…） |
-| `languageExtension` | 语言特有扩展（**重要**，见下方） |
-| `analysisFramework` | 9 维度分析框架（维度清单 + 候选模板） |
+| `guardFindings` | Guard 规则违规摘要 |
+| `targets` | 所有模块 Target（含 `inferredRole`: core/service/ui/networking/…） |
+| `dimensions` | 激活的分析维度任务列表（每个维度含 analysisGuide + evidenceStarters） |
+| `submissionSchema` | **提交格式定义 + 语言自适应 JSON 示例**（⚠️ 必须严格按此格式提交） |
+| `executionPlan` | 分 Tier 执行计划（Tier 1 → Tier 2 → Tier 3） |
+| `session` | Bootstrap 会话信息（session.id 供 dimension_complete 使用） |
 
-### languageExtension — 语言特有分析指引
+### submissionSchema — 提交格式（关键！）
 
-`languageExtension` 包含当前项目主语言的特有信息：
+Mission Briefing 的 `submissionSchema.example` 包含**完整的提交 JSON 示例**，按项目主语言自适应。
+**你必须严格按照该示例的字段格式提交知识**，特别注意：
+- `content` 是 JSON 对象：`{ "pattern": "...", "markdown": "...", "rationale": "..." }`
+- `reasoning` 是 JSON 对象：`{ "whyStandard": "...", "sources": [...], "confidence": 0.85 }`
+- `headers` 是数组：`["import Foundation"]`（无 import 时传 `[]`）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `language` | string | 主语言名称 |
-| `extraDimensions` | array | 语言特有的额外分析维度（如 Swift Concurrency、ObjC Block 模式、Go goroutine/channel、Python async/decorator、Java Stream/Optional、Dart Widget/BLoC/Riverpod、Rust ownership/borrowing/lifetime/trait 等） |
-| `typicalPatterns` | array | 该语言中典型的代码模式提示 |
-| `commonAntiPatterns` | array | 该语言常见反模式（bad/why/fix） |
-| `suggestedGuardRules` | array | 建议的 Guard 规则（pattern/severity/message） |
-| `agentCautions` | array | 该语言下 Agent 开发必须遵守的注意事项 |
-| `customFields` | object | 预留扩展字段（供用户/插件自定义） |
+### dimensions — 维度任务
 
-**你的分析应同时覆盖 `analysisFramework.dimensions`（9 通用维度）和 `languageExtension.extraDimensions`（语言特有维度）。**
+每个维度对象包含：
+- `id` — 维度标识
+- `label` — 维度名称
+- `analysisGuide` — 分析步骤指引（SOP）
+- `evidenceStarters` — 从 Phase 1-4 数据中提取的证据启发
+- `submissionSpec` — 提交规范（含 preSubmitChecklist）
 
-> **aiMode 选择**:
-> - `external`（默认）= 你自己分析代码，功能最完整，质量最高
-> - `internal` = 内置 AI 分析，你不需要逐文件阅读，适合 context window 不够的情况
-> - `auto` = 先试 internal，失败自动降级 external
+### executionPlan — 分 Tier 执行
+
+```
+Tier 1（项目特征/深度扫描/分类扫描）→ Tier 2（代码规范/架构/设计模式）→ Tier 3（事件流/最佳实践/开发指南）
+```
+
+每个维度的工作流：
+1. 用原生能力（read_file/grep_search）阅读代码分析
+2. 调用 `autosnippet_submit_knowledge_batch` 批量提交 3-5 条候选
+3. 调用 `autosnippet_dimension_complete` 完成维度（传 referencedFiles + keyFindings）
 
 ---
 
@@ -93,6 +105,9 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
   "category": "Service",
   "kind": "rule",
   "doClause": "Follow Presentation → Domain → Data layered architecture with no cross-layer access",
+  "dontClause": "Never import Data layer modules directly from Presentation layer",
+  "whenClause": "When creating new modules, reviewing code, or making architectural decisions",
+  "coreCode": "// Presentation → Domain → Data\n// ✅ Presentation imports Domain\nimport DomainModule\n// ✅ Domain imports Data\nimport DataModule\n// ❌ Presentation must NOT import Data directly",
   "knowledgeType": "architecture",
   "usageGuide": "### 何时使用\n- 新建模块时确定放置层级\n- 代码审查检查跨层调用\n\n### 规则\n- View 层只调 Domain\n- Domain 层只调 Data\n- 禁止反向依赖",
   "difficulty": "intermediate",
@@ -177,26 +192,32 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 {
   "title": "项目技术特征 — [ProjectName]",
   "trigger": "@projectProfile",
-  "code": "techStack:\n  primaryLanguage: <language>\n  frameworks: [<framework1>, <framework2>]\n  minDeployment: <platform version>\n\nprojectStructure:\n  pattern: <modular-spm|monorepo|workspace|...>\n  keyModules:\n    - ModuleA: 核心业务SDK\n    - ModuleB: UI组件库\n\ndependencies:\n  thirdParty:\n    - LibA: 用途\n    - LibB: 用途",
-  "summary_cn": "项目技术栈全貌：语言、框架、模块结构、三方依赖",
-  "summary_en": "Project tech profile: language, frameworks, module structure, dependencies",
+  "content": {
+    "markdown": "## 技术栈全貌\n\n| 维度 | 值 |\n|------|------|\n| 主语言 | <language> |\n| 框架 | <framework1>, <framework2> |\n| 最低部署版本 | <platform version> |\n\n### 项目结构\n- 类型: <modular-spm|monorepo|workspace|...>\n- 核心模块: ModuleA（核心业务SDK）, ModuleB（UI组件库）\n\n### 三方依赖\n- LibA: 用途\n- LibB: 用途",
+    "pattern": "techStack:\n  primaryLanguage: <language>\n  frameworks: [<fw1>, <fw2>]\n  projectStructure: <modular|monorepo|workspace>\n  keyModules: [ModuleA, ModuleB]",
+    "rationale": "项目技术栈全貌，新人 onboarding 和 Agent 理解项目的基础上下文"
+  },
+  "description": "项目技术栈全貌：语言、框架、模块结构、三方依赖",
   "language": "<primaryLanguage>",
   "headers": [],
   "category": "Architecture",
+  "kind": "fact",
+  "doClause": "Understand the project tech stack before making architectural decisions",
+  "dontClause": "Do not introduce frameworks or patterns that conflict with the established tech stack",
+  "whenClause": "When onboarding to the project or making technology choices",
+  "coreCode": "// Project: [ProjectName]\n// Language: <language>\n// Frameworks: <fw1>, <fw2>\n// Structure: <modular|monorepo|workspace>\n// Key Modules: ModuleA, ModuleB",
   "knowledgeType": "architecture",
-  "difficulty": "beginner",
-  "scope": "project-specific",
-  "rationale": "项目技术栈全貌，新人 onboarding 和 Agent 理解项目的基础",
+  "usageGuide": "### 何时查阅\n新人入职、技术选型、跨模块开发时参考\n### 注意事项\n版本升级时同步更新此条目",
   "reasoning": {
     "whyStandard": "项目技术选型摘要，所有开发决策的基础上下文",
-    "sources": ["<project manifest: Package.swift / package.json / go.mod / pom.xml / etc.>", "languageStats", "dependencyGraph"],
+    "sources": ["<project manifest: Package.swift / package.json / go.mod / pom.xml / etc.>", "projectMeta", "dependencyGraph"],
     "confidence": 0.95
   }
 }
 ```
 
 **分析要点**:
-- 从 `languageStats` 推断主要语言
+- 从 `projectMeta` 获取主语言和项目类型
 - 从 `targets` 推断项目结构（单体/模块化）
 - 从 `dependencyGraph` 推断三方/自有模块依赖
 - 从代码中的 import 语句推断框架使用
@@ -224,15 +245,22 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 {
   "title": "[must] UI 更新必须在主线程",
   "trigger": "@agent-threading",
-  "code": "// ✅ 正确 — 使用语言/框架提供的主线程机制\n// Swift: @MainActor func updateUI() { ... }\n// JS/TS: 无需显式处理（单线程）但 Web Worker 返回需 postMessage\n// Python: 使用 loop.call_soon_threadsafe() 或框架 API\n// Go: 使用 channel 或 sync 包\n// Java/Kotlin: runOnUiThread { ... } 或 Dispatchers.Main\n// Rust: 使用 tokio::spawn + channel 或 Arc<Mutex<T>> 跨线程共享\n// Dart: 使用 WidgetsBinding.instance.addPostFrameCallback 或 setState\n\n// ❌ 错误 — 在后台线程直接操作 UI",
-  "summary_cn": "UI 更新必须在主线程/主 Actor 执行，违反会导致崩溃或数据竞争",
-  "summary_en": "UI updates must run on the main thread/actor to prevent crashes and data races",
+  "content": {
+    "markdown": "## UI 线程安全\n\n所有 UI 更新操作必须在主线程/主 Actor 执行。\n\n### 各语言实现\n- **Swift**: `@MainActor func updateUI() { ... }`\n- **JS/TS**: 单线程无需处理，Web Worker 返回需 `postMessage`\n- **Python**: `loop.call_soon_threadsafe()` 或框架 API\n- **Go**: 使用 channel 或 sync 包\n- **Java/Kotlin**: `runOnUiThread { }` 或 `Dispatchers.Main`\n- **Rust**: `tokio::spawn` + channel 或 `Arc<Mutex<T>>`\n- **Dart**: `setState` 或 `WidgetsBinding.instance.addPostFrameCallback`\n\n### 反例\n在后台线程直接操作 UI 会导致崩溃或数据竞争。",
+    "pattern": "// ✅ 正确 — 使用语言/框架提供的主线程机制\n// Swift: @MainActor func updateUI() { ... }\n// Kotlin: runOnUiThread { updateView() }\n\n// ❌ 错误 — 在后台线程直接操作 UI",
+    "rationale": "UI 框架通常要求在主线程更新界面，违反会导致崩溃或数据竞争"
+  },
+  "description": "UI 更新必须在主线程/主 Actor 执行，违反会导致崩溃或数据竞争",
   "language": "<primaryLanguage>",
   "headers": [],
   "category": "Tool",
+  "kind": "rule",
+  "doClause": "Always dispatch UI updates to the main thread or main actor",
+  "dontClause": "Never update UI elements from background threads or non-main dispatchers",
+  "whenClause": "When writing code that updates UI after async operations or background tasks",
+  "coreCode": "// Swift: @MainActor func updateUI() { ... }\n// Kotlin: runOnUiThread { updateView() }\n// JS/TS: postMessage from Worker\n// Python: loop.call_soon_threadsafe(callback)",
   "knowledgeType": "boundary-constraint",
-  "difficulty": "intermediate",
-  "rationale": "UI 框架通常要求在主线程更新界面，违反会导致崩溃或数据竞争",
+  "usageGuide": "### 适用场景\n所有涉及 UI 更新的异步操作\n### 检查方式\n确认回调/闭包中的 UI 操作是否已切换到主线程",
   "reasoning": {
     "whyStandard": "项目 UI 层需在主线程操作，Agent 新写的代码也必须遵守",
     "sources": ["<relevant source files>"],
@@ -310,19 +338,6 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 
 ---
 
-## scan_project vs bootstrap_knowledge
-
-| | `bootstrap(op=scan)` | `bootstrap(op=knowledge)` |
-|---|---|---|
-| **用途** | 快速结构探查（不写库） | 完整知识库初始化（写 knowledge_edges） |
-| **SPM 图谱写入** | ❌ | ✅ |
-| **文件内容** | 可选 (includeContent) | external 模式自动包含 |
-| **Guard 审计** | ✅ | ✅ |
-| **后续动作** | 看看就好 | Agent 分析 → submit_candidates |
-| **适合场景** | 了解项目、检查 Guard | 首次接入、知识库重建 |
-
----
-
 ## Per-Dimension Industry Reference Templates
 
 > 以下是每个分析维度的**高质量候选模板**，基于业界最佳实践。分析时请以此为参考产出同等质量的候选。
@@ -952,7 +967,7 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 |------|------|
 | 文件太多超出 context window | 减小 `maxFiles`，或先分析 high priority 文件 |
 | 分析维度太多一次做不完 | 分 Target 分批进行，每次分析 1-2 个 Target |
-| 分析质量不高 | 切换 `aiMode="internal"` 使用内置 AI |
+| 分析质量不高 | 检查 submissionSchema 中的示例，确保字段格式严格匹配 |
 | Guard 违规太多 | 先处理 Guard 违规，再做知识分析 |
 | 提交后候选在哪里 | Dashboard → Candidates 页面审核 |
 | 不知道该语言的最佳实践 | 查阅 autosnippet-reference-{lang} Skill |
@@ -963,9 +978,9 @@ description: Cold-start knowledge base initialization. Full 9-dimension analysis
 
 | Tool | 用途 |
 |------|------|
-| `autosnippet_bootstrap(operation=knowledge)` | 启动冷启动扫描（本 Skill 核心工具） |
-| `autosnippet_bootstrap(operation=refine)` | AI 精炼候选质量（summary/insight/relations） |
-| `autosnippet_bootstrap(operation=scan)` | 轻量探查（不写库） |
+| `autosnippet_bootstrap` | 冷启动 Mission Briefing（无参数，返回项目分析 + 维度任务清单） |
+| `autosnippet_dimension_complete` | 维度分析完成通知（提交 recipe 后调用） |
+| `autosnippet_enrich_candidates` | 候选字段完整性诊断 |
 | `autosnippet_submit_knowledge_batch` | 批量提交候选 |
 | `autosnippet_submit_knowledge` | 提交单条候选（内置自动校验 + 去重检查） |
 | `autosnippet_search(mode=context)` | 查找已有知识（避免重复） |

package/skills/autosnippet-concepts/SKILL.md

@@ -87,8 +87,8 @@ This is a conceptual map. Skills stay semantic; MCP provides capability.
 | 候选提交 | `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)` |
+| 项目扫描 | `autosnippet_bootstrap`（无参数，返回 Mission Briefing） |
+| 冷启动 | `autosnippet_bootstrap` + `autosnippet_dimension_complete` |
 | Skills 管理 | `autosnippet_skill(operation=list/load/create/update/delete/suggest)` |
 | 自检 | `autosnippet_health` |
 

package/skills/autosnippet-guard/SKILL.md

@@ -81,7 +81,7 @@ Guard uses the **same Recipe content** in `AutoSnippet/recipes/` as the standard
 | 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(operation=scan)` | Full project scan + Guard audit | `maxFiles`, `includeContent` |
+| `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` |
 
 ---
@@ -100,7 +100,7 @@ Guard uses the **same Recipe content** in `AutoSnippet/recipes/` as the standard
 4. Suggest fixes based on Recipe standards
 
 ### Project-wide Compliance
-1. Call `autosnippet_bootstrap(operation=scan)` for full project scan
+1. Call `autosnippet_bootstrap` (no params) for full project scan
 2. Present high-severity findings first
 
 ---
@@ -117,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_bootstrap(operation=scan)`.
+- **autosnippet-analysis**: Deep project scan + Guard baseline via `autosnippet_bootstrap`.
 
 ```

package/skills/autosnippet-intent/SKILL.md

@@ -44,7 +44,7 @@ Use this skill when the user's intent is unclear or overlaps multiple capabiliti
 - Submit: `autosnippet_submit_knowledge`, `autosnippet_submit_knowledge_batch`
 - Document: `autosnippet_save_document`
 - Guard: `autosnippet_guard` (code 单文件 / files[] 批量)
-- Bootstrap: `autosnippet_bootstrap` (operation: knowledge / refine / scan)
+- Bootstrap: `autosnippet_bootstrap` (no params — Mission Briefing) + `autosnippet_dimension_complete`
 - Skills: `autosnippet_skill` (operation: list / load / create / update / delete / suggest)
 
 This skill is a router only; it does not perform actions itself.