autosnippet 3.2.17 → 3.2.20

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

@@ -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
  */
 import { BootstrapInput, CallContextInput, CapabilitiesInput, CheckDuplicateInput, DimensionCompleteInput, EnrichCandidatesInput, GraphInput, GuardInput, HealthInput, KnowledgeInput, KnowledgeLifecycleInput, SaveDocumentInput, SearchInput, SkillInput, StructureInput, SubmitKnowledgeBatchInput, SubmitKnowledgeInput, TaskInput, ValidateCandidateInput, WikiFinalizeInput, WikiPlanInput, } from '#shared/schemas/mcp-tools.js';
 import { zodToMcpSchema } from './zodToMcpSchema.js';
@@ -73,168 +75,194 @@ export const TOOLS = [
     {
         name: 'autosnippet_health',
         tier: 'agent',
-        description: '检查服务健康状态与知识库统计。total=0 时表示需要冷启动。',
+        description: '检查服务状态与知识库统计。返回 total（知识总数）和各 kind/lifecycle 分布。total=0 时需要冷启动（调用 autosnippet_bootstrap）。',
         inputSchema: zodToMcpSchema(HealthInput),
     },
-    // 2. 统合搜索（4 → 1）
+    // 2. 统合搜索
     {
         name: 'autosnippet_search',
         tier: 'agent',
-        description: '统合搜索入口。支持 4 种模式（mode 参数），返回 byKind 分组结果。',
+        description: '搜索知识库。5 种模式：\n' +
+            '• auto（默认）— 自动选最优策略\n' +
+            '• keyword — 精确关键词匹配，适合 trigger/title 查找\n' +
+            '• bm25 — 全文检索，适合自然语言描述\n' +
+            '• semantic — 向量语义搜索，适合模糊概念匹配\n' +
+            '• context — 综合搜索 + 上下文关联，适合编码辅助\n' +
+            '返回按 kind（rule/pattern/fact）分组的结果。',
         inputSchema: zodToMcpSchema(SearchInput),
     },
-    // 3. 知识浏览（7 → 1）
+    // 3. 知识浏览
     {
         name: 'autosnippet_knowledge',
         tier: 'agent',
-        description: '知识浏览与使用确认。list=列表过滤 | get=单条详情 | insights=质量洞察 | confirm_usage=记录采纳。',
+        description: '知识条目管理。\n' +
+            '• list — 按 kind/category/status 过滤列表\n' +
+            '• get — 获取单条完整内容（需 id）\n' +
+            '• insights — 条目质量分析与改进建议（需 id）\n' +
+            '• confirm_usage — 记录知识被实际采纳（需 id）',
         inputSchema: zodToMcpSchema(KnowledgeInput),
     },
-    // 4. 项目结构（3 → 1）
+    // 4. 项目结构
     {
         name: 'autosnippet_structure',
         tier: 'agent',
-        description: '项目结构探查。targets=目标列表 | files=文件列表 | metadata=元数据与依赖。',
+        description: '探查项目结构。\n' +
+            '• targets — 构建目标列表（模块/Target/Package）\n' +
+            '• files — 指定 Target 的文件列表\n' +
+            '• metadata — 项目元数据（语言、依赖、配置）',
         inputSchema: zodToMcpSchema(StructureInput),
     },
-    // 5. 知识图谱（4 → 1）
+    // 5. 知识图谱
     {
         name: 'autosnippet_graph',
         tier: 'agent',
-        description: '知识图谱查询。query=节点关系 | impact=影响分析 | path=路径查找 | stats=全局统计。',
+        description: '知识关系图谱查询。\n' +
+            '• query — 查询节点的关联关系\n' +
+            '• impact — 修改某知识的影响范围分析\n' +
+            '• path — 两个知识节点间的关联路径\n' +
+            '• stats — 图谱全局统计（节点/边/密度）',
         inputSchema: zodToMcpSchema(GraphInput),
     },
-    // 6. 调用链上下文 (Phase 5)
+    // 6. 调用链上下文
     {
         name: 'autosnippet_call_context',
         tier: 'agent',
-        description: '查询方法的调用链上下文。\n' +
-            '• callers: 谁调用了这个方法？（调用者链）\n' +
-            '• callees: 这个方法调用了谁？（依赖链）\n' +
-            '• impact: 修改此方法的影响半径分析\n' +
-            '• both: 同时获取调用者和被调用者',
+        description: '查询函数/方法的调用链。\n' +
+            '• callers — 谁调用了它（上游调用链）\n' +
+            '• callees — 它调用了谁（下游依赖链）\n' +
+            '• impact — 修改它的影响半径（上+下游+受影响文件数）\n' +
+            '• both — 同时获取 callers + callees',
         inputSchema: zodToMcpSchema(CallContextInput),
     },
-    // 7. Guard 检查（统一入口）
+    // 7. Guard 代码检查
     {
         name: 'autosnippet_guard',
         tier: 'agent',
-        description: '代码规范检查 & 质量门禁。\n' +
-            '• 无参数 → 自动从 git diff 检测增量文件并检查（编码后推荐用法）\n' +
-            '• files: ["path/to/file.m", ...] → 检查指定文件\n' +
-            '• code: "..." → 单文件内联检查\n' +
-            '每个 violation 内联 recipe 修复指南（doClause + coreCode），直接按指示修复后再次调用。',
+        description: '代码规范检查。\n' +
+            '• 无参数 → 自动检查 git diff 增量文件（编码后首选用法）\n' +
+            '• files → 检查指定文件列表\n' +
+            '• code → 内联检查代码片段\n' +
+            '每个 violation 附带修复指南（doClause + coreCode），按指示修复后可再次检查。',
         inputSchema: zodToMcpSchema(GuardInput),
     },
-    // 7. 提交知识（严格前置校验 + 去重检测）
+    // 8. 提交单条知识
     {
         name: 'autosnippet_submit_knowledge',
         tier: 'agent',
-        description: '提交单条知识到知识库（V3 统一实体）。严格前置校验，缺少必要字段将被直接拒绝（不入库）。\n' +
-            '所有必填字段必须在单次调用中一次性提供，不要分步提交。\n' +
-            '⚠️ 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',
+        description: '提交单条知识。所有字段须一次性提供。提交后进入 pending 状态，用户在 Dashboard 审核。\n' +
+            '校验未通过的条目仍会入库，返回 recipeReadyHints 提示缺失字段。\n' +
+            'content 和 reasoning 必须是对象（非字符串）。详见各参数 description。',
         inputSchema: zodToMcpSchema(SubmitKnowledgeInput),
     },
-    // 8. 批量知识提交
+    // 9. 批量知识提交
     {
         name: 'autosnippet_submit_knowledge_batch',
         tier: 'agent',
-        description: '批量提交知识条目（V3 统一实体）。每条字段要求同 submit_knowledge。支持去重。\n' +
-            '⚠️ items 数组中每条的 content 和 reasoning 都必须是 JSON 对象（不是字符串）。\n' +
-            'content 格式: { "pattern": "代码...", "markdown": "正文...", "rationale": "原理..." }\n' +
-            'reasoning 格式: { "whyStandard": "原因", "sources": ["file.ts"], "confidence": 0.85 }',
+        description: '批量提交知识条目。每条字段要求同 submit_knowledge，支持自动去重。\n' +
+            '校验更严格：不通过的条目会被拒绝（不入库），返回 rejectedSummary。\n' +
+            '适用于冷启动维度分析、模块批量扫描等场景。',
         inputSchema: zodToMcpSchema(SubmitKnowledgeBatchInput),
     },
-    // 9. 保存开发文档
+    // 10. 保存开发文档
     {
         name: 'autosnippet_save_document',
         tier: 'agent',
-        description: '保存开发文档（设计文档、排查报告、ADR 等）。仅需 title + markdown，自动以 dev-document 存储。',
+        description: '保存开发文档（设计文档、排查报告、ADR 等）到知识库。仅需 title + markdown，无需完整 V3 字段。',
         inputSchema: zodToMcpSchema(SaveDocumentInput),
     },
-    // 10. Skill 管理（6 → 1）
+    // 11. Skill 管理
     {
         name: 'autosnippet_skill',
         tier: 'agent',
-        description: 'Skill 管理。list=列表 | load=加载 | create=创建 | update=更新 | delete=删除 | suggest=AI推荐。',
+        description: 'Skill 管理。\n' +
+            '• list — 列出所有可用 Skill（内置 + 项目级）\n' +
+            '• load — 加载 Skill 完整内容，获取详细指引（需 name）\n' +
+            '• create — 创建项目级 Skill（需 name + description + content）\n' +
+            '• update — 更新项目级 Skill 内容\n' +
+            '• delete — 删除项目级 Skill（内置不可删）\n' +
+            '• suggest — 基于项目分析推荐应创建的 Skill',
         inputSchema: zodToMcpSchema(SkillInput),
     },
-    // 11. 冷启动 Mission Briefing（无参数，返回项目分析 + 执行计划）
+    // 12. 冷启动
     {
         name: 'autosnippet_bootstrap',
         tier: 'agent',
-        description: '冷启动 Mission Briefing — 自动分析项目结构、AST、依赖图和 Guard 审计，返回完整的执行计划和维度任务清单。无需任何参数，直接调用即可。不依赖数据库，DB 不可用时也能正常工作。\n' +
-            '💡 建议先加载 Skill 获取详细冷启动指引: autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })\n' +
-            '返回的 submissionSchema.example 包含完整的提交 JSON 示例，请严格按其格式提交知识。',
+        description: '冷启动 — 无需参数，自动分析项目（AST、依赖图、Guard 审计），返回 Mission Briefing：\n' +
+            '• 项目元数据与语言统计\n' +
+            '• 维度任务清单（8 维度 × 3 Tier）\n' +
+            '• 执行计划与提交示例\n' +
+            '收到 Briefing 后按 executionPlan 完成所有维度分析。',
         inputSchema: zodToMcpSchema(BootstrapInput),
     },
-    // 11b. 维度完成通知
+    // 13. 维度完成通知
     {
         name: 'autosnippet_dimension_complete',
         tier: 'agent',
-        description: '维度分析完成通知 — Agent 完成一个维度的分析后调用。负责 Recipe 关联、Skill 生成、Checkpoint 保存、进度推送、跨维度 Hints 分发。',
+        description: '维度分析完成通知。负责：Recipe 关联、Skill 生成（从已提交候选自动合成）、Checkpoint 保存、跨维度 Hints 分发。\n' +
+            'analysisText 可简写，系统会自动从已提交的候选知识中合成详细内容用于 Skill 生成。',
         inputSchema: zodToMcpSchema(DimensionCompleteInput),
     },
-    // 11c. Wiki 主题规划
+    // 14. Wiki 规划
     {
         name: 'autosnippet_wiki_plan',
         tier: 'agent',
-        description: '规划 Wiki 文档生成 — 扫描项目结构、分析 AST 和依赖、整合知识库，返回发现的文档主题及每个主题的数据包。Agent 根据规划自行撰写文章后写入 wiki 目录。',
+        description: '规划 Wiki 文档生成 — 整合项目结构与知识库，返回文档主题列表及每个主题的数据包。Agent 根据规划自行撰写文章。',
         inputSchema: zodToMcpSchema(WikiPlanInput),
     },
-    // 11d. Wiki 完成（meta.json + 去重）
+    // 15. Wiki 完成
     {
         name: 'autosnippet_wiki_finalize',
         tier: 'agent',
-        description: '完成 Wiki 生成 — 写入 meta.json、执行去重检查、验证文件完整性。在所有 Wiki 文章写入完成后调用。',
+        description: '完成 Wiki 生成 — 写入 meta.json、去重检查、验证完整性。所有文章写入后调用。',
         inputSchema: zodToMcpSchema(WikiFinalizeInput),
     },
-    // 12. 能力声明（Agent 自发现）
+    // 16. 能力自发现
     {
         name: 'autosnippet_capabilities',
         tier: 'agent',
-        description: '列出所有可用 MCP 工具的概览，供 Agent 自发现服务能力。',
+        description: '列出所有可用 MCP 工具及其用途概览。适合 Agent 初次接触时了解服务能力。',
         inputSchema: zodToMcpSchema(CapabilitiesInput),
     },
-    // 13. autosnippet_task — 统一任务管理（含 prime/decision/CRUD）
+    // 17. 任务与决策管理
     {
         name: 'autosnippet_task',
         tier: 'agent',
-        description: 'Unified task & decision management. Includes session context (prime), task CRUD, and decision persistence.\n' +
-            'Call prime FIRST at every conversation start to load decisions + tasks + knowledge context.',
+        description: '任务与决策管理。每次对话开始时先调用 prime 加载上下文。\n' +
+            '会话: prime（加载决策+任务+知识上下文）| ready（就绪确认）\n' +
+            '任务: create | claim | close | fail | defer | progress | show | list | stats | blocked\n' +
+            '分解: decompose（拆子任务）| dep_add（添加依赖）| dep_tree（依赖树）\n' +
+            '决策: record_decision | revise_decision | unpin_decision | list_decisions',
         inputSchema: zodToMcpSchema(TaskInput),
     },
     // ══════════════════════════════════════════════════════
     //  Tier: admin — 管理员/CI 工具 (额外 +4)
     // ══════════════════════════════════════════════════════
-    // 13. 候选字段诊断
+    // 18. 候选字段诊断
     {
         name: 'autosnippet_enrich_candidates',
         tier: 'admin',
-        description: '候选字段完整性诊断（不使用 AI）。返回 missingFields 列表，Agent 自行补全。',
+        description: '诊断候选条目的字段完整性（无 AI）。返回每条候选的 missingFields 列表，Agent 据此补全后重新提交。',
         inputSchema: zodToMcpSchema(EnrichCandidatesInput),
     },
-    // 14. 知识条目生命周期
+    // 19. 知识生命周期
     {
         name: 'autosnippet_knowledge_lifecycle',
         tier: 'admin',
-        description: '知识条目生命周期操作：submit/approve/reject/publish/deprecate/reactivate/fast_track。',
+        description: '知识条目生命周期操作。approve/fast_track → 发布知识；reject → 拒绝；deprecate → 废弃；reactivate → 恢复。',
         inputSchema: zodToMcpSchema(KnowledgeLifecycleInput),
     },
-    // 15. 独立候选校验（调试）
+    // 20. 候选预校验（调试）
     {
         name: 'autosnippet_validate_candidate',
         tier: 'admin',
-        description: '对候选做结构化预校验（5层），调试用（Agent 层的 submit_knowledge 已内置校验）。',
+        description: '独立候选校验（5 层结构化检查）。调试用，submit_knowledge 已内置校验。',
         inputSchema: zodToMcpSchema(ValidateCandidateInput),
     },
-    // 16. 独立去重检测（调试）
+    // 21. 去重检测（调试）
     {
         name: 'autosnippet_check_duplicate',
         tier: 'admin',
-        description: '相似度检测（调试用，Agent 层的 submit_knowledge 已内置去重）。',
+        description: '独立相似度检测。调试用，submit_knowledge 已内置去重。',
         inputSchema: zodToMcpSchema(CheckDuplicateInput),
     },
 ];

