@itradingai/aiwiki 0.2.5

package/docs/OBSIDIAN_DATAVIEW_PLAN.md

@@ -0,0 +1,194 @@
+# Obsidian + Dataview Integration
+
+## Decision
+
+AIWiki should treat Obsidian compatibility as a first-class product surface:
+
+- Base layer: works with Obsidian native Markdown, Properties, Backlinks, Search, and Graph View.
+- Enhanced layer: ships optional Dataview dashboards for users who install the Dataview community plugin.
+- Boundary: AIWiki must not automatically install or modify Obsidian community plugins. Plugin installation stays a documented user action.
+
+This keeps the knowledge base portable while making the Obsidian review workflow feel like a database when Dataview is available.
+
+## Implementation Status
+
+Implemented in `0.2.0`:
+
+- `setup` seeds dashboard, schema, and template files when missing.
+- Generated Markdown includes database-oriented frontmatter relationship fields.
+- CLI ingest output reports `dashboard` and `review_queue`.
+- The bundled Agent skill tells host Agents to report Obsidian review entry points and not to install Dataview automatically.
+
+## Evidence From Current Code
+
+- Workspace setup already creates `dashboards`, `_system/templates`, and `_system/schemas`, but only creates directories. No seeded dashboard/schema/template files exist yet. See `src/workspace.ts` lines 11-23 and 47-68.
+- Ingest now writes Obsidian wikilinks and basic frontmatter fields. See `src/ingest.ts` lines 190-244 and 247-320.
+- Generated relationship fields are currently mostly body links, not queryable frontmatter fields. See `src/ingest.ts` lines 203-206, 231-238, 258-259, 276-277, 294-295, and 312-313.
+- Existing usage docs mention Dataview only as a possible filter surface, not as an optional database enhancement with setup instructions. See `docs/USAGE.md` lines 189-204.
+- The Agent skill reports CLI output fields, but does not tell host Agents how to surface Obsidian dashboards or review queues to users. See `skill/SKILL.md` lines 30-39.
+
+External grounding:
+
+- Obsidian supports wikilinks and display aliases such as `[[note|label]]`: https://help.obsidian.md/Linking%20notes%20and%20files/Internal%20links
+- Obsidian properties are YAML stored at the top of notes: https://help.obsidian.md/properties
+- Dataview queries metadata fields from frontmatter/inline fields and implicit file metadata: https://blacksmithgu.github.io/obsidian-dataview/annotation/add-metadata/
+
+## Product Positioning
+
+This should become one of AIWiki's selling points:
+
+> AIWiki does not just save article Markdown. It turns every collected source into an Obsidian-ready review database: native Properties and Backlinks work out of the box, while optional Dataview dashboards provide source queues, claim queues, topic queues, and recent-run traceability.
+
+The user flow should become:
+
+1. `aiwiki setup` creates the vault-like folder structure plus database assets.
+2. User optionally installs Dataview in Obsidian.
+3. User asks a host Agent: `入库 <url>`.
+4. AIWiki writes raw/source/claims/assets/topics/outlines/runs with stable metadata and wikilinks.
+5. User opens `dashboards/AIWiki Home.md` in Obsidian.
+6. Without Dataview: links and Properties still work.
+7. With Dataview: dashboards render tables for review queues and recent activity.
+
+## Target Database Schema
+
+All generated Markdown notes should share these frontmatter fields:
+
+```yaml
+aiwiki_id: "<stable slug or run-scoped id>"
+type: "source_card | raw_article | claim_suggestions | asset_suggestions | topic_candidates | draft_outline | processing_summary"
+status: "to-review | ready | draft | reviewed | archived | fetch-failed"
+slug: "<article-slug>"
+title: "<human title>"
+source_url: "<original URL when available>"
+source_type: "url | file | text"
+source_card: "[[03-sources/article-cards/slug|资料卡]]"
+raw_note: "[[02-raw/articles/slug|原文]]"
+claims_note: "[[04-claims/_suggestions/slug-claims|Claim 建议]]"
+assets_note: "[[06-assets/_suggestions/slug-assets|素材建议]]"
+topics_note: "[[07-topics/ready/slug-topics|选题]]"
+outline_note: "[[08-outputs/outlines/slug-outline|大纲]]"
+run_summary: "[[09-runs/run-id/processing-summary|处理记录]]"
+run_id: "<run-id>"
+created_at: "<ISO timestamp>"
+captured_at: "<ISO timestamp from host Agent>"
+tags:
+  - aiwiki/source-card
+```
+
+Rules:
+
+- Use Obsidian-link strings in frontmatter for relationship fields, because Obsidian Properties can display internal links when they are quoted YAML strings.
+- Keep body wikilinks as human navigation, but make frontmatter the database source of truth.
+- Use lowercase snake_case field names to avoid Dataview field-name normalization surprises.
+- Preserve existing `url` for compatibility, but prefer `source_url` going forward.
+
+## Dashboard Files To Generate
+
+`aiwiki setup` should seed these files if missing:
+
+- `dashboards/AIWiki Home.md`: entry point, review counts, recent sources, links to all queues.
+- `dashboards/Review Queue.md`: sources and claims with `status = "to-review"`.
+- `dashboards/Recent Runs.md`: processing summaries sorted by creation time.
+- `dashboards/Topic Pipeline.md`: topic candidates and draft outlines.
+- `_system/schemas/aiwiki-frontmatter.md`: schema reference and allowed values.
+- `_system/templates/source-card.md`: source-card template.
+- `_system/templates/review-note.md`: generic review template.
+
+Dashboards should include:
+
+- A short native fallback section with normal links.
+- A Dataview section fenced as `dataview`, so users with the plugin get rendered tables.
+- A clear note that installing Dataview is optional.
+
+Example query:
+
+```dataview
+TABLE status, source_url, captured_at, run_summary
+FROM "03-sources/article-cards"
+WHERE type = "source_card"
+SORT captured_at DESC
+```
+
+## Implementation Plan
+
+1. Add workspace seed-file support in `src/workspace.ts`.
+   - Create a helper like `ensureSeedFile(root, relativePath, content)`.
+   - Only write files when missing, so user-edited dashboards/templates are not overwritten.
+   - Return seeded files in setup/init results so CLI can report them.
+
+2. Expand generated frontmatter in `src/ingest.ts`.
+   - Add stable relationship fields to raw, source card, claims, assets, topics, outline, and processing summary.
+   - Make `processing-summary.md` a first-class typed note with frontmatter.
+   - Keep existing body wikilinks for human navigation.
+
+3. Add dashboard content and schema docs.
+   - Seed `AIWiki Home.md`, `Review Queue.md`, `Recent Runs.md`, `Topic Pipeline.md`.
+   - Seed `_system/schemas/aiwiki-frontmatter.md`.
+   - Include optional Dataview installation instructions in docs, not automatic plugin writes.
+
+4. Update CLI output.
+   - After `setup`, print created/kept dashboard files.
+   - After successful ingest, print `dashboard: dashboards/AIWiki Home.md` or `review_queue: dashboards/Review Queue.md`.
+
+5. Update host Agent skill guidance.
+   - Tell Agents to report the Obsidian entry point after ingest.
+   - Tell Agents not to install Dataview or modify `.obsidian`.
+   - Tell Agents to say Dataview is optional and only enhances dashboard rendering.
+
+6. Update tests.
+   - Workspace tests assert seed files are created and preserved on rerun.
+   - Ingest tests assert all generated Markdown has the required frontmatter fields.
+   - CLI tests assert setup reports dashboard seed files and ingest reports the Obsidian entry point.
+   - Add collision tests to ensure relationship frontmatter points to the renamed long-term files.
+
+7. Update version.
+   - This is a user-visible workflow enhancement. Bump minor if implemented as a new feature, patch if only documentation/schema prep is merged.
+
+## Acceptance Criteria
+
+- `aiwiki setup` creates dashboard/schema/template files when missing and preserves them when already edited.
+- A fresh vault works in Obsidian without Dataview: links, backlinks, and Properties are usable.
+- Installing Dataview renders dashboard tables without further file edits.
+- Every generated Markdown note has `aiwiki_id`, `type`, `status`, `slug`, `created_at`, and relevant relationship fields.
+- Dataview queries do not depend on body text parsing.
+- Host Agent skill replies include the Obsidian review entry point.
+- Tests cover setup seeding, ingest metadata, dashboard query presence, and rerun preservation.
+
+## Risks And Mitigations
+
+- Risk: Auto-installing plugins can corrupt or surprise user vaults.
+  - Mitigation: Never edit `.obsidian/community-plugins.json`; document manual Dataview installation only.
+- Risk: Dataview field names drift from generated frontmatter.
+  - Mitigation: Centralize field names in one generator/schema helper and test dashboard query field names.
+- Risk: User customizes dashboards and setup overwrites them.
+  - Mitigation: Seed only when missing; future updates can write `.new` suggestions instead of overwriting.
+- Risk: Obsidian links in YAML are parsed as strings, not link values, in some contexts.
+  - Mitigation: Quote all link strings and keep body wikilinks as fallback navigation.
+
+## Skill Optimization Needed
+
+Yes, the AIWiki skill should be optimized after the database layer is implemented.
+
+Required changes:
+
+- Add an "Obsidian review workflow" section to `skill/SKILL.md`.
+- Instruct host Agents to report `processing_summary`, `source_card`, and the dashboard/review queue path.
+- Instruct host Agents not to install Dataview or edit Obsidian plugin files.
+- Add wording for the final user reply, for example:
+
+```text
+已入库，并加入 Obsidian 审阅队列。
+资料卡：...
+处理记录：...
+Obsidian 入口：dashboards/AIWiki Home.md
+Dataview 是可选增强；未安装时仍可用 Properties、Backlinks 和普通链接审阅。
+```
+
+## Verification Plan
+
+- Run `npm test`.
+- Run `npm pack --dry-run` and confirm dashboard/schema/template assets are included.
+- Generate a sample workspace, open generated Markdown, and inspect frontmatter/query blocks.
+- Manually check one sample vault in Obsidian:
+  - Without Dataview: links and Properties work.
+  - With Dataview: dashboards render tables.

