@itradingai/aiwiki 0.2.10 → 0.2.12

package/docs/AGENT_HANDOFF.md

@@ -15,33 +15,36 @@ Agent 应自动读取网页，生成 payload，通过 AIWiki CLI 写入本地知
 ## 职责边界
 
 ```text
-Agent 负责：读取网页、整理正文、生成 payload、调用 CLI、回复用户
-AIWiki CLI 负责：校验 payload、写本地文件、输出入库结果
+Agent 负责：读取网页、理解正文、尽量生成 analysis/wiki_entry、调用 CLI、回复用户
+AIWiki CLI 负责：校验 payload、写本地文件、生成 Wiki Entry、输出入库结果
 用户负责：提供链接或正文，最后审阅结果
 ```
 
-AIWiki CLI 不做通用网页抓取。网页读取失败时，Agent 仍然要调用 CLI 记录失败原因。
+AIWiki CLI 不做通用网页抓取，也不调用 LLM。网页读取失败时，Agent 仍然要调用 CLI 记录失败原因；高质量 Wiki 内容由宿主 Agent 提供。
+
+证据和疑似风险要分开：`source_quote` 等能回到原文的字段是宿主提供的 evidence/provenance；`coverage_suspected_incomplete`、`unsupported_claims`、`needs_review` 是 AIWiki 的复核提示，不代表已经证明遗漏或错误。
 
 ## 标准流程
 
 1. 读取用户给的 URL、正文、附件或消息。
 2. 如果读取成功，生成 `fetch_status: "ok"` 的 payload。
-3. 如果读取失败，生成 `fetch_status: "failed"` 的 payload，并写清 `fetch_notes`。
-4. 不要让用户保存 payload。
-5. 不要让用户手动运行命令。
-6. 优先通过 stdin 调用：
+3. 尽量基于正文生成 `analysis` 或 `wiki_entry`。
+4. 如果读取失败，生成 `fetch_status: "failed"` 的 payload，并写清 `fetch_notes`。
+5. 不要让用户保存 payload。
+6. 不要让用户手动运行命令。
+7. 优先通过 stdin 调用：
 
 ```bash
 aiwiki ingest-agent --stdin
 ```
 
-7. 如果当前 shell、终端或宿主环境无法保证 stdin 是 UTF-8，先把 payload 写成 UTF-8 JSON 文件，再调用：
+8. 如果当前 shell、终端或宿主环境无法保证 stdin 是 UTF-8，先把 payload 写成 UTF-8 JSON 文件，再调用：
 
 ```bash
 aiwiki ingest-agent --payload <utf8-json-file>
 ```
 
-8. 读取 CLI 输出，向用户回复入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+9. 读取 CLI 输出，向用户回复入库状态、摘要、Wiki 条目、质量模式、资料卡和处理记录。
 
 ## 编码要求
 
