@itradingai/aiwiki 0.2.18 → 0.2.20

package/docs/20260607-aiwiki-long-term-operating-roadmap.md

@@ -0,0 +1,409 @@
+# AIWiki 长期运营路线图
+
+日期：2026-06-07
+状态：公开试用早期
+适用范围：AIWiki 基础版、AIWiki Pro、公开试用群、内容运营和每日自动化开发队列
+
+## 1. 北极星目标
+
+AIWiki 的长期目标不是做一个“功能很多的知识库工具”，而是成为 Agent 时代的本地知识资产后端：
+
+> 让用户和 Agent 能持续沉淀资料、判断、输出和上下文，并在后续工作中稳定查询、检查、引用和复用。
+
+这意味着 AIWiki 的长期运营重点不是“加更多命令”，而是持续提升三件事：
+
+- 第一次能不能顺利用起来。
+- 入库后的内容能不能被再次找到和复用。
+- 用户和 Agent 能不能判断这个知识库是否健康、可信、值得继续维护。
+
+## 2. 当前阶段判断
+
+项目已经公开，并有约 80 人试用群，但群内反馈很少。
+
+这不是坏信号，但说明当前还不能以“反馈驱动功能”为主。现在更应该进入 feedback-light operating mode：
+
+- 不等待大量反馈才行动。
+- 主动制造清晰试用路径和使用场景。
+- 用案例、教程和小任务引导用户产生反馈。
+- 把重复问题、沉默和卡点都视为信号。
+- 每周只挑少量高确定性问题进入开发队列。
+
+当前阶段的主要风险：
+
+- 用户看到了项目，但不知道第一步该做什么。
+- 用户装好了，但不知道应该入库什么内容。
+- 用户入库了，但没有体验到“复用知识”的价值。
+- 群里没人反馈，开发方向容易被想象中的高级功能带偏。
+- 基础版如果继续扩功能，会削弱传播和试用成功率。
+
+## 3. 产品分层目标
+
+### 3.1 基础版目标
+
+基础版长期定位：
+
+> 稳定、轻量、可信、Agent-first 的本地 Markdown 知识资产后端。
+
+基础版必须长期坚持：
+
+- 单知识库。
+- 用户命令为 `aiwiki`。
+- 不内置网页抓取。
+- 不内置 LLM。
+- 不做多知识库管理。
+- 不做重型 review / retain / FSRS。
+- 不做 RSS、定时采集、批量 URL 队列。
+- 不做 dashboard / doctor bundle。
+- 不为每个动作新增顶层命令。
+
+基础版应持续强化：
+
+- `setup`
+- `agent sync/check`
+- `ingest-agent`
+- `ingest-file`
+- `context/query`
+- `lint`
+- `status/doctor`
+- Agent-readable JSON 输出
+- 安全修复，如 `lint --fix-empty-dirs --json`
+
+### 3.2 Pro 目标
+
+Pro 长期定位：
+
+> 面向长期运行、自动化维护、团队协作和商业交付的知识运营层。
+
+Pro 承接：
+
+- 多知识库。
+- queue / collect / schedule。
+- dedupe / score / route / validate。
+- inbox / connector / collection jobs。
+- dashboard bundle。
+- doctor bundle。
+- 规模化 lint。
+- 团队部署和服务支持。
+
+Pro 的价值不是“命令更多”，而是让用户不用每天手工维护知识库健康状态。
+
+### 3.3 内容和服务层目标
+
+AIWiki 的增长不只来自 npm 包或 GitHub。
+
+长期运营应持续生产：
+
+- 使用案例。
+- 入门教程。
+- 真实工作流拆解。
+- 群内答疑复盘。
+- 版本进展说明。
+- 迁移和部署服务说明。
+- 团队试点方案。
+
+内容层的目标是降低理解成本；服务层的目标是承接复杂用户。
+
+## 4. 30 / 90 / 180 天目标
+
+### 4.1 30 天目标：试用成功率
+
+30 天内不追大功能，重点是让试用者真的跑通第一轮。
+
+目标：
+
+- 新用户 10 分钟内能理解 AIWiki 是什么、不是什幺。
+- 新用户能完成 `setup`。
+- 新用户能入库第一篇内容。
+- 新用户能用 `query` 或 `context` 找回内容。
+- 用户能用 `lint` / `doctor` 自查问题。
+- 默认目录不再让用户困惑。
+- 群里能沉淀至少 3 个真实使用案例。
+
+建议指标：
+
+- 首次 setup 成功数。
+- 首篇入库成功数。
+- 用户上传或描述的 AIWiki 目录截图数。
+- 群里重复询问的安装/目录/入库问题数量。
+- 用户是否能说出“AIWiki 帮我复用了什么”。
+- 真实案例数，而不是群消息数。
+
+### 4.2 90 天目标：复用价值验证
+
+90 天目标不是用户多，而是证明“知识复用”这件事成立。
+
+目标：
+
+- 形成 5 个可展示的标准场景。
+- `query/context` 能支撑真实写作、研究、决策或项目回顾。
+- lint 能帮助用户发现结构和证据边界问题。
+- Agent handoff 成为稳定入口。
+- Pro 是否值得推进有明确证据。
+
+建议标准场景：
+
+- 文章研究库。
+- 公众号选题库。
+- AI 工具调研库。
+- 项目决策库。
+- Agent 工作记忆库。
+
+### 4.3 180 天目标：运营闭环和商业试点
+
+180 天目标是形成稳定的运营和商业化入口。
+
+目标：
+
+- 基础版成为公开传播入口。
+- Pro 成为自动化维护和团队试点入口。
+- 每月至少 1 个完整案例复盘。
+- 有清晰的部署服务、陪跑服务或团队集成服务说明。
+- 形成基础版免费试用、Pro/服务承接复杂需求的路径。
+
+## 5. 低反馈阶段运营策略
+
+群里反馈少时，不要简单判断为没人需要。
+
+优先做四件事：
+
+### 5.1 主动设计试用任务
+
+每周在群里给一个非常小的任务：
+
+- 今天把一篇文章入库。
+- 今天跑一次 `aiwiki doctor`。
+- 今天用 `aiwiki query` 找一个旧观点。
+- 今天贴一张 AIWiki 目录截图。
+- 今天说一个“我想让 Agent 记住的东西”。
+
+任务要小到用户 5-10 分钟能完成。
+
+### 5.2 用沉默判断卡点
+
+如果某个任务没人回应，可能不是没人感兴趣，而是：
+
+- 不知道从哪里开始。
+- 安装卡住。
+- 不知道选什么内容入库。
+- 不知道成功结果长什么样。
+- 不敢贴自己的知识库截图。
+
+沉默要进入运营复盘，而不是被忽略。
+
+### 5.3 做标准案例，而不是等用户案例
+
+反馈少时，先主动做 3-5 个标准案例。
+
+每个案例必须包含：
+
+- 输入材料是什么。
+- Agent 做了什么。
+- AIWiki 生成了什么。
+- 后续如何用 `query/context` 复用。
+- 这个场景为什么值得长期维护。
+
+### 5.4 把支持问题产品化
+
+群里每一个问题都归类：
+
+- 安装失败。
+- 不知道怎么开始。
+- 入库结果不理解。
+- 目录结构困惑。
+- 查询找不到。
+- 想要高级功能。
+
+只有前三类优先进入基础版开发。高级功能先进入 backlog 或 Pro。
+
+## 6. 运营节奏
+
+### 每日
+
+- 自动化队列执行一个明确任务。
+- 若任务涉及发布，完成测试、打包、发布状态和远程验证。
+- 不因为 npm OTP 或外部发布阻塞停止本地开发队列，但必须记录 release follow-up。
+
+### 每周
+
+- 周一：整理群反馈和沉默信号。
+- 周二：发布一个 5-10 分钟试用任务。
+- 周三：从反馈中挑 1-3 个最高价值问题进入队列。
+- 周五：发布小版本进展或案例说明。
+
+### 每两周
+
+- 做一次公开试用复盘。
+- 更新 FAQ。
+- 更新 SHOWCASE 或新增案例。
+- 检查是否有功能请求应该进入 Pro。
+
+### 每月
+
+- 复盘 30/90/180 天目标进度。
+- 清理不值得做的功能。
+- 更新开发队列和看板。
+- 决定 Pro 的下一项是否恢复。
+
+## 7. 开发计划安排
+
+当前开发优先级：
+
+1. `AIWIKI-006`：基础版收敛。
+2. `AIWIKI-007`：样例、文档和全链路回归。
+3. `AIWIKI-008`：公开试用激活闭环。
+4. `AIWIKI-009`：案例和教程资产包。
+5. `AIWIKI-010`：复用价值验证和 query/context 场景优化。
+6. `AIWIKI-011`：运营复盘、指标和反馈队列机制。
+7. `PRO-008`：在基础版契约稳定后恢复 dashboard / doctor bundle。
+
+### AIWIKI-008：公开试用激活闭环
+
+目标：
+
+让新用户能完成第一次成功试用，并知道如何反馈。
+
+范围：
+
+- README quick start。
+- USAGE。
+- FAQ。
+- AGENT_HANDOFF。
+- SHOWCASE。
+- skill。
+- 群试用任务模板。
+
+验收：
+
+- 有一条 10 分钟试用路径。
+- 有“第一篇文章入库”教程。
+- 有“成功结果长什么样”的截图或文件说明。
+- 有最小反馈模板。
+- 不新增基础版命令。
+- 不引入 Pro-only 能力。
+
+### AIWIKI-009：案例和教程资产包
+
+目标：
+
+在反馈少的阶段主动制造可理解、可传播、可复用的案例。
+
+范围：
+
+- 至少 3 个标准案例。
+- 示例输入。
+- 生成结果说明。
+- query/context 复用演示。
+- 群内发布文案。
+
+验收：
+
+- 每个案例都能回答“为什么要长期维护这个知识库”。
+- 每个案例都不依赖 Pro。
+- 每个案例都能用基础版跑通。
+
+### AIWIKI-010：复用价值验证
+
+目标：
+
+验证 AIWiki 不是只会保存文件，而是能帮助用户复用判断和上下文。
+
+范围：
+
+- query/context 场景文档。
+- 写作、研究、决策、回顾四类查询任务。
+- 必要时补小型 CLI 输出优化。
+
+验收：
+
+- 用户能看到 source、insight、output 的差异。
+- query/context 能给出可解释的匹配理由。
+- 文档能指导 Agent 在写作或研究前先取上下文。
+
+### AIWIKI-011：运营复盘和反馈队列机制
+
+目标：
+
+把群反馈、沉默信号、案例和开发任务连接起来。
+
+范围：
+
+- 反馈分类模板。
+- 每周复盘模板。
+- 月度路线图复盘模板。
+- 开发任务进入标准。
+- 不值得做的功能清单维护。
+
+验收：
+
+- 每周能从群运营产出明确的任务判断。
+- 反馈不会直接变成功能。
+- Pro / 基础版边界能被持续维护。
+
+## 8. 任务进入开发队列的标准
+
+一个需求进入基础版开发队列前，必须满足至少两项：
+
+- 能提升首次试用成功率。
+- 能降低用户理解成本。
+- 能提升知识复用效果。
+- 能让 Agent 更稳定地自动处理。
+- 能减少重复支持问题。
+- 不扩大基础版边界。
+
+进入 Pro 队列的标准：
+
+- 涉及多知识库。
+- 涉及长期自动化运行。
+- 涉及队列、调度、评分、路由、采集。
+- 涉及团队部署。
+- 涉及 dashboard / doctor bundle。
+- 涉及商业交付和支持。
+
+不进入队列的情况：
+
+- 只是“看起来酷”。
+- 只是给已有流程换一个新命令名。
+- 需要基础版内置网页抓取或 LLM。
+- 会让新用户更难理解。
+- 没有明确验证方式。
+
+## 9. 长期运营指标
+
+早期不建议追求活跃群消息数。
+
+更适合的指标：
+
+- 首次成功：能否完成 setup 和第一篇入库。
+- 首次价值：用户是否完成一次 query/context 复用。
+- 复用案例：是否出现真实二次使用。
+- 支持成本：重复问题是否减少。
+- 文档有效性：用户能否按教程自行完成。
+- 边界稳定性：基础版是否持续避免功能膨胀。
+- Pro 线索：是否出现明确团队、自动化或长期维护需求。
+
+## 10. 停止条件
+
+长期运营要敢于不做。
+
+应该停止或暂缓的信号：
+
+- 群里没有人能完成基础试用，却开始做高级功能。
+- 同一个安装或入库问题重复出现，但开发队列在做 dashboard。
+- 用户还没理解 query/context，就开始做多知识库。
+- 新命令增加了，但成功案例没有增加。
+- Pro 功能在基础版契约未稳定前继续扩张。
+
+## 11. 当前建议
+
+短期最重要的是继续跑完 `AIWIKI-006` 和 `AIWIKI-007`。
+
+在它们完成前，不建议把主要精力切到 Pro 或高级功能。群反馈少时，更应该用案例和试用任务制造反馈，而不是用新功能赌反馈。
+
+`AIWIKI-007` 完成后，开发队列应该转向公开试用激活：
+
+- 让用户知道第一步做什么。
+- 让用户知道成功结果长什么样。
+- 让用户知道如何反馈。
+- 让用户看到知识复用的真实价值。
+
+这条路线比继续堆功能更适合长期运营。

