kb-init

kb-init —— 搭建知识包框架

按照 kb 搭建符合规范的 知识包。你的独特工作是设计架构层 （第 2 步）并调整种子内容（第 3 步）。

开始编写前，请阅读版本配置。新知识包应使用 OKF v0.2。如果不熟悉下方术语，请阅读术语表。

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

默认在 knowledge/ 下创建知识包。根据用户请求接受以下覆盖项：

• 指定其他路径（例如 docs/kb）→ 改为在该路径下搭建。
• 指定命名知识包（例如“一个 ci 知识包”）→ 在 knowledge/<name>/ 下搭建，并将 knowledge/ 视为多知识包文件夹：确保顶层 knowledge/index.md 存在，用于汇总各个知识包（如果缺少则创建；将此知识包添加到其中）。

如果目标目录已包含知识包（根目录下有 index.md），请停止并报告；不要覆盖。对于仓库文档，请提供 kb-document；对于采集的来源，请提供 kb-ingest。

为 generated.by 选择真实的生成者身份：当前 Agent/工具，格式为 <producer>/<version>；除非人类确实编写了内容，否则绝不要使用 human:<id>。

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

2. 搭建框架前了解领域

框架搭建过程是确定性的；架构层需要判断，因此应先收集信息。检查工作区以获取线索（README、现有文档、代码、用户提及的任何笔记），判断这是仓库文档知识包还是采集来源知识包，并且只询问仍无法推断的信息：

• 这个知识包将收录哪类知识？（工作背景——人员、交易、产品；持续添加论文的研究文献集；代码库或产品手册；竞争格局；正在学习的书籍/课程；正在记录的规范或模式，例如本仓库的 OKF 知识包……）
• 主要实体有哪些——哪些反复出现的事物值得各自拥有一个概念？它们将构成 type 词汇表（例如 person、deal、metric；或 character、chapter、theme）。
• 对于采集来源知识包：将摄取哪些原始来源，它们应如何归入这些实体，以及哪些接收位置是明确管理的？
• 对于仓库文档：仓库的哪些部分属于范围，以及组件、工作流、接口、操作和决策应如何归类？仓库文件应原地作为证据保留，不属于原始接收内容。

保持简短——几个暂定类型和一行归类规则就足以开始。这是初始词汇表，并非封闭枚举；随着摄取过程揭示领域信息，架构层也会共同演进。 Reference（采集的来源材料）和 Spec Section（知识包自己的架构文档）是种子内容提供的工作流类型，不是需要用户设计的领域选择。

交互约定：

• 检查工作区一次，并在可行时批量读取相关内容。
• 用一个简洁的自由文本问题询问所有仍未知的信息。
• 不要针对这类领域特定输入使用预设的多选项。
• 用户回答后，从已加载的流程继续。不要再次加载 kb-init。
• 如果你提出架构供用户确认，只接受用户一次答复。获得批准后，直接搭建，不要重复陈述或重新规划。

**完成标准：**能够列出知识包的初始 type 值，以及原始来源和一行摄取归类规则，或仓库范围和一行文档归类规则。

3. 编写适配后的种子层和模式层

将 ../kb/example-bundle/ 作为源框架，然后将适配后的文件写入目标位置。不要先写入未经修改的副本再覆盖：创建目录，并将每个目标文件一次性写入最终的领域专属内容。获得用户批准后，安静地继续操作；不要逐条讲述每次读取或写入。

如果先前的尝试已创建目标文件，该文件就不再是新文件：编辑前立即读取该文件，保留有效内容，并从未完成的步骤继续。切勿盲目重试读取后写入失败，也不要将其视为误报。

文件	操作
index.md	保留 okf_version: "0.2" frontmatter；将正文替换为此知识包的标题和章节列表。
log.md	重新开始，仅添加一条带日期的 **Creation** 记录。
spec/types.md	保留 Spec Section 和 Reference；替换示例领域类型，并将 generated 设置为当前生成者/时间。
spec/conventions.md	替换为文件夹分类、路由、托管和信任规则；将 generated 设置为当前生成者/时间。
concepts/*	移除示例实体（customers、orders）；让 concepts/ 保持为空，或创建领域起始文件夹。
references/*	移除合成示例来源；在摄取真实来源之前，让 references/ 保持为空。
knowledge/index.md	若为多知识包（步骤 1）：创建或更新此知识包的目录条目。

创建新的概念/索引/日志文件时，使用 ../kb/templates/。

完成标准： 磁盘上已存在符合 OKF v0.2 的知识包；已处理上表中的所有行； 所有创建的概念均使用 generated，而非旧版 timestamp；spec/types.md 和 spec/conventions.md 描述的是此项目；如适用，已更新多知识包目录。

4. 验证

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

完成标准： 零项规范错误。

5. 交接

告知用户知识包已就绪及其所在位置。对于代码库知识包，交接给 kb-document；否则交接给 kb-ingest。两种情况下，kb-query 都能基于 结果回答问题。如果此项目使用 CLAUDE.md/AGENTS.md，可提议添加一行指引，让 Agent 在处理相关任务前先阅读知识包根目录下的 index.md；未经同意，绝不擅自添加。