Pi Adaptive Delivery

让 Pi 先和你商量清楚，再动手开发，最后拿出检查结果。

这是一个 Pi 扩展包。你决定要做什么、允许改哪里，Pi 负责组织开发和检查；简单任务由当前 Pi 直接完成，复杂任务才安排开发或独立审查。适合需要先讨论方案、明确修改范围，并查看实际检查结果的项目任务。

安装后默认不开启交付流程，日常照常使用 Pi。 输入 /delivery-shape 你的需求 才进入；任务结束后用 /delivery-exit 退出。简单任务可以只在聊天中写清方案和步骤，不必专门创建技术方案和实施计划文件。

开发和审查子 Agent 都继承主 Pi 已启用的全部普通工具及原有权限检查。 包括读写、编辑、Shell、联网和插件工具，审查角色也不禁用 write/edit/apply_patch。角色分工由任务提示词说明：开发负责实现，审查负责独立检查和报告问题。

完整流程 · 快速开始 · 协作时序 · 命令速查 · 使用边界

完整流程

图里的“检查”，就是针对最后改好的代码运行项目已有的测试、编译或 lint。代码如果又改过，就要重新检查。

flowchart TD
    A[普通使用 Pi] -->|/delivery-shape 你的需求| B[说清需求，一起讨论方案]
    B --> C[说明怎么改、业务行为与验收标准]
    C --> D[你确认方案并开始实施]
    D --> E[AI 内部拆解计划；父 Pi 直接完成简单任务或委派开发]
    E --> V[父 Pi 或审查子 Agent 运行项目检查]
    V -->|完成| F[高风险任务按需独立审查，主 Pi 核对结果]
    V -->|没有通过，修改后再检查| E
    F -->|还有需要修改的问题| E
    F -->|检查完成，问题已处理| G[交付改动和检查结果]
    G -->|/delivery-exit| A

你主要确认一次技术方案。例如，修复“空列表导致页面报错”：

确认	要决定什么	示例
方案确认并开始实施	目标、数据行为、技术路径、验收标准和重大风险	没有数据时显示空状态，有数据时保持原样，本次不改接口

需求清楚时直接整理方案；还有关键问题时，每次只问一件事。你可以反复提意见、改方案，再在 Pi 界面里确认。确认后 AI 在内部拆解并持续更新实施计划，按复杂度选择父 Pi 直接完成或调用 delivery_develop，按风险调用 delivery_review，不再要求第二次实施确认。文件数量、步骤、顺序和范围内返工由 AI 自行处理；业务目标、数据行为、对外接口、验收标准或重大外部风险变化时才重新确认。需要落规划文档时，方案会明确选择“复用现有文档”或“新建需求文档”；简单任务可以选择“不落盘”。

确认界面先展示这次怎么改，并固定显示本次文档安排：

文档策略：不落盘 / 复用现有文档 / 新建需求文档
技术方案：实际 Markdown 路径或无
内部实施台账：实际 Markdown 路径或无（由 AI 维护）

用 ↑↓ 选择操作、Enter 确定，Ctrl+O 查看详情，PgUp/PgDn 翻页。方案需要调整时，选择“提出修改意见”再输入；Enter 发送，Shift+Enter 换行，Esc 返回确认内容。意见提交后不会开始开发，父 Pi 会修订方案并重新确认。确认后的实施范围、计划步骤和检查方式由 AI 在内部维护；每次委派工具直接列出当前 paths 与 inputs。面板显示的路径来自本次方案确认载荷。落盘任务在确认前必须真的写入技术方案文档：路径指向的 Markdown 文件不存在、为空或不是普通文件时会被拒绝并提示先落盘；内部实施台账可在确认后由 AI 创建。不落盘时面板会直接说明“方案保存在本次会话，项目里不新增文档”。“方案提案已保存”仍只代表提案已落盘，不代表文档已写入。方案正文结尾会固定列出“本次假设”，写明 AI 依赖但你还没确认的推断，方便一眼否决。

需要长期查阅或持续跟踪进度时，再写文档。 项目已有相关方案和进度记录时，按项目规则继续维护，避免另建一套。没有规划文件的小任务，方案、步骤和检查记录都留在会话里。

快速开始

Package 支持 npm 安装和本地路径，本版本为 0.1.7：