package/docs/AGENT_HANDOFF.md

@@ -45,6 +45,7 @@ aiwiki ingest-agent --payload <utf8-json-file>
 ```
 
 9. 读取 CLI 输出，向用户回复入库状态、摘要、Wiki 条目、质量模式、资料卡和处理记录。
+10. 汇报产物时先说核心产物：Raw、Source Card、Wiki Entry、Run Summary、Processing Summary。Claim、Asset、Topic、Outline 只在本次 CLI 输出或文件中真实存在时再提。
 
 ## 编码要求
 
@@ -91,9 +92,6 @@ AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应
     "outputs": [
       "source_card",
       "wiki_entry",
-      "creative_assets",
-      "topics",
-      "draft_outline",
       "processing_summary"
     ],
     "language": "zh-CN"
@@ -193,15 +191,16 @@ aiwiki context "<主题>"
 aiwiki query "<主题>"
 ```
 
-当用户说“整理 / 检查知识库”时，调用：
+当用户说“整理 / 检查知识库”时，先调用 JSON 检查：
 
 ```bash
-aiwiki lint
+aiwiki lint --json
 ```
 
-需要机器读取时用：
+如果 `safe_fixes.only_safe_fixes` 为 `true`，且用户允许整理，可以应用内置安全修复并再次检查：
 
 ```bash
+aiwiki lint --fix-empty-dirs --json
 aiwiki lint --json
 ```
 
