---
description: 搭建 pi-kb 本地进化环境（克隆/fork 源码、业务仓改挂本地包、拉 evolve 分支）
argument-hint: "[--clone-dir DIR] [--fork-url URL] [--branch NAME]"
---

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

## 用户输入

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

---
帮助已用 npm 安装 pi-kb 的人，搭好**可改流程并提 MR**的本地环境。本命令**不**修改流程文件、**不**开 Issue；改流程请随后在源码检出内跑 `/kb-evolve`。

细则见 [kb-feedback-gitee.md](../skills/kb-workflow/references/kb-feedback-gitee.md)。

**输入**（可选）：克隆目录、fork URL、分支名。缺省时：`../pi-kb`（相对业务仓）、上游 `https://gitee.com/suveng/pi-kb.git`、分支 `evolve/<14位时间戳>`。

## 约束

- **主 Agent 不写文件**：克隆、改 `.pi/settings.json`、拉分支均由子 Agent 调脚本或 shell 完成。
- **不强制 fork**、不自动 push、不自动合 master。
- 贡献者推荐 clone **自己的 fork**，并加 `upstream`；维护者可直接 clone 上游。
- 提 Issue/MR 需要 `GITEE_ACCESS_TOKEN`；未设置时脚本只警告，不阻断搭环境。

## 执行步骤

1. **澄清**：若用户未说明 clone 路径 / 是否用 fork，问**一个**问题；或按缺省继续并在回报中写明假设。
2. **跑搭建脚本**（在业务仓 cwd）：

```bash
node "${PI_KB_ROOT}/scripts/kb-evolve-setup.mjs" \
  [--clone-dir <绝对路径>] \
  [--fork-url <https://gitee.com/<you>/pi-kb.git>] \
  [--branch evolve/<主题或日期>] \
  [--biz-dir "$(pwd)"]
```

3. **核对**：
   - 脚本输出「源码路径」存在且 `package.json` name 为 `@suwenguang/pi-kb`。
   - 提示用户 `/reload` 后执行 `/kb-root`，确认等于源码路径（**禁止**仍是 `node_modules/@suwenguang/pi-kb`）。
   - **未 /reload 前**当前会话 `PI_KB_ROOT` 可能仍是旧 node_modules；勿据此误判搭建失败。
4. **可选门禁自检**（在**源码目录** cwd 跑，避免 env 滞后）：

```bash
cd <源码路径> && node scripts/kb-evolve-setup.mjs --check
# 亦可：node "${PI_KB_ROOT}/scripts/kb-evolve-setup.mjs" --check
# --check 优先认定 cwd 为源码检出；若 cwd 与滞后 PI_KB_ROOT 不一致，以 cwd 为准并可能带 warning
```

exit 0 才允许后续 `/kb-evolve`。

## 输出格式

```markdown
## 本地进化环境

| 项目 | 内容 |
|---|---|
| 源码路径 | … |
| 分支 | … |
| token | 已设置 / 未设置 |
| 下一步 | /reload → /kb-root 核对 → 在源码仓 /kb-evolve |
```

## 退出口径

- 本命令不提交 git、不创建 Gitee Issue/MR。
- 业务仓继续只用 npm 包、只反馈不进化时：无需本命令，用 `/kb-feedback` 即可。