@suwenguang/pi-kb

KB 知识库驱动开发工作流的 Pi 原生包。对应 Claude Code 插件 kb-workflow（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 鉴权）：

# 公共 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 即可自动装缺失包。升级：

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

2. 业务仓落地

# 确保 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：

# 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 含按平台二进制）：

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 + 同步：

# 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 流程本身 的摩擦：

# 一次配置（推荐）
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 创建 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

机器探测是否可进化：

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 网络路径并入提案；未开启时行为与旧版一致

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 更新后执行：

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

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

7. 发布到公共 npm

npm login
npm publish --access public

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

8. 开发

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

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