autosnippet 3.3.3 → 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/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';
@@ -175,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') {
@@ -192,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: {},
@@ -212,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') {
@@ -232,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' },
     });
 }
@@ -323,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/service/task/IntentExtractor.d.ts

@@ -38,8 +38,10 @@ export interface TechTermOptions {
 export declare function extract(userQuery: string, activeFile?: string, language?: string, termOpts?: TechTermOptions): ExtractedIntent;
 /**
  * Build multi-query set from user query + active file.
- * Q1: raw query, Q2: extracted tech terms, Q3: file context.
+ * Q1: raw query, Q2: extracted tech terms, Q3: file context, Q4: synonym focus.
  * Q1 is enriched with cross-language synonyms to bridge EN↔CJK matching.
+ * Q4 (long queries only): synonym expansion as a separate focused query
+ * to prevent BM25 dilution in verbose natural language inputs.
  */
 export declare function buildQueries(userQuery: string, activeFile?: string, termOpts?: TechTermOptions): string[];
 /**

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

@@ -70,6 +70,13 @@ const SYNONYM_GROUPS = [
     ['sync', 'synchronous', '同步'],
     ['thread', 'threading', '线程'],
     ['concur', 'concurrency', '并发'],
+    // Memory management
+    ['memory', '内存'],
+    ['leak', 'leakage', '泄漏'],
+    ['weak', '弱引用'],
+    ['retain', '持有', '保留'],
+    ['release', '释放'],
+    ['reference', '引用'],
     // Common concepts
     ['network', '网络'],
     ['cache', 'caching', '缓存'],
@@ -120,8 +127,10 @@ export function extract(userQuery, activeFile, language, termOpts) {
 }
 /**
  * Build multi-query set from user query + active file.
- * Q1: raw query, Q2: extracted tech terms, Q3: file context.
+ * Q1: raw query, Q2: extracted tech terms, Q3: file context, Q4: synonym focus.
  * Q1 is enriched with cross-language synonyms to bridge EN↔CJK matching.
+ * Q4 (long queries only): synonym expansion as a separate focused query
+ * to prevent BM25 dilution in verbose natural language inputs.
  */
 export function buildQueries(userQuery, activeFile, termOpts) {
     // Enrich raw query with cross-language synonyms
@@ -132,6 +141,14 @@ export function buildQueries(userQuery, activeFile, termOpts) {
     if (terms.length > 0) {
         queries.push(terms.join(' '));
     }
+    // Q4: For long queries (> 50 chars), add cross-language synonyms as a
+    // separate focused query. In long sentences, synonym terms appended to Q1
+    // get diluted by common words ("ViewController", "ViewModel"), causing
+    // BM25 to miss the user's actual intent. A short focused query matches
+    // domain-specific terms (e.g. "singleton 单例 inject 注入") directly.
+    if (synonyms && userQuery.length > 50) {
+        queries.push(synonyms);
+    }
     if (activeFile) {
         const ctx = inferFileContext(activeFile);
         if (ctx) {
@@ -203,7 +220,7 @@ export function inferLanguage(filePath) {
  */
 export function classifyScenario(userQuery) {
     const q = userQuery.toLowerCase();
-    if (/帮我[加写做实现创建]|implement|add|create|新[增加建]/.test(q)) {
+    if (/帮我[加写做实现创建]|implement|add|create|新[增加建]|添加|修改|删除|实现|开发|编写|创建|初始化/.test(q)) {
         return 'generate';
     }
     if (/检查|review|lint|合规|违规|guard|规[则范]/.test(q)) {
@@ -220,23 +237,26 @@ export function classifyScenario(userQuery) {
  * Tokenizes query, looks up each token in the synonym table,
  * returns a query string of synonym expansions for cross-language matching.
  *
- * Strategy: return only cross-script synonyms (EN→CJK or CJK→EN).
- * This keeps the expansion focused — the original script tokens are already in Q1.
+ * Strategy: per-token cross-script expansion. Each token's script is checked
+ * individually, and only synonyms in the OPPOSITE script are added.
+ * This correctly handles mixed EN/CJK queries (e.g. "在 module 里用 singleton")
+ * where both EN→CJK and CJK→EN expansions are needed.
  */
 function expandWithSynonyms(query) {
     const tokens = tokenize(query);
     const crossScriptTerms = new Set();
-    // Detect query script: does it contain CJK?
-    const hasCJK = /[\u4e00-\u9fff\u3400-\u4dbf]/.test(query);
+    const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf]/;
     for (const token of tokens) {
         const synonyms = SYNONYM_LOOKUP.get(token.toLowerCase());
         if (!synonyms) {
             continue;
         }
+        // Determine THIS token's script, not the whole query's
+        const tokenIsCJK = CJK_RE.test(token);
         for (const syn of synonyms) {
-            const synIsCJK = /[\u4e00-\u9fff\u3400-\u4dbf]/.test(syn);
-            // Cross-script: EN query → add CJK synonyms; CJK query → add EN synonyms
-            if (hasCJK !== synIsCJK) {
+            const synIsCJK = CJK_RE.test(syn);
+            // Cross-script: EN token → add CJK synonyms; CJK token → add EN synonyms
+            if (tokenIsCJK !== synIsCJK) {
                 crossScriptTerms.add(syn);
             }
         }
@@ -244,7 +264,7 @@ function expandWithSynonyms(query) {
     if (crossScriptTerms.size === 0) {
         return null;
     }
-    return [...crossScriptTerms].slice(0, 12).join(' ');
+    return [...crossScriptTerms].slice(0, 16).join(' ');
 }
 function buildPrefixPattern(prefixes) {
     if (prefixes.length === 0) {

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

@@ -8,7 +8,12 @@
  */
 import { slimSearchResult } from '#service/search/SearchTypes.js';
 // ── Constants ───────────────────────────────────────
-const RELEVANCE_THRESHOLD = 0.01;
+/** Absolute minimum score — items below this are definitely noise */
+const MIN_SCORE_THRESHOLD = 0.3;
+/** Relative threshold — items scoring below this fraction of the best result are dropped */
+const RELATIVE_SCORE_RATIO = 0.15;
+/** Gap ratio — if score drops by more than this factor from the previous item, truncate */
+const GAP_DROP_RATIO = 0.25;
 // ── PrimeSearchPipeline ─────────────────────────────
 export class PrimeSearchPipeline {
     #search;
@@ -31,8 +36,8 @@ export class PrimeSearchPipeline {
         };
         // Multi-query parallel search (auto mode + keyword mode for cross-language)
         const allResults = await this.#multiQuerySearch(intent.queries, intent.keywordQueries ?? [], context);
-        // Threshold filter
-        const filtered = allResults.filter((r) => (r.score ?? 0) >= RELEVANCE_THRESHOLD);
+        // Quality filter: absolute threshold + relative-to-best + score gap detection
+        const filtered = this.#qualityFilter(allResults);
         if (filtered.length === 0) {
             return null;
         }
@@ -62,14 +67,46 @@ export class PrimeSearchPipeline {
     }
     // ── Private ───────────────────────────────────────
     /**
-     * Multi-query parallel search with Reciprocal Rank Fusion (RRF).
-     * Auto-mode queries use CoarseRanker; keyword queries use raw FWS scores.
-     * Results are fused by rank position, not absolute scores — robust across heterogeneous scorers.
+     * Quality filter: absolute threshold + relative-to-best + score gap detection.
+     * Expects items sorted by score descending.
+     */
+    #qualityFilter(items) {
+        if (items.length === 0) {
+            return [];
+        }
+        const maxScore = items[0]?.score ?? 0;
+        const effectiveThreshold = Math.max(MIN_SCORE_THRESHOLD, maxScore * RELATIVE_SCORE_RATIO);
+        const result = [];
+        let prevScore = maxScore;
+        for (const item of items) {
+            const score = item.score;
+            if (score < effectiveThreshold) {
+                break;
+            }
+            // Gap detection: if score drops sharply from previous item, stop
+            if (result.length > 0 && score < prevScore * GAP_DROP_RATIO) {
+                break;
+            }
+            result.push(item);
+            prevScore = score;
+        }
+        return result;
+    }
+    /**
+     * Multi-query parallel search with optional Reciprocal Rank Fusion (RRF).
+     *
+     * Single-query: preserves original search engine scores (BM25/CoarseRanker).
+     * Multi-query: uses RRF to fuse results, but weights by original score to
+     * retain magnitude information.
      */
     async #multiQuerySearch(autoQueries, keywordQueries, context) {
-        // Auto-mode searches (full CoarseRanker pipeline)
+        // Auto-mode searches (BM25 without CoarseRanker ranking)
+        // Using rank: false preserves raw BM25/FWS score magnitude,
+        // which the quality filter needs for effective discrimination.
+        // CoarseRanker's max-normalization + freshness/popularity signals
+        // would cluster scores around 0.35–0.41, defeating the filter.
         const autoPromises = autoQueries.map((q) => this.#search
-            .search(q, { mode: 'auto', limit: 8, rank: true, context })
+            .search(q, { mode: 'auto', limit: 8, rank: false, context })
             .catch(() => ({ items: [] })));
         // Keyword-mode searches (raw FWS scores — for cross-language synonym matching)
         const kwPromises = keywordQueries.map((q) => this.#search
@@ -80,15 +117,25 @@ export class PrimeSearchPipeline {
             Promise.all(kwPromises),
         ]);
         const allResponses = [...autoResponses, ...kwResponses];
-        // Reciprocal Rank Fusion: RRF(d) = Σ 1/(k + rank)
+        // Single-query shortcut: preserve original scores from search engine.
+        // RRF is pointless with one response — it just converts rank to score,
+        // discarding the magnitude information from BM25/CoarseRanker.
+        if (allResponses.length === 1) {
+            const items = (allResponses[0]?.items || []);
+            return items.map(slimSearchResult).sort((a, b) => b.score - a.score);
+        }
+        // Multi-query: Weighted RRF — RRF(d) = Σ origScore / (k + rank)
+        // Retains original score magnitude while still boosting cross-query overlap.
         const RRF_K = 60;
         const rrfScores = new Map();
         const itemById = new Map();
         for (const resp of allResponses) {
             const items = (resp.items || []);
             for (let rank = 0; rank < items.length; rank++) {
-                const item = slimSearchResult(items[rank]);
-                rrfScores.set(item.id, (rrfScores.get(item.id) ?? 0) + 1 / (RRF_K + rank));
+                const raw = items[rank];
+                const origScore = Math.max(raw.score || 0, 0.01);
+                const item = slimSearchResult(raw);
+                rrfScores.set(item.id, (rrfScores.get(item.id) ?? 0) + origScore / (RRF_K + rank));
                 // Keep the richest metadata version
                 if (!itemById.has(item.id)) {
                     itemById.set(item.id, item);
@@ -96,10 +143,18 @@ export class PrimeSearchPipeline {
             }
         }
         // Assign fused scores and sort
+        // Rescale: RRF_K division crushes scores to ~0.003–0.02 range,
+        // which falls below qualityFilter's MIN_SCORE_THRESHOLD (0.1).
+        // Multiply by RRF_K to restore original score magnitude.
+        // Effective formula: Σ origScore / (1 + rank/K), preserving magnitude
+        // while still giving a gentle rank-based discount.
         const results = [];
         for (const [id, rrfScore] of rrfScores) {
             const item = itemById.get(id);
-            item.score = rrfScore;
+            if (!item) {
+                continue;
+            }
+            item.score = Math.round(rrfScore * RRF_K * 1000) / 1000;
             results.push(item);
         }
         return results.sort((a, b) => b.score - a.score);

package/dist/lib/shared/schemas/mcp-tools.d.ts

@@ -247,6 +247,7 @@ export declare const TaskInput: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;
     rationale: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/lib/shared/schemas/mcp-tools.js

@@ -235,7 +235,11 @@ export const TaskInput = z.object({
         .describe('prime=加载知识上下文 | create=创建任务锚点 | close=完成+Guard | fail=放弃 | record_decision=记录用户偏好'),
     title: z.string().optional().describe('Task or decision title (create / record_decision)'),
     description: z.string().optional().describe('Decision description (record_decision)'),
-    id: z.string().optional().describe('Task ID (close / fail)'),
+    id: z
+        .string()
+        .optional()
+        .describe('Task ID (close / fail). Optional if a task was created in the current session.'),
+    taskId: z.string().optional().describe('Alias for id (accepted for convenience)'),
     reason: z.string().optional().describe('Close reason or fail reason'),
     rationale: z.string().optional().describe('Decision rationale (record_decision)'),
     tags: z.array(z.string()).optional().describe('Decision tags (record_decision)'),

package/package.json

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

package/templates/instructions/conventions.md

@@ -13,11 +13,13 @@ Users speak naturally; you translate to task operations. Never tell users to cal
 
 | User Says | You Run |
 |---|---|
-| "fix bug" / "implement" | `create` → code → `close` |
-| "continue" | resume in-progress → `close` |
+| "fix bug" / "implement" | `create` → code → `close` → `autosnippet_guard()` |
+| "continue" | resume in-progress → `close` → `autosnippet_guard()` |
 | "pause" / "abandon" | `fail(id, reason)` |
 | "agreed" | `record_decision(...)` |
 
+7. **After close** — MUST call `autosnippet_guard()` (no args) for compliance review before moving on. Never skip.
+
 ## Knowledge Rules
 
 - **Do NOT modify** `AutoSnippet/recipes/` or `.autosnippet/` directly.