# Pi Adaptive Delivery 技术方案

开发、审查及分析子 Agent 均继承父 Pi 已启用的全部普通工具和原有权限检查，包括文件读写、编辑、Shell、联网及插件工具。审查角色也不禁用 `write/edit`，职责差异由任务提示词说明，不额外裁剪能力或替换普通工具实现，不依赖 Docker。一次方案确认、writer 交接、候选核对和按需独立审查继续管理本 Package 的交付入口；普通工具不受交付 writer 强制约束。实现证据及最新状态入口统一见实施计划首页。

## 1. 文档状态

- 状态：当前仓库 manifest 为 `0.1.16`；本地源码已收敛为两个对外入口，实施与验证见唯一台账第 13.153 节，README 使用说明核对见第 13.154 节。本轮尚未提交或发布，已发布 npm `0.1.16` 仍为此前入口版本。子 Pi 原始错误保留、解锁与方案审阅优化、Pi `1.1.0` 对齐，以及 Git 推送和 npm 发布证据统一见唯一实施台账第 13.141—13.152 节。Package 按 Pi Package 约定由宿主提供 Pi 相关 peer dependency（声明为 `*`）；本仓库开发依赖已对齐 `1.1.0`，本轮自动化进展见第 13.151 节，没有把未运行的版本写成已验证兼容。历史测试保留当时条件，不能直接充当当前版本的验证结果。
- 能力与证据：历史版本有真实模型开发、审查发现问题、返工和复验的隔离 CLI 案例，也有真实 TUI 批准记录。新版本机执行主要以单元测试、真实 SDK/CLI 和临时 Git 集成验证，fake provider 与模拟批准不证明真实模型质量或桌面体验；其他项目、任意插件和跨平台仍须实际试用。
- 目标：轻量、自适应、可持续讨论和恢复的 AI 开发交付 Package。
- 已确认架构方向：Pi-only，自行实现服务于交付流程的轻量编排，不直接或间接依赖 `pi-subagents`；复用标准 Pi 正式版及公开能力，不修改 Pi 源码、安装包或私有运行态。
- 设计事实源：本文件；唯一进度台账：`docs/实施计划.md`。
- 授权边界：用户已确认唯一台账第 13.3 节的重构实施计划；后续真实模型、交互试用及提示调整的授权分别记于台账。按第 13.59 节用户要求，默认自动化不额外禁网，继续使用 fake provider，不读取真实凭证、修改用户 Pi 配置/安装目录或操作旧 canary；此前实验不原样合入，Git 与发布动作仍需单独授权。

本会话早期曾按旧的两阶段流程记录过方案和实施计划确认；这些记录属于历史上下文，不代表当前交互。当前实现由一次“确认方案并开始实施”授权本轮执行；后续只有业务目标、数据行为、对外接口、验收标准或重大外部风险变化才重新确认。

当前启用边界：Package 默认只注册入口命令，不安装交付策略、协调工具、原生执行覆盖、系统提示或断流提示；普通 Pi 使用不受交付约束。仅 `/delivery-shape` 在当前父会话动态安装既有运行逻辑，带需求时指向完整 Skill 并发送普通用户正文，不把参数展开为命令。入口先核实当前目录是 Git 工作区（writer lease 以 worktree 为单位）；不是时不写启用记录、不安装运行逻辑，直接说明原因并继续普通 Pi，不让非 Git 目录在首次批准或文档写入时才报错。Skill 设置 `disable-model-invocation: true`，不会因普通需求自动进入系统提示；单独读取 Skill 或状态查询均不启用。子角色由受控委派启动时立即安装原约束，不提供进入或退出命令。

对外只注册 `/delivery-shape` 和 `/delivery-status`，加载时即进入 Pi 的命令补全；未启用时状态查询仅说明当前沿用普通 Pi。Package 通过公开 autocomplete provider 将进入命令排在状态命令前。规划、实施和恢复由普通对话表达；状态面板只显示阶段、下一步和运行中任务，`Ctrl+O` 才展开 lease、PID、Session、执行路径和收尾诊断。只有满足结束条件时显示“结束交付”，默认回车不会执行唯一的结束操作。任务详情不在状态面板提供第二入口，恢复也不通过状态面板手动解锁。

`delivery-activation` 原生 custom entry 只记录启用意图与进入前工具名，不是批准或进度台账。按当前 Session 全部条目的最近选择恢复，分支导航不暗中退出；reload/重开保留约束但清空私有批准与检查证据，新建无记录会话默认普通使用。首次 assistant 前的落盘时机由 Pi 决定，不补造消息或独立写 Session；没有持久记录时不能承诺重开恢复。旧 Session 不迁移，没有启用记录则不接管。

用户在 `/delivery-status` 面板明确选择“结束交付”后，仅在回合和消息队列空闲、批准/无在途操作且工作区无 lease 或残留操作锁时记录退出。公开 `ctx.reload()` 仍在命令上下文中执行；新实例在所有启动钩子之后的 `resources_discover` 恢复进入前工具集合并消费一次恢复记录。失败保留现场，不自动强制解锁；继续交付时在本轮方案确认核验之后检查残留。完整证明原执行结束、持久收尾完整、父结果唯一落盘且 workspace、owner、lease ID 匹配的已知失败，可自动清理同一 lease/操作锁并写入 `delivery-unlock` 审计；未知收尾只显示一次恢复选择，清理不恢复批准、不重放未知执行。退出检查成功后清理本次交付记录中的系统临时审查制品；在途操作、未知状态或清理失败时保留制品。结束交付不等于检查或审查通过，不触发新模型回合，也不根据模型声称完成自动退出。以下门禁说明均限定在交付启用期间。

当前结构为显式入口、标准 Pi RPC 委派、一次方案确认并授权实施、父文档编辑、子本机开发及候选核对/审查，复用既有 workspace 与 lease。旧执行后端、批准字段和 Session 证据不兼容、不迁移、不回退。旧设计可从 Git 历史查阅，历史验证保留在唯一台账。

当前分析委派由普通 Extension 提供 `delivery_readonly`，子进程内部角色标记不提供交付协调工具。子按父已启用的普通工具启动；READY 在插件启动钩子结束后通过公开 `setActiveTools` 承接父本轮明确选择的列表，再核对原定义及来源，不复制父插件内存。只读是任务要求，不通过删减 Shell、联网或文件工具实现；运行时的逐调用来源检查只保护本 Package 的交付工具。任务正文不会作为斜线命令执行。收尾先 `clear_queue`、再 `abort`，调用公开 `ctx.shutdown()` 并等待进程关闭，最终正文从原生持久 Session 取得。普通子交互按第 7.1 节承接；信号强杀、模型完成声明及内存响应不作为成功凭据。

普通只读、开发与审查在模型正常结束、工具执行结束、进程及持久收尾核实后返回结果；过程中出现工具错误时，保留原工具的 `isError=true`，父委派返回 `isError=false` 并标注“已结束，曾有工具异常”。从已读取的原生记录按调用 ID 提取工具名、目标、返回摘要和原始行号，最多展示三次，超出或截断时指向完整子 Session；摘要只写入现有结果正文和进度动作，不增加错误日志或已核对状态。父须按原始证据说明具体原因、后续处理及交付影响，再决定返工或继续检查；不把退出 1 自动归类为无匹配，也不把后续成功解释为全部修复。该状态只说明委派正常结束，不证明目标达成。工具失败、取消、协议/记录异常及收尾不明仍抛异常返回失败并显示“异常退出”，附已取得的原始 Session 与收尾事实。`rpc.toolError` 的原始累计不增加错误白名单、自动恢复裁决或重试。最终原生记录读取要求完整 JSONL 结尾、唯一且归属匹配的 `delivery-child-exit`，关闭后不能有消息；审查交接复用此读取检查，不新增影子日志。开发和审查的 progress 另外投影当前阶段（调用前范围校验、批准/候选准备、子 Session 启动、子 Agent 工具执行、子 Session 收尾、父结果与 writer 交接）以及模型终态、原始错误、退出信号、在途工具、Session 持久化和审查制品路径；这些是事实投影，不是第二套状态机。

宿主辅助入口固定：工作区查询使用 `/usr/bin/git`；标准 Pi CLI 启动前解析实际路径，拒绝工作区内入口及指向项目的链接，并由当前工作区外 Node 解释器直接执行，不经项目 PATH 再解析 Node。不新增 Shell 包裹、其他运行时或入口配置回退；已安装工具与插件仍在宿主信任边界内，路径解析不是原子完整性监控。

Package 不注册 `user_bash` 拦截。用户 `!` / `!!`、RPC Shell 与模型普通工具均由 Pi 和原插件处理原命令、配置、输出、退出码、取消和上下文排除；不按命令或工具名建普通能力白名单。原工具结果不生成交付批准，也不能充当固定候选验收。原插件拒绝继续生效，Package 不提高宿主权限。

父模型的 `delivery_git_status({})` 固定查询当前 worktree 的分支、HEAD 和既有暂存/未暂存/未跟踪改动，明确 unborn 与 detached；原生只读工具清单由 `/delivery-status` 显示。项目须通过 Pi `defaultTools` 显式选择 `grep/find/ls`，不静默恢复停用工具。Git 查询使用最小环境、不更新 index、禁用 fsmonitor 和已配置 clean/process 过滤器；不深入子模块内部、不执行任意命令或返回源码 diff。查询结果超限或不能无损表示路径时失败，不把遗漏清单说成干净；这不是防止外部程序并发修改配置的原子沙箱。

`delivery_approval` 只由父角色注册：模型提供技术方案，只有父 TUI 的真实 `ctx.ui.custom()` 明确选择才形成 `tui/custom` 确认。主按钮为“确认方案并开始实施”，批准同时授权本轮实施；实施计划、文件范围、步骤和检查方式由 AI 内部维护，不再有第二次实施确认。提案保存完整正文与边界，批准引用正文并绑定当前会话、worktree 和交互来源。核对内存及原生持久记录，等待期间正文变化、取消、来源不符或写盘失败均拒绝批准。Markdown 默认可编辑，插件代码仍在 Pi 本地信任边界内，不提供插件沙箱。

P2.2 的正式父入口注册 `delivery_document_edit` 和 `delivery_document_write`，父 TUI 默认可编辑 worktree 内本次明确路径的 Markdown，子角色不注册。底层复用公开 `createEditTool` / `createWriteTool`、原生 schema 与变更队列，通过实时 `authorize()` 和本次操作的取消信号，在 I/O 前检查目标路径、原生调用及父 lease。拒绝源码、Git/Session、目录/文件符号链接与硬链接，保留原生编辑匹配及 BOM/换行行为。取消等待在途 I/O 和句柄关闭；部分内容不自动回滚，关闭失败锁定 `cleanupFailed` 并拒绝后续写入。每回合只进行一次文档变更，原生结果持久化并交回 writer 后才开始下一次，不新增批量写入状态机。默认文档编辑不替代方案确认，路径核验不是原子文件系统隔离。

在 `tool_call` 边界核实本 Package 的交付工具来源，不因同名覆盖、后置注册或重新激活放权；普通工具不参加此白名单。专用文档操作绑定真实原生调用、当前分支、持久 Session 与 canonical worktree，缺失或重放均拒绝。方案 `paths` 列明父维护的规划 Markdown，作为子任务约定和候选排除项，不是普通文件工具的硬拦截；无规划文档时可为空，实施范围仍须非空。

