@itradingai/aiwiki 0.2.20 → 0.2.22

package/docs/ROADMAP.zh-CN.md

@@ -0,0 +1,65 @@
+# AIWiki 路线图
+
+AIWiki 基础版只有一个公开产品定位：给 AI 助手使用的本地 Markdown 知识库。
+
+路线图会保持基础 CLI 聚焦。高级自动化、爬取、多知识库、向量检索和团队控制，不应混入基础版承诺，除非后续单独规划。
+
+## 当前重点
+
+### 1. 首次使用成功
+
+- 更清楚的 AI 助手安装提示词
+- 更安全的 `agent sync` 和知识库根指导
+- 更清楚的 `agent check` 诊断
+- 从 setup 到第一次入库、第一次查询的完整路径
+
+### 2. 本地知识复用
+
+- 更清楚的 Wiki Entry 质量信号
+- 更好解释 query/context 的结果
+- 更多写作、研究、决策、回顾场景案例
+- 更明确区分外部资料和用户个人输出
+
+### 3. 知识库健康
+
+- 给人和 AI 助手都能读懂的 lint 输出
+- 只在窄范围、可逆时提供自动安全修复
+- 更好的 status 和 doctor 引导
+- 新知识库减少空洞可选产物
+
+### 4. 公开试用资产
+
+- 5-10 分钟能完成的小任务
+- 与当前 CLI 行为一致的样例知识库
+- 微信群反馈模板
+- 区分用户痛点和功能蔓延的队列规则
+
+## 不进入基础版队列
+
+基础版 AIWiki 当前不规划：
+
+- 网页爬虫
+- 微信公众号读取
+- 浏览器插件
+- 向量检索
+- RAG-over-wiki
+- 多知识库
+- RBAC
+- RSS 或定时采集
+- 默认人工审核流程
+- 自动安装 Dataview 或 Obsidian 插件
+
+这些能力可以进入服务层、集成项目或 Pro 相邻项目，但不应模糊基础版 README 的承诺。
+
+## 运营原则
+
+AIWiki 应该在关键地方保持稳定朴素：
+
+```text
+助手负责阅读
+AIWiki 负责写入
+Markdown 保持本地
+上下文以后还能复用
+```
+
+产品进步的重点，是让第一次入库、第一次查询和第一次维护更可靠。

package/docs/SHOWCASE.md

@@ -1,25 +1,51 @@
-# AIWiki 示例展示
+# AIWiki Showcase
 
-这页不是讲概念，直接看一次完整跑通会发生什么。
+This page shows what a real AIWiki run creates.
 
-## 示例 1：一篇文章进知识库
+## 10-minute Trial Walkthrough
 
-### 用户输入
+This is the public-trial happy path:
 
 ```text
-入库 https://example.com/article
+1. Create a temporary knowledge base.
+2. Ingest one readable source.
+3. Inspect the generated run summary, Source Card, and Wiki Entry.
+4. Ask the knowledge base one question.
+5. Run lint/doctor for workspace health.
+6. Send feedback with the trial template.
 ```
 
-### 宿主 Agent 做的事
+Commands for a local-file trial:
 
-1. 读取网页正文或可访问内容。
-2. 组装 `aiwiki.agent_payload.v1`，并尽量提供 `analysis` 或 `wiki_entry`。
-3. 调用 `aiwiki ingest-agent --stdin`。
-4. 把 AIWiki 的处理结果回复给用户。
+```bash
+aiwiki setup --path ./aiwiki-trial --yes
+aiwiki doctor --path ./aiwiki-trial
+aiwiki ingest-file --file ./my-first-source.md --path ./aiwiki-trial
+aiwiki query "my topic" --path ./aiwiki-trial
+aiwiki context "my topic" --path ./aiwiki-trial
+aiwiki lint --json --path ./aiwiki-trial
+```
+
+For a URL trial, the assistant reads the URL first, then calls `aiwiki ingest-agent` with the content it read.
+
+## Scenario 1: Ingest an Article
+
+User message:
+
+```text
+Ingest this into AIWiki:
+https://example.com/article
+```
+
+Assistant work:
 
-### AIWiki 会写什么
+1. read the source
+2. create an `aiwiki.agent_payload.v1` payload
+3. provide `analysis` or `wiki_entry` when possible
+4. call `aiwiki ingest-agent --stdin`
+5. report the generated files
 
-核心产物优先看这些：
+Core output:
 
 ```text
 09-runs/<run-id>/payload.json
@@ -32,7 +58,7 @@
 05-wiki/source-knowledge/<slug>.md
 ```
 
-只有在宿主 Agent 提供了对应内容，或 payload 明确请求时，才会出现可选增强产物：
+Optional output appears only when the assistant provides matching content:
 
 ```text
 09-runs/<run-id>/creative-assets.md
@@ -44,50 +70,38 @@
 08-outputs/outlines/
 ```
 
-仓库里的 `examples/obsidian-vault-sample/` 同时包含一个普通本地文件入库和一个 enriched Agent payload 入库。前者只生成核心产物，后者因为包含 claims、topic candidates、creative assets 和 outline 请求，所以生成可选增强目录。
-
-### 用户在 Obsidian 里怎么看
-
-- 打开 `dashboards/AIWiki Home.md`
-- 查看 `05-wiki/source-knowledge/<slug>.md`
-- 从 Wiki 条目回到资料卡、原文和处理记录；如果这次入库生成了选题、大纲或 Claim，再继续查看对应可选产物
-- 需要结构检查时运行 `aiwiki lint`
+## Scenario 2: The Source Cannot Be Read
 
-## 示例 2：网页没读到正文
+Some pages require login or cannot be accessed by the assistant.
 