package/docs/README.md

@@ -0,0 +1,28 @@
+# AIWiki Docs
+
+AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent 已经读取到的文章、网页正文或本地文本写入单知识库。
+
+- 用户使用说明：[USAGE.md](USAGE.md)
+- Agent 对接协议：[AGENT_HANDOFF.md](AGENT_HANDOFF.md)
+- Obsidian + Dataview 方案：[OBSIDIAN_DATAVIEW_PLAN.md](OBSIDIAN_DATAVIEW_PLAN.md)
+- 架构图：[architecture.svg](architecture.svg)
+
+## Quick Start
+
+```bash
+npx @itradingai/aiwiki@latest setup
+aiwiki agent list
+aiwiki agent install
+aiwiki prompt agent
+aiwiki doctor
+```
+
+优先运行 `aiwiki agent install`，让 CLI 扫描本机 Codex、QClaw、OpenClaw、Claude Code 等宿主 Agent 并安装到所选目标。其他宿主 Agent 可使用 `aiwiki prompt agent` 输出通用协议，再安装成 skill 或粘贴到项目/会话说明里。之后把链接发给宿主 Agent：
+
+```text
+入库 https://example.com/article
+```
+
+## 重要边界
+
+CLI 不保证网页抓取成功。网页读取属于宿主 Agent。