P2.3 的内部 `createParentDocumentWriter()` 绑定本次原生工具调用与 Session，从 `git rev-parse --absolute-git-dir` 指向的 canonical Git 元数据目录下使用 `pi-adaptive-delivery` lease 状态根；同 worktree 的别名、子目录及不同 Pi agent dir 共用状态，linked worktree 分开。执行后等待原生 `turn_end`；原生持久化失败可能不产生该事件，所以 `agent_settled` 也调用同一核验。两类事件都只是触发点，在 lease 操作锁内核对 owner、当前分支、原调用和唯一持久工具结果与私有执行快照，才交回 writer。普通错误或用户取消只在 I/O 已结束、句柄已清理且失败终态核实后交回，不自动继续执行；关闭/reload 先取消 I/O，保留原生终态核验所需生命周期，收尾后再结束它，未交接状态不恢复。记录或清理错误锁定关闭；只有验证回调已经证明终态而后续 lease/操作锁清理失败，才允许本轮“继续”按同一 workspace、owner 和 lease ID 自动复位内存 fault。该模块不注册正式工具、不授予批准、不管理外部进程，CLI 中模拟父 TUI 的能力只存在于独立测试夹具。

P3 的 `delivery_develop` 复用同一标准 RPC 执行路径。父从本轮私有方案确认与一次原生读盘中核对正文及来源；每次开发或审查调用单独提供当前 `paths` 和 `inputs`，`paths` 表示本节点源码、测试或配置范围，`inputs` 表示额外只读证据；方案 `paths` 只用于保护父维护的规划文件，重叠时在子 Session 启动前拒绝并列出有界相对路径。只有业务目标、数据行为、对外接口、验收标准或重大外部风险变化才重新请求方案确认。父先取得 lease，核对独立子 Pi 的环境、实际工具来源、PID/Session/执行 ID 后，在操作锁内把唯一 owner 转移给子；父 coordinator 只可在核实终态后释放，没有写权限。lease 记录升为 v2，删除旧 bind、布尔证明释放和 force-release；旧记录不兼容、不迁移，解析失败保持关闭。

开发子不覆盖原生 `edit/write/bash` 或插件工具；所有普通调用沿用原实现、原参数和配置检查。子启动前继承父实际启用的工具，父子定义或来源不符时不发任务，不静默换实现。检查由父 Pi 或审查子 Agent 使用项目已有工具链完成；Package 不提供固定命令执行器。原开发文件包装已删除；批准范围、规划文档保护与不递归委派是模型须遵守的任务要求，不能宣称普通工具会在 I/O 前拦住所有越界操作。

子停止时按 Pi 工具终态和进程关闭收尾，对 Session 内存/磁盘条目生成单次一致性摘要。父核对摘要与本次父调用/唯一持久结果后，在 lease 锁内交回交付 writer；不补写缺失记录。普通失败或取消在调用已结束且记录明确后可交回，部分改动保留；工具或记录终态不明关闭交付入口。原工具取消和内部 I/O 清理由 Pi 或插件负责，Package 不额外证明它们的文件句柄或后台后代全部停止。

开发、检查与审查共享失败分支的错误正文携带可取得的子 Session 路径、父 Session 和本次工具调用 ID，便于父模型直接定位原始证据。子任务未发送时说明文件可能尚未生成，未取得引用或收尾证明时明确其缺口。收尾说明只引用现有核验结果，返回时父工具结果尚未落盘，不能宣称 writer 已交回。继续通过抛异常保留 Pi 原生 `isError=true`，补充后的失败正文与原失败状态一同进入既有私有快照及持久结果核对；没有新记录格式、自动重试或放行规则。

未开始例外仅对应 Pi 首条模型消息前尚未创建的 Session：子本轮无任何执行或消息时可正常关闭；父私有状态证明未发送任务，并核实控制协议无故障、无在途工具、退出码 0/无信号，最后仍须本次父原生调用和结果唯一落盘。不补写假子记录，不把文件不存在或 PID 已退出单独作为释放依据；已有任务、消息、执行或异常终态仍走严格持久核验。

**本次重构范围是整个 `pi-adaptive-delivery` 项目，不限于替换 `pi-subagents` 接入层或局部修补。**

- 获得正式实施授权后，可按新方案重组、替换或删除现有 Extension、Prompt、Skill、领域模块、依赖、测试与配套文档；不要求保持旧目录和模块边界。
- 不兼容任何旧实现：旧命令、配置字段、机器契约、Session、运行制品和内部 API 都不要求延续，不增加迁移、兼容垫片、旧逻辑回退或双后端。
- 旧代码能直接满足新设计时可以复用，但复用不是必须，也不为保住旧代码增加新设计复杂度。允许整体重构，不等于要求无差别全部重写。
- 测试以新需求和真实安全边界为准；仅服务于旧契约的断言可删除或重写，仍适用的权限、单 writer、验证与恢复边界继续覆盖，不以旧测试数量或旧行为全部不变作为验收目标。

这是本 Package 的重构边界，不自动替未来目标项目决定兼容策略，也不允许覆盖无关用户改动、操作旧 canary 现场或跳过方案确认。

## 2. 要解决的问题

企业开发中，反复澄清效果、边界和技术取舍，往往比写代码更困难。Package 应首先帮助用户把方案想清楚，而不是把一次简短需求迅速推入开发流水线。

期望体验：用户用大白话描述需求，AI 自查项目、适度追问，与用户边聊边完善方案；用户确认技术方案并授权开始实施后，AI 在内部维护计划，自主完成范围内的开发、验证、审查和返工。简单任务在会话中说明并交付，有持续维护需要时落方案和唯一台账。

多 Agent 的主要价值是独立质疑和取证，减少父会话的自我强化与确认偏误，不是为了提速或展示固定团队。独立上下文不能以削弱开发工具、执行环境或原有约束为代价，也不保证彻底消除幻觉。

旧实现中，方案批准后才首次落盘、普通验证失败也进入需要人工恢复的 `BLOCKED`，不符合持续讨论和范围内返工目标。当前允许简单任务不落规划文档，但不恢复旧 Tiny 模式或机器契约；旧版测试和 canary 证据不能替代当前流程验收。

## 3. 已对齐的主流程

```text
描述需求
  → 自查项目，判断是否需要持续维护规划文档
  → 形成方案草稿，按需追问、修订和技术实验
  → 用户确认方案并开始实施（唯一阶段确认）
  → AI 内部维护实施计划，按需实现 → 验证 / 审查 → 范围内返工
  → 按需更新已有台账，形成交付报告
```

- 用户只确认一次技术方案；确认按钮同时表达“确认方案并开始实施”。轻量任务可直接使用会话正文，不强制创建技术方案或实施计划文件。需要持续维护时落文档，已有相关方案/台账按项目规则沿用。Markdown 默认由父编辑，无须单独文档授权；必要实验仍使用单独的范围授权，不替代方案确认。
- 方案可以长期讨论，不规定轮数或截止时间。用户可以继续修改、暂缓或结束，不因已有草稿就催促进入计划。
- 方案确认后自动衔接内部计划和执行；不要求用户再输入一个不承载决策的“继续”命令。
- 计划讨论发现方案不成立时返回方案阶段，不先写代码再补批准。
- 普通问答、只读梳理、诊断和评审不自动进入修改流程；只读结论不构成任何写入授权。

这些是用户可理解的阶段，不要求为每个箭头、工具调用或 Agent 角色建立一个持久状态。

## 4. 方案对齐：允许深入，不机械追问

### 4.1 问什么，何时停止

追问参考 `grilling` / `grill-me` 的逐步对齐方式，深度以当前交付需要为准，不依赖安装这些外部 Skill：

- 优先查项目规则、相关代码、测试和已有设计，简短说明需求理解及假设。能由项目事实回答的问题自行核实；用户决定业务选择，AI 解释技术影响，不让用户代查 API 或排查代码。
- 用“不同回答是否明显改变本次交付的效果、范围或关键取舍”判断提问价值。每轮只问一个有依据、尚未解决的关键问题，给出背景、推荐和简短理由后等待回答；不展示整份问卷，也不在一个问题中捆绑多个独立决定。用户可用“按推荐”回答当前问题，该回答不替代方案确认。
- 收到回答后更新理解和方案，重新判断下一问；已覆盖的问题直接跳过，新产生的关键取舍按实际影响处理。用户纠正或改变方向时立即调整，不按预设问题顺序一路深入。
- 效果、范围、主要场景和验收清楚时停止追问，形成简短方案，说明确定的行为和采用的假设；明确需求可以零追问。未决关键业务取舍不能用默认值绕过；实现偏好、推测性边缘场景和未来扩展不构成继续盘问的理由，非关键技术细节在授权范围内自行决定。
- 不规定最少或最多轮数，不要求穷尽问题。用户仍想讨论时围绕其关注点继续；准备确认时衔接原阶段确认，不重新询问已决定的事项。

这些行为通过交付 Skill 和 `/delivery-shape` Extension 命令引导父模型。入口显式启用后要求读取完整 Skill；普通自然语言输入不自动触发。删除同名 shape Prompt，避免重复入口。资源加载测试只证明提示可用，不证明真实模型的提问质量或停止时机；不在 Extension 中增加问题计数、语义裁决或新的批准状态。

取证遵循先定位、后读取必要内容。删除按固定行数、读次数或对话轮数强迫收口的产品规则；重复调查是否有价值由实际信息缺口判断。

### 4.2 草稿按需落盘，边聊边改

- 简单任务直接修订会话中的方案正文，无须补建文件；需要文档时按项目路由确定技术方案和唯一台账路径，用父文档工具创建或修订，不再询问文档编辑授权。
- 草稿不必等所有问题解决后才创建；已有有效结论即可落盘，未决处标注待确认。
- 有效决策、事实或方向变化时更新对应部分，不每说一句话就整篇重写。
- 父文档专用工具仅覆盖 worktree 内明确路径的 Markdown；普通文件工具仍可用，但模型不得把讨论当作源码、配置或构建脚本的修改授权。
- 方案阶段不提前生成详细实施计划；已有唯一台账只记录当前阶段、方案工作证据和下一步。
- 已有文件不是 Package 专属文件。修改前读取当前内容，保留用户改动，冲突时先对齐，不用旧快照覆盖现场。

方案草稿可供审阅后，父用 `delivery_approval(stage: "design")` 展示完整决策正文；提案明确携带 `documentStrategy`（`none`/`reuse`/`new`），落盘时由 `paths`、`technicalPlanPath` 和 `implementationPlanPath` 冻结实际规划路径。唯一确认面板显示文档策略和规划路径；无文档时显示不落盘和无路径。正文先说明改法，有规划文档时在详情列明路径、正文后补充修改摘要，无文档时以 `paths=[]` 在会话中审阅。底部提供“确认方案并开始实施”、提出修改意见和稍后再看，选修改意见后才打开多行输入；不以“已经写好”推定用户准备批准。意见通过原生 `toolResult` 返回并继续当前模型回合，父结合最新意见与现场修订正文，有文件时先读取再修改同一文件，说明变化和未采纳原因，再发起新提案。仅明确选择确认才创建原生批准记录；输入反馈不批准，也不开始实施。

在方案页选择稍后再看或按 Esc 关闭并终止本次推进，保留方案和已发送意见，不自动重问；输入意见时 Esc 只返回方案，未发送草稿在本次面板中保留。用户说“继续看方案”、提出新意见或在实施中说“继续”，由父模型按 Skill 核对当前分支已有方案、意见、进度、最新文件和执行证据，再形成必要的新提案或继续原范围剩余工作。每轮父提示直接提供内存中的当前方案确认状态；历史确认不构成本轮权限，重载、重开或分支变化后须重新取得真实确认。无文档任务使用会话正文，不补建文件；无记录则说明缺口，不跨会话猜测。新确认仍走原提案落盘、归属、展示及明确选择核验，不新增恢复状态、语义分类器或特殊批准工具。自然语言理解与修订质量依赖模型，fake provider 只证明交互与工具链路。