pi install npm:pi-adaptive-delivery        # 全局：所有项目都加载
pi install npm:pi-adaptive-delivery -l     # 只装当前项目：写入该项目的 .pi/settings.json
pi remove  npm:pi-adaptive-delivery -l     # 卸载（全局安装时去掉 -l）

试用建议用项目级安装，避免影响其他项目。项目级安装会在项目里生成 .pi/：.pi/settings.json 声明了这个包，要提交、不要忽略；.pi/npm/ 下的 node_modules、package.json 和锁文件由 npm 自带的 .gitignore 排除，不要提交。你只需要已配置模型的 Pi 和一个 Git 项目。开发和测试直接在本机运行，不需要 Docker 或镜像。 项目原本需要的 Node、Python、Java 等工具和依赖，继续使用你本机已有的环境。

1. 获取本仓库：

   git clone https://github.com/small-xiexu/pi-adaptive-delivery.git
   

2. 在你要修改的项目的 .pi/settings.json 中，把本仓库的绝对路径加入 packages。下面的路径需要替换；已有配置和其他扩展包要保留：

   {
     "packages": ["/absolute/path/to/pi-adaptive-delivery"]
   }
   

3. 在你要修改的项目中启动 Pi：

   cd /path/to/your-project
   pi
   

   按 Pi 提示确认项目信任，然后输入需求：

   /delivery-shape 修复空列表导致页面报错，保持正常列表行为不变
   

   也可以先输入 /delivery-shape，再直接聊天描述需求。如果 Pi 已经开着，等当前任务结束后用 /reload 加载扩展包。

目前自动化验证过的基础组合是 macOS、Pi 0.87.0、Node 25.2.1，其他平台和版本还没验证。Structured 定向矩阵中，pi-codex-conversion 3.0.35 + Pi 0.87.0 和 3.0.25 + Pi 0.87.0 的最小开发/审查流程均通过；3.0.25 不提供 3.0.26 起新增的可选 developer-message API，本 Package 当前流程不调用它。其他适配器和 CLI 组合不据此宣称支持。父 Pi 与子 Pi CLI 必须使用同一套安装和版本；升级后请重启已运行的 Pi，避免父 SDK 与 PATH 解析出的子 CLI 混用。使用 pi-codex-conversion 的用户，先按Structured 接入说明（第 14.2 节）配置加载顺序。升级 Package 或修改 .pi/settings.json 后，如果 Pi 已经开着，等当前任务收尾再用 /reload；如果交付任务已结束并要回到普通使用，使用 /delivery-exit。

协作时序

“主 Pi”就是你正在对话的 Pi。它负责和你讨论、完成简单修改、分配复杂任务并核对结果。开始修改或委派前，它还会用一行说明这次走哪条路径（自己改、开发子 Agent、是否加独立审查）和理由；你觉得过重或过轻，直接要求调整即可。复杂任务才会使用独立开发或审查子 Agent；检查由父 Pi 或审查子 Agent 根据项目工具链主动完成。这些会话都在本机工作，交付任务按顺序交接。审查以独立检查和报告问题为职责，发现问题后交回父 Pi，由父 Pi 决定直接修复或重新委派开发；这个职责由任务提示词约定，不裁剪工具权限。子 Agent 不能代替你确认方案或允许改动的范围。

主 Pi 用什么模型，子 Agent 就用什么模型。 AI 只按任务难度调整推理级别，不会自行换成别的模型；你切换主 Pi 的模型后，新任务跟着切换，正在执行的任务保持原样。

sequenceDiagram
    actor U as 你
    participant P as 主 Pi
    participant D as 开发子 Agent
    participant V as 父 Pi / 审查子 Agent
    participant R as 审查子 Agent
    P->>U: 讨论方案
    U->>P: 确认方案并开始实施
    P->>P: 内部拆解并维护实施计划
    loop 按需重复，直到检查通过或需要暂停
        alt 简单任务
            P->>P: 在已确认的范围内直接修改
        else 复杂任务
            P->>D: 在已确认的范围内开发或修改
            D-->>P: 返回改动、自测结果和原始记录
        end
        P->>V: 运行项目测试、编译或 lint
        V-->>P: 返回实际结果，核对检查期间代码是否变化
        alt 检查没有通过
            P->>P: 查明原因，下一轮修改后重新验收
        else 检查完成
            opt 这次改动需要独立审查
                P->>R: 提供需求、实际改动和检查现场
                R-->>P: 返回审查意见
                P->>P: 核对意见，需要修改就回到下一轮
            end
        end
    end
    alt 检查完成，必要的审查问题也已处理
        P-->>U: 交付改动、检查结果和已知限制
    else 需要暂停
        P-->>U: 说明已完成什么、卡在哪里、接下来怎么办
    end

