# 开发

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

---

LLMS 索引： [llms.txt](/llms.txt)

---

更多准则请参阅 [AGENTS.md](https://github.com/earendil-works/pi/blob/main/AGENTS.md)。

## 环境搭建 {#setup}

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

从源码运行：

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

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

### 实验性远程测试框架 {#experimental-remote-harness}

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

```bash
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 与品牌重塑 {#forking--rebranding}

通过 `package.json` 配置：

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

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

## 路径解析 {#path-resolution}

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

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

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

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

## 调试命令 {#debug-command}

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

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

## 测试 {#testing}

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

### 已发布包冒烟测试 {#published-package-smoke-test}

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

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

## 项目结构 {#project-structure}

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

---

反链：

- [环境变量](/book/pi/environment-variables/)