### 4.3 技术不确定性用最小实验解决

无法通过代码与官方文档确认的关键技术问题，先提出最小实验：要验证的假设、实验位置与操作范围、判断标准。取得实验范围授权后，在临时目录或隔离 worktree 中验证。

- 不修改主工作区，不自动合入实验代码；结果回写方案，实验失败也作为事实记录。
- 实验授权不等于正式实施授权，也不借实验完成整项正式开发。
- 实验涉及有风险的外部操作时，仍须取得对应授权；不得擅自使用生产数据或真实凭证。
- 父 AI、子 Agent、技术实验中的模型调用均无需模型费用确认，不设置模型费用审批，也不因模型费用暂停。
- 模型费用无需确认不等于可以泄露数据或操作其他外部系统。Package 自动化测试不额外禁网，默认使用 fake provider、临时目录和空凭证。

## 5. 任务规模调整深度，不建立三套流程

规模、风险和不确定性分别判断，由 AI 简要说明建议，不实现评分器、封闭分类规则或自动角色配额。

| 任务规模 | 技术方案 | 实施计划 | 编排倾向 |
|---|---|---|---|
| 轻量 | 简单明确时直接在会话说明效果、范围、改法和检查方式，无须方案文件 | 在会话中说明少量步骤、检查和停止条件，无须计划文件 | 父 Pi 直接修改并运行项目已有检查，按风险安排审查 |
| 中等 | 补充模块影响、接口或数据变化、主要取舍 | 按依赖拆分任务，明确每项完成证据 | 按需使用开发或独立审查 Agent |
| 大型 | 详细架构、边界、风险和必要图表 | 里程碑、依赖、分段验收及有价值的 Agent 分工 | 按实际可分解性编排，不固定团队 |

一行权限修改也可能高风险，应加强安全设计与验证；大量机械改动不自动等于高风险。文档依据持续查阅决策、跟踪多个依赖步骤和分阶段交付的实际需要，不按行数评分、不增加文档批准或任务模式开关。简单任务可不落规划文档，两次阶段确认与执行/验收边界保持；用户或项目明确要求文档时遵循其要求。父在开始修改或委派前用一行说明本次采用的路径（父 Pi 直接修改、开发子 Agent、是否安排独立审查）和理由，用户可当场纠偏；这只是会话说明，不新增档位字段、状态或自动评分。

## 6. 文档内容与唯一进度台账

### 6.1 技术方案回答“要什么、为什么、怎么设计”

覆盖目标效果、当前事实、范围与非目标、关键设计和取舍、风险、可执行验收，以及真正待用户决定的问题。篇幅随任务调整，不要求每次填满固定章节。

事实、推断和待验证内容必须分开。图表只在有助理解时添加，不规定张数，也不为图表建立额外服务或交付门禁。

### 6.2 实施计划回答“如何有序完成并证明”

方案确认后才准备实施步骤，包含依赖、验证方式、操作范围及停止条件。简单任务直接在会话中说明；需要持续跟踪时形成详细计划，按实际需要加入里程碑和节点状态、真实证据、阻塞与下一步，不扩展成逐工具调用日志。

路径服从用户与项目规则。项目已有相关唯一台账时沿用它；需要记录的新增需求可在其中开设对应部分，不再维护一份相同进度的 TODO、Mission 看板或 JSON 计划。无文档简单任务的方案、内部计划和执行结果保留在 Pi 原生会话中，不为参数、验收或收尾补建技术方案/实施计划文件。

需要文档时，方案记录设计决策及带有时间语境的必要事实，执行状态和证据索引只维护在唯一台账；README 面向使用者，不复制活动进度。轻量任务不为填章节重复需求。修改前读取现有内容、保留用户改动，修改后核对受影响部分；没有新变化、截断或矛盾时，无须反复全文读回所有文档。以上是模型的取证判断，不削减工具在实际执行边界的原生记录核验。

### 6.3 及时同步，而不是最后补写

- 每完成一个可独立验证的事项，立即同步状态与证据；有台账时回写台账，再推进后续事项。大任务按里程碑内的小节点交接，不等整个 worker 大任务结束才记账。
- 发生阻塞、方向变化或中断时，记录已做、未做、现场断点和下一步。
- 未运行、失败或跳过的验证如实记录；父项未全部完成时保持进行中、阻塞或待验证。
- 有文档时，方案变化更新方案、执行进度更新唯一台账；无文档简单任务在会话中说明结果和必要证据，运行时不另存一份业务进度。

## 7. 最小技术结构

这里的“简化版”是本 Package 自己的窄范围编排，不是另做一个通用 `pi-subagents`。保留 Pi Package 的原生资源组合，复用 Pi 的模型、工具、扩展加载、Session、事件与中止能力；不重新实现 Agent 运行循环：

| 部分 | 负责 | 不负责 |
|---|---|---|
| 精简 Prompt 入口 | 带入用户需求、指向当前阶段和 Skill | 重复整套规则、罗列逐工具脚本 |
| 一个交付 Skill | 对齐方法、规模判断、计划质量、编排与返工原则 | 承担硬权限判断或复制 runtime 协议 |
| 父 Pi 会话 | 唯一协调者，维护方案与计划，判断问题并组织执行 | 模拟固定全职团队、让子 Agent 批准范围 |
| 窄职责 Extension | 用户批准、有限任务委派、操作权限、writer 归属、执行证据与恢复检查 | 判断方案好坏、自动拆业务任务、维护第二份计划 |
| Pi 原生能力 | 独立会话、模型与工具执行、事件、会话持久化与压缩 | 由本 Package 重写模型调用或 Agent 执行循环 |

技术依据来自 Pi 公开 Extension、Session 和 TUI 文档：`tool_call` 核实交付工具来源，`ctx.ui` 提供交互确认和状态展示，`pi.appendEntry()` 保存运行事实，`ctx.sessionManager` 定位当前 Session 分支。`getActiveTools/getAllTools` 提取父实际启用的普通工具；标准 CLI `--tools` 同时支持内置与扩展工具，不用它裁剪成只读集合。

采用已验证的普通 Extension → 标准 Pi RPC 子进程路径，由父会话管理并等待任务结果。只实现这一条路径所需的协议交互，不同时建设同进程 SDK 后端和独立后台 runner，不增加用户启动器、常驻服务或通用 RPC 框架。Pi SDK 的独立会话能力已有实验依据，仍由 Pi 自身使用；本 Package 不再重复包装另一套会话、记忆或模型服务。

本 Package 只补足任务与上下文分配、权限与单 writer、结果收集与核对、取消收尾及必要断点记录。任务拆分、独立审查、返工和唯一台账更新由父会话结合 Prompt / Skill 完成，不变成第二套工作流引擎。不做递归委派、后台调度、Fleet、跨会话消息平台、通用插件适配层或自动回退。

新设计不安装、捆绑、调用、包装或读取 `pi-subagents` 配置，也不通过另一依赖间接接入它；只参考其资源重建和独立会话思路，不复制整套功能、配置体系或私有字段操作。用户无需为本 Package 安装、卸载或匹配它的版本，已有独立插件不由本 Package 卸载或接管；不承诺任意插件全兼容。

### 7.1 按配置重建环境，而不是克隆父运行现场

用户已确认：按配置重新加载任务所需的开发工具、插件、规则、Skills 和原有检查，配合独立对话上下文，已经足够支撑当前编排。子 Agent 接收任务、边界和必要事实，不复制父全部历史；任务授权仍是上限，不能替用户批准、复制 writer 或递归委派。不能静默退回少量内置工具，或仅凭相同工具名称声称执行能力相同。

| 场景 | 验收要求 |
|---|---|
| 工具与插件 | 配置所需实现实际可用，包括必要覆盖；缺少必需能力时明确拒绝该任务，不静默降级 |
| 权限与原有检查 | 正向操作成功，禁止操作未执行；任务所需的模型请求、工具权限和结果处理不遗漏、不重复 |
| 基础指令、项目与全局规则、Skills | 按配置保留所需内容，子模型使用独立对话上下文 |
| 交互、取消与记录 | 必要请求由父会话承接，结果归属正确；子 Agent 不能代替用户批准 |
| 结束与恢复 | 子会话结束后父会话不串线；writer 交接仍等待真实收尾与持久记录 |

不要求自动复制任意插件内存态、父会话中所有临时配置或父 TUI，也不为它们预建兼容桥、状态序列化层或插件适配平台。某项任务确实依赖无法重建的临时能力或不支持的交互时，报告该项具体缺口并暂停受影响任务；不把所有假设性兼容问题作为整个编排的前置门槛。

分析与开发委派共用 READY 环境核验：父侧从公开 `before_agent_start.systemPromptOptions` 取得本回合基础输入，子侧从命令上下文 `getSystemPromptOptions()` 取得按配置重载结果。父 CLI `--tools` 之外，既有内部 READY 请求携带同一本轮明确选择的工具名；所有子启动钩子结束后，子用公开 `pi.setActiveTools()` 承接列表，再比对基础指令、已加载规则正文、Skills 目录元数据和普通工具完整定义/来源，并核对模型与思考级别。这样不会因动态工具插件按新会话重置列表而丢失父已启用工具；未请求工具不加入此选择，实际未注册、配置禁用和定义/来源不符仍不能发送任务。工具名单不包含本 Package 的协调工具，不按联网、读写或插件类型分类。握手仅存摘要，不携带父完整历史，不扫描额外资源或克隆插件内存；不符时先收尾再报告缺口，不静默降级。摘要相同不证明实现代码或 Skill 正文相同，也不列举全部钩子链；普通权限钩子继续生效，正向与拒绝行为由真实 Pi/临时 Git 集成测试取证。

工具不一致时直接列出子侧缺少、额外启用和同名定义/来源不同的工具，提示核对是否已注册、配置禁用或父保留更新前的实现；核对收尾后在 `/delivery-status` 选择“结束交付”恢复原工具并重载，继续开发再 `/delivery-shape`；不能只凭差异断言具体版本或静默启用工具。Pi 的 `/reload` 保留当前启用列表，旧版裁剪可能随重载保留；交付开启时的重载通知明确说明这一点及阶段确认失效。退出后仍不一致则按差异核对插件配置，不增加版本协议、兼容层或自动恢复授权。

P3.1 普通交互复用同一 `ChildRpc`，只把子 `select/confirm/input` 请求交给父 TUI 的公开 `ctx.ui`，用闭包绑定本次子连接/请求 ID，标题标明 PID 和“普通询问，不授予交付权限”。回答不进入批准模块，不放宽工具或 writer；未决对话不并发堆叠。取消、确认拒绝、超时和 UI 错误中止当前父任务并等待子收尾；标准 TUI 的 `ctx.abort()` 会将排队消息取回编辑器，SDK 测试宿主只模拟该公开绑定行为。子任务先结束或父取消时关闭未决对话，迟到回答不能续用；RPC 没有独立子对话撤销通知，不能声称已克隆全部 UI 生命周期。非 TUI 父入口及不能接收取消信号的多行 editor 明确拒绝，不转发父编辑器或持久 UI 状态。真实 TUI 按键对三种问答、取消和队列恢复的限定补证见唯一台账 P6.3。

最小执行闭环：父会话给出任务并交接权限 → 简单任务由父 Pi 直接修改，复杂任务由 Pi 子会话完成一个片段并收尾 → 父会话或审查子 Agent 使用项目工具核对最终候选，按风险安排独立审查、同步结果与已有台账 → 继续、范围内返工或暂停。