父 Pi 或开发子 Agent 完成修改后，仍要核对最终代码并运行项目已有检查。高风险或需要第二视角的任务再调用审查子 Agent；审查发现的问题由主 Pi 核对处理。原来约定范围内的问题可以继续修，想多改其他地方或改变检查方式，就要重新请你确认。缺少环境、权限或无法确认执行结果时，会暂停并说明原因。

子 Agent 的主状态只有三种：运行中、已完成、异常退出。工具调用失败是过程记录，不是子 Agent 失败：检索未匹配、编辑后修正和检查未通过都会留在详情里，卡片不会把它们提升为主状态，也不会自行宣布问题已解决。结果正文先给子 Agent 的结论，失败记录附在正文之后并明确“可能是检查未通过，也可能是命令或检索失败”；具体调用、返回摘要和原始记录位置保留在详情中，由主 Pi 核对后说明原因与影响。

命令速查

交付命令都在这里，/delivery-status 的详情用法单独列了一行。[内容] 可以省略，输入时不用带方括号。

命令	做什么	什么时候用
/delivery-shape [需求]	进入交付并讨论需求；不带需求时只开启流程	等当前回复、工具执行和排队消息结束后使用
/delivery-plan [补充要求]	请 Pi 整理技术方案、内部计划和验收路径，再请你确认	已进入交付时；可选
/delivery-run [补充要求]	请 Pi 核对本轮方案授权，继续开发、检查和必要的修改	已进入交付、方案已确认时；可选
/delivery-status	看当前确认或执行阶段、下一步建议及运行任务	进入前后都能查
/delivery-status details	查看工作区、运行模式、沿用工具、lease、状态目录和原始子 Session 等诊断信息	进入交付后排查问题；未进入时只提示当前状态
/delivery-tasks [任务ID]	选择子任务、看实时输出；带 ID 时直接打开对应详情	进入交付后，在主 Pi 终端查看当前会话分支的任务
/delivery-resume	继续看当前会话分支里最近尚未确认的方案	进入交付后、主 Pi 空闲时；只继续讨论，不会自动开始开发
/delivery-exit	退出并重载，恢复原工具和进入前启用的工具列表	等执行结束、写入权限交回；还不能退出时会说明原因
/delivery-unlock	人工核对并强制清理残留的 writer 记录	崩溃或强杀后退出或写入被拒时；清理后须自行核对代码改动

不必把这些命令按顺序输一遍。 进入后，主 Pi 会按流程推进，需要你确认时再提示。/delivery-plan 和 /delivery-run 只是方便你主动推进的提示，不会自行开启交付，也不能代替方案确认。

命令入口在加载扩展包时就会出现在补全列表里。子任务执行时也能用 /delivery-tasks 查看，不需要等它结束或重载。 全屏模式下还可以点击任务卡片；未进入交付时，查看任务或继续审阅只会提示先使用 /delivery-shape。

/delivery-status 默认只显示四类信息：当前阶段、下一步、当前任务和入口提示。例如运行开发任务时会显示：

当前阶段：实施进行中
下一步：等待当前任务结束，再核对结果。
当前任务：开发（运行中）
详情：/delivery-tasks；诊断：/delivery-status details。

任务的完整目标、当前 action、模型、命令、输出和原始 Session 路径在 /delivery-tasks 中查看；/delivery-status details 用于工作区和运行环境诊断。没有运行任务时显示“当前任务：无”。

任务列表中的“实施批次 N”表示同一套方案批准下的任务归组；“开发 · 第 2 次”表示该节点的第二次委派，返工仍属于同一批次。独立只读委派显示为“独立任务”，不会伪造实施批次。

如果确认后自动衔接没有出现，先确认当前模型回合已经结束，再使用 /delivery-plan 或 /delivery-run 推动内部计划和已确认方案范围内的开发。它们只是手工恢复入口，不会代替方案确认。

