---
description: 将业务仓 knowledge/ 存量迁移为 OKF Bundle（frontmatter type、index.md、log.md）。
argument-hint: "[--dry-run|--apply]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
将业务仓 `knowledge/` 对齐 [Open Knowledge Format](../skills/kb-workflow/references/kb-okf.md)（OKF v0.1）与本仓 [知识图谱契约](../skills/kb-workflow/references/kb-graph.md)。默认先 dry-run，确认后再 apply。

**输入**：可选。
- `dry-run`（默认）：只报告，不写盘
- `apply`：执行迁移
- 不指定：先 dry-run，向用户确认后再 apply

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## 约束

- **只改** `knowledge/**` 下 Markdown 结构、frontmatter、入口重命名与库内链接；**不改**业务代码、`00-manifest.json` 语义、`kb.project.json`。
- 目标已存在 `index.md` 且与待重命名源冲突时**中止**，不静默覆盖。
- 变更状态机仍以 `00-manifest.json` 为准；`01`～`07` 仅补 `Change*` frontmatter。

## 执行步骤

1. 确认业务仓根（含 `kb.project.json` 或 `knowledge/`）。
2. 运行校验（只读）：

```bash
node "${PI_KB_ROOT}/scripts/kb-okf-check.mjs" --target "$(pwd)"
```

3. Dry-run：

```bash
node "${PI_KB_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --dry-run
```

4. 向用户展示：计划重命名、type 分布、log 抽取、冲突。用户确认后执行：

```bash
node "${PI_KB_ROOT}/scripts/kb-okf-migrate.mjs" --target "$(pwd)" --apply
```

5. 再次 `kb-okf-check.mjs`；若有警告（正文残留变更记录等）逐条处理。
6. 建议运行 `/kb-index` 复核各层 `index.md` wikilink 列表（[kb-graph.md](../skills/kb-workflow/references/kb-graph.md) §6）。

## 迁移做了什么

1. 为概念文件补 YAML frontmatter（必填 `type`，推断见 `kb-okf.md`）。
2. 从「十/十一、变更记录」抽条目写入同目录 `log.md`，并删除该段。
3. `知识索引.md` → `index.md`；`00-README.md` / 平台或子目录 `README.md` → `index.md`。
4. **图谱**：存量 `[标题](相对路径.md)` 内链改写为 `[[wikilink]]`（目标无 `.md` 后缀）；为概念文件补空数组 `related` / `depends_on` 与「相关」段（子模块「十一、相关」、概览「十一、相关」、顶级 `## 相关`）；`index.md` 列表改为 `* [[wikilink]] - description`。
5. 改写库内旧路径链接；根 `index.md` 写入 `okf_version: "0.1"`。
6. 变更目录 `01`～`07` 仅补 `Change*` frontmatter，**暂不强制** `related` / `depends_on`。

## 输出格式

```markdown
## OKF 迁移报告

- 模式：dry-run / apply
- 重命名：N
- frontmatter：N
- 图谱（wikilink / related / 相关段）：N
- log 更新：N
- 校验：通过 / 阻断列表
- 下一步：/kb-index 或无
```