piup为 Pi Agent 打造的开发工作流工具。

为 Pi Agent 工作流而生 ​

There are many agent harnesses, but this one is yours.
Pi is a minimal agent harness. Adapt Pi to your workflows, not the other way around.

— Pi Agent 文档

piup 是为 Pi Agent 打造的开发工作流工具。 Pi 提供简洁、可适应的 agent harness；piup 在此基础上帮助组织开发任务的阶段、检查和执行记录。

快速开始 ​

需要 Node.js >=22.19.0、Git，以及项目本身使用的测试或构建工具。当前支持范围为 macOS/Linux 上的受信任本地项目；Pi 随 CLI 依赖提供，不要求全局安装 Pi。

npm install --global --ignore-scripts @piup/cli
piup --version
piup doctor

cd /path/to/your-project
piup "修复登录页问题"

无需项目初始化。 直接运行 piup 或 piup "修复登录页问题" 即可开始；

常用 CLI 命令 ​

用 piup --help 查看完整用法，用 piup --version 查看 CLI 版本。常见任务管理命令：

piup task list
piup task show <任务ID>
piup task trace <任务ID>
piup task chain <任务ID>
piup task chain <任务ID> --json
piup task resume <任务ID>
piup task cancel <任务ID>

task list 列出任务；show 查看任务、阶段和质量门状态；trace 查看事件；chain 汇总完整执行链路，--json 输出结构化结果。resume 用于恢复可恢复的任务；cancel 不能取消正在前台运行的任务。

恢复状态检查默认只读：

piup task recover --task <任务ID>

它只检查指定任务，不会杀进程或撤销外部操作。只有确认执行者已经退出并明确指定范围后，才考虑使用 --apply。

工作方式 ​

1. 描述目标：在项目目录中启动 piup，说明希望完成的开发任务。
2. 按阶段推进：piup 理解请求后组织实现与后续阶段；目标或范围不明确时会先澄清。
3. 运行项目检查：执行自动识别或项目工作流配置提供的检查，并保留结果与阶段记录。
4. 查看进度：Pi 会话中使用 /piup-status 查看当前任务和阶段；需要时运行 piup doctor 检查环境。

能力与边界 ​

• piup 面向受信任的本地项目，不是操作系统沙箱；项目命令以当前用户权限运行。
• 当前支持范围为 macOS/Linux；不要据此推断 Windows 或其他运行环境已通过验收。
• 检查质量取决于项目配置；空白检查不能证明测试、构建或业务行为通过。
• 部署、发布、提交推送及其他外部写入需要单独授权。