四类委派卡片按本次工具调用身份消费真实 RPC 事件，默认两行显示任务名称、实际状态和当前操作/最近动作；文件与命令来自工具参数，结束事件不再显示为正在执行。子任务主动输出的文本可以展示，不使用 thinking 内容或额外模型总结。展开最多保留 16 条近期动作与约 4000 字符的输出尾部，并显示耗时与原始 Session 引用；折叠不显示次数、耗时、无更新提示或完成百分比。展示缓存不授予权限、不参与证据裁决，UI 通知失败不改变执行结果；开发、验收和审查执行结束后仍明确等待父原生结果落盘与交接核验。`/delivery-status` 同时显示当前普通只读任务及已有子记录位置，没有第二份持久运行日志。

当前 UI 使用 Pi 1.1.0 的公开 API，不提供旧 Pi 兼容层。全屏卡片通过 `MouseRegion` 点击打开原生任务详情；`/delivery-status` 不提供任务选择或手动解锁，只显示阶段、下一步和运行中任务，`Ctrl+O` 展开技术诊断。折叠卡片在两行内保留命令提示、简短目标、真实状态与当前动作，模型文本生成时显示“正在整理任务说明”，不把有界输出尾部拼成动作；长预览明确提示到详情查看。任务详情从父当前分支的原生调用、结果及已有委派引用临时构造，详情在打开期间每秒读取原始子 Session 和现有进度，投影仅留在当前弹层内，不保存另一份任务日志。

任务详情使用带边框、留白与主题背景的居中弹层，宽度上限 110 列，高度随终端可用空间调整。保留短任务、当前阶段与当前动作，其余空间连续展示子模型公开正文和工具输出，默认跟随最新行；向上翻阅后保留当前阅读视图，End 或回到底部恢复跟随。删除页签、工具列表和专属结果页，工具按原调用 ID 关联返回，连续显示工具名、简短目标、真实状态及输出，不展示参数或返回元数据面板。Enter 查看完整任务、模型理由、阶段和原 Session 路径，再按 Enter 或 Backspace 返回实时输出；两个视图各自保留阅读位置。父最终失败原因直接附在连续输出中；有过程工具异常时也附上父收到的原始摘要，其他正常结果不重复子总结。正常收尾的卡片使用中性标题，过程异常次数和具体返回显示在第二行，调用前拒绝、子 Session 未启动、收尾未证明和 writer 交接失败通过阶段和正文区分；重开详情保留摘要与原始输出；真正的委派失败仍使用错误色。

每个详情窗口按原 Session 的路径、文件身份、大小和修改时间复用未变化的解析投影，文件变化后重新读取；缓存不保存原 JSONL 或 thinking，窗口关闭后丢弃。每次刷新重新合入当前在途正文及父终态，不把实时内容写回落盘投影。删除、读取或解析失败清除旧投影并提示；该展示优化不参与批准、候选或执行终态核验。

`/delivery-status` 首先说明当前阶段和下一步：本次运行尚未记录方案确认时提示对应确认；子任务在途显示实际任务，执行结束但尚未交回时提示等待收尾，发现 lease 或操作锁时提示说“继续”进行恢复核对。仅投影既有确认、阶段和运行事实，不新增持久阶段表、不从旧 Session 恢复批准，不把“方案已确认”或没有在途任务当作交付完成；实际执行仍走原有持久核验。状态正文不展示 lease、PID 或 Session，详情通过 `Ctrl+O` 查阅。只有回合空闲、没有排队消息和在途任务、writer 已交回且没有残留占用时显示“结束交付”；单一结束操作默认回车返回，需先导航选中。

既有进度缓存按调用 ID 和模型消息时间关联在途工具输出及文本增量，每条保留尾部 64000 字符，超出时明确提示；工具局部结果按累计正文替换，不重复叠加。详情每秒合并这些在途片段与原 Session，已落盘正文与工具返回优先、不会重复，父工具结果存在时不再叠加在途片段；工具/模型消息结束及任务取消收尾清除对应临时缓存。暂停阅读仅保留当前视图正文，不写第二日志、不参与批准或验收；程序尚未输出、工具没有进度事件时不能提前显示内容。子文本、模型错误、读取错误或半行提示直接显示，不展示 thinking。刷新不重置正在阅读的内容；Esc 从任一视图直接关闭详情并停止刷新，不调用 abort、不停止子任务、不恢复旧权限。当前进度不能覆盖已落盘父工具终态。

方案确认使用 `ctx.ui.custom()` 临时替换底部输入框，不启用 overlay，完成后恢复输入。正文优先展示本次方案，不截断长正文；模型先用大白话概括本次修改和效果，多个改动用短条目，再展开设计、验收及必要条件。文档安排使用简短说明，规划路径、工作目录和记录 ID 放入详情；底部保留本机 Shell 权限和外部操作边界，去掉重复的“说明”标题。整个面板的阅读宽度最多 100 列，通常使用约八成半终端高度，扣除操作及固定提示后剩余空间用于正文，为主对话保留空间；空间不足时提示放大终端并仅允许退出，避免批准不可见的选项。面板采用“阶段标题与确认原因—正文—操作影响—操作—快捷键”的层次，各区之间用空行或分隔线区分；正文按可用宽度预留缩进后换行，避免窄终端截掉中文或路径末尾。页脚快捷键写“Esc 暂停”，不重复操作项名称。

方案审阅复用公开 `Editor` 与 `SelectList`，默认阅读，操作为确认方案、提出修改意见、稍后再看，初始选择稍后再看。选择修改意见后才显示输入框，并暂时隐藏批准操作；Enter 发送意见、Shift+Enter 换行，空提交不批准，Esc 返回方案并保留草稿，再次 Esc 才暂停。输入沿用原生编辑、长粘贴展开和光标，鼠标动作仅在实际点击时生效；生命周期取消信号关闭等待并丢弃迟到回答。意见保留在原生工具结果，不参与批准核验；新 design 请求撤销旧方案授权，默认 Markdown 编辑不受方案确认影响。内部计划仍须区分规划文档与实际可写目录，不新增摘要 Schema 或语义判断器。原生提案条目默认只提示提案已保存，展开仍提供完整内容；方案工具卡片折叠只显示文档安排和审阅结果的中文摘要，展开保留完整原参数及执行指令、反馈或暂停正文，失败保留原始错误。当前内存确认有效时再次提案，说明本次会替换当前确认；当前确认不可用且本分支保留旧批准条目时，说明旧实施确认不可用、需要重新确认；没有旧条目时只提示核对本次修改和验收，不猜测重载、切换、范围或原故障原因。恢复任务的正文沿用和变化由模型核对现有方案与现场后说明，不新增摘要字段、持久状态或语义校验器。展示顺序和缩略不改变冻结与读盘核验。

**轻量自有编排已按本期范围实现，完整运行态克隆不在当前目标内。** 正式权限、lease 与恢复的限定验收见唯一台账；既有完整克隆实验的失败结论保留，不因本期完成而改记为通过。

### 7.2 既有最小实验与证据边界

已有 TypeScript、测试宿主和打包基础可按新设计直接复用，但不以保留现有目录、模块或旧测试契约为前提；具体文件拆分、工具 schema 和命令名称按新设计的最小实现安排。预期收益是减少安装和依赖协调、让编排贴合交付需求，不预先承诺代码行数、耗时或 Token 一定更少。

Pi `0.84.4`、`pi-subagents` `0.64.0`、Node.js `>=22.19.0` 是旧实现的依赖组合，不是当前运行依赖或兼容性承诺。当前已移除 `pi-subagents`，开发依赖和本轮真实 CLI 验证统一为 Pi `1.1.0`、Node `25.2.1`、macOS；manifest 按 Pi Package 约定声明由宿主提供的 Pi peer dependency 为 `*`，不把未验证的旧版本写成支持承诺。父 Pi 标准入口启动子 CLI 时优先复用父进程正在运行的 CLI；嵌入 SDK 没有可复用入口时才按 PATH 查找，并在任务发送前核对父子环境。

既有 SDK 最小实验证据（详细命令与临时制品位置见唯一实施台账）：

| 实验 | 已确认事实 | 不代表 |
|---|---|---|
| 资源与工具 | 真实 SDK 执行读取，拒绝 fake provider 强行请求的未开放写入和递归委派；显式 Loader 不加载临时哨兵，默认 Loader 正向对照会加载 | 任意第三方插件的共存认证 |
| 单 writer | 单进程实验 guard 在模型调用前拒绝第二 writer；首个会话结束后交接，受限写工具实际使用 Pi `createWriteTool()` | SDK 自动提供 lease，或生产跨进程与所有路径竞争已覆盖 |
| 取消 | abort 到达工具且 SDK 会话结束后，自定义工具启动的外部进程仍可存活，必须显式清理并确认退出 | `abort()` 等于全部进程终止 |
| 中断重开 | 真实 worker 在部分写入后被 `SIGKILL`，Session 无对应工具终态；重开会话不自动调用模型或重放写入，实验锁在未知状态期间保留 | 父 TUI reload、全部崩溃窗口或正式自动恢复流程已验收 |

上述既有实验使用临时 Git、临时 HOME / agent dir、空凭证存储与 Pi 自带 faux provider；macOS 系统策略实际拒绝网络和真实用户目录读取，只允许临时目录及 `/dev/null` 写入。它们只证明表中的有限路径，不证明性能、真实模型交付质量、其他 Pi / Node 版本或平台已通过；实验代码未合入主工作区。完整运行态克隆的既有反证保留在唯一实施台账，不再作为当前实现目标，也不重复失败方案期待不同结果。

此前普通 Package RPC 原型的 9 类场景均通过限定验证，夹具单元测试 7/7 通过：实际文件修改和 Node 检查、工具覆盖与检查钩子、规则/Skills 描述、独立历史与记录、模拟确认、拒绝与钩子异常、合作式进程取消、崩溃保留部分结果、持久化失败关闭交接。父侧核对文件与工具结果、记录终态、交回 writer、更新临时进度的先后顺序已核对。全部使用真实 Pi `0.85.1`、临时 Git、假插件和 fake provider，不加载真实插件或调用真实模型；不是正式权限/lease、所有外部进程或模型交付质量的验收。该实验记录不代替后续正式实现与验证。

### 7.3 原生 Pi 工具环境

本 Package 面向标准 Pi 的原生工具环境。父 Pi、开发子、分析子和审查子都沿用当前会话已启用的工具、系统指令、规则、Skills 和权限，不补回用户停用的工具，不替换普通工具实现，也不引入第二套命令执行后端。

两种角色共用交付流程、批准、交付 writer 和证据规则，使用标准 Pi RPC 委派。开发按任务实现或修复，审查默认只检查、运行检查并报告问题，具体职责由委派提示词说明。审查通过当前工具读取 `before/after/diff.patch` 和原始 Session；父文档沿用专用工具，图片和其他媒体交给当前工具，不另换实现。

通过交付入口安排复杂开发与检查须有本轮方案确认和 writer；简单任务的源码修改仍由父 Pi 在同一方案授权下直接完成。父 Pi 在直接开始一个实施节点前使用内部 `delivery_path` 记录 `parent_direct`、节点、理由和是否计划独立审查；`delivery_develop` 与 `delivery_review` 的路径由交付入口按真实调用自动记录。普通文件、命令、补丁和联网工具沿用 Pi 的会话、并发、取消、输出预算及非零退出语义，Package 不拦截普通工具，也不把未声明的父侧修改猜成已观察到的节点完成。

普通工具输出截断时使用当前 Pi 已启用的读取工具或 Shell 提取所需原文。缺原文时报告缺口，不把重新审查当成读回原证据。只读子接收父明确给定的证据路径，不复制父完整历史；子收尾后父按原委派引用读取原始 Session。没有挂载、日志副本或文件可见性回退，不承诺文件读取是原子快照。

