@itradingai/aiwiki 0.2.20 → 0.2.22

package/docs/USAGE.zh-CN.md

@@ -0,0 +1,243 @@
+# AIWiki 使用指南
+
+AIWiki 的主路径是让 AI 助手来使用。
+
+目标体验很简单：
+
+```text
+只设置一次
+  -> 以后把链接、文件、笔记发给 AI 助手
+  -> 助手调用 AIWiki
+  -> AIWiki 写入可复用的本地 Markdown 知识库
+```
+
+AIWiki 不抓网页，也不调用 LLM。宿主 AI 助手负责读取和理解资料；AIWiki 负责校验、写入、链接、查询和检查本地知识库。
+
+## 1. 让 AI 助手安装 AIWiki
+
+复制这段给你的 AI 助手：
+
+```text
+请帮我安装并配置 AIWiki。
+
+请先检查 Node.js 是否已安装，并确认 node --version >=20。
+如果没有安装 Node.js，或版本低于 20，请先停止，并告诉我如何升级，不要继续运行 npm install。
+
+我的知识库路径是：
+
+<替换成我的 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,86 @@
 
 This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
 
+## 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.20",
+  "version": "0.2.22",
   "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",

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.19 -->
+<!-- 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
@@ -34,15 +36,42 @@ aiwiki agent sync --json --yes
 aiwiki agent check --json
 ```
 
+For a project or vault workspace, also sync root guidance so future Agents see the command contract before they inspect files:
+
+```bash
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
 Sync behavior:
 
 - missing installed skill: install the packaged AIWiki skill
 - current installed skill: leave unchanged
 - different installed skill: backup the old file, then overwrite with the packaged skill
+- workspace `AGENTS.md`: append or refresh the marker-bounded AIWiki block without removing user instructions
 - unsupported host: do not write; use `aiwiki prompt agent` as a manual fallback
 
 After sync, tell the user the target path, any backup path, and that the target Agent may need to restart or reload before the new skill is active. Never edit Agent config during `npm install`; sync is the explicit safe step.
 
+## Required Command-First Loop
+
+When the user asks you to organize, inspect, ingest, query, reuse, or maintain an AIWiki workspace, run the AIWiki command surface before generic file search or ad hoc note edits:
+
+```bash
+aiwiki setup --path <workspace> --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+aiwiki lint --json --path <workspace>
+aiwiki lint --fix-empty-dirs --json --path <workspace>
+aiwiki ingest-file --file <file> --path <workspace>
+aiwiki ingest-agent --stdin --path <workspace>
+aiwiki status --path <workspace>
+aiwiki query <topic> --path <workspace>
+aiwiki context <topic> --path <workspace>
+```
+
+Use fallback shell/file search only after the relevant AIWiki command has been tried or when the command is unavailable. If you fall back, explain which AIWiki command was insufficient and why. If you skip the AIWiki commands entirely, the knowledge-base features are not being exercised.
+
 ## Knowledge Base Purpose
 
 Before ingesting, querying, linting, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace when it exists. Treat it as the local contract for:
@@ -57,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`.