拆开 Pi：谁拥有下一次模型调用？

一个基于 Pi 源码写成的中文技术小册网页，解释一次 Agent 运行中，prompt、工具批次、steer、follow-up 与 agent_settled 如何交接控制权。

线上版本：pi-turn-ownership-handbook.q835041058.chatgpt.site

内容基线

• 上游项目：earendil-works/pi
• 源码版本：Pi v0.83.0
• 核对 commit：a96fb984d8c8b065fc5d193309fc812a882adee0
• 核对日期：2026-08-04

网页将 “Turn Ownership” 作为解释源码行为的框架；它不是 Pi 源码中的正式术语，也不是 Pi 的官方文档。

页面内容

• 区分 Agent run、Turn、Tool batch 与 Session settled。
• 解释同一个 Agent 的 single-flight activeRun 约束。
• 对比 steer 与 follow-up 的读取时机。
• 说明并行工具完成顺序与 transcript 写入顺序的区别。
• 解释为什么 agent_end 不等于业务层已经空闲。
• 单独标注仍在演进的 AgentHarness，不与当前 CLI 主路径混写。

每个关键结论都附有固定 commit 的源码链接、行号和简化代码片段。

设计

页面参考了《你按下回车后，谁接管这次任务》的技术小册阅读方式，并针对 Pi 重新组织内容与视觉：

• 桌面端三栏：全书目录、纸张式正文、本章目录。
• 平板和手机端使用响应式目录抽屉。
• 暖色纸张、宋体正文、暗红源码证据色。
• 支持阅读进度、深色模式和代码复制。

本地运行

需要 Node.js >=22.13.0。

npm ci
npm run dev

默认开发地址为 http://localhost:3000。

验证

npm run build
node --test tests/rendered-html.test.mjs

也可以运行完整测试命令：

npm test

主要文件

• app/page.tsx：小册内容、导航和交互。
• app/globals.css：阅读器布局、视觉 token 与响应式样式。
• app/layout.tsx：页面元数据。
• tests/rendered-html.test.mjs：服务端渲染验证。

发布

项目使用 vinext 构建 Cloudflare Workers 兼容产物，并通过 OpenAI Sites 私有发布。站点绑定保存在 .openai/hosting.json。