@@ -62,12 +65,32 @@ 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": "一句话总结。",
+    "key_points": [
+      "核心观点 1",
+      "核心观点 2"
+    ],
+    "related_concepts": [
+      "概念 A"
+    ],
+    "claims": [
+      {
+        "claim": "强主张应绑定原文证据",
+        "confidence": "high",
+        "source_quote": "这里是宿主 Agent 读取到的正文内容。"
+      }
+    ]
   },
   "request": {
     "mode": "ingest",
     "outputs": [
       "source_card",
+      "wiki_entry",
       "creative_assets",
       "topics",
       "draft_outline",
@@ -108,6 +131,7 @@ AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应
 - 不要让用户手动保存 payload。
 - 不要让用户每次输入 `--path`。
 - 不要声称网页抓取是 AIWiki CLI 的能力。
+- 不要声称 AIWiki CLI 会在没有 Agent 分析字段时自动高质量总结。
 - 不要在 `fetch_status: "failed"` 时塞入正文内容。
 - 不要替用户安装 Dataview。
 - 不要修改 `.obsidian`、`community-plugins.json` 或 Obsidian 插件配置。
@@ -123,13 +147,14 @@ Dataview 只是可选增强。用户自行在 Obsidian Community plugins 中安
 成功时：
 
 ```text
-已加入 Obsidian 审阅队列。
+AIWiki 已完成入库，并生成 Wiki 条目。
 契合度：<fit_score> / <fit_level>
 摘要：<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>
-Obsidian 入口：<dashboard>
-待审队列：<review_queue>
 ```
 
 失败但已记录时：
@@ -140,5 +165,46 @@ Obsidian 入口：<dashboard>
 记录目录：<run_dir>
 处理摘要：<processing_summary>
 Obsidian 入口：<dashboard>
-待审队列：<review_queue>
 ```
+
+## Query / Lint
+
+当用户说“从 AIWiki 里了解某个主题”时，调用：
+
+```bash
+aiwiki context "<主题>"
+```
+
+`context` 是给宿主 Agent 使用的 JSON。如果用户是在终端里直接想看结果，可以运行：
+
+```bash
+aiwiki query "<主题>"
+```
+
+当用户说“整理 / 检查知识库”时，调用：
+
+```bash
+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/FAQ.md

@@ -2,11 +2,28 @@
 
 ## AIWiki 是什么？
 
-AIWiki 是一个开源的 Agent-first AI 知识库 CLI。它把文章链接、网页正文和本地文本整理成本地知识资产，方便在 Obsidian 里继续审阅和写作。
+AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。宿主 Agent 负责读取和理解内容，AIWiki 负责把结果稳定写成本地 Markdown 知识库。
 
 ## AIWiki 是网页爬虫吗？
 
-不是。网页读取主要交给宿主 Agent，AIWiki 专注于校验结构化输入、写本地文件和生成审阅产物。
+不是。网页读取主要交给宿主 Agent，AIWiki 专注于校验结构化输入、写本地文件、生成 Wiki Entry、提供 context 和 lint。
+
+## AIWiki 会自动高质量总结吗？
+
+不会。AIWiki CLI 本身不调用 LLM。高质量 Wiki Entry 来自宿主 Agent 在 payload 中提供的 `analysis` 或 `wiki_entry`。
+
+## 为什么会生成 05-wiki？
+
+因为 AIWiki 的目标不是只保存资料，而是让资料进入可查询、可维护的 Wiki 知识层。成功入库会生成 `05-wiki/source-knowledge/<slug>.md`。
+
+## Wiki Entry 的两种质量模式是什么？
+
+- `agent_enriched` / `enriched`：宿主 Agent 提供了总结、核心观点、知识点等分析结果。
+- `deterministic_fallback` / `scaffold`：AIWiki 只生成标题、来源、正文预览、反链和待补全区。
+
+## 05-wiki 是否代表我的观点？
+
+不一定。外部资料生成的 Wiki Entry 默认代表外部资料的结构化整理，不代表用户个人观点。
 
 ## 一定要用 Obsidian 吗？
 
@@ -18,9 +35,9 @@ AIWiki 是一个开源的 Agent-first AI 知识库 CLI。它把文章链接、
 
 ## 宿主 Agent 和 AIWiki 各负责什么？
 
-- 宿主 Agent 负责读取网页、正文或附件，并组装 payload
-- AIWiki 负责校验 payload、写本地知识库、输出处理记录
-- 用户负责提供链接或正文，最后在 Obsidian 里审阅结果
+- 宿主 Agent 负责读取网页、正文或附件，并尽量生成 `analysis` / `wiki_entry`
+- AIWiki 负责校验 payload、写本地知识库、生成 Wiki Entry、输出处理记录
+- 用户负责提供链接或正文，并在需要时让 Agent 继续查询或补全
 
 ## 为什么要先让 Agent 学会 AIWiki？
 
@@ -45,3 +62,19 @@ aiwiki agent install
 - [USAGE.md](USAGE.md)
 - [SHOWCASE.md](SHOWCASE.md)
 - [AGENT_HANDOFF.md](AGENT_HANDOFF.md)
+
+## 怎么从知识库里查询？
+
+让宿主 Agent 调用：
+
+```bash
+aiwiki context "主题"
+```
+
+## 怎么检查知识库结构？
+
+运行：
+
+```bash
+aiwiki lint
+```

package/docs/SHOWCASE.md

@@ -13,7 +13,7 @@
 ### 宿主 Agent 做的事
 
 1. 读取网页正文或可访问内容。
-2. 组装 `aiwiki.agent_payload.v1`。
+2. 组装 `aiwiki.agent_payload.v1`，并尽量提供 `analysis` 或 `wiki_entry`。
 3. 调用 `aiwiki ingest-agent --stdin`。
 4. 把 AIWiki 的处理结果回复给用户。
 
@@ -23,6 +23,7 @@
 09-runs/<run-id>/payload.json
 09-runs/<run-id>/raw.md
 09-runs/<run-id>/source-card.md
+09-runs/<run-id>/wiki-entry.md
 09-runs/<run-id>/creative-assets.md
 09-runs/<run-id>/topics.md
 09-runs/<run-id>/draft-outline.md
@@ -35,6 +36,7 @@
 02-raw/articles/
 03-sources/article-cards/
 04-claims/_suggestions/
+05-wiki/source-knowledge/
 06-assets/_suggestions/
 07-topics/ready/
 08-outputs/outlines/
@@ -44,8 +46,9 @@ dashboards/
 ### 用户在 Obsidian 里怎么看
 
 - 打开 `dashboards/AIWiki Home.md`
-- 查看 `dashboards/Review Queue.md`
-- 从资料卡回到原文、选题、大纲和处理记录
+- 查看 `05-wiki/source-knowledge/<slug>.md`
+- 从 Wiki 条目回到资料卡、原文、选题、大纲和处理记录
+- 需要结构检查时运行 `aiwiki lint`
 
 ## 示例 2：网页没读到正文
 
@@ -74,5 +77,7 @@ dashboards/
 
 - AIWiki 不是网页爬虫本体
 - 宿主 Agent 负责读取内容
+- 宿主 Agent 负责高质量总结和知识提炼
 - AIWiki 负责稳定写入本地知识库
+- AIWiki 会创建 Wiki Entry；没有 Agent 分析字段时只生成可追溯脚手架
 - 结果始终可追踪、可复盘、可继续写作

package/docs/USAGE.md

@@ -8,6 +8,10 @@
 
 AIWiki CLI 不负责网页抓取。Qclaw、Codex、Claude Code、Cursor、Gemini CLI 等都只是宿主 Agent 的例子；这份文档面向的是通用宿主 Agent 协作。
 
+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：
@@ -54,6 +58,7 @@ aiwiki status
 
 ```bash
 aiwiki agent list
+aiwiki agent check
 ```
 
 再启动安装向导：
@@ -86,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 协议后，把下面的话发给它，并替换链接：
@@ -118,8 +125,16 @@ source_url: https://example.com/article
 summary: 这里是文章前段摘要，方便 Agent 快速告诉用户文章大意。
 run_id: 20260507-153012-abc123
 run_dir: F:\knowledge_data\aiwiki\09-runs\20260507-153012-abc123
-files: 13
+files: 15
 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
@@ -130,13 +145,13 @@ warnings: 0
 宿主 Agent 回复用户时建议展示：
 
 ```text
-已加入 Obsidian 审阅队列。
+AIWiki 已完成入库，并生成 Wiki 条目。
 契合度：90 / high
 摘要：……
+Wiki 条目：……
+质量模式：enriched / agent_enriched
 资料卡：……
 处理记录：……
-Obsidian 入口：dashboards/AIWiki Home.md
-待审队列：dashboards/Review Queue.md
 ```
 
 网页读取失败但已记录原因时类似：
@@ -187,12 +202,38 @@ Obsidian 入口：dashboards/AIWiki Home.md
 02-raw/articles/
 03-sources/article-cards/
 04-claims/_suggestions/
+05-wiki/source-knowledge/
 06-assets/_suggestions/
 07-topics/ready/
 08-outputs/outlines/
 ```
 
-Obsidian 主要审阅长期目录；`09-runs` 用于追溯每次处理。
+`05-wiki/source-knowledge` 是默认知识层；`09-runs` 用于追溯每次处理。
+
+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 链接规则
 
@@ -200,13 +241,14 @@ AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会
 
 ```text
 [[03-sources/article-cards/article-slug|资料卡]]
+[[05-wiki/source-knowledge/article-slug|Wiki 条目]]
 [[02-raw/articles/article-slug|原文]]
 [[09-runs/20260507-153012-abc123/processing-summary|处理记录]]
 ```
 
 链接规则：
 - wikilink 使用 vault 相对路径，统一为 `/`，并去掉 `.md` 后缀。
-- `03-sources/article-cards` 是主要审阅入口，会链接到原文、Claim 建议、素材建议、选题、大纲和本次处理记录。
+- `05-wiki/source-knowledge` 是默认知识入口；`03-sources/article-cards` 会链接到 Wiki 条目、原文、Claim 建议、素材建议、选题、大纲和本次处理记录。
 - `02-raw/articles`、`04-claims/_suggestions`、`06-assets/_suggestions`、`07-topics/ready`、`08-outputs/outlines` 会回链到资料卡，Obsidian 的 Backlinks/Graph View 可以串起同一篇资料。
 - `09-runs/<run-id>/processing-summary.md` 会把本次生成的 Markdown 文件列成可点击 wikilink；`payload.json` 不是 Markdown，保留普通路径。
 - frontmatter 会写入 `aiwiki_id`、`type`、`status`、`slug`、`source_url`、`created_at`、`captured_at`、`run_id`、`source_card`、`raw_note`、`claims_note`、`assets_note`、`topics_note`、`outline_note`、`run_summary`、`tags` 等字段，便于后续用 Obsidian Search / Properties / Dataview 做筛选。
@@ -217,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
@@ -247,12 +291,38 @@ docs/AGENT_HANDOFF.md
 核心要求：
 
 - Agent 负责读取网页正文。
+- Agent 应尽量提供 `analysis` 或 `wiki_entry`，让 Wiki Entry 进入 enriched 模式。
 - Agent 不要让用户保存 payload。
 - Agent 不要让用户手动运行 `ingest-agent`。
 - Agent 生成 payload 后优先通过 stdin 调用 `aiwiki ingest-agent --stdin`。
-- Agent 最后只向用户汇报入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+- Agent 最后向用户汇报入库状态、摘要、Wiki 条目、质量模式、资料卡和处理记录。
+
+## 7. 查询和整理
+
+从知识库调度内容：
+
+```bash
+aiwiki context "AI Agent"
+aiwiki query "AI Agent"
+```
+
+`context` 返回 JSON 给宿主 Agent 使用；`query` 使用同一套检索结果，输出给人看的分组摘要。
+
+检查知识库结构：
+
+```bash
+aiwiki lint
+```
+
+查看下一步建议：
+
+```bash
+aiwiki next
+```
+
+`lint` 输出报告并写入 `dashboards/Lint Report.md`。
 
-## 7. 高级调试
+## 8. 高级调试
 
 如果 Agent 只能输出 JSON，才需要手动保存 payload：
 
@@ -285,7 +355,7 @@ aiwiki ingest-url "https://example.com/article" --content-file "F:\knowledge_dat
 
 注意：`ingest-url` 不会抓网页，只会读取 `--content-file`。
 
-## 8. 常见问题
+## 9. 常见问题
 
 ### 找不到 `aiwiki` 命令
 
@@ -317,7 +387,7 @@ aiwiki setup --path "F:\knowledge_data\aiwiki" --yes
 aiwiki setup --path "新的知识库路径" --yes
 ```
 
-## 9. 最小验收清单
+## 10. 最小验收清单
 
 完成一次 Agent 入库测试后，检查：
 
@@ -331,4 +401,5 @@ aiwiki status
 - `09-runs` 下出现新目录。
 - `processing-summary.md` 存在。
 - 成功读取时，`03-sources/article-cards` 下出现资料卡。
+- 成功读取时，`05-wiki/source-knowledge` 下出现 Wiki Entry。
 - 抓取失败时，`09-runs/<run-id>-fetch-failed` 下出现失败记录。

package/package.json

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

@@ -0,0 +1,42 @@
+# AIWiki Lint Protocol
+
+Use this protocol when the user asks:
+
+- 整理一下 AIWiki
+- 检查知识库有没有问题
+- 看看 AIWiki 结构是否健康
+- lint AIWiki
+
+## Steps
+
+1. Call:
+
+```bash
+aiwiki lint
+```
+
+2. Read the terminal report.
+3. 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".
+
+## Issue Meaning
+
+- `error`: broken structure such as a missing internal link.
+- `warning`: likely fix needed, such as missing source fields or stale fallback entries.
+- `info`: useful inventory, such as deterministic fallback count or duplicate titles.
+
+## Repair Guidance
+
+Prefer small, traceable fixes:
+
+- Regenerate or enrich missing Wiki Entries.
+- 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

@@ -0,0 +1,38 @@
+# AIWiki Query Protocol
+
+Use this protocol when the user asks:
+
+- 从 AIWiki 里了解某个主题
+- 基于 AIWiki 里的资料总结某个问题
+- AIWiki 里有没有关于某个主题的内容
+- 帮我用 AIWiki 写一篇文章大纲
+
+## Steps
+
+1. Identify the topic and expected output shape.
+2. Call:
+
+```bash
+aiwiki context "<topic>"
+```
+
+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:
+   - Wiki Entries are insufficient.
+   - The user asks to verify the original source.
+   - There is a source conflict.
+   - A precise quote or source check is needed.
+
+## Reply Shape
+
+Include:
+
+- Which Wiki Entries were found.
+- Main conclusions.
+- Source basis.
+- Known gaps or scaffold warnings.
+- Suggested next step.
+