图解 Pi AgentPi Agent, Illustratedv1.1.0
包Packages
演示Slides

路线图与变更日志Roadmap & changelogPi Agent, Illustrated · Pi v1.1.0

站点如何组织、每个包的进度、下一步计划，以及 Pi v1.1.0 相对上一版本的变化。How the site is organised, where each package stands, what comes next, and what changed in Pi v1.1.0.

01Roadmap

站点规划Site plan#

一句话结论Takeaway信息架构 = 一个总览页 + 每个包一个子页面，全部使用同一个包模板。计划已完成：全部 14 个包都已深挖（9 项模板齐全、各有 10 页演示），全站 125 张图。Information architecture = one overview page + one page per package, all following the same package template. The plan is complete: all 14 packages are fully covered (all nine template parts, a 10-slide deck each), 125 diagrams site-wide.

包Packagenpm状态Status定位Role
agent-core@earendil-works/pi-agent-core已完成Done通用 Agent：状态、事件循环、工具执行与钩子General-purpose agent with transport abstraction, state management, and attachment support
pi-ai@earendil-works/pi-ai已完成Done统一的 LLM API：模型目录、认证、42 个 provider、事件流Unified LLM API with automatic model discovery and provider configuration
coding-agent@earendil-works/pi-coding-agent已完成Done编码智能体 CLI：工具、会话树、压缩、扩展与运行模式Coding agent CLI with read, bash, edit, write tools and session management
tui@earendil-works/pi-tui已完成Done差分渲染的终端 UI 库Terminal User Interface library with differential rendering for efficient text-based applications
mcp@earendil-works/pi-mcp已完成Done独立的 Model Context Protocol 客户端Standalone Model Context Protocol client for pi and other applications
codemode@earendil-works/pi-codemode已完成Done沙箱化 JavaScript 执行：唯一能力是调用注入的工具Sandboxed JavaScript execution where the only capability is calling injected tools
telemetry@earendil-works/pi-telemetry已完成Done与厂商无关的遥测契约与类型化 schema 工具Vendor-neutral telemetry contracts and typed schema utilities for pi
chord@earendil-works/chord已完成Done应用组合运行时：服务、复制状态、RPC 与插件Application composition runtime for services, replicated state, RPC, and plugins
durable@earendil-works/pi-durable已完成Done持久化的会话、任务与文档运行时Durable conversation, task, and document runtime for Pi
env@earendil-works/pi-env已完成DonePi Durable 的远程执行环境（经 SSH 部署的小型守护进程）Remote execution environments for Pi Durable: a small daemon deployed over SSH and its ExecutionEnv client
protocol@earendil-works/pi-protocol已完成Done远程 pi 会话的传输无关 CBOR 协议Transport-neutral CBOR protocol for remote pi sessions
client@earendil-works/pi-client已完成Done基于分帧 CBOR 的远程 pi 会话客户端Transport-neutral client for remote pi sessions over framed CBOR bytes
server@earendil-works/pi-server已完成Done实验性的 pi 服务端experimental server package for pi
evals@earendil-works/pi-evals已完成Done私有包：行为评测与成对的文档提升对比（Docker 隔离）Private package: behavioural evals and paired documentation-lift comparisons (Docker-isolated)
02Roadmap

包模板Package template#

每个包页面按以下 9 项组织；完成的包页面全部覆盖，占位页显示进度。Every package page is organised by these nine parts; finished pages cover all of them, placeholders show progress.

  • 概览Overview定位、依赖、规模、一句话结论role, deps, size, one-line takeaway
  • 公共 APIPublic API导出路径与导出符号（逐行链接）export paths and exported symbols (line-linked)
  • 内部架构图Internal architecture模块 / 文件之间的结构structure between modules and files
  • 关键流程Key flows时序、状态机、数据流sequences, state machines, data flow
  • 数据类型Data types核心接口与它们的关系core interfaces and how they relate
  • 扩展点Extension points宿主可以替换或注入的地方where a host can plug in or replace behaviour
  • 关键文件Key files链接到 v1.1.0 的具体行links to exact lines at v1.1.0
  • 测试Tests测试文件与用例数test files and case counts
  • 交叉链接Cross-links相关包与相关章节related packages and sections
03Roadmap

