open-knowledge-discovery

OpenKnowledge — 介绍与安装方法

OpenKnowledge（OK）是一个基于 Markdown CRDT 的协作平台。它能将包含 .md / .mdx 文件的目录转化为实时、多写入者协作的知识库：Agent 和用户可以实时编辑同一份文档，每项更改都会标明作者，浏览器预览会在编辑内容写入时即时渲染。

本技能介绍如何发现、安装 OpenKnowledge，以及打开 OpenKnowledge 文件——包括不属于项目的单个文件（见下文 打开项目外的文件）。本技能不包含项目内读写运行时约定（例如原生文件工具的 STOP 规则、依据和链接规则，以及 MCP 路由表）——这些内容由 ok init 安装的项目本地技能单独提供（见下文 在项目中工作）。

CLI 名称。 下文命令使用 Stable 版的 ok（open-knowledge）。OpenKnowledge Beta 的终端命令为 ok-beta（open-knowledge-beta），并使用 ~/.ok-beta/ 替代 ~/.ok/。

在代码仓库中安装 OpenKnowledge

在代码仓库根目录运行 ok init：

npx @inkeep/open-knowledge init
# or, after a global install:
npm install -g @inkeep/open-knowledge
ok init

ok init 是唯一的设置命令。它会：

• 创建 .ok/ 目录（项目配置——content.dir 默认为 .）；
• 将 OpenKnowledge MCP 服务接入它在本机检测到的编码 Agent——使用 --no-mcp 可跳过此步骤；
• 将项目本地运行时技能安装到每个已检测到的 Agent 的技能目录（<agent-dir>/skills/open-knowledge/），让在此代码仓库中工作的 Agent 获得完整的读写约定。OK 只会写入已经存在的 Agent 目录——不会创建目录，因此你未使用的 Agent 不会出现相关文件；如果没有检测到任何 Agent，ok init 会说明这一点；
• 确保项目包含 .git/。

你可以随时重新运行 ok init，将接入配置和技能更新到已安装的 CLI 版本。

与协作者共享 OpenKnowledge 项目

OK 项目会随代码仓库一起移交。共享方法如下：

1. 提交 .ok/ 目录、ok init 创建的项目本地 <agent-dir>/skills/open-knowledge/ 目录，以及 .md 内容。
2. 协作者克隆代码仓库后，运行一次 ok init——此命令会在其本机注册 MCP 服务并更新项目技能。
3. 运行 ok start 启动编辑器和预览，或在 OK Desktop 中打开项目。

当两位写入者都打开了项目，并连接到同一个内容目录时，即可实时协作。

ok cowork — Claude Chat 和 Cowork

ok init 对编辑器的接入配置无法覆盖 Claude Chat 或 Cowork——它们会读取 Claude Desktop App 中单独的技能列表。运行 ok cowork 生成 openknowledge.skill 并打开 Claude Desktop，随后用户即可上传该技能（Customize → Skills → + → Create skill → Upload skill）。

OK Desktop

OK Desktop 是独立的 macOS 应用（@inkeep/open-knowledge-desktop）。它内置 CLI，可将项目作为编辑器和预览窗口打开，并在每次启动时更新项目的 MCP 接入配置和技能。可从发布页面下载 DMG。

打开项目外部的文件

OpenKnowledge 可以打开单个 Markdown 文件，即使它不属于 OK 项目——可以是独立的 .md / .mdx 文件，也可以是位于普通 仓库/文件夹中的文件（该仓库/文件夹从未运行过 ok init）。它会在一次性会话中打开（在操作系统临时目录中创建临时项目——不会触碰你的仓库，也不会在其中写入 .ok/），并提供与项目内相同的实时预览。

切勿仅为了查看或打开文件而运行 ok init。 ok init 会将仓库转换为共享的 OpenKnowledge 项目；它不是打开单个文件的前提条件。打开文件不需要项目、不需要 .ok/，也不需要已运行的服务——以下每种方式都会自行启动会话。

当用户要求打开或预览此类文件时，应根据你实际拥有的查看界面来决定——检查工具，而不是主机名称。只有确实有浏览器时才打开浏览器；绝不要在没有浏览器的主机上弹出浏览器标签页。

• 你有应用内/内置浏览器（Claude Code Desktop 的 Browser 窗格、Cursor、Codex 等）——这是默认方式：调用 preview_url MCP 工具，将 file 设为绝对路径（它会查找会话，或按需启动会话，并返回完整的 url），然后立即在应用内浏览器中打开该 url。“打开它”意味着导航到该页面——不要只打印 URL 就停下。这也是安装了 OK Desktop 应用时在浏览器中查看文件的唯一方式（ok open 会优先使用 Desktop 应用）。只能从 preview_url 获取 URL——绝不要通过 ok ps / ok status / ok start 查找，也不要猜测端口。
• 没有应用内浏览器（纯 stdio CLI）——运行 ok open /abs/path/to/file.md：如果已安装 Desktop 应用，就会打开该应用；否则会打开浏览器，并自行启动会话。不要强行打开用户未要求的浏览器标签页；此时默认应使用 ok open。如果 ok 不在 PATH 中，npx @inkeep/open-knowledge open /abs/path/to/file.md 也能完成相同操作。

如果此主机未接入 OK MCP 服务，就无法调用 preview_url——请使用上述 ok open 方式。不要手动重现 preview_url 的操作（例如自行启动 ok mcp，或从 ok ps 中抓取端口）。

请提供绝对路径。ok open 会打印它为该路径解析出的绝对项目根目录；如果解析出的根目录位于另一个项目内，也会标明外层项目。请阅读该行，而不要臆测实际打开的是哪个项目。

若要自行指定项目名称，请传入 --project <dir>。无论它出现在哪里都会生效：可以是 --project <dir> 或 --project=<dir>，可以放在路径之前或之后，也可以带 .md 扩展名或不带。如果无法按指定方式执行，该命令会以非零状态退出并说明原因，因此你无需再运行第二条命令来确认文件打开的位置，也无需停止服务后再修正。

再次打开同一个文件会进入同一个会话。绝不要构造或猜测 URL——请使用 preview_url 返回的 URL。

OK 还能做什么

此技能不会罗列 OK 的功能，而且功能可能会随版本发布而变化。有人询问 OK 是否支持某项功能时，请查阅资料，而不要猜测：

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

在项目内工作——使用项目本地技能，而非此技能

请勿使用此技能执行 OpenKnowledge 读取或写入操作。运行时约定——针对作用范围内 Markdown 的原生文件工具 STOP 规则、预览挂接握手、依据来源和链接规则，以及 MCP 工具路由表——都位于单独的项目本地技能中。每次运行 ok init 时，该技能都会安装到每个检测到的 Agent 的技能目录（<agent-dir>/skills/open-knowledge/SKILL.md）中。

如果用户正在编辑项目内的 Markdown，且该项目包含 .ok/ 目录，但当前仅加载了此发现技能，则说明缺少项目本地技能（该仓库从未运行过 ok init，或技能目录未提交）。请建议用户运行 ok init 进行安装。

了解更多

• 运行 ok --help 查看完整命令列表。