package/dist/lib/http/HttpServer.js

@@ -380,8 +380,21 @@ export class HttpServer {
      */
     mountDashboard(distDir) {
         // 从路由栈中移除最后的 404 catch-all 和根路径 handler
-        const layers = this.app
-            ._router.stack;
+        // Express 5 使用 app.router（Express 4 为 app._router）
+        const router = this.app.router ?? this.app._router;
+        if (!router) {
+            this.logger.warn('mountDashboard: Express router not available, mounting without route reordering');
+            this.app.use(express.static(distDir));
+            this.app.get('{*path}', (req, res, next) => {
+                if (req.path.startsWith('/api') || req.path.startsWith('/socket.io')) {
+                    return next();
+                }
+                res.sendFile(join(distDir, 'index.html'));
+            });
+            this.logger.info('Dashboard mounted (production mode, fallback)', { distDir });
+            return;
+        }
+        const layers = router.stack;
         // 倒序弹出最后 2 层（404 + root handler）
         const removedLayers = [];
         for (let i = layers.length - 1; i >= 0; i--) {

package/dist/lib/http/utils/routeHelpers.d.ts

@@ -31,7 +31,7 @@ export declare function safeInt(value: unknown, defaultValue: number, min?: numb
 export declare function sanitizeForAPI(entryOrJson: KnowledgeEntry | Record<string, unknown>): any;
 /**
  * 将分页结果中的 data 数组批量过滤系统标签
- * @param {{ data: Array, pagination: Object }} result
+ * @param result
  * @returns }
  */
 export declare function sanitizePaginatedForAPI(result: {

package/dist/lib/http/utils/routeHelpers.js

@@ -44,7 +44,7 @@ export function sanitizeForAPI(entryOrJson) {
 }
 /**
  * 将分页结果中的 data 数组批量过滤系统标签
- * @param {{ data: Array, pagination: Object }} result
+ * @param result
  * @returns }
  */
 export function sanitizePaginatedForAPI(result) {

package/dist/lib/http/utils/sse-sessions.d.ts

@@ -21,7 +21,7 @@ import { EventEmitter } from 'node:events';
 export declare function createStreamSession(scene: string): {
     sessionId: string;
     scene: string;
-    /** @type {Array<object>} 事件缓冲区（供 EventSource 连接后回放） */
+    /** 事件缓冲区（供 EventSource 连接后回放） */
     buffer: Record<string, unknown>[];
     /** 会话是否已结束 */
     completed: boolean;

package/dist/lib/http/utils/sse-sessions.js

@@ -30,7 +30,7 @@ export function createStreamSession(scene) {
     const session = {
         sessionId,
         scene,
-        /** @type {Array<object>} 事件缓冲区（供 EventSource 连接后回放） */
+        /** 事件缓冲区（供 EventSource 连接后回放） */
         buffer: [],
         /** 会话是否已结束 */
         completed: false,

package/dist/lib/infrastructure/cache/CacheService.js

@@ -9,7 +9,7 @@ export class CacheService {
     cache;
     cleanupInterval;
     constructor() {
-        /** @type {Map<string, { value: unknown, expiresAt: number }>} */
+        /** >} */
         this.cache = new Map();
         this.cleanupInterval = null;
         // 每 60 秒清理一次过期缓存（unref 避免阻止进程退出）

package/dist/lib/infrastructure/vector/AsyncPersistence.js

@@ -50,23 +50,23 @@ function crc32(str) {
     return ((crc ^ 0xffffffff) >>> 0).toString(16).padStart(8, '0');
 }
 export class AsyncPersistence {
-    /** @type {string} 主索引文件路径 (.asvec) */
+    /** 主索引文件路径 (.asvec) */
     #indexPath;
-    /** @type {string} WAL 文件路径 (.wal) */
+    /** WAL 文件路径 (.wal) */
     #walPath;
-    /** @type {Array<object>} 待刷盘操作队列 */
+    /** 待刷盘操作队列 */
     #pendingOps = [];
     #flushTimer = null;
     #flushing = false;
-    /** @type {number} flush 间隔 (ms) */
+    /** flush 间隔 (ms) */
     #flushIntervalMs;
-    /** @type {number} 触发立即 flush 的操作数 */
+    /** 触发立即 flush 的操作数 */
     #flushBatchSize;
-    /** @type {function} 外部提供的 persist 回调: () => Promise<void> */
+    /** 外部提供的 persist 回调: () => Promise<void> */
     #onPersist;
-    /** @type {function} 外部提供的 replay 回调: (op) => void */
+    /** 外部提供的 replay 回调: (op) => void */
     #onReplay;
-    /** @type {boolean} WAL 是否启用 */
+    /** WAL 是否启用 */
     #enabled;
     /**
      * @param options.indexPath 主索引文件路径 (.asvec)

package/dist/lib/infrastructure/vector/BatchEmbedder.d.ts

@@ -25,7 +25,7 @@ export declare class BatchEmbedder {
     /**
      * 批量 embed 文本
      *
-     * @param {Array<{ id: string, content: string }>} items
+     * @param items
      * @param [onProgress] (embedded, total) => void
      * @returns id → vector
      */

package/dist/lib/infrastructure/vector/BatchEmbedder.js

@@ -27,7 +27,7 @@ export class BatchEmbedder {
     /**
      * 批量 embed 文本
      *
-     * @param {Array<{ id: string, content: string }>} items
+     * @param items
      * @param [onProgress] (embedded, total) => void
      * @returns id → vector
      */
@@ -51,7 +51,7 @@ export class BatchEmbedder {
     }
     /**
      * embed 单个批次
-     * @param {Array<{ id: string, content: string }>} items
+     * @param items
      */
     async #embedBatch(items) {
         const result = new Map();

package/dist/lib/infrastructure/vector/HnswIndex.d.ts

@@ -54,18 +54,18 @@ export declare class HnswIndex {
     efConstruct: number;
     efSearch: number;
     mL: number;
-    /** @type {Array<{ id: string, vector: Float32Array|number[], level: number }>} */
+    /** >} */
     nodes: Array<{
         id: string;
         vector: Float32Array | number[];
         level: number;
         qvector?: Uint8Array | null;
     } | null>;
-    /** @type {Array<Map<number, Set<number>>>} graphs — per-level adjacency: graphs[level].get(nodeIdx) → Set<neighborIdx> */
+    /** graphs — per-level adjacency: graphs[level].get(nodeIdx) → Set<neighborIdx> */
     graphs: Map<number, Set<number>>[];
     entryPoint: number;
     maxLevel: number;
-    /** @type {Map<string, number>} id → nodeIdx */
+    /** id → nodeIdx */
     idToIndex: Map<any, any>;
     /** @param [options.distanceFn] 自定义距离函数 (a, b) => number */
     constructor(options?: {
@@ -154,7 +154,7 @@ export declare class HnswIndex {
     }): HnswIndex;
     /**
      * 批量插入 (比逐个 addPoint 更高效的初始构建)
-     * @param {Array<{ id: string, vector: Float32Array|number[] }>} items
+     * @param items
      */
     addPoints(items: Array<{
         id: string;

package/dist/lib/infrastructure/vector/HnswIndex.js

@@ -141,13 +141,13 @@ export class HnswIndex {
     efSearch; // 查询时搜索宽度
     mL; // 层级采样因子 = 1 / ln(M)
     // ── 存储 ──
-    /** @type {Array<{ id: string, vector: Float32Array|number[], level: number }>} */
+    /** >} */
     nodes = [];
-    /** @type {Array<Map<number, Set<number>>>} graphs — per-level adjacency: graphs[level].get(nodeIdx) → Set<neighborIdx> */
+    /** graphs — per-level adjacency: graphs[level].get(nodeIdx) → Set<neighborIdx> */
     graphs = [];
     entryPoint = -1; // 入口节点索引
     maxLevel = -1; // 当前最大层级
-    /** @type {Map<string, number>} id → nodeIdx */
+    /** id → nodeIdx */
     idToIndex = new Map();
     // ── 可选的自定义距离函数 (用于量化空间) ──
     #distanceFn = null;
@@ -449,7 +449,7 @@ export class HnswIndex {
     }
     /**
      * 简单邻居选择 — 取距离最近的 maxNeighbors 个
-     * @param {Array<{ nodeIdx: number, dist: number }>} candidates
+     * @param candidates
      * @returns >}
      */
     #selectNeighborsSimple(candidates, maxNeighbors) {
@@ -548,7 +548,7 @@ export class HnswIndex {
     }
     /**
      * 批量插入 (比逐个 addPoint 更高效的初始构建)
-     * @param {Array<{ id: string, vector: Float32Array|number[] }>} items
+     * @param items
      */
     addPoints(items) {
         for (const item of items) {

package/dist/lib/infrastructure/vector/HnswVectorAdapter.js

@@ -24,22 +24,22 @@ import { ScalarQuantizer } from './ScalarQuantizer.js';
 import { VectorStore } from './VectorStore.js';
 export class HnswVectorAdapter extends VectorStore {
     #index;
-    /** @type {Map<string, object>} id → metadata */
+    /** id → metadata */
     #metadata;
-    /** @type {Map<string, string>} id → content */
+    /** id → content */
     #contents;
     #quantizer;
-    /** @type {number} 向量维度 (首次 upsert 自动检测) */
+    /** 向量维度 (首次 upsert 自动检测) */
     #dimension = 0;
-    /** @type {boolean} 数据是否已修改 */
+    /** 数据是否已修改 */
     #dirty = false;
-    /** @type {ReturnType<typeof setTimeout>|null} flush 定时器 */
+    /** flush 定时器 */
     #flushTimer = null;
-    /** @type {number} 待刷盘操作计数 */
+    /** 待刷盘操作计数 */
     #pendingOps = 0;
-    /** @type {boolean} 是否正在刷盘 */
+    /** 是否正在刷盘 */
     #flushing = false;
-    /** @type {AsyncPersistence|null} WAL 持久化管理 */
+    /** WAL 持久化管理 */
     #wal = null;
     // ── 配置 ──
     #config;

package/dist/lib/infrastructure/vector/ScalarQuantizer.d.ts

@@ -56,7 +56,7 @@ export declare class ScalarQuantizer {
     };
     /**
      * 从序列化数据恢复量化器
-     * @param {{ dimension: number, mins: number[], maxs: number[] }} data
+     * @param data
      */
     static deserialize(data: {
         dimension: number;

package/dist/lib/infrastructure/vector/ScalarQuantizer.js

@@ -13,11 +13,11 @@
  */
 export class ScalarQuantizer {
     #dimension;
-    /** @type {Float32Array} 每维最小值 */
+    /** 每维最小值 */
     #mins;
-    /** @type {Float32Array} 每维最大值 */
+    /** 每维最大值 */
     #maxs;
-    /** @type {Float32Array} 每维范围 (max - min), 预计算避免重复减法 */
+    /** 每维范围 (max - min), 预计算避免重复减法 */
     #ranges;
     #trained = false;
     /** @param dimension 向量维度 */
@@ -157,7 +157,7 @@ export class ScalarQuantizer {
     }
     /**
      * 从序列化数据恢复量化器
-     * @param {{ dimension: number, mins: number[], maxs: number[] }} data
+     * @param data
      */
     static deserialize(data) {
         const q = new ScalarQuantizer(data.dimension);

package/dist/lib/infrastructure/vector/VectorStore.d.ts

@@ -7,7 +7,7 @@ export declare class VectorStore {
     init(): Promise<void>;
     /**
      * 插入或更新文档
-     * @param {{ id: string, content: string, vector: number[], metadata: object }} item
+     * @param item
      */
     upsert(item: {
         id: string;

package/dist/lib/infrastructure/vector/VectorStore.js

@@ -10,7 +10,7 @@ export class VectorStore {
     }
     /**
      * 插入或更新文档
-     * @param {{ id: string, content: string, vector: number[], metadata: object }} item
+     * @param item
      */
     async upsert(item) {
         throw new Error('Not implemented: upsert()');

package/dist/lib/injection/ServiceContainer.d.ts

@@ -16,7 +16,7 @@ export declare class ServiceContainer {
      *
      * @param name 服务名称
      * @param factory 工厂函数（首次 get 时执行）
-     * @param {{ aiDependent?: boolean }} [options] 选项
+     * @param [options] 选项
      *   - aiDependent: 标记为 AI Provider 依赖项，热重载时自动清除缓存
      */
     singleton(name: string, factory: (container: ServiceContainer) => unknown, options?: {

package/dist/lib/injection/ServiceContainer.js

@@ -36,7 +36,7 @@ export class ServiceContainer {
      *
      * @param name 服务名称
      * @param factory 工厂函数（首次 get 时执行）
-     * @param {{ aiDependent?: boolean }} [options] 选项
+     * @param [options] 选项
      *   - aiDependent: 标记为 AI Provider 依赖项，热重载时自动清除缓存
      */
     singleton(name, factory, options = {}) {

package/dist/lib/platform/NativeUi.d.ts

@@ -13,7 +13,7 @@ export declare function isNativeUiAvailable(): boolean;
 /**
  * 用组合窗口展示搜索结果（列表 + 预览）
  *
- * @param {Array<{title: string, code: string, explanation?: string, groupSize?: number}>} items
+ * @param items
  * @param keyword 搜索关键词
  * @returns 选中的索引（0-based），-1 表示取消
  */

package/dist/lib/platform/NativeUi.js

@@ -65,7 +65,7 @@ export function isNativeUiAvailable() {
 /**
  * 用组合窗口展示搜索结果（列表 + 预览）
  *
- * @param {Array<{title: string, code: string, explanation?: string, groupSize?: number}>} items
+ * @param items
  * @param keyword 搜索关键词
  * @returns 选中的索引（0-based），-1 表示取消
  */

package/dist/lib/platform/ios/spm/DependencyGraph.d.ts

@@ -8,7 +8,7 @@ export declare class DependencyGraph {
     constructor();
     /**
      * 从 PackageSwiftParser 的解析结果构建图
-     * @param {{ targets: { name: string, dependencies: string[] }[] }} parsed
+     * @param parsed
      */
     buildFromParsed(parsed: {
         targets: {