open-knowledge-discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenKnowledge — what it is and how to install it

OpenKnowledge — 是什么以及如何安装它

OpenKnowledge (OK) is a markdown-CRDT collaboration platform. It turns a directory of

.md

.mdx

files into a live, multi-writer knowledge base: agents and humans edit the same documents in real time, every change is attributed, and a browser preview renders edits as they land.

This skill covers discovery, install, and opening OpenKnowledge files — including single files that are not part of a project (see Opening a file outside a project below). It does not carry the in-project read/write runtime contract (the STOP rules for native file tools, the grounding and linking rules, the MCP routing table) — that ships separately as the project-local skill installed by

ok init

(see Working inside a project below).

OpenKnowledge（简称OK）是一个基于markdown-CRDT的协作平台。它将一个包含

.md

.mdx

文件的目录转换为一个实时的多写者知识库：Agent和人类可以实时编辑同一文档，每一处更改都会被标记归属，并且浏览器预览会在更改完成后立即渲染出来。

本技能涵盖OpenKnowledge的发现、安装以及打开文件——包括不属于任何项目的单个文件（见下文“打开项目外的文件”）。它不包含项目内的读写运行时协议（原生文件工具的STOP规则、锚定与链接规则、MCP路由表）——这些内容会作为

ok init

安装的项目本地技能单独提供（见下文“在项目内工作”）。

Install OpenKnowledge on a repository

在代码仓库中安装OpenKnowledge

Run

ok init

from the repository root:

bash

npx @inkeep/open-knowledge init

在仓库根目录运行

ok init

：

bash

npx @inkeep/open-knowledge init

or, after a global install:

或者，全局安装后：

npm install -g @inkeep/open-knowledge ok init


`ok init` is the one setup verb. It:

- scaffolds a `.ok/` directory (project config — `content.dir` defaults to `.`);
- wires the OpenKnowledge MCP server into detected editors (Claude Code,
  Cursor, Codex) — skip with `--no-mcp`;
- installs the **project-local runtime skill** at `.claude/skills/open-knowledge/`
  and `.cursor/skills/open-knowledge/` so agents working in this repo get the
  full read/write contract;
- ensures the project has a `.git/`.

Re-run `ok init` any time to refresh wiring and skills to the installed CLI
version.

npm install -g @inkeep/open-knowledge ok init


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

- 生成`.ok/`目录（项目配置——`content.dir`默认值为`.`）；
- 将OpenKnowledge MCP服务器连接到检测到的编辑器（Claude Code、Cursor、Codex）——可使用`--no-mcp`跳过此步骤；
- 在`.claude/skills/open-knowledge/`和`.cursor/skills/open-knowledge/`路径下安装**项目本地运行时技能**，以便在该仓库中工作的Agent获得完整的读写协议；
- 确保项目拥有`.git/`目录。

可随时重新运行`ok init`，将连接配置和技能更新至已安装的CLI版本。

Share an OpenKnowledge project with collaborators

与协作者共享OpenKnowledge项目

An OK project travels with its repository. To share one:

Commit the
```
.ok/
```
directory and the project-local
```
.claude/skills/open-knowledge/
```
(and
```
.cursor/skills/open-knowledge/
```
) directories along with your
```
.md
```
content.
Collaborators clone the repo and run
```
ok init
```
once — that registers the MCP server on their machine and refreshes the project skill.
Start the editor + preview with
```
ok start
```
(or open the project in OK Desktop).

Collaboration is real-time once two writers have the project open against the same content directory.

OK项目随代码仓库一同迁移。共享步骤如下：

提交
```
.ok/
```
目录以及项目本地的
```
.claude/skills/open-knowledge/
```
（和
```
.cursor/skills/open-knowledge/
```
）目录，同时提交你的
```
.md
```
内容。
协作者克隆仓库后，运行一次
```
ok init
```
——这会在他们的机器上注册MCP服务器并刷新项目技能。
使用
```
ok start
```
启动编辑器和预览（或在OK Desktop中打开项目）。

当两位写作者针对同一内容目录打开项目后，即可进行实时协作。

ok cowork

— Claude Chat & Cowork

ok cowork

— Claude Chat & Cowork

ok init

's editor wiring does not reach Claude Chat or Cowork — those read a separate Skills list inside the Claude Desktop App. Run

ok cowork

to build

openknowledge.skill

and open Claude Desktop so the user can upload it (Customize → Skills → + → Create skill → Upload skill).

ok init

的编辑器连接无法覆盖Claude Chat或Cowork——这些工具读取Claude桌面应用内的单独技能列表。运行

ok cowork

来构建

openknowledge.skill

，然后打开Claude桌面应用，用户即可上传该技能（自定义→技能→+→创建技能→上传技能）。

OK Desktop

OK Desktop is the standalone macOS app (

@inkeep/open-knowledge-desktop

). It bundles its own CLI, opens a project as an editor + preview window, and keeps the project's MCP wiring and skills current on every launch. Download DMGs from the releases page.

OK Desktop是独立的macOS应用（包名为

@inkeep/open-knowledge-desktop

）。它内置了自己的CLI，可将项目作为编辑器+预览窗口打开，并且每次启动时都会保持项目的MCP连接配置和技能为最新状态。可从发布页面下载DMG安装包。

Opening a file outside a project

打开项目外的文件

OpenKnowledge can open a single markdown file that is not part of an OK project — a loose

.md

.mdx

, or a file that lives inside a regular repo/folder which was never
ok init
'd. It opens in a throwaway session (a temp project in the OS temp dir — your repo is never touched, no

.ok/

is written into it) with the same live preview you get inside a project.

Never run
ok init
just to view or open a file.

ok init