-有些页面需要登录，或者宿主 Agent 暂时拿不到正文。这个时候 AIWiki 也不会装死，它会把失败原因记录下来。
-
-### 用户输入
+AIWiki should still record the attempt:
 
 ```text
-入库 https://example.com/locked-page
+09-runs/<run-id>/payload.json
+09-runs/<run-id>/processing-summary.md
 ```
 
-### 结果
+The failure reason is preserved, and the user can retry later when the assistant can access the source.
+
+## Scenario 3: Reuse the Knowledge Later
+
+User message:
 
 ```text
-09-runs/<run-id>/payload.json
-09-runs/<run-id>/processing-summary.md
+What does AIWiki know about AI agents?
 ```
 
-### 你会看到什么
+Assistant command:
 
-- 失败原因会写进 `processing-summary.md`
-- 用户仍然能在 Obsidian 里看到这次处理记录
-- 下次只要宿主 Agent 能读到正文，就可以重新入库
-
-## 这个示例页想说明什么
+```bash
+aiwiki context "AI agents"
+```
 
-- AIWiki 不是网页爬虫本体
-- 宿主 Agent 负责读取内容
-- 宿主 Agent 负责高质量总结和知识提炼
-- AIWiki 负责稳定写入本地知识库
-- AIWiki 会创建 Wiki Entry；没有 Agent 分析字段时只生成可追溯脚手架
-- 结果始终可追踪、可复盘、可继续写作
+The assistant should use the returned JSON, including match reasons and quality signals, before answering.
 
-## 本仓库样例
+## Sample Files
 
-- `examples/demo-run/`：输入、命令和 CLI 输出。
-- `examples/obsidian-vault-sample/`：已经生成好的样例知识库。
+- [`../examples/demo-run/`](../examples/demo-run/) records input files, commands, and CLI outputs.
+- [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/) is a generated sample vault.
 
-这个样例不依赖爬虫、向量库、RAG 或 Pro 自动化；它只展示基础 CLI 的真实落盘结果。
+The sample does not rely on crawling, vector search, RAG-over-wiki, or Pro automation. It shows the real base CLI file contract.

package/docs/SHOWCASE.zh-CN.md

@@ -0,0 +1,81 @@
+# AIWiki 案例展示
+
+这页直接展示一次真实 AIWiki 运行会生成什么。
+
+## 场景 1：入库一篇文章
+
+用户说：
+
+```text
+把这个资料入库到 AIWiki：
+https://example.com/article
+```
+
+助手会：
+
+1. 读取资料
+2. 生成 `aiwiki.agent_payload.v1`
+3. 能理解时提供 `analysis` 或 `wiki_entry`
+4. 调用 `aiwiki ingest-agent --stdin`
+5. 汇报生成文件
+
+核心产物：
+
+```text
+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>/processing-summary.md
+02-raw/articles/<slug>.md
+03-sources/article-cards/<slug>.md
+05-wiki/source-knowledge/<slug>.md
+```
+
+可选产物只在助手提供对应内容时出现：
+
+```text
+09-runs/<run-id>/creative-assets.md
+09-runs/<run-id>/topics.md
+09-runs/<run-id>/draft-outline.md
+04-claims/_suggestions/
+06-assets/_suggestions/
+07-topics/ready/
+08-outputs/outlines/
+```
+
+## 场景 2：资料暂时读不到
+
+有些页面需要登录，或助手暂时无法访问正文。
+
+AIWiki 仍然应该记录这次尝试：
+
+```text
+09-runs/<run-id>/payload.json
+09-runs/<run-id>/processing-summary.md
+```
+
+失败原因会被保留，之后助手能读到正文时可以重新入库。
+
+## 场景 3：以后复用知识
+
+用户问：
+
+```text
+AIWiki 里关于 AI Agent 有什么？
+```
+
+助手应该调用：
+
+```bash
+aiwiki context "AI Agent"
+```
+
+助手回答前应读取返回 JSON 里的匹配原因和质量信号。
+
+## 样例文件
+
+- [`../examples/demo-run/`](../examples/demo-run/)：输入、命令和 CLI 输出。
+- [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/)：已经生成好的样例知识库。
+
+这个样例不依赖爬虫、向量检索、RAG-over-wiki 或 Pro 自动化，只展示基础 CLI 的真实落盘结果。

package/docs/TRIAL_FEEDBACK_TEMPLATE.md

@@ -0,0 +1,49 @@
+# AIWiki Trial Feedback Template
+
+Use this template after a first public trial. It is intentionally small so feedback can be pasted into a WeChat group, issue, note, or planning document without adding a new CLI command.
+
+## Basic Info
+
+- AIWiki version:
+- Operating system:
+- Assistant used:
+- Knowledge base path type: temporary / real workspace / project folder
+
+## First-use Result
+
+- Setup result: success / blocked / unclear
+- First source type: URL / local file / pasted note / failed fetch
+- Ingest result: success / failed / recorded failure only
+- Query/context result: useful / partially useful / not useful / no match
+- Lint/doctor result: clean / actionable warning / confusing warning / error
+
+## What Worked
+
+- The clearest step was:
+- The most useful generated file was:
+- One thing I can reuse later:
+
+## What Was Confusing
+
+- Installation or Node.js issue:
+- Assistant did not call AIWiki commands:
+- I could not find generated files:
+- Query/context answer was unclear:
+- Lint/doctor output was unclear:
+- Other:
+
+## One Practical Scenario
+
+I would use AIWiki for:
+
+```text
+Example: saving article research before writing a WeChat post.
+```
+
+## Next Action
+
+- Keep using as-is
+- Needs documentation improvement
+- Needs assistant guidance improvement
+- Needs CLI behavior improvement
+- Not a fit for my workflow