open-knowledge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenKnowledge — agent guidance

OpenKnowledge — Agent操作指南

OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. This skill is the single source of OK agent guidance. Every rule below is a MUST unless marked otherwise. Depth lives in
references/*.md
— one level deep; load a reference when its task comes up.

Skill version tracks
@inkeep/open-knowledge-server
.
cat ~/.ok/skill-state.yml
shows what's installed.
ok seed
needs
@inkeep/open-knowledge
>= 0.4.0; if it errors
unknown command
,
npm install -g @inkeep/open-knowledge
.

Setup (not connected yet?). If the
mcp__open-knowledge__*
tools aren't available in your client, this project isn't wired up on this machine — see
references/setup.md
for the rung ladder (approve
.mcp.json
→
ok start
CLI → optional desktop app) and the canonical quickstart.

OpenKnowledge（简称OK）是一个通过MCP暴露的Markdown-CRDT协作平台。本Skill是OK Agent操作指南的唯一来源。除非另有标记，以下所有规则均为强制要求。详细内容位于
references/*.md
目录下（仅一级深度）；当涉及对应任务时，请加载参考文档。

Skill版本与
@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 → 可选桌面应用）以及标准快速入门指南。

TL;DR — the 90% case

核心要点——90%场景适用

Reads:
```
exec("cat …")
```
for one doc,
```
exec("ls -A …")
```
for a directory (folder defaults + template menu),
```
exec("grep …")
```
for literal,
```
search
```
for ranked retrieval. Native
```
Read
```
/
```
Grep
```
only on source code (
```
.ts
```
/
```
.py
```
/ …), never on in-scope
```
.md
```
/
```
.mdx
```
.
Writes:
```
write({ document: { path, content } })
```
for a new or full-replace doc;
```
edit({ document: { path, find, replace } })
```
for a body find/replace;
```
edit({ document: { path, frontmatter } })
```
for a frontmatter merge-patch (
```
null
```
deletes a key).
```
delete({ document })
```
removes,
```
move({ from, to })
```
moves/renames. Body find/replace is body-only. Pass a one-line
```
summary
```
(≤80 chars, user-facing outcome) on every content write.
Preview / open a doc — determine your ONE surface FIRST (once per session). Stop at first match: OK_DESKTOP_TERMINAL
or
OK_HOSTED_AGENT
set → you're inside OpenKnowledge (desktop terminal / in-app agent panel) →
```
ok open <name>
```
(switches the window the user is already looking at); never paste a
```
localhost
```
URL into your reply here · in-app browser (Claude Code Desktop's Browser pane, Cursor, Codex) →
```
preview_url
```
, then open/navigate it to the doc · else plain CLI →
```
ok open <name>
```
.
```
ok open <name>
```
opens a doc or folder (auto-detected);
```
--skill <name>
```
for a skill. The
```
previewUrl
```
field is a route id, not your open mechanism. Don't
```
preview_screenshot
```
to confirm edits. Full Step-0 procedure + per-surface how-to:
```
references/preview.md
```
.
Knowledge layers: capturing a source (ingest), synthesizing findings (research), promoting a decision (consolidate) — procedures, not tool calls; there is no
```
ingest
```
tool. Ingest ships here (
```
references/ingest-and-sources.md
```
); research + consolidate come with the
```
knowledge-base
```
pack. Layer model + packs:
```
references/starter-packs.md
```
.
Direct questions: a plain business question ("which customers…", "what did we decide about…") routes to
```
search
```
/
```
exec
```
+ a cited chat answer — no "research" keyword needed. Persist only when durable + multi-doc + not already covered, and offer first. See
```
references/corpus-qa.md
```
.
Authoring or improving a skill ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the open-knowledge-write-skill
skill — it owns scope choice (project vs global), the SKILL.md contract, evaluation, and install; don't improvise here. Author through the
```
skill
```
target (
```
write({ skill })
```
), never a raw path document. Skills are REAL folders under the editor dirs'
```
skills/
```
(
```
.claude
```
·
```
.cursor
```
·
```
.codex
```
·
```
.opencode
```
·
```
.pi
```
·
```
.agents
```
): ONE is the source, the rest are managed copies/symlinks. Read and edit via the tools (
skills
,
edit({ skill })
) — they route to the source. Never hand-edit a non-source copy: unedited copies refresh from the source, and editing one forks it into its own skill that stops refreshing.

读取操作：读取单个文档使用
```
exec("cat …")
```
，列出目录内容使用
```
exec("ls -A …")
```
（含默认文件夹模板菜单），精确匹配搜索使用
```
exec("grep …")
```
，排序检索使用
```
search
```
。仅在处理源代码（
```
.ts
```
/
```
.py
```
/…）时使用原生
```
Read
```
/
```
Grep
```
工具，绝对禁止用于范围内的
```
.md
```
/
```
.mdx
```
文件。
写入操作：创建或完全替换文档使用
```
write({ document: { path, content } })
```
；正文内容替换使用
```
edit({ document: { path, find, replace } })
```
；更新前置元数据使用
```
edit({ document: { path, frontmatter } })
```
（传入
```
null
```
可删除对应字段）。删除文档使用
```
delete({ document })
```
，移动/重命名文档使用
```
move({ from, to })
```
。正文替换仅作用于正文内容。每次写入内容时必须传入一行
```
summary
```
（≤80字符，面向用户的结果说明）。
预览/打开文档——先确定唯一操作入口（每会话一次）：按以下优先级选择第一个匹配项：已设置
OK_DESKTOP_TERMINAL
或
OK_HOSTED_AGENT
→ 处于OpenKnowledge环境（桌面终端/应用内Agent面板）→ 使用
```
ok open <name>
```
（切换用户当前查看的窗口）；在此场景下绝对不要在回复中粘贴
```
localhost
```
链接 · 应用内浏览器（Claude Code Desktop的Browser面板、Cursor、Codex）→ 使用
```
preview_url
```
，然后打开/导航到目标文档 · 纯CLI环境 → 使用
```
ok open <name>
```
。
```
ok open <name>
```
可自动检测并打开文档或文件夹；添加
```
--skill <name>
```
参数可打开指定Skill。
```
previewUrl
```
字段是路由ID，不是打开文档的操作方式。不要使用
```
preview_screenshot
```
确认编辑结果。完整的初始步骤及各场景操作指南：
```
references/preview.md
```
。
知识分层：捕获来源（摄入）、整合发现（研究）、固化决策（合并）——这些是流程步骤，不是工具调用；不存在
```
ingest
```
工具。摄入流程详见此处（
```
references/ingest-and-sources.md
```
）；研究与合并流程随
```
knowledge-base
```
包提供。分层模型及包说明：
```
references/starter-packs.md
```
。
直接问题处理：对于普通业务问题（如“哪些客户…“、“关于…我们的决策是什么…”），直接使用
```
search
```
/
```
exec
```
工具并给出带引用的聊天回复——无需使用“research”关键词。仅当内容具备持久性、跨文档性且未被现有内容覆盖时才进行持久化，并且先向用户确认。详见
```
references/corpus-qa.md
```
。
编写或改进Skill（如“编写/制作Skill”、“改进此Skill”、“将此内容转为Skill”）：立即停止当前操作并调用**
```
open-knowledge-write-skill
```
** Skill——它负责管理范围选择（项目级 vs 全局级）、SKILL.md契约、评估及安装；请勿自行操作。通过
```
skill
```
目标进行编写（
```
write({ skill })
```
），绝对不要直接操作路径文档。Skill是编辑器目录下
```
skills/
```
（
```
.claude
```
·
```
.cursor
```
·
```
.codex
```
·
```
.opencode
```
·
```
.pi
```
·
```
.agents
```
）中的真实文件夹：其中一个是源文件夹，其余为管理副本/符号链接。必须通过工具（
skills
、
edit({ skill })
）进行读写操作——它们会自动路由到源文件夹。绝对不要手动编辑非源文件夹的副本：未编辑的副本会从源文件夹同步更新，编辑副本会将其分叉为独立Skill并停止同步。

Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)

工具索引——21个工具（路由；MCP工具描述包含各工具的完整契约）

Reads —
```
exec
```
(primary; read-only
```
cat
```
/
```
ls
```
/
```
grep
```
/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell),
```
search
```
(ranked BM25 + recency),
```
history
```
(doc versions),
```
links
```
(
```
kind: backlinks|forward|dead|orphans|hubs|suggest
```
, or an array for one call),
```
skills
```
(search + read:
```
query
```
→ skills.sh; omit
```
name
```
to LIST managed (Project + Global);
```
name
```
READs one — by
```
name
```
+
```
scope
```
, never path),
```
config
```
(resolved config),
```
palette
```
(authoring forms +
```
html preview
```
starters + theme tokens;
```
palette({ components })
```
for JSX schemas),
```
preview_url
```
(browser preview URL on demand),
```
share_link
```
(GitHub-substrate share URL; read-only, errors without a GitHub remote),
```
lint
```
(markdown-lint violations:
```
document
```
for one doc, omit for the project;
```
fix: true
```
with
```
document
```
auto-fixes fixable rules in place — attributed, live in the preview; the rest need
```
edit
```
/
```
write
```
),
```
audit
```
(every lint violation + broken internal link in one read-only report, by source file with lines;
```
path
```
scopes; for link VALIDATION use this, not
```
links
```
).
Writes — four native CRUD verbs, polymorphic over
```
document
```
/
```
folder
```
/
```
template
```
/
```
skill
```
/
```
asset
```
(pass EXACTLY ONE target, nested under its address key):
```
write
```
(create/overwrite;
```
write({ skill: {…} })
```
authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent),
```
edit
```
(body find/replace/frontmatter merge-patch; no asset),
```
delete
```
(remove),
```
move
```
(move/rename, rewrites referrers; a skill also takes
```
scope
```
/
```
toScope
```
for Project↔Global — history resets, re-
```
install
```
). Output mirrors the input key; the preview envelope (
```
previewUrl
```
,
```
warning
```
) stays top-level. Plus
```
install
```
(WHERE a
```
skill
```
lives:
```
add
```
/
```
remove
```
locations additively — editor ids,
```
agents
```
, or custom roots;
```
mode
```
+
```
convert
```
re-form ONLY the locations named;
```
source
```
moves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only via
```
delete
```
),
```
import
```
(acquire a skill-dir into
```
add
```
's locations; scripts never run),
```
checkpoint
```
(named version), and
```
restore_version
```
(roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with.

Conflicts —

conflicts

(

kind: list|content

resolve_conflict

(write a resolution + commit; destructive). See

references/conflict-resolution.md

Self-correcting on misuse: constraints JSON Schema can't express ("exactly one target", "

find

needs a

replace

", body-XOR-frontmatter) return

isError: true

with a one-line corrective shape. Read it and retry with that shape; don't guess.

Tools NOT in OK MCP (your host's):

preview_start

preview_screenshot

WebFetch

WebSearch

, native

Read

Grep

Glob

Edit

. The STOP rule governs which you may use on in-scope markdown.

读取类工具 —
```
exec
```
（主要工具；支持只读的
```
cat
```
/
```
ls
```
/
```
grep
```
/…操作，以及前置元数据/反向链接/历史记录增强；仅支持单个命令或单管道，不支持完整shell）、
```
search
```
（基于BM25算法排序+时效性）、
```
history
```
（文档版本记录）、
```
links
```
（支持
```
kind: backlinks|forward|dead|orphans|hubs|suggest
```
，或传入数组一次性查询多种类型）、
```
skills
```
（搜索+读取：传入
```
query
```
调用skills.sh；省略
```
name
```
参数列出所有已管理的Skill（项目级+全局级）；传入
```
name
```
参数读取单个Skill——通过
```
name
```
+
```
scope
```
定位，绝对不要通过路径）、
```
config
```
（已解析的配置）、
```
palette
```
（创作表单+
```
html preview
```
模板+主题令牌；传入
```
palette({ components })
```
获取JSX模式）、
```
preview_url
```
（按需生成浏览器预览URL）、
```
share_link
```
（基于GitHub的共享URL；只读，无GitHub远程仓库时会报错）、
```
lint
```
（Markdown检查违规：传入
```
document
```
检查单个文档，省略则检查整个项目；传入
```
fix: true
```
并指定
```
document
```
可自动修复可修复的规则——修复结果会实时显示在预览中；其余问题需使用
```
edit
```
/
```
write
```
手动修复）、
```
audit
```
（生成包含所有检查违规及无效内部链接的只读报告，按源文件及行号展示；传入
```
path
```
指定检查范围；链接验证请使用此工具，不要使用
```
links
```
）。
写入类工具 — 四个原生CRUD动词，可作用于
```
document
```
/
```
folder
```
/
```
template
```
/
```
skill
```
/
```
asset
```
（必须传入且仅传入一个目标，嵌套在对应键下）：
```
write
```
（创建/覆盖；
```
write({ skill: {…} })
```
在项目默认Skill目录下创建真实文件夹形式的Skill——对该文件夹的Agent立即生效）、
```
edit
```
（正文内容替换/前置元数据合并更新；不支持asset）、
```
delete
```
（删除）、
```
move
```
（移动/重命名，自动更新引用；Skill还支持
```
scope
```
/
```
toScope
```
参数实现项目级↔全局级迁移——历史记录会重置，需重新
```
install
```
）。输出结构与输入键对应；预览信封（
```
previewUrl
```
、
```
warning
```
）保持在顶层。此外还有
```
install
```
（指定Skill的安装位置：
```
add
```
/
```
remove
```
参数可增量添加/移除位置——编辑器ID、
```
agents
```
或自定义根目录；
```
mode
```
+
```
convert
```
参数仅修改指定位置的格式；
```
source
```
参数移动源文件夹。源文件夹即为Skill本身——不存在“全局卸载”；仅通过
```
delete
```
可删除Skill）、
```
import
```
（将Skill目录导入
```
add
```
指定的位置；不会运行脚本）、
```
checkpoint
```
（创建命名版本）、
```
restore_version
```
（回滚版本）。文件夹的前置元数据为开放结构且仅作用于自身（不会向下级联到子文档）；模板是新文档的初始内容。
冲突处理工具 —
```
conflicts
```
（支持
```
kind: list|content
```
）、
```
resolve_conflict
```
（写入解决方案并提交；具有破坏性）。详见
```
references/conflict-resolution.md
```
。

误用自动纠正：JSON Schema无法表达的约束（如“必须且仅传入一个目标”、“

find

必须搭配

replace

”、正文与前置元数据二选一）会返回

isError: true

及一行纠正说明。请根据说明重新尝试，不要自行猜测。

不属于OK MCP的工具（宿主工具）：

preview_start

、

preview_screenshot

、

WebFetch

、

WebSearch

、原生

Read

Grep

Glob

Edit

。STOP规则管控着哪些工具可用于范围内的Markdown文件。

STOP — native tools on in-scope

.md

.mdx

STOP规则——禁止对范围内的

.md

.mdx

使用原生工具

Route every in-scope markdown read and write through OK's MCP tools — never your host's native file tools. Native

Edit

sed

/ direct

Write

on in-scope markdown bypasses the CRDT and loses agent attribution in the shadow repo; native reads skip frontmatter, backlinks, shadow-repo activity, and project git history that OK returns for every matched file. When this workspace has OpenKnowledge MCP configured, do not use native file tools on markdown paths inside the content directory. The ban covers every common rationalization:

Native
Read
/
Grep
/
Glob
on in-scope
.md
/
.mdx
— the original case.
Bash ls
/
Bash find
/
Bash cat
on dirs containing in-scope markdown — use
```
exec("ls -A …")
```
/
```
exec("find … -name '*.md'")
```
/
```
exec("cat …")
```
. Native returns bare names;
```
exec
```
returns frontmatter, backlink counts, and recent activity.
```
-A
```
shows hidden entries (
```
.ok/
```
,
```
.okignore
```
) without the
```
.
```
/
```
..
```
noise.

Glob patterns that target markdown (

**/*.md

