# 🌟 pi-unifan-zh (Pi 中文扩展全家桶与独立插件库)

专为 **Pi Coding Agent** 打造的高质量中文扩展合集与独立插件库。

支持 **“全家桶一键整包安装”** 与 **“按需单个插件独立安装”** 双模式架构。

---

## 📁 目录结构

```text
pi-unifan-zh/
├── package.json              # 根包配置（支持整包一键安装）
├── tsconfig.json             # TypeScript 配置
├── AGENTS.md                 # 开发者与智能体规范指南
├── README.md                 # English Documentation
├── README_zh.md              # 中文说明文档
├── extensions/               # 📦 扩展插件集
│   ├── sessions/             # 📜 ① 历史会话管理器（双栏实时预览与恢复·中文增强版）
│   ├── review/               # 🔍 ② AI 代码审查套件（日常3专家 / 极速单兵 / 性能探针 / 全量会诊）
│   ├── commit/               # 📦 ③ 智能 Git 提交助手（Conventional Commits 纯中文规范版）
│   └── workflow/             # 🔄 ④ 复合工程工作流引擎（状态感知 / 断点续跑 / 输出压缩）
└── skills/                   # 🎯 复合工程流程技能库 (00-next ~ 05-learn)
    ├── 00-next/              # 🚦 流程导航调度器（自动分析仓库产物并推荐下一步）
    ├── 01-brainstorm/        # 💡 需求发现与交互对齐（单选/多选复选框/开放问答）
    ├── 02-plan/              # 📐 TDD 架构规划与 Implementation Units 拆解
    ├── 03-work/              # 🛠️ 严格 TDD 编码执行与断点持久化
    ├── 04-review/            # 🧐 代码审查与回归测试闭环
    └── 05-learn/             # 📝 极简避坑指南与经验复利沉淀
```

---

## 🚀 安装指南

### 模式 A：一键安装整包（包含所有插件与技能）

#### 1. 通过 npm 在线安装（推荐 ⭐）：
```bash
pi install npm:@unifan/pi-unifan-zh
```

#### 2. 通过 GitHub 远程在线安装：
```bash
pi install git:github.com/821869798/pi-unifan-zh
```

#### 3. 本地开发调试安装：
```bash
pi install D:/program/my/pi-unifan-zh
```

---

### 模式 B：按需单独安装单个插件

每个插件均已独立打包并发布至 npm，可根据需要挑选单独安装（互不依赖，开箱即用）：

> 💡 **提示**：Pi CLI 的 `git:` 方式仅支持安装整个仓库根目录；若需**按模块单独安装**，请使用推荐的 `npm:` 方式或本地绝对路径。

#### 1. 仅安装 `sessions`（历史会话管理器·中文版）：
```bash
# npm 在线单独安装
pi install npm:@unifan/pi-sessions-zh
# 或本地路径安装
pi install D:/program/my/pi-unifan-zh/extensions/sessions
```

#### 2. 仅安装 `review`（AI 代码审查系统·中文版）：
```bash
# npm 在线单独安装
pi install npm:@unifan/pi-review-zh
# 或本地路径安装
pi install D:/program/my/pi-unifan-zh/extensions/review
```

#### 3. 仅安装 `commit`（智能 Git 提交助手·中文版）：
```bash
# npm 在线单独安装
pi install npm:@unifan/pi-commit-zh
# 或本地路径安装
pi install D:/program/my/pi-unifan-zh/extensions/commit
```

#### 4. 仅安装 `workflow`（复合工程工作流引擎与全套技能·中文版）：
> 包含 `/workflow` 命令、断点续跑、Token压缩器以及完整的 6 大流程技能 (`00-next` ~ `05-learn`)。
```bash
# npm 在线单独安装
pi install npm:@unifan/pi-workflow-zh
# 或本地路径安装
pi install D:/program/my/pi-unifan-zh/extensions/workflow

# 推荐搭配安装交互提问工具（支持现代终端多选复选框与单选）：
pi install npm:@juicesharp/rpiv-ask-user-question
```

