---
description: 在当前项目初始化 KB 工作流（knowledge 骨架、schema、kb.project.json）
argument-hint: "[可选：说明]"
---

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

## 用户输入

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

---
为**尚未接入** kb-workflow 插件的项目做一次性初始化。已存在 `kb.project.json` 或完整 `knowledge/` 时只补缺，不覆盖业务正文。

**与 `kb-bootstrap` 的关系**：`/kb-init` 是斜杠命令入口；落地动作就是执行 `kb-bootstrap.mjs`。无第二套初始化逻辑。其他 `/kb-*` 开始前须通过 `kb-bootstrap-check.mjs`。

## 执行方式（子 Agent 用 shell）

从已安装插件执行 bootstrap（`${PI_KB_ROOT}` 由 Claude Code 注入）：

```bash
node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
```

初始化完成后可自检：

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

**前提**：已在当前仓库 **project scope** 安装并启用 `kb-workflow` 插件（见 `docs/CLAUDE_MARKETPLACE.md` §一、§三）。不推荐 user scope 全局安装。

## 初始化产物

| 路径 | 说明 |
|------|------|
| `kb.project.json` | 项目级路径与代码根配置（**必改** `codeRoots`）；外部集成在 `integrations.*` 配置 |
| `knowledge/` | 知识库骨架（索引、地图、变更目录） |
| `knowledge/AGENTS.md` | 知识文件内容规范 |
| `.kb/kb-manifest.schema.json` | manifest JSON Schema（每次 bootstrap **覆盖**，随插件版本更新） |

**不在业务仓复制**：dispatcher 等运行时脚本随插件安装在 `${PI_KB_ROOT}/scripts/`；CodeGraph MCP 由**业务仓项目级配置**提供（见下文），bootstrap **不**写入 MCP 文件。

## 初始化后人工步骤

1. 编辑 `kb.project.json` 的 `codeRoots`，对齐本仓库真实目录。
2. 按需维护 `knowledge/知识地图.md` 与 `knowledge/业务域/**`。
3. 若需外部登记/通知：在 `kb.project.json` 配置 `integrations.registry` / `integrations.notifications` 及 provider `handler`（建议 `.kb/providers/<name>.mjs`，由扩展插件写入）。
4. 在项目根执行 CodeGraph 索引：

```bash
npx -y @colbymchenry/codegraph@0.9.3 init
npx -y @colbymchenry/codegraph@0.9.3 index
```

5. **按当前宿主复制项目级 MCP 示例**（bootstrap 不自动写入；**禁止**无脑双写）：

先判定宿主（Cursor → `.cursor/mcp.json`；Claude Code / 其他 → 根 `.mcp.json`），**只写一份**：

```bash
# Claude Code / 其他（含 pi）
cp "${PI_KB_ROOT}/bootstrap/examples/mcp/claude.mcp.json" .mcp.json

# 仅当当前宿主为 Cursor 时：
# mkdir -p .cursor
# cp "${PI_KB_ROOT}/bootstrap/examples/mcp/cursor.mcp.json" .cursor/mcp.json
```

双 IDE 仅当用户**明确要求**时再补另一份。若目标文件已存在，手动合并 `codegraph` server 条目，勿与已有 MCP 重复冲突。细则见 `skills/kb-workflow/references/kb-codegraph.md` §一。

6. 使项目级 MCP 生效：Cursor 执行 **Developer: Reload Window**；Claude Code / 其他重启会话或按宿主要求重载 MCP。

7. **（Pi）DeepSeek Search**：本包已 bundled `pi-deepseek-search`（工具 `web_search`）。请用户完成一次凭证配置后 `/reload`：
   - `/login` 选择 DeepSeek；或 `export DEEPSEEK_API_KEY=...`
   - 引导命令：`/kb-deepseek-search-setup`；最佳实践：`skills/kb-workflow/references/kb-deepseek-search.md`
   - 无 Key 时扩展不注册 `web_search`（不阻断 KB 主流程）

8. **（Pi，可选）Cursor Agent**：若要用 Cursor 模型（如 Composer）跑 `/kb-*`，业务仓另装扩展（本包**不** bundled）：
   - `pi install npm:pi-cursor-sdk -l --approve`，然后 `/login` 选 Cursor（或 `export CURSOR_API_KEY=...`）
   - 启动：`pi --approve --model cursor/composer-2-5`
   - 引导命令：`/kb-cursor-setup`；实践：`skills/kb-workflow/references/kb-cursor-sdk.md`

9. **（Pi）Figma Remote MCP**：本包已 bundled `pi-figma-remote-auth` + token sync。读设计帧/组件前：
   - `/figma-remote-auth setup --project` → `/figma-remote-auth login` → `/figma-oauth-sync` → `/mcp reconnect figma`
   - 引导：`/kb-figma-setup`；实践：`skills/kb-workflow/references/kb-figma-remote.md`
   - 与 `/kb-propose` 产品闸门（有无设计图）分工见实践文档

## 约束

- **禁止**覆盖已有 `knowledge/业务域/**` 正文。
- bootstrap **不**写入含密钥的凭证文件。
- 初始化完成后可用 `/kb-check` 或 `/kb-explore` 验证检索路径。

## 从旧版迁移

### 曾依赖插件自动 MCP（已废弃）

旧版通过插件 `plugin/.mcp.json` 在启用 `kb-workflow` 时自动连接 CodeGraph，**已不再支持**。须按上文步骤 5～6 改为业务仓项目级配置（**只写当前宿主**对应文件）。若曾无脑双写：保留当前宿主那一份，删除多余副本。

### 曾 bootstrap 写入 `.cursor/`

若业务仓仍有 `.cursor/kb-manifest.schema.json`、由旧 bootstrap 写入的 `.cursor/mcp.json` 或 `.cursor/scripts/codegraph-mcp.cjs`：

1. 重新执行 `/kb-init`（或上述 bootstrap 命令）以写入 `.kb/kb-manifest.schema.json`。
2. 将 `kb.project.json` 的 `manifestSchema` 改为 `.kb/kb-manifest.schema.json`（新仓 bootstrap 已默认）。
3. 删除 `.cursor/` 下由 kb-workflow 旧 bootstrap 写入的 schema / launcher 副本；**保留**你自行配置的其他 Cursor 文件。若当前宿主非 Cursor 且无团队 Cursor 需求，可删除误写的 `.cursor/mcp.json`；若当前宿主为 Cursor，按步骤 5 合并或更新 CodeGraph MCP 条目。