@unifan/pi-unifan-zh 1.0.34 → 1.0.35

package/AGENTS.md

@@ -30,13 +30,19 @@ pi-unifan-zh/
 │   │   │   ├── history-context.md # 历史上下文专家
 │   │   │   └── code-comments.md   # 注释检查专家
 │   │   └── package.json           # 独立子包: @unifan/pi-review-zh
-│   └── commit/                    # ③ 智能 Git 提交助手 (/commit, /commit-push)
-│       ├── index.ts               # 一键提交与推流命令
+│   ├── commit/                    # ③ 智能 Git 提交助手 (/commit, /commit-push)
+│   │   ├── index.ts               # 一键提交与推流命令
+│   │   ├── src/
+│   │   │   ├── git.ts             # Git 执行引擎 (含自动变基 pull --rebase)
+│   │   │   └── prompt.ts          # Conventional Commits 中文提示词
+│   │   └── package.json           # 独立子包: @unifan/pi-commit-zh
+│   └── workflow/                  # ④ 复合工程工作流引擎 (/workflow)
+│       ├── index.ts               # 工具与输出过滤器注册
 │       ├── src/
-│       │   ├── git.ts             # Git 执行引擎 (含自动变基 pull --rebase)
-│       │   └── prompt.ts          # Conventional Commits 中文提示词
-│       └── package.json           # 独立子包: @unifan/pi-commit-zh
-└── skills/                        # 内置专业技能集
+│       │   ├── tools/             # workflow_state, artifact_helper, session_checkpoint
+│       │   └── filters/           # bash_output_filter, read_output_filter
+│       └── package.json           # 独立子包: @unifan/pi-workflow-zh
+└── skills/                        # 内置专业技能集 (00-next ~ 05-learn)
 ```
 
 ---
@@ -128,7 +134,12 @@ cd D:\program\my\pi-unifan-zh\extensions\commit
 npm version patch
 npm publish --access public
 
-# 4. 提交版本号变更到 Git 远端
+# 4. 升级并发布 workflow 子包 (@unifan/pi-workflow-zh)（如有修改）
+cd D:\program\my\pi-unifan-zh\extensions\workflow
+npm version patch
+npm publish --access public
+
+# 5. 提交版本号变更到 Git 远端
 cd D:\program\my\pi-unifan-zh
 git add .
 git commit -m "chore(release): 升级版本号至 vX.Y.Z"

package/README.md

@@ -17,11 +17,18 @@ pi-unifan-zh/
 ├── AGENTS.md                 # Developer and AI agent guidelines
 ├── README.md                 # English Documentation
 ├── README_zh.md              # Chinese Documentation
-├── extensions/               # 📦 Individual Extension Packages
+├── extensions/               # 📦 Extension Packages
 │   ├── sessions/             # 📜 ① Dual-pane session manager with live preview (Chinese)
 │   ├── review/               # 🔍 ② AI multi-agent code review suite (Daily/Lite/Perf/Full)
-│   └── commit/               # 📦 ③ Intelligent Conventional Commits assistant (Chinese)
-└── skills/                   # 🎯 Custom prompt skills library
+│   ├── commit/               # 📦 ③ Intelligent Conventional Commits assistant (Chinese)
+│   └── workflow/             # 🔄 ④ Compound Engineering Workflow engine (State/Checkpoints/Filters)
+└── skills/                   # 🎯 Compound Engineering Skills (00-next ~ 05-learn)
+    ├── 00-next/              # 🚦 Router & orchestrator (inspects repo state, recommends next step)
+    ├── 01-brainstorm/        # 💡 Discovery & flexible interactions (single/multi-select/custom text)
+    ├── 02-plan/              # 📐 TDD architecture planning & Implementation Units
+    ├── 03-work/              # 🛠️ Strict TDD coding execution & checkpoint resume
+    ├── 04-review/            # 🧐 Code review, spec verification & regression testing
+    └── 05-learn/             # 📝 Lightweight solution cards & knowledge compounding
 ```
 
 ---
@@ -49,19 +56,44 @@ pi install D:/program/my/pi-unifan-zh
 
 ### Option B: Install Individual Extensions
 
