autosnippet 3.2.18 → 3.2.21

package/dist/lib/service/search/SearchEngine.js

@@ -636,7 +636,7 @@ export class SearchEngine {
      *     - 已删除    → scorer.removeDocument()
      *  3. 清空缓存以确保搜索结果刷新
      *
-     * @param {{ force?: boolean }} [opts] - force=true 强制全量重建
+     * @param [opts] - force=true 强制全量重建
      */
     refreshIndex(opts = {}) {
         if (opts.force || !this._indexed || !this._lastIndexTime) {
@@ -689,7 +689,6 @@ export class SearchEngine {
      * 使用 BM25F 思想：高价值字段（title, trigger）重复出现以提升 TF 权重
      * — title ×3, trigger ×2, description ×1.5（通过重复 token 实现）
      * 这确保标题匹配的文档获得显著更高的 BM25 分数
-     * @private
      */
     _buildDocText(r) {
         let contentText = '';
@@ -731,7 +730,6 @@ export class SearchEngine {
     }
     /**
      * 从 DB 行构建文档 meta
-     * @private
      */
     _buildDocMeta(r) {
         let parsedTags = [];

package/dist/lib/service/search/contextBoost.d.ts

@@ -11,7 +11,7 @@
  */
 /**
  * @param items 已排序的候选列表（需有 rankerScore / coarseScore / score）
- * @param {Array<{content?: string, rawInput?: string}>} [context.sessionHistory]
+ * @param [context.sessionHistory]
  * @returns 含 contextScore / contextBoost 字段的排序列表
  */
 export interface SearchItem {

package/dist/lib/service/skills/EventAggregator.js

@@ -22,9 +22,9 @@ const DEFAULT_WINDOW_MS = 5000; // 5 秒聚合窗口
 const DEFAULT_MAX_BATCH = 50; // 单次 batch 最大事件数
 const DEFAULT_DEDUPE_MS = 60_000; // 60 秒去重窗口
 export class EventAggregator {
-    /** @type {Map<string, { events: Record<string, unknown>[], timer: ReturnType<typeof setTimeout> | null }>} */
+    /** >} */
     #buckets = new Map();
-    /** @type {Map<string, number>} 已处理事件的 hash → 最后处理时间 */
+    /** 已处理事件的 hash → 最后处理时间 */
     #dedupeMap = new Map();
     #listeners = new Map();
     #windowMs;

package/dist/lib/service/skills/SignalCollector.js

@@ -60,7 +60,7 @@ export class SignalCollector {
     #snapshotPath;
     #snapshot;
     #onSuggestions;
-    /** @type {EventAggregator} 信号聚类引擎 */
+    /** 信号聚类引擎 */
     #aggregator;
     /**
      * @param opts.projectRoot 用户项目根目录

package/dist/lib/service/snippet/codecs/VSCodeCodec.js

@@ -61,7 +61,7 @@ export class VSCodeCodec extends SnippetCodec {
     getBundleFilename() {
         return BUNDLE_FILENAME;
     }
-    /** @private SnippetSpec → VSCode snippet entry */
+    /** SnippetSpec → VSCode snippet entry */
     #specToEntry(spec) {
         const code = Array.isArray(spec.code) ? spec.code.join('\n') : spec.code || '';
         // 自动将 Xcode 占位符转为 VSCode 格式

package/dist/lib/service/task/TaskGraphService.d.ts

@@ -211,15 +211,12 @@ export declare class TaskGraphService {
      * P2: 获取决策过期阈值（秒）
      * 默认 30 天 = 2592000 秒。可通过容器内 'config' 服务配置。
      * 返回 0 表示禁用过期检测。
-     * @private
      */
     _getDecisionStaleThreshold(): number;
     /**
      * 查找因 closedTaskId 完成而新解除阻塞的任务
-     * @private
      */
     _checkNewlyUnblocked(closedTaskId: string): string[];
-    /** @private */
     _logEvent(taskId: string, eventType: string, oldValue: string | null, newValue: string | null): void;
 }
 export default TaskGraphService;

package/dist/lib/service/task/TaskGraphService.js

@@ -542,7 +542,6 @@ export class TaskGraphService {
      * P2: 获取决策过期阈值（秒）
      * 默认 30 天 = 2592000 秒。可通过容器内 'config' 服务配置。
      * 返回 0 表示禁用过期检测。
-     * @private
      */
     _getDecisionStaleThreshold() {
         try {
@@ -565,7 +564,6 @@ export class TaskGraphService {
     }
     /**
      * 查找因 closedTaskId 完成而新解除阻塞的任务
-     * @private
      */
     _checkNewlyUnblocked(closedTaskId) {
         const dependents = this.repo.getDependents(closedTaskId);
@@ -587,7 +585,6 @@ export class TaskGraphService {
         }
         return newlyReady;
     }
-    /** @private */
     _logEvent(taskId, eventType, oldValue, newValue) {
         try {
             this.repo.logEvent(taskId, eventType, oldValue, newValue);

package/dist/lib/service/task/TaskKnowledgeBridge.d.ts

@@ -1,4 +1,3 @@
-import { type SlimSearchResult } from '#service/search/SearchTypes.js';
 import type { Task } from '../../domain/task/Task.js';
 import Logger from '../../infrastructure/logging/Logger.js';
 /** 知识注入的上下文选项（从 prime / ready / claim 透传） */
@@ -10,8 +9,6 @@ export interface KnowledgeEnrichOptions {
     /** 当前编程语言 */
     language?: string;
 }
-/** 投影后的知识条目（返回给 Agent）— 使用统一投影类型 */
-type SlimKnowledgeItem = SlimSearchResult;
 /**
  * TaskKnowledgeBridge — 任务 ↔ 知识桥接服务
  *
@@ -54,13 +51,8 @@ export declare class TaskKnowledgeBridge {
     }): Promise<Record<string, unknown> | null>;
     /**
      * 为单个任务构建知识上下文（v2 — multi-query + 上下文 + 缓存）
-     * @private
      */
-    _buildContext(task: Task, options?: KnowledgeEnrichOptions): Promise<Record<string, unknown> | {
-        relatedKnowledge: SlimSearchResult[];
-        guardRules: SlimSearchResult[];
-        searchQuery: string;
-    } | null>;
+    private _buildContext;
     /**
      * P2: 构建多条互补搜索查询
      *
@@ -69,45 +61,34 @@ export declare class TaskKnowledgeBridge {
      *   Q2 (语义): 用户输入 — 包含更丰富的自然语义
      *   Q3 (关键词): 从描述/用户输入提取技术术语
      *
-     * @private
      */
-    _buildSearchQueries(task: Task, userQuery?: string): string[];
+    private _buildSearchQueries;
     /**
      * P2: 从文本中提取技术术语（类名、文件名、API 名等）
-     * @private
      */
-    _extractTechTerms(text: string): string[];
+    private _extractTechTerms;
     /**
      * P2 + P3: Multi-Query 搜索 + 合并去重
      *
      * 对每个 query 执行搜索（并行），合并结果并按 score 去重保留最高分。
-     * @private
      */
-    _multiQuerySearch(queries: string[], options: {
-        language?: string;
-    }): Promise<Array<Record<string, unknown>>>;
+    private _multiQuerySearch;
     /**
      * 执行单次搜索（含 P3 上下文透传）
-     * @private
      */
-    _singleSearch(query: string, options: {
-        language?: string;
-    }): Promise<Array<Record<string, unknown>>>;
+    private _singleSearch;
     /**
      * P4: 相关性阈值判断
-     * @private
      */
-    _aboveThreshold(item: Record<string, unknown>): boolean;
+    private _aboveThreshold;
     /**
      * P4: 增强投影 — 使用统一 slimSearchResult() 投影函数
-     * @private
      */
-    _projectItem(item: Record<string, unknown>): SlimKnowledgeItem;
+    private _projectItem;
     /**
      * P6: 缓存键 — 基于 taskQuery + userQuery 的内容指纹
-     * @private
      */
-    _contentKey(taskQuery: string, userQuery?: string): string;
+    private _contentKey;
     /** 清除全部缓存（测试 / 索引重建后使用） */
     clearCache(): void;
 }

package/dist/lib/service/task/TaskKnowledgeBridge.js

@@ -112,7 +112,6 @@ export class TaskKnowledgeBridge {
     // ═══ 私有方法 ═══════════════════════════════════════
     /**
      * 为单个任务构建知识上下文（v2 — multi-query + 上下文 + 缓存）
-     * @private
      */
     async _buildContext(task, options) {
         const taskQuery = `${task.title} ${task.description}`.trim();
@@ -174,7 +173,6 @@ export class TaskKnowledgeBridge {
      *   Q2 (语义): 用户输入 — 包含更丰富的自然语义
      *   Q3 (关键词): 从描述/用户输入提取技术术语
      *
-     * @private
      */
     _buildSearchQueries(task, userQuery) {
         const queries = [];
@@ -209,7 +207,6 @@ export class TaskKnowledgeBridge {
     }
     /**
      * P2: 从文本中提取技术术语（类名、文件名、API 名等）
-     * @private
      */
     _extractTechTerms(text) {
         if (!text) {
@@ -234,7 +231,6 @@ export class TaskKnowledgeBridge {
      * P2 + P3: Multi-Query 搜索 + 合并去重
      *
      * 对每个 query 执行搜索（并行），合并结果并按 score 去重保留最高分。
-     * @private
      */
     async _multiQuerySearch(queries, options) {
         if (queries.length === 0) {
@@ -262,7 +258,6 @@ export class TaskKnowledgeBridge {
     }
     /**
      * 执行单次搜索（含 P3 上下文透传）
-     * @private
      */
     async _singleSearch(query, options) {
         const searchResult = await this._search.search(query, {
@@ -278,7 +273,6 @@ export class TaskKnowledgeBridge {
     }
     /**
      * P4: 相关性阈值判断
-     * @private
      */
     _aboveThreshold(item) {
         const score = item.score || 0;
@@ -286,14 +280,12 @@ export class TaskKnowledgeBridge {
     }
     /**
      * P4: 增强投影 — 使用统一 slimSearchResult() 投影函数
-     * @private
      */
     _projectItem(item) {
         return slimSearchResult(item);
     }
     /**
      * P6: 缓存键 — 基于 taskQuery + userQuery 的内容指纹
-     * @private
      */
     _contentKey(taskQuery, userQuery) {
         return `${taskQuery}||${userQuery || ''}`;

package/dist/lib/service/task/TaskReadyEngine.d.ts

@@ -15,8 +15,7 @@ export declare class TaskReadyEngine {
     _readyStmt: ReturnType<import('better-sqlite3').Database['prepare']>;
     /** @param db raw SQLite handle */
     constructor(db: import('better-sqlite3').Database);
-    /** @private */
-    _prepareStatements(): void;
+    private _prepareStatements;
     /**
      * 获取就绪任务（核心方法）
      *

package/dist/lib/service/task/TaskReadyEngine.js

@@ -18,7 +18,6 @@ export class TaskReadyEngine {
         this._db = db;
         this._prepareStatements();
     }
-    /** @private */
     _prepareStatements() {
         // ── 核心: 递归 CTE 计算传递性阻塞 ──
         this._readyStmt = this._db.prepare(`

package/dist/lib/service/wiki/WikiRenderers.js

@@ -1100,7 +1100,6 @@ export function renderGettingStarted(project, modules, ast, isZh) {
 const BUILD_SYSTEM_FILES = Object.fromEntries(LanguageService.buildSystemMarkers.map((m) => [m.buildTool, m.file]));
 /**
  * 按生态系统输出构建步骤
- * @private
  */
 function _pushBuildSteps(lines, buildSys, projectName, isZh) {
     const { eco, buildTool } = buildSys;

package/dist/lib/service/wiki/WikiUtils.js

@@ -548,7 +548,7 @@ export function profileFolders(projectInfo, options = {}) {
     const root = projectInfo.root;
     const sourceFiles = projectInfo.sourceFiles || [];
     // ── 1. 按文件夹分组源文件 ──
-    /** @type {Map<string, string[]>} relDir → [relFilePath, ...] */
+    /** relDir → [relFilePath, ...] */
     const folderFiles = new Map();
     for (const relFile of sourceFiles) {
         const dir = path.dirname(relFile);
@@ -558,7 +558,7 @@ export function profileFolders(projectInfo, options = {}) {
         folderFiles.get(dir).push(relFile);
     }
     // ── 2. 聚合: 将子文件夹的文件计入父文件夹 (递归) ──
-    /** @type {Map<string, string[]>} relDir → 所有递归子文件 */
+    /** relDir → 所有递归子文件 */
     const folderRecursive = new Map();
     for (const [dir, files] of folderFiles) {
         // 把文件计入 dir 本身及所有祖先
@@ -612,7 +612,6 @@ export function profileFolders(projectInfo, options = {}) {
 }
 /**
  * 修剪冗余文件夹: 如果子目录文件数与父目录接近 (>80%), 仅保留父目录
- * @private
  */
 function _pruneRedundantFolders(candidates, maxFolders) {
     const kept = [];
@@ -649,7 +648,6 @@ function _pruneRedundantFolders(candidates, maxFolders) {
 }
 /**
  * 为单个文件夹构建 FolderProfile
- * @private
  */
 function _buildFolderProfile(relDir, files, depth, projectRoot, sampleLines) {
     const fullDir = path.join(projectRoot, relDir);
@@ -735,7 +733,6 @@ function _buildFolderProfile(relDir, files, depth, projectRoot, sampleLines) {
 }
 /**
  * 从文件名列表检测命名约定
- * @private
  * @param fileNames basename 列表
  */
 function _detectNamingPatterns(fileNames) {
@@ -781,7 +778,6 @@ function _detectNamingPatterns(fileNames) {
 }
 /**
  * 从文件顶部提取 import/require 语句，推断文件夹级依赖
- * @private
  */
 function _extractImports(keyFiles, projectRoot, sampleLines, currentDir) {
     const importTargets = new Set();
@@ -883,7 +879,6 @@ function _extractImports(keyFiles, projectRoot, sampleLines, currentDir) {
 }
 /**
  * 提取文件头部注释 (第一个注释块)
- * @private
  */
 function _extractHeaderComment(fullPath) {
     try {

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/config.js

@@ -32,7 +32,7 @@ const MonitoringConfig = z.object({
 });
 const FileLogConfig = z.object({
     enabled: z.boolean().default(true),
-    path: z.string().default('./logs'),
+    path: z.string().default('./.autosnippet/logs'),
 });
 const LoggingConfig = z.object({
     level: z.enum(['debug', 'info', 'warn', 'error', 'silent']).default('info'),

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.21",
   "description": "Extract code patterns into a knowledge base for AI coding assistants",
   "type": "module",
   "main": "dist/lib/bootstrap.js",