---

## 📦 扩展功能与核心命令

### 1. 📜 `sessions`（历史会话管理器·中文版）
- **命令**：`/sessions`
- **特性**：
  - 双栏全屏 TUI 视图（左侧选会话与 Git 变更统计，右侧毫秒级实时滚屏预览完整对话）。
  - 支持 `◆ 用户`、`● 助手`、`◌ 思考过程`、`▸ 工具调用` 与折叠。
  - 界面与时间提示（刚刚/X分钟前/昨天）全面中文化。
  - 零多余 Token 消耗，纯净轻快。
- **快捷键**：
  - `Enter`：一键恢复并切换到所选会话。
  - `t`：展开/折叠工具输出。
  - `h`：展开/隐藏思考过程。
  - `Tab`：切换左右面板焦点。
  - `PgUp` / `PgDn`：预览窗滚屏翻页。
  - `Ctrl+T` / `Alt+W`：切换全部工作区/仅当前项目。
  - `Esc`：退出选择器。

---

### 2. 🔍 `review`（AI 交互式代码审查套件·中文版）
- **架构亮点**：
  - 参考并融合了 **Codex 与 pi-agent-extensions**（Armin Ronacher @mitsuhiko）的经典架构。
  - **双执行引擎自由切换**：
    - ① **单模型深度审查（默认推荐）**：0 子代理依赖，0 网络断流，极速且 100% 稳定。
    - ② **多 Subagent 并发审查**：支持自由配置并发启动 **2、3、4、5、6** 个专家子代理协同会诊（Bug猎手、安全专家、性能探针、规范合规、注释质量、历史脉络）。
  - **会话模型与思考档位继承**：单模型审查和主审汇总直接使用当前会话；多专家审查通过一个异步工作流启动，在每个专家请求中显式传入当前会话的 `提供方/模型:思考档位`，避免被子代理默认配置覆盖。
- **核心审查命令**：
  - **`/review`** 🔍 **（交互式全功能审查）**：唤起全中文 TUI 选择弹窗，支持 6 种审查模式与配置中心：
    - ① `审查未提交改动` (工作区已暂存 + 未暂存代码，智能默认推荐)
    - ② `与基准分支对比审查` (如与 main / master / dev 自动计算 merge-base 对比)
    - ③ `审查指定提交` (从最近提交历史中搜索挑选)
    - ④ `审查 Pull Request` (输入 PR 编号或 GitHub URL 本地自动检出审查)
    - ⑤ `审查指定目录/文件` (全量静态快照审查，非 diff)
    - ⑥ `自定义审查要求` (针对并发安全、GC/性能、指定接口等重点排查)
    - ⑦ `⚙️ 审查配置中心` (弹窗设置：单模型 / 多Subagent并发数 2~6 个)
  - **`/review-config`** ⚙️ **（审查配置中心）**：独立配置命令，随时切换审查引擎模式与并发数（配置自动保存在 `~/.pi/agent/pi-review.json`）。
  - **`/review-lite`** ⭐ **（极速单兵审查）**：无需弹窗，直接对当前工作区未提交改动做闪电审查（零多余前置步骤）。
  - **`/review-full`** 🚀 **（全量深度审查）**：直接对当前工作区与分支全部改动展开深度审查，严禁输出任何待办清单和环境测试，秒级直达 P0~P3 审查发现！
  - **`/review-sync`** 🔄 **（双会话审查接力闭环 · 自动识别角色）**：
    - **开发会话粘贴审查意见**：自动识别为【代码修复】，逐项核验：有道理的立即改代码并总结修改了啥，没有道理的在总结中解释为什么没道理。
    - **审查会话粘贴修复报告**：自动识别为【只读复核】，绝不盲信文字报告，必须对照 `git diff` 实际看改动代码且**严禁改动任何代码**，满意后输出 `✅【审核通过，可以提交代码】`！
  - **`/review-end`** 🏁 **（结束审查并返回，别名 `/end-review`）**：
    - 自动将审查分支中发现的 `[P0~P3]` 缺陷与待办事项生成结构化中文报告。
    - 一键平滑跳回主开发会话分支，并自动在输入框回填 `根据上述代码审查发现进行修改修复`！