下一步Next steps#

  1. 计划已完成Plan complete — 8 批之后，全部 14 个包都已按同一模板完成深挖：125 张手绘图（第一版 12 张 + 新增 113 张），14 套包演示文稿。没有剩余的批次；之后的工作是随新版本更新。After eight batches all 14 packages are covered with the same template: 125 hand-laid diagrams (12 from the first edition + 113 new), and 14 package decks. No batches remain; future work is keeping up with new releases.
04Changelog

本版站点变更What changed in this edition#

本次更新：telemetry 与 evals 完成（第 8 批），全部 14 个包完成This update: telemetry and evals done (batch 8) — all 14 packages covered

  • telemetry 深挖：新增 8 张图（契约与两个参考上下文、span 模型、一次 startSpan()、适配器契约与 9 个一致性用例、InMemoryTelemetryContext、可序列化 schema、类型化启动器、在 pi 中的使用）。telemetry deep dive: 8 new diagrams (the contract and two reference contexts, the span model, one startSpan(), the adapter contract and its 9 conformance cases, InMemoryTelemetryContext, serializable schemas, typed starters, how pi uses it).
  • evals 深挖：新增 8 张图（三个目录、7 个评测、一次 eval:docs、任务计划、Dockerfile 的 5 个阶段、三层沙箱、一次 harness 运行、报告与一个按 report.ts 规则算出的 report.txt）。evals deep dive: 8 new diagrams (three directories, the seven evals, one eval:docs run, the task plan, the five Dockerfile stages, the three-layer sandbox, one harness run, the report with a report.txt computed by the report.ts rules).
  • 两个包各有 10 页的演示文稿；evals 是私有包、没有 exports，公共 API 一节改为 npm 脚本、参数与 src/ 各模块的逐行导出表。A 10-slide deck for each package; evals is private with no exports, so its public-API section lists the npm scripts, flags and line-linked exports of each src/ module.
  • 路线图计划完成：全部 14 个包已深挖，全站合计 125 张图。The roadmap plan is complete: all 14 packages covered, 125 diagrams site-wide.

上次更新：protocol、client 与 server 完成（第 7 批）Previous update: protocol, client and server done (batch 7)

  • protocol 深挖：新增 8 张图（三层结构、一条消息的往返、8 种消息、RpcTarget 路由、一条连接上的消息顺序、分帧、严格的 CBOR 子集、与 chord 的分界）。protocol deep dive: 8 new diagrams (three layers, one message there and back, the 8 messages, RpcTarget routes, message order on one connection, framing, the strict CBOR subset, the boundary with chord).
  • client 深挖：新增 8 张图（模块、连接状态机、一个请求、服务订阅、附着与 Chord 适配器、字节传输与 Unix 写队列、本机发现、失败语义与恢复）。client deep dive: 8 new diagrams (modules, the connection state machine, one request, service subscriptions, attachments and the Chord adapter, byte transports and the Unix write queue, local discovery, failure semantics and recovery).
  • server 深挖：新增 8 张图（模块、ServerHost 契约、连接阶段与握手、请求处理、SessionRouter、附着的释放、Unix 监听器、错误码与测试工具）。server deep dive: 8 new diagrams (modules, the ServerHost contract, connection stages and the handshake, request handling, SessionRouter, attachment release, the Unix listener, error codes and the testing kit).
  • 三个包各有 10 页的演示文稿；protocol 与 server 的根入口用 export *，公共 API 表改为展开到声明所在的模块并逐行链接；当时全站合计 109 张图。A 10-slide deck for each package; protocol and server use export * at the root, so their public-API tables expand to the declaring modules with line links; 109 diagrams site-wide at the time.
  • telemetry 与 evals 顺延到第 8 批。telemetry and evals move to batch 8.

更早：chord、durable 与 env 完成（第 6 批）Earlier: chord, durable and env done (batch 6)

  • chord 深挖：新增 8 张图（模块、facet 生命周期、热重载、服务、远程服务、复制状态、增量与草稿、打包与加载）。chord deep dive: 8 new diagrams (modules, the facet lifecycle, hot reload, services, remote services, replicated state, deltas and drafts, bundling and loading).
  • durable 深挖：新增 8 张图（模块、数据模型、一次运行、任务、收件箱、文档、存储、扩展）。durable deep dive: 8 new diagrams (modules, the data model, one run, tasks, the inbox, documents, storage, extensions).
  • env 深挖：新增 8 张图（模块、TypeScript 与 Rust 的分工、SSH 部署、帧格式、一次连接、命令执行、文件操作、文件监视）。env deep dive: 8 new diagrams (modules, the TypeScript / Rust split, SSH deployment, the frame format, one connection, command execution, file operations, file watching).
  • 三个包各有 10 页的演示文稿，公共 API 表按 index.ts 的导出自动生成；当时全站合计 85 张图。A 10-slide deck for each package and public-API tables generated from the index.ts exports; 85 diagrams site-wide at the time.

