Pi Agent Harness 中文技术文档¶

这套文档基于本地源码仓库 /Users/gitsilence/github/pi 分析生成，目标不是翻译官方文档，而是帮助开发者理解 Pi 当前代码里的优秀设计：它怎样把一个 coding agent 拆成模型适配、agent runtime、coding 产品层、终端 UI 和扩展系统；它怎样处理长上下文、会话树、工具调用、插件能力和无内置 MCP 的取舍。

仓库定位¶

Pi 是一个 TypeScript monorepo，核心包如下：

包	角色	关键源码
@earendil-works/pi-ai	统一多模型 API，把不同 provider 规约折叠成 Model + Context + streamSimple	packages/ai/src
@earendil-works/pi-agent-core	低层 agent runtime，负责消息循环、工具调用、事件流、队列	packages/agent/src
@earendil-works/pi-coding-agent	CLI/SDK/RPC 产品层，负责会话、扩展、内置工具、设置、压缩、项目资源	packages/coding-agent/src
@earendil-works/pi-tui	终端 UI 组件与交互渲染	packages/tui/src

推荐阅读顺序¶

1. 先读技术架构，建立整体分层。
2. 打开源码索引，用知识点快速定位 packages/.../file.ts:line。
3. 再读用户旅程，理解一次 prompt 如何穿过 CLI、资源、扩展、agent loop 和持久化。
4. 重点读 Agent Loop、Harness 设计、上下文压缩，这些是代码里最值得借鉴的核心。
5. 如果你想扩展 Pi，读工具系统、插件与扩展、MCP 与集成取舍。
6. 如果你关心模型适配，读模型与 Provider。

源码阅读地图¶

packages/ai/src
  stream.ts, types.ts, api-registry.ts, providers/*

packages/agent/src
  agent-loop.ts, agent.ts, types.ts
  harness/agent-harness.ts
  harness/session/*
  harness/compaction/*

packages/coding-agent/src/core
  sdk.ts, agent-session.ts, agent-session-runtime.ts
  session-manager.ts, resource-loader.ts
  extensions/*, tools/*, compaction/*

packages/coding-agent/src/modes
  interactive/*
  rpc/*

文档原则¶

本文档会尽量从“为什么这样设计”出发，而不是逐行解释源码。每一章都列出可对照的源码路径，便于继续深入。

所有核心知识点的具体文件和行号集中维护在源码索引。