@itradingai/aiwiki 0.2.21 → 0.2.23

package/docs/USAGE.zh-CN.md

@@ -0,0 +1,247 @@
+# AIWiki 使用指南
+
+AIWiki 的主路径是让 AI 助手来使用。
+
+目标体验很简单：
+
+```text
+只设置一次
+  -> 以后把链接、文件、笔记发给 AI 助手
+  -> 助手调用 AIWiki
+  -> AIWiki 写入可复用的本地 Markdown 知识库
+```
+
+AIWiki 不抓网页，也不调用 LLM。宿主 AI 助手负责读取和理解资料；AIWiki 负责校验、写入、链接、查询和检查本地知识库。
+
+## 1. 让 AI 助手安装 AIWiki
+
+复制这段给你的 AI 助手：
+
+发送前，请把所有 `<替换成我的 AIWiki 知识库路径>` 替换成你自己的本地文件夹路径，例如 `D:\AIWiki` 或 `~/AIWiki`。不要把这个占位符原样留在命令里。
+
+```text
+请帮我安装并配置 AIWiki。
+
+请先检查 Node.js 是否已安装，并确认 node --version >=20。
+如果没有安装 Node.js，或版本低于 20，请先停止，并告诉我如何升级，不要继续运行 npm install。
+
+我的知识库路径是：
+
+<替换成我的 AIWiki 知识库路径>
+
+运行命令前，请把下面所有 `<替换成我的 AIWiki 知识库路径>` 替换成我的真实本地文件夹路径。如果我没有替换，占位符仍然原样存在，请停止并向我询问真实路径。
+
+请运行这些命令：
+
+npm install -g @itradingai/aiwiki@latest
+aiwiki setup --path "<替换成我的 AIWiki 知识库路径>" --yes
+aiwiki agent sync --yes
+aiwiki agent sync --path "<替换成我的 AIWiki 知识库路径>" --yes
+aiwiki agent check --json
+aiwiki agent check --path "<替换成我的 AIWiki 知识库路径>" --json
+aiwiki doctor --path "<替换成我的 AIWiki 知识库路径>"
+aiwiki status --path "<替换成我的 AIWiki 知识库路径>"
+
+最后总结安装是否成功、同步了哪些助手目标、知识库根指导是否存在，以及我是否需要重启或重新加载助手。
+```
+
+知识库路径示例：
+
+```text
+Windows: D:\AIWiki
+macOS/Linux: ~/AIWiki
+项目内测试: ./aiwiki-test
+```
+
+这会创建或修复知识库，同步 AIWiki skill，并在知识库根目录写入 `AGENTS.md` 指导。
+
+安装成功后应该看到：
+
+- `aiwiki --version` 可以正常输出
+- `aiwiki doctor --path <workspace>` 通过，或给出明确可处理的问题
+- `aiwiki agent check --json` 报告支持的助手目标为 `installed`、`updated` 或 `current`
+- `aiwiki agent check --path <workspace> --json` 报告知识库根指导是 current
+- `aiwiki status --path <workspace>` 返回知识库状态和下一步动作
+
+## 2. Agent 同步的两层含义
+
+```bash
+aiwiki agent sync --yes
+```
+
+同步到本机支持的 AI 助手环境，例如 Codex、Claude Code、QClaw、OpenClaw。
+
+```bash
+aiwiki agent sync --path <workspace> --yes
+```
+
+在知识库根目录写入带标记的指导，让以后进入这个目录的 Agent 先使用 AIWiki 命令，而不是直接翻文件。
+
+验证两层同步：
+
+```bash
+aiwiki agent check --json
+aiwiki agent check --path <workspace> --json
+```
+
+不支持自动写入的宿主，可以输出通用协议：
+
+```bash
+aiwiki prompt agent
+```
+
+## 3. 入库资料
+
+对 AI 助手说：
+
+```text
+把这个资料入库到 AIWiki：
+https://example.com/article
+```
+
+助手应该：
+
+1. 读取资料
+2. 生成 `aiwiki.agent_payload.v1`
+3. 能理解时尽量提供 `analysis` 或 `wiki_entry`
+4. 调用 `aiwiki ingest-agent --stdin`
+5. 汇报 Wiki Entry、Source Card 和 Processing Summary
+
+本地文件可以调用：
+
+```bash
+aiwiki ingest-file --file <file>
+```
+
+如果网页读取失败，助手也应该记录 `fetch_status: "failed"`，让这次尝试可追踪。
+
+## 4. 从知识库提问
+
+对 AI 助手说：
+
+```text
+AIWiki 里关于 <主题> 有什么？
+```
+
+助手应该调用：
+
+```bash
+aiwiki context "<主题>"
+```
+
+`context` 返回给助手使用的 JSON，包含查询范围、结果质量、匹配原因、质量信号和相关引用。
+
+人在终端里看结果可以用：
+
+```bash
+aiwiki query "<主题>"
+```
+
+## 5. 检查和维护知识库
+
+对 AI 助手说：
+
+```text
+帮我检查并整理 AIWiki 知识库。
+```
+
+助手应该先运行：
+
+```bash
+aiwiki lint --json
+```
+
+如果只有安全修复，并且你允许整理：
+
+```bash
+aiwiki lint --fix-empty-dirs --json
+aiwiki lint --json
+```
+
+当前自动安全修复只包括：删除已知且为空的可选增强目录。AIWiki 不应把核心目录、未知目录、非空目录或文件当成 safe fix 删除。
+
+## 6. 生成的文件
+
+核心产物：
+
+```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/
+03-sources/article-cards/
+05-wiki/source-knowledge/
+```
+
+可选产物只在助手提供对应内容或明确请求时出现：
+
+```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/
+```
+
+Wiki Entry 有两种质量模式：
+
+- `agent_enriched` / `enriched`：助手提供了分析或 Wiki 内容。
+- `deterministic_fallback` / `scaffold`：AIWiki 只根据来源内容生成可追踪脚手架。
+
+## 7. Obsidian 和 Dataview
+
+AIWiki 写的是普通 Markdown 和 frontmatter。
+
+Obsidian 可选，Dataview 也可选。AIWiki 不修改 `.obsidian`，不安装插件，也不依赖 Dataview 查询知识库。
+
+`aiwiki setup` 会在缺失时创建 dashboard 和 schema 文件，并保留用户已经编辑过的文件。
+
+## 8. 常见排障
+
+### 找不到 `aiwiki`
+
+让助手重新安装：
+
+```bash
+npm install -g @itradingai/aiwiki@latest
+aiwiki --version
+```
+
+### 助手还是直接翻文件
+
+运行：
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+必要时重启或重新加载助手。
+
+助手应该先使用 `aiwiki lint`、`aiwiki status`、`aiwiki query`、`aiwiki context`、`aiwiki ingest-file` 或 `aiwiki ingest-agent`，再考虑通用文件搜索。
+
+### 助手读不到网页
+
+这是宿主助手访问网页的问题，不是 AIWiki 爬虫失败。让助手记录 failed fetch payload，保留可追踪记录。
+
+## 9. 本地开发
+
+```bash
+npm install
+npm run build
+npm test
+npm link
+```
+
+用临时知识库测试：
+
+```bash
+aiwiki setup --path "./aiwiki-test" --yes
+aiwiki doctor --path "./aiwiki-test"
+aiwiki status --path "./aiwiki-test"
+```

