@xicode/pi-delivery

面向 Pi coding agent 的事后交付插件。它不向主 agent 注册常规交付工具，也不在主模型 上下文中注入交付协议。

当一次存在待处理仓库改动的 agent run 完全 settled 后，插件使用当前会话模型做一次隔离判断：当前只是探索、 澄清、实现、修订、等待用户或阻塞，还是整个任务已经真正进入 Final Answer。Final 时还会区分 “需要交付到当前代码仓库”和“日常事务、只读分析或用户明确无需提交”。非 Final 与无需仓库交付时 静默结束；只有 Final 且需要仓库交付时才进行第二次隔离调用，生成变更文件摘要、commit message、Verify 和 PR 标题； 文件状态、原路径、分支、工作区警告和固定章节 PR 正文由程序生成，再按配置执行 Git/GitHub Actions，并在正常 Final Answer 后显示独立的 Pi TUI Delivery 卡片。

安装

pi install npm:@xicode/pi-delivery

安装后重启 Pi 或执行 /reload。默认 prepare，不会写入 Git。

配置

{
  "enabled": true,
  "mode": "prepare",
  "debug": false,
  "deliver": {
    "level": "commit"
  }
}

字段	取值	默认	说明
enabled	true | false	true	是否启用；关闭后不调用 post-run 模型，也不执行 Git/GitHub 操作
mode	prepare | deliver	prepare	prepare 只生成建议；deliver 自动执行
debug	true | false	false	显示每次 post-run 判断的阶段、结构化响应与校验诊断
deliver.level	commit | push | pr	commit	依次增加本地提交、推送、创建或更新 Ready PR

配置优先级：用户级 ~/.pi/agent/delivery.json < 受信任项目的 .pi/delivery.json < /delivery ... 写入的 session 覆盖。JSON Schema 位于 schemas/config.schema.json。该文件只描述插件配置，模型的 结构化输出由运行时 Tool Schema 约束。

命令

命令	用途
/delivery、/delivery status	查看生效配置与 Git/GitHub 诊断
/delivery on、/delivery off	开启或关闭当前 session 的插件
/delivery mode prepare	只显示交付建议
/delivery mode deliver commit	自动创建安全分支并精确提交任务文件
/delivery mode deliver push	提交并推送
/delivery mode deliver pr	提交、推送并创建或更新 Ready PR
/delivery debug on、/delivery debug off	开启或关闭当前 session 的判断过程诊断
/delivery reset	清除 session 覆盖

运行方式

main agent run
  -> agent_settled
  -> disabled / non-Git / no pending repository changes: stop silently
  -> isolated Final assessment (current ctx.model)
       |- non-final: keep task state (debug off 时静默)
       |- final without repository delivery: no Delivery entry
       `- final with repository delivery (结论锁定)
            `- isolated Delivery generation
                 -> program-owned Git facts / branch / PR body
                 -> Verify / Git validation
                 -> prepare / commit / push / pr Actions
                 -> delivery.result custom entry
                 -> copy-safe Pi TUI card

两次隔离调用都复用当前分支和压缩后的有效会话上下文，并追加只读仓库证据。原始 diff 会保留用于核对原请求，但不能用于发现范围外新任务。提示与返回结果不会 写成普通 session message；delivery.result 是不参与后续 LLM 上下文的 custom entry。

Debug 默认关闭。开启后，每次普通用户请求对应的 agent run settled 都会显示一个独立的 delivery.debug TUI 条目，包括是否需要 Delivery、模型选择的 assessment 工具、完整结构化 响应、阶段与判断依据；校验失败时还会保留首次响应、修复响应和每次校验错误。展开后可查看 模型、耗时、可用工具、任务基线与当前脏路径。该条目同样不进入模型上下文，并沿用 copy-safe 渲染，不需要额外复制命令。

无 Git 仓库和没有待提交仓库改动的普通 run 不调用判断模型。存在仓库改动时，Finality 会结合 原请求判断它是否属于当前代码库成果，不能仅凭文件发生变化就要求提交。Finality 非 Final 必须 提供会话中可逐字核对的硬阻断；clarification / awaiting_user 还必须 说明用户必需动作与不存在安全默认值的原因。项目仍可改进、范围外小问题和可选建议都不能 阻止 Final。结构化响应校验失败时，修复轮会锁定首次选择的工具，不允许为了通过 Schema 而切换 Final/非 Final 结论。

内部规则分别位于 internal-skills/final-assessment/SKILL.md 与 internal-skills/delivery-generation/SKILL.md，由插件直接读取，不通过 pi.skills 或 resources_discover 暴露给主 agent。Skill 不重复 JSON 模板；运行时 Tool Schema 是结构权威。

卡片与复制

卡片始终显示变更文件、分支、commit message、固定章节的 PR 正文和执行结果。展开模式 增加结构化 Verify、Final 判断原因、模型、耗时与恢复建议。

渲染器不使用会补齐 viewport 宽度的原生 Text，也不使用产生横向 padding 的 Box； 空白分隔行是零长度字符串，因此普通终端原生多行选择不会复制额外行首或行尾空格。

Actions 安全边界

• 只处理结构化结果中明确列出、属于当前仓库且确实处于变更状态的路径。
• 文件状态、重命名原路径与任务开始前既有改动警告由程序从 Git 事实生成，模型不负责填写。
• 自动 Actions 必须携带结构化 Verify：实际通过才可标记 passed；未执行时必须使用 not_applicable 并提供原因；failed 或 blocked 阻止所有 Git 写操作。
• 分支名由程序根据当前分支与提交类型生成；PR 正文由结构化摘要、文件、Verify、交接与范围 警告唯一组装；commit subject 长度由程序校验。
• 其他工作区/暂存区变更保持原状并显示警告。
• 默认分支上先创建有效的新分支；不会直接提交或推送默认分支。
• Git 调用参数化，不使用 force、reset 或 stash。
• push/pr 在任何写操作前完成远端与 GitHub 预检；不等待 CI、不合并 PR。
• 任一步骤失败立即停止，卡片准确展示已完成动作和恢复建议。

开发

pnpm --filter @xicode/pi-delivery typecheck
pnpm --filter @xicode/pi-delivery test
pnpm --filter @xicode/pi-delivery build