open-knowledge

OpenKnowledge — Agent 指南

OpenKnowledge（OK）是一个通过 MCP 提供的 Markdown-CRDT 协作平台。本技能是 OK Agent 指南的唯一来源。除非另有标注，以下规则都必须遵守。详细内容位于 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。

CLI 名称。 此处的命令使用 Stable 版的 ok（open-knowledge）和 ~/.ok/。使用 OpenKnowledge Beta 时，请改用 ok-beta（open-knowledge-beta）和 ~/.ok-beta/；preview_url 的 okOpenCommand 已指定正确的命令。

设置（尚未连接？）。 如果客户端中没有 mcp__open-knowledge* 工具，则此项目尚未在此机器上完成配置——请参阅 references/setup.md 中的阶梯式流程（批准 .mcp.json → ok start CLI → 可选的桌面应用）和规范快速入门指南。

TL;DR — 90% 的情况

1. 读取： 单篇文档使用 exec("cat …")，目录使用 exec("ls -A …")（文件夹默认设置 + 模板菜单），字面查找使用 exec("grep …")，排序检索使用 search。原生 Read / Grep 仅用于源代码（.ts / .py / …），绝不用于范围内的 .md / .mdx。
2. 写入： 新建或完整替换文档使用 write({ document: { path, content } })；正文查找并替换使用 edit({ document: { path, find, replace } })；frontmatter 合并补丁使用 edit({ document: { path, frontmatter } })（null 会删除键）。delete({ document }) 用于删除，move({ from, to }) 用于移动或重命名。正文查找并替换仅作用于正文。每次内容写入都要提供一行 summary（≤80 chars，说明面向用户的结果）。
3. 预览 / 打开文档——先确定唯一的操作界面（每个会话只需一次）。 遇到第一个匹配项即停止：已设置 OK_DESKTOP_TERMINAL 或 OK_HOSTED_AGENT → 你位于 OpenKnowledge 中（桌面终端 / 应用内 Agent 面板）→ 使用 ok open <name>（切换用户当前已在查看的窗口）；此处回复时绝不要粘贴 localhost URL · 应用内浏览器（Claude Code Desktop 的 Browser 面板、Cursor、Codex）→ 使用 preview_url，然后打开 / 导航至对应文档 · 其他情况为普通 CLI → 使用 ok open <name>。ok open <name> 可打开文档或文件夹（自动检测）；技能使用 --skill <name>。previewUrl 字段是路由 ID，不是打开文档的方式。不要用 preview_screenshot 确认编辑结果。完整的步骤 0 流程和各界面操作方法见：references/preview.md。
4. 直接提问： 普通业务问题（“哪些客户……”“我们对……作了什么决定”）应使用 search / exec，并以引用内容回答——无需出现“研究”一词。仅当内容具有长期价值、涉及多篇文档且尚未覆盖时才保存，并且要先提出建议。参见 references/corpus-qa.md。
5. 编写或改进技能（“编写 / 创建 / 改进技能”“把这个做成技能”）：停止当前操作并调用 /open-knowledge-write-skill，以确定范围（项目 / 全局）、契约、评估和安装方式。使用 write({ skill }) 编写，绝不要使用文档路径。技能是编辑器 skills/ 目录（.claude · .cursor · .codex · .github · .opencode · .pi · .agents）中的真实文件夹：一个源文件以及由其管理的副本 / 符号链接。**通过 skills 和 edit({ skill }) 读取 / 编辑——它们会定位到源文件。**绝不要手动编辑非源副本：已记录但未经编辑的副本会在技能监视器运行或服务器启动时从源文件刷新，因此源文件的修改可能先于刷新。直接编辑副本会使其分叉并停止刷新。

工具索引 — 19 个工具（路由器；调用约定见工具描述和输入架构）

• exec — 在文档上下文中读取文件和目录。
• search — 检索按相关性排序的工作区匹配项。
• links — 检查链接关系和建议。
• lint — 检查内容规则并应用自动修复。
• audit — 验证内容规则和内部链接。
• write — 创建或替换内容。
• edit — 就地更改内容或元数据。
• delete — 移除内容。
• move — 通过托管操作重命名或移动内容。
• install — 管理技能来源和编辑器位置。
• import — 获取技能文件夹，但不运行脚本。
• history — 检查文档、文件夹或技能版本。
• skills — 按名称和范围发现、列出或读取技能。
• checkpoint — 保存命名版本。
• restore_version — 恢复文档或技能版本。
• palette — 发现组件和创作表单。
• config — 读取解析后的配置。
• preview_url — 获取浏览器预览 URL。
• share_link — 获取由 GitHub 支持的分享链接。