- **极简高效，彻底告别繁琐步骤**：
  - 彻底干掉了任何“打印步骤待办清单（Checklist）”、“多轮执行 bash 测试文件”等冗余步骤，指令直达 `git diff`，直接输出代码发现。
- **命令行参数支持**：
  - `/review --subagents -c 2`：临时以 2 个专家并发启动审查
  - `/review --single`：强制单模型直接审查
- **审查准则与标准**：
  - **P0~P3 严格分级**：致命阻塞、紧急待修、普通建议、细节优化。
  - **严格过滤误报**：基于代码事实与真实 diff，杜绝主观臆测，重点排查并发竞态、内存开销、外部未受信输入与边界异常。
  - **支持项目定制规范**：自动识别并加载项目根目录的 `REVIEW_GUIDELINES.md`、`AGENTS.md` 或 `CLAUDE.md`。

---

### 3. 📦 `commit`（智能 Git 提交助手·中文版）
- **命令**：
  - **`/commit`**：自动分析暂存区/工作区代码变动（`git diff`），使用当前会话模型与思考档位，由提供方统一转换模型参数，根据实际暂存内容生成标准的 Conventional Commits 纯中文提交信息后提交。模型认证、请求、空结果或输出校验失败时会显示原因并停止提交与推送，保留暂存内容，不再使用固定兜底文案。
  - **`/commit-push`** 🚀：自动生成中文 Commit 提交，并**自动执行 `git push` 推送**到远端分支。
- **常用参数与用法**：
  - `/commit`：智能提交（有暂存只提暂存，无暂存自动暂存全量）。
  - `/commit -a` 或 `/commit --all`：自动强制暂存所有工作区修改（`git add -A`）并提交。
  - `/commit 修复了技能释放异常`：带提示词定向引导生成提交信息。
- **核心工程规范**：
  - **11 大标准分类**：`feat`, `fix`, `perf`, `refactor`, `ci`, `build`, `chore`, `docs`, `test`, `style`, `revert`。
  - **严格半角英文标点**：括号 `()` 与冒号空格 `: ` 严格使用英文半角字符，确保 CI / Commitlint 正则解析合规。
  - **严禁 Emoji**：保持严谨、专业的纯文本工程风格。
  - **智能自动变基（Auto Rebase）**：在 `/commit-push` 时，若远端有别人先提交的代码被拒绝，**自动在后台执行 `git pull --rebase` 变基并自动重试推送**，Git 历史保持一条干净直线！
  - **智能冲突引导**：变基遇冲突时列出冲突文件，提示严禁直接用 ours/theirs 覆盖，需按修改对比与上下文解决。
  - **未推送提交自动同步**：即使当前工作区干净，若检测到本地有尚未 push 的历史 Commit，`/commit-push` 也会自动将其推送至远端！

---

### 4. 🔄 `workflow` 与复合工程流 (Compound Engineering)
本套件内嵌完整的 **Pi 原生复合工程流体系**，将 AI 辅助编程从“随性写代码”升级为“严格的工程流水线”：

```text
00-next  ──>  01-brainstorm  ──>  02-plan  ──>  03-work  ──>  04-review  ──>  05-learn
 (智能调度)       (需求澄清)       (TDD计划)      (断点编码)      (质量审查)     (极简复盘)
```

- **核心命令与工具**：
  - **`/workflow`**：快速在终端查看当前项目工作流阶段、各产物数量、当前自主循环进度与下一步推荐技能。
  - **`workflow_state`** 工具：自动扫描 `docs/` 与 `.context/checkpoints/` 状态。
  - **`artifact_helper`** 工具：规范化解析和建立需求、计划与避坑文档。
  - **`session_checkpoint`** 工具：以 Implementation Unit 为粒度记录执行断点，**写一半中断后再次启动自动从断点续跑，绝不重头重来**。
