@itradingai/aiwiki 0.2.11 → 0.2.12

package/README.md

@@ -30,9 +30,10 @@ AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。
 
 ```bash
 aiwiki context "AI Agent 出海机会"
+aiwiki query "AI Agent 出海机会"
 ```
 
-`context` 返回 JSON，主要给宿主 Agent 用。第一版是本地关键词检索，不是向量检索。
+`context` 返回 JSON，主要给宿主 Agent 用；`query` 使用同一套检索结果，输出给人看的摘要。第一版是本地关键词检索，不是向量检索。
 
 ### Lint：检查知识库结构
 
@@ -71,6 +72,7 @@ aiwiki agent install
 ```bash
 aiwiki agent list
 aiwiki agent install
+aiwiki agent check
 ```
 
 也可以直接输出通用协议：
@@ -103,6 +105,12 @@ aiwiki prompt agent
 aiwiki context "xxx"
 ```
 
+人直接查询时可以运行：
+
+```bash
+aiwiki query "xxx"
+```
+
 ## AIWiki 会生成什么
 
 成功入库会生成：
@@ -131,6 +139,8 @@ generation_mode: "agent_enriched"
 quality: "enriched"
 generated_by: "host_agent"
 llm_enriched: true
+source_role: "input"
+represents_user_view: false
 ```
 
 ### Deterministic Fallback Wiki Entry
@@ -144,6 +154,8 @@ generation_mode: "deterministic_fallback"
 quality: "scaffold"
 generated_by: "aiwiki_cli"
 llm_enriched: false
+source_role: "input"
+represents_user_view: false
 ```
 
 AIWiki CLI 本身不调用 LLM，所以不会在没有 Agent 分析字段时承诺高质量提炼。
@@ -156,7 +168,7 @@ AIWiki 做：
 - 写入本地 Markdown。
 - 生成 frontmatter、wikilink、处理记录。
 - 生成 Wiki Entry 容器。
-- 支持 `context` 和 `lint`。
+- 支持 `context`、`query`、`next` 和 `lint`。
 
 AIWiki 不做：
 
@@ -195,7 +207,7 @@ Review Queue 可以保留为回看入口，但不是 AIWiki 的主流程。
 
 ### 什么内容才代表我的观点？
 
-后续 `source_role=output` 会用于标记用户已发布文章、演讲稿、公众号文章等个人输出。本阶段外部资料默认是 `source_role: input`、`represents_user_view: false`。
+`source_role=output` 用于标记用户已发布文章、演讲稿、公众号文章等个人输出，并可配合 `represents_user_view: true`。外部资料默认是 `source_role: input`、`represents_user_view: false`。
 
 ### Dataview 必须安装吗？
 
@@ -227,6 +239,8 @@ aiwiki setup --path "F:\knowledge_data\aiwiki-test" --yes
 aiwiki doctor
 aiwiki ingest-agent --payload tests/fixtures/agent_payload.url.valid.json --path "F:\knowledge_data\aiwiki-test"
 aiwiki context "AI Agent" --path "F:\knowledge_data\aiwiki-test"
+aiwiki query "AI Agent" --path "F:\knowledge_data\aiwiki-test"
+aiwiki next --path "F:\knowledge_data\aiwiki-test"
 aiwiki lint --path "F:\knowledge_data\aiwiki-test"
 ```
 

package/dist/src/app.js

@@ -54,6 +54,10 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             }
             return 0;
         }
+        if (command === "agent" && subcommand === "check") {
+            await printAgentCheck(streams.stdout, await discoverAgentTargets());
+            return 0;
+        }
         if (command === "agent" && (subcommand === "list" || !subcommand)) {
             printAgentList(streams.stdout, await discoverAgentTargets());
             return 0;
@@ -124,6 +128,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             writeLine(streams.stdout, `处理次数: ${summary.runCount}`);
             writeLine(streams.stdout, `失败次数: ${summary.failedCount}`);
             writeLine(streams.stdout, `最近处理: ${summary.lastRunId ?? "无"}`);
+            await printStatusDetails(streams.stdout, root, summary.runCount);
             return 0;
         }
         if (command === "context") {
@@ -135,6 +140,23 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             writeLine(streams.stdout, JSON.stringify(await buildContext(root, query), null, 2));
             return 0;
         }