+Each extension is published as a standalone npm package and can be installed individually:
+
+> 💡 **Note**: Pi CLI's `git:` source only supports cloning the entire repository root. For **installing individual extensions**, use the recommended `npm:` method or local paths.
+
 #### 1. Install `sessions` (Session Manager with TUI Preview):
 ```bash
+# Via npm
 pi install npm:@unifan/pi-sessions-zh
+# Or via local path
+pi install D:/program/my/pi-unifan-zh/extensions/sessions
 ```
 
 #### 2. Install `review` (AI Parallel Code Review Suite):
 ```bash
+# Via npm
 pi install npm:@unifan/pi-review-zh
+# Or via local path
+pi install D:/program/my/pi-unifan-zh/extensions/review
 ```
 
 #### 3. Install `commit` (Intelligent Git Commit Assistant):
 ```bash
+# Via npm
 pi install npm:@unifan/pi-commit-zh
+# Or via local path
+pi install D:/program/my/pi-unifan-zh/extensions/commit
+```
+
+#### 4. Install `workflow` (Compound Engineering Engine & Skills):
+> Includes `/workflow` command, checkpoint persistence, token filters, and all 6 workflow skills (`00-next` ~ `05-learn`).
+```bash
+# Via npm
+pi install npm:@unifan/pi-workflow-zh
+# Or via local path
+pi install D:/program/my/pi-unifan-zh/extensions/workflow
+
+# Recommended peer question UI extension:
+pi install npm:@juicesharp/rpiv-ask-user-question
 ```
 
 ---
@@ -134,6 +166,51 @@ pi install npm:@unifan/pi-commit-zh
 
 ---
 