@@ -219,7 +218,7 @@ aiwiki lint --severity info
 aiwiki lint --no-write
 ```
 
-Lint 输出会包含摘要、最高优先级问题、分级报告，以及建议动作。把 `error` 当作必须先修的结构问题，把 `warning` 当作需要处理或复核的维护问题，把 `info` 当作富集、归档或后续整理 backlog。
+Lint 输出会包含摘要、`safe_fixes`、最高优先级问题、分级报告，以及建议动作。把 `error` 当作必须先修的结构问题，把 `warning` 当作需要处理或复核的维护问题，把 `info` 当作富集、归档或后续整理 backlog。当前唯一可自动应用的 safe fix 是 `remove_empty_optional_dir`，只会删除已知且为空的可选增强目录；不要删除核心目录、未知目录、非空目录或文件。
 
 `context` 返回 JSON，注意其中的 `generation_mode`、`quality` 和 `warnings`。如果结果是 `deterministic_fallback` / `scaffold`，回复时要说明它只是可追溯脚手架，不是高质量知识提炼。
 

package/docs/FAQ.md

@@ -53,8 +53,8 @@ AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。宿主 Agent 负责
 
 ```bash
 npx @itradingai/aiwiki@latest setup
-aiwiki agent list
-aiwiki agent install
+aiwiki agent sync --yes
+aiwiki agent check --json
 ```
 
 然后去看：
@@ -63,6 +63,10 @@ aiwiki agent install
 - [SHOWCASE.md](SHOWCASE.md)
 - [AGENT_HANDOFF.md](AGENT_HANDOFF.md)
 
+## 有没有可以直接看的样例？
+
+有。`examples/demo-run/` 记录输入、命令和 CLI 输出；`examples/obsidian-vault-sample/` 是已经生成好的样例知识库。它展示了核心产物优先，以及可选增强目录只在有内容时出现。
+
 ## 怎么从知识库里查询？
 
 让宿主 Agent 调用：
@@ -78,3 +82,5 @@ aiwiki context "主题"
 ```bash
 aiwiki lint
 ```
+
+如果只是清理旧版本留下的空可选增强目录，可以让 Agent 先运行 `aiwiki lint --json`，确认只有 safe fix 后再运行 `aiwiki lint --fix-empty-dirs --json`。

package/docs/README.md

@@ -11,17 +11,21 @@ AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent
 - 路线图：[ROADMAP.md](ROADMAP.md)
 - 开发记录：[development-log.md](development-log.md)
 
+## Examples
+
+- `../examples/demo-run/` records the input files, commands, and CLI outputs from a regenerated demo.
+- `../examples/obsidian-vault-sample/` is a sample vault showing the current core-first artifact contract.
+
 ## Quick Start
 
 ```bash
 npx @itradingai/aiwiki@latest setup
