# @suwenguang/pi-kb

KB 知识库驱动开发工作流的 **Pi 原生包**。对应 Claude Code 插件 [`kb-workflow`](https://gitee.com/suveng/kb)（marketplace `doger-kb-plugins`）。

当前版本 **0.1.16**。共享核可自 `kb-workflow` sync；**流程反馈/进化为 Pi 自有模型**（Gitee Issue + 源码 MR），与 CC 业务仓本地 FB 解耦。可选 **EvoMap** 网络进化路径（默认关闭，`/kb-evomap-setup` 开启）。可选 **Cursor Agent**（业务仓装 `pi-cursor-sdk`，`/kb-cursor-setup`）。已 bundled **Figma Remote MCP**（`pi-figma-remote-auth`，`/kb-figma-setup`）。

## 1. 安装（团队共享）

**一条命令即可**（已 bundled `pi-subagents` + `pi-mcp-adapter` + `pi-deepseek-search` + `pi-figma-remote-auth`，含工种子 Agent、`subagent` 工具、MCP 适配、DeepSeek `web_search` 与 Figma Remote 鉴权）：

```bash
# 公共 npm：
pi install npm:@suwenguang/pi-kb -l

# Gitee：
pi install git:gitee.com/suveng/pi-kb -l

# 本地开发 / 进化（先在本仓执行 npm install）：
pi install /path/to/pi-kb -l
```

业务仓信任项目本地配置后，同事 clone 即可自动装缺失包。升级：

```bash
pi update npm:@suwenguang/pi-kb
# 或
pi update --extensions
```

## 2. 业务仓落地

```bash
# 确保 PI_KB_ROOT 已由扩展注入；也可手动 export
node "$PI_KB_ROOT/scripts/kb-bootstrap.mjs" --target "$(pwd)"
```

或在 Pi 中执行 `/kb-init`。随后编辑 `kb.project.json` 的 `codeRoots` / 可选 `integrations`。

CodeGraph：业务仓自行配置项目级 MCP；示例见包内 `bootstrap/examples/mcp/`（`pi-mcp-adapter` 已 bundled，装本包即可用）。

DeepSeek Search：装本包即带 `web_search`。需一次配置 DeepSeek 凭证后 `/reload`：

```bash
# Pi 内 /login 选择 DeepSeek
# 或：
export DEEPSEEK_API_KEY=sk-...
```

引导：`/kb-deepseek-search-setup`；最佳实践：`skills/kb-workflow/references/kb-deepseek-search.md`。无 Key 时不注册工具（不阻断主流程）。

Cursor Agent（可选；**不** bundled，因 `@cursor/sdk` 含按平台二进制）：

```bash
pi install npm:pi-cursor-sdk -l --approve
# /login → Cursor，或：export CURSOR_API_KEY=cursor_...
pi --approve --model cursor/composer-2-5
```

引导：`/kb-cursor-setup`；实践：`skills/kb-workflow/references/kb-cursor-sdk.md`。Node.js ≥ 22.19。

Figma Remote MCP：装本包即带 `/figma-remote-auth` 与 `/figma-oauth-sync`。读设计前完成一次 OAuth + 同步：

```bash
# Pi 内：
/figma-remote-auth setup --project
/figma-remote-auth login
/figma-oauth-sync
# 或 /reload（有明文 token 时 session_start 自动 sync）后 /mcp reconnect figma
```

引导：`/kb-figma-setup`；实践：`skills/kb-workflow/references/kb-figma-remote.md`。可从业务仓 `.pi/settings.json` 移除单独的 `npm:pi-figma-remote-auth`。

## 3. 流程反馈（Gitee Issue）

业务仓使用中遇到 **KB 流程本身** 的摩擦：

```bash
# 一次配置（推荐）
node "$PI_KB_ROOT/scripts/kb-config.mjs" set-token
# 或临时：export GITEE_ACCESS_TOKEN=...   # https://gitee.com/profile/personal_access_tokens
node "$PI_KB_ROOT/scripts/kb-config.mjs" show-source   # 诊断来源，不打印全文
```

- 单条吐槽：`/kb-feedback <描述>` → 向 [gitee.com/suveng/pi-kb](https://gitee.com/suveng/pi-kb) 创建 Issue（label `pi-kb-feedback`）。
- **会话级复盘**：`/kb-session-retro` → 总结本会话失败/摩擦经验，并对可改进项**自动**开 Issue（或同因评论）。扩展在 `/new` / resume 前若检测到摩擦，**零确认**自动注入本命令；执行中旁路攒候选（不阻断）。
- **不要求**业务仓已 `/kb-init`（反馈类命令豁免 Bootstrap 门禁）。

- **不**写业务仓 `knowledge/.../反馈/`
- **不**在 npm 副本上改流程文件

## 4. 本地进化环境 + MR

想改流程并贡献回上游：

1. `/kb-evolve-setup`（或手动 clone 源码 / fork，再 `pi install <绝对路径> -l`）
2. `/reload` 后 `/kb-root`，确认等于源码路径（非 `node_modules`）
3. 在源码仓 `/kb-evolve`（拉取 open Issue → 确认 → 改包 → `docs/evolution/`）
4. push 分支 → 脚本提 MR 到 `master`
5. 维护者合入后 bump / `npm publish`；业务仓 `pi update`

机器探测是否可进化：

```bash
node "$PI_KB_ROOT/scripts/kb-evolve-setup.mjs" --check
```

细则：`skills/kb-workflow/references/kb-feedback-gitee.md`、`docs/evolution/README.md`。

## 4.1 可选：EvoMap 网络进化（默认关闭）

作者想让 `/kb-evolve` 检索全球 Agent 网络上的最佳路径（并可回传）：

1. `/kb-evomap-setup`（Agent 注册节点 → 展示 `claim_url` → 你浏览器绑定一次 → `enable`）
2. 可选 `enable --publish`：进化成功后允许**经确认**回传 Gene/Capsule
3. 之后 `/kb-evolve` 会 `search` 网络路径并入提案；未开启时行为与旧版一致

```bash
node "$PI_KB_ROOT/scripts/kb-evomap.mjs" status --json
```

配置：`~/.config/pi-kb/evomap.json`；凭证：`~/.evomap/`（不进 git）。  
直连失败时自动探测本机 Clash 等常见端口（7890/1080/1897…）并走代理；也可设 `HTTPS_PROXY` 或配置 `"proxy"`。细则：`skills/kb-workflow/references/kb-evomap.md`。

## 5. 常用斜杠命令

| 命令 | 作用 |
|------|------|
| `/kb-orchestrator` | 意图识别与编排（新建默认 lite；下一跳见 `kb-stage-next.mjs`） |
| `/kb-lite` | 轻量变更（**默认新建入口**） |
| `/kb-propose` | 业务 PRD / 标准流 |
| `/kb-design` | 技术设计 |
| `/kb-plan` | 任务拆解 |
| `/kb-apply` | 落地实现 |
| `/kb-review` | 评审 |
| `/kb-test` | 验收 |
| `/kb-archive` | 归档 |
| `/kb-feedback` | 流程摩擦 → Gitee Issue |
| `/kb-session-retro` | 会话回顾失败经验 → 自动 Gitee Issue |
| `/kb-evolve-setup` | 搭建本地进化环境 |
| `/kb-evomap-setup` | 开启/关闭 EvoMap 网络进化（默认关闭） |
| `/kb-deepseek-search-setup` | DeepSeek Search（`web_search`）配置引导 |
| `/kb-cursor-setup` | Cursor Agent（`pi-cursor-sdk`）安装与 Key 引导 |
| `/kb-figma-setup` | Figma Remote MCP（`pi-figma-remote-auth`）setup/login 引导 |
| `/kb-evolve` | 源码仓进化 + MR（勿在业务仓 npm 副本执行；可选 EvoMap） |
| `/kb-root` | 打印包根路径 |

完整列表见 `prompts/`。

## 6. 与 Claude 插件的关系

| | Claude（`kb` 仓） | Pi（本仓） |
|--|-------------------|-----------|
| 分发 | marketplace + plugin install | `pi install npm:@suwenguang/pi-kb` |
| 命令 | `plugin/commands` | `prompts/` → `/kb-*` |
| Skills / scripts / bootstrap / schema | `plugin/` | **sync 自 kb**（随后 overlay Pi 反馈口径） |
| 反馈/进化 | 业务仓本地 FB + evolve | **Gitee Issue + 源码 MR**（Pi 自有：`feedback` / `session-retro` / `evolve` / `evolve-setup` / `evomap-setup`，migrate 跳过）；可选 EvoMap |
| Agents | `plugin/agents` | `agents/` + `pi-subagents` |
| 包根变量 | `CLAUDE_PLUGIN_ROOT` | `PI_KB_ROOT` |

共享核真相仍可在 `kb/plugin`；本仓维护者在 `kb` 更新后执行：

```bash
npm run migrate   # sync + overlay + 重生成 prompts/agents（跳过 feedback/evolve/setup）
```

再 bump 本包 `version`、写 `CHANGELOG.md`、`npm publish --access public`。

## 7. 发布到公共 npm

```bash
npm login
npm publish --access public
```

当前包名为 `@suwenguang/pi-kb`（npm 账号 `suwenguang`）。

## 8. 开发

```text
pi-kb/
  prompts/          # Pi 斜杠 prompt（Pi 自有：feedback/session-retro/evolve/evolve-setup）
  agents/           # pi-subagents 工种定义
  skills/           # sync + Pi overlay
  scripts/          # sync + migrate + gitee/evolve-setup/evomap
  pi-overlays/      # sync 后写回的 Pi 口径源
  docs/evolution/   # 源仓进化日志
  bootstrap/ schema/
  extensions/kb-root.ts
```

```bash
npm run sync              # 同步共享核 + 应用 Pi feedback overlay
npm run migrate:prompts   # 重生成 prompts（跳过 Pi 自有四个）
npm run migrate:agents    # 重生成 agents
npm run migrate           # 以上全部
```

## 9. 版本对应

| @suwenguang/pi-kb | kb-workflow |
|--------------|-------------|
| 0.1.16 | （知识图谱自进化 + stage-next / 新建默认 lite） |
| 0.1.15 | （bundled Figma Remote：`/kb-figma-setup` + kb-figma-remote.md） |
| 0.1.14 | （Cursor Agent 配套：`/kb-cursor-setup` + kb-cursor-sdk.md） |
| 0.1.13 | （bundled DeepSeek Search + 归档门禁） |
| 0.1.8 | （会话回顾 /kb-session-retro + 自动反馈） |
| 0.1.7 | （修复 prompt YAML argument-hint） |
| 0.1.6 | （Pi 反馈模型；共享核可至 0.7.5） |
| 0.1.5 | 0.7.5 |
| 0.1.4 | 0.7.3 |
| 0.1.3 | 0.7.2 |
| 0.1.2 | 0.7.2 |
| 0.1.1 | 0.7.2 |
| 0.1.0 | 0.7.2 |