autosnippet 3.3.2 → 3.3.4

package/README.md

@@ -93,13 +93,17 @@ Want to know the blast radius before refactoring a function? Static call graph a
 
 Keyword search only finds literal matches. With an LLM API Key, search upgrades to vector + BM25 hybrid retrieval — asking "how to manage memory" finds Recipes about garbage collection, semantically similar results rank first.
 
-### Knowledge Graph
+### Intent-Aware Search (Prime)
 
-Recipes have relationships. Query impact paths, dependency depth, and related Recipes for any module — once you've accumulated enough knowledge, it helps you see the structure behind it.
+At the start of every conversation, the Agent auto-triggers prime to intelligently inject knowledge based on the user query and current file. IntentExtractor extracts tech terms, infers language and module, performs cross-language (EN↔CJK) synonym expansion; PrimeSearchPipeline executes multi-query parallel search (raw query + term query + file context + focused synonyms), returning precise results after 3-layer quality filtering. Supports long natural-language sentences, short exact matches, and mixed-language queries.
+
+### Recipe Source Evidence (sourceRefs)
 
-### TaskGraph Orchestration
+Recipes carry the project file paths analyzed during creation as evidence. The 📍 sourceRefs in search results point to real project files — the Agent can trust and reference them without self-verification. Path validity is monitored automatically, with git rename auto-repair.
 
-Break a large task into steps, declare dependencies between them, and each step auto-injects relevant Recipes as context. Team decisions (rationale, confidence) persist alongside tasks — they don't vanish with the conversation.
+### Knowledge Graph
+
+Recipes have relationships. Query impact paths, dependency depth, and related Recipes for any module — once you've accumulated enough knowledge, it helps you see the structure behind it.
 
 ### Self-Cycling Signal Mechanism
 

package/dist/bin/cli.js

@@ -742,6 +742,17 @@ program
         httpServer = new HttpServer({ port, host });
         await httpServer.initialize();
         await httpServer.start();
+        // ── UiStartupTasks: 后台异步刷新（不阻塞 UI） ──
+        import('../lib/service/bootstrap/UiStartupTasks.js')
+            .then(({ runUiStartupTasks }) => runUiStartupTasks({ projectRoot, container }))
+            .then((report) => {
+            if (report.errors.length > 0) {
+                cli.warn(`⚠️  UiStartupTasks completed with ${report.errors.length} error(s)`);
+            }
+        })
+            .catch((err) => {
+            cli.debug(`UiStartupTasks failed: ${err.message}`);
+        });
         // ── MCP 配置检测 ──
         const cursorMcpPath = join(projectRoot, '.cursor', 'mcp.json');
         const vscodeMcpPath = join(projectRoot, '.vscode', 'mcp.json');
