@itradingai/aiwiki 0.2.7 → 0.2.9

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to AIWiki
+
+谢谢你愿意帮 AIWiki 变好。
+
+这个仓库比较在意三件事：
+
+- 文档说人话
+- 命令可复现
+- 不破坏已有 CLI 行为
+
+## 先准备什么
+
+本地开发前，先确认：
+
+- Node.js `>=20`
+- `npm install`
+- `npm run build`
+- `npm test`
+
+## 提 issue 前最好给什么
+
+如果你来报 bug，最好把这些信息一起带上：
+
+- 操作系统
+- Node.js 版本
+- AIWiki 版本
+- 宿主 Agent
+- 复现步骤
+- 实际输出
+- 期望输出
+
+如果能贴 `aiwiki doctor` 和 `aiwiki status` 的输出就更好了。
+
+## 提 PR 时注意什么
+
+- 尽量小步改
+- 不要顺手改一堆无关内容
+- 不要破坏已有 CLI 输出
+- 新功能尽量补最小测试
+
+## 本地验证
+
+```bash
+npm run build
+npm test
+aiwiki doctor
+aiwiki status
+```
+
+如果你改的是文档，就至少确认链接、命令和文件名都还对。

package/README.md

@@ -1,61 +1,53 @@
-![AIWiki 宣传图](docs/assets/aiwiki-hero.png)
+![AIWiki 宣传图](https://raw.githubusercontent.com/iTradingAI/aiwiki/refs/heads/main/docs/assets/aiwiki-hero.png)
 
 # AIWiki
 
-AIWiki 是一个面向宿主 Agent 的本地知识库生产 CLI。用户把文章链接或正文发给 Codex、QClaw、OpenClaw、Claude Code 等 Agent，并使用“入库”触发词；宿主 Agent 负责读取网页或上下文，AIWiki 负责把内容写入本地知识库，并生成适合 Obsidian + Dataview 审阅的资料结构。
+AIWiki 是一个开源的 Agent-first AI 知识库 CLI。你把文章链接、网页正文或本地文本交给宿主 Agent，宿主 Agent 负责读取内容，AIWiki 负责把结果稳定写进本地知识库，并生成适合 Obsidian 审阅的资料卡、主题、大纲和处理记录。
 
-AIWiki 的重点不是替代 Agent 抓网页，而是把 Agent 已经读到的内容稳定沉淀为可追踪、可复盘、可继续写作的本地知识库。
+对外只有一个 AIWiki，公开页面不做软件分层。商业服务放在部署、陪跑和团队集成里，不放在软件版本层。
 
-## 最新动态
-
-- `2026-05-09`：完成 npm 公开发布准备，补齐发布前的 README 与交付信息，并让 CLI 版本号与 `package.json` / 发布包保持一致，便于安装、排查与版本确认。
-- `2026-05-08`：完成中文化体验收口，包括默认生成中文 prompt、中文状态输出、中文目标描述，以及 README 和使用文档的中文本地化。
-- `2026-05-08`：强化 Obsidian 工作流，把 Review Queue、Claims Review 等审阅队列提升为一等入口，方便在知识库里持续审阅和回看入库内容。
-- `2026-05-07`：新增 Codex skill 安装能力，并补上 Agent 协议安装引导，让宿主 Agent 在正式入库前更容易完成对接。
-- `2026-05-07`：持续打磨初始化体验，修复 setup 提示问题，避免静默套用默认值，并把首次使用流程改成交互式引导。
+## 它解决什么
 
-## 安装与初始化
+- 收藏了很多链接，但最后都散在聊天记录里
+- 想用 AI 总结内容，却很难继续写作或复用
+- 想做选题、资料卡和大纲，但每次都得重新整理
+- 想让 Agent 帮忙收资料，但缺一个稳定的本地入库出口
 
-一次性运行交互式 setup：
+## 它会生成什么
 
-```bash
-npx @itradingai/aiwiki@latest setup
-```
-
-CLI 会询问知识库路径。直接回车会使用默认目录，确认后会创建或补齐 AIWiki 目录，并写入默认知识库配置。
+- 原文记录
+- Source Card 资料卡
+- Claim 建议
+- 创意素材
+- 选题候选
+- 草稿大纲
+- 处理摘要
+- Obsidian 审阅入口
 
-自动化初始化可以使用：
+## 30 秒上手
 
 ```bash
-npx @itradingai/aiwiki@latest setup --path "F:\knowledge_data\aiwiki" --yes
-```
-
-如果希望长期使用全局命令：
-
-```bash
-npm install -g @itradingai/aiwiki@latest
-aiwiki setup
-```
-
-升级到最新版本：
-
-```bash
-npm install -g @itradingai/aiwiki@latest
+npx @itradingai/aiwiki@latest setup
+aiwiki agent list
+aiwiki agent install
+aiwiki prompt agent
 ```
 
-要求 Node.js `>=20`。
+然后把 `入库 <url>` 发给宿主 Agent。
 
 ## 直接发给 AI 帮你安装
 
-如果你希望让 Codex、Claude Code、QClaw、OpenClaw 等 AI 直接帮你完成安装和配置，可以把下面这段话原样发给它，注意修改下你的知识库路径：
+如果你希望让 Codex、Claude Code、QClaw、OpenClaw 等 AI 直接帮你完成安装和配置，可以把下面这段话原样发给它，记得改成你自己的知识库路径：
 
 ```text
 请帮我安装并配置 AIWiki。
+安装命令：npm install -g @itradingai/aiwiki@latest
+我的知识库路径：F:\knowledges
 
 要求：
 1. 先检查本机 Node.js 是否满足 >=20。
 2. 如果还没安装 AIWiki，就安装最新版 `@itradingai/aiwiki`。
-3. 执行 `aiwiki setup`，帮我完成知识库初始化；把知识库路径设为 `F:\knowledge_data\aiwiki`。
+3. 执行 `aiwiki setup --path "我的知识库路径" --yes`，帮我完成知识库初始化。
 4. 执行 `aiwiki agent list` 检查当前环境支持哪些宿主 Agent。
 5. 优先为当前 AI/Agent 安装 AIWiki 对接；如果能自动安装，就执行 `aiwiki agent install` 或对应的 `--agent` 命令。
 6. 如果当前 Agent 不支持自动安装，就执行 `aiwiki prompt agent`，然后把生成的对接协议整理好，告诉我应该粘贴到哪里。
@@ -67,15 +59,9 @@ npm install -g @itradingai/aiwiki@latest
    - 如果还差手动步骤，明确告诉我下一步怎么做
 ```
 
-如果你已经确定知识库路径，也可以把上面第 3 步改成直接执行：
-
-```bash
-aiwiki setup --path "F:\knowledge_data\aiwiki" --yes
-```
-
 ## 让宿主 Agent 学会 AIWiki
 
-初始化知识库后，先扫描本机支持的宿主 Agent：
+初始化知识库后，先扫一遍本机支持的宿主 Agent：
 
 ```bash
 aiwiki agent list
@@ -102,14 +88,14 @@ aiwiki agent install --agent claude --yes
 aiwiki prompt agent
 ```
 
-把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。
+把输出内容安装成宿主 Agent 的 skill，或者粘贴到宿主 Agent 的项目说明里。
 
-## 入库流程
+## 日常入库
 
 完成 setup 和 Agent 安装后，对宿主 Agent 发送：
 
 ```text
-入库 https://example.com/article
+入库 https://mp.weixin.qq.com/s/5i9UJdBOhCB2a1EVp0lVXQ
 ```
 
 宿主 Agent 读取网页后，通过 `aiwiki ingest-agent --stdin` 把结构化内容交给 AIWiki CLI。用户不需要手动保存 payload，也不需要每次输入 `--path`。
@@ -120,49 +106,21 @@ aiwiki prompt agent
 用户发送链接 -> 宿主 Agent 读取内容 -> Agent 调用 AIWiki -> AIWiki 写入本地知识库 -> Obsidian 审阅和沉淀
 ```
 
-## Obsidian 与 Dataview
+## 设计边界
 
-AIWiki 初始化时会创建面向 Obsidian 的目录、Dashboard、Dataview 查询和 frontmatter 约定。核心入口包括：
+AIWiki 不是通用网页抓取器。网页读取主要交给宿主 Agent，AIWiki 专注于把 Agent 已经读到的内容写成稳定、可追踪、可复用的本地知识资产。
 
-- `dashboards/AIWiki Home.md`
-- `dashboards/Review Queue.md`
-- `dashboards/Claims Review.md`
-- `_system/schemas/aiwiki-frontmatter.md`
+AIWiki 生成的 Markdown 和 frontmatter 默认面向 Obsidian + Dataview 审阅；如果你不装 Dataview，普通 Markdown、Properties、Backlinks、Search 和 Graph View 也能用。
 
-完整方案见：[docs/OBSIDIAN_DATAVIEW_PLAN.md](docs/OBSIDIAN_DATAVIEW_PLAN.md)。
+当前范围：
 
-## 常用命令
-
-```bash
-aiwiki setup
-aiwiki setup --path <path> --yes
-aiwiki agent list
-aiwiki agent install
-aiwiki prompt agent
-aiwiki doctor
-aiwiki status
-aiwiki ingest-agent --stdin
-aiwiki ingest-file --file <file>
-```
-
-高级/调试命令：
-
-```bash
-aiwiki init --path <path> --yes --set-default
-aiwiki config show
-aiwiki ingest-agent --payload <file>
-aiwiki ingest-url <url> --content-file <file>
-```
-
-## 当前范围
-
-- 单知识库
+- 只写入当前配置的知识库
 - 单次处理一条输入
 - 宿主 Agent 读取网页、附件或正文
 - CLI 写入本地文件和 Obsidian 友好的结构
 - 生成资料卡、素材建议、主题候选、草稿大纲、处理摘要
 
-## 当前不包含
+当前不包含：
 
 - CLI 内置通用网页抓取
 - 跨主题自动路由
@@ -171,12 +129,32 @@ aiwiki ingest-url <url> --content-file <file>
 - 长流程状态机
 - 技术支持流程
 
+## 示例展示
+
+想先看一次完整跑完会生成什么，可以看：
+
+- [docs/SHOWCASE.md](docs/SHOWCASE.md)
+
 ## 文档
 
-- 使用说明：[docs/USAGE.md](docs/USAGE.md)
-- Agent 对接协议：[docs/AGENT_HANDOFF.md](docs/AGENT_HANDOFF.md)
-- Obsidian + Dataview 方案：[docs/OBSIDIAN_DATAVIEW_PLAN.md](docs/OBSIDIAN_DATAVIEW_PLAN.md)
-- 架构图：[docs/architecture.svg](docs/architecture.svg)
+- [docs/USAGE.md](docs/USAGE.md)
+- [docs/AGENT_HANDOFF.md](docs/AGENT_HANDOFF.md)
+- [docs/OBSIDIAN_DATAVIEW_PLAN.md](docs/OBSIDIAN_DATAVIEW_PLAN.md)
+- [docs/FAQ.md](docs/FAQ.md)
+- [docs/ROADMAP.md](docs/ROADMAP.md)
+- [docs/RELEASE.md](docs/RELEASE.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [docs/architecture.svg](docs/architecture.svg)
+
+## 参与与反馈
+
+如果你想提 bug、提需求，或者反馈宿主 Agent 对接问题，直接看：
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [.github/ISSUE_TEMPLATE/bug_report.md](.github/ISSUE_TEMPLATE/bug_report.md)
+- [.github/ISSUE_TEMPLATE/feature_request.md](.github/ISSUE_TEMPLATE/feature_request.md)
+- [.github/ISSUE_TEMPLATE/agent_integration.md](.github/ISSUE_TEMPLATE/agent_integration.md)
 
 ## 联系与交流
 
@@ -185,12 +163,12 @@ aiwiki ingest-url <url> --content-file <file>
 <table>
   <tr>
     <td align="center" width="50%">
-      <img src="docs/assets/join-group.png" alt="扫码进群交流" width="360">
+      <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/refs/heads/main/docs/assets/join-group.png" alt="扫码进群交流" width="360">
       <br>
       <strong>扫码进群</strong>
     </td>
     <td align="center" width="50%">
-      <img src="docs/assets/wechat-official-account.png" alt="扫码关注公众号" width="360">
+      <img src="https://raw.githubusercontent.com/iTradingAI/aiwiki/refs/heads/main/docs/assets/wechat-official-account.png" alt="扫码关注公众号" width="360">
       <br>
       <strong>关注公众号</strong>
     </td>
@@ -208,6 +186,15 @@ aiwiki prompt agent
 aiwiki doctor
 ```
 
+## 最新动态
+
+- `2026-05-12`：公开前口径收口，统一 README、npm 元数据和公开文档入口。
+- `2026-05-09`：完成 npm 公开发布准备，补齐发布前的 README 与交付信息，并让 CLI 版本号与 `package.json` / 发布包保持一致，便于安装、排查与版本确认。
+- `2026-05-08`：完成中文化体验收口，包括默认生成中文 prompt、中文状态输出、中文目标描述，以及 README 和使用文档的中文本地化。
+- `2026-05-08`：强化 Obsidian 工作流，把 Review Queue、Claims Review 等审阅队列提升为一等入口，方便在知识库里持续审阅和回看入库内容。
+- `2026-05-07`：新增 Codex skill 安装能力，并补上 Agent 协议安装引导，让宿主 Agent 在正式入库前更容易完成对接。
+- `2026-05-07`：持续打磨初始化体验，修复 setup 提示问题，避免静默套用默认值，并把首次使用流程改成交互式引导。
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+AIWiki 是一个本地 CLI 工具。它会按用户指定的路径写入 Markdown、JSON 和配置文件。
+
+## 安全边界
+
+AIWiki 不会：
+
+- 主动上传用户本地知识库内容
+- 绕过登录墙或付费墙
+- 自动修改 `.obsidian` 插件配置
+- 自动安装 Dataview
+- 扫描未指定的个人目录
+
+## 建议
+
+- 只在你信任的环境里运行 AIWiki
+- 首次使用时最好指定一个新的测试知识库目录
+- 遇到异常写入行为时，先停下来检查 payload 和目标路径
+
+## 报告问题
+
+如果你发现疑似安全问题，请优先提交 issue，并尽量附上：
+
+- 运行命令
+- 目标路径
+- `aiwiki doctor` 输出
+- `aiwiki status` 输出
+- 能稳定复现的最小示例
+
+如果问题涉及本地数据泄露、越权写入或路径逃逸，请尽量把细节说清楚，方便快速复核。

package/dist/src/app.js

@@ -7,13 +7,12 @@ import { flagBool, flagString, parseArgs } from "./args.js";
 import { ingestFile, ingestPayload } from "./ingest.js";
 import { CliError, writeLine } from "./output.js";
 import { confirmInit, directorySummary, doctor, exists, initWorkspace, promptForSetup, promptForInitPath, readConfig, resolveWorkspace, setDefaultWorkspace, statusSummary } from "./workspace.js";
-export const VERSION = "0.2.7";
 export async function runCli(argv, streams = { stdout: process.stdout, stderr: process.stderr }) {
     try {
         const args = parseArgs(argv);
         const [command, subcommand] = args.positional;
         if (args.flags.has("version") || command === "version" || command === "-v") {
-            writeLine(streams.stdout, `aiwiki ${VERSION}`);
+            writeLine(streams.stdout, `aiwiki ${await packageVersion()}`);
             return 0;
         }
         if (args.flags.has("help") || !command || command === "help" || command === "-h") {
@@ -415,3 +414,12 @@ function parseJson(text) {
         throw new CliError("payload must be valid JSON");
     }
 }
+async function packageVersion() {
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const text = await fs.readFile(path.join(packageRoot, "package.json"), "utf8");
+    const parsed = JSON.parse(text);
+    if (typeof parsed.version !== "string") {
+        throw new CliError("package.json is missing version");
+    }
+    return parsed.version;
+}

package/dist/src/encoding.js

@@ -0,0 +1,76 @@
+export function repairMojibake(value) {
+    if (!value || !looksLikeUtf8Mojibake(value)) {
+        return { value, repaired: false };
+    }
+    const repaired = decodeUtf8BytesFromLatin1(value) ?? decodeUtf8BytesFromCp1252(value);
+    if (!repaired || scoreText(repaired) <= scoreText(value)) {
+        return { value, repaired: false };
+    }
+    return { value: repaired, repaired: true };
+}
+function looksLikeUtf8Mojibake(value) {
+    return /(?:Ã|Â|â€|“|”|’|å|ç|è|é|ä|æ|ï¼|ã€)/.test(value);
+}
+function decodeUtf8BytesFromLatin1(value) {
+    try {
+        return Buffer.from(value, "latin1").toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeUtf8BytesFromCp1252(value) {
+    const bytes = [];
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (code === undefined) {
+            continue;
+        }
+        const mapped = cp1252ReverseMap.get(code);
+        if (mapped !== undefined) {
+            bytes.push(mapped);
+        }
+        else if (code <= 0xff) {
+            bytes.push(code);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
+function scoreText(value) {
+    const cjk = [...value].filter((char) => /[\u4e00-\u9fff]/u.test(char)).length;
+    const mojibake = (value.match(/(?:Ã|Â|â€|“|”|’|å|ç|è|é|ä|æ|ï¼|ã€)/g) ?? []).length;
+    const replacement = (value.match(/\uFFFD/g) ?? []).length;
+    return cjk * 4 - mojibake * 20 - replacement * 50;
+}
+const cp1252ReverseMap = new Map([
+    [0x20ac, 0x80],
+    [0x201a, 0x82],
+    [0x0192, 0x83],
+    [0x201e, 0x84],
+    [0x2026, 0x85],
+    [0x2020, 0x86],
+    [0x2021, 0x87],
+    [0x02c6, 0x88],
+    [0x2030, 0x89],
+    [0x0160, 0x8a],
+    [0x2039, 0x8b],
+    [0x0152, 0x8c],
+    [0x017d, 0x8e],
+    [0x2018, 0x91],
+    [0x2019, 0x92],
+    [0x201c, 0x93],
+    [0x201d, 0x94],
+    [0x2022, 0x95],
+    [0x2013, 0x96],
+    [0x2014, 0x97],
+    [0x02dc, 0x98],
+    [0x2122, 0x99],
+    [0x0161, 0x9a],
+    [0x203a, 0x9b],
+    [0x0153, 0x9c],
+    [0x017e, 0x9e],
+    [0x0178, 0x9f]
+]);

package/dist/src/payload.js

@@ -1,3 +1,4 @@
+import { repairMojibake } from "./encoding.js";
 export function normalizePayload(raw, runStartedAt) {
     if (!isRecord(raw)) {
         throw new Error("payload must be a JSON object");
@@ -40,10 +41,10 @@ export function normalizePayload(raw, runStartedAt) {
         : ["source_card", "creative_assets", "topics", "draft_outline", "processing_summary"];
     const outputs = ["source_card", "creative_assets", "topics", "draft_outline", "processing_summary"];
     if (fetchStatus !== "failed" && requestedOutputs.length && requestedOutputs.length !== outputs.length) {
-        warnings.push("基础版会生成完整单条资料产物，request.outputs 已按全量输出处理。");
+        warnings.push("AIWiki 会为每条输入生成完整资料产物，request.outputs 已按全量输出处理。");
     }
     if (typeof raw.target_kb === "string" && raw.target_kb.trim()) {
-        warnings.push(`target_kb=${raw.target_kb} 已被单知识库流程忽略。`);
+        warnings.push(`target_kb=${raw.target_kb} 已被当前知识库流程忽略。`);
     }
     if (contentRepair.repaired) {
         warnings.push("source.content 检测到疑似 UTF-8 mojibake，已自动修复。");
@@ -105,79 +106,3 @@ function stringValue(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function repairMojibake(value) {
-    if (!value || !looksLikeUtf8Mojibake(value)) {
-        return { value, repaired: false };
-    }
-    const repaired = decodeUtf8BytesFromLatin1(value) ?? decodeUtf8BytesFromCp1252(value);
-    if (!repaired || scoreText(repaired) <= scoreText(value)) {
-        return { value, repaired: false };
-    }
-    return { value: repaired, repaired: true };
-}
-function looksLikeUtf8Mojibake(value) {
-    return /(?:Ã|Â|â€|“|”|’|å|ç|è|é|ä|æ|ï¼|ã€)/.test(value);
-}
-function decodeUtf8BytesFromLatin1(value) {
-    try {
-        return Buffer.from(value, "latin1").toString("utf8");
-    }
-    catch {
-        return undefined;
-    }
-}
-function decodeUtf8BytesFromCp1252(value) {
-    const bytes = [];
-    for (const char of value) {
-        const code = char.codePointAt(0);
-        if (code === undefined) {
-            continue;
-        }
-        const mapped = cp1252ReverseMap.get(code);
-        if (mapped !== undefined) {
-            bytes.push(mapped);
-        }
-        else if (code <= 0xff) {
-            bytes.push(code);
-        }
-        else {
-            return undefined;
-        }
-    }
-    return Buffer.from(bytes).toString("utf8");
-}
-function scoreText(value) {
-    const cjk = [...value].filter((char) => /[\u4e00-\u9fff]/u.test(char)).length;
-    const mojibake = (value.match(/(?:Ã|Â|â€|“|”|’|å|ç|è|é|ä|æ|ï¼|ã€)/g) ?? []).length;
-    const replacement = (value.match(/\uFFFD/g) ?? []).length;
-    return cjk * 4 - mojibake * 20 - replacement * 50;
-}
-const cp1252ReverseMap = new Map([
-    [0x20ac, 0x80],
-    [0x201a, 0x82],
-    [0x0192, 0x83],
-    [0x201e, 0x84],
-    [0x2026, 0x85],
-    [0x2020, 0x86],
-    [0x2021, 0x87],
-    [0x02c6, 0x88],
-    [0x2030, 0x89],
-    [0x0160, 0x8a],
-    [0x2039, 0x8b],
-    [0x0152, 0x8c],
-    [0x017d, 0x8e],
-    [0x2018, 0x91],
-    [0x2019, 0x92],
-    [0x201c, 0x93],
-    [0x201d, 0x94],
-    [0x2022, 0x95],
-    [0x2013, 0x96],
-    [0x2014, 0x97],
-    [0x02dc, 0x98],
-    [0x2122, 0x99],
-    [0x0161, 0x9a],
-    [0x203a, 0x9b],
-    [0x0153, 0x9c],
-    [0x017e, 0x9e],
-    [0x0178, 0x9f]
-]);

package/docs/AGENT_HANDOFF.md

@@ -35,7 +35,19 @@ AIWiki CLI 不做通用网页抓取。网页读取失败时，Agent 仍然要调
 aiwiki ingest-agent --stdin
 ```
 
-7. 读取 CLI 输出，向用户回复入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+7. 如果当前 shell、终端或宿主环境无法保证 stdin 是 UTF-8，先把 payload 写成 UTF-8 JSON 文件，再调用：
+
+```bash
+aiwiki ingest-agent --payload <utf8-json-file>
+```
+
+8. 读取 CLI 输出，向用户回复入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+
+## 编码要求
+
+payload 必须是 UTF-8 JSON。Windows PowerShell、批处理、第三方 Agent shell bridge 可能会把中文 JSON 管道按非 UTF-8 编码传递；遇到中文乱码、`payload must be valid JSON` 或无法确认管道编码时，使用 `--payload <utf8-json-file>`。
+
+AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应尽量传入干净 UTF-8。
 
 ## 成功 payload
 

package/docs/FAQ.md

@@ -0,0 +1,47 @@
+# AIWiki FAQ
+
+## AIWiki 是什么？
+
+AIWiki 是一个开源的 Agent-first AI 知识库 CLI。它把文章链接、网页正文和本地文本整理成本地知识资产，方便在 Obsidian 里继续审阅和写作。
+
+## AIWiki 是网页爬虫吗？
+
+不是。网页读取主要交给宿主 Agent，AIWiki 专注于校验结构化输入、写本地文件和生成审阅产物。
+
+## 一定要用 Obsidian 吗？
+
+不一定。AIWiki 生成的是标准 Markdown 和 frontmatter，Obsidian 只是最适合它的审阅界面之一。
+
+## 一定要装 Dataview 吗？
+
+不一定。没有 Dataview，也可以用 Obsidian 原生的 Properties、Backlinks、Search 和 Graph View。
+
+## 宿主 Agent 和 AIWiki 各负责什么？
+
+- 宿主 Agent 负责读取网页、正文或附件，并组装 payload
+- AIWiki 负责校验 payload、写本地知识库、输出处理记录
+- 用户负责提供链接或正文，最后在 Obsidian 里审阅结果
+
+## 为什么要先让 Agent 学会 AIWiki？
+
+因为大多数用户不想每次手动跑命令。更顺的方式是：把链接发给宿主 Agent，Agent 自动把内容交给 AIWiki，AIWiki 再把结果写进本地知识库。
+
+## 我能不能把它当成一个通用爬虫用？
+
+不建议。AIWiki 的边界不是“抓全网”，而是“把宿主 Agent 已经读到的内容稳定沉淀下来”。
+
+## 我从哪里开始最好？
+
+先跑：
+
+```bash
+npx @itradingai/aiwiki@latest setup
+aiwiki agent list
+aiwiki agent install
+```
+
+然后去看：
+
+- [USAGE.md](USAGE.md)
+- [SHOWCASE.md](SHOWCASE.md)
+- [AGENT_HANDOFF.md](AGENT_HANDOFF.md)

package/docs/README.md

@@ -1,11 +1,14 @@
 # AIWiki Docs
 
-AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent 已经读取到的文章、网页正文或本地文本写入单知识库。
+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)
+- 示例展示：[SHOWCASE.md](SHOWCASE.md)
+- 常见问题：[FAQ.md](FAQ.md)
+- 路线图：[ROADMAP.md](ROADMAP.md)
 
 ## Quick Start
 

package/docs/RELEASE.md

@@ -0,0 +1,59 @@
+# AIWiki 发布检查
+
+发布前先确认本地工作区只包含本次发布需要的改动：
+
+```bash
+git status --short --branch
+npm run release:check
+```
+
+`release:check` 会执行测试、构建、`npm pack --dry-run`、CLI 版本一致性检查，以及一次临时知识库入库检查。
+
+## 版本号
+
+版本号以 `package.json` 为唯一来源。CLI 的 `aiwiki --version` 会运行时读取 `package.json`，不要在源码里另写一份版本常量。
+
+升级版本：
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+## npm 发布
+
+发布前确认 npm 登录账号：
+
+```bash
+npm whoami
+```
+
+正式发布：
+
+```bash
+npm publish --access public
+```
+
+如果账号开启了 publish 2FA，普通 token 可能只能 `whoami`，但发布时仍会要求 OTP。此时有两种方式：
+
+```bash
+npm publish --access public --otp <OTP>
+```
+
+或使用 npm Automation token 写入用户级 `.npmrc`：
+
+```bash
+npm config set //registry.npmjs.org/:_authToken "<NPM_AUTOMATION_TOKEN>"
+```
+
+发布后验证：
+
+```bash
+npm view @itradingai/aiwiki version
+npm view @itradingai/aiwiki versions --json
+```
+
+## 包体积
+
+npm 包只应包含 CLI 运行和用户文档所需文件。README 中的图片使用 GitHub raw 链接展示，`docs/assets/` 不进入 npm 包。
+
+如果 `npm pack --dry-run` 输出里出现 `docs/assets/`，说明包内容配置回退了，需要先修复 `package.json.files`。

package/docs/ROADMAP.md

@@ -0,0 +1,38 @@
+# AIWiki Roadmap
+
+AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版本分层。
+
+## 1. 更稳的入库体验
+
+- 更顺的 setup 引导
+- 更清晰的 doctor 检查
+- 更稳定的 Agent handoff
+- 更完整的 Obsidian 审阅入口
+- 更容易追查失败原因
+
+## 2. 更完整的内容处理能力
+
+- 更好用的资料卡
+- 更清楚的 Claim / Evidence 建议
+- 更顺手的选题候选
+- 更稳定的大纲生成
+- 更好复用的模板和输出结构
+
+## 3. 更适合团队和自动化部署
+
+- 更多宿主 Agent 接入方式
+- 更适合团队协作的知识库目录
+- 更完善的部署说明
+- 更清楚的诊断和支持入口
+- 更好的服务化落地方式
+
+## 4. 服务层能力
+
+公开软件还是 AIWiki 本身。后续如果要做商业化，重点会放在：
+
+- 部署服务
+- 陪跑服务
+- 团队集成服务
+- 技术支持服务
+
+这些都属于服务层，不是把 AIWiki 拆成多个软件版本。

package/docs/SHOWCASE.md

@@ -0,0 +1,78 @@
+# AIWiki 示例展示
+
+这页不是讲概念，直接看一次完整跑通会发生什么。
+
+## 示例 1：一篇文章进知识库
+
+### 用户输入
+
+```text
+入库 https://example.com/article
+```
+
+### 宿主 Agent 做的事
+
+1. 读取网页正文或可访问内容。
+2. 组装 `aiwiki.agent_payload.v1`。
+3. 调用 `aiwiki ingest-agent --stdin`。
+4. 把 AIWiki 的处理结果回复给用户。
+
+### AIWiki 会写什么
+
+```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/
+dashboards/
+```
+
+### 用户在 Obsidian 里怎么看
+
+- 打开 `dashboards/AIWiki Home.md`
+- 查看 `dashboards/Review Queue.md`
+- 从资料卡回到原文、选题、大纲和处理记录
+
+## 示例 2：网页没读到正文
+
+有些页面需要登录，或者宿主 Agent 暂时拿不到正文。这个时候 AIWiki 也不会装死，它会把失败原因记录下来。
+
+### 用户输入
+
+```text
+入库 https://example.com/locked-page
+```
+
+### 结果
+
+```text
+09-runs/<run-id>/payload.json
+09-runs/<run-id>/processing-summary.md
+```
+
+### 你会看到什么
+
+- 失败原因会写进 `processing-summary.md`
+- 用户仍然能在 Obsidian 里看到这次处理记录
+- 下次只要宿主 Agent 能读到正文，就可以重新入库
+
+## 这个示例页想说明什么
+
+- AIWiki 不是网页爬虫本体
+- 宿主 Agent 负责读取内容
+- AIWiki 负责稳定写入本地知识库
+- 结果始终可追踪、可复盘、可继续写作

package/docs/USAGE.md

@@ -6,7 +6,7 @@
 用户只做一次 setup -> 之后只把链接发给 Agent -> Agent 自动调用 AIWiki 入库
 ```
 
-AIWiki CLI 不负责网页抓取。Qclaw、Codex、Claude Code、Cursor、Gemini CLI 等都只是宿主 Agent 的例子；基础版面向的是通用宿主 Agent 协作。
+AIWiki CLI 不负责网页抓取。Qclaw、Codex、Claude Code、Cursor、Gemini CLI 等都只是宿主 Agent 的例子；这份文档面向的是通用宿主 Agent 协作。
 
 ## 1. 一次性设置
 
@@ -78,13 +78,13 @@ aiwiki agent install --agent claude --yes
 - `openclaw`：复制到 OpenClaw workspace skills 目录。
 - `claude`：复制为 Claude Code slash-command 提示文件。
 
-`opencode` 和 `hermes` 会被扫描出来，但基础版暂不自动写入它们的配置。确认官方用户提示/skill 目录后再开放自动安装。现在可先输出通用对接协议：
+`opencode` 和 `hermes` 会被扫描出来，但 AIWiki 暂不自动写入它们的配置。确认官方用户提示/skill 目录后再开放自动安装。现在可先输出通用对接协议：
 
 ```bash
 aiwiki prompt agent
 ```
 
-把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以基础版提供自动安装向导和通用协议两条路径。
+把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
 ## 3. 日常使用
 

package/docs/architecture.svg

@@ -1,6 +1,6 @@
 <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>
+  <title id="title">AIWiki Architecture</title>
+  <desc id="desc">AIWiki architecture showing setup, host Agent installation, ingestion, CLI processing, and local knowledge base outputs.</desc>
   <defs>
     <style>
       .bg { fill: #fbfaf7; }
@@ -25,7 +25,7 @@
   </defs>
 
   <rect class="bg" x="0" y="0" width="1280" height="820"/>
-  <text class="title" x="54" y="58">AIWiki 基础版架构图</text>
+  <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"/>
@@ -98,6 +98,6 @@
 
   <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="714">AIWiki 不抓网页、不做多知识库、不做状态机、不做批量队列。</text>
   <text class="small" x="798" y="738">所有写入必须限制在目标知识库根目录内。</text>
 </svg>

package/package.json

@@ -1,13 +1,26 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
-  "description": "Agent-first local knowledge production CLI for a single knowledge base.",
+  "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",
   "keywords": [
     "aiwiki",
-    "agent",
+    "ai-knowledge-base",
     "knowledge-base",
+    "knowledge-management",
+    "agent",
+    "ai-agent",
+    "agentic-workflow",
+    "llm-wiki",
+    "markdown",
+    "cli",
+    "codex",
+    "claude-code",
+    "openclaw",
+    "qclaw",
+    "content-workflow",
+    "writing-workflow",
     "obsidian",
     "dataview"
   ],
@@ -22,7 +35,11 @@
   "files": [
     "dist/src",
     "README.md",
-    "docs",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs/*.md",
+    "docs/architecture.svg",
     "skill"
   ],
   "bin": {
@@ -32,6 +49,7 @@
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test \"dist/tests/*.test.js\"",
     "check": "npm run test",
+    "release:check": "npm test && node scripts/release-check.mjs",
     "prepack": "npm run build"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -21,6 +21,12 @@ The host Agent reads the webpage or user-provided body, then passes structured c
 aiwiki ingest-agent --stdin
 ```
 
+If the current shell or Agent bridge cannot guarantee UTF-8 stdin, write the payload as a UTF-8 JSON file and call:
+
+```bash
+aiwiki ingest-agent --payload <utf8-json-file>
+```
+
 For local files, call:
 
 ```bash