@itradingai/aiwiki 0.2.7 → 0.2.8

package/README.md

@@ -1,4 +1,4 @@
-![AIWiki 宣传图](docs/assets/aiwiki-hero.png)
+![AIWiki 宣传图](https://raw.githubusercontent.com/iTradingAI/aiwiki/refs/heads/main/docs/assets/aiwiki-hero.png)
 
 # AIWiki
 
@@ -14,7 +14,32 @@ AIWiki 的重点不是替代 Agent 抓网页，而是把 Agent 已经读到的
 - `2026-05-07`：新增 Codex skill 安装能力，并补上 Agent 协议安装引导，让宿主 Agent 在正式入库前更容易完成对接。
 - `2026-05-07`：持续打磨初始化体验，修复 setup 提示问题，避免静默套用默认值，并把首次使用流程改成交互式引导。
 
-## 安装与初始化
+## 直接发给 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 --path "我的知识库路径" --yes`，帮我完成知识库初始化。
+4. 执行 `aiwiki agent list` 检查当前环境支持哪些宿主 Agent。
+5. 优先为当前 AI/Agent 安装 AIWiki 对接；如果能自动安装，就执行 `aiwiki agent install` 或对应的 `--agent` 命令。
+6. 如果当前 Agent 不支持自动安装，就执行 `aiwiki prompt agent`，然后把生成的对接协议整理好，告诉我应该粘贴到哪里。
+7. 完成后，再执行 `aiwiki doctor` 和 `aiwiki status`，确认安装和配置是否正常。
+8. 最后告诉我：
+   - 实际执行了哪些命令
+   - 知识库路径是什么
+   - Agent 对接是否完成
+   - 如果还差手动步骤，明确告诉我下一步怎么做
+```
+
+
+## 手动安装与初始化
 
 一次性运行交互式 setup：
 
@@ -30,7 +55,7 @@ CLI 会询问知识库路径。直接回车会使用默认目录，确认后会
 npx @itradingai/aiwiki@latest setup --path "F:\knowledge_data\aiwiki" --yes
 ```
 
-如果希望长期使用全局命令：
+如果希望**长期使用**全局命令：
 
 ```bash
 npm install -g @itradingai/aiwiki@latest
@@ -45,34 +70,6 @@ npm install -g @itradingai/aiwiki@latest
 
 要求 Node.js `>=20`。
 
-## 直接发给 AI 帮你安装
-
-如果你希望让 Codex、Claude Code、QClaw、OpenClaw 等 AI 直接帮你完成安装和配置，可以把下面这段话原样发给它，注意修改下你的知识库路径：
-
-```text
-请帮我安装并配置 AIWiki。
-
-要求：
-1. 先检查本机 Node.js 是否满足 >=20。
-2. 如果还没安装 AIWiki，就安装最新版 `@itradingai/aiwiki`。
-3. 执行 `aiwiki setup`，帮我完成知识库初始化；把知识库路径设为 `F:\knowledge_data\aiwiki`。
-4. 执行 `aiwiki agent list` 检查当前环境支持哪些宿主 Agent。
-5. 优先为当前 AI/Agent 安装 AIWiki 对接；如果能自动安装，就执行 `aiwiki agent install` 或对应的 `--agent` 命令。
-6. 如果当前 Agent 不支持自动安装，就执行 `aiwiki prompt agent`，然后把生成的对接协议整理好，告诉我应该粘贴到哪里。
-7. 完成后，再执行 `aiwiki doctor` 和 `aiwiki status`，确认安装和配置是否正常。
-8. 最后告诉我：
-   - 实际执行了哪些命令
-   - 知识库路径是什么
-   - Agent 对接是否完成
-   - 如果还差手动步骤，明确告诉我下一步怎么做
-```
-
-如果你已经确定知识库路径，也可以把上面第 3 步改成直接执行：
-
-```bash
-aiwiki setup --path "F:\knowledge_data\aiwiki" --yes
-```
-
 ## 让宿主 Agent 学会 AIWiki
 
 初始化知识库后，先扫描本机支持的宿主 Agent：
@@ -109,7 +106,7 @@ aiwiki prompt 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`。
@@ -176,6 +173,7 @@ aiwiki ingest-url <url> --content-file <file>
 - 使用说明：[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/RELEASE.md](docs/RELEASE.md)
 - 架构图：[docs/architecture.svg](docs/architecture.svg)
 
 ## 联系与交流
@@ -185,12 +183,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>

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");
@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "type": "module",
   "description": "Agent-first local knowledge production CLI for a single knowledge base.",
   "license": "MIT",
@@ -22,7 +22,8 @@
   "files": [
     "dist/src",
     "README.md",
-    "docs",
+    "docs/*.md",
+    "docs/architecture.svg",
     "skill"
   ],
   "bin": {
@@ -32,6 +33,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