回合结束、取消或关闭时，交付层核实 Pi 进程和持久 Session；未知时保留 lease。父子握手核对工具定义与基础环境，无法对齐时不发送子任务。自动化使用 fake provider 和模拟批准 UI；真实模型与真实 TUI 试用单独记录，不混用证据。版本、命令和通过数量仅维护在唯一台账。


### 7.4 实施路径与失败事实的可见性

执行路径是交付记录的一部分，但不是新的权限模式或任务状态机。父 Pi 直接完成一个实施节点前，通过 `delivery_path` 写入当前原生 Session 的 custom entry，记录 `parent_direct`、节点、理由和是否计划独立审查；该工具只记录事实，不编辑 worktree，也不替代方案确认、writer 或项目检查。`delivery_develop` 和 `delivery_review` 在真实调用时由 Package 记录对应路径、节点和调用结果。未声明的父侧普通工具修改保持“未声明”，不通过拦截或猜测补建业务节点。

委派失败继续关闭权限和交付 writer，但返回结果同时保留可核对的原生事实：模型 `stopReason`、`errorMessage`、子进程退出、在途工具、Session 是否完整持久化、候选是否已核对以及原始记录路径。事实字段不等于验收通过，不建立封闭 Provider 错误码表，也不因可识别原因自动重放开发或审查。

子 Pi RPC 异常区分 JSON 解析失败与事件处理失败，在现有 `ChildRpc.failure` 错误正文中保留有界的原始原因；事件处理失败追加本次事件的 `type`、`command`、工具关联 ID/名称或扩展路径/事件名，不复制整条 RPC 记录、工具参数或结果。`extension_error` 保留 Pi 提供的原始 `error`。既有委派终态与 `executionFacts.childProcessFailure` 持久保存同一错误正文，父侧收尾核验失败追加在原始任务错误之后，不再覆盖触发原因。RPC 失效后的停止与未知终态保留 lease 规则继续沿用，诊断信息不授予重新调用或自动清理权限。

`/delivery-status` 在方案已确认且没有在途操作时显示“交付已启用，当前无在途任务”，在实际任务运行时显示“实施进行中”；`Ctrl+O` 展开详情，投影本轮已记录的执行路径和终态事实。该投影复用原生 Session 与现有委派记录，不生成第二份任务账本。长任务 checkpoint、受约束 review 重试和 cwd 诊断另行评估。


### 8.1 方案确认与实施授权

| 批准 | 用户确认的内容 | 后续允许 |
|---|---|---|
| 方案确认并开始实施 | 目标效果、业务与数据行为、边界、关键设计与验收标准 | 在原方案约束内维护内部计划，开发、自检、验证、审查和返工 |

使用 Pi 交互式 TUI 的实际用户确认作为权限入口，向用户展示清楚的批准摘要；不让模型生成的“已批准”、工具结果、压缩摘要或子 Agent 文本成为授权证据。取消不扩大权限，没有可信交互来源时保持只读，不补建 RPC 审批平台。

**批准固定当时同意的内容，不锁死整个文档。** 采用以下最小分工：

- 需要持续维护时，方案与唯一台账按原项目格式由父维护；方案 `paths` 列明确规划 Markdown，随确认冻结为子任务保护路径。无文档可传 `[]`，不能遗漏已有需维护的文档；每次 `delivery_develop` 或 `delivery_review` 的 `paths` 必须非空，且 `inputs` 只读。规划路径字段（`technicalPlanPath` / `implementationPlanPath`）没有对应文件时省略该字段，空字符串按省略处理，不因单个空字段拒绝整次批准，也不为填参数创建占位文档。**落盘策略（`reuse` / `new`）下，确认前在入口实查这些路径**：必须是 worktree 内、非空的普通 Markdown 文件（拒绝符号链接），缺失时拒绝批准并提示先用父文档工具落盘或改用 `none`；内部台账可在确认后由父创建。不落盘时面板首屏直接写明“方案保存在本次会话，项目里不新增文档”，无需用户翻详情。专用文档工具保护 Session 和 Git，普通工具沿用 Pi 权限。
- 确认时冻结本任务实际展示给用户的方案或计划内容，使用 Pi 原生 Session 条目保存；已有完整展示条目时引用它，否则在确认入口保存当次展示的正文快照。不复制整个项目台账，不把文件路径或可变文件摘要单独当成可恢复的批准正文。
- 正文按本阶段决策组织：方案说明目标、范围、关键设计、验收方向和必要取舍；确认后由 AI 内部维护步骤、依赖、验证和停止条件。详情提供完整方案，模型不再把相同内容抄入另一份实施正文。缩短重复表述不等于省略影响决定的条件，不增加固定字数或完整性规则引擎。方案正文结尾固定附一行「本次假设」，列出未经用户确认、若不成立就要改方案的推断，供用户直接否决；这是正文内容要求，不是新的必填字段或校验器。
- 批准记录绑定该快照、实际用户确认来源和工作区。实施计划、当前开发范围、检查命令和审查输入由 AI 在当前 Session 与每次工具调用中维护；不要求模型再维护一份完整 JSON 方案或任务树。
- 快照只在确认时形成，执行中不跟着文档更新。它是批准证据，不是第二份活动计划或进度台账；批准依据不能读取、来源不能证明或记录保存失败时，不启动新的交付开发或验收。
- 更新当前文档不能改变上述权限。恢复与委派时显式提供相关批准正文，不仅传递快照 ID 或摘要；Pi 自定义条目默认不进入模型上下文。委派和最终验收仍对照已批准的目标与验收要求，而不是把后来修改的文档自动解释为新批准。

文档变化按含义处理，而不是按整文件 hash 变化一律要求批准：

| 变化 | 处理 |
|---|---|
| 进度勾选、测试证据、断点说明、排版，或授权范围内的文件数量、步骤顺序、检查命令及实现细节调整 | 正常回写，不重复批准；代码或验证条件变化仍按 candidate 规则使旧证据失效 |
| 改变目标、数据行为、对外接口、验收标准或未覆盖的重大外部风险 | 先暂停受影响实施，回到方案确认点；旧批准不覆盖新内容 |
| 超出已确认的任务边界或扩大外部操作权限 | 须重新确认；父 Pi 或审查子 Agent 按当前项目检查方式核对，普通工具的修改范围由模型遵守，Package 不提供全工具路径拦截 |
| 外部修改或变化性质无法解释清楚 | 先只读核对并保留现场；不能仅标注“进度更新”就恢复写权限 |

上述变化判断由父会话对照批准快照完成，必要时结合审查和用户选择；运行时核实交付入口的授权来源、交接、专用文档范围与候选核对，不自动识别所有业务语义漂移或阻止普通工具越界。不新增标题解析契约、语义分类器或另一套文档状态。

### 8.2 工具能力与交付授权分开

- 普通问答不自动修改文件；任务所需 Markdown 默认由父专用工具编辑。方案讨论不授予源码修改权限，但普通工具仍沿用 Pi，不额外隐藏或拦截。
- 技术实验使用单独授权的隔离位置，不据此开放主工作区源码权限。
- 实施阶段允许当前 writer 使用任务真正需要的开发工具和本地自检；不能因为验证器固定而迫使 AI 手工模拟 formatter。
- 项目检查由父 Pi 或审查子 Agent 使用普通工具执行并保存可核对结果；命令可能写入构建产物，不能仅凭名称把它称为只读或安全。
- 普通工具的准入与原有检查交给 Pi 及原插件；Package 不建联网、文件或未知工具白名单。交付工具来源、批准或执行证据不能证明时拒绝本次交付调用。
- commit、push、PR、npm publish、部署、生产操作及其他有风险的外部写入继续需要明确的单独授权，不随实施自动获得。
- 任务结束后，已有明确授权的纯 Git 提交由父使用普通 Shell 工具完成，不重新调用开发委派或申请方案确认。重载使交付阶段批准失效，不撤销对话中本次明确的提交授权；普通工具缺失时引导用户在执行收尾后通过状态面板结束交付，恢复原工具。仍须核对实际差异和验证，不扩大为推送、发布或新代码修改，不借普通工具绕过未知收尾。

### 8.3 单写入者与边界诚实性

保留以 canonical cwd/worktree 为单位的交付 writer lease，用于串行安排本 Package 的开发、文档与审查任务。父会话与 worker 须遵守不同时写入的任务要求；更新规划文档或进度前先交回 writer。普通工具与其他程序不受这把锁强制控制，不能宣称它阻止任意并发修改。未知 worker 终态不启动替代交付 writer，不自动 force-release，也不撤销用户中断。

Pi 子会话不是 OS 沙箱，`cwd` 和候选核验均不能冒充事前路径拦截。此前实验已证明，`session.abort()` 完成后，自定义工具启动但未主动清理的外部进程仍会存活。普通工具的执行、取消与清理由原工具负责；交付层仅核实自己能观察到的 Pi 工具终态、进程和持久记录，不据此推定所有内部 I/O 或后台后代已消失。需要强隔离时另行选择外部执行环境，Package 不自研沙箱。

### 8.4 工具清理与 writer 交接责任

采用当前任务内的前台执行，不建设通用进程管理平台：

- 启动任务的父会话负责停止新增委派、向子会话传递取消，并等待当前任务的实际结果。
- 取消必须同时处理待执行消息；标准 RPC 的 `abort` 不清队列，模拟 Esc 须先 `clear_queue` 再 `abort`。不能将中止返回视作“后续任务不会再运行”的充分条件。
- 启动本地命令或外部进程的工具负责取消传递、必要的终止和等待退出；优先使用 Pi 已有工具与公开执行能力，不重写 shell 或按命令文本猜测是否会产生后台进程。
- 项目检查若需要临时服务，应在该命令自己的生命周期中完成启动、验证与清理。不把命令返回后仍存在的服务偷偷移交给 Package；确需超出这一范围的操作，先调整方案与授权。
- 交付 writer 只在 Pi 会话与工具终态、进程退出及持久记录核实后交接。`prompt()`、`agent_end`、`abort()` 返回或 Agent 声称完成，任何一个都不能单独证明所有写入已结束。普通工具内部清理不再由本包重复包装。
- 原生 Session 写入失败时不得用内存读回冒充落盘：此前已复现 `appendEntry()` 抛错后 `get_entries` 仍能看到未写进 JSONL 的条目。写入失败或持久状态未知时关闭交接，不修补 Pi 内部字段，也不据此新增双份状态账本。
- `dispose()` 只在停止和收尾之后用于清理会话资源，不代替停止执行，也不能先丢掉观察能力再释放 lease。异常清理路径不能无条件在 `finally` 中释放 writer。

| 结束情况 | writer 与流程处理 |
|---|---|
| 正常完成，执行和清理已确认 | 记录终态后交回 writer，父会话更新进度或推进检查 |
| 普通测试 / 工具失败，但执行已结束且清理完成 | 保留失败证据，可交接并在原授权内返工，不强制人工解锁 |
| 任务未发送、子进程已正常关闭 | 显示启动失败；握手前仍由父持有的 writer 也核对子关闭证明及父原生错误结果后释放，不要求尚未产生的模型 Session |
| 用户取消，执行和清理已确认 | 可释放 writer，但保持用户暂停，不自动继续或替用户撤销中断 |
| 清理失败、Pi 进程或工具终态未知、观察连接丢失 | 关闭交付入口的新写入，保留执行引用与 lease，不启动替代交付 writer；先查明现场 |

这里的终态记录只补足恢复所需的当前任务 / 命令引用与已知结果，详细事件继续使用 Pi 原生日志，不另建进程目录、后台轮询器或每个工具调用的第二份状态账本。具体取消、持久化失败及跨进程竞争以正式实现的回归证据为准，不把单进程实验 guard 当作成品 lease。