specs/**

reports/**

docs/**

) — use

exec

with

find

exec("ls -A <dir>")

Dispatching the Explore / general-purpose subagent for markdown-heavy exploration — subagents use native tools internally and bypass OK. Do markdown exploration yourself via
```
exec
```
/
```
search
```
. Subagents remain appropriate for source-code exploration.
Native
Read
/
Grep
on in-scope markdown inside
.ok/
—
```
.ok/
```
is in-scope; treat its
```
.md
```
/
```
.mdx
```
like any other KB file.
ls
/
cat
/
find
on skill folders to discover or read a skill — skills are addressed by
```
name
```
+
```
scope
```
, not by path (a skill can live in any editor dir, the
```
.agents/skills/
```
hub, or a custom root, with copies elsewhere). Use the
```
skills
```
tool.

Not seeing
exec
is NOT the escape hatch. Wiring, labels, and tool visibility vary by client; some (notably Codex) defer MCP tools behind lazy discovery. Registration is the test, not top-level-symbol visibility — run tool discovery for

open-knowledge

first. Detail:

references/setup.md

Escape hatch. Native

Read

Grep

Glob

.md

.mdx

is allowed only when, after running tool discovery (above), no OpenKnowledge MCP server is registered for this project, or immediately after you actually invoked an MCP call and it failed — then begin a user-visible sentence with

OpenKnowledge MCP unavailable:

. "Not registered" is a conclusion you may only reach after tool discovery turned it up empty — never from the initial tool list alone. Never use the hatch because you skipped your client's MCP path, didn't see

exec

as a top-level tool, didn't run tool discovery, or rationalized the skill wasn't necessary.

Source code and non-markdown files (

.ts

.py

package.json

, …): native

Read

Grep

Glob

always.

所有范围内Markdown文件的读写操作必须通过OK的MCP工具完成——绝对禁止使用宿主的原生文件工具。对范围内Markdown文件使用原生

Edit

sed

/直接

Write

会绕过CRDT，并在影子仓库中丢失Agent操作记录；原生读取工具会忽略前置元数据、反向链接、影子仓库活动及项目Git历史，而这些信息OK会为每个匹配文件返回。当工作区已配置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/通用子Agent进行Markdown内容探索——子Agent内部使用原生工具，会绕过OK。请自行通过
```
exec
```
/
```
search
```
进行Markdown内容探索。子Agent仍适用于源代码探索。
对
.ok/
目录内的范围内Markdown文件使用原生
Read
/
Grep
——
```
.ok/
```
属于范围之内；其
```
.md
```
/
```
.mdx
```
文件需按普通知识库文件处理。
对Skill文件夹使用
ls
/
cat
/
find
来发现或读取Skill——Skill通过
```
name
```
+
```
scope
```
定位，而非路径（Skill可位于任何编辑器目录、
```
.agents/skills/
```
中心或自定义根目录，并在其他位置存在副本）。请使用
```
skills
```
工具。

未看到
exec
工具并非免责理由。不同客户端的配置、标签及工具可见性有所不同；部分客户端（尤其是Codex）会延迟加载MCP工具。请先运行

open-knowledge

工具发现，再判断是否可用，不要仅通过初始工具列表判断。详细说明：

references/setup.md

。

例外情况：仅当运行工具发现后（如上所述），发现此项目未注册OpenKnowledge MCP服务器，或实际调用MCP工具后失败时，才允许对

.md

.mdx

使用原生

Read

Grep

Glob

工具——此时需在面向用户的回复开头加上

OpenKnowledge MCP unavailable:

。“未注册”结论仅能在工具发现无结果后得出——绝对不要仅通过初始工具列表判断。绝对不要因跳过客户端MCP路径、未在顶层工具中看到

exec

、未运行工具发现或认为本Skill不必要而使用例外情况。

源代码及非Markdown文件（

.ts

、

.py

、

package.json

等）：始终允许使用原生

Read

Grep

Glob

工具。

Reads — examples

读取操作示例

Read a file:
```
exec("cat <path>.md")
```
— contents + full enrichment.
List a directory:
```
exec("ls -A <dir>")
```
— per-child frontmatter, recursive markdown counts, most-recently-updated doc per subdir, the folder's own
```
title
```
/
```
description
```
/
```
tags
```
+
```
templates_available
```
. Prefer
```
-A
```
over plain
```
ls
```
.
Literal search:
```
exec("grep -rn <term> <dir> | head -5")
```
— matches + enrichment on matched files.
Ranked search:
```
search({ query })
```
— title boost + body BM25 + recency; use when picking the best doc, not when listing every occurrence.

读取文件：
```
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算法+时效性；用于筛选最佳文档，而非列出所有匹配项。

Writing

写入操作

Call

write

edit

as soon as you have content (route through MCP per the STOP rule).

Persist incrementally — the knowledge base IS your checkpoint (MUST). On any multi-step or long-running task — a research sweep, a multi-source synthesis, a batch of docs — write completed work to the KB as you finish each unit: per section, per source, per doc. Never hold finished findings only in your context waiting for one final write at the end. A rate limit, crash, or context compaction mid-task discards everything still unwritten; work already persisted survives, and you resume by reading the doc back. Create the target doc early (skeleton + frontmatter), then

edit

each section in as it firms up.

Pass a
summary
on every content write (SHOULD) — a one-line (≤80 char) user-facing note; it becomes the timeline entry. Reach for visual structure (Callout,

mermaid

, table,

html preview

) where it carries the point better than prose; call

palette

as you draft. Advisory write-warnings, MDX authoring, delete/move mechanics, and visual authoring:

references/writing.md

references/components-and-visuals.md

references/media-and-assets.md

一旦准备好内容，请立即调用

write

edit

（遵循STOP规则通过MCP路由）。

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

edit

添加内容。

每次写入内容时建议传入
summary
——一行（≤80字符）面向用户的说明；它会成为时间线条目。优先使用可视化结构（提示框、

mermaid

、表格、

html preview

），当它们比 prose 更能清晰表达观点时；编写时可调用

palette

工具。写入警告、MDX创作、删除/移动机制及可视化创作说明：

references/writing.md

references/components-and-visuals.md

references/media-and-assets.md

。

Grounding — every factual claim needs a source (MUST)

溯源——每个事实性声明必须有来源（强制要求）

KB docs are factual artifacts: every claim traceable, and the source lives inside the knowledge base, not on the public web.

Ingest is a procedure, not a tool — binary-vs-text classification, SSRF-safe fetch flags, size + executable gates, wrapper frontmatter — in

references/ingest-and-sources.md

. Read it before your first capture; a naive fetch-and-paste skips every gate.

Closed loop. External sources are pulled in by the ingest procedure, then cited locally. A bare
```
[source](https://...)
```
inside a KB doc is not a citation — it is a TODO meaning "still needs ingesting". The chain only works if every leaf is a local doc.
Every factual claim MUST cite its source at the point of claim. No unsourced speculation.
Web sources → fetch the page (host
```
WebFetch
```
/
```
WebSearch
```
), ingest it, then cite the path:
```
[source name](./path/to/source.md)
```
(the local doc carries
```
source_url:
```
). Inline
```
[source](URL)
```
is a chat affordance, not a KB one.
Self-fetched counts. A URL YOU fetched to ground a claim gets the same ingest — no inline-URL downgrade.
Internal cross-refs → link the OK doc holding the authoritative claim; that doc cites its own sources (chains terminate in preserved local docs).
No evidence? Search and ingest the result, OR mark
```
(TODO: needs source)
```
, OR don't write the claim. Do NOT fabricate — unsourced speculation rots into untraceable tribal lore.

知识库文档是事实性产物：每个声明必须可追溯，且来源必须位于知识库内部，而非公共网络。

摄入是流程，不是工具——包含二进制与文本分类、SSRF安全的获取标志、大小与可执行文件限制、包装前置元数据——详见

references/ingest-and-sources.md

。首次捕获来源前请阅读此文档；直接获取并粘贴会跳过所有限制。

闭环原则：外部来源需通过摄入流程导入，然后在本地引用。知识库文档中的裸链接
```
[source](https://...)
```
不是有效引用——它是一个待办事项，意为“仍需摄入”。只有当每个叶子节点都是本地文档时，溯源链才有效。
每个事实性声明必须在声明处引用来源。禁止无来源的推测。
网络来源 → 获取页面（使用宿主
```
WebFetch
```
/
```
WebSearch
```
）、摄入、然后引用路径：
```
[source name](./path/to/source.md)
```
（本地文档需包含
```
source_url:
```
字段）。聊天中可使用内联
```
[source](URL)
```
，但知识库中禁止使用。
自行获取的来源同样适用。你为验证声明而获取的URL需按相同流程摄入——不能降级为内联URL。
内部交叉引用 → 链接持有权威声明的OK文档；该文档会引用自身的来源（溯源链终止于已保存的本地文档）。
无证据？ 搜索并摄入结果，OR标记
```
(TODO: needs source)
```
，OR不写入该声明。绝对不要编造内容——无来源的推测会演变为无法追溯的隐性知识。

Linking — standard markdown links (MUST)

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

Link every noun-phrase that names another document —

[text](./relative/path.md)

— and link liberally. Every link must resolve to a doc that exists by the time you're done (a same-pass forward-reference you create later in the pass is fine; for one that genuinely won't exist, leave the mention as plain prose + a tracked task). Never backtick a link (

`[text](./foo.md)`

is a bug) and never use HTML

<a>

. Read
brokenLinks
on every
write
/
edit
response:
[]
means all links resolve; a populated list names each broken
href
+
reason
(
no-such-doc
/
no-such-file
/
unresolvable
) — fix them in a follow-up
edit
.

audit

is the authoritative end-state link check (the editor's red-underline is slug-tolerant and lies, so trust the tool). External web sources are NOT inline body links (see Grounding). Full rule set + the

[[Page]]

legacy note:

references/linking.md

为每个指代其他文档的名词短语添加链接——

[text](./relative/path.md)

——并尽量多添加链接。所有链接必须在你完成操作时可解析（同一流程中后续创建的前置引用是允许的；对于确实不会存在的引用，请保留为普通文本+跟踪任务）。绝对不要为链接添加反引号（

`[text](./foo.md)`

是错误），也不要使用HTML

<a>

标签。每次
write
/
edit
响应时请查看
brokenLinks
字段：
[]
表示所有链接均可解析；非空列表会列出每个无效
href
及原因（
no-such-doc
/
no-such-file
/
unresolvable
）——请通过后续
edit
修复。

audit

是权威的最终状态链接检查工具（编辑器的红色下划线对路径容错且不准确，请信任工具结果）。外部网络来源不允许作为正文中的内联链接（详见溯源部分）。完整规则集+

[[Page]]

历史说明：

references/linking.md

。

Folders, frontmatter, templates

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

Every

.md

.mdx

needs YAML frontmatter —

title

description

required,

tags

recommended. Two opt-in, nested folder mechanisms: folder frontmatter (

<folder>/.ok/frontmatter.yml

— the folder's own open-shape properties; self-only, does NOT cascade into child docs) and templates (

<folder>/.ok/templates/

— what new docs start with). Most folders have NO

.ok/

. A doc's frontmatter is exactly its own on-disk YAML. Structural model + the full pre-write checklist:

references/folder-model.md

. Template authoring + folder editing:

references/template-authoring.md

. Frontmatter-vs-body edit rules:

references/doc-editing.md

Read the folder before writing (MUST). Before creating/editing docs in a folder, call
```
exec("ls -A <folder>")
```
once per folder per session — it returns the folder's
```
title
```
/
```
description
```
/
```
tags
```
+
```
templates_available
```
. Skipping it lands docs that violate folder discipline. (If a folder has no frontmatter AND no templates AND the repo has substantial content elsewhere, it isn't onboarded — run
```
references/onboard-existing-repo.md
```
first.)
Use a template when one fits (MUST). Instantiate via
```
write({ document: { path, template } })
```
; inherited templates count. Skip only when none match or the user asked for free-form (note why in chat). Create templates proactively when a shape recurs.
When recurring per-doc properties emerge (MUST). Writing the same frontmatter on multiple siblings → bake those starting values into a template (
```
write({ template })
```
). Folder frontmatter does not cascade values into docs.

每个

.md

.mdx

文件必须包含YAML前置元数据——

title

description

为必填项，

tags

为推荐项。两种可选的嵌套文件夹机制：文件夹前置元数据（

<folder>/.ok/frontmatter.yml

——文件夹自身的开放结构属性；仅作用于自身，不会向下级联到子文档）和模板（

<folder>/.ok/templates/

——新文档的初始内容）。大多数文件夹没有

.ok/

目录。文档的前置元数据完全等同于其磁盘上的YAML内容。结构模型+完整写入前检查清单：

references/folder-model.md

。模板创作+文件夹编辑说明：

references/template-authoring.md

。前置元数据与正文编辑规则：

references/doc-editing.md

。

写入前先读取文件夹信息（强制要求）。在文件夹中创建/编辑文档前，每个会话每个文件夹需调用一次
```
exec("ls -A <folder>")
```
——它会返回文件夹的
```
title
```
/
```
description
```
/
```
tags
```
+
```
templates_available
```
。跳过此步骤会导致文档违反文件夹规范。（如果文件夹没有前置元数据且没有模板，同时仓库其他位置有大量内容，则说明该文件夹未纳入管理——请先运行
```
references/onboard-existing-repo.md
```
。）
合适时使用模板（强制要求）。通过
```
write({ document: { path, template } })
```
实例化；继承的模板同样有效。仅当没有匹配模板或用户要求自由格式时才跳过（请在聊天中说明原因）。当某种结构重复出现时，请主动创建模板。
当出现重复的文档属性时（强制要求）。如果多个同级文档使用相同的前置元数据，请将这些初始值整合到模板中（
```
write({ template })
```
）。文件夹前置元数据不会向下级联到文档。

Conflict-aware writes

冲突感知写入

Projects with GitHub sync may carry docs in merge-conflict state; mutating calls against them return RFC 9457

urn:ok:error:doc-in-conflict

(409). Detect proactively —

exec("cat <path>.md")

returns

lifecycle: {status, reason} | null

; on

status === 'conflict'

switch to the

conflicts

resolve_conflict

flow. Full flow:

references/conflict-resolution.md

开启GitHub同步的项目可能存在处于合并冲突状态的文档；对这些文档进行修改会返回RFC 9457

urn:ok:error:doc-in-conflict

（409）错误。请主动检测——

exec("cat <path>.md")

会返回

lifecycle: {status, reason} | null

；当

status === 'conflict'

时，请切换到

conflicts

resolve_conflict

流程。完整流程：

references/conflict-resolution.md

。

Anti-patterns — the top offenders

反模式——常见错误

Task	Don't	Do
List / find / read markdown	`Bash: ls` / `Glob: */.md` / `Read: foo.md`	`exec("ls -A …")` / `exec("find …")` / `exec("cat …")`
Explore a markdown-heavy dir	`Agent(Explore)` (bypasses OK)	`exec` / `search` yourself
Reference another doc	`[text](./p.md)` (backticked) or HTML `<a>`	`[text](./p.md)`
Embed an image	`<img>` , a `localhost` / `preview_url` URL, hot-link	save locally + `![meaningful alt](./path)`
Factual claim in a KB doc	prose with no citation, OR inline `[src](https://…)`	ingest the source ( `references/ingest-and-sources.md` ), cite the local path
Confirm an edit landed	`preview_screenshot` / verification loop	trust the CRDT tool response
Delete a markdown doc	`Bash: rm` / native deletion	`delete({ document })` ( `checkpoint()` first if risky)
Write in an unfamiliar folder	straight to `write`	`exec("ls -A <folder>")` first

Full table:

references/anti-patterns.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` 链接、热链接	保存到本地 + `![有意义的替代文本](./path)`
知识库文档中的事实性声明	无引用的 prose，OR内联 `[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

。

Knowledge layers — the shape most KB work takes

知识分层——知识库工作的典型模式

Three recurring practices, not tool calls — each a full procedure that ships as skill guidance.

Layer	When	Procedure
ingest	Preserve a shared URL/PDF/file verbatim, or you fetched a URL to ground a claim (binary sources preserved, not scraped).	`references/ingest-and-sources.md` — ships here, §Grounding depends on it
research	Investigate / compare / synthesize sources → `status: provisional` article + `sources:` .	`research-with-sources` skill
consolidate	A decision was made → canonical source-of-truth with a `supersedes:` chain.	`consolidate-notes` skill

Research and consolidate arrive with

ok seed --pack knowledge-base

. Without that pack you do not have those procedures — don't improvise one; do the work as an ordinary grounded

write

, or offer to seed it (

ok seed --pack knowledge-base --dry-run

shows what it would add).

Don't chain silently: let the user drive ingest → research → consolidate, and a procedure's STOP gates override session-level "don't stop to ask" hints. After any turn that changes KB content, check for a

log.md

and follow its contract (

references/cadence-and-logs.md

). Interleave a multi-doc batch so the preview shows narrative progress.

Onboarding a repo that already has content:

references/onboard-existing-repo.md

. Layer model + packs:

references/starter-packs.md

三种重复出现的实践，不是工具调用——每种都是完整流程，作为Skill指南提供。

分层	适用场景	流程说明
摄入	需完整保存共享URL/PDF/文件，或你为验证声明而获取了URL（二进制来源需完整保存，而非抓取）。	`references/ingest-and-sources.md` ——此处提供，§溯源部分依赖此流程
研究	调查/比较/整合来源 → 生成 `status: provisional` 的文章 + `sources:` 字段。	`research-with-sources` Skill
合并	已做出决策 → 生成带 `supersedes:` 链的权威可信来源。	`consolidate-notes` Skill

研究与合并流程随

ok seed --pack knowledge-base

提供。未安装此包则无法使用这些流程——请勿自行创造；请作为普通的带溯源

write

操作完成工作，或向用户提议安装此包（

ok seed --pack knowledge-base --dry-run

可展示会添加的内容）。

请勿静默执行流程链：请让用户驱动摄入→研究→合并流程，且流程的STOP规则会覆盖会话级“无需询问”提示。任何修改知识库内容的操作后，请检查是否存在

log.md

并遵循其契约（

references/cadence-and-logs.md

）。多文档批量操作时请交替进行，以便预览展示进度。

已有内容的仓库纳入管理：

references/onboard-existing-repo.md

。分层模型及包说明：

references/starter-packs.md

。

Server lifecycle

服务器生命周期

write

edit

returns

"Hocuspocus server is not running"

, run

ok start

(via Bash) and retry. Never fall back to native

Edit

Write

for in-scope markdown.

如果

write

edit

"Hocuspocus server is not running"

，请通过Bash运行

ok start

并重试。绝对不要 fallback 到原生

Edit

Write

工具处理范围内的Markdown文件。

Scope recap

范围回顾

OK looks for documents under the resolved

content.dir

(runtime:

config({ key: 'content.dir' })

);

.gitignore

and

.okignore

(at root or any folder depth) define exclusions. Every
.md
/
.mdx
under
content.dir
not excluded is an OpenKnowledge document — including under

specs/

reports/

docs/

. Folder metadata + templates live in nested

<folder>/.ok/

, not in

.ok/config.yml

. Working in a git worktree? Pass the worktree's absolute path as

cwd

on your OK tool calls once — it sticks for the session, so reads, writes, and the preview all target that worktree.

OK会在已解析的

content.dir

下查找文档（运行时可通过

config({ key: 'content.dir' })

查看）；

.gitignore

和

.okignore

（根目录或任何文件夹深度）定义排除规则。content.dir
下未被排除的所有
.md
/
.mdx
文件均为OpenKnowledge文档——包括

specs/

、

reports/

、

docs/

下的文件。文件夹元数据+模板存储在嵌套的

<folder>/.ok/

目录中，而非

.ok/config.yml

。在Git工作树中工作？ 请在OK工具调用中传入工作树的绝对路径作为

cwd

——会话中会保持此设置，因此读取、写入及预览都会指向该工作树。

open-knowledge

Original

Translation

OpenKnowledge — agent guidance

OpenKnowledge — Agent操作指南

TL;DR — the 90% case

核心要点——90%场景适用

Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)

工具索引——21个工具（路由；MCP工具描述包含各工具的完整契约）

STOP — native tools on in-scope
`.md`
/
`.mdx`

STOP规则——禁止对范围内的
`.md`
/
`.mdx`
使用原生工具

Reads — examples

读取操作示例

Writing

写入操作

Grounding — every factual claim needs a source (MUST)

溯源——每个事实性声明必须有来源（强制要求）

Linking — standard markdown links (MUST)

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

Folders, frontmatter, templates

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

Conflict-aware writes

冲突感知写入

Anti-patterns — the top offenders

反模式——常见错误

Knowledge layers — the shape most KB work takes

知识分层——知识库工作的典型模式

Server lifecycle

服务器生命周期

Scope recap

范围回顾

open-knowledge

Original

Translation

OpenKnowledge — agent guidance

OpenKnowledge — Agent操作指南

TL;DR — the 90% case

核心要点——90%场景适用

Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)

工具索引——21个工具（路由；MCP工具描述包含各工具的完整契约）

STOP — native tools on in-scope .md / .mdx

STOP规则——禁止对范围内的.md/.mdx使用原生工具

Reads — examples

读取操作示例

Writing

写入操作

Grounding — every factual claim needs a source (MUST)

溯源——每个事实性声明必须有来源（强制要求）

Linking — standard markdown links (MUST)

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

Folders, frontmatter, templates

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

Conflict-aware writes

冲突感知写入

Anti-patterns — the top offenders

反模式——常见错误

Knowledge layers — the shape most KB work takes

知识分层——知识库工作的典型模式

Server lifecycle

服务器生命周期

Scope recap

范围回顾

STOP — native tools on in-scope
`.md`
/
`.mdx`

STOP规则——禁止对范围内的
`.md`
/
`.mdx`
使用原生工具