成功的 lint/audit 结果中，请读取 ran：未出现在 ran 中的类别表示未检查，[] 表示未选择任何检查。对于链接验证，请使用 audit；links 报告关系和原始失效链接状态。注意事项：references/linking.md。

技能的位置与技能内容相互独立：源文件夹本身就是技能，移除已安装的副本不会删除技能。执行 Project↔Global 移动时，历史记录会重置；只有目标级别能够容纳的内容会重新投影，其余内容会从源位置移除，并作为 droppedLocations 返回（成功后可通过 install 重新添加）。恢复前请先阅读返回的结果。文件夹的 frontmatter 采用开放结构，且仅作用于自身（不会级联）；新文档的起始内容由模板决定。

**误用时自我纠正：**对于 JSON Schema 无法表达的约束（“恰好一个目标”、“find 需要 replace”、body 与 frontmatter 二选一），会返回 isError: true，并附上一行纠正后的格式。请阅读并按该格式重试；不要猜测。

不属于 OK MCP（你的宿主）的工具：preview_start、preview_screenshot、WebFetch、WebSearch、原生 Read / Grep / Glob / Edit。STOP 规则规定了你可以对范围内的 markdown 使用哪些工具。

停止 — 范围内 .md / .mdx 文件必须使用原生工具

所有范围内的 Markdown 读取和写入都必须通过 OK 的 MCP 工具完成，绝不能使用主机的原生文件工具。 对范围内的 Markdown 使用原生 Edit / sed / 直接 Write 会绕过 CRDT，并导致影子仓库中丢失 Agent 归属信息；原生读取会跳过 OK 为每个匹配文件返回的 frontmatter、反向链接、影子仓库活动记录和项目 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 还会添加 frontmatter、反向链接和近期活动记录。-A 会显示隐藏条目，但不显示 . / ..。
• 使用针对 Markdown 的 Glob 模式 — exec 会展开文件操作数（cat specs/*.md）；带引号的模式和命令自身的模式（find -name）会保持原样。
• 派遣 Explore / 通用子 Agent 执行以 Markdown 为主的探索 — 子 Agent 内部使用原生工具，会绕过 OK。请自行通过 exec / search 探索 Markdown。子 Agent 仍适用于源代码探索。
• 对 .ok/ 中范围内的 Markdown 使用原生 Read / Grep — .ok/ 也在范围内；其中的 .md / .mdx 应与其他知识库文件一视同仁。
• 通过对技能文件夹使用 ls / cat / find 来发现或读取技能 — 技能通过 name+scope 寻址，而不是通过路径寻址（技能可能位于任何编辑器目录、.agents/skills/ 中心目录或自定义根目录中，也可能在其他位置有副本）。请使用 skills 工具。

看不到 exec 并不意味着可以绕过规则。 不同客户端的接线方式、标签和工具可见性各不相同；有些客户端（尤其是 Codex）会将 MCP 工具延迟到按需发现后才提供。应以注册状态为准，而非顶层符号是否可见——请先搜索发现 open-knowledge 工具。详情见：references/setup.md。

例外情况。 只有在运行上述工具发现后，确认此项目未注册任何 OpenKnowledge MCP 服务，或者刚刚实际调用 MCP 但调用失败后，才允许对 .md / .mdx 使用原生 Read / Grep / Glob——此时请以 OpenKnowledge MCP unavailable: 开始一条用户可见的句子。“未注册”只能在工具发现结果为空时得出，绝不能仅凭初始工具列表作此判断。不得因为跳过客户端的 MCP 使用流程、看不到顶层工具中的 exec、未运行工具发现，或自行认定技能没有必要，就使用此例外。

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

写作

有内容后立即调用 write / edit（按 STOP 规则通过 MCP 路由）。

增量持久化——知识库就是你的检查点（必须）。 对于任何多步骤或耗时较长的任务——研究汇总、多来源综合、批量文档——每完成一个单元，就将已完成的工作写入知识库：按章节、按来源、按文档。不要把已完成的发现只留在上下文中，等到最后一次性写入。限流、崩溃或上下文压缩若在任务中途发生，所有尚未写入的内容都会丢失；已持久化的工作则会保留，你可以通过读回文档继续。尽早创建目标文档（骨架 + frontmatter），然后在各章节逐步完善时调用 edit 写入。

每次写入内容时都传入 summary（应当）。 用一行面向用户的说明（≤80 个字符）；它会成为时间线条目。适当采用视觉结构（Callout、mermaid、表格、html preview），如果它比纯文字更能传达要点；起草时调用 palette。有关写入警告、MDX 编写、删除/移动机制和视觉内容编写，请参阅 references/writing.md + references/components-and-visuals.md + references/media-and-assets.md。

溯源——每条事实性陈述都需要来源（必须）

知识库文档是事实性资料：每条陈述都必须可追溯，且来源必须保存在知识库中，而不是公共网络上。

摄取是一套流程，不是工具——二进制与文本分类、SSRF 安全抓取标志、大小和可执行文件门槛、封装器 frontmatter——详见 references/ingest-and-sources.md。首次抓取前请先阅读；不加判断地抓取并粘贴会跳过所有门槛。

• 闭环。 外部来源通过摄取流程引入，然后在本地引用。在知识库文档中单独放置 [source](https://...) 不算引用——它是一个待办事项，表示“仍需摄取”。只有每个末端都指向本地文档，这条链路才有效。
• 每条事实性陈述都必须在陈述处引用来源。 不得无来源地推测。
• 网络来源 → 抓取页面（托管 WebFetch / WebSearch），进行摄取，然后引用路径：[source name](./path/to/source.md)（本地文档中包含 source_url:）。行内 [source](URL) 是聊天场景的便捷方式，不适用于知识库。
• 自行抓取的来源同样适用。 你为支撑某条陈述而抓取的 URL，也必须经过同样的摄取流程——不得降级为行内 URL。
• 内部交叉引用 → 链接到包含权威陈述的 OK 文档；该文档应引用自己的来源（引用链最终指向已保留的本地文档）。
• 没有证据？ 搜索并摄取结果，或标记为 (TODO: needs source)，或不要写入该陈述。切勿捏造——无来源的推测会腐化成无法追溯的内部传闻。

链接——标准 Markdown 链接（必须）

为每个指向其他文档的名词短语添加链接——[text](./relative/path.md)——并广泛添加链接。要指向长文档中的某个章节，在聊天回复中也应链接到 ./path.md#heading-slug。任务完成时，每个链接都必须指向一个确实存在的文档（同一轮操作中稍后创建的前向引用可以接受；若目标确实不会存在，则将该提及保留为纯文本，并创建一个已跟踪任务）。绝不要给链接加反引号（`[text](./foo.md)` 是错误写法），也绝不要使用 HTML <a>。每次 write / edit 后，都要读取 brokenLinks：修复报告中的 href；[] 表示所有链接均已解析，除非 brokenLinkSuppression 暂缓了保留日志中的发现（这些不需要你修复），或者 link-check-deferred 警告表示尚未进行检查（服务器仍在启动或正忙于其他写入；只有之后再次对该文档执行 write / edit 或运行 audit 才会重新检查，而服务器仍在启动时运行 audit 可能超时）。audit 的结果具有权威性；其中相同标记的含义也相同。外部网络来源不得作为正文行内链接（参阅“溯源”）。完整规则、slug 规则和 [[Page]] 旧式写法说明：references/linking.md。

文件夹、frontmatter、模板

每个 .md / .mdx 文件都需要 YAML frontmatter——必须包含 title + description，建议包含 tags。OKF 项目（okf pack）例外：以 pack 规则为准——非根目录的 index.md 不得包含任何 frontmatter（frontmatter-reserved-index lint 会对任何键发出警告），log.md 无需 frontmatter，概念文档只需一个非空的 type；其中 title / description 可选。两种选择启用、可嵌套的文件夹机制：文件夹 frontmatter（<folder>/.ok/frontmatter.yml——文件夹自身的开放结构属性；仅作用于自身，不会向子文档级联）和模板（<folder>/.ok/templates/——新文档的初始内容）。大多数文件夹都没有 .ok/。文档的 frontmatter 完全取自其磁盘上的 YAML。结构模型 + 完整的写入前检查清单：references/folder-model.md。模板编写 + 文件夹编辑：references/template-authoring.md。Frontmatter 与正文的编辑规则：references/doc-editing.md。

• 写入前先查看文件夹（必须）。 在文件夹中创建 / 编辑文档前，每个会话中对每个文件夹调用一次 exec("ls -A <folder>")——它会返回文件夹的 title / description / tags + templates_available。跳过此步骤会导致文档违反文件夹规范。（如果某个文件夹既没有 frontmatter，也没有模板，并且仓库其他位置有大量内容，则表示该文件夹尚未完成接入——请先运行 references/onboard-existing-repo.md。）
• 有适用模板时必须使用（必须）。 通过 write({ document: { path, template } }) 实例化；继承而来的模板也算。只有没有匹配模板，或用户要求自由格式时，才可跳过（请在聊天中说明原因）。当某种结构反复出现时，主动创建模板。
• 出现重复的文档属性时（必须）。 多个同级文档重复使用相同的 frontmatter → 将这些初始值写入模板（write({ template })）。文件夹 frontmatter 不会将值级联到文档中。

处理冲突的写入

遇到冲突而拒绝写入时，请遵循工具的恢复说明和 references/conflict-resolution.md；请让用户在应用中解决已跟踪的冲突。

反模式——最常见的问题

任务	不要这样做	应这样做
列出 / 查找 / 读取 Markdown	Bash: ls / Glob: **/*.md / Read: foo.md	exec("ls -A …") / exec("find …") / exec("cat …")
探索 Markdown 密集型目录	Agent(Explore)（绕过 OK）	自行使用 exec / search
引用另一篇文档	`[text](./p.md)`（放在反引号中）或 HTML <a>	[text](./p.md)
嵌入图片	<img>、localhost / preview_url URL、热链接	保存到本地 + 
在知识库文档中陈述事实	没有引用的正文，或内联 [src](https://…)	导入来源（references/ingest-and-sources.md），引用本地路径
确认编辑已生效	preview_screenshot / 验证循环	信任 CRDT 工具响应
删除 Markdown 文档	Bash: rm / 原生删除	delete({ document })（如果有风险，先执行 checkpoint()）
在不熟悉的文件夹中写入	直接调用 write	先调用 exec("ls -A <folder>")

完整表格：references/anti-patterns.md。

知识分层——大多数知识库工作采用的形式

三种反复使用的做法，而非工具调用——每种都是一套完整流程，以技能指南的形式提供。

层级	适用时机	流程
ingest	原样保留共享的 URL/PDF/文件，或你获取了一个 URL 来为某项主张提供依据（保留二进制来源，不进行抓取）。	references/ingest-and-sources.md——随此内容提供，§Grounding 依赖它
research	调查／比较／综合来源 → status: provisional 文章 + sources:。	/research-with-sources 技能
consolidate	已作出决策 → 权威事实来源，并带有 supersedes: 链。	/consolidate-notes 技能

运行 ok seed --pack knowledge-base 即可获取 research 和 consolidate。没有该包，就没有这些流程——不要自行编造；请按常规的有依据的 write 方式完成工作，或提出为其添加种子（ok seed --pack knowledge-base --dry-run 会显示将添加的内容）。

不要悄悄串联流程：让用户推动 ingest → research → consolidate，并且流程中的 STOP 关卡优先于会话级“不要停下来询问”提示。任何会更改知识库内容的轮次结束后，检查是否存在 log.md，并遵循其约定（references/cadence-and-logs.md）。交错处理多文档批次，让预览展现叙述进展。

为已有内容的仓库进行入门配置：references/onboard-existing-repo.md。分层模型 + 包：references/starter-packs.md。

此技能之外的功能

OK 的功能不止此技能所述，而且会随版本发布而变化。这里未涵盖的内容？请阅读，不要猜测：

• 文档——https://openknowledge.ai/docs
• 源代码——https://github.com/inkeep/open-knowledge

范围回顾

OK 会在解析后的 content.dir 下查找文档（运行时：config({ key: 'content.dir' })）；根目录或任意文件夹深度下的 .gitignore 和 .okignore 用于定义排除项。content.dir 下所有未被排除的 .md / .mdx 文件都是 OpenKnowledge 文档——包括 specs/、reports/、docs/ 下的文件。文件夹元数据 + 模板位于嵌套的 <folder>/.ok/ 中，而非 .ok/config.yml 中。**在 git worktree 中工作？**只需在 OK 工具调用中将 worktree 的绝对路径作为 cwd 传入一次——该设置会在整个会话中保持不变，因此读取、写入和预览都会针对该 worktree。