# OKF 参考布局与本仓图谱扩展

> 本文件是 OKF（Open Knowledge Format v0.1）与 kb-workflow `knowledge/` Bundle 的**参考布局与 type 映射**唯一说明。迁移见 `/kb-okf-migrate` 与 `scripts/kb-okf-migrate.mjs`。**内部链接、关系字段、回链与孤儿规则**以 [kb-graph.md](kb-graph.md) 为准（本仓相对官方 OKF 的**有意扩展**）。

## 1. 定位：参考布局，非强制标准

1. 业务仓 `knowledge/` **参考** OKF Bundle：Markdown + YAML frontmatter（概念文件必填 `type`），保留名 `index.md` / `log.md`。
2. OKF 在本仓**不**作为全文合规标准；保留名、`type` 枚举、目录入口习惯仍沿用，便于工具与迁移对齐。
3. **与官方 OKF 的已知差异（有意）**：官方推荐知识库内「普通 Markdown 链接」；本仓**仅允许 `[[wikilink]]` 作内部互链**，Markdown 链接**仅用于**外部 `http`/`https`。理由：Obsidian 关系图谱 + Agent 可解析出链/入链。详见 [kb-graph.md](kb-graph.md)。
4. 变更状态机仍由 `00-manifest.json` 承担，不迁入 OKF。

## 2. 路径映射

| 旧路径 | OKF 落点 |
|--------|----------|
| `knowledge/知识索引.md` | `knowledge/index.md`（允许且仅此处 frontmatter：`okf_version: "0.1"`） |
| `业务域/<域>/00-README.md` | `业务域/<域>/index.md`（无 frontmatter） |
| `工程平台/README.md` | `工程平台/index.md`（无 frontmatter） |
| `工程平台/<分区>/00-README.md` | `工程平台/<分区>/index.md`（无 frontmatter） |
| 子目录 `README.md` | 同目录 `index.md`（无 frontmatter） |
| 正文「十/十一、变更记录」 | 同目录 `log.md`（ISO 日期分组、最新在前） |

检索路径：`knowledge/index.md` → 领域/平台 `index.md` → 叶子概念文件（列表项为 wikilink，见 §6）。

## 3. type 枚举（生产者约定）

消费者须容忍未知 `type`。本仓生产者应使用下表：

| 路径模式 | type |
|----------|------|
| `knowledge/AGENTS.md` | `AgentsSpec` |
| `knowledge/知识地图.md` | `KnowledgeMap` |
| `业务域/*/01-概览.md` | `DomainOverview` |
| `业务域/*/0N-*.md`（非概览） | `DomainModule` |
| `工程平台/*/01-概览.md` | `PlatformOverview` |
| `工程平台/*/0N-*.md`（非概览） | `PlatformModule` |
| `变更/**/01-proposal.md` | `ChangeProposal` |
| `变更/**/02-design.md` | `ChangeDesign` |
| `变更/**/03-tasks.md` | `ChangeTasks` |
| `变更/**/04-review.md` | `ChangeReview` |
| `变更/**/05-summary.md` | `ChangeSummary` |
| `变更/**/06-automation-test.md` | `ChangeTest` |
| `变更/**/07-prd-revisions.md` | `ChangeRevisions` |

推荐字段：`title`、`description`、`timestamp`（ISO 8601）；可选 `tags`、`resource`。

**概念文件（非 `index.md` / `log.md`）另强制**：`related`、`depends_on`（`string[]`，字段必须存在，可为空数组）。校验见 `schema/kb-concept-frontmatter.schema.json` 与 [kb-graph.md](kb-graph.md) §3。

**时效与检索扩展（可选）**：`status`（`current`｜`superseded`，缺省 `current`）、`supersedes`（`string[]`）、`keywords`（`string[]`）。语义见 [kb-graph.md](kb-graph.md) §3.1；写时演化与效用分见 [kb-knowledge-evolve.md](kb-knowledge-evolve.md)。

## 4. 合规条件

**OKF 参考三条件**

1. 每个非保留名 `.md` 含可解析 YAML frontmatter。
2. 每个 frontmatter 含非空 `type`。
3. 若存在 `index.md` / `log.md`，分别符合目录列表与按日分组日志结构。

**本仓图谱扩展（kb 健康，见 kb-graph.md）**

1. 概念文件含 `related`、`depends_on`（可为 `[]`）。
2. 概念文件含 `## 相关`（子模块为「十一、相关」；概览为「十一、相关」；顶级概念为文末 `## 相关`）。
3. 内部链接为 wikilink；`index.md` 列表为 wikilink 格式。
4. 无长期孤儿节点（警告/阻断级别由 `/kb-check` 实现定义）。

**额外警告（不阻断 OKF 字面参考，但阻断 kb 健康）**

- 残留 `知识索引.md`、`00-README.md`、领域/分区下旧名入口。
- 概念文件误用保留名 `index.md`/`log.md` 且带非法 frontmatter（除根 `index.md` 的 `okf_version`）。
- 内部互链仍使用 Markdown `[text](path.md)`。

## 5. 保留名规则

| 文件 | 规则 |
|------|------|
| `index.md` | 无 frontmatter（根目录除外可有 `okf_version`）；分节 + `* [[wikilink]] - description` 列表 |
| `log.md` | 无 frontmatter；`## YYYY-MM-DD` 分组，最新在前 |

## 6. 存量与增量

1. **存量**：`node "${PI_KB_ROOT}/scripts/kb-okf-migrate.mjs" --target <业务仓> --dry-run`，确认后 `--apply`；或 `/kb-okf-migrate`。含 Markdown 内链 → wikilink、补关系字段与 `## 相关`（脚本由实现任务落地）。
2. **增量**：新建/改写概念文件必须带 `type`、`related`、`depends_on` 与 `## 相关`；维护同目录 `index.md`（wikilink 列表）；结构性变更追加同目录 `log.md`，不在正文写「变更记录」段。
3. **校验**：`kb-okf-check.mjs` 或 `/kb-check` 的 OKF 节；图谱节见 [kb-graph.md](kb-graph.md) §7。

## 7. 与 AGENTS 的关系

十段式（含「相关」）、编号子模块、变更 `02`/`03` 结构以 `knowledge/AGENTS.md` 为准；本文件规定 OKF **参考**元数据、入口/日志文件名与 `type`；链接与图谱以 [kb-graph.md](kb-graph.md) 为准。冲突时：内容结构听 AGENTS，入口命名与 frontmatter 听本文件，链接与关系听 kb-graph。