更早：mcp 与 codemode 完成（第 5 批）Earlier: mcp and codemode done (batch 5)

  • mcp 深挖：新增 8 张图（模块、连接生命周期与握手、请求与分页、stdio 传输、Streamable HTTP、OAuth、结果内容与错误、在 pi 中的使用）。mcp deep dive: 8 new diagrams (modules, connection lifecycle and handshake, requests and paging, the stdio transport, Streamable HTTP, OAuth, result content and errors, how pi uses it).
  • codemode 深挖：新增 8 张图（模块、三层隔离、一次执行、工具调用往返、脚本 API 与限额、类型与源码格式、TypeScript 声明、在 pi 中的使用）。codemode deep dive: 8 new diagrams (modules, three layers of isolation, one execution, the tool-call round trip, the script API and limits, types and the source format, TypeScript declarations, how pi uses it).
  • 两个包各有 10 页的演示文稿。A 10-slide deck for each package.
  • 演示文稿：较高的图（如 tui 的差分渲染、coding-agent 的会话装配与 JSONL 格式）改用“左文右图”版式，显示得更大。Decks: tall diagrams (such as tui differential rendering, coding-agent session wiring and the JSONL format) now use a text-beside-diagram layout and render larger.
  • telemetry 按路线图留在第 7 批。telemetry stays in batch 7, as planned.

更早：coding-agent 与 tui 完成Earlier: coding-agent and tui done

  • coding-agent 深挖：新增 9 张图（模块、CLI 启动、AgentSession 装配、会话替换、内置工具、JSONL 格式、扩展 API、RPC 协议、设置与资源），并保留第一版的 4 节coding-agent deep dive: 9 new diagrams (modules, CLI start-up, AgentSession wiring, session replacement, built-in tools, the JSONL format, the extension API, the RPC protocol, settings and resources), keeping the four first-edition sections.
  • tui 深挖：新增 8 张图（模块、组件模型、差分渲染、两种屏幕、输入与按键、编辑器与补全、覆盖层、终端能力）。tui deep dive: 8 new diagrams (modules, the component model, differential rendering, the two screens, input and keys, the editor and autocomplete, overlays, terminal capabilities).
  • 两个包各有 10 页的演示文稿；两个包的公共 API 表按 index.ts 的导出自动生成。A 10-slide deck for each package; both public-API tables are generated from the index.ts exports.
  • 修复：中文幻灯片页脚显示英文站名。Fix: Chinese slides showed the English site name in the footer.

信息架构Information architecture

  • 单页 → 总览 + 14 个包子页面 + 路线图；全站顶部导航带包切换器，子页面有面包屑。Single page → overview + 14 package pages + roadmap; a global top nav with a package switcher, breadcrumbs on sub-pages.
  • 第一版 12 节全部保留：4 节留在总览，8 节迁到所属包页面；旧锚点自动跳转。All 12 first-edition sections kept: 4 stay on the overview, 8 moved to their package pages; old anchors redirect.

新内容New content

  • agent-core 与 pi-ai 深挖：新增 16 张手绘图（当时合计 28 张），公共 API、扩展点、测试与交叉链接。agent-core and pi-ai deep dives: 16 new hand-laid diagrams (28 in total at the time), plus public API, extension points, tests and cross-links.
  • 两个包各自的演示文稿；12 个包的自动占位页。A slide deck for each of the two packages; generated placeholder pages for 12 packages.

