25  开发贡献

25.1 概述

Pi 是一个开源项目，欢迎社区参与贡献。本章介绍如何从源码构建 Pi、项目结构、调试方法以及如何参与开发。

无论是想提交 Bug 修复、添加新功能，还是想 Fork Pi 打造自己的品牌，本章都能帮助你快速上手。

25.2 环境搭建

25.2.1 前置要求

  • Node.js（建议 LTS 版本）
  • npm（随 Node.js 一起安装）
  • Git

25.2.2 克隆与安装

# 克隆 pi-mono 单体仓库
git clone https://github.com/earendil-works/pi-mono
cd pi-mono

# 安装依赖
npm install

# 构建所有包
npm run build

Pi 采用 monorepo（单体仓库）结构，所有包都在同一个仓库中管理。npm install 会自动处理包之间的依赖关系，npm run build 会按依赖顺序构建所有子包。

Note

参见仓库根目录的 AGENTS.md 了解额外的开发指南和规范。

25.3 从源码运行

构建完成后，可以使用 pi-test.sh 脚本从源码运行 Pi：

/path/to/pi-mono/pi-test.sh

这个脚本可以在任何目录下运行。Pi 会使用调用者的当前工作目录作为会话的工作目录（cwd），这与通过 npm 全局安装后运行 pi 的行为一致。

Tip

开发时常见的 workflow 是：在一个终端窗口运行 npm run build（或使用 npm run build -- --watch 监听文件变化），然后在另一个终端使用 pi-test.sh 测试你的修改。

25.4 Forking 与 Rebranding

如果你想基于 Pi 创建自己的分支品牌（fork/rebrand），可以通过 package.json 中的 piConfig 字段进行配置：

{
  "name": "my-coding-agent",
  "bin": {
    "mycli": "./dist/cli.js"
  },
  "piConfig": {
    "name": "mycli",
    "configDir": ".mycli"
  }
}

可配置项：

字段 说明 影响
piConfig.name CLI 名称 影响 CLI 启动时的 Banner 显示、配置路径和环境变量名
piConfig.configDir 配置目录名 影响用户主目录下的配置路径（如 ~/.mycli/ 而非 ~/.pi/）
bin 可执行命令名 用户安装后在终端输入的命令名
Warning

修改 piConfig 后，需要确保环境变量前缀也相应调整。例如，将 name 改为 mycli 后，原来的 PI_API_KEY 可能变为 MYCLI_API_KEY。具体行为请测试确认。

25.5 路径解析

Pi 支持三种执行模式，每种模式下包资源的路径解析方式不同：

  1. npm 全局安装（npm install -g）
  2. 独立二进制文件（standalone binary）
  3. tsx 从源码运行（pi-test.sh）

为了正确处理这三种模式，Pi 使用 src/config.ts 中提供的工具函数来定位包资源：

// 正确方式：使用 config.ts 提供的工具函数
import { getPackageDir, getThemeDir } from "./config.js";

const packageDir = getPackageDir();
const themeDir = getThemeDir();
Warning

永远不要直接使用 __dirname 来定位包资源。__dirname 在三种执行模式下的行为不同，会导致路径解析错误。始终使用 src/config.ts 提供的工具函数。

25.6 Debug 命令

Pi 提供了一个隐藏的 /debug 命令，用于排查问题。执行后会将调试信息写入 ~/.pi/agent/pi-debug.log 文件，包括：

  • TUI 渲染数据：带 ANSI 颜色码的终端渲染行
  • 最近的 LLM 消息：最后一次发送给 LLM 的完整消息内容

使用方法：在 Pi 交互模式下输入 /debug，然后查看日志文件：

# 执行 /debug 后查看日志
cat ~/.pi/agent/pi-debug.log

# 或实时跟踪日志
tail -f ~/.pi/agent/pi-debug.log
Tip

当你遇到 TUI 显示异常或 LLM 响应不符合预期时，/debug 是排查问题的第一工具。

25.7 测试

Pi 包含两类测试：

# 运行非 LLM 测试（无需 API Key，适合 CI/CD）
./test.sh

# 运行所有测试（包括需要真实 LLM API 调用的测试）
npm test

# 运行特定测试文件
npm test -- test/specific.test.ts
命令 说明 需要 API Key
./test.sh 非 LLM 测试（单元测试、集成测试） ❌
npm test 全部测试（含 LLM 调用测试） ✅
npm test -- test/xxx.test.ts 指定测试文件 取决于测试内容
Note

运行 npm test 前，确保已设置相应的环境变量（如 ANTHROPIC_API_KEY）或已通过 /login 认证。LLM 测试会产生实际的 API 调用费用。

25.8 项目结构

Pi monorepo 采用分层的包结构设计，每个包有清晰的职责边界：

packages/
├── ai/            # LLM 提供商抽象层
├── agent/         # Agent 循环和消息类型
├── tui/           # 终端 UI 组件
└── coding-agent/  # CLI 和交互模式

25.8.1 packages/ai — LLM 抽象层

封装与各种 LLM 提供商（Anthropic、OpenAI、Google 等）的通信逻辑。定义了基础消息类型（UserMessage、AssistantMessage、ToolResultMessage）和 Usage 统计结构。

25.8.2 packages/agent — Agent 核心循环

实现 Agent 的核心循环逻辑：接收用户输入 → 调用 LLM → 执行工具 → 返回结果。定义了 AgentMessage 联合类型。

25.8.3 packages/tui — 终端 UI 组件

提供终端用户界面的渲染组件，包括输入框、消息列表、树导航视图、主题支持等。这些组件可以被扩展（Extensions）复用来构建自定义 UI。

25.8.4 packages/coding-agent — CLI 与交互模式

Pi 的最上层包，整合 ai、agent 和 tui 包，提供完整的命令行工具和交互式编程体验。包含会话管理（SessionManager）、扩展系统、Skills、Prompt 模板、主题等核心功能。

Tip

理解包之间的依赖关系有助于快速定位问题来源： - LLM 调用问题 → 查看 packages/ai - Agent 行为/工具执行问题 → 查看 packages/agent - 终端显示/UI 问题 → 查看 packages/tui - CLI/扩展/会话问题 → 查看 packages/coding-agent

25.9 参与贡献

Pi 是一个活跃的开源项目，欢迎各种形式的贡献：

  • Bug 报告：在 GitHub Issues 中提交
  • 功能建议：先在 Discord 中讨论，再提交 PR
  • 代码贡献：Fork 仓库 → 创建分支 → 提交 PR
  • 文档改进：直接编辑对应文档文件并提交 PR
Note

提交代码前，请务必运行 ./test.sh 确保所有非 LLM 测试通过。如果修改了 LLM 相关逻辑，请同时运行 npm test 确认完整测试通过。