已结束且未自动收尾的失败（`finished` 且已 `fault`）保留为终态，但只有终态证明完整的同一运行态才可自动恢复。`terminalVerified` 只在原生工具结果唯一落盘、子进程/工具终态和 Session 收尾均核验成功后设置；如果之后 lease 清理失败，当前 workspace 完整身份、owner/coordinator、PID、processToken、Session、执行 ID、run ID 和 lease ID 必须全部匹配，恢复前还会重新读取原生结果和当前 Session，用户说“继续”时才自动清理同一 lease 并复位内存 fault。残留 operation lock 即使与已核实 fault 同时存在，也要求用户明确选择后清理；清理顺序先处理 operation lock，再删除 lease，任一步失败都保留仍可核对的现场。SIGKILL、扩展异常、记录不完整、现场变化、lease ID 不匹配、归属被替换或缺少终态证明均保持关闭，不启动替代 writer。

未知残留由交付工具在本轮方案确认核验之后显示一次“恢复交付”面板，提供“清理残留并继续”和“暂不处理”。恢复前先完成本次开发/审查的参数、原生调用和活动任务核验，再重新读取现场并核对 lease digest；父文档 writer 也使用同一前置检查。清理后保留已有代码、原始 Session 和失败事实，写入 `delivery-unlock` 审计，区分 `recovery: "automatic"` 与 `recovery: "confirmed"`。清理不恢复旧批准、不重放未知任务、不代表检查或审查通过；状态面板只投影摘要，完整 lease、PID、Session、执行路径和收尾证据通过 `Ctrl+O` 查看。没有 TUI 或归属无法核实时拒绝恢复选择，不做 PID 存活探测、超时清理、旧记录迁移或模型可调用的强制解锁。

本机 Shell 的边界：cwd 不限制文件写入；正常返回后可能仍有脱离 stdio 的后台后代，事后取消 signal 也不能证明其退出。用户在了解这些影响后要求移除 Docker，覆盖此前外部隔离的选择。当前执行在本机进行，不保留容器后端、迁移兼容或运行模式开关。

普通原生命令直接使用父配置的 `bash`，复用本机 Shell、PATH 和当前用户环境，不新增通用后台进程管理器。

普通文件、Shell、联网及插件工具沿用 Pi 自身权限。`paths` 与 `inputs` 指定任务与候选范围，不提供普通工具路径隔离；方案确认须清楚说明。审查模型可使用全部继承工具，通常按任务提示负责分析、检查和报告问题；未取得方案确认时，交付开发和审查入口拒绝执行。

执行引用中的 `settled` 只表示本次受控调用已经返回；不等同于所有后台后代已停止。子关闭证明核对受控工具调用、Pi 进程与持久记录，仍有调用在途或记录未知时不交回 writer。正常命令退出码直接记录，取消和超时单独标注；没有原容器的 1 GiB、CPU、PID、300 秒或禁网限制，原生 timeout 沿用 Pi 参数语义。

正式实施提案沿用已确认方案的 `documentStrategy` 和规划路径，另使用 `paths` 与可选 `inputs`；`inputs` 是纳入候选指纹的额外文件范围，不是只读挂载。子 Agent 主状态只展示运行中、已完成或异常退出；工具调用异常和项目检查结果作为原始执行结果交回父 Pi，不单独改变主状态。旧批准或执行格式不迁移、不自动恢复。

## 9. Agent 按价值编排，而不是按职位排队

- 父会话始终负责产品判断、方案取舍、进度和最终交付；子 Agent 的输出是参考与执行结果，不是批准。
- 轻量任务由父会话负责讨论、规划、源码修改、项目检查和证据裁决，台账按持续维护需要保留；按风险安排 fresh review。架构挑战、复杂实现和需要独立视角的任务才使用子会话，不为轻量任务组建固定团队。
- 测试设计 Agent 可以挑战断言和覆盖面，不能以“我测过了”替代真实命令结果。
- 独立只读研究、评审可以并行；有顺序依赖的开发任务串行推进，不为表现多 Agent 而建立 worktree fleet。
- 子会话只执行父交给它的任务，不注册本 Package 的协调入口；原有插件仍可加载，模型须遵守不继续委派的要求，不宣称工具层阻止一切递归。不建立固定长期团队或后台任务平台。
- 每次委派说明目标、边界、必要上下文和预期产物，不复制父会话全部历史；开发子 Agent 不承担唯一台账的同步职责。
- worker 完成一个可独立验证的片段及自检后结束本轮执行；父会话核对证据、取得 writer，按需同步已有唯一台账，再继续或直接交付。节点不是按文件或时间机械切分，不要求每次都换新 Agent 或重新取得用户批准。
- 子任务固定继承父 Pi 当前的 Provider 和模型，只按任务需要调整推理级别，复用 Pi 公开能力；不读取 `pi-subagents` 配置，不硬编码 Provider、模型 ID、强制 fallback 数量或模型费用确认。

四类委派均从公开 `ctx.model` 取得父当前模型，接受可选 `agent: { thinking?, reason }`，指定配置时理由必填；省略级别继承父当前级别。父每轮交付提示通过 `getSupportedThinkingLevels()` 列出当前模型支持的级别，不查询其他模型、认证或费用。工具参数不接受 `agent.model`，不再提供 `delivery_models`。父切换模型后，新启动的任务跟随切换，已启动的任务保留启动时模型。级别不受父模型支持时拒绝，不静默压低级别或自动换模型。RPC 启动仍显式传模型/级别，任务发送前用实际子状态核对；父原生调用的完整参数（含 agent）仍与私有执行快照绑定。

场景与复杂度由父结合 Skill 的 14 类工作指引判断：需求澄清、现状取证、方案编写/审查、计划编制、代码编写、测试编写、代码审查、执行验收、故障返工、文档编写/审查、交付发布、运行维护。明确执行通常 low，局部开发与一般分析通常 medium，关键设计、复杂边界和审查通常 high，困难任务且模型支持时才考虑 xhigh；不是固定映射或必须走完的角色清单，不支持推理的模型使用 off。缺事实、环境或权限时解决实际缺口，不用升档和重复委派替代取证。父仍负责方案、计划与 Markdown，子选择不改变父模型、父推理级别或授权范围，不实现发布/运维系统。

子 READY 核验后才把实际模型、级别与选择理由加入既有进度和委派记录；折叠卡片保持两行并显示简短模型/级别，详情显示完整标识与理由，重开时投影原记录。未取得实际状态时不冒充已选模型，不增加另一份任务日志、费用/token 统计或自动效果评分。机制此前已由禁网 fake provider 验证，真实模型的取舍质量与节省效果留待用户使用判断。

<a id="section-10"></a>
## 10. 验证、审查与自主返工

### 10.1 真实验证与当前候选绑定

验证先小后大。开发期自检用于快速定位，父 Pi 或审查子 Agent 按项目实际工具链运行测试、编译或 lint，记录命令、环境、终态和关键结果；失败、超时、取消与未运行必须区分。

开发和审查工具已自动附带原方案与实施正文，父模型的 `task` 只补当前节点目标、事实、预期证据或审查盲点。父仍核对实际变更及相关原始输出、终态和审查正文，按信息缺口定位记录，不用实现者总结代替证据，也不为复述已核实事实反复遍历整个 Session。成功检查若只缺退出码或摘要，先查原生记录；实现、条件发生变化，或失败、证据确有缺口时才复验。开发自检不能替代父核对，也不能替代高风险任务的独立审查。

保留 candidate 与 evidence 绑定：被验证的代码范围冻结后才能形成交付证据，相关代码、测试、依赖或验证条件变化后不能复用旧结论。编写进度记录不是代码验证的替代，也不能通过把任意文件归为“进度”而逃避验收。

按风险和实际盲点决定是否需要 fresh-context review。需要时 reviewer 应读取原始目标、检查方式、当前代码及实际 diff，不只看 worker 总结；review 结论记录实际审查时的候选。reviewer 默认只检查、运行检查并报告问题，发现问题后由父会话直接修复或重新委派开发，保持审查与修复的职责分离。审查子仍继承普通工具，Package 不在代码层面裁剪写入能力；若模型违反职责提示发生修改，仍重新捕获最终候选和 diff，不把修改前结论冒充修改后结论。

候选在需要独立审查时绑定审查输入：包含明确源码及额外输入的内容和元数据，不按 Git ignore 排除，也不快照整台电脑或全部依赖。候选读取不是原子快照，不能保证发现范围外写入或所有临时改回。父 Pi 或审查子 Agent 的普通工具结果只作为实际证据，不生成第二套执行记录；未运行或结果缺失时不能声称通过。

`delivery_review` 在开发或父侧直接修改完成后按风险调用。审查子获得原方案、内部计划、代码路径、父维护的规划文档清单（只说明它们不在子任务修改范围、不算越界，但文档与代码是否一致仍需核对）和实际 diff，使用继承的普通工具独立分析并主动运行项目测试、编译或 lint，记录真实命令结果；任务要求逐条取证——先列出方案与实现依赖的关键事实并给出文件与行号，再列出未覆盖的失败路径，只有经实际读取或实际运行证实的结论才算成立，不要求审查者只作表态。默认不修改源码，发现由父会话裁决并交给父 Pi 或 `delivery_develop` 修复。Package 不在代码层面裁剪写入能力；若模型违反职责提示发生修改，记录修改后的候选，不把修改前结论当作最终结论。不新增评分器、完成状态机或第二份计划；该机制不承诺能识别所有语义缺陷。

审查制品用固定 `/usr/bin/git`、空配置、禁用 fsmonitor 和 `--no-replace-objects` 的原始 blob 查询，忽略仓库的对象替代映射但不删除引用或修改历史；实际差异在临时 before/after 副本间用 `--no-index --no-ext-diff --no-textconv --binary` 生成，不触发项目内容过滤器。以原始 HEAD 为明确基线，无 HEAD 使用空基线；包含全部可写候选及 Git 常规列出的只读输入，被忽略的只读依赖由 reviewer 按路径核对。特殊旧基线类型、非无损 UTF-8 路径、缺系统 Git 或超过单文件/差异 16 MiB 时报告缺口；制品暂存于系统临时目录，用户在状态面板选择“结束交付”且退出检查通过后清理；退出被阻塞或清理失败时保留供查阅，不是第二活动台账。READY 前未发任务且实际正常退出不要求不存在的模型 Session 文件，已发任务则必须核实持久关闭。

### 10.2 正常失败留在已授权的开发闭环内

```text
实现 → 自检 / 验证 / 必要审查
          ├─ 通过 → 更新进度，推进下一项或交付
          ├─ 范围内缺陷 → 定位、修复，形成新候选并复验
          └─ 超范围、设计变化、授权或执行事实不明 → 暂停并说明
```

- 代码缺陷、测试断言错误和范围内审查返工，不自动转成必须用户手动恢复的阻塞。
- 先区分代码、验证环境和计划问题。已授权的本地环境修复可自行处理；需要改变验收标准、外部环境或权限时请求用户，不靠降低测试要求消除失败。
- 对可证明未发生副作用的临时失败，可以在现有范围内重试；结果未知的命令不盲目重放。
- review 发现由父会话裁决，集中返工后检查关闭情况与受影响范围。修复方式默认按影响面选：单文件、不改变对外行为契约的修复由父 Pi 直接改并复跑项目检查；涉及多文件，或金额、并发、权限、迁移等边界，或需重新跑子任务自检的，重新委派 `delivery_develop`。这是完成方式的选择，不扩大已确认范围，也不新增一次实施确认。不得不断加入无关优化，也不以固定轮数替代收敛判断。
- 同一问题反复出现且没有新证据时，停止重复补丁，改变定位方式或做最小实验；若需要关键设计变化，再返回用户确认。