你仍可以在主 Pi 终端输入 !命令 运行 Shell；!!命令 也会执行，但输出不会交给模型。你手动运行命令，不会因此给 AI 增加权限，结果也不算这套流程的检查证据。

暂停和重新打开时，记住这几件事：

• 暂停看方案： 在方案页选择“稍后再看”或按 Esc，之后可以直接提意见，或用 /delivery-resume 继续。输入意见时，Esc 先返回方案页。
• 关闭子任务详情： 按 Esc 只关窗口，任务还会继续。
• 卡在“暂不能退出交付”： 先用 /delivery-status details 看现场。确属崩溃或强杀留下的残留记录时，用 /delivery-unlock 核对证据并确认清理；清理后要自己核对代码改动，交付仍保持启用。
• 命令没生效： 模型正在输出或排队消息时输入的命令可能不会执行（输入框里会只剩下命令名）；等执行结束后重新输入，并可用 /delivery-status 核对是否真的已启用或已退出。
• 重载或重开原会话： /reload 会重载扩展；交付流程仍然开启，但旧批准和检查证据不能直接沿用，开发前需要重新确认方案。历史消息、方案正文、已有代码改动和任务进度仍可作为恢复依据，不需要重新设计或回退已完成工作。重载保留当前启用的工具列表；升级后若缺少原有工具，待执行收尾后用 /delivery-exit 恢复进入前工具，再按需要进入交付。新建普通会话则默认不开启交付。

退出交付只表示回到普通使用，不代表任务已经检查或审查通过。

模型长时间没有响应时，交付流程会中断这次请求并自动继续（默认超过 120 秒没有任何内容增量即判定为停顿，每个回合最多自动恢复两次，界面会明确提示）；工具执行期间不计时，长时间运行的命令不会被误判。该机制只在交付流程内生效（/delivery-shape 之后，含它派出的开发和审查子会话）；普通会话不受影响，遇到停顿仍由 Pi 自身处理。

使用边界

当前版本面向标准 Pi 的 Git 项目使用，已在 macOS、Pi 0.87.0、Node 25.2.1 环境验证。Package 不改变普通 Pi 会话的使用方式，也不自动启用交付流程。Structured 环境需要使用 executionMode: "normal"，Code Mode 和 Notebook Mode 不在当前支持范围内；父 Pi 与按 PATH 启动的子 CLI 版本不一致时会保持失败关闭。

交付流程会核对批准、任务交接和检查证据，但不会替代 Pi 或其他插件的权限系统。开发和审查角色的职责由任务上下文约定；后台进程、项目依赖和外部工具仍由原有环境负责。遇到工具缺失、环境不一致或无法确认执行结果时，流程会暂停并说明原因。

这套流程核对自己的批准、任务交接和检查证据，不会接管普通工具的权限。修改范围和子 Agent 的职责仍需 AI 遵守，不能据此保证任何工具都无法越界或同时写文件。审查子虽然继承普通写入工具，但默认只检查和报告；源码修复由父 Pi 或开发子 Agent 负责。原插件自己的拒绝仍有效；后台进程由原工具和项目脚本负责，交付包不保证它们全部停止。子会话按配置重建工具，无法复制的临时插件能力会明确报错；退出时也不保证其他插件的内部状态全部还原。

环境边界：支持标准 Pi 工具集（read/bash/write/edit 等），以及当前矩阵已验证的 @howaboua/pi-codex-conversion Structured 适配器（executionMode: normal，即 exec_command / apply_patch / write_stdin / view_image 那套工具，没有独立的 read/edit/write）。该插件的 Code Mode（只暴露 exec/wait）与 Notebook Mode 不在支持范围内；工具集或父子基础环境不符时子会话交接会明确报错，不会静默降级。

需要了解	阅读
本机工具和 Structured 配置	接入说明（第 14 节）
为什么要确认方案，怎样避免 AI 同时改文件	确认与写入控制（第 8 节）
怎么检查代码，发现问题后怎么修	验收、审查与返工（第 10 节）
中断后怎样查看记录，继续处理	进度与中断恢复（第 11 节）
AI 的具体协作规则与推理级别	adaptive-delivery Skill
目前做到了哪一步，有哪些实际案例和测试记录	实施计划
运行机制与验证说明	本机接入与开发验证（第 14 节）

本项目基于标准 Pi 的公开 API，不依赖或包装 pi-subagents。