kb-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kb-init — scaffold a knowledge bundle

kb-init — 搭建知识包

Scaffold a conformant bundle per kb. Your unique work is the schema layer (step 2) and adapting the seed (step 3).

Read the version profile before writing. New bundles target OKF v0.2. Read the glossary if the terms below are unfamiliar.

按照kb规范搭建一个合规的bundle。你需要自主完成的是schema层（步骤2）和适配初始模板（步骤3）。

在开始编写前，请阅读版本配置文件。新的知识包目标为OKF v0.2版本。如果对以下术语不熟悉，请阅读术语表。

1. Resolve location and bundle name

1. 确定位置和知识包名称

Default to a bundle at knowledge/
. Accept overrides from the user's request:

A different path (e.g.
```
docs/kb
```
) → scaffold there instead.
A named bundle (e.g. "a
```
ci
```
bundle") → scaffold at
```
knowledge/<name>/
```
and treat
```
knowledge/
```
as a multi-bundle folder: ensure a top-level
```
knowledge/index.md
```
exists that catalogs the bundles (create it if missing; add this bundle to it).

If the target directory already contains a bundle (a root

index.md

), stop and report it — do not overwrite. Offer kb-document for repository documentation or kb-ingest for captured sources.

Choose an honest producer actor for

generated.by

: the current agent/tool as

<producer>/<version>

, never

human:<id>

unless the human actually authored the content.

Completion criterion: the target path, bundle name, and producer actor are fixed, and the target is confirmed not to collide with an existing bundle.

默认在**

knowledge/

**目录下创建知识包。可根据用户请求进行覆盖：

不同路径（如
```
docs/kb
```
）→ 改为在该路径下搭建。
命名知识包（如“
```
ci
```
知识包”）→ 在
```
knowledge/<name>/
```
路径下搭建，并将
```
knowledge/
```
视为多知识包文件夹：确保顶层
```
knowledge/index.md
```
存在以记录所有知识包（若缺失则创建；并将此知识包添加到其中）。

index.md

），则停止操作并报告——请勿覆盖。若需存储库文档，可推荐使用kb-document；若需导入已有资源，可推荐使用kb-ingest。

为

generated.by

选择真实的生成者角色：当前代理/工具，格式为

<producer>/<version>

，除非人类实际创作了内容，否则绝不要使用

human:<id>

。

完成标准：目标路径、知识包名称和生成者角色已确定，且确认目标不会与现有知识包冲突。

2. Understand the domain before scaffolding

2. 搭建前理解领域

The scaffold is deterministic; the schema layer needs judgment, so gather it first. Inspect the workspace for signal (README, existing docs, the code, any notes the user points at), determine whether this is a repository-documentation or captured-source bundle, and ask the user only what you still can't infer:

What kind of knowledge will this bundle hold? (work context — people, deals, product; a research corpus you keep adding papers to; a codebase or product handbook; competitive landscape; a book/course you're studying; a spec or pattern you're documenting, like this repo's OKF bundle, …)
What are the main entities — the recurring things worth a concept each? These become the
```
type
```
vocabulary (e.g.
```
person
```
,
```
deal
```
,
```
metric
```
; or
```
character
```
,
```
chapter
```
,
```
theme
```
).
For a captured-source bundle: what raw sources will be ingested, how should they route to those entities, and which intake locations are explicitly managed?
For repository documentation: which parts of the repository are in scope, and how should components, workflows, interfaces, operations, and decisions route? Repository files remain evidence in place and are not raw intake.

Keep it short — a few provisional types and a one-line routing rule is enough to start. This is an initial vocabulary, not a closed enum; the schema layer co-evolves as ingest reveals the domain.

Reference

(captured source material) and

Spec Section

(the bundle's own schema documents) are workflow types supplied by the seed, not domain choices the user needs to design.

Interaction contract:

Inspect the workspace once, batching related reads where practical.
Ask one concise, free-text question for everything that remains unknown.
Do not use canned multiple-choice options for this domain-specific input.
After the user answers, continue from this loaded procedure. Do not load
```
kb-init
```
again.
If you propose a schema for confirmation, accept the user's answer once. After approval, scaffold without restating or replanning it.

Completion criterion: you can name the bundle's initial

type

values and either its raw sources plus a one-line ingest routing rule, or its repository scope plus a one-line documentation routing rule.

搭建流程是确定性的；schema层需要判断，因此先收集相关信息。检查工作区中的信号（README、现有文档、代码、用户指向的任何笔记），确定这是存储库文档类型还是资源导入类型的知识包，仅询问仍无法推断的信息：

该知识包将存储何种类型的知识？（工作背景——人员、交易、产品；持续添加论文的研究语料库；代码库或产品手册；竞争格局；正在学习的书籍/课程；正在记录的规范或模式，如本仓库的OKF知识包等）
主要实体有哪些——即每个值得单独定义概念的重复事物？这些将成为
```
type
```
词汇表（如
```
person
```
、
```
deal
```
、
```
metric
```
；或
```
character
```
、
```
chapter
```
、
```
theme
```
）。
对于资源导入类型的知识包：将导入哪些原始资源，它们应如何关联到这些实体，以及哪些导入位置是明确管理的？
对于存储库文档类型的知识包：存储库的哪些部分在范围内，组件、工作流、接口、操作和决策应如何关联？存储库文件将作为证据保留在原位，不会作为原始导入内容。

保持简洁——几个临时类型和一行关联规则就足够开始。这是初始词汇表，而非封闭枚举；schema层会随着导入过程揭示更多领域信息而共同演进。

Reference

（导入的原始资源材料）和

Spec Section

（知识包自身的schema文档）是初始模板提供的工作流类型，无需用户设计。

交互约定：

仅检查工作区一次，尽可能批量读取相关内容。
用一个简洁的自由文本问题询问所有未知信息。
不要针对此领域特定输入使用固定的多项选择选项。
用户回答后，继续执行当前流程。请勿重新加载
```
kb-init
```
。
如果提出schema供确认，仅接受用户一次回答。获得批准后，直接搭建，无需重述或重新规划。

完成标准：你可以说出知识包的初始

type

值，以及原始资源加一行导入关联规则，或者存储库范围加一行文档关联规则。

3. Write the adapted seed and schema layer

3. 编写适配后的初始模板和schema层

Read ../kb/example-bundle/ as the source scaffold, then write its adapted artifacts into the target. Do not first write an unmodified copy and then overwrite it: create the directories and write each target file once with its final, domain-specific content. Work quietly after the user's approval; do not narrate each read or write.

If a prior attempt already created a target file, it is no longer new: read that file immediately before editing it, preserve valid work, and resume from the incomplete step. Never retry a read-before-write failure blindly or dismiss it as a false alarm.

Artifact	Action
`index.md`	Keep `okf_version: "0.2"` frontmatter; replace the body with this bundle's title and section list.
`log.md`	Start fresh with a single dated `Creation` entry.
`spec/types.md`	Keep `Spec Section` and `Reference` ; replace the example domain types and set `generated` to the current producer/time.
`spec/conventions.md`	Replace with folder taxonomy, routing, custody, and trust rules; set `generated` to the current producer/time.
`concepts/*`	Remove example entities ( `customers` , `orders` ); leave `concepts/` empty or create domain starter folders.
`references/*`	Remove the synthetic example source; leave `references/` empty until a real source is ingested.
`knowledge/index.md`	If multi-bundle (step 1): create or update the catalog entry for this bundle.

Use ../kb/templates/ for any new concept/index/log files.

Completion criterion: the bundle exists on disk as OKF v0.2; every row above is accounted for; all created concepts use

generated

rather than legacy

timestamp

;

spec/types.md

and

spec/conventions.md

describe this project; multi-bundle catalog updated if applicable.

以../kb/example-bundle/为模板来源，然后将适配后的文件写入目标路径。请勿先写入未修改的副本再覆盖：创建目录并一次性写入每个目标文件的最终领域特定内容。获得用户批准后静默操作；无需叙述每次读取或写入。

如果之前的尝试已创建目标文件，则该文件不再是新文件：编辑前立即读取该文件，保留有效内容，并从未完成的步骤继续。切勿盲目重试读取-写入失败或忽略错误。

工件	操作
`index.md`	保留 `okf_version: "0.2"` 前置元数据；将正文替换为此知识包的标题和章节列表。
`log.md`	从头开始，添加一条带日期的 `Creation` 记录。
`spec/types.md`	保留 `Spec Section` 和 `Reference` ；替换示例领域类型，并将 `generated` 设置为当前生成者/时间。
`spec/conventions.md`	替换为文件夹分类、关联规则、保管和信任规则；将 `generated` 设置为当前生成者/时间。
`concepts/*`	删除示例实体（ `customers` 、 `orders` ）；保留 `concepts/` 为空或创建领域起始文件夹。
`references/*`	删除合成示例资源；保留 `references/` 为空，直到导入真实资源。
`knowledge/index.md`	如果是多知识包（步骤1）：创建或更新此知识包的目录条目。

任何新的concept/index/log文件请使用../kb/templates/模板。

完成标准：知识包已按OKF v0.2版本存储在磁盘上；上述所有条目均已处理；所有创建的概念使用

generated

而非旧版

timestamp

；

spec/types.md

和

spec/conventions.md

描述的是本项目；若为多知识包则已更新目录。

4. Validate

4. 验证

Run kb-lint if available; otherwise verify the bundle is conformant per kb (SPEC §11 — the one hard rule).

Completion criterion: zero conformance errors.

如果可用，运行kb-lint；否则根据kb（SPEC §11——唯一硬性规则）验证知识包是否合规。

完成标准：零合规错误。

5. Hand off

5. 交接

Tell the user the bundle is ready and where it lives. For a codebase bundle, hand off to kb-document; otherwise hand off to kb-ingest. In both cases, kb-query answers from the result. If this project uses

CLAUDE.md

AGENTS.md

, offer to add a one-line pointer so agents read the bundle's root

index.md

before relevant tasks; never add it without agreement.

告知用户知识包已准备就绪及其位置。对于代码库知识包，交接给kb-document；否则交接给kb-ingest。两种情况下，kb-query都可从结果中获取答案。如果本项目使用

CLAUDE.md

AGENTS.md

，可提出添加一行指向，以便代理在执行相关任务前阅读知识包的根目录

index.md

；未经同意切勿添加。