最佳实践

Knowlery 最好被当作一种节奏，而不是一个偶尔访问的工具。本页收集的是让知识库 在数月尺度上保持健康的实践——每一条都基于系统的真实行为。

核心循环：capture → cook → ask

其他一切都是为这个循环服务的。

1. 无仪式感地捕获。 原始笔记、会议片段、剪藏文章、对话里的 MCP capture 调用——它们都以普通用户笔记（或 inbox/）落盘。捕获时不要整理；整理是 /cook 的工作。凌乱的 inbox 是正常的，丢内容才不正常。
2. 按批次 cook，不要持续 cook。 有一批值得编译的材料时再跑 /cook—— 项目告一段落、一次阅读结束、一周的捕获积累之后。staleness 报告 （knowlery stale，或 dashboard 的 Knowledge health）会精确告诉你什么在 等待：先是 stale 页面，然后是未编译笔记（最新在前）。
3. 对编译层提问。 /ask 和 knowlery query 从编译页面回答，带引用。 如果答案显得单薄，那是 cook 欠债的信号，不是检索的问题。

相信弃答

当检索说 No confident matches，请相信它。引擎在问题没有被任何页面充分覆盖 时会主动弃答——这个回答的意思是"你的知识库还不知道这件事"，当它为真时，这 正是你想听到的。

• 不要换五种问法去逼出一个命中；如果这个问题重要，去 cook 应该回答它的材料。
• Agent 应该原样转述弃答，而不是用猜测填充——内置技能和 MCP 工具描述里都写 了这条，所以一个围着弃答编造答案的 agent 是配置有问题，不是信息不够。

守住两层边界

最重要的一条结构规则：用户笔记是你的；四个编译目录是 agent 的。

• 不要批量手写页面进 entities/、concepts/、comparisons/、queries/。 编译页面写错了可以改，但创建应该经过 /cook——它会维持 sources 引用和 SCHEMA.md 分类的一致性。
• 永远不要让 agent 重构你自己的笔记。内置规则已经强制这一点；写自定义规则时 也请保持。
• Library/（已安装的知识包）是只读参考材料。想拥有某个包里的页面时， fork 到自己的目录——不要原地编辑，否则更新会拒绝覆盖你的修改（这是 设计行为）。

引用是整个系统的经纬线

编译页面通过 sources: frontmatter 和 wikilink 引用来源。这不是装饰——它是 整套机制能够机械运转的前提：

• 陈旧检测比较来源与页面的修改时间；没有引用的页面永远不会被标记为 stale。
• 当编译页面引用的原始笔记命中问题时，检索会给该编译页面加分——跨语言提问 就是通过这条路径抵达编译层答案的。
• /challenge 和 Freshness Review 沿引用链核查论断。

如果你接受了一个没有引用的 agent 生成页面，你就制造了一个机制看不见的页面。 "Citation required" 规则就是为此存在的。

大动作之后跑 health

导入、迁移、切换平台、大型 agent 会话之后，跑 knowlery health（或 Settings → Diagnostics）。它便宜、只读，而且能在无聊的故障（缺技能、配置 损坏、目录缺失）变成令人困惑的 agent 行为之前抓住它们。knowlery sync 修复 health 报告的问题；它幂等且只在有变化时写入，"以防万一"跑一次毫无成本。

Schema 纪律，轻拿轻放

SCHEMA.md 是活的约定文件。让 /cook 随新材料扩展 tag 和 domain 分类—— 那是它的职责——但偶尔审一眼 diff。两个值得动手的坏味道：

• 同义 tag（ml、machine-learning）——合并它们；检索把 tag 当证据， 同义词会分裂证据。
• 只有一页的 domain——通常是 cook 太急切的信号；并进相邻 domain。

想要更深入的检查时，/audit 报告结构漂移（孤儿页、断链、frontmatter 缺失）。

分享：review 意味着真的读

导出评审门会展示将要发出的每个页面和每个来源，带风险提示（邮箱、敏感 URL、 人物页、会议类笔记）。让这套机制保持诚实的实践：

• 读清单，不要扫清单。 刻意没有 approve-all 开关。如果由 agent 驱动评审， 它必须先完整逐字呈现清单、再执行你的决定——这条行为准则写在技能里，请 按这个标准要求它。
• 默认走私有分发。 私有仓库的 GitHub Release 加 gh 认证安装覆盖绝大多数 分享场景；--public 藏在第二道确认门之后是有原因的——公开发布是永久的 （假设任何公开发布的内容在上线那一刻就已被下载）。
• 有意识地管理版本号。 订阅者看得到你的版本号；修正 bump patch，新增页面 bump minor。更新管线拒绝降级、拒绝覆盖本地修改——顺着这个纹理工作， 不要对抗它。

多知识库：按受众切分，不按主题切分

注册名（kb add）很便宜，但知识库本身不是免费的——每个都是独立的检索范围、 cook 范围和分享范围。好的切分标准是谁可以看到它（工作 / 个人 / 团队共享）， 因为这条边界同时决定了导出范围和远程暴露范围。同一受众下的不同主题通常属于 同一个知识库，用 domain 组织——跨库的"我在哪写过这个"用联邦查询 （--kb '*'）解决。

Agent：把正门给它们

• 让 agent 先读 KNOWLEDGE.md——它就是为 agent 写的。
• 优先用确定性工具（query、stale、MCP 工具），而不是让 agent grep 整个 vault——引擎的打分、CJK 处理和弃答机制都是临时 grep 不具备的。
• MCP 写工具的行为准则：写操作执行的是你的话，绝不是 agent 的主动性。 一个悄悄 capture 或不复述路径就 init 目录的 agent 已经越界——工具描述里 写了这条，你也应该这样要求。
• 把 vault 放进版本控制（至少要有备份）。Knowlery 的每个操作都按非破坏性 设计，但 agent 终究是 agent。

不要做的事

• 不要缓存检索结果或另建索引——每次查询都是设计上的实时扫描；没有需要失效 的缓存，也没有会漂移的索引。
• 不要手改 .knowlery/ 下的状态文件（bundles.json、export-scope.json、 registry），除非确实坏了；它们是 shell 之间的契约。
• 不要用旧版 CLI 操作被新版本 sync 过的工作区——降级守卫会拒绝，正确的修法 是 npm i -g knowlery@latest，不是强行绕过。
• 不要"为了测试"往公开仓库发布知识包——用私有仓库或本地 zip 测试；公开是 永久的。