用户中断、权限不明、writer 归属不明、外部风险和需要业务选择，才是明确暂停的原因；不是所有非零退出码都需要人工解锁。

### 10.3 实施修订与任务历史展示

方案确认后进入实施。同范围代码返工和项目检查沿用本轮批准，不因失败重新确认。业务目标、数据行为、对外接口、验收标准或重大外部风险变化时暂停并重新确认方案。不建立第二套阶段状态或自动判别检查语义的规则引擎。

方案确认支持“提出修改意见”。意见不授予权限；父按意见修订方案提案。确认后简单任务由父直接修改并运行项目检查，复杂任务才安排开发委派。取消或暂不批准后暂停，不循环弹窗。批准核验失败仍关闭权限。

文档策略与角色路径在批准入口统一核对。`none` 没有规划路径；落盘任务必须明确技术方案或实施计划的实际角色路径并将其列入 `paths`，允许沿用单份合并文档，不为填参数新建占位文件。实施沿用已确认方案，其他规划文档也须可查看，不能展示“复用现有文档”而不给出任何实际规划文件。

任务列表按已确认方案组织实施批次，开发和独立审查显示各阶段调用次数；返工仍归同批次。数据从原生批准和委派记录投影，不新增任务树或持久日志。列表使用“实施批次 N”与“独立任务”区分归属，顶部显示任务总数和当前运行数量，并在已有 Agent 记录时显示当前模型和推理级别；主状态仍只有“运行中 / 已完成 / 异常退出”，检查结果保留在详情中。

父模型在方案确认前发生 provider 5xx 或连接中断时，Package 只保留当前会话和交付状态，不把普通正文视为方案批准。恢复由下一轮父模型复用已形成的正文并重新调用 `delivery_approval` 生成持久 `design` 提案；正文不完整时先补齐方案。没有持久提案和批准记录时，禁止自动进入实施、验收或开发，避免用半截输出扩大权限。

`/delivery-status` 的正文显示当前阶段、下一步和当前任务；工作区、继承工具、运行模式、lease、状态目录等诊断信息通过 `Ctrl+O` 展开。

### 10.4 方案确认后的自动回合衔接

方案批准成功后，Package 应在当前父 Agent 真正 settled 后自动开启一次受控 follow-up 回合，避免把“开始实施”交给模型是否愿意继续的偶然行为。design 批准只触发“整理内部实施计划并按复杂度执行”的回合；简单任务由父 Pi 直接完成，复杂任务按需调用 `delivery_develop`，必要时安排 `delivery_review`。

衔接标记只保存在 Extension 内存中，并绑定方案批准 ID。在 Pi 公开 `agent_before_settle` 边界，若该标记仍有效、本轮完成且没有用户排队消息，返回原有边界条目加一条隐藏的实施说明 `custom_message`，以及 `continue: true`。Pi 负责持久化条目、根据追加后的上下文续跑；`agent_settled` 只通知全部衔接已完成，不再启动该回合。若父模型已自行开始执行、发生会话切换、取消、错误或非父 TUI，则清除衔接标记；批准失败、用户提出意见、暂停和未取得持久批准时不触发。该机制不创建第二套阶段状态、任务树或批准记录。

### 10.5 `/delivery-status` 默认摘要

状态面板正文只保留当前阶段、下一步和运行中任务。详细动作、模型、命令、输出、Session、lease、PID、执行路径和收尾证据通过 `Ctrl+O` 展开；任务详情仍可从原生工具卡片进入，不在状态面板重复提供任务选择。常规面板没有解锁操作，只有满足回合空闲、无排队消息、无在途任务、writer 已交回且无残留占用时显示“结束交付”。单一结束操作默认回车返回，必须先导航选中后才执行。非 TUI 模式只返回可读取的状态详情，不提供恢复选择或结束操作。

### 10.6 实施范围与委派启动失败

每次开发或审查调用的 `paths` 表示本次子任务可修改或核对的候选范围，必须非空；`inputs` 表示只读输入。设计批准中的规划文档路径由父会话维护，始终属于保护路径。入口必须拒绝本次 `paths` 或 `inputs` 与已确认规划路径相同、互相包含的情况，避免把错误范围留到检查时才暴露；错误在调用前范围校验阶段返回，列出有界相对冲突路径，说明两类参数的含义、修正方式并明确子 Session 尚未启动。空范围、越界路径和空白路径也在同一阶段报告。

子任务在发送前因范围、Skills、工具、规则或指令握手不一致而被拒绝时，属于启动失败，不产生开发证据。错误必须明确提示父模型停止普通源码/测试写入，先核对环境和收尾状态；Package 保留 Pi 原生普通工具能力，但流程提示不能把普通工具当作失败委派的替代路径。

未发送任务的委派显示“异常退出”，子进程正常关闭只证明收尾可核实。已发送任务且收尾可核实的开发或审查显示“已完成”，检查失败单独保留在结果中；生命周期展示不改变 writer 交接规则。进度详情另外显示调用前校验、批准/候选准备、子 Session 启动、子 Agent 工具执行、子 Session 收尾和父结果/writer 交接等阶段；`SIGTERM`、`SIGKILL`、父回合中断、模型终态、工具失败、在途工具、Session 持久化和审查候选失效继续作为事实，强制终止不能形成审查通过。

本次修复保持现有安全关闭策略：不放宽父子环境一致性检查，不增加第二套权限隔离；提前校验实施候选与规划保护路径的冲突，修正启动失败状态，并补足停止提示。

### 10.7 生命周期与验收结果的卡片渲染

交付任务卡片的颜色和主状态只反映子 Agent 生命周期；父 Pi 直接检查没有子 Agent 时，结果保留在父工具和会话中。复杂任务子 Agent 已正常收尾显示“已完成”，异常进程或无法核实收尾显示“异常退出”。项目测试失败、命令非零或候选变化属于实际结果，仍通过工具结果、详情和父模型可读正文交回。

工具层继续保留 Pi 原生的失败语义，父模型仍能看到检查失败并决定是否进入或继续审查；Package 只在自有渲染器中根据已核实生命周期选择背景和标题颜色，不伪造成功结果或隐藏失败详情。

### 10.8 集成宿主契约与实施范围样本

真实 Pi 集成宿主必须提供被验证 Extension 真实使用的公开 UI 能力；部分 UI 替身不能以 `as` 转型后缺少方法，否则会在 `session_start` 中断后续恢复逻辑。补齐测试宿主契约属于测试夹具修复，不在产品代码中增加针对不完整宿主的兼容分支。

测试样本应覆盖一次方案确认后的动态路径语义：设计规划文档路径由父维护并受保护，开发或审查只传实际源码或测试范围，例如 `paths: ["src"]`，不能使用设计样本的 `plan.md` 作为实施范围。保护路径校验继续在产品入口执行，测试应覆盖合法范围和冲突范围。

<a id="section-11"></a>
## 11. 进度与中断恢复

恢复采用“原始记录指路，现场确认”：

1. 读取项目规则、原始会话中的方案、内部计划及已有相关文档，确认需求、原批准边界和记载的断点；无规划文档时不补建文件，记录不足则说明缺口。
2. 核对实际 cwd/worktree、Git 分支和现有改动，保留用户未提交内容。
3. 通过现有运行记录核对活动执行、writer 归属和已完成验证；不能仅因计划写着完成就视为事实。
4. 从最后可证明的位置继续。结果未知的写入不重放，旧 evidence 不移植给新 candidate，不能证明的权限保持关闭。
5. 将核对后的当前阶段、断点和下一步写回已有相关台账，无文档任务在会话中说明；用户主动暂停后，等待其继续意图，不自动取消中断。

运行时只补足文档无法表达的执行事实，例如用户批准引用、workspace/writer 归属、仍需辨认的执行 ID、候选与验证证据引用。第 8.1 节的 Session 快照仅用于证明批准时同意的内容，不随实施回写；不保存第二套任务树、活动计划副本或每个工具调用的业务状态。

恢复时区分“任务做到了哪里”和“是否还能产生写入”：前者由原始会话正文、已有方案/台账、Git 和证据核对，后者由原执行及其工具终态证明。没有旧执行的可证明终态时，即使台账写着完成或会话已经重开，也不能启动替代 writer。正常退出或 reload 应先停止和收尾再释放观察资源；异常退出无法完成该顺序时，恢复默认只读，保留部分改动，不盲目重放。

同一流程 Session 的续接、压缩、reload 和分支变化均需核对当前事实，不能把上下文摘要当成授权。新 Session 可依据原始正文及已有文档重建任务理解；没有本轮可信方案确认时不能使用交付开发和审查入口，未知 writer 仍阻止专用文档写入。普通工具继续由 Pi 管理，不实现旧版 Session 兼容。

当前限定实现：正常在途 reload 中止父回合，保留旧 writer 处理器直至原生 `agent_settled`，按原有 I/O、子退出、持久结果核实完成交接后才撤销残余 lifetime。未完成清理或缺记录仍锁定，不补写终态；已写文件不回滚。正常收尾后重载或分支导航不自动调用模型，原权限失效；重新确认后可继续。压缩只影响模型上下文，本轮权限仍核对私有确认与原始磁盘；摘要本身没有授权或检查能力。

`/delivery-status` 直接读取同一 worktree 的 lease，正文只投影阶段、下一步和运行中任务；展开详情显示原 owner/PID/Session/执行 ID、记录位置与原诊断，不把当前进程无 active 对象说成现场空闲。继续进入 `delivery_develop` 或 `delivery_review` 时，先核验本轮方案确认，再重新读取现场。若终态证明完整且 workspace、owner、Session、执行 ID 和 lease ID 完全匹配，只清理同一残留并保留 `delivery-unlock` 审计；崩溃、扩展异常、记录不完整、现场变化或归属不明时只显示一次“恢复交付”选择，不能启动替代 writer。状态面板不手动解锁、不做 PID 存活探测、不做超时清理或旧记录迁移；未知状态选择清理也不恢复批准、不重放执行。正常 reload/重进的真实 TUI 证据及故障矩阵见唯一台账，不覆盖所有崩溃窗口或任意插件。

`src/stream-retry.ts` 在父子公共入口注册公开 `message_end` 钩子，仅对 `role=assistant`、`stopReason=error` 且 `errorMessage` 确切等于 `stream_read_error` 的消息附加重试说明。保留原始错误前缀、正文、调用片段、用量及失败状态；说明中的 `you can retry your request` 由 Pi 1.1.0 的原生分类器识别，替换发生在消息持久化及重试判断之前。重复处理不追加第二次说明，其他模型错误、工具结果和用户主动取消不变。这依赖当前公开钩子和原生文本分类行为，升级 Pi 时须运行对应集成验证，不导入私有路径或修改安装包。

`src/stall-watch.ts` 用公开 `message_start` / `message_update` / `message_end` 观测**内容增量间隔**，在交付启用期间（父子均安装）对停顿做兜底恢复：仅在 assistant 正在流式输出时计时，工具执行期间计时器停止，因此长时间运行的命令不会被误判；阈值默认 120 秒（可用 `PI_ADAPTIVE_STALL_MS` 覆盖，仅测试用）。超时后先 `ctx.abort()` 中断本次请求，等 `agent_settled` 再以 `deliverAs: followUp` 开启新的恢复回合（原中断通知为 `aborted=true`，恢复完成为 `aborted=false`），并在界面明确提示“已中断本次请求并自动继续（第 N/2 次）”；每个回合最多自动恢复 2 次，收到完整回复（非 aborted/error）即重置计数，避免“停顿→重试→再停顿”无限循环；达到上限后不再自动重试，改为提示用户。它不重写模型调用或 Agent 循环，也不替换 Pi 原生重试：字节级 `httpIdleTimeoutMs` 实测对 `openai` SDK 与插件自带传输不可靠，因此这里按内容增量判定，二者并存。