- **6 大内置流程技能**：
  - **`00-next`（智能路标）**：用户随口说 `continue`、`下一步` 或输入 `/skill:00-next`，自动探查当前进度并无缝引导至下一个环节。
  - **`01-brainstorm`（需求发现）**：引导需求澄清，**灵活调用 `@juicesharp/rpiv-ask-user-question`**：互斥方案用单选（1-9直选）、模块清单用多选复选框、开放问题自由输入，自然对齐技术方案。
  - **`02-plan`（计划拆解）**：将需求拆解为包含验证命令与改动清单的 Implementation Units，坚持极简阶梯（The Ladder）原则。
  - **`03-work`（跨回合自主循环驱动编码）** 🚀：**原生内置类似 `goal` 的连续自动驱动引擎**。直接使用 `/skill:03-work`（或要求执行计划）启动后，后台引擎按计划中的 Implementation Units 逐单元跨回合自主推进“红-绿-重构”，**不做完规划任务绝不停机**！支持断点续跑与遇错即停（Stop-the-line）硬门禁；如需暂停，输入 `暂停`、`pause` 或按 `Esc` 即可。
  - **`04-review`（审查闭环）**：全量代码审查、Spec 需求符合度核验、回归测试绿灯检查。
  - **`05-learn`（极简知识复盘）**：价值门禁驱动，仅沉淀非平凡的疑难避坑卡片至 `docs/solutions/`，坚决不制造文档噪音。
- **内置上下文优化黑科技 (Token Saver)**：
  - **`bash` 输出智能过滤器**：自动压缩长终端命令输出（如 `npm install`、长日志），保留首尾关键行，节省 80%+ 上下文 Token！
  - **`read` 输出智能过滤器**：智能压缩 `package-lock.json` 等超大文件，只保留版本和依赖概览。

### 🔄 03-work 跨回合自主循环工作原理

传统 AI 编程助手往往在单个回合输出后便停下等待用户确认，导致长流程编码被频繁打断。`03-work` 原生集成了 `WorkLoopDriver` 跨回合自主驱动引擎：
1. **事件级生命周期监听**：挂载 Pi 的 `agent_settled` 事件，在每回合执行完毕且环境就绪时自动触发状态核验。
2. **磁盘断点双向校验**：实时扫描 `.context/checkpoints/` 与规划文件中的 Implementation Units，确保内存与磁盘状态强一致。
3. **自主连续推进**：若存在剩余未完成单元，驱动器防抖调度后续消息（`deliverAs: "followUp"`），实现跨回合无人值守自主编码与单测验证，**不做完计划绝不停机**。
4. **多重安全防护阀**：
   - **Stop-The-Line 遇错即停**：同一单元若连续 3 次排查修复失败，强制停机并完整记录错误现场，杜绝无效死循环与 Token 浪费。
   - **50 轮安全轮次上限**：防止异常任务无休止推进。
   - **随时安全打断**：按下 `Esc` 或输入 `暂停` / `pause`，随时安全挂起循环。
5. **闭环自动流转**：全量单元绿灯通过后，自动交接调度 `/skill:04-review` 进行代码审查与回归验证。

---

## 💡 致谢与参考 (Acknowledgments)

本扩展库中的复合工程工作流（Compound Engineering）模块深度参考并借鉴了以下优秀开源项目的架构思想：
- **[`@leing2021/super-pi`](https://github.com/leing2021/super-pi)**：特别致谢 `super-pi` 项目对复合工程流流水线、断点续传（Checkpoints）与产物治理模式的探索与启发。本项目在汲取其精髓的基础上，全面重构了终端交互体验，解除了只能单选的限制，引入了 **`00-next` 智能调度导航**、**极简避坑复盘 `05-learn`**，并深度打通了 **`@juicesharp/rpiv-ask-user-question`** 的现代多选复选框终端交互体系。

---

## 📄 开源许可证

本项目基于 [MIT License](./LICENSE) 协议开源。