@itradingai/aiwiki 0.2.16 → 0.2.19

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

@@ -91,9 +91,6 @@ AIWiki 会修复常见 UTF-8 mojibake，但这只是兜底；宿主 Agent 仍应
     "outputs": [
       "source_card",
       "wiki_entry",
-      "creative_assets",
-      "topics",
-      "draft_outline",
       "processing_summary"
     ],
     "language": "zh-CN"
@@ -193,15 +190,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 +217,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`，回复时要说明它只是可追溯脚手架，不是高质量知识提炼。
 
@@ -247,3 +245,57 @@ Lint 输出会包含摘要、最高优先级问题、分级报告，以及建议
 Before ingesting, querying, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace. Treat it as the local contract for what belongs in this knowledge base, what should stay out, and how future multi-knowledge-base routing should be handled.
 
 If the material does not fit the purpose file, do not force it into the knowledge base as confirmed knowledge. Record the mismatch, ask for review when needed, or keep it as a traceable source rather than a claim.
+
+## Context JSON for Retrieval
+
+When answering from AIWiki, prefer:
+
+```bash
+aiwiki context "<topic>" --limit 10
+```
+
+Use filters when the user intent is narrow:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --source-role input --wiki-type source_knowledge --status active
+aiwiki context "<topic>" --type source_cards --status to-review
+```
+
+`context` is local Markdown/frontmatter retrieval only. Do not describe it as vector search, RAG, a database query, or external web search.
+
+Read these fields before responding:
+
+- `query_scope`: what was searched and which filters were applied.
+- `result_quality.total_matches` and `result_quality.has_wiki_entry`: whether the answer is grounded in a Wiki Entry or only in supporting artifacts.
+- `recommended_next_action`: whether to answer, enrich, review grounding, or broaden the query.
+- `match_reasons`: why each result matched, such as title, body, tags, topics, relationships, or source URL.
+- `quality_signals`: scaffold, enriched, status, grounding, and relationship hints.
+- `related_refs`: local wikilinks and frontmatter relationships such as `source_card`, `raw_file`, and run artifacts.
+
+If `quality_signals` contains `quality:scaffold` or `grounding:needs_review`, tell the user the result is a traceable lead that needs enrichment or review. Do not present it as confirmed final knowledge.
+
+## Agent Skill Upgrade Flow
+
+When the user asks you to install, update, upgrade, or repair AIWiki integration, run:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+Use JSON when you need exact state:
+
+```bash
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+```
+
+Interpret sync results:
+
+- `installed`: target did not exist and now has the packaged skill.
+- `current`: installed skill already matches the packaged skill.
+- `updated`: installed skill differed; the old file was backed up and replaced.
+- `would_install` / `would_update`: dry-run preview only.
+- `unsupported`: no safe automatic target is known; use `aiwiki prompt agent`.
+
+After sync, report the target path, backup path when present, and that the user may need to restart or reload the Agent. Do not claim the new skill is active until the Agent has reloaded it.

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
 ```
 
 然后去看：
@@ -78,3 +78,5 @@ aiwiki context "主题"
 ```bash
 aiwiki lint
 ```
+
+如果只是清理旧版本留下的空可选增强目录，可以让 Agent 先运行 `aiwiki lint --json`，确认只有 safe fix 后再运行 `aiwiki lint --fix-empty-dirs --json`。

package/docs/README.md

@@ -15,13 +15,12 @@ AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent
 
 ```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/ROADMAP.md

@@ -2,6 +2,10 @@
 
 AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版本分层。
 
+公开试用和长期运营的完整路线图见：
+
+- [AIWiki 长期运营路线图](./20260607-aiwiki-long-term-operating-roadmap.md)
+
 ## 1. 更稳的入库体验
 
 - 更顺的 setup 引导

package/docs/USAGE.md

@@ -56,14 +56,14 @@ aiwiki status
 
 ## 2. 让宿主 Agent 学会 AIWiki
 
-初始化知识库之后，先让宿主 Agent 学会 AIWiki。推荐先扫描本机支持的宿主 Agent：
+初始化知识库之后，先让宿主 Agent 学会 AIWiki。主路径推荐使用幂等同步：
 
 ```bash
-aiwiki agent list
-aiwiki agent check
+aiwiki agent sync --yes
+aiwiki agent check --json
 ```
 
-再启动安装向导：
+旧的安装向导仍然兼容，但不再作为首选路径：
 
 ```bash
 aiwiki agent install
@@ -93,7 +93,7 @@ aiwiki prompt agent
 
 把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
-`aiwiki agent check` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent install --agent <id> --yes`。
+`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。
 
 ## 3. 日常使用
 
@@ -127,7 +127,7 @@ source_url: https://example.com/article
 summary: 这里是文章前段摘要，方便 Agent 快速告诉用户文章大意。
 run_id: 20260507-153012-abc123
 run_dir: F:\knowledge_data\aiwiki\09-runs\20260507-153012-abc123
-files: 15
+files: 8
 processing_summary: 09-runs/20260507-153012-abc123/processing-summary.md
 wiki_entry: 05-wiki/source-knowledge/article-slug.md
 wiki_entry_generation_mode: agent_enriched
@@ -138,7 +138,7 @@ grounding_needs_review: no
 grounding_markers: none
 grounding_claims_with_quotes: 1/1
 source_card: 03-sources/article-cards/article-slug.md
-draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md
+draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md  # 仅在生成大纲时出现
 dashboard: dashboards/AIWiki Home.md
 review_queue: dashboards/Review Queue.md
 warnings: 0
@@ -203,8 +203,13 @@ Obsidian 入口：dashboards/AIWiki Home.md
 ```text
 02-raw/articles/
 03-sources/article-cards/
