okf-knowledge-base

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OKF starter pack — how to work here

OKF入门套件——使用指南

This project was scaffolded to be conformant with Google's Open Knowledge Format (OKF) v0.1 from the first commit — markdown + YAML frontmatter, a standard-markdown link graph, and two reserved files. Conformance here is pre-populated, not enforced: OpenKnowledge's native frontmatter schema stays open-shaped, nothing is linted, and you are free to author however you like. This skill explains the conventions so the kit stays OKF-portable as it grows.

This skill is pack guidance. The platform
/open-knowledge
skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the OKF conventions on top.

本项目从第一次提交起就按照Google Open Knowledge Format（OKF）v0.1规范搭建——采用markdown + YAML前置元数据、标准markdown链接图谱，以及两个预留文件。此处的合规性是预先配置的，而非强制要求：OpenKnowledge的原生前置元数据架构保持开放形态，不进行任何语法检查，您可以自由创作。本技能将介绍相关约定，确保套件在扩展过程中仍保持OKF可移植性。

本技能是套件使用指南。平台的
/open-knowledge
技能（读/写/预览/链接/基础规则）仍管控所有markdown操作——本技能仅在其基础上叠加OKF约定。

The one rule (keep the kit conformant)

唯一规则（保持套件合规）

OKF requires exactly one thing of every non-reserved document: a non-empty
type
in its frontmatter. That is the whole conformance contract for your content.

The value is yours to choose —
```
concept
```
,
```
reference
```
,
```
note
```
,
```
person
```
,
```
event
```
, anything that fits. There is no blessed taxonomy.
```
Document
```
is a fine generic fallback when nothing more specific fits (it is just a non-empty value, not a special keyword).
The folder templates already set a sensible
```
type
```
per section — create docs with
```
write({ document: { path, template: "<name>" } })
```
and you inherit it.

OKF对所有非预留文档仅要求一点：前置元数据中需包含**非空的

type

**字段。这就是您的内容需遵守的全部合规约定。

字段值由您自行选择——可以是
```
concept
```
、
```
reference
```
、
```
note
```
、
```
person
```
、
```
event
```
，任何符合需求的类型。不存在官方认可的分类体系。
当没有更具体的类型可选时，
```
Document
```
是不错的通用备选（它只是一个非空值，并非特殊关键字）。
文件夹模板已为每个章节设置了合理的
```
type
```
值——使用
```
write({ document: { path, template: "<name>" } })
```
创建文档时，将自动继承该类型。

Folders

文件夹说明

concepts/
— durable ideas and definitions, one file per concept (
```
type: concept
```
).
references/
— external sources and citations you rely on (
```
type: reference
```
).
notes/
— working notes and observations (
```
type: note
```
).

Link liberally with standard markdown links (

[text](./path.md)

) — the value is the graph that emerges from the links between typed docs, and standard links keep that graph portable to any OKF consumer. (OpenKnowledge also accepts

[[wiki-link]]

shorthand as a native superset and preserves it byte-for-byte — but seeded content uses standard links so the bundle is conformant as-is.)

concepts/
— 存放持久化的理念和定义，每个概念对应一个文件（
```
type: concept
```
）。
references/
— 存放您依赖的外部资源和引用资料（
```
type: reference
```
）。
notes/
— 存放工作笔记和观察记录（
```
type: note
```
）。

请大量使用标准markdown链接（

[text](./path.md)

）——价值源于带类型文档之间的链接所形成的图谱，而标准链接可确保该图谱能移植到任何OKF兼容系统中。（OpenKnowledge也支持

[[wiki-link]]

简写作为原生扩展，并会原样保留该格式——但初始内容使用标准链接，以确保套件本身符合OKF规范。）

Reserved files (keep them frontmatter-free)

预留文件（不得包含前置元数据）

OKF reserves two lowercase files at the project root. Neither carries frontmatter — adding any frontmatter to a reserved file breaks OKF conformance.

index.md
(OKF §6) — the navigation hub: a link-list to the key docs and sections. Keep it current as you add important docs; it is how a reader (or a strict OKF consumer) finds their way in.
log.md
(OKF §7) — the change history: newest-first dated entries shaped
```
## YYYY-MM-DD: <summary>
```
. Add an entry whenever you create, edit, or restructure content. The seed ships a prose instruction documenting this format — add your first dated entry on your first edit.

The tool does not keep these live for you (that would be enforcement) — maintaining them is part of authoring here.

OKF在项目根目录预留了两个小写文件名的文件。这两个文件都不得包含前置元数据——若为预留文件添加前置元数据，将破坏OKF合规性。

index.md
（OKF第6节）——导航中心：包含指向关键文档和章节的链接列表。添加重要文档时请更新该文件；读者（或严格的OKF使用者）将通过它找到所需内容。
log.md
（OKF第7节）——变更历史：采用最新条目优先的日期格式
```
## YYYY-MM-DD: <摘要>
```
。每当您创建、编辑或重构内容时，请添加一条记录。初始版本包含说明该格式的文字——您第一次编辑时，请添加第一条带日期的记录。

工具不会自动维护这些文件（否则就成了强制要求）——维护它们是创作工作的一部分。

What stays OKF-portable

保持OKF可移植性的要点

Every non-reserved doc has a non-empty
```
type
```
. ✅
```
index.md
```
/
```
log.md
```
stay lowercase and frontmatter-free. ✅
Links use standard markdown / wiki-link syntax. ✅

If you ever want to hand this knowledge base to a strict OKF consumer, those three habits are all it takes.

所有非预留文档都包含非空的
```
type
```
字段。 ✅
```
index.md
```
/
```
log.md
```
保持小写且无前置元数据。 ✅
链接使用标准markdown / wiki-link语法。 ✅

如果您希望将此知识库交给严格的OKF使用者，只需养成这三个习惯即可。