源码版本Source version

  • 分析对象从开发中的提交 4130bd5 改为发布标签 v1.1.0（abe508e，2026-10-07）；所有 GitHub 链接改为指向该标签，所有行号重新计算。The analysed source moved from the in-progress commit 4130bd5 to the release tag v1.1.0 (abe508e, 2026-10-07); every GitHub link now targets the tag and every line number was recomputed.
  • 构建时断言：所有 14 个包的 package.json 版本均为 1.1.0；12 项核心计数（provider、API、事件、RPC 命令等）在标签上与第一版一致。Build-time assertions: all 14 package.json versions are 1.1.0; the 12 core counts (providers, APIs, events, RPC commands …) are unchanged at the tag.

名称Name

  • 站点更名为“图解 Pi Agent”。The site is now called “Pi Agent, Illustrated”.
05Changelog

Pi 1.1.0 变更日志Pi 1.1.0 changelog#

Pi v1.1.0 发布于 2026-10-07。以下摘自各包 CHANGELOG.md 的 [1.1.0] 段（原文为英文，每类最多显示 4 条）。合计：Added 29 · Changed 5 · Breaking Changes 4 · Fixed 35 · New Features 5。Pi v1.1.0 was released on 2026-10-07. Excerpts from each package's CHANGELOG.md [1.1.0] section (at most four per category). Totals: Added 29 · Changed 5 · Breaking Changes 4 · Fixed 35 · New Features 5.

agent-core已完成DoneAdded 1Changed 1

Added · 1

  • Added durationMs to tool result messages, AgentToolCallOutcome, and tool_execution_end events: how long execute() took, measured with a monotonic clock and excluding hooks. Calls that did not run have …

Changed · 1

  • streamProxy() returns an AssistantMessageEventStream, so proxied responses get durationMs like direct ones

CHANGELOG.md · [1.1.0] · 2026-10-07L3

pi-ai已完成DoneBreaking Changes 1Added 6Changed 1Fixed 10

Breaking Changes · 1

  • A stream function must return an AssistantMessageEventStream, for example from createAssistantMessageEventStream(); a hand-written EventStream<AssistantMessageEvent, AssistantMessage> subclass no longer …

Added · 6

  • Added durationMs to AssistantMessage: AssistantMessageEventStream measures each response with a monotonic clock from the start of the request to its final message, for every API implementation, including …
  • Added an optional durationMs to ToolResultMessage for the execution time of the tool
  • Added the openai-decisions classifier API for OpenAI's Decisions API, with gpt-6-luna as a classifier model of the openai provider. It needs an API key, so it is not listed as available while openai …
  • Added Claude Haiku 5.5 (claude-haiku-5-5) to the anthropic provider with its prompt-length pricing tier, adaptive thinking with xhigh/max effort, per-message effort, and mid-conversation system …
  • …

Changed · 1

  • The faux provider's prompt-cache usage estimate compares the previous and current prompt message by message and compares characters only from the first differing message; the usage numbers are unchanged.

Fixed · 10

  • Fixed server_busy and servers are currently busy provider errors ending the turn instead of being retried
  • Fixed the error message of a failed lazy API setup, such as a module load or auth failure, using its failure time as timestamp instead of the request start
  • Reduced context-limit request failures by estimating input at 3.5 characters per token instead of 4 when calculating output limits
  • Fixed Radius models disabled by an organization owner still being listed: a fetched or cached Radius catalog now replaces the shipped default catalog instead of being merged into it
  • …

CHANGELOG.md · [1.1.0] · 2026-10-07L3

coding-agent已完成DoneNew Features 5Added 9Changed 2Fixed 22