package/docs/USAGE.md

@@ -0,0 +1,329 @@
+# AIWiki 使用说明
+
+目标体验：
+
+```text
+用户只做一次 setup -> 之后只把链接发给 Agent -> Agent 自动调用 AIWiki 入库
+```
+
+AIWiki CLI 不负责网页抓取。Qclaw、Codex、Claude Code、Cursor、Gemini CLI 等都只是宿主 Agent 的例子；基础版面向的是通用宿主 Agent 协作。
+
+## 1. 一次性设置
+
+发布后直接运行交互式 setup：
+
+```bash
+npx @itradingai/aiwiki@latest setup
+```
+
+CLI 会询问知识库路径。直接回车会使用默认目录；输入 `y` 后会创建或补齐目录，并设置为默认知识库。
+
+如果你想一行命令完成，也可以运行：
+
+```bash
+npx @itradingai/aiwiki@latest setup --path "F:\knowledge_data\aiwiki" --yes
+```
+
+本地仓库测试时：
+
+```bash
+cd "<AIWiki 仓库路径>"
+npm install
+npm run build
+npm link
+aiwiki setup --path "F:\knowledge_data\aiwiki-test" --yes
+```
+
+验证：
+
+```bash
+aiwiki doctor
+aiwiki status
+```
+
+`setup` 会做两件事：
+
+- 创建或补齐知识库目录。
+- 写入默认知识库配置到用户目录，例如 `%USERPROFILE%\.aiwiki\config.json`。
+
+之后大多数命令都可以省略 `--path`。
+
+## 2. 让宿主 Agent 学会 AIWiki
+
+初始化知识库之后，先让宿主 Agent 学会 AIWiki。推荐先扫描本机支持的宿主 Agent：
+
+```bash
+aiwiki agent list
+```
+
+再启动安装向导：
+
+```bash
+aiwiki agent install
+```
+
+也可以跳过选择，直接指定目标：
+
+```bash
+aiwiki agent install --agent codex --yes
+aiwiki agent install --agent qclaw --yes
+aiwiki agent install --agent openclaw --yes
+aiwiki agent install --agent claude --yes
+```
+
+当前自动复制范围：
+
+- `codex`：复制到 Codex 用户 skills 目录。
+- `qclaw`：复制到 QClaw skills 目录。
+- `openclaw`：复制到 OpenClaw workspace skills 目录。
+- `claude`：复制为 Claude Code slash-command 提示文件。
+
+`opencode` 和 `hermes` 会被扫描出来，但基础版暂不自动写入它们的配置。确认官方用户提示/skill 目录后再开放自动安装。现在可先输出通用对接协议：
+
+```bash
+aiwiki prompt agent
+```
+
+把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以基础版提供自动安装向导和通用协议两条路径。
+
+## 3. 日常使用
+
+宿主 Agent 已经加载 AIWiki 协议后，把下面的话发给它，并替换链接：
+
+```text
+入库 https://example.com/article
+```
+
+宿主 Agent 应该自动完成：
+
+1. 读取网页正文。
+2. 生成 `aiwiki.agent_payload.v1`。
+3. 通过 stdin 调用 `aiwiki ingest-agent --stdin`。
+4. 把 AIWiki CLI 输出的入库结果摘要回复给用户。
+
+用户不需要保存 JSON，不需要手动运行 `ingest-agent`，也不需要每次输入知识库路径。
+
+## 4. 宿主 Agent 端应回复什么
+
+AIWiki CLI 会输出 key-value 信息。成功入库时类似：
+
+```text
+ingested: yes
+recorded: yes
+fetch_status: ok
+fit_score: 90
+fit_level: high
+source_title: 文章标题
+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
+processing_summary: 09-runs/20260507-153012-abc123/processing-summary.md
+source_card: 03-sources/article-cards/article-slug.md
+draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md
+dashboard: dashboards/AIWiki Home.md
+review_queue: dashboards/Review Queue.md
+warnings: 0
+```
+
+宿主 Agent 回复用户时建议展示：
+
+```text
+已加入 Obsidian 审阅队列。
+契合度：90 / high
+摘要：……
+资料卡：……
+处理记录：……
+Obsidian 入口：dashboards/AIWiki Home.md
+待审队列：dashboards/Review Queue.md
+```
+
+网页读取失败但已记录原因时类似：
+
+```text
+ingested: no
+recorded: yes
+fetch_status: failed
+fit_score: 0
+fit_level: fetch_failed
+summary: 网页需要登录或宿主 Agent 无法访问正文。
+run_id: 20260507-153012-abc123-fetch-failed
+run_dir: F:\knowledge_data\aiwiki\09-runs\20260507-153012-abc123-fetch-failed
+files: 2
+processing_summary: 09-runs/20260507-153012-abc123-fetch-failed/processing-summary.md
+dashboard: dashboards/AIWiki Home.md
+review_queue: dashboards/Review Queue.md
+warnings: 0
+```
+
+宿主 Agent 回复用户时建议展示：
+
+```text
+未成功入库正文，但已记录失败原因。
+原因：……
+记录目录：……
+处理记录：……
+Obsidian 入口：dashboards/AIWiki Home.md
+```
+
+## 5. 成功后会生成什么
+
+每次 run 会写入：
+
+```text
+09-runs/<run-id>/payload.json
+09-runs/<run-id>/raw.md
+09-runs/<run-id>/source-card.md
+09-runs/<run-id>/creative-assets.md
+09-runs/<run-id>/topics.md
+09-runs/<run-id>/draft-outline.md
+09-runs/<run-id>/processing-summary.md
+```
+
+同时写入长期目录：
+
+```text
+02-raw/articles/
+03-sources/article-cards/
+04-claims/_suggestions/
+06-assets/_suggestions/
+07-topics/ready/
+08-outputs/outlines/
+```
+
+Obsidian 主要审阅长期目录；`09-runs` 用于追溯每次处理。
+
+### Obsidian 链接规则
+
+AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会使用 wikilink：
+
+```text
+[[03-sources/article-cards/article-slug|资料卡]]
+[[02-raw/articles/article-slug|原文]]
+[[09-runs/20260507-153012-abc123/processing-summary|处理记录]]
+```
+
+链接规则：
+- wikilink 使用 vault 相对路径，统一为 `/`，并去掉 `.md` 后缀。
+- `03-sources/article-cards` 是主要审阅入口，会链接到原文、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 做筛选。
+
+### Obsidian 数据库入口
+
+`setup` 会创建或补齐 Obsidian 数据库资产：
+
+```text
+dashboards/AIWiki Home.md
+dashboards/Review Queue.md
+dashboards/Recent Runs.md
+dashboards/Topic Pipeline.md
+_system/schemas/aiwiki-frontmatter.md
+_system/templates/source-card.md
+_system/templates/review-note.md
+```
+
+这些文件只在缺失时创建；如果你已经在 Obsidian 中改过 dashboard 或模板，重新运行 `aiwiki setup` 不会覆盖。
+
+不安装 Dataview 也可以使用：
+- 用 `dashboards/AIWiki Home.md` 作为入口。
+- 用 Obsidian Properties 查看字段。
+- 用 Backlinks / Graph View 查看资料卡和原文、Claim、素材、选题、大纲之间的关系。
+
+安装 Dataview 后，dashboard 中的 `dataview` 代码块会渲染成表格，用来查看最近入库、待审队列、选题管线和处理记录。
+
+Dataview 是可选增强，不是 AIWiki 的必需依赖。AIWiki 不会自动修改 `.obsidian` 或安装社区插件；需要时请在 Obsidian 的 Community plugins 中自行安装并启用 Dataview。
+
+## 6. Agent 对接协议
+
+给任意宿主 Agent 的详细协议见：
+
+```text
+docs/AGENT_HANDOFF.md
+```
+
+核心要求：
+
+- Agent 负责读取网页正文。
+- Agent 不要让用户保存 payload。
+- Agent 不要让用户手动运行 `ingest-agent`。
+- Agent 生成 payload 后优先通过 stdin 调用 `aiwiki ingest-agent --stdin`。
+- Agent 最后只向用户汇报入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+
+## 7. 高级调试
+
+如果 Agent 只能输出 JSON，才需要手动保存 payload：
+
+```bash
+aiwiki ingest-agent --payload "F:\knowledge_data\payload.json"
+```
+
+也可以用 stdin：
+
+```bash
+type "F:\knowledge_data\payload.json" | aiwiki ingest-agent --stdin
+```
+
+本地 Markdown 文件：
+
+```bash
+aiwiki ingest-file --file "F:\knowledge_data\article.md"
+```
+
+链接加正文文件：
+
+```bash
+aiwiki ingest-url "https://example.com/article" --content-file "F:\knowledge_data\article.md"
+```
+
+注意：`ingest-url` 不会抓网页，只会读取 `--content-file`。
+
+## 8. 常见问题
+
+### 找不到 `aiwiki` 命令
+
+本地仓库测试时重新执行：
+
+```bash
+cd "<AIWiki 仓库路径>"
+npm run build
+npm link
+```
+
+### `doctor` 提示没有默认知识库
+
+运行：
+
+```bash
+aiwiki setup --path "F:\knowledge_data\aiwiki" --yes
+```
+
+### 宿主 Agent 抓不到网页
+
+这是宿主 Agent 的网页读取问题，不是 AIWiki CLI 的问题。让宿主 Agent 生成 `fetch_status=failed` 的 payload，AIWiki 会记录失败原因。
+
+### 想换默认知识库目录
+
+重新运行：
+
+```bash
+aiwiki setup --path "新的知识库路径" --yes
+```
+
+## 9. 最小验收清单
+
+完成一次 Agent 入库测试后，检查：
+
+```bash
+aiwiki status
+```
+
+验收标准：
+
+- `run_count` 增加。
+- `09-runs` 下出现新目录。
+- `processing-summary.md` 存在。
+- 成功读取时，`03-sources/article-cards` 下出现资料卡。
+- 抓取失败时，`09-runs/<run-id>-fetch-failed` 下出现失败记录。