+### 4. 🔄 `workflow` & Compound Engineering Workflow Suite
+Turn your AI coding agent into a disciplined software engineer through an iterative stage-gated pipeline:
+
+```text
+00-next  ──>  01-brainstorm  ──>  02-plan  ──>  03-work  ──>  04-review  ──>  05-learn
+ (Router)        (Discovery)      (TDD Plan)    (Execution)      (Review)      (Compounding)
+```
+
+- **Commands & Tools**:
+  - **`/workflow`**: Inspect current project stage, artifact counts, active autonomous driving loop progress, and recommended next skill.
+  - **`workflow_state` tool**: Automatically scans `docs/` and `.context/checkpoints/` state.
+  - **`artifact_helper` tool**: Resolves standardized artifact paths for requirements, plans, and solutions.
+  - **`session_checkpoint` tool**: Saves and restores execution breakpoints at the Implementation Unit level — resume right from where you left off.
+- **6 Built-in Pipeline Skills**:
+  - **`00-next` (Router & Orchestrator)**: Say `continue` or type `/skill:00-next`, and it automatically guides you to the right next step.
+  - **`01-brainstorm` (Requirements Discovery)**: Clarifies scope and architecture decisions. **Pairs with `@juicesharp/rpiv-ask-user-question`** for flexible interactions: single-select (1-9 hotkeys) for mutually exclusive choices, multi-select checkboxes for feature lists, and custom text inputs.
+  - **`02-plan` (Architecture Planning)**: Decomposes requirements into TDD Implementation Units following The Ladder minimalism principles.
+  - **`03-work` (Autonomous Loop TDD Coding)** 🚀: **Built-in autonomous continuation engine similar to `goal`**. Directly invoking `/skill:03-work` starts a background cross-turn driver that sequentially executes Implementation Units with red-green-refactor, **never stopping until all planned units are 100% completed**! Supports checkpoint resumption and strict Stop-The-Line policy. Type `pause`, `stop`, or press `Esc` to pause anytime.
+  - **`04-review` (Quality & Spec Review)**: Verifies git diff, checks Spec contract compliance, and ensures clean regression tests.
+  - **`05-learn` (Knowledge Compounding)**: Lightweight, pragmatic pitfall compounding into `docs/solutions/` — zero noise, only non-trivial insights.
+- **Context Optimizers (Token Savers)**:
+  - **`bash` smart filter**: Automatically summarizes verbose command outputs (`npm install`, verbose logs), saving 80%+ context tokens.
+  - **`read` smart filter**: Compresses oversized lockfiles (e.g. `package-lock.json`) and long logs into compact structural summaries.
+
+### 🔄 How 03-work Autonomous Loop Works
+
+Traditional AI coding tools stop after each turn, asking for user confirmation before doing the next step. `03-work` natively integrates the `WorkLoopDriver` engine:
+1. **Lifecycle Event Hook**: Binds to Pi's `agent_settled` event to verify execution state immediately after each turn finishes.
+2. **Bi-directional Checkpoint Sync**: Re-reads `.context/checkpoints/` and the active plan to ensure in-memory and disk states match.
+3. **Autonomous Continuation**: If units remain, dispatches a follow-up turn (`deliverAs: "followUp"`), driving red-green-refactor cycles autonomously across turns until all units pass.
+4. **Safety Valves**:
+   - **Stop-The-Line**: Automatically pauses upon 3 consecutive failures on the same unit, preserving exact error context.
+   - **50-Turn Safety Threshold**: Prevents runaway looping.
+   - **Interactive Pause**: Hit `Esc` or type `pause` / `stop` anytime to safely suspend.
+5. **Auto-Handover**: Automatically cascades into `/skill:04-review` once all units are verified green.
+
+---
+
+## 💡 Acknowledgments & References
+
+The Compound Engineering workflow pipeline in this repository draws deep architectural inspiration and reference from:
+- **[`@leing2021/super-pi`](https://github.com/leing2021/super-pi)**: Special thanks to `super-pi` for its pioneering design of Pi-native Compound Engineering pipelines, checkpoint resumes, and artifact management patterns. In this project, we re-architected the terminal interaction to unlock multi-select capabilities, introduced the **`00-next` router**, streamlined **`05-learn`**, and fully integrated **`@juicesharp/rpiv-ask-user-question`** for rich terminal UI dialogs.
+
+---
+
 ## 📄 License
 
 MIT License.

package/README_zh.md

@@ -15,11 +15,18 @@ pi-unifan-zh/
 ├── AGENTS.md                 # 开发者与智能体规范指南
 ├── README.md                 # English Documentation
 ├── README_zh.md              # 中文说明文档
-├── extensions/               # 📦 独立插件集
+├── extensions/               # 📦 扩展插件集
 │   ├── sessions/             # 📜 ① 历史会话管理器（双栏实时预览与恢复·中文增强版）
 │   ├── review/               # 🔍 ② AI 代码审查套件（日常3专家 / 极速单兵 / 性能探针 / 全量会诊）
-│   └── commit/               # 📦 ③ 智能 Git 提交助手（Conventional Commits 纯中文规范版）
-└── skills/                   # 🎯 自定义技能库
+│   ├── 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/             # 📝 极简避坑指南与经验复利沉淀
 ```
 
 ---
@@ -47,19 +54,44 @@ 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
 ```
 
 ---
@@ -139,6 +171,51 @@ pi install npm:@unifan/pi-commit-zh
 
 ---
 
+### 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) 协议开源。

package/extensions/commit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifan/pi-commit-zh",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Pi 智能 Git 提交助手（规范化 Conventional Commits 纯中文版，支持一键提审与推流）",
   "type": "module",
   "main": "index.ts",

package/extensions/review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifan/pi-review-zh",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "description": "Pi 交互式 AI 代码审查扩展（支持单模型与多 Subagent 并发 2~6 专家自由切换，Codex 经典架构）",
   "type": "module",
   "license": "MIT",

package/extensions/workflow/README.md

@@ -0,0 +1,50 @@
+# 🔄 @unifan/pi-workflow-zh (复合工程工作流引擎·中文版)
+
+专为 **Pi Coding Agent** 打造的复合工程工作流（Compound Engineering）引擎扩展。提供状态自动感知、执行断点持久化与长输出智能压缩。
+
+---
+
+## ✨ 核心特性
+
+- **工作流状态感知**：自动识别项目当前处于需求、计划、编码还是复盘阶段，提供智能下一步建议。
+- **执行断点恢复（Checkpoints）**：以 Implementation Unit 为粒度持久化执行状态，支持中断后无缝续跑。
+- **产物目录标准化**：自动规范化 `docs/brainstorms/`、`docs/plans/`、`docs/solutions/` 与 `.context/checkpoints/`。
+- **上下文 Token 压缩器**：内置 `bash` 与 `read` 智能过滤器，过滤冗余日志与超大 Lockfile，节省 80%+ Token。
+- **与现代终端问答联动**：无缝协同 `@juicesharp/rpiv-ask-user-question` 终端多选/单选/自由输入组件。
+
+---
+
+## 🚀 安装方式
+
+### 1. 从 npm 在线安装：
+```bash
+pi install npm:@unifan/pi-workflow-zh
+```
+
+### 2. 本地路径单独安装：
+```bash
+pi install D:/program/my/pi-unifan-zh/extensions/workflow
+```
+
+> **提示**：若需要终端弹窗多选复选框等高级问答交互，建议搭配安装：
+> ```bash
+> pi install npm:@juicesharp/rpiv-ask-user-question
+> ```
+
+---
+
+## 🎮 使用方法
+
+在 Pi 中输入命令查看工作流看板：
+```text
+/workflow
+```
+可查看当前项目工作流阶段状态、已归档产物清单与 03-work 自主循环进度。
+
+### 6 大内置复合工程技能
+- **`/skill:00-next`**：智能进度分析与路由推荐
+- **`/skill:01-brainstorm`**：需求发现与边界澄清
+- **`/skill:02-plan`**：TDD 架构规划与 Implementation Units 拆解
+- **`/skill:03-work`** 🚀：**自主循环干活（不做完不停机）**。按计划顺序跨回合自动推进所有单元，完成全部规划前绝不停机，中途可随时输入“暂停”或按 Esc 挂起。
+- **`/skill:04-review`**：全量代码审查与回归验证
+- **`/skill:05-learn`**：极简疑难避坑卡片沉淀

package/extensions/workflow/index.ts

@@ -0,0 +1,275 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resolveArtifactPath, type ArtifactType } from "./src/tools/artifact-helper.js";
+import { detectWorkflowState } from "./src/tools/workflow-state.js";
+import { executeSessionCheckpoint } from "./src/tools/session-checkpoint.js";
+import { filterBashOutput } from "./src/filters/bash-output-filter.js";
+import { filterReadOutput } from "./src/filters/read-output-filter.js";
+import { WorkLoopDriver } from "./src/driver/work-loop-driver.js";
+
+const workflowStateParams = Type.Object({
+	repoRoot: Type.String({ description: "Repository root path to scan for workflow artifacts" }),
+});
+
+const artifactHelperParams = Type.Object({
+	repoRoot: Type.String({ description: "Repository root where workflow artifacts are stored" }),
+	artifactType: Type.Union(
+		[
+			Type.Literal("brainstorm"),
+			Type.Literal("plan"),
+			Type.Literal("solution"),
+			Type.Literal("checkpoint"),
+		],
+		{ description: "Target artifact category" },
+	),
+	topic: Type.Optional(Type.String({ description: "Topic or feature name for the artifact" })),
+	date: Type.Optional(Type.String({ description: "Date prefix formatted as YYYY-MM-DD" })),
+	ensureDir: Type.Optional(Type.Boolean({ description: "Whether to create directory if missing" })),
+});
+
+const sessionCheckpointParams = Type.Object({
+	operation: Type.Union(
+		[
+			Type.Literal("save"),
+			Type.Literal("load"),
+			Type.Literal("list"),
+			Type.Literal("fail"),
+			Type.Literal("retry"),
+		],
+		{ description: "Checkpoint action to execute" },
+	),
+	repoRoot: Type.String({ description: "Repository root path" }),
+	planPath: Type.Optional(Type.String({ description: "Path to the plan markdown artifact" })),
+	planSlug: Type.Optional(Type.String({ description: "Slug identifier for the execution plan" })),
+	completedUnits: Type.Optional(
+		Type.Array(Type.String(), { description: "List of completed unit names" }),
+	),
+	failedUnit: Type.Optional(Type.String({ description: "Unit name that encountered a failure" })),
+	error: Type.Optional(Type.String({ description: "Error description or failure details" })),
+});
+
+export default function workflowExtension(pi: ExtensionAPI) {
+	// 1. Register workflow_state tool (Core engine for 00-next)
+	pi.registerTool({
+		name: "workflow_state",
+		label: "Workflow State",
+		description:
+			"Scan repository artifacts (brainstorms, plans, checkpoints, solutions) and determine current stage and recommended next skill.",
+		parameters: workflowStateParams,
+		async execute(_toolCallId, params) {
+			const result = await detectWorkflowState(params.repoRoot);
+			return {
+				content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+				details: result,
+			};
+		},
+	});
+
+	// 2. Register artifact_helper tool
+	pi.registerTool({
+		name: "artifact_helper",
+		label: "Artifact Helper",
+		description:
+			"Resolve and optionally create standard Compound Engineering artifact paths under docs/ or .context/.",
+		parameters: artifactHelperParams,
+		async execute(_toolCallId, params) {
+			const result = await resolveArtifactPath({
+				repoRoot: params.repoRoot,
+				artifactType: params.artifactType as ArtifactType,
+				topic: params.topic,
+				date: params.date,
+				ensureDir: params.ensureDir,
+			});
+			return {
+				content: [{ type: "text", text: result.path }],
+				details: result,
+			};
+		},
+	});
+
+	// 3. Register session_checkpoint tool
+	pi.registerTool({
+		name: "session_checkpoint",
+		label: "Session Checkpoint",
+		description:
+			"Manage plan execution checkpoints: save completed units, load breakpoints, record errors, and retry failed units.",
+		parameters: sessionCheckpointParams,
+		async execute(_toolCallId, params) {
+			const result = await executeSessionCheckpoint({
+				operation: params.operation,
+				repoRoot: params.repoRoot,
+				planPath: params.planPath,
+				planSlug: params.planSlug,
+				completedUnits: params.completedUnits,
+				failedUnit: params.failedUnit,
+				error: params.error,
+			});
+			return {
+				content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+				details: result,
+			};
+		},
+	});
+
+	// 4. Hook: Bash output smart filter (Reduce context waste from verbose commands)
+	pi.on("tool_result", async (event, _ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = (event.input as { command?: string })?.command ?? "";
+		if (!command) return undefined;
+
+		const textBlocks =
+			(event.content as Array<{ type: string; text?: string }>)?.filter(
+				(b) => b.type === "text",
+			) ?? [];
+		if (textBlocks.length === 0) return undefined;
+
+		const output = textBlocks.map((b) => b.text ?? "").join("");
+		const result = filterBashOutput({
+			command,
+			output,
+			isError: event.isError ?? false,
+		});
+
+		if (!result.filtered) return undefined;
+
+		return {
+			content: [{ type: "text", text: result.output }],
+			details: {
+				...(event.details && typeof event.details === "object" ? event.details : {}),
+				bashFilter: {
+					strategy: result.strategy,
+					originalBytes: result.originalBytes,
+					filteredBytes: result.filteredBytes,
+				},
+			},
+		};
+	});
+
+	// 5. Hook: Read output filter (Reduce context waste from large lockfiles and long texts)
+	pi.on("tool_result", async (event, _ctx) => {
+		if (event.toolName !== "read") return undefined;
+
+		const filePath = (event.input as { path?: string })?.path ?? "";
+		if (!filePath) return undefined;
+
+		const textBlocks =
+			(event.content as Array<{ type: string; text?: string }>)?.filter(
+				(b) => b.type === "text",
+			) ?? [];
+		if (textBlocks.length === 0) return undefined;
+
+		const output = textBlocks.map((b) => b.text ?? "").join("");
+		const isImage =
+			(event.content as Array<{ type: string }>)?.some((b) => b.type === "image") ?? false;
+
+		const result = filterReadOutput({
+			path: filePath,
+			output,
+			isError: event.isError ?? false,
+			isImage,
+		});
+
+		if (!result.filtered) return undefined;
+
+		return {
+			content: [{ type: "text", text: result.output }],
+			details: {
+				...(event.details && typeof event.details === "object" ? event.details : {}),
+				readFilter: {
+					strategy: result.strategy,
+					originalBytes: result.originalBytes,
+					filteredBytes: result.filteredBytes,
+				},
+			},
+		};
+	});
+
+	// 6. User Command: /workflow (查看工作流总览与 03-work 自主循环状态)
+	pi.registerCommand("workflow", {
+		description: "查看当前项目的复合工程流状态与下一步推荐技能",
+		async handler(_args, ctx) {
+			const repoRoot = ctx.cwd || process.cwd();
+			const state = await detectWorkflowState(repoRoot);
+			const workStatus = workDriver.getStatus();
+
+			const msg = [
+				`🎯 **复合工程工作流状态 (Compound Engineering)**`,
+				`📁 仓库路径: \`${state.repoRoot}\``,
+				`📊 当前阶段: **${state.stage.toUpperCase()}**`,
+				`🚀 推荐下一步: \`/skill:${state.recommendedSkill}\``,
+				`💡 理由: ${state.recommendationReason}`,
+				``,
+				workStatus.isActive
+					? `⚡ **03-work 自主循环运行中**: [${workStatus.completedUnits.length}/${workStatus.allUnits.length}] 当前推进: **${workStatus.currentUnit || "全部完成"}**`
+					: `⚡ **03-work 自主循环状态**: ⚪ 空闲（调用 /skill:03-work 即可自动循环驱动）`,
+				``,
+				`📋 **产物概览**:`,
+				`- 需求文档 (Brainstorms): ${state.brainstorms.length} 个 ${state.latestBrainstorm ? `(最新: ${state.latestBrainstorm.filename})` : ""}`,
+				`- 执行计划 (Plans): ${state.plans.length} 个 ${state.latestPlan ? `(最新: ${state.latestPlan.filename})` : ""}`,
+				`- 运行断点 (Checkpoints): ${state.checkpoints.length} 个 ${state.activeCheckpoint ? `(已完成: ${state.activeCheckpoint.completedUnits.length} 单元)` : ""}`,
+				`- 避坑经验 (Solutions): ${state.solutions.length} 个 ${state.latestSolution ? `(最新: ${state.latestSolution.filename})` : ""}`,
+			].join("\n");
+
+			if (ctx.hasUI) {
+				ctx.ui.notify?.(msg, "info");
+			}
+		},
+	});
+
+	// 7. 03-work 原生自主循环驱动引擎 (无须额外命令，直接在 03-work 中原生生效)
+	const workDriver = new WorkLoopDriver();
+
+	// 监听用户输入与技能启动：当调用 03-work 或请求恢复执行时，自动启动自主循环驱动
+	pi.on("before_agent_start", async (event, ctx) => {
+		const promptLower = event.prompt.toLowerCase();
+		const is03Work =
+			event.prompt.includes("03-work") ||
+			event.systemPrompt.includes("03-work") ||
+			(promptLower.includes("03") &&
+				(promptLower.includes("work") ||
+					promptLower.includes("继续") ||
+					promptLower.includes("恢复") ||
+					promptLower.includes("resume") ||
+					promptLower.includes("干活")));
+
+		if (is03Work && !workDriver.getStatus().isActive) {
+			workDriver.setRepoRoot(ctx.cwd || process.cwd());
+			const res = await workDriver.start();
+			if (res.success && res.status.isActive) {
+				const nextUnit = res.status.currentUnit ? `下一个: ${res.status.currentUnit}` : "准备就绪";
+				ctx.ui?.setStatus?.(
+					"workflow",
+					`🔄 03-work 自主干活 [${res.status.completedUnits.length}/${res.status.allUnits.length}] ${nextUnit}`,
+				);
+			}
+		}
+	});
+
+	// 监听用户打断指令：用户若输入“暂停”或“停止”，自动安全挂起 03 自主循环
+	pi.on("input", async (event, ctx) => {
+		const text = event.text.trim().toLowerCase();
+		if (
+			workDriver.getStatus().isActive &&
+			(text === "暂停" || text === "停止" || text === "pause" || text === "stop")
+		) {
+			await workDriver.pause("用户手动输入暂停");
+			ctx.ui?.setStatus?.("workflow", undefined);
+			ctx.ui?.notify?.(
+				"⏸️ 03-work 自主循环已暂停。随时输入“继续”或调用 /skill:03-work 即可恢复。",
+				"info",
+			);
+			return { action: "handled" };
+		}
+		return { action: "continue" };
+	});
+
+	// 核心事件循环：每个回合结束后，若仍有未完成单元，自动注入下一回合实现“不做完不停机”
+	pi.on("agent_settled", async (_event, ctx) => {
+		await workDriver.onAgentSettled(ctx, pi);
+	});
+
+	pi.on("session_shutdown", async () => {
+		workDriver.cancelTimer();
+	});
+}

package/extensions/workflow/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@unifan/pi-workflow-zh",
+  "version": "1.0.2",
+  "description": "Pi 复合工程工作流引擎（状态感知 / 断点续跑 / 输出压缩 / 自动化工具集）",
+  "type": "module",
+  "main": "index.ts",
+  "author": "821869798",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/821869798/pi-unifan-zh.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "workflow",
+    "compound-engineering",
+    "checkpoints",
+    "chinese"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0 <1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0 <1.0.0",
+    "@juicesharp/rpiv-ask-user-question": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@juicesharp/rpiv-ask-user-question": {
+      "optional": true
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "skills",
+    "README.md",
+    "package.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}