+        if (command === "query") {
+            const root = await resolveWorkspace(flagString(args, "path"));
+            const query = args.positional.slice(1).join(" ").trim();
+            if (!query) {
+                throw new CliError("请提供查询主题。");
+            }
+            writeLine(streams.stdout, renderQuery(await buildContext(root, query)));
+            return 0;
+        }
+        if (command === "next") {
+            const root = await resolveWorkspace(flagString(args, "path"));
+            const summary = await statusSummary(root);
+            const checks = await doctor(root);
+            const report = summary.runCount > 0 ? await lintWorkspace(root) : undefined;
+            await printNext(streams.stdout, root, summary.runCount, checks, await discoverAgentTargets(), report);
+            return 0;
+        }
         if (command === "lint") {
             const root = await resolveWorkspace(flagString(args, "path"));
             const report = await lintWorkspace(root);
@@ -223,6 +245,8 @@ function printHelp(stream) {
     writeLine(stream, "  aiwiki doctor");
     writeLine(stream, "  aiwiki status");
     writeLine(stream, "  aiwiki context <query>");
+    writeLine(stream, "  aiwiki query <query>");
+    writeLine(stream, "  aiwiki next");
     writeLine(stream, "  aiwiki lint");
     writeLine(stream, "  aiwiki ingest-agent --stdin");
     writeLine(stream, "  aiwiki ingest-file --file <file>");
@@ -230,6 +254,7 @@ function printHelp(stream) {
     writeLine(stream, "  aiwiki config show");
     writeLine(stream, "  aiwiki ingest-agent --payload <file>");
     writeLine(stream, "  aiwiki ingest-url <url> --content-file <file>");
+    writeLine(stream, "  aiwiki agent check");
 }
 async function discoverAgentTargets() {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -309,6 +334,19 @@ function printAgentList(stream, targets) {
         }
     }
 }
+async function printAgentCheck(stream, targets) {
+    writeLine(stream, "AIWiki Agent 接入检查");
+    for (const target of targets) {
+        const installed = target.target ? await exists(target.target) : false;
+        writeLine(stream, `${target.id}: ${target.name} | detected=${target.detected ? "yes" : "no"} | installed=${installed ? "yes" : "no"} | installable=${target.installable ? "yes" : "no"}`);
+        if (target.detected && target.installable && !installed) {
+            writeLine(stream, `  建议: aiwiki agent install --agent ${target.id} --yes`);
+        }
+        else if (target.detected && !target.installable) {
+            writeLine(stream, "  建议: aiwiki prompt agent");
+        }
+    }
+}
 async function installAgentSkill(options) {
     const targets = await discoverAgentTargets();
     const installable = targets.filter((target) => target.detected && target.installable);
@@ -389,6 +427,127 @@ function printAgentPrompt(stream) {
     writeLine(stream, "");
     writeLine(stream, "禁止：让用户保存 payload；让用户每次输入 --path；声称 AIWiki CLI 负责网页抓取；声称 AIWiki CLI 会在没有 Agent 分析字段时自动高质量总结。");
 }
+async function printStatusDetails(stream, root, runCount) {
+    const counts = await contentCounts(root);
+    const lintPath = path.join(root, "dashboards", "Lint Report.md");
+    writeLine(stream, "");
+    writeLine(stream, "内容统计:");
+    writeLine(stream, `Wiki 条目: ${counts.wikiEntries}`);
+    writeLine(stream, `资料卡: ${counts.sourceCards}`);
+    writeLine(stream, `原文: ${counts.rawFiles}`);
+    writeLine(stream, `选题: ${counts.topics}`);
+    writeLine(stream, `大纲: ${counts.outlines}`);
+    writeLine(stream, `最近 lint: ${await exists(lintPath) ? await relativeMtime(root, lintPath) : "无"}`);
+    writeLine(stream, "");
+    writeLine(stream, "下一步建议:");
+    writeLine(stream, runCount === 0 ? "运行 `aiwiki agent install` 接入宿主 Agent，然后发送 `入库 <url>`。" : "运行 `aiwiki query <主题>` 查询知识，或运行 `aiwiki lint` 检查结构。");
+}
+async function printNext(stream, root, runCount, checks, targets, report) {
+    const missing = checks.filter((check) => check.status !== "ok");
+    const installableMissing = [];
+    for (const target of targets) {
+        if (target.detected && target.installable && target.target && !(await exists(target.target))) {
+            installableMissing.push(target);
+        }
+    }
+    writeLine(stream, "AIWiki 下一步建议");
+    writeLine(stream, `知识库路径: ${root}`);
+    if (missing.length) {
+        writeLine(stream, "");
+        writeLine(stream, "先修复知识库结构:");
+        writeLine(stream, `- aiwiki setup --path "${root}" --yes`);
+        return;
+    }
+    if (runCount === 0) {
+        writeLine(stream, "");
+        writeLine(stream, "还没有入库记录。");
+        writeLine(stream, "- aiwiki agent install");
+        writeLine(stream, "- 然后向宿主 Agent 发送 `入库 <url>`");
+        writeLine(stream, "- CLI 不抓网页；网页正文由宿主 Agent 提供。");
+        return;
+    }
+    const actionableIssues = report?.issues.filter((issue) => issue.severity !== "info") ?? [];
+    if (actionableIssues.length) {
+        writeLine(stream, "");
+        writeLine(stream, `结构检查发现 ${actionableIssues.length} 个需要处理的问题。`);
+        writeLine(stream, "- aiwiki lint");
+        writeLine(stream, `- 查看报告: dashboards/Lint Report.md`);
+        writeLine(stream, "- 先处理 error / warning，再继续扩展查询或入库。");
+        return;
+    }
+    writeLine(stream, "");
+    writeLine(stream, "已有入库记录，可以继续：");
+    writeLine(stream, "- aiwiki query <主题>");
+    writeLine(stream, "- aiwiki lint");
+    if (installableMissing.length) {
+        writeLine(stream, "");
+        writeLine(stream, "可补充宿主 Agent 接入:");
+        for (const target of installableMissing) {
+            writeLine(stream, `- aiwiki agent install --agent ${target.id} --yes`);
+        }
+    }
+}
+function renderQuery(context) {
+    const lines = [`AIWiki 查询: ${context.query}`, ""];
+    appendQueryGroup(lines, "Wiki 条目", context.matches.wiki_entries);
+    appendQueryGroup(lines, "资料卡", context.matches.source_cards);
+    appendQueryGroup(lines, "选题", context.matches.topics);
+    appendQueryGroup(lines, "Claim 建议", context.matches.claims);
+    appendQueryGroup(lines, "大纲", context.matches.outlines);
+    appendQueryGroup(lines, "原文引用", context.matches.raw_refs);
+    if (context.warnings.length) {
+        lines.push("提示:", ...context.warnings.map((warning) => `- ${warning}`), "");
+    }
+    lines.push("Agent JSON:", `- aiwiki context "${context.query}"`);
+    return `${lines.join("\n")}\n`;
+}
+function appendQueryGroup(lines, label, items) {
+    lines.push(`${label}:`);
+    if (!items.length) {
+        lines.push("- 无", "");
+        return;
+    }
+    for (const item of items.slice(0, 5)) {
+        lines.push(`- ${item.title} (${item.path})`);
+        if (item.summary) {
+            lines.push(`  ${item.summary}`);
+        }
+        if (item.warnings.length) {
+            lines.push(`  提示: ${item.warnings.join("；")}`);
+        }
+    }
+    lines.push("");
+}
+async function contentCounts(root) {
+    return {
+        wikiEntries: await countMarkdownFiles(path.join(root, "05-wiki")),
+        sourceCards: await countMarkdownFiles(path.join(root, "03-sources", "article-cards")),
+        rawFiles: await countMarkdownFiles(path.join(root, "02-raw", "articles")),
+        topics: await countMarkdownFiles(path.join(root, "07-topics", "ready")),
+        outlines: await countMarkdownFiles(path.join(root, "08-outputs", "outlines"))
+    };
+}
+async function countMarkdownFiles(dir) {
+    if (!(await exists(dir))) {
+        return 0;
+    }
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        const target = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            count += await countMarkdownFiles(target);
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            count += 1;
+        }
+    }
+    return count;
+}
+async function relativeMtime(root, target) {
+    const stats = await fs.stat(target);
+    return `${path.relative(root, target).replace(/\\/g, "/")} (${stats.mtime.toISOString()})`;
+}
 function doctorStatusText(status) {
     if (status === "ok") {
         return "正常";
@@ -422,6 +581,11 @@ function printIngestResult(stream, result) {
     if (result.agentReport.wikiEntryQuality) {
         writeLine(stream, `wiki_entry_quality: ${result.agentReport.wikiEntryQuality}`);
     }
+    writeLine(stream, `grounding_evidence_available: ${result.agentReport.grounding.evidence_available ? "yes" : "no"}`);
+    writeLine(stream, `grounding_evidence_channel: ${result.agentReport.grounding.evidence_channel}`);
+    writeLine(stream, `grounding_needs_review: ${result.agentReport.grounding.needs_review ? "yes" : "no"}`);
+    writeLine(stream, `grounding_markers: ${result.agentReport.grounding.suspicion_markers.length ? result.agentReport.grounding.suspicion_markers.join(",") : "none"}`);
+    writeLine(stream, `grounding_claims_with_quotes: ${result.agentReport.grounding.claim_quote_count}/${result.agentReport.grounding.claim_count}`);
     if (result.agentReport.keyFiles.sourceCard) {
         writeLine(stream, `source_card: ${result.agentReport.keyFiles.sourceCard}`);
     }

package/dist/src/context.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { frontmatterArray, frontmatterString, parseMarkdown } from "./frontmatter.js";
+import { frontmatterArray, frontmatterBoolean, frontmatterString, parseMarkdown } from "./frontmatter.js";
 import { relativePath } from "./paths.js";
 import { exists } from "./workspace.js";
 const GROUPS = [
@@ -75,9 +75,14 @@ async function searchDir(root, dir, tokens, weight) {
         }
         const generationMode = frontmatterString(parsed.frontmatter, "generation_mode");
         const quality = frontmatterString(parsed.frontmatter, "quality");
+        const groundingMarkers = frontmatterArray(parsed.frontmatter, "grounding_markers");
+        const groundingNeedsReview = frontmatterBoolean(parsed.frontmatter, "grounding_needs_review");
         const warnings = generationMode === "deterministic_fallback"
             ? ["该 Wiki Entry 是 deterministic fallback，仅包含来源、正文预览和待补全区。"]
             : [];
+        if (groundingNeedsReview) {
+            warnings.push(`Grounding needs review${groundingMarkers.length ? `: ${groundingMarkers.join(", ")}` : ""}.`);
+        }
         matches.push({
             title,
             path: rel,
@@ -87,6 +92,9 @@ async function searchDir(root, dir, tokens, weight) {
             source_url: frontmatterString(parsed.frontmatter, "source_url") ?? "",
             generation_mode: generationMode,
             quality,
+            grounding_evidence_available: frontmatterBoolean(parsed.frontmatter, "grounding_evidence_available"),
+            grounding_needs_review: groundingNeedsReview,
+            grounding_markers: groundingMarkers,
             warnings
         });
     }

package/dist/src/grounding.js

@@ -0,0 +1,83 @@
+export function buildGroundingReport(payload) {
+    const claims = payload.analysis?.claims ?? [];
+    const reusableKnowledge = payload.analysis?.reusable_knowledge ?? [];
+    const content = payload.source.content ?? "";
+    let evidenceQuoteCount = 0;
+    let unsupportedClaimCount = 0;
+    const markers = new Set();
+    for (const claim of claims) {
+        const quote = claim.source_quote?.trim();
+        if (quote && content.includes(quote)) {
+            evidenceQuoteCount += 1;
+            continue;
+        }
+        unsupportedClaimCount += 1;
+        markers.add(quote ? "source_quote_not_found" : "unsupported_claims");
+    }
+    for (const item of reusableKnowledge) {
+        const quote = item.source_quote?.trim();
+        if (quote && content.includes(quote)) {
+            evidenceQuoteCount += 1;
+        }
+        else if (quote) {
+            markers.add("source_quote_not_found");
+        }
+    }
+    const coverageSuspectedIncomplete = hasSparseAnalysisForLongContent(payload);
+    if (coverageSuspectedIncomplete) {
+        markers.add("coverage_suspected_incomplete");
+    }
+    return {
+        evidence_available: evidenceQuoteCount > 0,
+        evidence_channel: evidenceQuoteCount > 0 ? "host_supplied" : "none",
+        claim_count: claims.length,
+        claim_quote_count: claims.filter((claim) => claim.source_quote?.trim() && content.includes(claim.source_quote.trim())).length,
+        unsupported_claim_count: unsupportedClaimCount,
+        coverage_suspected_incomplete: coverageSuspectedIncomplete,
+        needs_review: markers.size > 0,
+        suspicion_markers: [...markers]
+    };
+}
+export function groundingWarnings(report) {
+    const warnings = [];
+    if (report.unsupported_claim_count > 0) {
+        warnings.push(`grounding: ${report.unsupported_claim_count} claim(s) lack a source_quote found in raw content.`);
+    }
+    if (report.coverage_suspected_incomplete) {
+        warnings.push("grounding: coverage_suspected_incomplete is heuristic and needs review.");
+    }
+    return warnings;
+}
+export function groundingFrontmatterLines(grounding) {
+    return [
+        `grounding_evidence_available: ${grounding.evidence_available ? "true" : "false"}`,
+        `grounding_evidence_channel: "${grounding.evidence_channel}"`,
+        `grounding_needs_review: ${grounding.needs_review ? "true" : "false"}`,
+        `grounding_markers: ${yamlStringArray(grounding.suspicion_markers)}`,
+        `grounding_claim_count: "${grounding.claim_count}"`,
+        `grounding_claim_quote_count: "${grounding.claim_quote_count}"`,
+        `grounding_unsupported_claim_count: "${grounding.unsupported_claim_count}"`,
+        `coverage_suspected_incomplete: ${grounding.coverage_suspected_incomplete ? "true" : "false"}`
+    ];
+}
+function hasSparseAnalysisForLongContent(payload) {
+    if (!payload.analysis) {
+        return false;
+    }
+    const contentLength = (payload.source.content ?? "").replace(/\s+/g, "").length;
+    if (contentLength < 500) {
+        return false;
+    }
+    const extractedSignals = payload.analysis.key_points.length +
+        payload.analysis.reusable_knowledge.length +
+        payload.analysis.related_concepts.length +
+        payload.analysis.use_cases.length +
+        payload.analysis.topic_candidates.length;
+    return extractedSignals < 3;
+}
+function yamlStringArray(values) {
+    return `[${values.map((value) => `"${escapeYaml(value)}"`).join(", ")}]`;
+}
+function escapeYaml(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/src/ingest.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { normalizePayload } from "./payload.js";
+import { buildGroundingReport, groundingFrontmatterLines, groundingWarnings } from "./grounding.js";
 import { appendRunIdBeforeExt, relativePath, safeJoin, slugify } from "./paths.js";
 import { initWorkspace } from "./workspace.js";
 import { renderWikiEntry } from "./wiki-entry.js";
@@ -17,10 +18,11 @@ export async function ingestPayload(rootPath, rawPayload) {
     const generatedFiles = [];
     await writeFile(path.join(runDir, "payload.json"), `${JSON.stringify(payload, null, 2)}\n`, generatedFiles);
     if (payload.source.fetch_status === "failed") {
+        const grounding = buildGroundingReport(payload);
         await writeSummary(root, runDir, payload, generatedFiles, [
             ...payload.warnings,
             "宿主 Agent 未能提供正文，AIWiki CLI 没有自行抓取网页。"
-        ]);
+        ], undefined, grounding);
         return { runId: runDirName, runDir, generatedFiles, warnings: payload.warnings, agentReport: buildAgentReport(root, runDir, payload, generatedFiles) };
     }
     const slug = slugify(payload.source.title ?? payload.source.url);
@@ -28,22 +30,23 @@ export async function ingestPayload(rootPath, rawPayload) {
     const collisionWarnings = [];
     const longTermTargets = await chooseLongTermTargets(root, slug, runId, collisionWarnings);
     const links = buildArtifactLinks(root, slug, runDirName, runStartedAt, longTermTargets);
+    const grounding = buildGroundingReport(payload);
     await writeFile(path.join(runDir, "raw.md"), contentFile(payload, content, links), generatedFiles);
-    await writeFile(path.join(runDir, "source-card.md"), sourceCard(payload, runDirName, links), generatedFiles);
+    await writeFile(path.join(runDir, "source-card.md"), sourceCard(payload, runDirName, links, grounding), generatedFiles);
     const wikiEntryResult = renderWikiEntry(payload, links);
     await writeFile(path.join(runDir, "wiki-entry.md"), wikiEntryResult.markdown, generatedFiles);
     await writeFile(path.join(runDir, "creative-assets.md"), creativeAssets(payload, links), generatedFiles);
     await writeFile(path.join(runDir, "topics.md"), topics(payload, links), generatedFiles);
     await writeFile(path.join(runDir, "draft-outline.md"), outline(payload, links), generatedFiles);
     await writeFile(longTermTargets.raw, contentFile(payload, content, links), generatedFiles);
-    await writeFile(longTermTargets.sourceCard, sourceCard(payload, runDirName, links), generatedFiles);
+    await writeFile(longTermTargets.sourceCard, sourceCard(payload, runDirName, links, grounding), generatedFiles);
     await writeFile(longTermTargets.wikiEntry, wikiEntryResult.markdown, generatedFiles);
-    await writeFile(longTermTargets.claims, claims(payload, links), generatedFiles);
+    await writeFile(longTermTargets.claims, claims(payload, links, grounding), generatedFiles);
     await writeFile(longTermTargets.assets, creativeAssets(payload, links), generatedFiles);
     await writeFile(longTermTargets.topics, topics(payload, links), generatedFiles);
     await writeFile(longTermTargets.outline, outline(payload, links), generatedFiles);
-    const warnings = [...payload.warnings, ...collisionWarnings];
-    await writeSummary(root, runDir, payload, generatedFiles, warnings, links);
+    const warnings = [...payload.warnings, ...groundingWarnings(grounding), ...collisionWarnings];
+    await writeSummary(root, runDir, payload, generatedFiles, warnings, links, grounding);
     return { runId, runDir, generatedFiles, warnings, agentReport: buildAgentReport(root, runDir, payload, generatedFiles) };
 }
 export async function ingestFile(rootPath, filePath) {
@@ -111,7 +114,7 @@ async function writeFile(target, content, generatedFiles) {
     }
     generatedFiles.push(target);
 }
-async function writeSummary(root, runDir, payload, generatedFiles, warnings, links) {
+async function writeSummary(root, runDir, payload, generatedFiles, warnings, links, grounding = buildGroundingReport(payload)) {
     const summaryPath = path.join(runDir, "processing-summary.md");
     const files = [...generatedFiles, summaryPath];
     const runId = path.basename(runDir);
@@ -130,6 +133,7 @@ async function writeSummary(root, runDir, payload, generatedFiles, warnings, lin
         `captured_at: "${escapeYaml(payload.source.captured_at)}"`,
         `run_id: "${escapeYaml(runId)}"`,
         ...(links ? relationshipFrontmatter(links) : []),
+        ...groundingFrontmatterLines(grounding),
         `tags: ["aiwiki/run"]`,
         "---",
         "",
@@ -145,6 +149,13 @@ async function writeSummary(root, runDir, payload, generatedFiles, warnings, lin
         "告警：",
         ...(warnings.length ? warnings.map((warning) => `- ${warning}`) : ["- none"]),
         "",
+        "Grounding：",
+        `- evidence_available: ${grounding.evidence_available ? "yes" : "no"}`,
+        `- evidence_channel: ${grounding.evidence_channel}`,
+        `- needs_review: ${grounding.needs_review ? "yes" : "no"}`,
+        `- suspicion_markers: ${grounding.suspicion_markers.length ? grounding.suspicion_markers.join(", ") : "none"}`,
+        `- claims_with_quotes: ${grounding.claim_quote_count}/${grounding.claim_count}`,
+        "",
         "下一步审阅：",
         "- 请在 Obsidian 中人工审阅资料卡、Claim 建议、素材建议、选题和大纲。",
         "- AIWiki CLI 不负责网页抓取稳定性。"
@@ -181,7 +192,7 @@ function contentFile(payload, content, links) {
         ""
     ].join("\n");
 }
-function sourceCard(payload, runId, links) {
+function sourceCard(payload, runId, links, grounding) {
     return [
         "---",
         `aiwiki_id: "${escapeYaml(`${links.slug}:source-card`)}"`,
@@ -197,6 +208,7 @@ function sourceCard(payload, runId, links) {
         `captured_at: "${escapeYaml(payload.source.captured_at)}"`,
         `run_id: "${escapeYaml(runId)}"`,
         ...relationshipFrontmatter(links),
+        ...groundingFrontmatterLines(grounding),
         `aliases: ["${escapeYaml(payload.source.title ?? "Untitled")}"]`,
         `tags: ["aiwiki/source-card"]`,
         "---",
@@ -216,10 +228,19 @@ function sourceCard(payload, runId, links) {
         "## 摘要",
         "",
         trimPreview(payload.source.content ?? payload.source.fetch_notes ?? ""),
+        "",
+        "## Grounding 状态",
+        "",
+        `- 证据通道：${grounding.evidence_channel}`,
+        `- 需要复核：${grounding.needs_review ? "yes" : "no"}`,
+        `- 疑似标记：${grounding.suspicion_markers.length ? grounding.suspicion_markers.join(", ") : "none"}`,
         ""
     ].join("\n");
 }
-function claims(payload, links) {
+function claims(payload, links, grounding) {
+    const claimLines = payload.analysis?.claims.length
+        ? payload.analysis.claims.flatMap((item, index) => claimSuggestionLines(index + 1, item.claim, item.confidence, item.source_quote, payload.source.content ?? ""))
+        : ["- 暂无宿主 Agent 提供的 Claim。"];
     return [
         "---",
         `aiwiki_id: "${escapeYaml(`${links.slug}:claims`)}"`,
@@ -233,6 +254,7 @@ function claims(payload, links) {
         `captured_at: "${escapeYaml(payload.source.captured_at)}"`,
         `run_id: "${escapeYaml(links.runId)}"`,
         ...relationshipFrontmatter(links),
+        ...groundingFrontmatterLines(grounding),
         `tags: ["aiwiki/claims"]`,
         "---",
         "",
@@ -242,6 +264,16 @@ function claims(payload, links) {
         `- 资料卡：${obsidianLink(links.sourceCard, "资料卡")}`,
         `- 原文：${obsidianLink(links.raw, "原文")}`,
         `- 待人工审阅：${payload.source.title ?? "Untitled"}`,
+        "",
+        "## Grounding",
+        "",
+        `- evidence_channel: ${grounding.evidence_channel}`,
+        `- needs_review: ${grounding.needs_review ? "yes" : "no"}`,
+        `- suspicion_markers: ${grounding.suspicion_markers.length ? grounding.suspicion_markers.join(", ") : "none"}`,
+        "",
+        "## 建议",
+        "",
+        ...claimLines,
         ""
     ].join("\n");
 }
@@ -327,6 +359,19 @@ function outline(payload, links) {
         ""
     ].join("\n");
 }
+function claimSuggestionLines(index, claim, confidence, sourceQuote, content) {
+    const quote = sourceQuote?.trim();
+    const supported = Boolean(quote && content.includes(quote));
+    return [
+        `### Claim ${index}`,
+        "",
+        `- claim: ${claim}`,
+        `- confidence: ${confidence ?? "unknown"}`,
+        `- evidence_status: ${supported ? "host_quote_found" : "needs_review"}`,
+        ...(quote ? [`- source_quote: ${quote}`] : ["- source_quote: missing"]),
+        ""
+    ];
+}
 function trimPreview(value) {
     return value.trim().slice(0, 500) || "待人工补充。";
 }
@@ -352,7 +397,8 @@ function buildAgentReport(root, runDir, payload, generatedFiles) {
             reviewQueue: "dashboards/Review Queue.md"
         },
         wikiEntryGenerationMode: fetchFailed ? undefined : (payload.wiki_entry || payload.analysis ? "agent_enriched" : "deterministic_fallback"),
-        wikiEntryQuality: fetchFailed ? undefined : (payload.wiki_entry || payload.analysis ? "enriched" : "scaffold")
+        wikiEntryQuality: fetchFailed ? undefined : (payload.wiki_entry || payload.analysis ? "enriched" : "scaffold"),
+        grounding: buildGroundingReport(payload)
     };
 }
 function estimateFitScore(payload, content) {

package/dist/src/lint.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { frontmatterBoolean, frontmatterString, parseMarkdown } from "./frontmatter.js";
+import { frontmatterArray, frontmatterBoolean, frontmatterString, parseMarkdown } from "./frontmatter.js";
 import { relativePath, safeJoin } from "./paths.js";
 import { exists } from "./workspace.js";
 export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
@@ -57,8 +57,17 @@ export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
                 issues.push({ severity: "warning", path: entry.path, message: "agent_enriched Wiki Entry 缺少 key_points。", suggestion: "让宿主 Agent 提供 analysis.key_points。" });
             }
         }
-        if (frontmatterBoolean(entry.frontmatter, "represents_user_view") === true && frontmatterString(entry.frontmatter, "source_role") === "input") {
-            issues.push({ severity: "warning", path: entry.path, message: "外部 input 被标记为代表用户观点。", suggestion: "将 represents_user_view 改为 false，或在 P1 使用 source_role=output。" });
+        if (frontmatterBoolean(entry.frontmatter, "grounding_needs_review") === true) {
+            const markers = frontmatterArray(entry.frontmatter, "grounding_markers");
+            issues.push({
+                severity: "warning",
+                path: entry.path,
+                message: `Wiki Entry 需要 grounding 复核${markers.length ? `: ${markers.join(", ")}` : "。"}`,
+                suggestion: "检查 source_quote 是否能在 Raw 中找到；coverage_suspected_incomplete 仅代表启发式疑似风险。"
+            });
+        }
+        if (frontmatterBoolean(entry.frontmatter, "represents_user_view") === true && frontmatterString(entry.frontmatter, "source_role") !== "output") {
+            issues.push({ severity: "warning", path: entry.path, message: "只有 output 角色应标记为代表用户观点。", suggestion: "将 represents_user_view 改为 false，或将 source_role 改为 output。" });
         }
     }
     issues.push(...duplicateIssues(sourceCards, "source_url", "重复 URL"));

package/dist/src/payload.js

@@ -35,6 +35,8 @@ export function normalizePayload(raw, runStartedAt) {
     if (!kind) {
         throw new Error("source.kind is required");
     }
+    const sourceRole = normalizeSourceRole(stringValue(sourceRaw.source_role) ?? stringValue(sourceRaw.role), warnings);
+    const representsUserView = booleanValue(sourceRaw.represents_user_view) ?? sourceRole === "output";
     const requestRaw = isRecord(raw.request) ? raw.request : {};
     const requestedOutputs = Array.isArray(requestRaw.outputs)
         ? requestRaw.outputs.filter((item) => typeof item === "string")
@@ -65,6 +67,8 @@ export function normalizePayload(raw, runStartedAt) {
         target_kb: stringValue(raw.target_kb),
         source: {
             kind,
+            source_role: sourceRole,
+            represents_user_view: representsUserView,
             url: stringValue(sourceRaw.url),
             title: titleRepair.value,
             author: stringValue(sourceRaw.author),
@@ -87,6 +91,16 @@ export function normalizePayload(raw, runStartedAt) {
         warnings
     };
 }
+function normalizeSourceRole(value, warnings) {
+    if (!value) {
+        return "input";
+    }
+    if (value === "input" || value === "processing" || value === "output") {
+        return value;
+    }
+    warnings.push(`source_role 已忽略：${value} 不是 input、processing 或 output。`);
+    return "input";
+}
 function normalizeFetchStatus(value, content) {
     if (value === "failed") {
         return "failed";
@@ -110,6 +124,9 @@ function rejectWriteControlFields(raw) {
 function stringValue(value) {
     return typeof value === "string" ? value : undefined;
 }
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -172,7 +189,7 @@ function reusableKnowledgeArray(value, warnings) {
             return [{ content: item.trim() }];
         }
         if (isRecord(item) && typeof item.content === "string" && item.content.trim()) {
-            return [{ title: stringValue(item.title), content: item.content.trim() }];
+            return [{ title: stringValue(item.title), content: item.content.trim(), source_quote: stringValue(item.source_quote) }];
         }
         return [];
     });

package/dist/src/wiki-entry.js

@@ -1,24 +1,26 @@
+import { buildGroundingReport, groundingFrontmatterLines } from "./grounding.js";
 export function renderWikiEntry(payload, links) {
     const enriched = Boolean(payload.wiki_entry || payload.analysis);
     const mode = enriched ? "agent_enriched" : "deterministic_fallback";
     const quality = enriched ? "enriched" : "scaffold";
     const title = payload.wiki_entry?.title ?? payload.source.title ?? "Untitled";
-    const frontmatter = wikiFrontmatter(payload, links, title, mode, quality);
-    const body = enriched ? enrichedBody(payload, links, title) : fallbackBody(payload, links, title);
+    const grounding = buildGroundingReport(payload);
+    const frontmatter = wikiFrontmatter(payload, links, title, mode, quality, grounding);
+    const body = enriched ? enrichedBody(payload, links, title, grounding) : fallbackBody(payload, links, title, grounding);
     return {
         mode,
         quality,
         markdown: `${frontmatter}\n${body}`
     };
 }
-function wikiFrontmatter(payload, links, title, mode, quality) {
+function wikiFrontmatter(payload, links, title, mode, quality, grounding) {
     return [
         "---",
         `aiwiki_id: "${escapeYaml(`${links.slug}:wiki-entry`)}"`,
         `type: "wiki_entry"`,
-        `wiki_type: "source_knowledge"`,
-        `source_role: "input"`,
-        `represents_user_view: false`,
+        `wiki_type: "${wikiType(payload)}"`,
+        `source_role: "${payload.source.source_role}"`,
+        `represents_user_view: ${payload.source.represents_user_view ? "true" : "false"}`,
         `status: "active"`,
         `generation_mode: "${mode}"`,
         `quality: "${quality}"`,
@@ -40,12 +42,23 @@ function wikiFrontmatter(payload, links, title, mode, quality) {
         ...(mode === "agent_enriched" ? [`summary: "${escapeYaml(payload.wiki_entry?.summary ?? payload.analysis?.summary ?? "")}"`] : []),
         `topics: ${yamlStringArray(payload.analysis?.related_concepts ?? [])}`,
         `claims: ${yamlStringArray(payload.analysis?.claims.map((claim) => claim.claim) ?? [])}`,
+        ...groundingFrontmatterLines(grounding),
         `tags: ["aiwiki/wiki-entry"]`,
         "---"
     ].join("\n");
 }
-function enrichedBody(payload, links, title) {
+function wikiType(payload) {
+    if (payload.source.source_role === "output") {
+        return "personal_knowledge";
+    }
+    if (payload.source.source_role === "processing") {
+        return "thought_note";
+    }
+    return "source_knowledge";
+}
+function enrichedBody(payload, links, title, grounding) {
     const sections = [`# ${title}`, ""];
+    appendGroundingReview(sections, grounding);
     if (payload.wiki_entry?.summary || payload.analysis?.summary) {
         sections.push("## 一句话总结", "", payload.wiki_entry?.summary ?? payload.analysis?.summary ?? "", "");
     }
@@ -81,7 +94,7 @@ function bodyHasHeading(markdown, heading) {
     const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     return new RegExp(`^#{1,6}\\s+${escaped}\\s*$`, "m").test(markdown);
 }
-function fallbackBody(payload, links, title) {
+function fallbackBody(payload, links, title, grounding) {
     const preview = trimPreview(payload.source.content ?? payload.source.fetch_notes ?? "", 1000);
     return [
         `# ${title}`,
@@ -112,6 +125,8 @@ function fallbackBody(payload, links, title) {
         "- 适用场景",
         "- 可转化选题",
         "",
+        ...groundingReviewLines(grounding),
+        "",
         sourceSection(links)
     ].join("\n");
 }
@@ -134,6 +149,20 @@ function sourceSection(links) {
         `- Run: ${obsidianLink(links.runSummary, "处理记录")}`
     ].join("\n");
 }
+function appendGroundingReview(sections, grounding) {
+    if (!grounding.needs_review) {
+        return;
+    }
+    sections.push("## Grounding 复核", "", ...groundingReviewLines(grounding), "");
+}
+function groundingReviewLines(grounding) {
+    return [
+        `- 证据通道：${grounding.evidence_channel}`,
+        `- 需要复核：${grounding.needs_review ? "yes" : "no"}`,
+        `- 疑似标记：${grounding.suspicion_markers.length ? grounding.suspicion_markers.join(", ") : "none"}`,
+        `- Claim 引用覆盖：${grounding.claim_quote_count}/${grounding.claim_count}`
+    ];
+}
 function obsidianLink(vaultPath, label) {
     return `[[${vaultPath.replace(/\\/g, "/").replace(/\.md$/i, "")}|${label}]]`;
 }

package/dist/src/workspace.js

@@ -29,9 +29,12 @@ AIWiki 的 Obsidian 入口。Dataview 是可选增强；未安装时仍可使用
 
 ## 原生链接入口
 
+- [[dashboards/Wiki Entries|Wiki 条目]]
+- [[dashboards/Source Cards|资料卡]]
 - [[dashboards/Review Queue|待审队列]]
 - [[dashboards/Recent Runs|最近处理]]
 - [[dashboards/Topic Pipeline|选题管线]]
+- [[dashboards/Lint Report|结构检查]]
 - [[_system/schemas/aiwiki-frontmatter|字段说明]]
 
 ## 最近收录
@@ -51,6 +54,34 @@ FROM "03-sources/article-cards" or "04-claims/_suggestions" or "06-assets/_sugge
 WHERE status = "to-review"
 SORT created_at DESC
 \`\`\`
+`
+    },
+    {
+        path: "dashboards/Wiki Entries.md",
+        content: `# Wiki 条目
+
+AIWiki 每次成功入库都会生成 Wiki Entry。这里是知识层入口，不要求先经过 Review Queue 才能查询。
+
+\`\`\`dataview
+TABLE wiki_type, source_role, represents_user_view, quality, source_card, raw_file, updated_at
+FROM "05-wiki"
+WHERE type = "wiki_entry"
+SORT updated_at DESC
+\`\`\`
+`
+    },
+    {
+        path: "dashboards/Source Cards.md",
+        content: `# 资料卡
+
+资料卡用于追踪来源、原文、Claim 建议、素材建议、选题和大纲。
+
+\`\`\`dataview
+TABLE status, source_url, wiki_entry, raw_note, captured_at
+FROM "03-sources/article-cards"
+WHERE type = "source_card"
+SORT captured_at DESC
+\`\`\`
 `
     },
     {

package/docs/AGENT_HANDOFF.md

@@ -22,6 +22,8 @@ AIWiki CLI 负责：校验 payload、写本地文件、生成 Wiki Entry、输
 
 AIWiki CLI 不做通用网页抓取，也不调用 LLM。网页读取失败时，Agent 仍然要调用 CLI 记录失败原因；高质量 Wiki 内容由宿主 Agent 提供。
 
+证据和疑似风险要分开：`source_quote` 等能回到原文的字段是宿主提供的 evidence/provenance；`coverage_suspected_incomplete`、`unsupported_claims`、`needs_review` 是 AIWiki 的复核提示，不代表已经证明遗漏或错误。
+
 ## 标准流程
 
 1. 读取用户给的 URL、正文、附件或消息。
@@ -63,7 +65,9 @@ AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应
     "content": "这里是宿主 Agent 读取到的正文内容。",
     "fetcher": "host-agent",
     "fetch_status": "ok",
-    "captured_at": "2026-05-07T10:00:00+08:00"
+    "captured_at": "2026-05-07T10:00:00+08:00",
+    "source_role": "input",
+    "represents_user_view": false
   },
   "analysis": {
     "summary": "一句话总结。",
@@ -73,6 +77,13 @@ AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应
     ],
     "related_concepts": [
       "概念 A"
+    ],
+    "claims": [
+      {
+        "claim": "强主张应绑定原文证据",
+        "confidence": "high",
+        "source_quote": "这里是宿主 Agent 读取到的正文内容。"
+      }
     ]
   },
   "request": {
@@ -141,6 +152,7 @@ AIWiki 已完成入库，并生成 Wiki 条目。
 摘要：<summary>
 Wiki 条目：<wiki_entry>
 质量模式：<wiki_entry_quality> / <wiki_entry_generation_mode>
+Grounding：<grounding_evidence_channel> / review=<grounding_needs_review> / markers=<grounding_markers>
 资料卡：<source_card>
 处理记录：<processing_summary>
 ```
@@ -163,6 +175,12 @@ Obsidian 入口：<dashboard>
 aiwiki context "<主题>"
 ```
 
+`context` 是给宿主 Agent 使用的 JSON。如果用户是在终端里直接想看结果，可以运行：
+
+```bash
+aiwiki query "<主题>"
+```
+
 当用户说“整理 / 检查知识库”时，调用：
 
 ```bash
@@ -170,3 +188,23 @@ aiwiki lint
 ```
 
 `context` 返回 JSON，注意其中的 `generation_mode`、`quality` 和 `warnings`。如果结果是 `deterministic_fallback` / `scaffold`，回复时要说明它只是可追溯脚手架，不是高质量知识提炼。
+
+`context` 也可能返回 grounding 字段。回复用户时可以把 `grounding_needs_review: true` 解释为“这条资料需要复核证据或覆盖度”，不要说成“AIWiki 已确认漏掉重点”。
+
+## Source Role
+
+默认外部资料使用：
+
+```json
+"source_role": "input",
+"represents_user_view": false
+```
+
+只有当用户明确导入自己的已发布文章、演讲稿、公众号文章等个人输出时，才使用：
+
+```json
+"source_role": "output",
+"represents_user_view": true
+```
+
+不要把外部资料标成代表用户观点。

package/docs/USAGE.md

@@ -10,6 +10,8 @@ AIWiki CLI 不负责网页抓取。Qclaw、Codex、Claude Code、Cursor、Gemini
 
 AIWiki CLI 也不调用 LLM。高质量 Wiki Entry 来自宿主 Agent 提供的 `analysis` 或 `wiki_entry`；如果没有这些字段，AIWiki 会生成可追溯的 deterministic fallback 条目，只包含来源、反链、正文预览和待补全区。
 
+AIWiki 会把证据通道和疑似风险分开记录。`source_quote` 等宿主 Agent 提供的原文引用属于证据通道；`coverage_suspected_incomplete`、`unsupported_claims`、`needs_review` 等属于 AIWiki 生成的启发式复核信号，不等于已经证明内容遗漏。
+
 ## 1. 一次性设置
 
 发布后直接运行交互式 setup：
@@ -56,6 +58,7 @@ aiwiki status
 
 ```bash
 aiwiki agent list
+aiwiki agent check
 ```
 
 再启动安装向导：
@@ -88,6 +91,8 @@ aiwiki prompt agent
 
 把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
+`aiwiki agent check` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent install --agent <id> --yes`。
+
 ## 3. 日常使用
 
 宿主 Agent 已经加载 AIWiki 协议后，把下面的话发给它，并替换链接：
@@ -125,6 +130,11 @@ processing_summary: 09-runs/20260507-153012-abc123/processing-summary.md
 wiki_entry: 05-wiki/source-knowledge/article-slug.md
 wiki_entry_generation_mode: agent_enriched
 wiki_entry_quality: enriched
+grounding_evidence_available: yes
+grounding_evidence_channel: host_supplied
+grounding_needs_review: no
+grounding_markers: none
+grounding_claims_with_quotes: 1/1
 source_card: 03-sources/article-cards/article-slug.md
 draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md
 dashboard: dashboards/AIWiki Home.md
@@ -205,6 +215,26 @@ Wiki Entry 有两种质量模式：
 - `agent_enriched` / `enriched`：宿主 Agent 提供了 `analysis` 或 `wiki_entry`。
 - `deterministic_fallback` / `scaffold`：AIWiki 只生成来源、反链、正文预览和待补全区。
 
+Artifact 角色保持固定：
+
+- `03-sources/article-cards` 是 trace-first 的资料卡：保留来源、反链、原文预览和 grounding 状态，不承担完整知识正文。
+- `05-wiki/source-knowledge` 是 enriched knowledge surface：宿主 Agent 的 `analysis` / `wiki_entry` 会进入这里。
+- `02-raw/articles` 是原始证据层，后续摘要、Claim 和复核都应能回查这里。
+
+Grounding 字段都是 additive，可被旧工具忽略：
+
+- `grounding_evidence_available`：是否存在可回查的宿主证据。
+- `grounding_evidence_channel`：`host_supplied` 或 `none`。
+- `grounding_needs_review`：是否需要复核。
+- `grounding_markers`：例如 `unsupported_claims`、`source_quote_not_found`、`coverage_suspected_incomplete`。
+- `coverage_suspected_incomplete`：长文提取过少时的启发式疑似标记，不是确定遗漏结论。
+
+Wiki Entry 还会记录来源角色：
+
+- `source_role: input`：默认值，外部文章、网页、书籍、视频等资料；`represents_user_view: false`。
+- `source_role: output`：用户已发布文章、演讲稿、公众号文章等个人输出；通常可配合 `represents_user_view: true`。
+- `source_role: processing`：用户自己的草稿、笔记、思考过程；默认不直接代表最终观点。
+
 ### Obsidian 链接规则
 
 AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会使用 wikilink：
@@ -229,6 +259,8 @@ AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会
 
 ```text
 dashboards/AIWiki Home.md
+dashboards/Wiki Entries.md
+dashboards/Source Cards.md
 dashboards/Review Queue.md
 dashboards/Recent Runs.md
 dashboards/Topic Pipeline.md
@@ -271,15 +303,24 @@ docs/AGENT_HANDOFF.md
 
 ```bash
 aiwiki context "AI Agent"
+aiwiki query "AI Agent"
 ```
 
+`context` 返回 JSON 给宿主 Agent 使用；`query` 使用同一套检索结果，输出给人看的分组摘要。
+
 检查知识库结构：
 
 ```bash
 aiwiki lint
 ```
 
-`context` 返回 JSON 给宿主 Agent 使用。`lint` 输出报告并写入 `dashboards/Lint Report.md`。
+查看下一步建议：
+
+```bash
+aiwiki next
+```
+
+`lint` 输出报告并写入 `dashboards/Lint Report.md`。
 
 ## 8. 高级调试
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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/SKILL.md

@@ -74,7 +74,9 @@ Because AIWiki CLI does not call an LLM, high-quality summary and knowledge extr
     "content": "Article body read by the host Agent.",
     "fetcher": "host-agent",
     "fetch_status": "ok",
-    "captured_at": "2026-05-07T10:00:00+08:00"
+    "captured_at": "2026-05-07T10:00:00+08:00",
+    "source_role": "input",
+    "represents_user_view": false
   },
   "analysis": {
     "summary": "One-sentence summary.",
@@ -130,6 +132,14 @@ 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.
 
+For direct human terminal output, use:
+
+```bash
+aiwiki query "<topic>"
+```
+
+`query` renders the same retrieval basis as `context`; do not treat it as a separate search system.
+
 ## Lint Protocol
 
 When the user asks to整理 / 检查 / lint the knowledge base, call:
@@ -140,6 +150,17 @@ aiwiki lint
 
 Explain warnings and errors as structure-health feedback. Do not frame lint as a requirement that the user manually review every item.
 
+## Source Role
+
+Use the default source role for external material:
+
+```json
+"source_role": "input",
+"represents_user_view": false
+```
+
+Only use `source_role: "output"` with `represents_user_view: true` when the user is importing their own published writing, talk transcript, newsletter, or similar authored output. Do not mark external material as the user's view.
+
 ## Obsidian + Dataview Boundary
 
 - AIWiki can be used with plain Markdown.