autosnippet 3.2.17 → 3.2.20

package/dist/lib/external/mcp/McpServer.js

@@ -18,7 +18,7 @@
  * Handler 实现 → handlers/*.js
  * 整合路由 → handlers/consolidated.js
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer as SdkMcpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { CapabilityProbe } from '#core/capability/CapabilityProbe.js';
@@ -48,12 +48,12 @@ export class McpServer {
     _session;
     _startedAt;
     bootstrap;
-    server;
+    sdkServer;
     constructor(options = {}) {
         this.logger = Logger.getInstance();
         this.container = options.container || null;
         this.bootstrap = options.bootstrap || null;
-        this.server = null;
+        this.sdkServer = null;
         this._startedAt = Date.now();
         this._autoApproveMarked = false;
         this._capabilityProbe = null;
@@ -115,7 +115,7 @@ export class McpServer {
                 registerGatewayActions(gateway, this.container);
             }
         }
-        this.server = new Server({ name: 'autosnippet-v3', version: '3.0.0' }, { capabilities: { tools: {} } });
+        this.sdkServer = new SdkMcpServer({ name: 'autosnippet-v3', version: '3.0.0' }, { capabilities: { tools: {} } });
         this._registerHandlers();
         return this;
     }
@@ -125,14 +125,14 @@ export class McpServer {
      */
     _registerHandlers() {
         // ── ListTools: 按 tier 过滤 ──
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+        this.sdkServer.server.setRequestHandler(ListToolsRequestSchema, async () => {
             const tierName = process.env.ASD_MCP_TIER || 'agent';
             const maxTier = TIER_ORDER[tierName] ?? TIER_ORDER.agent;
             const visible = TOOLS.filter((t) => (TIER_ORDER[t.tier || 'agent'] ?? 0) <= maxTier);
             return { tools: visible };
         });
         // ── CallTool: 路由到 handler ──
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.sdkServer.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
             const t0 = Date.now();
             try {
@@ -240,7 +240,6 @@ export class McpServer {
     }
     /**
      * 获取 decisions 摘要（带缓存 + 防并发）
-     * @private
      * @returns >>}
      */
     async _getDecisionsSummary() {
@@ -271,7 +270,6 @@ export class McpServer {
     }
     /**
      * 从 DB 查询 decisions 摘要（仅 id + title）
-     * @private
      */
     async _fetchDecisionsSummary() {
         const cache = this._decisionCache;
@@ -297,7 +295,6 @@ export class McpServer {
     }
     /**
      * 从 ready 响应结果中刷新缓存（避免额外 DB 查询）
-     * @private
      */
     _refreshCacheFromReady(readyResult) {
         try {
@@ -316,7 +313,6 @@ export class McpServer {
     }
     /**
      * 解析工具名到 handler 函数（V3 整合版）
-     * @private
      */
     _resolveHandler(name) {
         const HANDLER_MAP = {
@@ -444,7 +440,7 @@ export class McpServer {
             /* non-blocking */
         }
         const transport = new StdioServerTransport();
-        await this.server.connect(transport);
+        await this.sdkServer.connect(transport);
         const tierName = process.env.ASD_MCP_TIER || 'agent';
         const maxTier = TIER_ORDER[tierName] ?? TIER_ORDER.agent;
         const visibleCount = TOOLS.filter((t) => (TIER_ORDER[t.tier || 'agent'] ?? 0) <= maxTier).length;
@@ -452,8 +448,8 @@ export class McpServer {
         process.stderr.write(`AutoSnippet MCP ready — ${visibleCount} tools [tier=${tierName}]\n`);
     }
     async shutdown() {
-        if (this.server) {
-            await this.server.close();
+        if (this.sdkServer) {
+            await this.sdkServer.close();
         }
         if (this.bootstrap) {
             await this.bootstrap.shutdown();

package/dist/lib/external/mcp/handlers/bootstrap/ExternalSubmissionTracker.js

@@ -30,15 +30,15 @@ const MAX_SUBMISSIONS_PER_DIM = 20;
 const MAX_NEGATIVE_SIGNALS = 30;
 // ── 主类 ────────────────────────────────────────────────────
 export class ExternalSubmissionTracker {
-    /** @type {Map<string, SubmissionRecord[]>} dimId → 提交记录列表 */
+    /** dimId → 提交记录列表 */
     #dimensionSubmissions = new Map();
-    /** @type {Map<string, Set<string>>} filePath → 引用此文件的 dimId 集合 */
+    /** filePath → 引用此文件的 dimId 集合 */
     #fileEvidenceMap = new Map();
-    /** @type {NegativeSignal[]} 负空间信号 */
+    /** 负空间信号 */
     #negativeSignals = [];
-    /** @type {Map<string, string[]>} dimId → 被拒绝的提交标题列表 */
+    /** dimId → 被拒绝的提交标题列表 */
     #rejections = new Map();
-    /** @type {Set<string>} 已使用的唯一 trigger 集合 (跨维度) */
+    /** 已使用的唯一 trigger 集合 (跨维度) */
     #usedTriggers = new Set();
     // ─── 提交记录 ─────────────────────────────────────────
     /**

package/dist/lib/external/mcp/handlers/bootstrap/MissionBriefingBuilder.js

@@ -77,8 +77,9 @@ function enrichDimensionTask(dim, tier) {
                 },
                 {
                     phase: '4. 提交',
-                    action: '按项目特写格式提交 3-5 个知识候选',
+                    action: '按项目特写格式提交知识候选（**最少 3 条，目标 5 条**，将不同关注点拆为独立候选）',
                     qualityChecklist: [
+                        '候选数量 ≥3（1-2 条是不合格的，不同关注点必须拆分为独立候选）',
                         '每个 content ≥200 字符',
                         '每个候选引用 ≥3 个文件路径',
                         'coreCode 提供可复制的完整代码骨架',
@@ -95,7 +96,7 @@ function enrichDimensionTask(dim, tier) {
     // ── submissionSpec: 嵌入 Quality Checklist ──
     const submissionSpec = {
         knowledgeTypes: dim.knowledgeTypes || [],
-        targetCandidateCount: '3-5',
+        targetCandidateCount: '每维度最少 3 条，目标 5 条（1-2 条不合格）。将不同关注点（如命名规范 vs 文件组织 vs 注释风格）拆分为独立候选，不要合并到一条中。',
         contentStyle: PROJECT_SNAPSHOT_STYLE_GUIDE.split('\n')
             .filter((l) => !l.startsWith('#') || l.startsWith('##'))
             .filter((l) => l.trim())
@@ -645,7 +646,7 @@ function buildExecutionPlan(activeDimensions) {
     return {
         tiers: plan,
         totalDimensions: activeDimensions.length,
-        workflow: '对每个维度: (1) 用你的原生能力阅读代码分析 → (2) 调用 autosnippet_submit_knowledge_batch 批量提交 3-5 条候选 → (3) 调用 autosnippet_dimension_complete 完成维度（必须传 referencedFiles=[分析过的文件路径] 和 keyFindings=[3-5条关键发现]）',
+        workflow: '对每个维度: (1) 用你的原生能力阅读代码分析 → (2) 调用 autosnippet_submit_knowledge_batch 批量提交候选（**每维度最少 3 条，目标 5 条**，将不同关注点拆分为独立候选，1-2 条视为不合格） → (3) 调用 autosnippet_dimension_complete 完成维度（必须传 referencedFiles=[分析过的文件路径] 和 keyFindings=[3-5条关键发现]）',
     };
 }
 // ── Mission Briefing 主构建函数 ──────────────────────────────

package/dist/lib/external/mcp/handlers/bootstrap/pipeline/BootstrapSnapshot.d.ts

@@ -99,7 +99,7 @@ export declare class BootstrapSnapshot {
      *
      * @param params.sessionId Bootstrap 会话 ID
      * @param params.projectRoot 项目根目录
-     * @param {Array<{path: string, relativePath: string}>} params.allFiles 扫描到的文件列表
+     * @param params.allFiles 扫描到的文件列表
      * @param params.dimensionStats { dimId: { referencedFiles: string[] } }
      * @param [params.episodicData] EpisodicMemory.toJSON()
      * @param [params.meta] { durationMs, candidateCount, primaryLang }
@@ -126,7 +126,7 @@ export declare class BootstrapSnapshot {
      * 计算当前文件与快照的 diff
      *
      * @param snapshot getLatest() 返回的快照
-     * @param {Array<{path: string, relativePath: string, content: string}>} currentFiles 当前文件列表
+     * @param currentFiles 当前文件列表
      * @returns }
      */
     computeDiff(snapshot: SnapshotData, currentFiles: SnapshotFile[], projectRoot: string): DiffResult;
@@ -139,7 +139,7 @@ export declare class BootstrapSnapshot {
      * 3. 如果变更比例超过阈值 → 建议全量
      *
      * @param snapshot 上次快照
-     * @param {{ added: string[], modified: string[], deleted: string[] }} diff
+     * @param diff
      * @param allDimIds 所有可用维度 ID
      * @returns }
      */

package/dist/lib/external/mcp/handlers/bootstrap/pipeline/BootstrapSnapshot.js

@@ -47,7 +47,7 @@ export class BootstrapSnapshot {
      *
      * @param params.sessionId Bootstrap 会话 ID
      * @param params.projectRoot 项目根目录
-     * @param {Array<{path: string, relativePath: string}>} params.allFiles 扫描到的文件列表
+     * @param params.allFiles 扫描到的文件列表
      * @param params.dimensionStats { dimId: { referencedFiles: string[] } }
      * @param [params.episodicData] EpisodicMemory.toJSON()
      * @param [params.meta] { durationMs, candidateCount, primaryLang }
@@ -169,7 +169,7 @@ export class BootstrapSnapshot {
      * 计算当前文件与快照的 diff
      *
      * @param snapshot getLatest() 返回的快照
-     * @param {Array<{path: string, relativePath: string, content: string}>} currentFiles 当前文件列表
+     * @param currentFiles 当前文件列表
      * @returns }
      */
     computeDiff(snapshot, currentFiles, projectRoot) {
@@ -212,7 +212,7 @@ export class BootstrapSnapshot {
      * 3. 如果变更比例超过阈值 → 建议全量
      *
      * @param snapshot 上次快照
-     * @param {{ added: string[], modified: string[], deleted: string[] }} diff
+     * @param diff
      * @param allDimIds 所有可用维度 ID
      * @returns }
      */

package/dist/lib/external/mcp/handlers/bootstrap/pipeline/IncrementalBootstrap.d.ts

@@ -25,7 +25,7 @@ export declare class IncrementalBootstrap {
     /**
      * 评估增量可行性 — 在 bootstrap 流程最开始调用
      *
-     * @param {Array<{path: string, relativePath: string, content: string}>} currentFiles 当前扫描到的文件
+     * @param currentFiles 当前扫描到的文件
      * @param allDimIds 所有可用维度 ID
      */
     evaluate(currentFiles: BootstrapFile[], allDimIds: string[]): {

package/dist/lib/external/mcp/handlers/bootstrap/pipeline/IncrementalBootstrap.js

@@ -31,7 +31,7 @@ export class IncrementalBootstrap {
     /**
      * 评估增量可行性 — 在 bootstrap 流程最开始调用
      *
-     * @param {Array<{path: string, relativePath: string, content: string}>} currentFiles 当前扫描到的文件
+     * @param currentFiles 当前扫描到的文件
      * @param allDimIds 所有可用维度 ID
      */
     evaluate(currentFiles, allDimIds) {

package/dist/lib/external/mcp/handlers/bootstrap/pipeline/dimension-context.js

@@ -25,11 +25,11 @@ export class DimensionContext {
     submittedCandidates;
     /** @param projectContext 项目基础信息 (全程不变) */
     constructor(projectContext) {
-        /** @type {object} 项目基础信息 */
+        /** 项目基础信息 */
         this.projectContext = projectContext;
-        /** @type {Map<string, DimensionDigest>} 已完成维度的摘要 */
+        /** 已完成维度的摘要 */
         this.completedDimensions = new Map();
-        /** @type {Array<CandidateSummary>} 已提交候选的摘要 */
+        /** 已提交候选的摘要 */
         this.submittedCandidates = [];
     }
     /**

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

@@ -53,7 +53,7 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '按项目特写格式提交 3-5 个知识候选，每个候选聚焦一种具体代码规范',
+                action: '按项目特写格式提交知识候选（**最少 3 条，目标 5 条**），每个候选聚焦一种具体代码规范（如命名约定、注释风格、文件组织分别独立提交）',
                 qualityChecklist: [
                     '每个 content ≥200 字符',
                     '每个候选引用 ≥3 个文件路径',
@@ -106,8 +106,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '每种设计模式单独提交一个候选，包含标准实现代码和使用约束',
+                action: '每种设计模式单独提交候选（**整体最少 3 条，目标 5 条**），包含标准实现代码和使用约束',
                 qualityChecklist: [
+                    '候选数量 ≥3（将不同模式拆分为独立候选，如 Singleton 一条、Factory 一条、Delegate 一条）',
                     '每个候选只聚焦一种设计模式',
                     'content 包含 ✅ 正确写法 和 ❌ 禁止写法',
                     'coreCode 是可复制的模式骨架代码',
@@ -143,8 +144,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '分别提交分层架构、模块通信、依赖管理等知识候选',
+                action: '分别提交分层架构、模块通信、依赖管理等知识候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（分层结构、通信方式、依赖管理应分别提交）',
                     'content 包含架构层次图或文字描述',
                     '引用具体目录路径和核心文件',
                     'doClause 表达架构约束规则',
@@ -191,8 +193,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '每种最佳实践独立提交，包含正反面代码示例',
+                action: '每种最佳实践独立提交（**整体最少 3 条，目标 5 条**），包含正反面代码示例',
                 qualityChecklist: [
+                    '候选数量 ≥3（错误处理、并发安全、日志规范等应分别提交）',
                     '每个候选聚焦一种实践（如"错误处理"或"并发安全"）',
                     'content 包含 ✅ 推荐写法 和 ❌ 反模式',
                     '提供具体的统计数据（如"项目中 80% 的错误处理使用 Result 类型"）',
@@ -242,8 +245,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '事件传播和数据流分别提交候选',
+                action: '事件传播和数据流分别提交候选（**最少 3 条，目标 5 条**，将不同机制拆为独立候选）',
                 qualityChecklist: [
+                    '候选数量 ≥3（Delegate、Notification、Callback 等每种机制独立提交）',
                     '每个候选聚焦一种事件/数据流模式',
                     'content 描述具体的事件传播链路（从触发到响应）',
                     'whenClause 描述何时使用此事件/数据模式',
@@ -293,8 +297,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '分模块提交项目特征候选（技术栈、依赖、入口点、基础设施等）',
+                action: '分模块提交项目特征候选（**最少 3 条，目标 5 条**：技术栈、依赖、入口点、基础设施等分别提交）',
                 qualityChecklist: [
+                    '候选数量 ≥3（技术栈、三方依赖、启动流程等应独立成条）',
                     'content 包含具体的技术栈版本和依赖列表',
                     '引用配置文件和入口文件路径',
                     '每个候选只关注一个方面（如"三方依赖"或"启动流程"）',
@@ -340,8 +345,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '每条开发约束单独提交，确保 doClause 表达清晰的强制规则',
+                action: '每条开发约束单独提交（**最少 3 条，目标 5 条**），确保 doClause 表达清晰的强制规则',
                 qualityChecklist: [
+                    '候选数量 ≥3（命名约束、线程约束、废弃 API  等应分别提交）',
                     '每个候选是一条明确的项目开发规则',
                     'doClause 以动词开头，表达强制性要求',
                     'dontClause 明确禁止的做法',
@@ -395,8 +401,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '宏定义、常量、Hook 分别提交候选，确保包含完整实现代码',
+                action: '宏定义、常量、Hook 分别提交候选（**最少 3 条，目标 5 条**），确保包含完整实现代码',
                 qualityChecklist: [
+                    '候选数量 ≥3（宏定义、常量定义、Method Swizzling 等应分别提交）',
                     'coreCode 包含完整的宏/常量/Hook 实现',
                     'content 包含使用频率和场景说明',
                     'Hook 候选必须说明原方法和替换方法的对应关系',
@@ -446,8 +453,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '按基类分组提交候选（NSString Category 一条、UIView Category 一条等）',
+                action: '按基类分组提交候选（**最少 3 条，目标 5 条**：NSString Category 一条、UIView Category 一条等）',
                 qualityChecklist: [
+                    '候选数量 ≥3（不同基类的 Category 独立提交）',
                     'content 包含完整的方法签名列表',
                     'coreCode 包含最常用方法的实现代码',
                     'doClause 强制要求使用已有 Category 方法',
@@ -492,8 +500,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '分别提交 barrel export 结构、导出约定、依赖约束等候选',
+                action: '分别提交 barrel export 结构、导出约定、依赖约束等候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（barrel export、命名导出约定、依赖方向约束等独立提交）',
                     'content 包含具体的 import/export 代码示例',
                     '引用 index.ts 和核心模块文件路径',
                     'doClause 表达导出约定规则',
@@ -541,8 +550,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '组件约定、状态管理、路由模式分别提交候选',
+                action: '组件约定、状态管理、路由模式分别提交候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（组件结构、状态管理、路由配置等独立提交）',
                     'content 包含组件/状态/路由的代码示例',
                     '引用具体框架版本和配置文件',
                     'coreCode 是可复制的标准写法模板',
@@ -588,8 +598,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '包结构、导入约定、类型标注分别提交候选',
+                action: '包结构、导入约定、类型标注分别提交候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（包结构、导入风格、类型标注约定独立提交）',
                     'content 包含具体的 import/type hint 代码示例',
                     '引用 __init__.py 和核心模块路径',
                     'coreCode 展示标准的导入和类型标注写法',
@@ -637,8 +648,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: 'DI、ORM、API、自定义注解分别提交候选',
+                action: 'DI、ORM、API、自定义注解分别提交候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（DI 注解、ORM 注解、API 注解等独立提交）',
                     'content 包含注解的完整使用示例',
                     '引用具体的类文件和配置',
                     'coreCode 展示标准的注解使用骨架',
@@ -676,8 +688,9 @@ export const DIMENSION_SOP = {
             },
             {
                 phase: '4. 提交',
-                action: '模块结构、接口约定、初始化模式分别提交候选',
+                action: '模块结构、接口约定、初始化模式分别提交候选（**最少 3 条，目标 5 条**）',
                 qualityChecklist: [
+                    '候选数量 ≥3（模块结构、接口约定、初始化模式独立提交）',
                     'content 包含模块依赖关系和接口设计',
                     '引用 go.mod 和核心包路径',
                     'coreCode 展示标准的接口定义和使用',

package/dist/lib/external/mcp/handlers/bootstrap-external.js

@@ -147,6 +147,12 @@ export async function bootstrapExternal(ctx) {
     return envelope({
         success: true,
         data: briefing,
+        message: `⚠️ Bootstrap 仅完成第一步（项目扫描），你必须继续完成全部 ${dimensions.length} 个维度的分析。` +
+            `请立即按 executionPlan.tiers 的顺序，对每个维度执行：` +
+            `(1) 用你的代码阅读能力分析该维度相关文件 → ` +
+            `(2) 调用 autosnippet_submit_knowledge_batch 提交候选知识（**每维度最少 3 条，目标 5 条**，不同关注点拆为独立候选） → ` +
+            `(3) 调用 autosnippet_dimension_complete 标记维度完成。` +
+            `不要停下来等待用户确认，直接开始第一个维度。`,
         meta: { tool: 'autosnippet_bootstrap', responseTimeMs: Date.now() - t0 },
     });
 }

package/dist/lib/external/mcp/handlers/dimension-complete-external.js

@@ -176,10 +176,64 @@ export async function dimensionComplete(ctx, args) {
     }
     // ═══════════════════════════════════════════════════════════
     // 2. Skill 生成 (skillWorthy 维度) — 使用共享 skill-generator
+    //    如果 analysisText 太短，自动从已提交的候选知识中合成结构化内容
     // ═══════════════════════════════════════════════════════════
     let skillCreated = false;
     if (dim.skillWorthy) {
-        const skillResult = await generateSkill(ctx, dim, analysisText, referencedFiles, keyFindings, 'external-agent-bootstrap');
+        let effectiveAnalysis = analysisText;
+        // 当 analysisText 不足以通过质量门控时，从候选知识中合成
+        if (analysisText.length < 500 && submittedRecipeIds.length > 0) {
+            try {
+                const knowledgeService = ctx.container.get('knowledgeService');
+                if (knowledgeService) {
+                    const parts = [`## ${dim.label || dimensionId} — 分析报告\n`];
+                    if (analysisText.trim().length > 0) {
+                        parts.push(analysisText.trim(), '');
+                    }
+                    for (const recipeId of submittedRecipeIds) {
+                        const entry = await knowledgeService.get(recipeId);
+                        if (!entry) {
+                            continue;
+                        }
+                        parts.push(`### ${entry.title || 'Untitled'}`);
+                        if (entry.description) {
+                            parts.push(entry.description);
+                        }
+                        if (entry.whenClause || entry.doClause || entry.dontClause) {
+                            parts.push('');
+                            if (entry.whenClause) {
+                                parts.push(`- **When**: ${entry.whenClause}`);
+                            }
+                            if (entry.doClause) {
+                                parts.push(`- **Do**: ${entry.doClause}`);
+                            }
+                            if (entry.dontClause) {
+                                parts.push(`- **Don't**: ${entry.dontClause}`);
+                            }
+                        }
+                        if (entry.coreCode) {
+                            parts.push('', '```', entry.coreCode.substring(0, 500), '```');
+                        }
+                        parts.push('');
+                    }
+                    if (keyFindings.length > 0) {
+                        parts.push('## Key Findings', '');
+                        for (const f of keyFindings) {
+                            parts.push(`- ${f}`);
+                        }
+                    }
+                    const synthesized = parts.join('\n');
+                    if (synthesized.length > effectiveAnalysis.length) {
+                        effectiveAnalysis = synthesized;
+                        logger.info(`[DimensionComplete] Synthesized analysisText for "${dimensionId}" from ${submittedRecipeIds.length} candidates (${analysisText.length} → ${synthesized.length} chars)`);
+                    }
+                }
+            }
+            catch (e) {
+                logger.debug(`[DimensionComplete] Failed to synthesize analysisText: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        const skillResult = await generateSkill(ctx, dim, effectiveAnalysis, referencedFiles, keyFindings, 'external-agent-bootstrap');
         skillCreated = skillResult.success;
         if (!skillCreated) {
             logger.warn(`[DimensionComplete] Skill skipped for "${dimensionId}": ${skillResult.error}`);

package/dist/lib/external/mcp/handlers/skill.js

@@ -63,16 +63,11 @@ function _parseSkillMeta(skillName, baseDir = SKILLS_DIR) {
 }
 /** Skill 适用场景映射 — 帮助 Agent 判断何时该加载哪个 Skill */
 const SKILL_USE_CASES = {
-    'autosnippet-intent': '不确定该用哪个能力时，先加载此 Skill 做意图路由',
-    'autosnippet-coldstart': '冷启动/初始化知识库时的完整 9 维度分析指南',
-    'autosnippet-analysis': '深度项目分析 — 扫描 + 语义补齐 + 缺口填充',
-    'autosnippet-candidates': '生成/提交高质量候选（V2 全字段结构化）',
-    'autosnippet-create': '将代码提交到知识库（Dashboard 入口）',
+    'autosnippet-create': '将代码模式/规则/事实提交到知识库',
     'autosnippet-guard': '代码规范审计（Guard 规则检查）',
     'autosnippet-recipes': '查询/使用项目标准（Recipe 上下文检索）',
-    'autosnippet-structure': '了解项目结构（SPM Target / 依赖图谱 / 知识图谱）',
-    'autosnippet-concepts': '学习 AutoSnippet 核心概念（知识库/Recipe/Snippet/向量库）',
-    'autosnippet-lifecycle': '了解 Recipe 生命周期与 Agent 权限边界',
+    'autosnippet-structure': '了解项目结构（Target / 依赖图谱 / 知识图谱）',
+    'autosnippet-devdocs': '保存开发文档（架构决策、调试报告、设计文档）',
 };
 // ═══════════════════════════════════════════════════════════
 // Handler: listSkills
@@ -141,7 +136,7 @@ export function listSkills(ctx) {
             data: {
                 skills,
                 total: skills.length,
-                hint: '根据当前任务选择合适的 Skill 加载（load_skill）。不确定时先加载 autosnippet-intent 做意图路由。',
+                hint: '根据当前任务选择合适的 Skill 加载（load_skill）。',
                 _meta: { signalSuggestions: suggestionCount },
             },
         });
@@ -689,28 +684,11 @@ function _listExistingProjectSkillNames(ctx) {
 /** 推荐相关 Skills（基于静态映射） */
 function _getRelatedSkills(skillName) {
     const relations = {
-        'autosnippet-coldstart': [
-            'autosnippet-analysis',
-            'autosnippet-candidates',
-            'autosnippet-structure',
-        ],
-        'autosnippet-analysis': [
-            'autosnippet-candidates',
-            'autosnippet-coldstart',
-            'autosnippet-structure',
-        ],
-        'autosnippet-candidates': [
-            'autosnippet-analysis',
-            'autosnippet-create',
-            'autosnippet-lifecycle',
-        ],
-        'autosnippet-create': ['autosnippet-candidates', 'autosnippet-lifecycle'],
-        'autosnippet-guard': ['autosnippet-recipes', 'autosnippet-analysis'],
-        'autosnippet-recipes': ['autosnippet-guard', 'autosnippet-structure', 'autosnippet-concepts'],
-        'autosnippet-structure': ['autosnippet-analysis', 'autosnippet-coldstart'],
-        'autosnippet-concepts': ['autosnippet-recipes', 'autosnippet-lifecycle'],
-        'autosnippet-lifecycle': ['autosnippet-candidates', 'autosnippet-concepts'],
-        'autosnippet-intent': [],
+        'autosnippet-create': ['autosnippet-recipes'],
+        'autosnippet-guard': ['autosnippet-recipes'],
+        'autosnippet-recipes': ['autosnippet-guard', 'autosnippet-structure', 'autosnippet-create'],
+        'autosnippet-structure': ['autosnippet-recipes', 'autosnippet-create'],
+        'autosnippet-devdocs': ['autosnippet-recipes', 'autosnippet-create'],
     };
     return relations[skillName] || [];
 }

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

@@ -116,7 +116,7 @@ export async function health(ctx) {
     }
     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" })');
+        actionHints.push('💡 冷启动指引：调用 autosnippet_bootstrap 获取 Mission Briefing → 按维度分析代码 → 调用 autosnippet_dimension_complete 完成每个维度');
     }
     return envelope({
         success: true,
@@ -243,7 +243,7 @@ export function capabilities() {
                 {
                     name: '冷启动（外部 Agent）',
                     steps: [
-                        '⚠️ 先加载 Skill 获取详细指引: autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })',
+                        '⚠️ 调用 autosnippet_bootstrap 获取 Mission Briefing（无参数直接调用）',
                         'bootstrap（获取 Mission Briefing，无参数直接调用）',
                         '按 Briefing 中的 submissionSchema.example 格式提交知识（注意: content 和 reasoning 都是 JSON 对象）',
                         'Agent 分析代码 + submit_knowledge / submit_knowledge_batch × N',

package/dist/lib/external/mcp/handlers/task.js

@@ -154,13 +154,28 @@ async function _close(ctx, svc, args) {
         });
     }
     const { task, newlyReady } = await svc.close(args.id, args.reason || 'Completed');
+    const lines = [`✅ Closed: ${args.id} — ${task.title}`];
+    if (args.reason && args.reason !== 'Completed') {
+        lines.push(`Reason: ${args.reason}`);
+    }
+    if (newlyReady.length > 0) {
+        lines.push(`→ ${newlyReady.length} task(s) newly ready`);
+    }
+    lines.push('');
+    lines.push('⚠️ REQUIRED: You MUST call autosnippet_guard (no args) NOW to review changed files for compliance violations. Do NOT proceed to the next task until guard review passes.');
     return envelope({
         success: true,
         data: {
             closed: task.toJSON(),
             newlyReady,
+            nextAction: {
+                tool: 'autosnippet_guard',
+                args: {},
+                required: true,
+                reason: 'Post-close compliance review — check diff for violations before moving on.',
+            },
         },
-        message: `Closed ${args.id}. ${newlyReady.length} task(s) newly ready.`,
+        message: lines.join('\n'),
         meta: { tool: 'autosnippet_task' },
     });
 }

package/dist/lib/external/mcp/tools.d.ts

@@ -1,18 +1,20 @@
 /**
  * MCP 工具定义 — V3 整合版 (18 agent + 4 admin = 22 工具)
  *
- * 从 39 → 22 工具（参数路由合并同类工具 + 外部 Agent 冷启动新架构 + TaskGraph 统一入口）。
- * TaskGraph: autosnippet_task (统一入口，含 prime/decision/task CRUD)
- * 每个工具声明增加 tier 字段（agent / admin）。
+ * 每个工具声明包含 name、tier（agent/admin）、description 和 inputSchema。
+ * description 是 Agent 选择工具的关键 — 使用 bullet list 列出所有 operation 及其用途。
+ * inputSchema 由 Zod Schema 自动生成（zodToMcpSchema），参数的 .describe() 会转为 JSON Schema description。
  *
- * inputSchema 由 Zod Schema 自动生成（zodToMcpSchema），消除手写 JSON Schema 双重维护。
- * Zod Schema → 运行时校验（wrapHandler）+ JSON Schema 声明（ListTools）。
+ * Agent 工具 (18):
+ *   1-7:   查询工具 (health/search/knowledge/structure/graph/call_context/guard)
+ *   8-10:  写入工具 (submit_knowledge/submit_knowledge_batch/save_document)
+ *   11:    Skill 管理 (skill)
+ *   12-15: 冷启动 (bootstrap/dimension_complete/wiki_plan/wiki_finalize)
+ *   16:    自发现 (capabilities)
+ *   17:    任务管理 (task)
  *
- * 外部 Agent 冷启动新工具 (v3.1):
- *   - autosnippet_bootstrap:          参数化 → 无参数化 Mission Briefing
- *   - autosnippet_dimension_complete:  维度分析完成通知
- *   - autosnippet_wiki_plan:           Wiki 主题规划
- *   - autosnippet_wiki_finalize:       Wiki 元数据 + 去重
+ * Admin 工具 (4):
+ *   18-21: enrich_candidates/knowledge_lifecycle/validate_candidate/check_duplicate
  */
 export declare const TIER_ORDER: {
     agent: number;