-aiwiki agent list
-aiwiki agent install
-aiwiki prompt agent
+aiwiki agent sync --yes
+aiwiki agent check --json
 aiwiki doctor
 ```
 
-优先运行 `aiwiki agent install`，让 CLI 扫描本机 Codex、QClaw、OpenClaw、Claude Code 等宿主 Agent 并安装到所选目标。其他宿主 Agent 可使用 `aiwiki prompt agent` 输出通用协议，再安装成 skill 或粘贴到项目/会话说明里。之后把链接发给宿主 Agent：
+优先运行 `aiwiki agent sync --yes`，让 CLI 幂等同步本机 Codex、QClaw、OpenClaw、Claude Code 等宿主 Agent 对接文件。其他宿主 Agent 可使用 `aiwiki prompt agent` 输出通用协议，再安装成 skill 或粘贴到项目/会话说明里。之后把链接发给宿主 Agent：
 
 ```text
 入库 https://example.com/article

package/docs/RELEASE.md

@@ -21,28 +21,21 @@ npm version patch --no-git-tag-version
 
 ## npm 发布
 
-发布前确认 npm 登录账号：
+发布前必须先让同一个本地 tarball 在测试服务器通过 smoke test。顺序是：本地验证、版本号、提交、本地 `npm pack`、测试服务器安装 tarball 并跑 CLI smoke，然后才能 `git push` 和 `npm publish`。
 
