inkeep/open-knowledge

OpenKnowledge — 代理指南

OpenKnowledge (OK) 是一个通过 MCP 暴露的 Markdown-CRDT 协作平台。此技能是 OK 代理行为的唯一权威指南。除非另有标注，以下每条规则均为强制要求。详细信息请参考 references/*.md 文件——仅深入一层；当相关任务出现时加载对应的参考文件。

技能版本与 @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。

设置（尚未连接？）。 如果你的客户端中没有 mcp__open-knowledge__* 工具，则此项目尚未在该机器上配置——请参见 references/setup.md 了解阶梯式设置步骤（批准 .mcp.json → ok start CLI → 可选桌面应用）以及标准的快速入门指南。

概要——90% 的常见场景

1. 读取操作： 使用 exec("cat …") 读取单个文档，使用 exec("ls -A …") 列出目录内容（显示文件夹默认信息和模板菜单），使用 exec("grep …") 进行精确搜索，使用 search 进行排序检索。仅对源代码（.ts / .py 等）使用原生的 Read / Grep 操作，绝不用于范围内的 .md / .mdx 文件。
2. 写入操作： 使用 write({ document: { path, content } }) 创建新文档或完全替换现有文档；使用 edit({ document: { path, find, replace } }) 对文档正文进行查找替换；使用 edit({ document: { path, frontmatter } }) 对文档前置元数据进行合并更新（null 值会删除对应键）。使用 delete({ document }) 删除文档，使用 move({ from, to }) 移动/重命名文档。正文查找替换仅作用于正文。每次内容写入时，请提供一个单行 summary（不超过 80 个字符，描述面向用户的成果）。
3. 预览： 每次读取/写入响应都会携带一个仅包含路由的 previewUrl（/#/<doc> 格式，不包含主机和端口）。在会话开始时打开一次浏览器。不要使用 preview_screenshot 来确认编辑结果——工具的响应本身就是确认。完整的多主机约定请参见：references/preview.md。
4. 工作流指南： workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) 返回一个流程指南，而非实际数据。当工作符合对应层次时使用它。
5. 直接提问： 对于简单的业务问题（"哪些客户…"、"我们关于…的决定是什么"），应使用 search / exec 工具并结合带有引用的聊天回答——无需使用 "research" 关键词。仅当答案需要持久化、涉及多个文档且尚未被覆盖时，才进行存储，并且先征询用户意见。请参见 references/corpus-qa.md。
6. 编写或改进技能（"编写/创建一个技能"、"改进此技能"、"将其转为技能"）：请立即停止并调用 open-knowledge-write-skill 技能——它负责处理范围选择（项目级 vs 全局级）、SKILL.md 合同、评估和安装；请不要在此技能中自行操作。通过 skill 目标进行编写（write({ skill })），绝不要直接操作原始路径 .ok/skills/… 下的文档。绝对不要读取、对比或编辑安装在 .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ 下的投影文件——install 命令会生成它们，并在下次同步时覆盖；它们不是权威来源。

工具索引——19 个工具（路由器；每个工具的完整约定请参见 MCP 工具描述）

• 读取操作——exec（主要工具；只读的 cat/ls/grep/find/head/tail/wc/sort/uniq/cut 命令 + 前置元数据、反向链接、历史记录；支持单个命令或单个管道，不是完整的 shell）、search（基于 BM25 + 时效性的排序搜索）、history（查看文档的历史版本）、links（kind: backlinks|forward|dead|orphans|hubs|suggest，或提供一个数组以一次调用完成全面审计）、skills（查找和读取技能：省略 name 可列出项目和全局范围内的所有技能，传入 name 可读取某一个技能——通过 name+scope 寻址，绝不通过路径）、config（获取已解析的配置）、palette（原生于 Markdown 的创作表单 + html preview 启动器 + 主题 token；使用 palette({ components }) 获取 JSX 模式）、preview_url（按需获取浏览器预览 URL）、share_link（基于 GitHub 的分享链接；只读，如果没有 GitHub 远程仓库则会报错）。
• 写入操作——四个原生 CRUD 动词，多态作用于 document / folder / template / skill / asset（恰好传入一个目标，嵌套在其地址键下）：write（创建/覆盖；write({ skill: { name, description, body, scope? } }) 创建一个技能 → .ok/skills/<name>/SKILL.md，在 install 之前为草稿状态）、edit（正文查找替换或前置元数据合并更新；不支持 asset）、delete（删除）、move（移动/重命名，会重写引用它的文档；对于技能，还可以使用 scope/toScope 在项目级和全局级之间移动——历史记录会重置，需要重新 install）。输出会镜像输入的目标键；预览信封（previewUrl、warning）保持在顶层。此外还有 install（将技能的草稿安装到你的编辑器中——在 write({ skill }) 之后运行）、checkpoint（创建命名版本）、restore_version（回滚到某个版本）。文件夹的前置元数据是开放形状的且仅作用于自身（不会级联）；模板是创建新文档时的初始内容。编写/改进一个技能？请调用 open-knowledge-write-skill（概要第 6 条），不要自行操作。
• 冲突处理——conflicts（kind: list|content）、resolve_conflict（编写解决方案并提交；具有破坏性）。请参见 references/conflict-resolution.md。
• 工作流——workflow（kind: ingest|research|consolidate|discover；流程指南，并非数据）。请参见 references/workflow-guides.md。

自我纠错机制： JSON Schema 无法表达的约束（如“恰好一个目标”、“find 需要配合 replace”、“正文与前置元数据互斥”）会返回 isError: true 以及一个包含正确形状的单行提示。读取该提示并使用正确的形状重试，不要猜测。

不是 OK MCP 的工具（属于宿主平台的工具）：preview_start、preview_screenshot、WebFetch、WebSearch、原生的 Read / Grep / Glob / Edit。关于哪些工具可以对范围内的 Markdown 文件使用，请遵守 STOP 规则。

STOP——禁止对范围内 .md / .mdx 文件使用原生工具

将对范围内 Markdown 文件的每次读取和写入操作都路由到 OK 的 MCP 工具——绝对不要使用宿主平台的原生文件工具。 在范围内的 Markdown 文件上使用原生的 Edit / sed / 直接 Write 会绕过 CRDT，并在影子仓库中丢失代理归属；原生读取操作会跳过 OK 为每个匹配文件返回的前置元数据、反向链接、影子仓库活动以及项目 git 历史记录。当工作空间已配置 OpenKnowledge MCP 时，请不要对内容目录内的 Markdown 文件路径使用原生文件工具。此禁令涵盖所有常见的合理化借口：

• 在范围内的 .md / .mdx 文件上使用原生的 Read / Grep / Glob——这是原始案例。
• 在包含范围内 Markdown 文件的目录上使用 Bash ls / Bash find / Bash cat——请使用 exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …")。原生工具只返回裸名称；exec 则返回前置元数据、反向链接计数和近期活动。-A 参数可以显示隐藏条目（.ok/、.okignore），且没有 ./.. 干扰。
• 匹配 Markdown 文件的 Glob 模式（**/*.md、specs/**、reports/**、docs/**）——请使用带 find 的 exec 或 exec("ls -A <dir>")。
• 将 Explore/通用子代理用于以 Markdown 为主的探索——子代理内部会使用原生工具并绕过 OK。请自己通过 exec / search 进行 Markdown 探索。子代理仍然适合用于源代码探索。
• 对 .ok/ 目录下范围内的 Markdown 文件使用原生的 Read / Grep——.ok/ 目录本身也是范围内的内容，应将其中的 .md / .mdx 文件视作其他知识库文件。
• 使用 ls / cat / find 访问 .ok/skills/ 目录来发现或读取技能——.ok/skills/ 是不透明的内部状态；技能通过 name+scope 寻址，不是通过路径。请使用 skills 工具（省略 name 可列出项目和全局范围内的所有技能，传入 name 可读取某一个）；绝对不要浏览 .ok/skills/... 路径。

MCP 工具可见性——看不到 exec 并不等于可以回避。 MCP 的配置方式因客户端而异（Claude Code、Cursor、Codex、Windsurf、VS Code）。服务器标签由用户定义；工具可能不会以名为 exec 的顶层符号出现。如果 OpenKnowledge 在此处被注册为 MCP 服务器，请通过你客户端文档中规定的 MCP 调用方式（包括任何通用的“调用 MCP 工具”流程）将 Markdown 读取操作路由到它的 exec / search 工具。判断依据是是否已注册，而不是顶层符号是否可见。

初始工具列表并非详尽无遗——在得出结论说 MCP 缺失之前，请先运行工具发现机制。 某些客户端（特别是 Codex）会将 MCP 工具推迟到懒加载的 tool_search / 工具发现步骤之后，因此 mcp__open-knowledge__* 在初始工具集中不存在，只有在搜索后才会出现。在可见列表中的缺失意味着“我尚未发现它”，而不是“它未注册”。如果看不到工具，你的第一步是运行客户端的工具发现 / tool_search 来搜索 open-knowledge（或 exec / search / write）——不要从初始列表中推断其不可用。

逃生舱。 仅在以下情况下允许对 .md / .mdx 文件使用原生的 Read / Grep / Glob：在运行了工具发现机制（见上文）后，确认该项目没有注册任何 OpenKnowledge MCP 服务器；或者在你实际调用了一次 MCP 调用且它失败之后——此时，请以用户可见的一句话开头说“OpenKnowledge MCP unavailable:”。你只有在工具发现机制返回空结果后，才能得出“未注册”的结论——绝不要仅凭初始工具列表就下结论。绝不要因为你跳过了客户端的 MCP 路径、没有看到 exec 作为顶层工具、没有运行工具发现机制、或认为此技能非必需而使用逃生舱。

源代码和非 Markdown 文件（.ts、.py、package.json 等）：始终可以使用原生的 Read / Grep / Glob 工具。

读取操作——示例

• 读取文件：exec("cat <path>.md")——返回内容 + 全部增强信息。
• 列出目录：exec("ls -A <dir>")——返回每个子项的前置元数据、递归 Markdown 文件计数、每个子目录中最近更新的文档、文件夹自身的 title/description/tags 以及 templates_available。建议使用 -A 而不是普通的 ls。
• 精确搜索：exec("grep -rn <term> <dir> | head -5")——返回匹配结果及匹配文件的增强信息。
• 排序搜索：search({ query })——标题权重提升 + 正文 BM25 排序 + 时效性考量；适合在挑选最佳文档时使用，而不是在需要列出所有出现位置时使用。

写入操作

一旦你有了内容，就立即调用 write / edit（根据 STOP 规则通过 MCP 进行）。

增量持久化——知识库就是你的检查点（强制要求）。 在任何多步骤或长时间运行的任务中（如研究扫描、多源综合、批量文档处理），请在完成每个单元后立即将完成的工作写入知识库：按章节、按来源、按文档进行。绝不要仅仅将完成的研究结果保留在你的上下文中，等待到最后一次性写入。速率限制、崩溃或上下文中途压缩会丢弃所有尚未写入的内容；已经持久化的工作可以存活下来，而你可以通过读取文档来恢复。尽早创建目标文档（骨架 + 前置元数据），然后在每个部分确定后使用 edit 逐步写入。

每次内容写入时请提供 summary（建议遵守） ——这是一个单行（不超过 80 个字符）面向用户的变更说明，会成为时间线条目。善用可视结构（Callout、mermaid 图表、表格、html preview），尤其是在这些结构比纯文本更能传达要点的地方；在创作时调用 palette。关于写入警告、MDX 创作、删除/移动机制和可视创作的更多信息，请参见 references/writing.md + references/components-and-visuals.md + references/media-and-assets.md。

引用溯源——每个事实声明都需要一个来源（强制要求）

知识库文档是事实性的人工产物。每个声明必须是可追溯的，并且来源必须存在于知识库内部，而不是飘浮在公共网络上。

• 知识库是权威信息来源——闭环。 外部来源不会被直接引用到外部网站；它们会通过 ingest 被拉入本地，然后在文档内部引用。知识库文档中一个裸露的 [source](https://...) URL 并不是一个完成的引用——它只是一个 TODO，表示“此来源尚需要被摄入”。只有当每个叶子节点都是本地文档时，这个链条才算完整。
• 每个事实声明必须在其声明点处引用其来源。不允许没有来源的推测。
• 用于知识库文档的网页来源 → 获取该页面（使用宿主平台的 WebFetch / WebSearch），然后通过 ingest 将其作为本地文档摄入，最后引用本地路径：[source name](./path/to/source.md)（本地文档会在其 source_url: 字段中携带原始 URL）。内联的 [source](URL) 是聊天中的便捷方式，而非知识库中的标准做法。
• 自行获取也视为有效。 当你为了将某个声明落地到知识库而获取了一个 URL 时，该获取行为会触发 ingest，就像用户分享一样——不要因为获取是由代理发起的就降级为内联 URL 引用。
• 内部交叉引用 → 使用标准 Markdown 链接指向包含权威声明的 OK 文档；该文档必须引用其自身的来源（链条终止于被保留的本地文档）。
• 如果你没有证据： 进行一次网络搜索并用 ingest 摄入搜索结果，或者在文档中标注 (TODO: needs source)，或者不写这个声明。不要捏造来源。没有来源的推测会腐烂成无法追踪的“部落知识”。

链接——使用标准 Markdown 链接（强制要求）

链接每一个指向其他文档的名词短语——[text](./relative/path.md)——并且要广泛使用链接。每个链接在完成时都必须指向一个实际存在的文档（在同一轮次中，稍后才会创建的前向引用是可以的；对于确实不存在的文档，请将提及的部分保留为纯文本，并添加一个待办任务）。绝对不要在链接周围使用反引号（`[text](./foo.md)` 是一个错误），也不要使用 HTML <a> 标签。在每次 write/edit 响应中检查 brokenLinks： [] 表示所有链接都能解析；如果列表不为空，则会列出每个损坏的 href 及其 reason（no-such-doc / no-such-file / unresolvable）——请通过后续的 edit 修复它们。links({ kind: "dead" }) 是权威的最终状态审计（编辑器中的红色下划线对 slug 名称容忍性较高且可能不准确，所以请相信工具本身）。外部网页来源不是内联正文链接（请参见“引用溯源”）。完整的规则集以及关于 [[Page]] 旧有语法的说明，请参见 references/linking.md。

文件夹、前置元数据、模板

每个 .md / .mdx 文件都需要 YAML 前置元数据——title + description 为必需，tags 为推荐。两个可选且嵌套的文件夹机制：文件夹前置元数据（<folder>/.ok/frontmatter.yml —— 文件夹自身的开放形状属性；仅作用于自身，不会级联到子目录或文件）和文件夹模板（<folder>/.ok/templates/ 目录下的 .md 文件）。创建新文档时，OK 会检查是否有名为 _default 的模板，并将其内容作为起始内容。templates_available 会在 ls -A 和 search 响应中列出。palette({ components }) 可以提供 JSX 模式的模板。更多信息请参见 references/frontmatter-and-folders.md。

冲突解决

当两个代理同时编辑同一个文档时，OK 的 CRDT 层会检测到冲突。使用 conflicts({ kind: "list" }) 列出所有未解决的冲突，使用 conflicts({ kind: "content", doc: "<path>" }) 查看特定冲突的详细信息。要解决冲突，请使用 resolve_conflict({ document: { path }, resolution: "<合并后的内容>" })。此操作具有破坏性——它将用提供的解决方案原文替换冲突的内容并提交。完整的策略和最佳实践请参见 references/conflict-resolution.md。

配置与状态

OK 的行为由项目根目录下的 .ok/config.yml 配置文件控制。使用 config 工具（config({})）来读取已解析的配置，它将合并所有层级（默认值、用户级、项目级）的选项。关键的配置选项包括：contentDir（默认为 .，即项目根目录）、ignore（类似 .gitignore 的模式列表）、mcpServerName（MCP 服务器的标签）等。技能状态存储在 ~/.ok/skill-state.yml 中，可以使用 cat 命令查看。

版本控制

OK 会维护一个影子 Git 仓库来跟踪所有变更。使用 history({ document: "<path>" }) 来查看文档的版本历史。使用 checkpoint({ document: "<path>", name: "<版本名称>" }) 来创建一个命名版本。使用 restore_version({ document: "<path>", version: "<版本标识符>" }) 回滚到特定版本。版本控制集成在 CRDT 层之上，因此即使在协作场景中也能保持一致性。

故障排除

• 工具未显示： 运行客户端的工具发现机制（如 tool_search）来查找 OpenKnowledge 工具。如果仍然看不到，请检查 .ok/config.yml 中的 MCP 配置，或参考 references/setup.md 进行设置。
• 写入失败： 检查 isError 响应以获取格式说明。常见的错误包括：未为内容写入提供 summary、未提供恰好一个目标，或在 edit 调用中同时提供了 find/replace 和 frontmatter。
• 链接损坏： 读取 write/edit 响应中的 brokenLinks 属性，并修复指的路径。使用 links({ kind: "dead" }) 进行完整审计。
• MCP 调用失败： 如果经过工具发现和调用尝试后 MCP 调用失败，你可以使用逃生舱（参见 STOP 规则），但必须以 OpenKnowledge MCP unavailable: 开头向用户说明。

参考文件

此目录中的 references/ 子目录包含了更深入的指南和约定。当相关任务出现时，请加载对应的参考文件。关键参考文件包括：

• references/setup.md —— 初始设置和配置
• references/preview.md —— 预览 URL 和浏览器集成
• references/corpus-qa.md —— 直接问答工作流
• references/writing.md —— 写入操作和最佳实践
• references/components-and-visuals.md —— MDX 组件和可视结构
• references/media-and-assets.md —— 媒体和资产处理
• references/linking.md —— 链接规则和约定
• references/frontmatter-and-folders.md —— 前置元数据和文件夹管理
• references/conflict-resolution.md —— 冲突解决策略
• references/workflow-guides.md —— 工作流指南（ingest、research、consolidate、discover）

---

此技能文档与 @inkeep/open-knowledge-server 版本的 OpenKnowledge 平台保持同步。