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[你确认实施]
    E --> F[父 Pi 直接完成简单任务；复杂任务委派开发]
    F --> V[父 Pi 或审查子 Agent 运行项目检查]
    V -->|完成| G[高风险任务按需独立审查，主 Pi 核对结果]
    V -->|没有通过，修改后再检查| F
    G -->|还有需要修改的问题| F
    G -->|检查完成，问题已处理| H[交付改动和检查结果]
    H -->|/delivery-exit| A

你主要参与两次不同的决定。例如，修复“空列表导致页面报错”：

确认	要决定什么	示例
方案确认	这个需求要怎么解决	没有数据时显示空状态，有数据时保持原样，本次不改接口
实施确认	允许改哪些文件，怎么检查	修改列表组件和测试，在本机运行项目的测试命令

需求清楚时直接整理方案；还有关键问题时，每次只问一件事。你可以反复提意见、改方案，再在 Pi 界面里分别确认方案和实施。方案确认后自动进入实施提案准备，实施确认后按复杂度选择父 Pi 直接完成或调用 delivery_develop，不必反复输入“继续”。这两个自动衔接只推动下一步准备或执行，不会跳过实施确认，也不会扩大已确认范围。需要落规划文档时，方案会明确选择“复用现有文档”或“新建需求文档”；简单任务可以选择“不落盘”。

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

文档策略：不落盘 / 复用现有文档 / 新建需求文档
技术方案：实际 Markdown 路径或无
实施计划：实际 Markdown 路径或无

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

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

快速开始

Package 支持本地路径和 npm 安装。本版本为 0.1.6，可以使用 pi install npm:pi-adaptive-delivery 安装 npm 上的最新版；本地开发或试用仍可按下面的路径配置。你只需要已配置模型的 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.85.1、Node 25.2.1，其他平台和版本还没验证。使用 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->>U: 说明修改范围、执行步骤和检查方式
    U->>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 秒没有任何内容增量即判定为停顿，每个回合最多自动恢复两次，界面会明确提示）；工具执行期间不计时，长时间运行的命令不会被误判。

任务完成后，你明确要求提交代码，Pi 会核对差异和验证结果，再用普通工具完成已授权的本地提交，无须为了提交现有改动重走方案和实施确认。工具缺失时先用 /delivery-exit 恢复；提交不会自动推送或发布。

开发验证

以下命令在本仓库运行，需要先安装项目依赖。默认测试不额外禁网，使用临时 Git、临时 HOME/agent dir、空凭证和 fake provider；不调用真实模型，也不读取用户凭证。

npm run typecheck
npm run test:all
git diff --check

test:all 包含单元、集成和 E2E 测试。两个完整流程 demo（均不在 test:all 内；真实模型那个会发起真实 Provider 调用并产生费用）：

# 1) 隔离 fake provider：无需凭证，不调用真实模型
node --import tsx test/support/run-tests.ts test/demo/full-flow.test.ts

# 2) 真实模型：临时 agent dir 只符号链接你的 auth.json，不复制凭证
node --import tsx test/demo/real-model.ts

使用 pi-codex-conversion 时，再按已安装插件的实际路径运行 Structured 专项（由 Pi 安装的 npm 插件通常在 ~/.pi/agent/npm/node_modules/ 下；已在本机 @howaboua/pi-codex-conversion 3.0.31 上验证通过）：

node --import tsx test/support/run-tests.ts \
  --adapter "$HOME/.pi/agent/npm/node_modules/@howaboua/pi-codex-conversion" \
  test/structured/flow.test.ts

测试缺少项目依赖或本机工具时应报告实际错误，不自动安装依赖或跳过场景。验证结果和临时测试制品以实施计划为准；fake provider 和模拟批准只能验证工具链路，不能代表真实模型质量或完整终端体验。

当前边界与进一步阅读

历史版本已有真实模型在隔离环境中完成命令行工具开发、审查、修复和交付的案例；这些不能直接当作当前版本的验证结果。最新状态和证据入口统一见实施计划首页。实际终端用起来是否顺畅、AI 是否会给小任务多写文档、完整业务项目能否顺利交付，还需要继续试用验证。

这套流程核对自己的批准、任务交接和检查证据，不会接管普通工具的权限。修改范围和子 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.3 节）
真实终端手动验证（PTY 脚本）	test/demo/pty

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