@@ -1337,7 +1348,7 @@ program
         process.exit(1);
     }
     try {
-        const report = syncService.sync(db, {
+        const report = await syncService.syncAll(db, {
             dryRun: opts.dryRun,
             force: opts.force,
         });
@@ -1347,6 +1358,21 @@ program
         cli.log(`  Updated:   ${report.updated ?? 0}`);
         cli.log(`  Unchanged: ${report.unchanged ?? 0}`);
         cli.log(`  Deleted:   ${report.deleted ?? 0}`);
+        if (report.reconcileReport) {
+            cli.log(`\n  📍 Source Refs`);
+            cli.log(`  ${'─'.repeat(40)}`);
+            cli.log(`  Inserted:  ${report.reconcileReport.inserted ?? 0}`);
+            cli.log(`  Active:    ${report.reconcileReport.active ?? 0}`);
+            cli.log(`  Stale:     ${report.reconcileReport.stale ?? 0}`);
+            cli.log(`  Skipped:   ${report.reconcileReport.skipped ?? 0}`);
+        }
+        if (report.repairReport &&
+            (report.repairReport.renamed > 0 || report.repairReport.stillStale > 0)) {
+            cli.log(`\n  🔧 Rename Repairs`);
+            cli.log(`  ${'─'.repeat(40)}`);
+            cli.log(`  Renamed:    ${report.repairReport.renamed ?? 0}`);
+            cli.log(`  Still Stale: ${report.repairReport.stillStale ?? 0}`);
+        }
         if (report.violations.length > 0) {
             cli.log(`\n  ⚠️  Violations (${report.violations.length}):`);
             for (const v of report.violations) {

package/dist/lib/cli/KnowledgeSyncService.d.ts

@@ -14,12 +14,38 @@
  *  - 内部: SetupService.stepDatabase() 委托调用（skipViolations = true）
  */
 import Logger from '../infrastructure/logging/Logger.js';
+import type { ApplyReport, ReconcileReport, RepairReport } from '../service/knowledge/SourceRefReconciler.js';
+export interface SyncAllReport {
+    synced: number;
+    created: number;
+    updated: number;
+    violations: string[];
+    orphaned: string[];
+    skipped: number;
+    reconcileReport?: ReconcileReport;
+    repairReport?: RepairReport;
+    applyReport?: ApplyReport;
+}
 export declare class KnowledgeSyncService {
     candidatesDir: string;
     logger: ReturnType<typeof Logger.getInstance>;
     projectRoot: string;
     recipesDir: string;
     constructor(projectRoot: string);
+    /**
+     * 完整同步入口 — sync + reconcile + repair
+     *
+     * asd sync CLI 和 asd ui 启动都调用此方法。
+     *
+     * @param db better-sqlite3 原始句柄
+     * @param opts 同步选项
+     * @returns 包含 sync + reconcile + repair 报告的综合结果
+     */
+    syncAll(db: Parameters<KnowledgeSyncService['sync']>[0], opts?: {
+        dryRun?: boolean;
+        force?: boolean;
+        skipViolations?: boolean;
+    }): Promise<SyncAllReport>;
     /**
      * 执行增量同步：.md → DB（knowledge_entries 表）
      *

package/dist/lib/cli/KnowledgeSyncService.js

@@ -19,6 +19,7 @@ import path from 'node:path';
 import { CANDIDATES_DIR, RECIPES_DIR } from '../infrastructure/config/Defaults.js';
 import Logger from '../infrastructure/logging/Logger.js';
 import { computeKnowledgeHash, parseKnowledgeMarkdown, } from '../service/knowledge/KnowledgeFileWriter.js';
+import { SourceRefReconciler } from '../service/knowledge/SourceRefReconciler.js';
 export class KnowledgeSyncService {
     candidatesDir;
     logger;
@@ -30,6 +31,37 @@ export class KnowledgeSyncService {
         this.candidatesDir = path.join(projectRoot, CANDIDATES_DIR);
         this.logger = Logger.getInstance();
     }
+    /**
+     * 完整同步入口 — sync + reconcile + repair
+     *
+     * asd sync CLI 和 asd ui 启动都调用此方法。
+     *
+     * @param db better-sqlite3 原始句柄
+     * @param opts 同步选项
+     * @returns 包含 sync + reconcile + repair 报告的综合结果
+     */
+    async syncAll(db, opts = {}) {
+        // 1. .md → DB 同步
+        const syncReport = this.sync(db, opts);
+        const report = { ...syncReport };
+        // 2. 填充/验证 recipe_source_refs 桥接表
+        try {
+            const reconciler = new SourceRefReconciler(this.projectRoot, db);
+            report.reconcileReport = reconciler.reconcile({ force: opts.force });
+            // 3. git rename 修复
+            report.repairReport = await reconciler.repairRenames();
+            // 4. 写回修复
+            if (report.repairReport.renamed > 0) {
+                report.applyReport = reconciler.applyRepairs();
+            }
+        }
+        catch (err) {
+            this.logger.warn('KnowledgeSyncService: sourceRef reconcile failed (non-blocking)', {
+                error: err.message,
+            });
+        }
+        return report;
+    }
     /**
      * 执行增量同步：.md → DB（knowledge_entries 表）
      *
@@ -89,7 +121,7 @@ export class KnowledgeSyncService {
                 if (!dryRun) {
                     const existed = this._entryExists(db, parsed.id);
                     const row = this._buildDbRow(parsed, relPath, content);
-                    upsertStmt.run(...Object.values(row));
+                    upsertStmt?.run(...Object.values(row));
                     if (existed) {
                         report.updated++;
                     }

package/dist/lib/external/mcp/handlers/browse.d.ts

@@ -67,6 +67,7 @@ export declare function getRecipe(ctx: McpContext, args: BrowseGetArgs): Promise
         } | undefined;
         headers: string[] | undefined;
         reasoning: {
+            sources?: unknown[] | undefined;
             confidence?: number | undefined;
             whyStandard?: string | undefined;
         } | undefined;

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

@@ -74,11 +74,12 @@ function _projectForAgent(json) {
             ...((json.content.steps?.length ?? 0) > 0 ? { steps: json.content.steps } : {}),
         }
         : undefined;
-    // reasoning 精简：仅保留 whyStandard + confidence
+    // reasoning 精简：保留 whyStandard + confidence + sources（可信度证据链）
     const reasoning = json.reasoning
         ? {
             ...(json.reasoning.whyStandard ? { whyStandard: json.reasoning.whyStandard } : {}),
             ...(json.reasoning.confidence != null ? { confidence: json.reasoning.confidence } : {}),
+            ...((json.reasoning.sources?.length ?? 0) > 0 ? { sources: json.reasoning.sources } : {}),
         }
         : undefined;
     // constraints 精简：仅保留 guards 和 sideEffects

package/dist/lib/external/mcp/handlers/consolidated.d.ts

@@ -112,6 +112,7 @@ export declare function consolidatedKnowledge(ctx: McpContext, args: Consolidate
         } | undefined;
         headers: string[] | undefined;
         reasoning: {
+            sources?: unknown[] | undefined;
             confidence?: number | undefined;
             whyStandard?: string | undefined;
         } | undefined;

package/dist/lib/external/mcp/handlers/panorama.d.ts

@@ -1,17 +1,17 @@
 /**
  * MCP Handler — autosnippet_panorama
  *
- * 项目全景查询工具，提供 8 个 operation：
- *   overview — 项目骨架 + 层级 + 模块角色
- *   module   — 单模块详情 + 邻居关系
- *   gaps     — 知识空白区 (有代码无 Recipe)
- *   health   — 全景健康度 (覆盖率 + 耦合度 + 循环)
- *   governance_cycle       — 新陈代谢完整周期 (矛盾+冗余+衰退)
- *   decay_report           — 衰退评估报告
- *   staging_check          — staging 条目检查 + 自动发布
- *   enhancement_suggestions — 基于使用数据的增强建议
+ * Project panorama query tool with 8 operations:
+ *   overview — project skeleton + layers + module roles
+ *   module   — single module detail + neighbors + recipes + file groups
+ *   gaps     — knowledge gaps (code without Recipes)
+ *   health   — panorama health (coverage + coupling + cycles)
+ *   governance_cycle       — full metabolism cycle (contradiction + redundancy + decay)
+ *   decay_report           — decay assessment report
+ *   staging_check          — staging entry check + auto-publish
+ *   enhancement_suggestions — usage-data-based enhancement suggestions
  *
- * 全部为只读操作（governance_cycle 和 staging_check 除外，会执行状态转换）。
+ * All read-only except governance_cycle and staging_check (which perform state transitions).
  */
 import type { McpContext } from './types.js';
 interface PanoramaArgs {
@@ -19,7 +19,7 @@ interface PanoramaArgs {
     module?: string;
 }
 /**
- * autosnippet_panorama — 统合全景查询
+ * autosnippet_panorama — unified panorama query
  */
 export declare function panoramaHandler(ctx: McpContext, args: PanoramaArgs): Promise<{
     success: boolean;

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

@@ -1,21 +1,21 @@
 /**
  * MCP Handler — autosnippet_panorama
  *
- * 项目全景查询工具，提供 8 个 operation：
- *   overview — 项目骨架 + 层级 + 模块角色
- *   module   — 单模块详情 + 邻居关系
- *   gaps     — 知识空白区 (有代码无 Recipe)
- *   health   — 全景健康度 (覆盖率 + 耦合度 + 循环)
- *   governance_cycle       — 新陈代谢完整周期 (矛盾+冗余+衰退)
- *   decay_report           — 衰退评估报告
- *   staging_check          — staging 条目检查 + 自动发布
- *   enhancement_suggestions — 基于使用数据的增强建议
+ * Project panorama query tool with 8 operations:
+ *   overview — project skeleton + layers + module roles
+ *   module   — single module detail + neighbors + recipes + file groups
+ *   gaps     — knowledge gaps (code without Recipes)
+ *   health   — panorama health (coverage + coupling + cycles)
+ *   governance_cycle       — full metabolism cycle (contradiction + redundancy + decay)
+ *   decay_report           — decay assessment report
+ *   staging_check          — staging entry check + auto-publish
+ *   enhancement_suggestions — usage-data-based enhancement suggestions
  *
- * 全部为只读操作（governance_cycle 和 staging_check 除外，会执行状态转换）。
+ * All read-only except governance_cycle and staging_check (which perform state transitions).
  */
 import { envelope } from '../envelope.js';
 /**
- * autosnippet_panorama — 统合全景查询
+ * autosnippet_panorama — unified panorama query
  */
 export async function panoramaHandler(ctx, args) {
     const op = args.operation || 'overview';
@@ -23,11 +23,11 @@ export async function panoramaHandler(ctx, args) {
     if (!panoramaService) {
         return envelope({
             success: false,
-            message: '全景服务未初始化',
+            message: 'Panorama service not initialized',
             meta: { tool: 'autosnippet_panorama' },
         });
     }
-    // 自动确保数据就绪（无数据时触发内置扫描）
+    // Auto-ensure data is ready (triggers built-in scan when no data exists)
     await panoramaService.ensureData();
     switch (op) {
         case 'overview': {
@@ -43,7 +43,7 @@ export async function panoramaHandler(ctx, args) {
             if (!moduleName) {
                 return envelope({
                     success: false,
-                    message: 'operation=module 需要提供 module 参数（模块名称）',
+                    message: 'operation=module requires the "module" parameter (module name)',
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }
@@ -51,7 +51,7 @@ export async function panoramaHandler(ctx, args) {
             if (!detail) {
                 return envelope({
                     success: false,
-                    message: `未找到模块: ${moduleName}`,
+                    message: `Module not found: ${moduleName}`,
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }
@@ -78,7 +78,7 @@ export async function panoramaHandler(ctx, args) {
             });
         }
         default:
-            // ── Governance operations (不依赖 panoramaService) ──
+            // ── Governance operations (independent of panoramaService) ──
             return handleGovernanceOps(ctx, op);
     }
 }
@@ -90,7 +90,7 @@ async function handleGovernanceOps(ctx, op) {
             if (!metabolism) {
                 return envelope({
                     success: false,
-                    message: '治理服务未初始化（knowledgeMetabolism 未注册）',
+                    message: 'Governance service not initialized (knowledgeMetabolism not registered)',
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }
@@ -106,7 +106,7 @@ async function handleGovernanceOps(ctx, op) {
             if (!decayDetector) {
                 return envelope({
                     success: false,
-                    message: '衰退检测器未初始化（decayDetector 未注册）',
+                    message: 'Decay detector not initialized (decayDetector not registered)',
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }
@@ -122,7 +122,7 @@ async function handleGovernanceOps(ctx, op) {
             if (!stagingManager) {
                 return envelope({
                     success: false,
-                    message: 'staging 管理器未初始化（stagingManager 未注册）',
+                    message: 'Staging manager not initialized (stagingManager not registered)',
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }
@@ -139,7 +139,7 @@ async function handleGovernanceOps(ctx, op) {
             if (!suggester) {
                 return envelope({
                     success: false,
-                    message: '增强建议器未初始化（enhancementSuggester 未注册）',
+                    message: 'Enhancement suggester not initialized (enhancementSuggester not registered)',
                     meta: { tool: 'autosnippet_panorama' },
                 });
             }

package/dist/lib/external/mcp/handlers/system.d.ts

@@ -12,7 +12,7 @@ export declare function health(ctx: McpContext): Promise<{
         issues?: string[] | undefined;
         session?: {
             id: string;
-            intentPhase: "idle" | "active" | "ended";
+            intentPhase: "active" | "idle" | "ended";
             toolCallCount: number;
             toolsUsed: string[];
             durationMs: number;

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

@@ -44,6 +44,10 @@ const _taskRules = {
  * Unified entry point
  */
 export async function taskHandler(ctx, args) {
+    // Normalize taskId → id (schema accepts both for convenience)
+    if (!args.id && typeof args.taskId === 'string') {
+        args.id = args.taskId;
+    }
     let result;
     switch (args.operation) {
         case 'prime':
@@ -88,11 +92,20 @@ async function _prime(ctx, args) {
     if (pipeline && extracted.queries[0]?.trim()) {
         try {
             searchResult = await pipeline.search(extracted);
+            if (!searchResult) {
+                process.stderr.write('[MCP/Task] prime: pipeline.search returned null (all filtered)\n');
+            }
         }
-        catch {
-            // search failure is non-fatal
+        catch (err) {
+            process.stderr.write(`[MCP/Task] prime search error: ${err instanceof Error ? err.stack || err.message : String(err)}\n`);
         }
     }
+    else if (!pipeline) {
+        process.stderr.write('[MCP/Task] prime: pipeline is null, skipping search\n');
+    }
+    else {
+        process.stderr.write(`[MCP/Task] prime: queries empty, skipping search. queries=${JSON.stringify(extracted.queries)}\n`);
+    }
     // ─── Lifecycle: initialize IntentState ───
     const freshIntent = createIdleIntent();
     freshIntent.phase = 'active';
@@ -124,7 +137,8 @@ async function _prime(ctx, args) {
         lines.push(`📋 Found ${relatedCount} recipe(s), ${ruleCount} guard rule(s).`);
         for (const r of searchResult.relatedKnowledge) {
             const hint = r.actionHint ? ` — ${r.actionHint}` : '';
-            lines.push(`  • ${r.trigger || r.title}${hint}`);
+            const refs = r.sourceRefs?.length ? `\n    📍 ${r.sourceRefs.join(', ')}` : '';
+            lines.push(`  • ${r.trigger || r.title}${hint}${refs}`);
         }
         for (const r of searchResult.guardRules) {
             lines.push(`  • [rule] ${r.trigger || r.title}`);
@@ -174,14 +188,16 @@ async function _create(ctx, args) {
 }
 // ═══ close ══════════════════════════════════════════════
 async function _close(ctx, args) {
-    if (!args.id) {
+    const intent = ctx.session?.intent;
+    // Resolve id: explicit arg > session intent > fail
+    const id = args.id || (intent?.taskId ?? '');
+    if (!id) {
         return envelope({
             success: false,
-            message: 'id is required',
+            message: 'id is required (pass id or ensure a task was created in this session)',
             meta: { tool: 'autosnippet_task' },
         });
     }
-    const intent = ctx.session?.intent;
     const reason = args.reason || 'Completed';
     // Persist intent chain via SignalBus
     if (intent && intent.phase === 'active') {
@@ -191,13 +207,13 @@ async function _close(ctx, args) {
     if (ctx.session) {
         ctx.session.intent = createIdleIntent();
     }
-    const lines = [`✅ Closed: ${args.id} — ${reason}`];
+    const lines = [`✅ Closed: ${id} — ${reason}`];
     lines.push('');
     lines.push('⚠️ REQUIRED: You MUST call autosnippet_guard (no args) NOW to review changed files for compliance violations.');
     return envelope({
         success: true,
         data: {
-            closed: { id: args.id, reason, closedAt: Date.now() },
+            closed: { id, reason, closedAt: Date.now() },
             nextAction: {
                 tool: 'autosnippet_guard',
                 args: {},
@@ -211,14 +227,16 @@ async function _close(ctx, args) {
 }
 // ═══ fail ═══════════════════════════════════════════════
 async function _fail(ctx, args) {
-    if (!args.id) {
+    const intent = ctx.session?.intent;
+    // Resolve id: explicit arg > session intent > fail
+    const id = args.id || (intent?.taskId ?? '');
+    if (!id) {
         return envelope({
             success: false,
-            message: 'id is required',
+            message: 'id is required (pass id or ensure a task was created in this session)',
             meta: { tool: 'autosnippet_task' },
         });
     }
-    const intent = ctx.session?.intent;
     const reason = args.reason || 'Agent execution failed';
     // Persist intent chain via SignalBus
     if (intent && intent.phase === 'active') {
@@ -231,9 +249,9 @@ async function _fail(ctx, args) {
     return envelope({
         success: true,
         data: {
-            failed: { id: args.id, reason, failedAt: Date.now() },
+            failed: { id, reason, failedAt: Date.now() },
         },
-        message: `❌ Failed: ${args.id} — ${reason}`,
+        message: `❌ Failed: ${id} — ${reason}`,
         meta: { tool: 'autosnippet_task' },
     });
 }
@@ -322,9 +340,14 @@ function _computeDriftScore(intent) {
 }
 function _getPipeline(container) {
     try {
-        return container.get('primeSearchPipeline');
+        const p = container.get('primeSearchPipeline');
+        if (!p) {
+            process.stderr.write('[MCP/Task] _getPipeline: container returned null/undefined\n');
+        }
+        return p;
     }
-    catch {
+    catch (err) {
+        process.stderr.write(`[MCP/Task] _getPipeline failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return null;
     }
 }

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

@@ -1,19 +1,19 @@
 /**
- * MCP 工具定义 — V3 整合版 (14 agent + 2 admin = 16 工具)
+ * MCP Tool Definitions — V3 Consolidated (14 agent + 2 admin = 16 tools)
  *
- * 每个工具声明包含 name、tier（agent/admin）、description 和 inputSchema。
- * description 是 Agent 选择工具的关键 — 使用 bullet list 列出所有 operation 及其用途。
- * inputSchema 由 Zod Schema 自动生成（zodToMcpSchema），参数的 .describe() 会转为 JSON Schema description。
+ * Each tool declaration contains name, tier (agent/admin), description, and inputSchema.
+ * description is the key for Agent tool selection — use bullet list to enumerate all operations and their purposes.
+ * inputSchema is auto-generated from Zod Schema (zodToMcpSchema); parameter .describe() translates to JSON Schema description.
  *
- * Agent 工具 (14):
- *   1-7:   查询工具 (health/search/knowledge/structure/graph/call_context/guard)
- *   8:     写入工具 (submit_knowledge — unified pipeline，单条/批量统一处理)
- *   9:     Skill 管理 (skill)
- *   10-12: 冷启动 (bootstrap/dimension_complete/wiki)
- *   13:    项目全景 (panorama)
- *   14:    任务管理 (task — 5 ops: prime/create/close/fail/record_decision)
+ * Agent tools (14):
+ *   1-7:   Query tools (health/search/knowledge/structure/graph/call_context/guard)
+ *   8:     Write tool (submit_knowledge — unified pipeline, single/batch)
+ *   9:     Skill management (skill)
+ *   10-12: Cold-start (bootstrap/dimension_complete/wiki)
+ *   13:    Project panorama (panorama)
+ *   14:    Task management (task — 5 ops: prime/create/close/fail/record_decision)
  *
- * Admin 工具 (2):
+ * Admin tools (2):
  *   15-16: enrich_candidates/knowledge_lifecycle
  */
 export declare const TIER_ORDER: {