在 OpenKnowledge 项目中用 MCP…

当项目由 OpenKnowledge（OK）MCP 管理、需要读取/列出/搜索/编辑/删除/lint 任意 content.dir 范围内的 .md/.mdx 或调用 mcp__open-knowledge__* 工具时使用。

适用场景

解决思路

1. 所有规则默认 MUST；处理相关任务时按需加载一层深的 references/*.md 引用。
2. 如果 mcp__open-knowledge__* 工具不可用，先阅读 references/setup.md，按 rung ladder 操作：approve .mcp.json -> ok start CLI -> 可选 desktop app，并参考 canonical quickstart。
3. 读取单个文档用 exec("cat …")；列目录用 exec("ls -A …") 获取 folder defaults + template menu；字面搜索用 exec("grep …")；排名检索用 search。原生 Read/Grep 仅用于源代码（.ts/.py/…），绝不用于范围内 .md/.mdx。
4. 写入：新建或全量替换文档用 write({ document: { path, content } })；正文查找替换用 edit({ document: { path, find, replace } })；frontmatter 合并补丁用 edit({ document: { path, frontmatter } })，null 删除键；删除用 delete({ document })；移动/重命名用 move({ from, to })。正文 find/replace 仅正文。每次内容写入传一行 summary（≤80 chars，用户可见结果）。
5. 预览/打开文档：每会话先确定唯一 surface，按第一个匹配停止：OK_DESKTOP_TERMINAL 或 OK_HOSTED_AGENT 设置 -> 在 OpenKnowledge 内 -> ok open <name>（切换用户已看窗口），绝不在回复粘贴 localhost URL；应用内浏览器 -> preview_url 然后打开/导航到文档；否则 plain CLI -> ok open <name>。ok open <name> 打开文档或文件夹（自动检测）；--skill <name> 用于 skill。previewUrl 字段是 route id，不是打开机制。不要 preview_screenshot 确认编辑。完整 Step-0 + per-surface how-to 查 references/preview.md。
6. 知识层捕获/综合/提升是过程，不是工具调用；没有 ingest 工具。ingest 见 references/ingest-and-sources.md；research + consolidate 随 knowledge-base pack；层模型 + packs 见 references/starter-packs.md。
7. 直接业务问题（“which customers…”，“what did we decide about…”）路由到 search/exec + 带引用的聊天回答，无需 research 关键词；仅当持久 + 多文档 + 未覆盖时持久化，且先 offer。见 references/corpus-qa.md。
8. 编写或改进 skill 时停止并调用 /open-knowledge-write-skill 处理 scope（项目/全局）、contract、evaluation、install；通过 write({ skill }) 创作，绝不通过 document path；skills 是 editor skills/ 目录下真实文件夹（.claude/.cursor/.codex/.github/.opencode/.pi/.agents），一个 source 加 managed copies/symlinks；通过 skills 和 edit({ skill }) 读取/编辑，它们路由到 source；绝不手改非 source copy，managed copies 从 source 刷新，编辑会 fork 并停止刷新。
9. 工具索引读取类：exec 主读取工具，在只读文件系统执行 cat/ls/grep/…，并加 frontmatter/backlink/history enrichment；一条命令或一个 pipe，不是 shell。search 排名 BM25 + recency。history 查 doc versions。links 用 kind: backlinks|forward|dead|orphans|hubs|suggest，或传数组一次调用。skills 搜索+读取：query 到 skills.sh；省略 name 列出 managed (Project + Global)；name 读取一个——按 name+scope，从不按 path。config 查 resolved config。palette 取 authoring forms + html preview starters + theme tokens；palette({ components }) 取 JSX schemas。preview_url 按需取 preview URL。share_link 取 GitHub-substrate share URL；只读，无 GitHub remote 会报错。lint 查 markdown-lint violations：document 查一个文档，省略查项目；fix: true 加 document 就地自动修复可修复规则并归属、在 preview 中 live；其余需 edit/write。audit 一份报告列出每个 lint violation + broken internal link，按 source file 带行；path 限定范围；链接验证用 audit 而非 links；caveats 见 references/linking.md。成功 lint/audit 结果读 ran：ran 中缺失的 family 未检查，[] 表示未选择检查。
10. 写入类：四个原生 CRUD 动词多态 document/folder/template/skill/asset，恰好一个目标，嵌套在地址键下。write create/overwrite；write({ skill: {…} }) 在项目默认 skill home 创作为真实文件夹，对该 folder 的 agent 立即可用。edit 正文 find/replace/frontmatter merge-patch；无 asset。delete 删除。move 移动/重命名并重写 referrers；skill 还接受 scope/toScope 用于 Project↔Global：history 重置，只有 destination level 能 host 的部分 re-project；其余在 source 移除并以 droppedLocations 返回（成功时用 install 重新添加）。Output mirrors input key；preview envelope (previewUrl, warning) 保持 top-level。
11. 其他写入工具：install 决定 skill 住在哪里：add/remove locations 加性——editor ids、agents 或 custom roots；mode + convert 只重排指定 locations；source 移动真实文件夹。source folder 就是 skill——没有 uninstall everywhere；skill 只能通过 delete 消亡。import 将 skill-dir 获取到 add 的 locations；scripts 永不运行。checkpoint 命名版本。restore_version 回滚。folder 的 frontmatter 是 open-shape 且 self-only（不级联）；templates 是新文档起始内容。
12. 冲突工具：conflicts 用 kind: list|content；resolve_conflict 从该冲突的 resolutionOptions 写解决方案；仅 merge-native 提交；破坏性。见 references/conflict-resolution.md。
13. 误用自纠正：约束 JSON Schema 无法表达（“exactly one target”、“find 需要 replace”、body-XOR-frontmatter）返回 isError: true 和一行 corrective shape；读取并用该 shape 重试，不要猜。
14. 识别非 OK MCP 工具：preview_start、preview_screenshot、WebFetch、WebSearch、原生 Read/Grep/Glob/Edit 属于 host；STOP 规则决定哪些可用于 in-scope markdown。
15. STOP 规则：所有 in-scope markdown 读写通过 OK MCP 工具，绝不用宿主原生文件工具；原生 Edit/sed/直接 Write 绕过 CRDT 并丢失 shadow repo 中 agent attribution；原生读取跳过 frontmatter、backlinks、shadow-repo activity、project git history。工作区配置 OpenKnowledge MCP 时，不要对 content directory 内 markdown 路径用原生文件工具。
16. 禁止合理化 1：原生 Read/Grep/Glob 在 in-scope .md/.mdx。
17. 禁止合理化 2：Bash ls/find/cat 在包含 in-scope markdown 的目录；用 exec("ls -A …")/exec("find … -name '*.md'")/exec("cat …")；原生返回裸名，exec 添加 frontmatter/backlinks/recent activity；-A 显示隐藏条目且无 . / ..。
18. 禁止合理化 3：Glob 模式针对 markdown；exec 扩展文件操作数（如 cat specs/*.md）；带引号模式和命令自身模式（find -name）保持字面。
19. 禁止合理化 4：派发 Explore/general-purpose subagent 做 markdown-heavy 探索；subagents 内部用原生工具并绕过 OK；自己用 exec/search 做 markdown 探索；subagents 适合 source-code 探索。
20. 禁止合理化 5：原生 Read/Grep 在 .ok/ 内 in-scope markdown；.ok/ 是 in-scope，像其他 KB 文件处理其 .md/.mdx。
21. 禁止合理化 6：ls/cat/find 在 skill 文件夹发现或读取 skill；skills 按 name+scope 寻址，不按 path（skill 可在任何 editor dir、.agents/skills/ hub 或 custom root，副本在别处）；用 skills 工具。
22. 没看到 exec 不是逃生口：wiring、labels、tool visibility 因 client 而异；有些（尤其 Codex）把 MCP 工具推迟到 lazy discovery；注册是测试，不是顶层符号可见性；先为 open-knowledge 运行 tool discovery。细节 references/setup.md。
23. Escape hatch：仅当运行 tool discovery 后，项目没有注册 OpenKnowledge MCP server，或刚实际调用 MCP 并失败；然后以用户可见句子开头 OpenKnowledge MCP unavailable:。只有 tool discovery 空后才能得出“未注册”，绝不要仅从初始工具列表得出。绝不因跳过客户端 MCP 路径、没看到 exec 顶层、没运行 tool discovery、或合理化 skill 不必要而使用。
24. 源代码和非 markdown 文件（.ts、.py、package.json、…）始终可用原生 Read/Grep/Glob。
25. Reads 示例：读文件 exec("cat <path>.md") 得内容+完整 enrichment。
26. 列目录 exec("ls -A <dir>") 得每个 child 的 frontmatter、递归 markdown 计数、每个 subdir 最近更新 doc、folder 自身 title/description/tags + templates_available；优先 -A 而非普通 ls。
27. 字面搜索 exec("grep -rn <term> <dir> | head -5") 得匹配 + 匹配文件 enrichment。
28. 排名搜索 search({ query }) 有 title boost + body BM25 + recency；用于挑最佳 doc，不用于列出每次出现。
29. 写入：一有内容立即调用 write/edit（按 STOP 规则走 MCP）。
30. 增量持久化（MUST）：多步或长任务（research sweep、多源综合、批量文档）每完成一个单元写 KB：每 section、每 source、每 doc；绝不把完成发现只放上下文等最后写；rate limit、crash、context compaction 中途会丢弃未写；已持久化幸存，读回文档恢复；尽早创建目标 doc（skeleton + frontmatter），然后 edit 每 section。
31. 每次内容写入传 summary（SHOULD）：一行（≤80 char）用户可见 note，成为 timeline entry。
32. 在比 prose 更好时使用视觉结构（Callout、mermaid、table、html preview）；起草时调 palette；advisory write-warnings、MDX authoring、delete/move mechanics、visual authoring 见 references/writing.md + references/components-and-visuals.md + references/media-and-assets.md。
33. Grounding：每个事实性声明必须有来源（MUST）；KB 文档是事实 artifact，每个 claim 可追溯，来源在知识库内而非公共 web。
34. Ingest 是过程不是工具：binary-vs-text classification、SSRF-safe fetch flags、size + executable gates、wrapper frontmatter 见 references/ingest-and-sources.md；首次 capture 前读；naive fetch-and-paste 跳过所有 gates。
35. Closed loop：外部源通过 ingest 过程拉入，然后本地引用；KB 文档内裸 [source](https://...) 不是 citation，是 TODO 表示还需 ingest；只有每个叶子是本地文档链才工作。
36. 每个事实性声明 MUST 在 claim 点引用来源；无 unsourced speculation。
37. Web 源：fetch 页面（host WebFetch/WebSearch），ingest 它，然后引用路径 [source name](./path/to/source.md)（本地文档带 source_url:）；inline [source](URL) 是聊天 affordance，不是 KB。
38. 自抓取也算：你 fetch 的 URL 用于 grounding claim 同样要 ingest，不因 inline URL 降级。
39. 内部交叉引用：链接持有权威 claim 的 OK 文档；该文档引用自己的来源（链终止于保留本地文档）。
40. 无证据：搜索并 ingest 结果，或标 (TODO: needs source)，或不写该 claim；绝不捏造；unsourced speculation 腐烂成不可追溯 tribal lore。
41. Linking：标准 markdown links（MUST）；链接每个命名另一文档的名词短语 [text](./relative/path.md)，并自由链接；每个 link 必须在完成时 resolve 到存在的 doc（同一 pass 前向引用稍后创建可以；真正不会存在的保留为 plain prose + tracked task）；绝不 backtick link（`[text](./foo.md)` 是 bug），绝不用 HTML <a>。
42. 每次 write/edit 后读 brokenLinks：修复报告的 href；[] 表示所有链接 resolve，除非 brokenLinkSuppression 扣留 reserved-log findings（那些不是你的修复）；audit 权威，同 marker 同含义；外部 web 源不是 inline body links；完整规则 + [[Page]] legacy note 见 references/linking.md。
43. Folders/frontmatter/templates：每个 .md/.mdx 需要 YAML frontmatter，title + description 必需，tags 推荐；OKF 项目（okf pack）例外：pack rules 优先——非根 index.md 不带 frontmatter（frontmatter-reserved-index lint 对任何 key 警告），log.md 不需要，concept docs 只需非空 type；title/description 可选。
44. 两个 opt-in、nested folder 机制：folder frontmatter（<folder>/.ok/frontmatter.yml 是文件夹自身 open-shape properties；self-only，不级联到子文档）和 templates（<folder>/.ok/templates/ 是新文档起始内容）；大多数 folder 没有 .ok/；文档 frontmatter 就是自身 on-disk YAML；结构模型 + 完整 pre-write checklist 见 references/folder-model.md；template authoring + folder editing 见 references/template-authoring.md；frontmatter-vs-body edit rules 见 references/doc-editing.md。
45. 写前读文件夹（MUST）：在 folder 创建/编辑文档前，每 folder 每 session 调一次 exec("ls -A <folder>")，它返回 folder 的 title/description/tags + templates_available；跳过会落违反 folder discipline 的文档。（如果 folder 无 frontmatter 且无 templates 且 repo 其他内容多，则未 onboarded——先运行 references/onboard-existing-repo.md。）
46. 模板适合就用（MUST）：通过 write({ document: { path, template } }) 实例化；继承模板计入；仅当无匹配或用户要求自由形式时跳过（在 chat 中说明原因）；形状重复时主动创建模板。
47. 当重复的每文档属性出现（MUST）：多个兄弟写相同 frontmatter 时，把这些起始值烘焙进模板（write({ template })）；folder frontmatter 不级联值到文档。
48. Conflict-aware writes：doc-in-conflict 冻结写；stale-external-write 表示 recovery 漏掉 disk；两者用 conflicts 检测，不用 exec；见 references/conflict-resolution.md；concurrent-overwrite-refused 不是 conflict state：等它的 bound 再重试，或使用 append/prepend/edit。
49. Anti-patterns 做法：列/查找/读 markdown 用 exec("ls -A …")/exec("find …")/exec("cat …")，不用 Bash: ls/Glob: **/*.md/Read: foo.md。
50. 探索 markdown-heavy dir 自己做 exec/search，不用 Agent(Explore)（绕过 OK）。
51. 引用另一文档用 [text](./p.md)，不用 backticked 或 HTML <a>。
52. 嵌入图片保存本地 + ，不用 <img>、localhost/preview_url URL、hot-link。
53. KB 文档事实声明：ingest source（references/ingest-and-sources.md）并 cite local path，不用无引用 prose 或 inline [src](https://…)。
54. 确认编辑落地 trust CRDT tool response，不用 preview_screenshot 或 verification loop。
55. 删除 markdown 文档用 delete({ document })（有风险先 checkpoint()），不用 Bash: rm/native deletion。
56. 在陌生 folder 写前先 exec("ls -A <folder>")。全表 references/anti-patterns.md。
57. Knowledge layers：ingest 用于原样保留共享 URL/PDF/file 或你 fetch URL 来 grounding claim（binary 源保留，不 scrape），过程 references/ingest-and-sources.md；research 用于调查/比较/综合源 -> status: provisional 文章 + sources:，过程 /research-with-sources skill；consolidate 用于决策已做 -> canonical source-of-truth 带 supersedes: 链，过程 /consolidate-notes skill。
58. Research 和 consolidate 随 ok seed --pack knowledge-base 到来；没有 pack 就没有那些过程，不要即兴；作为普通 grounded write 做，或 offer seed（ok seed --pack knowledge-base --dry-run 显示会加什么）。
59. 不要静默链：让用户驱动 ingest -> research -> consolidate；过程 STOP gates 覆盖 session-level don't stop to ask hints；任何改变 KB 内容的 turn 后检查 log.md 并遵循其 contract（references/cadence-and-logs.md）；多文档批次交错写，让 preview 显示叙述进展。
60. Onboarding 已有内容 repo 见 references/onboard-existing-repo.md；层模型 + packs 见 references/starter-packs.md。
61. OK 的更多能力随版本变化；未覆盖时读 docs https://openknowledge.ai/docs 和 source https://github.com/inkeep/open-knowledge，不要猜。
62. Server lifecycle：如果 write/edit 返回 Hocuspocus server is not running，通过 Bash 运行 ok start 并重试；绝不对 in-scope markdown 回退到原生 Edit/Write。
63. Scope：OK 在 resolved content.dir 下查找文档（runtime: config({ key: 'content.dir' })）；.gitignore 和 .okignore（root 或任意 folder depth）定义排除；content.dir 下未被排除的每个 .md/.mdx 都是 OpenKnowledge 文档，包括 specs/、reports/、docs/ 下；folder metadata + templates 在 nested <folder>/.ok/，不在 .ok/config.yml。
64. 在 git worktree 时，将 worktree 绝对路径作为 cwd 传给 OK 工具调用一次，它 sticky 整个 session，所以 reads/writes/preview 都 target 该 worktree。
65. Skill version tracks @inkeep/open-knowledge-server；cat ~/.ok/skill-state.yml 显示安装内容；ok seed 需要 @inkeep/open-knowledge >= 0.4.0；如果报 unknown command，运行 npm install -g @inkeep/open-knowledge。

适用边界 · 注意事项

• 不适用于非 OpenKnowledge 项目、未配置 OpenKnowledge MCP server，或不在 content.dir 范围/被 .gitignore/.okignore 排除的 markdown；此时按普通流程处理。
• 不适用于源代码和非 markdown 文件（.ts、.py、package.json 等）；这些始终可用原生 Read/Grep/Glob。
• 未安装 knowledge-base pack 时不适用 research/consolidate 过程；不要即兴编写，改用普通 grounded write 或先运行 ok seed --pack knowledge-base。