29 开发

从源码构建与测试 pi，涵盖 fork 品牌重塑、路径解析与项目结构。

更多准则请参阅 AGENTS.md。

环境搭建

git clone https://github.com/earendil-works/pi
cd pi
npm install
npm run build

从源码运行：

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

该脚本可以在任意目录下运行。Pi 会保留调用者当前的工作目录。

实验性远程测试框架

远程测试框架（remote harness）的服务器/客户端集成仅用于开发。在仓库中运行：

PI_EXPERIMENTAL=1 ./pi-test.sh server
PI_EXPERIMENTAL=1 ./pi-test.sh client

PI_SERVER_DIR 覆盖服务器配置档案和套接字目录（默认为 ~/.pi/server）。当未指定 --server-id 时，PI_SERVER_ID 用于选择逻辑服务器 ID。

client 和 experimental/plugin 包子路径只在源码检出中且 source 条件下才能解析。它们的实现以及 server/client 命令不会包含在 npm 包和独立二进制文件中。pi-client、pi-protocol 和 pi-server 是 coding-agent 的开发依赖，而非运行时依赖。本地 SDK 和 stdio RPC API 保持不变。

Fork 与品牌重塑

通过 package.json 配置：

{
  "piConfig": {
    "name": "pi",
    "configDir": ".pi"
  }
}

在你的 fork 中修改 name、configDir 和 bin 字段。这会影响 CLI 横幅、配置路径和环境变量名称。

路径解析

三种执行模式：npm 安装、独立二进制、从源码以 tsx 运行。

对于包内资源，始终使用 src/config.ts：

import { getPackageDir, getThemeDir } from "./config.js";

对于包内资源，切勿直接使用 __dirname。

调试命令

/debug（隐藏命令）会将以下内容写入 ~/.pi/agent/pi-debug.log：

渲染后的 TUI 行（含 ANSI 码）
最近发送给 LLM 的消息

测试

./test.sh                         # Run non-LLM tests (no API keys needed)
npm test                          # Run all tests
npm test -- test/specific.test.ts # Run specific test

已发布包冒烟测试

构建完成后，运行 npm run check:package-install。它会打包公开的各个包，并在仓库之外的临时目录中仅将 coding-agent 作为直接依赖安装。本地 tarball 会有选择地覆盖已声明的传递依赖，而不会安装仅用于开发的包。该检查验证 SDK 导入和 CLI 启动，不需要凭据，也不会发起模型请求。

npm run check 还会检查运行时依赖声明，并拒绝通过导入将被排除的开发源码带进某个包的构建产物。

项目结构

packages/
  ai/           # LLM provider abstraction
  agent/        # Agent loop and message types  
  tui/          # Terminal UI components
  coding-agent/ # CLI and interactive mode