package/docs/architecture.svg

@@ -0,0 +1,103 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="820" viewBox="0 0 1280 820" role="img" aria-labelledby="title desc">
+  <title id="title">AIWiki Base Architecture</title>
+  <desc id="desc">AIWiki base edition architecture showing setup, host Agent installation, ingestion, CLI processing, and local knowledge base outputs.</desc>
+  <defs>
+    <style>
+      .bg { fill: #fbfaf7; }
+      .band { fill: #fff7ed; stroke: #d9a36a; stroke-width: 2; }
+      .panel { fill: #ffffff; stroke: #b9c2cc; stroke-width: 1.5; }
+      .core { fill: #eef6ff; stroke: #4e85bd; stroke-width: 2; }
+      .agent { fill: #f2fbf5; stroke: #4c9a67; stroke-width: 2; }
+      .store { fill: #fff4f0; stroke: #c8755a; stroke-width: 2; }
+      .note { fill: #f7f7f7; stroke: #c5c5c5; stroke-width: 1.2; }
+      .title { font: 700 30px Arial, "Microsoft YaHei", sans-serif; fill: #25313d; }
+      .h2 { font: 700 18px Arial, "Microsoft YaHei", sans-serif; fill: #25313d; }
+      .text { font: 15px Arial, "Microsoft YaHei", sans-serif; fill: #334155; }
+      .small { font: 13px Arial, "Microsoft YaHei", sans-serif; fill: #52606d; }
+      .mono { font: 14px Consolas, "SFMono-Regular", monospace; fill: #243b53; }
+      .arrow { stroke: #536471; stroke-width: 2.2; fill: none; marker-end: url(#arrow); }
+      .dash { stroke-dasharray: 7 6; }
+      .chip { fill: #eef2f7; stroke: #c9d2dd; }
+    </style>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L0,6 L8,3 z" fill="#536471"/>
+    </marker>
+  </defs>
+
+  <rect class="bg" x="0" y="0" width="1280" height="820"/>
+  <text class="title" x="54" y="58">AIWiki 基础版架构图</text>
+  <text class="small" x="56" y="86">目标：宿主 Agent 负责读取与理解，AIWiki CLI 负责校验与本地确定性写入。</text>
+
+  <rect class="band" x="48" y="118" width="1184" height="118" rx="8"/>
+  <text class="h2" x="72" y="153">1. 一次性初始化与 Agent 安装</text>
+  <rect class="chip" x="72" y="174" width="172" height="34" rx="6"/>
+  <text class="mono" x="91" y="197">aiwiki setup</text>
+  <rect class="chip" x="292" y="174" width="172" height="34" rx="6"/>
+  <text class="mono" x="315" y="197">agent list</text>
+  <rect class="chip" x="512" y="174" width="212" height="34" rx="6"/>
+  <text class="mono" x="533" y="197">agent install</text>
+  <rect class="chip" x="772" y="174" width="210" height="34" rx="6"/>
+  <text class="mono" x="794" y="197">prompt agent</text>
+  <text class="small" x="1014" y="187">不自动乱写未知 Agent；</text>
+  <text class="small" x="1014" y="207">用户选择后才复制。</text>
+  <path class="arrow" d="M244 191 H292"/>
+  <path class="arrow" d="M464 191 H512"/>
+  <path class="arrow" d="M724 191 H772"/>
+
+  <rect class="panel" x="58" y="280" width="264" height="330" rx="8"/>
+  <text class="h2" x="84" y="318">用户 / 安装向导</text>
+  <text class="text" x="84" y="356">选择宿主 Agent：</text>
+  <text class="small" x="104" y="386">Codex</text>
+  <text class="small" x="104" y="414">QClaw / OpenClaw</text>
+  <text class="small" x="104" y="442">Claude Code</text>
+  <text class="small" x="104" y="470">opencode / Hermes</text>
+  <rect class="note" x="84" y="505" width="206" height="72" rx="6"/>
+  <text class="small" x="101" y="532">未知目录只给 prompt，</text>
+  <text class="small" x="101" y="555">不直接改配置。</text>
+
+  <rect class="agent" x="382" y="280" width="330" height="330" rx="8"/>
+  <text class="h2" x="414" y="318">宿主 Agent 层</text>
+  <text class="text" x="414" y="356">已加载 AIWiki skill / prompt</text>
+  <text class="small" x="434" y="386">读取 URL / 文件 / 正文</text>
+  <text class="small" x="434" y="414">提取标题、正文、来源信息</text>
+  <text class="small" x="434" y="442">生成 agent payload v1</text>
+  <text class="small" x="434" y="470">调用 stdin 交给 CLI</text>
+  <rect class="note" x="414" y="505" width="260" height="72" rx="6"/>
+  <text class="mono" x="434" y="533">aiwiki ingest-agent</text>
+  <text class="mono" x="434" y="555">  --stdin</text>
+
+  <rect class="core" x="772" y="280" width="210" height="330" rx="8"/>
+  <text class="h2" x="812" y="318">AIWiki CLI</text>
+  <text class="small" x="806" y="356">校验 payload</text>
+  <text class="small" x="806" y="386">拒绝越界路径</text>
+  <text class="small" x="806" y="416">生成 run_id</text>
+  <text class="small" x="806" y="446">写入运行产物</text>
+  <text class="small" x="806" y="476">写入长期目录</text>
+  <text class="small" x="806" y="506">输出 key-value 结果</text>
+
+  <rect class="store" x="1042" y="280" width="190" height="330" rx="8"/>
+  <text class="h2" x="1082" y="318">本地知识库</text>
+  <text class="mono" x="1064" y="356">aiwiki.yaml</text>
+  <text class="mono" x="1064" y="386">09-runs/</text>
+  <text class="mono" x="1064" y="416">02-raw/</text>
+  <text class="mono" x="1064" y="446">03-sources/</text>
+  <text class="mono" x="1064" y="476">04-claims/</text>
+  <text class="mono" x="1064" y="506">07-topics/</text>
+  <text class="mono" x="1064" y="536">08-outputs/</text>
+
+  <path class="arrow" d="M322 445 H382"/>
+  <path class="arrow" d="M712 445 H772"/>
+  <path class="arrow" d="M982 445 H1042"/>
+  <path class="arrow dash" d="M876 610 C876 688 544 688 544 610"/>
+  <text class="small" x="602" y="712">CLI 输出入库状态、契合度、摘要、run_dir，由宿主 Agent 回复用户</text>
+
+  <rect class="panel" x="58" y="650" width="452" height="102" rx="8"/>
+  <text class="h2" x="84" y="684">安装目标</text>
+  <text class="small" x="84" y="714">自动复制：Codex、QClaw、OpenClaw、Claude Code</text>
+  <text class="small" x="84" y="738">仅提示协议：opencode、Hermes（目录规范确认后再开放）</text>
+
+  <rect class="panel" x="772" y="650" width="460" height="102" rx="8"/>
+  <text class="h2" x="798" y="684">边界</text>
+  <text class="small" x="798" y="714">基础版不抓网页、不做多知识库、不做状态机、不做批量队列。</text>
+  <text class="small" x="798" y="738">所有写入必须限制在目标知识库根目录内。</text>
+</svg>