# Pi：流程反馈与进化（Gitee Issue + 源码 MR）

> 本文件为 **@suwenguang/pi-kb 自有口径**，与 Claude Code `kb-workflow` 的「业务仓本地 `反馈/FB-*.md` + `/kb-evolve`」模型**解耦**。  
> `npm run sync` / `migrate` 不得覆盖本文件；Pi 专用 prompts：`kb-feedback` / `kb-session-retro` / `kb-evolve` / `kb-evolve-setup` / `kb-evomap-setup` 亦跳过 migrate。

## 1. 角色

| 角色 | 命令 | 落点 |
|------|------|------|
| 业务仓使用者 | `/kb-feedback` | 仅向 [gitee.com/suveng/pi-kb](https://gitee.com/suveng/pi-kb) 建 Issue（label `pi-kb-feedback`） |
| 业务仓使用者 | `/kb-session-retro` | **会话级**总结失败/摩擦经验，并对可改进项**自动**建 Issue（或同因评论） |
| 贡献者 | `/kb-evolve-setup` → `/kb-evolve` | 源码检出内改流程 → feature 分支 → **MR → master** |
| 贡献者 | `/kb-evomap-setup`（可选） | 开启 EvoMap：注册节点 / claim / enable；默认关闭，见 [kb-evomap.md](kb-evomap.md) |
| 维护者 | 合入 MR 后 bump / CHANGELOG / `npm publish` | 业务仓 `pi update` |

## 2. 硬约束

1. 业务仓**禁止**写 `knowledge/工程平台/KB工作流/反馈/`。
2. 业务仓**禁止**在 npm 副本（`node_modules/@suwenguang/pi-kb`）上跑 `/kb-evolve`。
3. `/kb-feedback`、`/kb-session-retro` **豁免** Bootstrap 门禁（不依赖业务仓 KB 骨架；禁止因未 `/kb-init` 而硬拦反馈）。
4. `/kb-evolve` 仅当工作目录（或可进化的检出路径）是 **pi-kb git 源码检出**：`package.json` name=`@suwenguang/pi-kb` 且 remote 含 `gitee.com/.../pi-kb`。机器探测：

```bash
# 优先在源码仓 cwd 跑；--check 会优先认定「当前 cwd 是源码检出」而非滞后的 PI_KB_ROOT
node scripts/kb-evolve-setup.mjs --check
# 或：node "$PI_KB_ROOT/scripts/kb-evolve-setup.mjs" --check
```

5. 进化默认 **不直推 master**：commit → push 分支 → `kb-gitee-issue.mjs mr`。
6. 合入前**不强制 close** Issue；MR 正文可用 `Closes #N`，或合入后由维护者关闭。

## 3. 会话级回顾（`/kb-session-retro`）

1. **何时用**：本会话内多次门禁/阶段/口径摩擦；收工前想沉淀「流程该怎么改」；扩展在 `/new` / resume 前检测到摩擦时**零确认**自动注入本命令。
2. **做什么**：只读会话上下文 → 分流（流程 / 编码 AGENTS 建议 / 验收）→ 对流程项自动 `kb-gitee-issue.mjs` create/comment（标题含 `[会话回顾]`，body 含 `[pi-kb-session-retro]`）。可合并扩展旁路写入的 feedback 候选（`kb-feedback-candidates.mjs list`）。
3. **不做什么**：不写本地 FB、不改 prompts/skills、不落盘 AGENTS、不推进变更 stage。
4. **与 `/kb-feedback`**：单条明确吐槽用 feedback；整段会话复盘用 session-retro（可一次多项，新建 Issue 上限 3）。

## 4. 脚本

| 脚本 | 用途 |
|------|------|
| `scripts/kb-gitee-issue.mjs` | `create` / `list` / `comment` / `close` / `mr` |
| `scripts/kb-config.mjs` | `set-token` / `show-source`（Gitee token 持久化） |
| `scripts/kb-evolve-setup.mjs` | 克隆/fork、改 `.pi/settings.json`、拉分支、`--check` |
| `scripts/kb-feedback-candidates.mjs` | 旁路摩擦候选：`list` / `add` / `ack` / `dismiss` / `clear` |
| `scripts/kb-evomap.mjs` | EvoMap：`status` / `enable` / `disable` / `register` / `search` / `publish`（默认关闭） |

认证优先级：`GITEE_ACCESS_TOKEN` 环境变量 → `~/.config/pi-kb/token` → 业务仓 `.kb-token`（须 gitignore）。一次配置：`node "$PI_KB_ROOT/scripts/kb-config.mjs" set-token`（从 stdin 读入，不回显到帮助输出）。  
令牌申请：[个人访问令牌](https://gitee.com/profile/personal_access_tokens)（需 issues / 仓库权限）。  
EvoMap：见 [kb-evomap.md](kb-evomap.md)（`~/.config/pi-kb/evomap.json` + `~/.evomap/`）。

## 5. 进化日志

源仓目录：`docs/evolution/<YYYYMMDDHHMMSS>-<中文主题>.md`（一轮一文件）。  
业务仓 knowledge **不**再作为流程进化日志落点。采用 EvoMap 资产时在日志中记录 `evomap_asset_ids`。

## 6. 闭环摘要

```text
业务仓 /kb-feedback 或 /kb-session-retro → Gitee Issue
       ↓
（可选）/kb-evolve-setup 拉源码 + 本地 pi install -l
       ↓
（可选）/kb-evomap-setup → enabled=true（默认关闭）
       ↓
源码仓 /kb-evolve →（若启用）search 网络路径 → 改 prompts/skills/agents/… + docs/evolution
       ↓
push 分支 → Gitee MR → master → 维护者 publish → 业务仓 pi update
       ↓
（若 publish=true）validate → publish 回 EvoMap（默认回传；首次提示；用户当轮拒绝则跳过）
```