package/docs/development-log.md

@@ -2,6 +2,151 @@
 
 This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
 
+## 2026-06-11 - Repository trust and README P0/P1 polish
+
+Status: implemented and locally verified. Demo GIF recording is intentionally deferred until the P0/P1 documentation and repository trust pass is complete.
+
+### Goal
+
+Close the high-priority public-facing issues identified after the README rewrite:
+
+- keep GitHub About, npm metadata, and README positioning aligned;
+- make README shorter and push detailed procedures into docs;
+- document security and privacy boundaries;
+- add CI coverage for build, test, and package inspection;
+- make Agent sync failure reporting easier;
+- keep WeChat community entry visible without overwhelming the README.
+
+### Implemented
+
+- Compressed the English and Chinese README quick-start flows around the assistant-driven install prompt.
+- Moved detailed first-use, lint, and trial-route guidance toward the usage guides.
+- Added Agent sync failure issue guidance with `agent check` and `doctor` evidence.
+- Added Security and Privacy and Current Status sections in both README files.
+- Refined practical scenarios around research, reusable ideas, assistant context, and traceability.
+- Reduced community QR display size while keeping the WeChat group and official account visible.
+- Clarified that `<replace-with-my-aiwiki-path>` and `<替换成我的 AIWiki 知识库路径>` are placeholders users must replace with their own local folder path before running commands.
+- Added `.github/workflows/ci.yml` to run build, tests, and `npm pack --dry-run` on Node 20, 22, and 24.
+- Fixed the npm test runner command so CI does not depend on shell glob expansion or newer Node test-runner glob behavior.
+
+### Verification
+
+- Local README/doc link check: passed, `broken links: 0`.
+- `npm run release:check`: passed, 61 tests.
+- `npm pack --dry-run --json`: passed for `@itradingai/aiwiki@0.2.22`, 90 files, package size approximately 106 kB.
+- Pack inspection confirmed `docs/assets`, `aiwiki-hero`, `aiwiki-logo`, `join-group`, and `wechat-official-account` are still excluded from the npm tarball.
+- GitHub About description was updated to match npm/README positioning.
+- Initial CI run exposed Node 20 incompatibility in the quoted test glob; the test helper was added, and the follow-up GitHub Actions CI run passed on Node 20, 22, and 24.
+
+## 2026-06-11 - README hero and logo asset refresh
+
+Status: implemented and locally verified. This pass targets GitHub raw image delivery only; no npm publication.
+
+### Goal
+
+Replace the older README hero visual with gpt-image-2 generated brand assets that better match the current AIWiki positioning:
+
+- golden angular AIWiki logo with a four-point star in the center;
+- clear source inputs: Web link, PDF, and Notes;
+- assistant-driven reading and understanding;
+- AIWiki writing structured Markdown;
+- local Markdown knowledge vault and later `aiwiki context` retrieval;
+- separate English and Chinese README hero images.
+
+### Implemented
+
+- Replaced `docs/assets/aiwiki-hero.png` with the English gpt-image-2 generated hero.
+- Added `docs/assets/aiwiki-hero.zh-CN.png` as the Chinese gpt-image-2 generated hero.
+- Added `docs/assets/aiwiki-logo.png` cropped from the gpt-image-2 generated English hero for future brand reuse.
+- Updated `README.zh-CN.md` to use the Chinese raw GitHub hero URL: `docs/assets/aiwiki-hero.zh-CN.png`.
+- Kept README images out of the npm package; README files reference GitHub raw URLs instead.
+
+### Verification
+
+- Local README/doc link check: passed, `broken links: 0`.
+- `npm run release:check`: passed, 61 tests.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.22`; confirmed `docs/assets`, `aiwiki-hero`, `aiwiki-logo`, `join-group`, and `wechat-official-account` were not included in the npm tarball.
+
+## 2026-06-11 - Public trial path and feedback loop
+
+Status: implemented and locally verified. Pre-delivery remote tarball smoke, GitHub push, Trusted Publishing, registry verification, and post-publish remote sanity are required before queue completion.
+
+Version target: `@itradingai/aiwiki@0.2.22`
+
+### Goal
+
+Make the public trial path concrete enough that a first-time user can complete one useful AIWiki loop without learning the whole product first.
+
+The scoped acceptance criteria were:
+
+- show a 10-minute path from setup to first ingest to query/context reuse;
+- explain what a successful first run should generate;
+- cover installation, first ingest, doctor/lint, query/context, and feedback questions in public docs;
+- give host Agents a small first-use handoff path;
+- provide a minimal feedback template without adding a CLI command;
+- keep the base product boundary: no crawler, WeChat reader, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, browser plugin, Pro-only command, or multi-KB workflow.
+
+### Implemented
+
+- Added an explicit 10-minute public trial path to the README, usage guide, and showcase.
+- Added first-run success checks for the run folder, Source Card, Wiki Entry, query/context match, and structured lint output.
+- Added `docs/TRIAL_FEEDBACK_TEMPLATE.md` for lightweight public-trial feedback.
+- Updated FAQ coverage for first trial, doctor/lint, query/context, and feedback.
+- Updated Agent handoff and packaged skill guidance so host Agents guide first-time users through one small loop before broad exploration.
+- Included the trial feedback template in the npm package file list.
+
+### Verification
+
+- `npm test`: passed, 61 tests.
+- `npm run release:check`: passed for `@itradingai/aiwiki@0.2.22`, including tests and `scripts/release-check.mjs`.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.22`, 90 files, package size approximately 105 kB. Exact tarball shasum is recorded in the queue evidence instead of this packaged log file to avoid a self-referential hash.
+- Pack inspection confirmed `docs/TRIAL_FEEDBACK_TEMPLATE.md` is included and `docs/assets/` images are still excluded from the npm tarball.
+
+## 2026-06-10 - README and documentation positioning rewrite
+
+Status: implemented and locally verified. Not pushed, published, or remote-server verified in this documentation-only pass.
+
+Version target: no version bump in this pass.
+
+### Goal
+
+Rebuild the public AIWiki documentation around a clearer user-facing position:
+
+- English README is the primary GitHub/npm entry.
+- Chinese documentation is split into dedicated `zh-CN` files.
+- The first-screen message is "AIWiki is a local Markdown knowledge base for AI assistants."
+- The main Quick Start asks users to let an AI assistant install and configure AIWiki.
+- Agent sync remains explicit through `aiwiki agent sync` and `aiwiki agent check`; npm install alone does not silently modify host assistant configuration.
+- The older split story of "manual install" followed by a separate host-Agent connection step is removed from the main README path.
+- Community QR codes remain visible in the README through raw GitHub asset links.
+
+### Implemented
+
+- Rewrote `README.md` as the English public README with hero image, language/docs/npm links, Quick Start assistant prompt, first-use workflow, boundaries, community, and documentation links.
+- Added `README.zh-CN.md` as the Chinese public README.
+- Rewrote English docs: `docs/README.md`, `docs/USAGE.md`, `docs/FAQ.md`, `docs/AGENT_HANDOFF.md`, `docs/SHOWCASE.md`, `docs/ROADMAP.md`, and `docs/RELEASE.md`.
+- Added matching Chinese docs: `docs/README.zh-CN.md`, `docs/USAGE.zh-CN.md`, `docs/FAQ.zh-CN.md`, `docs/AGENT_HANDOFF.zh-CN.md`, `docs/SHOWCASE.zh-CN.md`, `docs/ROADMAP.zh-CN.md`, and `docs/RELEASE.zh-CN.md`.
+- Updated `package.json` description and package file list so the bilingual documentation is included in the npm tarball.
+- Updated `skill/SKILL.md` to use the same product positioning while preserving the command-first AIWiki workflow.
+- Updated CLI tests so bundled Claude handoff installation is verified against the new English `docs/AGENT_HANDOFF.md` contract.
+
+### Verification
+
+- `npm test`: passed, 61 tests.
+- `npm run release:check`: passed, including tests and `scripts/release-check.mjs`.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.21`, 89 files, package size 100.0 kB, shasum `6973ed940edf8f4620b7a3e578ddf3ececa01f45`.
+- Public English docs scan: no Chinese characters found in `README.md`, the English docs, or `package.json`.
+- Deprecated onboarding scan: no `Manual Install`, old `npx ... setup` path, old "second step host Agent" wording, or old first-screen positioning found in the rewritten public docs.
+
+### Follow-up Optimization
+
+- Added npm, Node.js, and license badges to the public README files.
+- Added Node.js >=20 checks to the assistant-install prompts.
+- Added concrete knowledge base path examples for Windows, macOS/Linux, and project-local testing.
+- Added "expected result" sections so users know what a successful install should report.
+- Added practical scenario sections to make the README more readable for first-time users.
+- Added FAQ entries for Node.js version-related installation failures.
+
 ## 2026-06-08 - Base contract cleanup and safe optional directory pruning
 
 Status: implemented and locally verified, committed locally, blocked before GitHub push and npm publication. Test-server verification is now required before both GitHub push and npm publication.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "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.",
+  "description": "Local Markdown knowledge base for AI assistants. Save what your AI reads, ask it later, and keep everything local.",
   "license": "MIT",
   "keywords": [
     "aiwiki",
@@ -35,19 +35,28 @@
   "files": [
     "dist/src",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "docs/20260607-aiwiki-feature-pruning-plan.md",
     "docs/20260607-aiwiki-long-term-operating-roadmap.md",
     "docs/AGENT_HANDOFF.md",
+    "docs/AGENT_HANDOFF.zh-CN.md",
     "docs/FAQ.md",
+    "docs/FAQ.zh-CN.md",
     "docs/OBSIDIAN_DATAVIEW_PLAN.md",
     "docs/README.md",
+    "docs/README.zh-CN.md",
     "docs/RELEASE.md",
+    "docs/RELEASE.zh-CN.md",
     "docs/ROADMAP.md",
+    "docs/ROADMAP.zh-CN.md",
     "docs/SHOWCASE.md",
+    "docs/SHOWCASE.zh-CN.md",
+    "docs/TRIAL_FEEDBACK_TEMPLATE.md",
     "docs/USAGE.md",
+    "docs/USAGE.zh-CN.md",
     "docs/development-log.md",
     "docs/architecture.svg",
     "examples",
@@ -58,7 +67,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test \"dist/tests/*.test.js\"",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "check": "npm run test",
     "release:check": "npm test && node scripts/release-check.mjs",
     "prepack": "npm run build"

package/skill/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: aiwiki
-description: Agent-first AIWiki workflow for turning one URL/body into local Wiki knowledge files.
+description: Local Markdown knowledge base workflow for AI assistants.
 ---
 
-<!-- aiwiki-skill-version: 0.2.21 -->
+<!-- aiwiki-skill-version: 0.2.22 -->
 
 # AIWiki Skill
 
 Use this skill when the user asks an Agent to process one URL, article body, or local text file with the `aiwiki` keyword, or says phrases like `入库 <url>` / `收录 <url>` / `从 AIWiki 里了解 <topic>`.
 
+AIWiki is a local Markdown knowledge base for AI assistants. Save what the assistant reads, ask it later, and keep everything local.
+
 AIWiki CLI does not fetch webpages and does not call an LLM. The host Agent reads and understands the source; AIWiki validates, writes, links, tracks, queries, and lints local Markdown knowledge files.
 
 ## Agent-First Setup and Upgrade
@@ -84,6 +86,8 @@ If the material does not fit the purpose file, do not force it into the knowledg
 
 ## Ingest Flow
 
+For first-time public-trial users, keep the path small and concrete: setup the workspace, ingest one source, inspect the generated run summary / Source Card / Wiki Entry, retrieve with query or context, run lint/doctor, then capture feedback with `docs/TRIAL_FEEDBACK_TEMPLATE.md`. Do not invent a new CLI command for feedback.
+
 1. Read the URL, message, attachment, or user-provided body.
 2. Read `_system/purpose.md` and decide whether the material fits this knowledge base.
 3. Build an `aiwiki.agent_payload.v1` payload with `source` and `request`.