Added · 9

  • Added +name and -name entries to --tools, which change the default tool selection instead of replacing it, for example pi -t +codemode
  • Added durationMs to the tool render context and to tool_execution_end extension events: the recorded execution time of a final tool result
  • Added outputPad to the tool render context (#10557 by @rwachtler)
  • Added OpenAI's GPT-6 Luna as a classifier model through the Decisions API, available with OPENAI_API_KEY (see Use classifier models)
  • …

Changed · 2

  • Changed outputPad to also apply to ! command output, tool output, and summary blocks (#9946, #10557 by @rwachtler)
  • Changed pi mcp login --timeout to limit the whole sign-in, including requests to the authorization server, instead of only the wait for the browser

Fixed · 22

  • Fixed bash and PowerShell results losing Took after reloading a session, and the live Took including wall-clock steps; both now show the recorded execution time
  • Fixed managed installs keeping every old release; pi update now keeps only the new release and the one it updated from (#10392, #10511 by @davidbrai)
  • Fixed standalone binaries loading .env, .env.local, and .env.development from the launch directory into Pi's environment
  • Fixed !! command headers losing their dim color once output arrives (#10557 by @rwachtler)
  • …

CHANGELOG.md · [1.1.0] · 2026-10-07L3

tui已完成DoneBreaking Changes 1Added 3Fixed 1

Breaking Changes · 1

  • Terminal implementations must provide setProgramStatus(status); a terminal without OSC 7501 support can implement it as a no-op

Added · 3

  • Added Box.setPaddingX(...) and Text.setPaddingX(...) (#10557 by @rwachtler)
  • Added Terminal.setProgramStatus() and formatProgramStatus() for the Program Status Protocol (OSC 7501). ProcessTerminal asks the terminal for support at startup and sends reports only if it answers; …
  • Added TuiAltScreen.resetTextSelection(), which drops the text selection and multi-click state, for example before a host replaces the transcript (#9311, #10567 by @christianklotz)

Fixed · 1

  • Fixed Markdown links not being clickable in Herdr: TERM_PROGRAM=herdr is now detected as supporting OSC 8 hyperlinks

CHANGELOG.md · [1.1.0] · 2026-10-07L3

mcp已完成DoneAdded 1Fixed 1

Added · 1

  • Added a signal option to authorizeMcp(), registerClient(), the token request functions, and the discovery functions, which aborts their requests. An aborted refresh no longer falls back to a new …

Fixed · 1

  • Fixed StreamableHttpTransport.close() calling AuthProvider.token(), which could refresh tokens over the network before the session DELETE and delay closing; the DELETE now reuses the token of the last …

CHANGELOG.md · [1.1.0] · 2026-10-07L3

codemode已完成DoneAdded 1

Added · 1

  • Added console: true to text output items produced by console.*, so hosts can tell them apart from text() output

CHANGELOG.md · [1.1.0] · 2026-10-07L3

telemetry已完成Done

该版本没有单独的条目。No entries of its own in this release.

CHANGELOG.md · [1.1.0] · 2026-10-07L3

chord · 没有 CHANGELOG.mdno CHANGELOG.md
durable已完成DoneBreaking Changes 2Added 8Changed 1Fixed 1

Breaking Changes · 2

  • Storage implementations must honor the new order field of ConversationQuery, EntryQuery, TaskQuery, and SubmissionQuery, and continue a cursor in the order it was returned with. A storage that …
  • TaskRuntime.context() takes the cutoff as an options object, matching Conversation.context(): runtime.context(conversationId, context, { at }) replaces runtime.context(conversationId, context, at).

Added · 8

  • ToolExecutionApi.models and HookApi.models: the Harness's models, so tools and hooks can resolve models and make requests with the same catalog, credentials, and request transforms as generation.
  • Conversation.context(context, { at }) returns the model context as of a visible earlier entry, the same view fork(at) would start with, without creating a conversation.
  • ScanOrder (ascending or descending) as order on conversation, entry, task, and submission scans, including Tx.scanTasks() and Conversation.entries(), so hosts can page the newest tasks first. …
  • Task records carry startedAt and endedAt, wall-clock times the Session stamps at the first change to running and at the change to terminal, with HarnessOptions.now or the new createSession(storage, …
  • …

Changed · 1

  • runtime.context() keeps each conversation's last read range and derived view in memory: a later read by any of its tasks with the same head marker scans and derives only the entries committed since. A …

Fixed · 1

  • A conversation's first system message, and the baseline after a compaction or reset, now leads the model context instead of following the input that started the run. Providers with native mid-conversation tool …

CHANGELOG.md · [1.1.0] · 2026-10-07L3

env已完成Done

该版本没有单独的条目。No entries of its own in this release.

CHANGELOG.md · [1.1.0] · 2026-10-07L3

protocol已完成Done

该版本没有单独的条目。No entries of its own in this release.

CHANGELOG.md · [1.1.0] · 2026-10-07L3

client已完成Done

该版本没有单独的条目。No entries of its own in this release.

CHANGELOG.md · [1.1.0] · 2026-10-07L3

server已完成Done

该版本没有单独的条目。No entries of its own in this release.

CHANGELOG.md · [1.1.0] · 2026-10-07L3

evals · 没有 CHANGELOG.mdno CHANGELOG.md