turns a repo into a shared OpenKnowledge project; it is not a prerequisite for opening one file. Opening a file needs no project, no

.ok/

, and no server already running — each path below boots the session itself.

When asked to open or preview such a file, decide by the viewing surface you actually have — check the tool, not the host name. Only open a browser when you genuinely have one; never pop a browser tab on a host that has none.

You have an in-app / built-in browser (Claude Code Desktop's Browser pane, Cursor, Codex, and similar) — this is the default: call the preview_url
MCP tool with
```
file
```
set to the absolute path (it finds, or boots on demand, the session and returns a full
```
url
```
), then immediately open that
url
in your in-app browser. "Open it" means navigate your browser — don't just print the URL and stop. This is also the only way to view it in a browser when the OK Desktop app is installed (
```
ok open
```
prefers the Desktop app). Get the URL from
```
preview_url
```
only — never hunt for it via
```
ok ps
```
/
```
ok status
```
/
```
ok ui
```
/
```
ok start
```
or a guessed port.
No in-app browser (a pure-stdio CLI) — run
```
ok open /abs/path/to/file.md
```
: it opens the Desktop app when installed, else a browser, and boots the session itself. Don't force a browser tab the user didn't ask for;
```
ok open
```
is the right default here. If
```
ok
```
isn't on PATH,
```
npx @inkeep/open-knowledge open /abs/path/to/file.md
```
does the same.

If the OK MCP server isn't wired into this host there is no

preview_url

to call — use the

ok open

path above. Don't reconstruct what

preview_url

does by hand (spawning

ok mcp

yourself, scraping ports from

ok ps

The path must be absolute (a file outside a project has no cwd to anchor a relative path). Re-opening the same file lands on the same session. Never construct or guess the URL — use the one

preview_url

returns.

OpenKnowledge可以打开不属于OK项目的单个markdown文件——一个独立的

.md

.mdx

文件，或者位于从未执行过
ok init
的普通仓库/文件夹中的文件。它会在临时会话中打开（操作系统临时目录中的临时项目——不会触及你的仓库，也不会向其中写入

.ok/

目录），并提供与项目内相同的实时预览功能。

切勿仅为了查看或打开文件而运行
ok init
。

ok init

会将仓库转换为共享的OpenKnowledge项目；它并非打开单个文件的前提条件。打开文件无需项目、无需

.ok/

目录，也无需预先运行服务器——以下每种方式都会自行启动会话。

当被要求打开或预览此类文件时，请根据实际可用的查看界面来决定操作方式——检查工具，而非主机名。仅当确实有浏览器时才打开浏览器；切勿在没有浏览器的主机上弹出浏览器标签页。

拥有内置浏览器（Claude Code Desktop的浏览器面板、Cursor、Codex等）——这是默认方式：调用**
```
preview_url
```
MCP工具**，将
```
file
```
设置为文件的绝对路径（它会查找或按需启动会话，并返回完整的
```
url
```
），然后立即在内置浏览器中打开该
url
。“打开它”意味着导航到该URL——不要只打印URL就停止。当安装了OK Desktop应用时，这也是在浏览器中查看文件的唯一方式（
```
ok open
```
优先使用Desktop应用）。仅从
```
preview_url
```
获取URL——切勿通过
```
ok ps
```
/
```
ok status
```
/
```
ok ui
```
/
```
ok start
```
或猜测端口来查找URL。
无内置浏览器（纯标准输入输出的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

中获取端口）。

路径必须是绝对路径（项目外的文件没有当前工作目录来锚定相对路径）。重新打开同一文件会进入同一会话。切勿构造或猜测URL——请使用

preview_url

返回的URL。

Working inside a project — use the project-local skill, not this one

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

Do not use this skill to perform OpenKnowledge reads or writes. The runtime contract — STOP rules for native file tools on in-scope markdown, the preview-attach handshake, grounding and linking rules, the MCP tool routing table — lives in a separate project-local skill installed at

.claude/skills/open-knowledge/SKILL.md

whenever

ok init

runs.

If the user is editing markdown inside a project that has a

.ok/

directory and this discovery skill is the only OpenKnowledge skill loaded, the project-local skill is missing (the repo was never

ok init

'd, or the skill directory was not committed). Advise the user to run

ok init

to install it.

请勿使用本技能执行OpenKnowledge的读写操作。运行时协议——针对范围内markdown的原生文件工具STOP规则、预览附加握手、锚定与链接规则、MCP工具路由表——存放在单独的项目本地技能中，该技能会在每次运行

ok init

时安装到

.claude/skills/open-knowledge/SKILL.md

路径下。

如果用户正在一个拥有

.ok/

目录的项目中编辑markdown，但仅加载了本发现技能，则说明项目本地技能缺失（仓库从未执行过

ok init

，或者技能目录未被提交）。建议用户运行

ok init

来安装该技能。

Learn more

了解更多

Repository: https://github.com/inkeep/open-knowledge
Run
```
ok --help
```
for the full command list.

代码仓库：https://github.com/inkeep/open-knowledge
运行
```
ok --help
```
查看完整命令列表。

open-knowledge-discovery

Original

Translation

OpenKnowledge — what it is and how to install it

OpenKnowledge — 是什么以及如何安装它

Install OpenKnowledge on a repository

在代码仓库中安装OpenKnowledge

or, after a global install:

或者，全局安装后：

Share an OpenKnowledge project with collaborators

与协作者共享OpenKnowledge项目

`ok cowork`
— Claude Chat & Cowork

`ok cowork`
— Claude Chat & Cowork

OK Desktop

OK Desktop

Opening a file outside a project

打开项目外的文件

Working inside a project — use the project-local skill, not this one

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

Learn more

了解更多