@itradingai/aiwiki 0.2.16 → 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

@@ -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") {
@@ -247,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");
@@ -262,6 +288,41 @@ 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;
@@ -362,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);
@@ -400,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) {
@@ -415,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。`);
@@ -423,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, "");
@@ -508,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");
@@ -535,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);
@@ -561,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";
+    }
+}

package/docs/AGENT_HANDOFF.md

@@ -247,3 +247,57 @@ Lint 输出会包含摘要、最高优先级问题、分级报告，以及建议
 Before ingesting, querying, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace. Treat it as the local contract for what belongs in this knowledge base, what should stay out, and how future multi-knowledge-base routing should be handled.
 
 If the material does not fit the purpose file, do not force it into the knowledge base as confirmed knowledge. Record the mismatch, ask for review when needed, or keep it as a traceable source rather than a claim.
+
+## Context JSON for Retrieval
+
+When answering from AIWiki, prefer:
+
+```bash
+aiwiki context "<topic>" --limit 10
+```
+
+Use filters when the user intent is narrow:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --source-role input --wiki-type source_knowledge --status active
+aiwiki context "<topic>" --type source_cards --status to-review
+```
+
+`context` is local Markdown/frontmatter retrieval only. Do not describe it as vector search, RAG, a database query, or external web search.
+
+Read these fields before responding:
+
+- `query_scope`: what was searched and which filters were applied.
+- `result_quality.total_matches` and `result_quality.has_wiki_entry`: whether the answer is grounded in a Wiki Entry or only in supporting artifacts.
+- `recommended_next_action`: whether to answer, enrich, review grounding, or broaden the query.
+- `match_reasons`: why each result matched, such as title, body, tags, topics, relationships, or source URL.
+- `quality_signals`: scaffold, enriched, status, grounding, and relationship hints.
+- `related_refs`: local wikilinks and frontmatter relationships such as `source_card`, `raw_file`, and run artifacts.
+
+If `quality_signals` contains `quality:scaffold` or `grounding:needs_review`, tell the user the result is a traceable lead that needs enrichment or review. Do not present it as confirmed final knowledge.
+
+## Agent Skill Upgrade Flow
+
+When the user asks you to install, update, upgrade, or repair AIWiki integration, run:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+Use JSON when you need exact state:
+
+```bash
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+```
+
+Interpret sync results:
+
+- `installed`: target did not exist and now has the packaged skill.
+- `current`: installed skill already matches the packaged skill.
+- `updated`: installed skill differed; the old file was backed up and replaced.
+- `would_install` / `would_update`: dry-run preview only.
+- `unsupported`: no safe automatic target is known; use `aiwiki prompt agent`.
+
+After sync, report the target path, backup path when present, and that the user may need to restart or reload the Agent. Do not claim the new skill is active until the Agent has reloaded it.

package/docs/POSITIONING_CONTEXT_COMPILER_PLAN.md

@@ -0,0 +1,347 @@
+# AIWiki 定位调整与产品方案
+
+本文基于 `20260607-aiwiki定位.md` 的判断，并结合当前 AIWiki 仓库现状整理。结论是：文档大方向可取，但不能把 AIWiki 改成重学习、重记忆、重人工复习的 Knowledge MEMO。AIWiki 更适合继续做 Agent-first 本地上下文编译器。
+
+## 一句话定位
+
+AIWiki 不是替代搜索，也不是替你读书，而是把你真正需要反复调用的资料、判断和输出，编译成 AI 能查询、能引用、能检查、能继续使用的本地知识资产。
+
+更锋利的对外表达：
+
+> 公开知识交给搜索。
+> 私有判断、项目经验、输出风格、证据链，交给 AIWiki。
+
+## 建议取舍判断
+
+| 文档建议 | 判断 | 原因 | 落地优先级 |
+| --- | --- | --- | --- |
+| 不把 AIWiki 宣传成普通个人知识库或资料索引 | 可取 | 当前 README 已强调 Agent-first 和本地 LLM-wiki 后端，但还可以更明确地区分搜索、收藏夹和上下文编译器 | P0 |
+| 保留 Markdown Wiki 形态 | 可取 | AIWiki 面向人和 Agent 协作，Markdown 的可读、可 diff、可回滚、可被 Agent 编辑是核心优势 | P0 |
+| 强化个人判断层 | 强烈可取 | 当前 payload 已有 `source_role=processing`，但产品心智和目录/命令输出还没有把 personal insight 变成一等资产 | P0 |
+| 强化输出资产层 | 强烈可取 | 当前已有 `source_role=output` 和 `represents_user_view=true` 边界，这是 AIWiki 最有差异化的一层 | P0 |
+| `context` 从资料检索升级为任务上下文包 | 强烈可取 | 当前 `context` 已是 JSON 结构，适合加 `mode` 和按任务分组的结果，不需要推倒重做 | P0 |
+| `query` 输出按资料类型分组 | 可取 | 这是低成本心智升级：从“搜索结果”变成“知识资产调度” | P1 |
+| `lint` 从结构检查升级为知识质量检查 | 可取 | 当前 lint 已有元数据边界、fallback、grounding 检查，可继续加入 insight/output/evidence 使用关系检查 | P1 |
+| `next` 从命令导航升级为加工建议 | 可取 | 适合帮助用户把资料推进到 insight、output、topic 或 review，而不是只提示下一条 CLI 命令 | P1 |
+| 新增 Retain / Review | 部分可取 | 可以做轻量回看，但不应成为主流程，也不要第一阶段引入 FSRS 或 Anki 式学习系统 | P2 |
+| 把 AIWiki 改成纯人脑内化工具 | 不建议 | 会偏离当前 Agent-first CLI 边界，也会让产品过重 | 不做 |
+| 引入多知识库、自动采集、内置网页抓取 | 不建议 | 与当前仓库 AGENTS.md 和 README 边界冲突；这些属于 AIWiki Pro 或宿主 Agent/服务层，不属于基础 CLI | 不做 |
+
+## 产品原则
+
+1. AIWiki 只沉淀值得复用的上下文，不收藏所有公开知识。
+2. 外部资料默认不代表用户观点。
+3. 用户自己的输出和判断比外部输入更值钱。
+4. AIWiki CLI 不调用 LLM；高质量分析由宿主 Agent 提供，AIWiki 负责规范、落盘、追踪、检查。
+5. 保持单知识库、单命令 `aiwiki`、本地 Markdown 的基本边界。
+6. Review / Retain 是增强闭环，不是默认主流程。
+
+## 三类知识资产模型
+
+### 1. Source Knowledge：来源证据
+
+用于保存外部文章、网页、报告、视频转写、书籍摘录等。
+
+建议字段：
+
+```yaml
+source_role: input
+wiki_type: source_knowledge
+represents_user_view: false
+```
+
+价值标准：
+
+- 是否能作为证据引用。
+- 是否能支撑观点或反驳观点。
+- 是否能生成选题、方案、脚本或研究方向。
+- 是否能和已有资料、判断、输出建立连接。
+
+### 2. Personal Insight：个人判断
+
+用于保存用户或宿主 Agent 帮用户整理出的判断、取舍、冲突、决策理由。
+
+建议先复用现有 `source_role=processing`，并把 `wiki_type` 从宽泛的 `thought_note` 收窄为更明确的 `personal_insight` 或 `decision_note`。第一阶段可以兼容旧值。
+
+建议字段：
+
+```yaml
+type: insight_note
+source_role: processing
+wiki_type: personal_insight
+represents_user_view: true
+confidence: low | medium | high
+based_on:
+  - 03-sources/article-cards/example.md
+  - 05-wiki/source-knowledge/example.md
+used_for:
+  - article
+  - product_decision
+  - client_solution
+  - research
+```
+
+条目应回答：
+
+- 我认同什么，为什么。
+- 我反对什么，为什么。
+- 对项目、文章、产品或客户方案有什么启发。
+- 能否转成文章观点、产品决策或执行动作。
+- 和我已有判断是否冲突。
+
+### 3. Output Knowledge：可复用输出
+
+用于保存用户已经发布或交付过的文章、方案、PRD、README、报价、视频脚本、群内回答等。
+
+建议字段：
+
+```yaml
+source_role: output
+wiki_type: personal_knowledge
+represents_user_view: true
+```
+
+价值标准：
+
+- 能反映用户真实观点。
+- 能反映用户表达风格。
+- 能被新文章、新方案、新脚本复用。
+- 能回溯到支撑它的 source 和 insight。
+
+## 命令方案
+
+### `aiwiki context`
+
+定位：从“相关资料包”升级为“任务上下文包”。
+
+新增 `--mode`：
+
+```bash
+aiwiki context "AI知识库是否还有必要" --mode write
+aiwiki context "AIWiki产品定位" --mode decide
+aiwiki context "Karpathy LLM Wiki" --mode research
+aiwiki context "我的公众号文章风格" --mode style
+aiwiki context "某个知识点" --mode learn
+```
+
+建议返回结构：
+
+```json
+{
+  "schema_version": "aiwiki.context.v2",
+  "query": "AIWiki产品定位",
+  "mode": "decide",
+  "external_sources": [],
+  "personal_insights": [],
+  "past_outputs": [],
+  "conflicts": [],
+  "usable_arguments": [],
+  "missing_context": [],
+  "recommended_next_action": ""
+}
+```
+
+兼容策略：
+
+- 保留 v1 `matches` 结构一段时间。
+- v2 可以先在结果中新增字段，不立刻移除旧字段。
+- `--mode` 缺省为 `general`。
+
+### `aiwiki query`
+
+定位：给人看的知识资产摘要，不是普通搜索结果。
+
+建议输出分组：
+
+```text
+外部资料
+- ...
+
+个人判断
+- ...
+
+已发布输出
+- ...
+
+证据与冲突
+- ...
+
+建议下一步
+- ...
+```
+
+优先级：
+
+- 命中 output 和 insight 时，展示在 source 前面。
+- source 只作为证据，不默认当成结论。
+
+### `aiwiki lint`
+
+定位：从文件结构健康检查升级为知识资产健康检查。
+
+保留现有检查：
+
+- 缺少系统文件。
+- Source Card 没有 Wiki Entry。
+- Wiki Entry 缺少 source_card / raw_file。
+- fallback scaffold 过期。
+- grounding needs review。
+- `represents_user_view=true` 但不是 output。
+- 重复 URL、重复标题、断链。
+
+新增质量检查：
+
+- 某主题只有 source，没有 insight。
+- 某 insight 没有 `based_on`。
+- 某 output 没有关联 source 或 insight。
+- source 被错误标记为代表用户观点。
+- claim 没有 source quote 或证据边界。
+- 某主题存在冲突观点但没有决策结论。
+- enriched entry 只有摘要，没有 reusable judgment / reusable knowledge。
+
+### `aiwiki next`
+
+定位：从命令导航升级为加工建议。
+
+建议输出：
+
+```text
+当前最值得做：
+- 这 3 篇 source 只有摘要，没有个人判断。
+- 这个主题已有 5 条 source，可以生成主题页。
+- 这条 output 没有证据链，建议补 linked sources。
+- 这个观点和历史输出存在冲突，建议进入 review。
+```
+
+### `aiwiki review` 或 `aiwiki retain`
+
+定位：轻量回看，不做重学习系统。
+
+第一版只做候选生成：
+
+```text
+今日建议回看：
+- 3 条个人 insight
+- 2 条高价值 source knowledge
+- 1 条已输出文章中的核心观点
+
+可生成卡片：
+- 观点卡
+- 证据卡
+- 反驳卡
+- 案例卡
+- 输出卡
+```
+
+暂不做：
+
+- FSRS。
+- 每日强制复习。
+- Anki 兼容。
+- 学习进度系统。
+
+## README 与对外话术
+
+建议把开头改得更锋利：
+
+```text
+AIWiki 是一个 Agent-first 本地上下文编译器。
+
+它不替代搜索，也不替你读书，而是把你真正需要反复调用的资料、判断和输出，编译成 AI 能查询、能引用、能检查、能继续使用的本地知识资产。
+```
+
+“它解决什么”建议改成：
+
+- 公开资料搜索得到，但你的使用场景、判断和输出痕迹搜不到。
+- 链接和资料散在聊天记录里，后续很难被 Agent 复用。
+- AI 总结过一次内容，但没有沉淀成可追踪、可查询、可检查的上下文资产。
+- 想把来源证据、个人判断、选题、大纲和已输出内容放进同一个本地知识系统。
+- 想让宿主 Agent 负责理解内容，让 AIWiki 负责稳定落盘、连接和检查。
+
+不建议继续主打：
+
+```text
+打造你的 AI 个人知识库
+```
+
+这个说法太泛，容易被理解成“AI 时代还要不要收藏夹”。
+
+## 分阶段落地
+
+### P0：定位与 schema 心智对齐
+
+目标：不大改代码，先把产品定位和现有字段解释清楚。
+
+任务：
+
+1. 更新 README、FAQ、USAGE 的定位话术。
+2. 在 docs 中新增“三类资产模型”说明。
+3. 在 Agent handoff / skill 中要求宿主 Agent 区分 source、insight、output。
+4. 明确 `source_role=input` 永远不默认代表用户观点。
+5. 为 `processing` 角色补充 personal insight 示例 payload。
+
+验收：
+
+- 新用户能在 README 前 30 秒理解 AIWiki 不是搜索替代品。
+- 文档能解释 source、insight、output 三层差异。
+- 不引入新命令、不破坏旧 payload。
+
+### P1：任务上下文与质量检查
+
+目标：让 AIWiki 从“能查到资料”升级为“能为任务组织上下文”。
+
+任务：
+
+1. `context` 增加 `--mode`。
+2. `context` 输出新增 `external_sources`、`personal_insights`、`past_outputs`、`conflicts`、`usable_arguments`、`missing_context`。
+3. `query` 输出按资产类型分组。
+4. `lint` 增加 insight/output/evidence 质量检查。
+5. `next` 增加加工建议。
+
+验收：
+
+- 同一个 query 在 `write`、`decide`、`research`、`style` 下返回不同的建议结构。
+- 有 insight/output 时优先暴露，不被 source 淹没。
+- `lint` 能指出“只有资料、没有个人判断”和“输出没有证据链”。
+
+### P2：轻量回看闭环
+
+目标：吸收 Retain 思想，但不把 AIWiki 变成学习软件。
+
+任务：
+
+1. 新增 `review` 或 `retain` 的候选生成命令。
+2. 支持观点卡、证据卡、反驳卡、案例卡、输出卡。
+3. Review Queue 只作为入口，不成为默认强制流程。
+
+验收：
+
+- 命令能生成今日回看候选。
+- 不需要用户维护复杂学习计划。
+- 不引入 FSRS 或重型记忆系统。
+
+## 不做清单
+
+- 不做通用网页抓取。
+- 不做多知识库。
+- 不做 CLI 内置 LLM。
+- 不做默认人工审核流程。
+- 不把 Review Queue 变成强制主流程。
+- 不把 AIWiki 改成 Anki 或 Knowledge MEMO。
+- 不用 `aiwiki-pro` 作为用户命令。
+
+## 推荐任务拆分
+
+1. `AIWIKI-POS-001`：更新 README / FAQ / USAGE 定位话术。
+2. `AIWIKI-POS-002`：补充三类资产模型文档和示例 payload。
+3. `AIWIKI-CTX-001`：为 `context` 增加 `--mode` 和 v2 结果字段。
+4. `AIWIKI-QRY-001`：让 `query` 按 source / insight / output 分组展示。
+5. `AIWIKI-LINT-001`：增加知识质量 lint。
+6. `AIWIKI-NEXT-001`：让 `next` 输出加工建议。
+7. `AIWIKI-REV-001`：设计轻量 review / retain 候选生成。
+
+## 最终判断
+
+这份定位文档对 AIWiki 是利好。它指出了“普通个人知识库/资料索引”在 AI 时代价值下降，这个判断应该接受；但它没有否定 AIWiki 的 Agent-first 本地上下文后端方向。真正可取的调整，是把 AIWiki 从“存知识”进一步收窄成“存上下文、判断和使用痕迹”。
+
+AIWiki 下一步最该做的不是扩功能，而是把已有地基讲清楚、排出优先级，然后补齐 personal insight、output knowledge、task context 和 quality lint 这四块。

package/docs/USAGE.md

@@ -434,3 +434,59 @@ aiwiki status
 - `next_action`: the recommended next command.
 
 `aiwiki next` uses the same repair order: fix workspace structure first, then lint errors, lint warnings, empty-workspace onboarding, and finally healthy-state query guidance.
+
+## Query and Context Filters
+
+`aiwiki context` and `aiwiki query` use local Markdown/frontmatter search. They do not use vector search, a database, external search, or RAG-over-wiki.
+
+Useful filters:
+
+```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
+```
+
+Supported filters:
+
+- `--type`: one result group, such as `wiki_entries`, `source_cards`, `claims`, `topics`, `outlines`, or `raw_refs`.
+- `--source-role`: frontmatter `source_role`, usually `input`, `processing`, or `output`.
+- `--wiki-type`: frontmatter `wiki_type`, such as `source_knowledge` or `personal_knowledge`.
+- `--status`: frontmatter status, such as `active`, `to-review`, `ready`, or `draft`.
+- `--limit`: per-group result limit, clamped from 1 to 50.
+
+The JSON result keeps the stable `schema_version: "aiwiki.context.v1"` and now also includes:
+
+- `query_scope`: filters, limit, and searched groups.
+- `result_quality`: total matches, best score, whether a Wiki Entry was found, and warnings.
+- `recommended_next_action`: for example `use_matches_for_answer`, `review_grounding_or_enrich_entry`, or `broaden_query_or_ingest_source`.
+- Per match: `match_reasons`, `quality_signals`, and `related_refs`.
+
+Use `match_reasons` to explain why a result matched. Use `quality_signals` before answering confidently: scaffold or grounding-review entries should be treated as traceable leads, not final knowledge.
+
+## Agent Skill Sync
+
+AIWiki does not modify Agent configuration during `npm install`. After first install or upgrade, sync the packaged skill explicitly:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+For one host Agent:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+Useful Agent-facing options:
+
+```bash
+aiwiki agent sync --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+aiwiki agent help
+aiwiki context --help
+```
+
+`agent sync` is safe for first install and cross-version upgrades. It installs missing targets, leaves current targets unchanged, and backs up changed installed skill files before overwrite. If a backup is created, tell the user the backup path and that rollback means copying the backup file back to the target path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "type": "module",
   "description": "Agent-first AI knowledge base CLI for turning articles, links and notes into Obsidian-ready source cards, topics, outlines and reusable knowledge assets.",
   "license": "MIT",

package/skill/LINT_PROTOCOL.md

@@ -15,15 +15,23 @@ Use this protocol when the user asks:
 aiwiki lint
 ```
 
-2. Read the terminal report.
-3. Mention the report path, usually:
+2. When you need machine-readable triage, call:
+
+```bash
+aiwiki lint --json
+aiwiki next
+```
+
+3. Read the terminal report.
+4. Mention the report path, usually:
 
 ```text
 dashboards/Lint Report.md
 ```
 
-4. Explain warnings and errors as structure-health feedback.
-5. Do not frame lint as "the user must manually audit every note".
+5. Explain warnings and errors as structure-health feedback.
+6. Do not frame lint as "the user must manually audit every note".
+7. If `aiwiki next` recommends `aiwiki agent sync --yes`, treat Agent skill setup as the next operational step before asking the user to ingest or query more material.
 
 ## Issue Meaning
 
@@ -39,4 +47,3 @@ Prefer small, traceable fixes:
 - Fix broken wikilinks.
 - Add missing `source_card` or `raw_file` paths.
 - Ask the host Agent to provide `analysis` for scaffold entries.
-

package/skill/QUERY_PROTOCOL.md

@@ -16,11 +16,29 @@ Use this protocol when the user asks:
 aiwiki context "<topic>"
 ```
 
+Add filters when the user intent is specific:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --status active --limit 5
+aiwiki context "<topic>" --source-role input --wiki-type source_knowledge --limit 5
+aiwiki context "<topic>" --source-role output --limit 5
+aiwiki context "<topic>" --type source_cards --status to-review --limit 5
+```
+
 3. Read the JSON result.
 4. Prefer `matches.wiki_entries` before source cards, claims, topics, outlines, or raw refs.
-5. Pay attention to `generation_mode`, `quality`, and `warnings`.
-6. If the best Wiki Entry has `quality: "scaffold"`, tell the user that the entry is a traceable fallback and may need Agent enrichment.
-7. Do not scan `02-raw` by default unless:
+5. Read `query_scope` to understand what was searched.
+6. Read `result_quality` before deciding how confident the answer can be.
+7. Follow `recommended_next_action`:
+   - `use_matches_for_answer`: answer from the matches.
+   - `review_grounding_or_enrich_entry`: answer cautiously and suggest enrichment/review.
+   - `review_source_cards_then_create_wiki_entry`: explain that only source-level material exists.
+   - `broaden_query_or_ingest_source`: ask for a broader query or ingest more material.
+8. Use `match_reasons` to explain why an item was selected.
+9. Use `quality_signals` to decide whether the result is enriched, scaffold, needs grounding review, or only has weak source support.
+10. Use `related_refs` to mention useful local follow-up files.
+11. If the best Wiki Entry has `quality: "scaffold"` or `quality_signals` includes `grounding:needs_review`, tell the user that the entry is a traceable lead and may need Agent enrichment or evidence review.
+12. Do not scan `02-raw` by default unless:
    - Wiki Entries are insufficient.
    - The user asks to verify the original source.
    - There is a source conflict.
@@ -35,4 +53,3 @@ Include:
 - Source basis.
 - Known gaps or scaffold warnings.
 - Suggested next step.
-

package/skill/SKILL.md

@@ -3,12 +3,46 @@ name: aiwiki
 description: Agent-first AIWiki workflow for turning one URL/body into local Wiki knowledge files.
 ---
 
+<!-- aiwiki-skill-version: 0.2.18 -->
+
 # AIWiki Skill
 
 Use this skill when the user asks an Agent to process one URL, article body, or local text file with the `aiwiki` keyword, or says phrases like `入库 <url>` / `收录 <url>` / `从 AIWiki 里了解 <topic>`.
 
 AIWiki CLI does not fetch webpages and does not call an LLM. The host Agent reads and understands the source; AIWiki validates, writes, links, tracks, queries, and lints local Markdown knowledge files.
 
+## Agent-First Setup and Upgrade
+
+When the user asks you to install, update, or repair AIWiki Agent integration, prefer the idempotent sync command:
+
+```bash
+aiwiki agent sync --yes
+```
+
+For a specific host:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+Use `--dry-run` to preview without writing, and `--json` when you need machine-readable status:
+
+```bash
+aiwiki agent sync --agent codex --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+```
+
+Sync behavior:
+
+- missing installed skill: install the packaged AIWiki skill
+- current installed skill: leave unchanged
+- different installed skill: backup the old file, then overwrite with the packaged skill
+- unsupported host: do not write; use `aiwiki prompt agent` as a manual fallback
+
+After sync, tell the user the target path, any backup path, and that the target Agent may need to restart or reload before the new skill is active. Never edit Agent config during `npm install`; sync is the explicit safe step.
+
 ## Knowledge Base Purpose
 
 Before ingesting, querying, linting, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace when it exists. Treat it as the local contract for:
@@ -143,7 +177,26 @@ When the user asks to understand a topic from AIWiki, call:
 aiwiki context "<topic>"
 ```
 
-Use the returned JSON to answer. Prefer Wiki Entries first. Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.
+Use filters when the user's intent is clear:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --status active --limit 5
+aiwiki context "<topic>" --source-role output --limit 5
+aiwiki context "<topic>" --type source_cards --status to-review --limit 5
+```
+
+Use the returned JSON to answer. Prefer Wiki Entries first, but read these fields before responding:
+
+- `query_scope`: filters, limit, and searched groups
+- `result_quality`: total matches, best score, and whether a Wiki Entry was found
+- `recommended_next_action`: whether to answer, broaden the query, enrich, or review grounding
+- `match_reasons`: why each result matched
+- `quality_signals`: scaffold, enriched, grounding, status, and relationship hints
+- `related_refs`: local wikilinks and frontmatter relationships
+
+Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.
+
+If `quality_signals` contains `quality:scaffold` or `grounding:needs_review`, tell the user the result is a traceable lead that needs enrichment or review. Do not present it as final confirmed knowledge.
 
 For direct human terminal output, use:
 

package/skill/UPGRADE_NOTES.md

@@ -0,0 +1,22 @@
+# AIWiki Skill Upgrade Notes
+
+Use this note when an Agent finishes `aiwiki agent sync`.
+
+## Current Major Changes
+
+- Agent integration should use `aiwiki agent sync --yes` for both first install and upgrades.
+- Sync backs up changed installed skill files before overwriting them.
+- `aiwiki agent check --json` and `aiwiki agent sync --json --yes` provide machine-readable status for Agents.
+- `aiwiki context` supports `--type`, `--source-role`, `--wiki-type`, `--status`, and `--limit`.
+- Context JSON includes `query_scope`, `result_quality`, `recommended_next_action`, `match_reasons`, `quality_signals`, and `related_refs`.
+- Scaffold or grounding-review matches are traceable leads, not final confirmed knowledge.
+
+## Agent Reply After Sync
+
+Tell the user:
+
+- which Agent targets were installed, current, updated, or unsupported
+- where the new skill was written
+- where the old skill was backed up, if any
+- that the Agent may need a restart or reload
+- that rollback is possible by copying the backup file back to the target path