-```bash
-npm whoami
-```
+AIWiki 使用 npm Trusted Publishing。npm 发布应由 GitHub Actions 的 `.github/workflows/publish.yml` 完成，不依赖本机 `npm login`、OTP 或长期 `NPM_TOKEN`。
 
-正式发布：
+远程测试和 GitHub push 都通过后，触发发布 workflow：
 
 ```bash
-npm publish --access public
+gh workflow run publish.yml --repo iTradingAI/aiwiki
+gh run watch --repo iTradingAI/aiwiki
 ```
 
-如果账号开启了 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>"
+gh run list --workflow publish.yml --repo iTradingAI/aiwiki --limit 5
 ```
 
 发布后验证：
@@ -52,6 +45,8 @@ npm view @itradingai/aiwiki version
 npm view @itradingai/aiwiki versions --json
 ```
 
+如果 workflow 提示 Trusted Publishing / OIDC 权限问题，检查 npm 包设置里的 Trusted Publisher 是否指向 `iTradingAI/aiwiki` 和 workflow 文件名 `publish.yml`，并确认 workflow 顶层包含 `permissions: id-token: write`。
+
 ## 包体积
 
 npm 包只应包含 CLI 运行和用户文档所需文件。README 中的图片使用 GitHub raw 链接展示，`docs/assets/` 不进入 npm 包。

package/docs/ROADMAP.md

@@ -2,6 +2,10 @@
 
 AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版本分层。
 
+公开试用和长期运营的完整路线图见：
+
+- [AIWiki 长期运营路线图](./20260607-aiwiki-long-term-operating-roadmap.md)
+
 ## 1. 更稳的入库体验
 
 - 更顺的 setup 引导
@@ -9,6 +13,7 @@ AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版
 - 更稳定的 Agent handoff
 - 更完整的 Obsidian 审阅入口
 - 更容易追查失败原因
+- 更稳定的公开样例，让新用户先看到真实生成的核心产物
 
 ## 2. 更完整的内容处理能力
 

package/docs/SHOWCASE.md

@@ -19,35 +19,38 @@
 
 ### 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>/wiki-entry.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
+02-raw/articles/<slug>.md
+03-sources/article-cards/<slug>.md
+05-wiki/source-knowledge/<slug>.md
 ```
 
-### 长期目录会出现什么
+只有在宿主 Agent 提供了对应内容，或 payload 明确请求时，才会出现可选增强产物：
 
 ```text
-02-raw/articles/
-03-sources/article-cards/
+09-runs/<run-id>/creative-assets.md
+09-runs/<run-id>/topics.md
+09-runs/<run-id>/draft-outline.md
 04-claims/_suggestions/
-05-wiki/source-knowledge/
 06-assets/_suggestions/
 07-topics/ready/
 08-outputs/outlines/
-dashboards/
 ```
 
+仓库里的 `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 条目回到资料卡、原文、选题、大纲和处理记录
+- 从 Wiki 条目回到资料卡、原文和处理记录；如果这次入库生成了选题、大纲或 Claim，再继续查看对应可选产物
 - 需要结构检查时运行 `aiwiki lint`
 
 ## 示例 2：网页没读到正文
@@ -81,3 +84,10 @@ dashboards/
 - AIWiki 负责稳定写入本地知识库
 - AIWiki 会创建 Wiki Entry；没有 Agent 分析字段时只生成可追溯脚手架
 - 结果始终可追踪、可复盘、可继续写作
+
+## 本仓库样例
+
+- `examples/demo-run/`：输入、命令和 CLI 输出。
+- `examples/obsidian-vault-sample/`：已经生成好的样例知识库。
+
+这个样例不依赖爬虫、向量库、RAG 或 Pro 自动化；它只展示基础 CLI 的真实落盘结果。