重试沿用 Pi 的开关、次数上限、指数退避、提示与取消，不注入“继续”或重放已完成工具/委派。失败消息保留在 Session，半截工具调用不执行；父继续等待子 `agent_settled` 与持久收尾，重试不释放 writer 或生成批准。非目标错误、RPC/记录故障与未知执行仍关闭权限。本机命令后断流的自动化证据使用 fake provider，不代表底层根因已定位或取得新真实模型恢复证据。

## 12. 旧机制取舍

| 保留或复用 | 删除或重做 |
|---|---|
| Pi 原生 Prompt / Skill / Extension 与公开 SDK 会话能力 | `pi-subagents` 依赖与接入协议、两种执行后端、第二套 runtime / 计划系统及兼容垫片 |
| 父会话唯一协调、每 worktree 单 writer | 固定完整团队、强制按规模切换父/worker 的旧路由 |
| 真实用户授权与一次方案确认并开始实施 | 固定第二次实施确认、Tiny 特例与自动批准捷径 |
| 规划文档作为协作事实源 | 批准后才 create-only 落盘、完整机器契约与文档并行维护 |
| 真实命令、候选及审查证据绑定 | 所有验证失败统一人工解锁、脱离开发自检的机械脚本 |
| 必要的执行断点与未知状态失败关闭 | 多份状态互相对账、将每个业务判断硬编码成状态或错误码 |
| 按可验证节点同步唯一台账 | 进度回写对旧 `VALIDATING/BLOCKED` 状态窗口的依赖 |
| 最小权限与明确的真实安全边界 | 固定读量额度、标题排版校验、固定角色与图表配额 |

本表是设计职责的取舍，不是要求保留旧实现文件。整个 Package 可以重新组织或实现，不要求沿 R29 逐项打补丁；安全目标继续成立，但实现与测试不受旧契约约束。具体代码是否复用，以新需求能否直接覆盖为准，不为保留文件结构而改写新目标。

## 13. 验收要求与实施边界

以下是已确认方案的验收要求，不是已通过证据；具体实施顺序与进度只记录在 `docs/实施计划.md`：

- 使用标准 Pi 正式版即可安装本 Package，不依赖 `pi-subagents`，不要求定制 Pi，不补丁宿主私有运行态；用户已有的独立插件不需要为本 Package 卸载，不新增第二个委派 runtime owner。
- 开发子 Agent 满足第 7.1 节的环境重建与独立上下文要求：任务所需工具、规则、Skills 和检查实际可用，缺失能力明确报告；不以工具名一致代替行为验证，不要求完整克隆父运行态或 TUI。
- 自有编排仅覆盖当前交付流程；不直接或间接依赖 `pi-subagents`，不另做通用 Agent 框架、后台平台、通用插件适配平台或双执行后端。父子沿用同一标准 Pi RPC 委派路径和当前会话工具环境。
- 标准 Pi 的父会话与子 Agent 满足第 7.3 节的工具继承、基础环境核对和完整交付边界要求；环境不一致时保持失败关闭。
- 简单明确的需求可用会话中的简短方案一次确认并开始实施，不创建规划文件；需要持续维护时落文档，已有相关台账沿用，不自动开出完整 Agent 团队。
- 方案可反复修改并提前落盘；方案与计划阶段不授予正式源码修改授权，模型须遵守，普通工具能力保持。明确需求不反复盘问，未决关键问题不草率收口。
- 实验能在授权隔离范围验证假设，主工作区不变；实验结果不自动合入，模型费用不触发审批。
- 方案确认后，范围内测试失败能自主定位、返工和复验，无需用户逐轮解锁。
- 需求、关键设计、验收或安全范围变化时及时停止并请求相应确认。
- 已有相关台账按可验证节点及时回写，无文档简单任务直接在会话交付结果和证据；worker 与父会话文档更新不存在双 writer。
- 进度与排版更新不撤销原批准，也不能扩大权限；实际委派与验收仍对照用户当时确认的内容。目标、验收或权限变化不能通过改文档绕过确认。
- 普通失败已结束且清理完成时可自主返工；用户取消后不自动续跑，清理失败或终态未知时不交接 writer。
- 对外只提供进入和状态两个命令；规划和恢复使用普通对话，任务详情从原生工具卡片进入，状态正文只显示摘要，技术诊断通过 `Ctrl+O` 查看。继续交付时由工具在本轮方案确认核验后自动判断是否能安全复位同一残留；未知收尾只显示一次恢复选择，不通过状态面板手动解锁。默认关闭及证据查看不改变启用或批准状态；明确结束仍核验原执行、lease、操作锁和原工具恢复。
- 中断恢复能识别部分改动、未知执行与过期 evidence，不猜测完成、不重复未知写入。
- 关键权限与恢复边界同时取得单元测试和真实 Pi / 临时 Git 集成证据；普通自动化使用 fake provider 和隔离 agent dir，网络不额外限制，不冒充真实模型体验验收。

整体方案已确认：第 7 节的轻量自有编排、第 8.1 节的批准快照、第 8.4 节的清理与交接、第 11 节的恢复均按现有 Pi 与 Package 的职责实现，不新增计划、语义规则或进程管理平台，不再等待完整运行态克隆。

工具继承的实施证据保留在唯一台账第 13.57 节，最新工作与验证入口统一见台账首页。讨论深度、任务拆分、修改范围遵守、审查裁决与进度组织由 Prompt/Skill 和父模型承担；运行时核验交付批准、专用文档范围、交付 writer、候选及持久终态，不保证模型判断或测试覆盖充分。跨平台、任意插件、所有故障窗口及完整业务交付仍未全面覆盖。

方案与实施计划均已确认。唯一台账第 1 节提供当前摘要与断点，第 13.1 节保留历史阶段，第 13.3 节保留 P1—P6 实施与验收，后续章节记录试用、修复及追加验证。后续若发现关键方案变化或新的关键不确定性，先返回用户确认或提出范围明确的最小实验，不自动扩大实施授权。

<a id="section-14"></a>
## 14. 本机接入与开发验证

本节承接 README 中的详细操作说明。首次使用入口与流程图见 [README](../README.md)，运行机制和边界沿用前文，验证进度仅维护在实施计划。

### 14.1 试用环境

- 已安装标准 Pi 并配置可用模型，在可信 Git 项目中启用本地 Package。当前实际验证组合为 macOS、Pi `1.1.0`、Node `25.2.1`；manifest 按 Pi Package 约定声明由宿主提供的 Pi peer dependency 为 `*`，安装声明不等于其他组合已经验收。标准 Pi 子任务优先复用父进程的 CLI 入口；嵌入 SDK 无可复用入口时才按 PATH 查找工作区外标准 CLI，升级后需重启已运行的父 Pi。
- 在目标项目 `.pi/settings.json` 的 `packages` 中追加本仓库绝对路径，保留已有配置。当前任务正常收尾后重载或重新启动 Pi，再确认项目信任；加载本身不启用交付约束，`/delivery-status` 可查询状态。
- Pi 默认四工具不包含 `grep/find/ls`。需要原生仓库查找时，在已有 `defaultTools` 中加入这些工具，例如 `["read", "bash", "edit", "write", "grep", "find", "ls"]`；项目数组会替换全局数组，修改时保留其他所需工具。Package 不自动启用停用的查找工具。
- 原生 `grep` 需要 `rg`，`find` 需要 `fd` 或 `fdfind`，可来自 PATH 或 Pi 的本地缓存。离线环境应提前准备；工具名称可见不代表底层程序就绪，缺失时按实际错误处理。
- 开发和项目检查直接使用项目的本机工具链，不需要 Docker、镜像或其他执行服务。项目依赖仍须可用；Package 不擅自安装依赖、修改环境或声称工具名称存在就代表项目可以通过测试。
- 命令按当前用户权限执行，文件和网络不由 Package 隔离；后台进程边界与 writer 交接见第 8.4 节。测试入口同样不额外禁网，保留临时目录与凭证隔离。
- 若 `pi-web-access` 报公共域名解析到 `198.18.0.0/15` 而拒绝抓取，先核实是否使用 TUN/fake-IP 代理，再按该插件的 `ssrf.allowRanges` 配置声明实际代理地址段。此拒绝来自原联网插件；本 Package 不自动改其配置。唯一台账第 13.60 节记录了临时试用配置中的这一环境适配，不能把外层工具正常返回但正文含抓取错误记作联网内容已取得。

### 14.2 原生工具与子会话环境

Package 只使用标准 Pi 的公开 API。父 Pi、开发子、分析子和审查子沿用当前会话实际启用的工具、系统指令、规则和 Skills，不补回被停用的能力，不复制任意插件内存，也不替换普通工具实现。

1. 在目标项目 `.pi/settings.json` 的 `packages` 中追加本仓库绝对路径，保留已有配置。当前任务收尾后重载或重新启动 Pi，再确认项目信任；加载本身不启用交付约束，`/delivery-status` 可查询状态。
2. Pi 默认四工具不包含 `grep/find/ls`。需要原生仓库查找时，在已有 `defaultTools` 中加入这些工具，例如 `["read", "bash", "edit", "write", "grep", "find", "ls"]`；项目数组会替换全局数组，修改时保留其他所需工具。Package 不自动启用停用的工具。
3. 使用 `/delivery-shape` 进入，再用 `/delivery-status` 核对当前工具和阶段。父子工具定义、基础指令、规则或 Skills 无法对齐时，不发送子任务；不要通过跳过握手或放宽检查继续执行。正常退出经重载恢复进入前工具选择，不承诺恢复其他插件内部状态。

具体工具、路径、命令生命周期及输出截断的处理范围见第 7.3 节。

<a id="section-14-3"></a>
### 14.3 开发验证

以下命令在本仓库运行，需要已有项目依赖。默认入口不额外禁网，也不强制 Pi 或 npm 使用 offline 参数；继续使用临时 Git、临时 HOME/agent dir、空凭证和 fake provider。缺少有效文件隔离时失败退出，不静默跳过；仅本仓库源码/依赖及必要祖先元数据可从真实 HOME 读取，临时根外写入被拒绝。网络回归通过真实 Pi 连接本机临时服务验证，不依赖公共网站的可用性。

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

本机命令的真实 Pi/临时 Git 集成测试已包含在 `test:all`。测试不连接 Docker socket，所有测试命令继承临时 HOME 与文件隔离，网络不额外限制。原生查找测试需要可用 `fd`，可将已缓存二进制复制到临时目录加入本次测试 PATH，不开放用户配置目录。

`test/support/run-tests.ts` 会把仓库本地 `node_modules/.bin/pi` 放在测试 PATH 首位，并在该入口不存在时直接失败；因此测试父 SDK 与子 CLI 使用同一仓库版本，不回退到系统全局 `pi`。生产标准 Pi 运行时优先复用父进程的 CLI 入口；嵌入 SDK 无可复用入口时才按 PATH 解析工作区外的标准 CLI，父子环境摘要不一致时保持失败关闭。

测试制品保留在命令输出的临时目录中。依赖操作不强制离线，继续禁止安装脚本；不读取真实 `.npmrc`、凭据或加载未明确选择的用户插件。fake provider、模拟批准界面、真实 CLI/本机工具各自的验证层次须如实说明，不能据此宣称真实模型质量、用户桌面体验或费用改善。最新结果与实际运行环境见唯一实施台账。