@itradingai/aiwiki 0.2.15 → 0.2.18

package/README.md

@@ -247,3 +247,37 @@ aiwiki lint --path "F:\knowledge_data\aiwiki-test"
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+## Query Filters
+
+AIWiki retrieval is local Markdown/frontmatter search. It is intentionally lightweight: no vector search, no database, no external search, and no RAG-over-wiki.
+
+```bash
+aiwiki context "AI Agent" --type wiki_entries --source-role input --wiki-type source_knowledge --status active --limit 5
+aiwiki query "AI Agent" --type source_cards --status to-review --limit 3
+```
+
+`context` returns Agent-readable JSON with `query_scope`, `result_quality`, `recommended_next_action`, `match_reasons`, `quality_signals`, and `related_refs`. `query` uses the same retrieval path and shows the match reasons and quality hints for humans.
+
+## Agent Skill Sync and Upgrade
+
+AIWiki is Agent-first: after installing or upgrading the npm package, sync the packaged AIWiki skill into the local Agent environment.
+
+First install and later upgrades use the same safe command:
+
+```bash
+npm install -g @itradingai/aiwiki@latest
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+For one Agent:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+`agent sync` is idempotent. Missing targets are installed, current targets are left unchanged, and changed old skill files are backed up before overwrite. Use `--dry-run` to preview and `--json` when an AI Agent needs stable machine-readable status.
+
+After sync, restart or reload the target Agent so it reads the new AIWiki skill. To roll back, copy the generated `.bak-<timestamp>` file back over the target skill file.

package/dist/src/app.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { flagBool, flagString, parseArgs } from "./args.js";
 import { buildContext } from "./context.js";
 import { deriveFileTitle, ingestFile, ingestPayload } from "./ingest.js";
-import { lintWorkspace, renderLintReport, writeLintReport } from "./lint.js";
+import { filterLintReport, lintWorkspace, renderLintReport, renderLintSummary, writeLintReport } from "./lint.js";
 import { CliError, writeLine } from "./output.js";
 import { confirmInit, directorySummary, doctor, exists, initWorkspace, promptForSetup, promptForInitPath, readConfig, resolveWorkspace, setDefaultWorkspace, statusSummary } from "./workspace.js";
 export async function runCli(argv, streams = { stdout: process.stdout, stderr: process.stderr }) {
@@ -17,6 +17,14 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             writeLine(streams.stdout, `aiwiki ${await packageVersion()}`);
             return 0;
         }
+        if (command === "agent" && (subcommand === "help" || args.flags.has("help"))) {
+            printAgentHelp(streams.stdout);
+            return 0;
+        }
+        if ((command === "context" || command === "query") && args.flags.has("help")) {
+            printContextHelp(streams.stdout);
+            return 0;
+        }
         if (args.flags.has("help") || !command || command === "help" || command === "-h") {
             printHelp(streams.stdout);
             return 0;
@@ -54,8 +62,24 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             }
             return 0;
         }
+        if (command === "agent" && subcommand === "sync") {
+            const result = await syncAgentSkills({
+                agentId: flagString(args, "agent"),
+                yes: flagBool(args, "yes"),
+                dryRun: flagBool(args, "dry-run"),
+                json: flagBool(args, "json"),
+                streams
+            });
+            if (flagBool(args, "json")) {
+                writeLine(streams.stdout, JSON.stringify(result, null, 2));
+            }
+            else {
+                printAgentSyncResult(streams.stdout, result);
+            }
+            return 0;
+        }
         if (command === "agent" && subcommand === "check") {
-            await printAgentCheck(streams.stdout, await discoverAgentTargets());
+            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(), flagBool(args, "json"));
             return 0;
         }
         if (command === "agent" && (subcommand === "list" || !subcommand)) {
@@ -137,7 +161,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             if (!query) {
                 throw new CliError("请提供查询主题。");
             }
-            writeLine(streams.stdout, JSON.stringify(await buildContext(root, query), null, 2));
+            writeLine(streams.stdout, JSON.stringify(await buildContext(root, query, contextOptions(args)), null, 2));
             return 0;
         }
         if (command === "query") {
@@ -146,7 +170,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             if (!query) {
                 throw new CliError("请提供查询主题。");
             }
-            writeLine(streams.stdout, renderQuery(await buildContext(root, query)));
+            writeLine(streams.stdout, renderQuery(await buildContext(root, query, contextOptions(args))));
             return 0;
         }
         if (command === "next") {
@@ -159,10 +183,16 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
         }
         if (command === "lint") {
             const root = await resolveWorkspace(flagString(args, "path"));
-            const report = await lintWorkspace(root);
-            const reportPath = await writeLintReport(root, report);
+            const severity = parseLintSeverity(flagString(args, "severity"));
+            const report = filterLintReport(await lintWorkspace(root), severity);
+            if (flagBool(args, "json")) {
+                writeLine(streams.stdout, JSON.stringify(report, null, 2));
+                return 0;
+            }
+            const reportPath = flagBool(args, "no-write") ? undefined : await writeLintReport(root, report);
+            writeLine(streams.stdout, renderLintSummary(report, reportPath));
+            writeLine(streams.stdout, "");
             writeLine(streams.stdout, renderLintReport(report));
-            writeLine(streams.stdout, `report: ${reportPath}`);
             return 0;
         }
         if (command === "ingest-agent") {
@@ -241,6 +271,8 @@ function printHelp(stream) {
     writeLine(stream, "  aiwiki agent list");
     writeLine(stream, "  aiwiki agent install");
     writeLine(stream, "  aiwiki agent install --agent codex --yes");
+    writeLine(stream, "  aiwiki agent sync --yes");
+    writeLine(stream, "  aiwiki agent check --json");
     writeLine(stream, "  aiwiki prompt agent");
     writeLine(stream, "  aiwiki doctor");
     writeLine(stream, "  aiwiki status");
@@ -256,6 +288,50 @@ function printHelp(stream) {
     writeLine(stream, "  aiwiki ingest-url <url> --content-file <file>");
     writeLine(stream, "  aiwiki agent check");
 }
+function printAgentHelp(stream) {
+    writeLine(stream, "AIWiki Agent commands");
+    writeLine(stream, "");
+    writeLine(stream, "Agent-first setup and upgrade:");
+    writeLine(stream, "  aiwiki agent sync --yes");
+    writeLine(stream, "  aiwiki agent sync --agent codex --yes");
+    writeLine(stream, "  aiwiki agent sync --agent codex --dry-run");
+    writeLine(stream, "  aiwiki agent sync --json --yes");
+    writeLine(stream, "");
+    writeLine(stream, "Status:");
+    writeLine(stream, "  aiwiki agent check");
+    writeLine(stream, "  aiwiki agent check --json");
+    writeLine(stream, "");
+    writeLine(stream, "Compatibility:");
+    writeLine(stream, "  aiwiki agent install --agent codex --yes");
+    writeLine(stream, "  aiwiki agent install --agent codex --yes --force");
+    writeLine(stream, "");
+    writeLine(stream, "sync is idempotent: missing targets are installed, current targets are left unchanged, and different targets are backed up before overwrite.");
+}
+function printContextHelp(stream) {
+    writeLine(stream, "AIWiki context/query");
+    writeLine(stream, "");
+    writeLine(stream, "Local Markdown/frontmatter retrieval for host Agents and humans:");
+    writeLine(stream, "  aiwiki context <topic> --limit 10");
+    writeLine(stream, "  aiwiki query <topic> --type wiki_entries --status active");
+    writeLine(stream, "");
+    writeLine(stream, "Filters:");
+    writeLine(stream, "  --type wiki_entries|source_cards|claims|topics|outlines|raw_refs");
+    writeLine(stream, "  --source-role input|processing|output");
+    writeLine(stream, "  --wiki-type source_knowledge|personal_knowledge");
+    writeLine(stream, "  --status active|to-review|ready|draft");
+    writeLine(stream, "  --limit <1-50>");
+    writeLine(stream, "");
+    writeLine(stream, "context JSON includes query_scope, result_quality, recommended_next_action, match_reasons, quality_signals, and related_refs.");
+}
+function parseLintSeverity(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "error" || value === "warning" || value === "info") {
+        return value;
+    }
+    throw new CliError("lint --severity must be error, warning, or info");
+}
 async function discoverAgentTargets() {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
     const skillSource = path.join(packageRoot, "skill", "SKILL.md");
@@ -347,6 +423,40 @@ async function printAgentCheck(stream, targets) {
         }
     }
 }
+async function printAgentCheckDetailed(stream, targets, json = false) {
+    const checked = await Promise.all(targets.map(async (target) => ({
+        ...target,
+        state: await inspectAgentTarget(target),
+        installed: target.target ? await exists(target.target) : false
+    })));
+    if (json) {
+        writeLine(stream, JSON.stringify({
+            schema_version: "aiwiki.agent_check.v1",
+            generated_at: new Date().toISOString(),
+            targets: checked.map((target) => ({
+                id: target.id,
+                name: target.name,
+                detected: target.detected,
+                installable: target.installable,
+                installed: target.installed,
+                state: target.state,
+                source: target.source,
+                target: target.target
+            }))
+        }, null, 2));
+        return;
+    }
+    writeLine(stream, "AIWiki Agent check");
+    for (const target of checked) {
+        writeLine(stream, `${target.id}: ${target.name} | detected=${target.detected ? "yes" : "no"} | installed=${target.installed ? "yes" : "no"} | installable=${target.installable ? "yes" : "no"} | state=${target.state}`);
+        if (target.detected && target.installable && (target.state === "missing" || target.state === "different")) {
+            writeLine(stream, `  suggested: aiwiki agent sync --agent ${target.id} --yes`);
+        }
+        else if (target.detected && !target.installable) {
+            writeLine(stream, "  suggested: aiwiki prompt agent");
+        }
+    }
+}
 async function installAgentSkill(options) {
     const targets = await discoverAgentTargets();
     const installable = targets.filter((target) => target.detected && target.installable);
@@ -385,8 +495,8 @@ async function installAgentSkill(options) {
             return undefined;
         }
     }
-    await copyInstallFile(selected.source, selected.target, options.force);
-    return selected;
+    const result = await copyInstallFileSafe(selected.source, selected.target, options.force);
+    return { ...selected, ...result };
 }
 async function askQuestion(streams, question) {
     if (!process.stdin.isTTY) {
@@ -400,7 +510,28 @@ async function askQuestion(streams, question) {
         rl.close();
     }
 }
+async function syncAgentSkills(options) {
+    const targets = await discoverAgentTargets();
+    const selected = options.agentId ? targets.find((target) => target.id === options.agentId) : undefined;
+    if (!selected && options.agentId) {
+        throw new CliError(`未知宿主 Agent: ${options.agentId}`);
+    }
+    const syncTargets = selected ? [selected] : targets.filter((target) => target.detected && target.installable);
+    if (!syncTargets.length) {
+        throw new CliError("No detected installable Agent targets. Run aiwiki agent list or aiwiki prompt agent.");
+    }
+    if (!options.yes && !options.dryRun) {
+        throw new CliError("agent sync modifies Agent skill files. Re-run with --yes, or use --dry-run to preview.");
+    }
+    return {
+        schema_version: "aiwiki.agent_sync.v1",
+        generated_at: new Date().toISOString(),
+        dry_run: options.dryRun,
+        results: await Promise.all(syncTargets.map((target) => syncAgentTarget(target, options.dryRun)))
+    };
+}
 async function copyInstallFile(source, target, force) {
+    return copyInstallFileSafe(source, target, force);
     await fs.access(source);
     if (!force && (await exists(target))) {
         throw new CliError(`目标文件已存在: ${target}。如需覆盖，请加 --force。`);
@@ -408,6 +539,84 @@ async function copyInstallFile(source, target, force) {
     await fs.mkdir(path.dirname(target), { recursive: true });
     await fs.copyFile(source, target);
 }
+async function copyInstallFileSafe(source, target, force) {
+    await fs.access(source);
+    const targetExists = await exists(target);
+    if (!force && targetExists) {
+        throw new CliError(`目标文件已存在: ${target}。如需覆盖，请运行 aiwiki agent sync --agent <id> --yes，或为 install 加 --force。`);
+    }
+    if (targetExists && await sameFileContent(source, target)) {
+        return { action: "current" };
+    }
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const backupPath = targetExists ? await backupFile(target) : undefined;
+    await fs.copyFile(source, target);
+    return { action: targetExists ? "updated" : "installed", backupPath };
+}
+async function inspectAgentTarget(target) {
+    if (!target.installable || !target.source || !target.target) {
+        return "unsupported";
+    }
+    if (!(await exists(target.target))) {
+        return "missing";
+    }
+    return await sameFileContent(target.source, target.target) ? "current" : "different";
+}
+async function syncAgentTarget(target, dryRun) {
+    const state = await inspectAgentTarget(target);
+    const base = {
+        id: target.id,
+        name: target.name,
+        detected: target.detected,
+        installable: target.installable,
+        state,
+        target: target.target,
+        source: target.source,
+        changed: false,
+        dryRun
+    };
+    if (state === "unsupported" || !target.source || !target.target) {
+        return { ...base, action: "unsupported", note: target.note };
+    }
+    if (state === "current") {
+        return { ...base, action: "current" };
+    }
+    if (dryRun) {
+        return { ...base, action: state === "missing" ? "would_install" : "would_update", changed: true };
+    }
+    const result = await copyInstallFileSafe(target.source, target.target, true);
+    return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
+}
+async function sameFileContent(source, target) {
+    try {
+        const [sourceText, targetText] = await Promise.all([fs.readFile(source, "utf8"), fs.readFile(target, "utf8")]);
+        return sourceText === targetText;
+    }
+    catch {
+        return false;
+    }
+}
+async function backupFile(target) {
+    const parsed = path.parse(target);
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+    const backupPath = path.join(parsed.dir, `${parsed.base}.bak-${stamp}`);
+    await fs.copyFile(target, backupPath);
+    return backupPath;
+}
+function printAgentSyncResult(stream, report) {
+    writeLine(stream, "AIWiki Agent sync");
+    writeLine(stream, `dry_run: ${report.dry_run ? "yes" : "no"}`);
+    for (const item of report.results) {
+        writeLine(stream, `${item.id}: ${item.name} | state=${item.state} | action=${item.action} | changed=${item.changed ? "yes" : "no"}`);
+        if (item.target) {
+            writeLine(stream, `  target: ${item.target}`);
+        }
+        if (item.backupPath) {
+            writeLine(stream, `  backup: ${item.backupPath}`);
+        }
+    }
+    writeLine(stream, "next: restart or reload the target Agent so it reads the synced AIWiki skill.");
+}
 function printAgentPrompt(stream) {
     writeLine(stream, "AIWiki Agent 中文提示");
     writeLine(stream, "");
@@ -493,7 +702,7 @@ async function printNext(stream, root, runCount, checks, targets, report) {
     if (runCount === 0) {
         writeLine(stream, "");
         writeLine(stream, "No ingest records yet.");
-        writeLine(stream, "- aiwiki agent install");
+        writeLine(stream, "- aiwiki agent sync --yes");
         writeLine(stream, "- Then ask the host Agent to ingest a URL.");
         writeLine(stream, "- AIWiki CLI does not fetch webpages; the host Agent supplies content.");
         writeLine(stream, "- repair_order: empty_workspace");
@@ -520,12 +729,25 @@ function recommendedNextAction(runCount, lintStatus, hasMissingSystemFiles) {
         return "next_action: aiwiki lint";
     }
     if (runCount === 0) {
-        return "next_action: aiwiki agent install";
+        return "next_action: aiwiki agent sync --yes";
     }
     return "next_action: aiwiki query <topic>";
 }
+function contextOptions(args) {
+    const limit = flagString(args, "limit");
+    return {
+        filters: {
+            type: flagString(args, "type"),
+            source_role: flagString(args, "source-role"),
+            wiki_type: flagString(args, "wiki-type"),
+            status: flagString(args, "status")
+        },
+        limit: limit === undefined ? undefined : Number(limit)
+    };
+}
 function renderQuery(context) {
     const lines = [`AIWiki 查询: ${context.query}`, ""];
+    lines.push(`结果质量: matches=${context.result_quality.total_matches}, best_score=${context.result_quality.best_score}, has_wiki_entry=${context.result_quality.has_wiki_entry ? "yes" : "no"}`, `下一步建议: ${context.recommended_next_action}`, `查询范围: groups=${context.query_scope.searched_groups.join(",") || "none"}, limit=${context.query_scope.limit}, filters=${JSON.stringify(context.query_scope.filters)}`, "");
     appendQueryGroup(lines, "Wiki 条目", context.matches.wiki_entries);
     appendQueryGroup(lines, "资料卡", context.matches.source_cards);
     appendQueryGroup(lines, "选题", context.matches.topics);
@@ -546,9 +768,13 @@ function appendQueryGroup(lines, label, items) {
     }
     for (const item of items.slice(0, 5)) {
         lines.push(`- ${item.title} (${item.path})`);
+        lines.push(`  score=${item.score}; reasons=${item.match_reasons.join(",") || "unknown"}; quality=${item.quality_signals.join(",") || "none"}`);
         if (item.summary) {
             lines.push(`  ${item.summary}`);
         }
+        if (item.related_refs.length) {
+            lines.push(`  related: ${item.related_refs.slice(0, 5).join("; ")}`);
+        }
         if (item.warnings.length) {
             lines.push(`  提示: ${item.warnings.join("；")}`);
         }

package/dist/src/context.js

@@ -11,13 +11,28 @@ const GROUPS = [
     { key: "outlines", dir: "08-outputs/outlines", weight: 2 },
     { key: "raw_refs", dir: "02-raw/articles", weight: 1 }
 ];
-export async function buildContext(rootPath, query, now = new Date().toISOString()) {
+const DEFAULT_LIMIT = 10;
+export async function buildContext(rootPath, query, options = {}, now = new Date().toISOString()) {
     const root = path.resolve(rootPath);
     const tokens = tokenize(query);
+    const limit = normalizeLimit(options.limit);
+    const filters = normalizeFilters(options.filters);
     const result = {
         schema_version: "aiwiki.context.v1",
         query,
         generated_at: now,
+        query_scope: {
+            filters,
+            limit,
+            searched_groups: []
+        },
+        result_quality: {
+            total_matches: 0,
+            best_score: 0,
+            has_wiki_entry: false,
+            warnings: []
+        },
+        recommended_next_action: "broaden_query",
         matches: {
             wiki_entries: [],
             source_cards: [],
@@ -26,34 +41,41 @@ export async function buildContext(rootPath, query, now = new Date().toISOString
             outlines: [],
             raw_refs: []
         },
-        suggested_answer_structure: ["主题概览", "核心观点", "已有资料依据", "可复用判断", "下一步建议"],
+        suggested_answer_structure: ["topic overview", "core claims", "available evidence", "reuse judgment", "next action"],
         warnings: []
     };
     if (!tokens.length) {
         result.warnings.push("query is empty after tokenization");
+        finalizeQuality(result);
         return result;
     }
     for (const group of GROUPS.filter((item) => item.key !== "raw_refs")) {
+        if (!groupAllowed(group.key, filters.type)) {
+            continue;
+        }
         const dir = path.join(root, group.dir);
         if (!(await exists(dir))) {
             continue;
         }
-        const matches = await searchDir(root, dir, tokens, group.weight);
-        result.matches[group.key].push(...matches.slice(0, 10));
+        result.query_scope.searched_groups.push(group.key);
+        const matches = await searchDir(root, dir, tokens, group.weight, group.key, filters);
+        result.matches[group.key].push(...matches.slice(0, limit));
     }
-    if (!result.matches.wiki_entries.length) {
-        result.warnings.push("未命中 Wiki Entry，结果可能来自资料卡、选题或原文引用。");
+    if (!result.matches.wiki_entries.length && groupAllowed("raw_refs", filters.type)) {
+        result.warnings.push("No Wiki Entry matched; results may come from source cards, topics, outlines, or raw references.");
         const rawGroup = GROUPS.find((item) => item.key === "raw_refs");
         if (rawGroup) {
             const rawDir = path.join(root, rawGroup.dir);
             if (await exists(rawDir)) {
-                result.matches.raw_refs.push(...(await searchDir(root, rawDir, tokens, rawGroup.weight)).slice(0, 10));
+                result.query_scope.searched_groups.push(rawGroup.key);
+                result.matches.raw_refs.push(...(await searchDir(root, rawDir, tokens, rawGroup.weight, rawGroup.key, filters)).slice(0, limit));
             }
         }
     }
+    finalizeQuality(result);
     return result;
 }
-async function searchDir(root, dir, tokens, weight) {
+async function searchDir(root, dir, tokens, weight, groupKey, filters) {
     const files = await listMarkdownFiles(dir);
     const matches = [];
     for (const file of files) {
@@ -61,12 +83,24 @@ async function searchDir(root, dir, tokens, weight) {
         const parsed = parseMarkdown(text);
         const rel = relativePath(root, file);
         const title = frontmatterString(parsed.frontmatter, "title") ?? path.basename(file, ".md");
+        const type = frontmatterString(parsed.frontmatter, "type") ?? groupKey;
+        const status = frontmatterString(parsed.frontmatter, "status");
+        const sourceRole = frontmatterString(parsed.frontmatter, "source_role");
+        const wikiType = frontmatterString(parsed.frontmatter, "wiki_type");
+        if (!passesFilters({ type, groupKey, status, source_role: sourceRole, wiki_type: wikiType }, filters)) {
+            continue;
+        }
+        const topics = frontmatterArray(parsed.frontmatter, "topics");
+        const tags = frontmatterArray(parsed.frontmatter, "tags");
+        const relatedRefs = relatedReferences(parsed.frontmatter, parsed.body);
+        const sourceUrl = frontmatterString(parsed.frontmatter, "source_url") ?? "";
         const haystack = [
             rel,
             title,
-            frontmatterString(parsed.frontmatter, "source_url") ?? "",
-            frontmatterArray(parsed.frontmatter, "topics").join(" "),
-            frontmatterArray(parsed.frontmatter, "tags").join(" "),
+            sourceUrl,
+            topics.join(" "),
+            tags.join(" "),
+            relatedRefs.join(" "),
             parsed.body
         ].join("\n").toLowerCase();
         const hits = tokens.filter((token) => haystack.includes(token.toLowerCase())).length;
@@ -77,8 +111,9 @@ async function searchDir(root, dir, tokens, weight) {
         const quality = frontmatterString(parsed.frontmatter, "quality");
         const groundingMarkers = frontmatterArray(parsed.frontmatter, "grounding_markers");
         const groundingNeedsReview = frontmatterBoolean(parsed.frontmatter, "grounding_needs_review");
+        const groundingEvidenceAvailable = frontmatterBoolean(parsed.frontmatter, "grounding_evidence_available");
         const warnings = generationMode === "deterministic_fallback"
-            ? ["该 Wiki Entry 是 deterministic fallback，仅包含来源、正文预览和待补全区。"]
+            ? ["This Wiki Entry is a deterministic fallback; it may need host-agent enrichment."]
             : [];
         if (groundingNeedsReview) {
             warnings.push(`Grounding needs review${groundingMarkers.length ? `: ${groundingMarkers.join(", ")}` : ""}.`);
@@ -88,11 +123,19 @@ async function searchDir(root, dir, tokens, weight) {
             path: rel,
             summary: frontmatterString(parsed.frontmatter, "summary") ?? summarize(parsed.body, quality),
             score: Number(((hits / tokens.length) * weight).toFixed(2)),
-            topics: frontmatterArray(parsed.frontmatter, "topics"),
-            source_url: frontmatterString(parsed.frontmatter, "source_url") ?? "",
+            type,
+            topics,
+            tags,
+            source_url: sourceUrl,
+            status,
+            source_role: sourceRole,
+            wiki_type: wikiType,
+            match_reasons: matchReasons(tokens, { rel, title, body: parsed.body, topics, tags, relatedRefs, sourceUrl }),
+            quality_signals: qualitySignals({ quality, generationMode, groundingEvidenceAvailable, groundingNeedsReview, status, relatedRefs }),
+            related_refs: relatedRefs,
             generation_mode: generationMode,
             quality,
-            grounding_evidence_available: frontmatterBoolean(parsed.frontmatter, "grounding_evidence_available"),
+            grounding_evidence_available: groundingEvidenceAvailable,
             grounding_needs_review: groundingNeedsReview,
             grounding_markers: groundingMarkers,
             warnings
@@ -125,7 +168,121 @@ function tokenize(value) {
 function summarize(body, quality) {
     const compact = body.replace(/\s+/g, " ").trim();
     if (quality === "scaffold") {
-        return "仅有正文预览，未生成高质量摘要。";
+        return "Only a scaffold preview is available; enrich before relying on it as a final answer.";
     }
     return compact.length > 180 ? `${compact.slice(0, 180)}...` : compact;
 }
+function normalizeLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_LIMIT;
+    }
+    return Math.max(1, Math.min(50, Math.floor(value)));
+}
+function normalizeFilters(filters) {
+    return Object.fromEntries(Object.entries(filters ?? {})
+        .filter(([, value]) => typeof value === "string" && value.trim())
+        .map(([key, value]) => [key, String(value).trim()]));
+}
+function groupAllowed(groupKey, typeFilter) {
+    if (!typeFilter) {
+        return true;
+    }
+    return normalizeType(typeFilter) === normalizeType(groupKey);
+}
+function passesFilters(item, filters) {
+    if (filters.type && normalizeType(filters.type) !== normalizeType(item.type) && normalizeType(filters.type) !== normalizeType(item.groupKey)) {
+        return false;
+    }
+    if (filters.status && filters.status !== item.status) {
+        return false;
+    }
+    if (filters.source_role && filters.source_role !== item.source_role) {
+        return false;
+    }
+    if (filters.wiki_type && filters.wiki_type !== item.wiki_type) {
+        return false;
+    }
+    return true;
+}
+function normalizeType(value) {
+    return value.replace(/-/g, "_").toLowerCase();
+}
+function relatedReferences(frontmatter, body) {
+    const refs = [
+        frontmatterString(frontmatter, "source_card"),
+        frontmatterString(frontmatter, "raw_file"),
+        frontmatterString(frontmatter, "claims_note"),
+        frontmatterString(frontmatter, "assets_note"),
+        frontmatterString(frontmatter, "topics_note"),
+        frontmatterString(frontmatter, "outline_note"),
+        ...extractWikilinks(body)
+    ].filter((value) => Boolean(value));
+    return Array.from(new Set(refs));
+}
+function extractWikilinks(body) {
+    const refs = [];
+    const pattern = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+    for (const match of body.matchAll(pattern)) {
+        refs.push(match[1].trim());
+    }
+    return refs;
+}
+function matchReasons(tokens, fields) {
+    const reasons = new Set();
+    for (const token of tokens.map((item) => item.toLowerCase())) {
+        if (fields.title.toLowerCase().includes(token))
+            reasons.add("title");
+        if (fields.rel.toLowerCase().includes(token))
+            reasons.add("path");
+        if (fields.sourceUrl.toLowerCase().includes(token))
+            reasons.add("source_url");
+        if (fields.topics.join(" ").toLowerCase().includes(token))
+            reasons.add("topics");
+        if (fields.tags.join(" ").toLowerCase().includes(token))
+            reasons.add("tags");
+        if (fields.relatedRefs.join(" ").toLowerCase().includes(token))
+            reasons.add("relationships");
+        if (fields.body.toLowerCase().includes(token))
+            reasons.add("body");
+    }
+    return Array.from(reasons);
+}
+function qualitySignals(item) {
+    const signals = [];
+    if (item.quality)
+        signals.push(`quality:${item.quality}`);
+    if (item.status)
+        signals.push(`status:${item.status}`);
+    if (item.generationMode)
+        signals.push(`generation_mode:${item.generationMode}`);
+    if (item.groundingEvidenceAvailable === true)
+        signals.push("grounding:evidence_available");
+    if (item.groundingEvidenceAvailable === false)
+        signals.push("grounding:no_evidence_flag");
+    if (item.groundingNeedsReview)
+        signals.push("grounding:needs_review");
+    if (item.relatedRefs.length)
+        signals.push("relationships:present");
+    return signals;
+}
+function finalizeQuality(result) {
+    const all = Object.values(result.matches).flat();
+    result.result_quality = {
+        total_matches: all.length,
+        best_score: all.reduce((best, item) => Math.max(best, item.score), 0),
+        has_wiki_entry: result.matches.wiki_entries.length > 0,
+        warnings: result.warnings
+    };
+    if (!all.length) {
+        result.recommended_next_action = "broaden_query_or_ingest_source";
+    }
+    else if (!result.matches.wiki_entries.length) {
+        result.recommended_next_action = "review_source_cards_then_create_wiki_entry";
+    }
+    else if (all.some((item) => item.grounding_needs_review || item.quality === "scaffold")) {
+        result.recommended_next_action = "review_grounding_or_enrich_entry";
+    }
+    else {
+        result.recommended_next_action = "use_matches_for_answer";
+    }
+}