-04-claims/_suggestions/
 05-wiki/source-knowledge/
+```
+
+可选增强目录只在有对应内容或 `request.outputs` 明确请求时生成：
+
+```text
+04-claims/_suggestions/
 06-assets/_suggestions/
 07-topics/ready/
 08-outputs/outlines/
@@ -252,10 +257,10 @@ AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会
 
 链接规则：
 - wikilink 使用 vault 相对路径，统一为 `/`，并去掉 `.md` 后缀。
-- `05-wiki/source-knowledge` 是默认知识入口；`03-sources/article-cards` 会链接到 Wiki 条目、原文、Claim 建议、素材建议、选题、大纲和本次处理记录。
-- `02-raw/articles`、`04-claims/_suggestions`、`06-assets/_suggestions`、`07-topics/ready`、`08-outputs/outlines` 会回链到资料卡，Obsidian 的 Backlinks/Graph View 可以串起同一篇资料。
+- `02-raw/articles`、`03-sources/article-cards`、`05-wiki/source-knowledge` 和 `09-runs/<run-id>` 是核心产物；`04-claims/_suggestions`、`06-assets/_suggestions`、`07-topics/ready`、`08-outputs/outlines` 只在 payload 有对应内容或 `request.outputs` 明确请求时生成。
+- `03-sources/article-cards` 只链接本次实际生成的可选增强产物，避免空目录和断链。
 - `09-runs/<run-id>/processing-summary.md` 会把本次生成的 Markdown 文件列成可点击 wikilink；`payload.json` 不是 Markdown，保留普通路径。
-- frontmatter 会写入 `aiwiki_id`、`type`、`status`、`slug`、`source_url`、`content_fingerprint`、`created_at`、`captured_at`、`run_id`、`source_card`、`raw_note`、`claims_note`、`assets_note`、`topics_note`、`outline_note`、`run_summary`、`tags` 等字段，便于后续用 Obsidian Search / Properties / Dataview 做筛选。
+- frontmatter 会写入 `aiwiki_id`、`type`、`status`、`slug`、`source_url`、`content_fingerprint`、`created_at`、`captured_at`、`run_id`、`source_card`、`raw_note`、`run_summary` 等核心字段；`claims_note`、`assets_note`、`topics_note`、`outline_note` 只在对应产物存在时出现。
 
 ### Obsidian 数据库入口
 
@@ -324,9 +329,10 @@ aiwiki lint
 aiwiki lint --severity warning
 aiwiki lint --json
 aiwiki lint --no-write
+aiwiki lint --fix-empty-dirs --json
 ```
 
-`lint` 会先输出 `lint_summary`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive` 或 `mark_reviewed`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。
+`lint` 会先输出 `lint_summary`、`safe_fixes`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive`、`mark_reviewed` 或 `remove_empty_optional_dir`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。`--fix-empty-dirs --json` 只会删除已知且为空的可选增强目录，并在 `safe_fixes.applied` 里报告删除了什么。
 
 查看下一步建议：
 
@@ -434,3 +440,59 @@ aiwiki status
 - `next_action`: the recommended next command.
 
 `aiwiki next` uses the same repair order: fix workspace structure first, then lint errors, lint warnings, empty-workspace onboarding, and finally healthy-state query guidance.
+
+## Query and Context Filters
+
+`aiwiki context` and `aiwiki query` use local Markdown/frontmatter search. They do not use vector search, a database, external search, or RAG-over-wiki.
+
+Useful filters:
+
+```bash
+aiwiki context "AI Agent" --type wiki_entries --source-role input --wiki-type source_knowledge --status active --limit 5
+aiwiki query "AI Agent" --type source_cards --status to-review --limit 3
+```
+
+Supported filters:
+
+- `--type`: one result group, such as `wiki_entries`, `source_cards`, `claims`, `topics`, `outlines`, or `raw_refs`.
+- `--source-role`: frontmatter `source_role`, usually `input`, `processing`, or `output`.
+- `--wiki-type`: frontmatter `wiki_type`, such as `source_knowledge` or `personal_knowledge`.
+- `--status`: frontmatter status, such as `active`, `to-review`, `ready`, or `draft`.
+- `--limit`: per-group result limit, clamped from 1 to 50.
+
+The JSON result keeps the stable `schema_version: "aiwiki.context.v1"` and now also includes:
+
+- `query_scope`: filters, limit, and searched groups.
+- `result_quality`: total matches, best score, whether a Wiki Entry was found, and warnings.
+- `recommended_next_action`: for example `use_matches_for_answer`, `review_grounding_or_enrich_entry`, or `broaden_query_or_ingest_source`.
+- Per match: `match_reasons`, `quality_signals`, and `related_refs`.
+
+Use `match_reasons` to explain why a result matched. Use `quality_signals` before answering confidently: scaffold or grounding-review entries should be treated as traceable leads, not final knowledge.
+
+## Agent Skill Sync
+
+AIWiki does not modify Agent configuration during `npm install`. After first install or upgrade, sync the packaged skill explicitly:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+For one host Agent:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+Useful Agent-facing options:
+
+```bash
+aiwiki agent sync --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+aiwiki agent help
+aiwiki context --help
+```
+
+`agent sync` is safe for first install and cross-version upgrades. It installs missing targets, leaves current targets unchanged, and backs up changed installed skill files before overwrite. If a backup is created, tell the user the backup path and that rollback means copying the backup file back to the target path.