# pi-agent-go

**Repository Path**: lkq55421/pi-agent-go

## Basic Information

- **Project Name**: pi-agent-go
- **Description**: pi agent的go语言转换版本，并做了大量优化内容，性能比pi快了好几倍

- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 48
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# pi-go

**pi 编码代理的 Go 实现 —— 单一静态二进制，零 Node 依赖**

<p>对 <code>@earendil-works/pi-coding-agent</code>（TypeScript monorepo，约 1146 个源文件 / 23 万行）的忠实移植：<br>同等的交互式编码体验，原生并发的运行时，一个 exe 直接分发。</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Go](https://img.shields.io/badge/Go-1.25-00ADD8.svg)
![Binary](https://img.shields.io/badge/binary-~20MB-success.svg)
![Direct%20deps](https://img.shields.io/badge/direct%20deps-2-brightgreen.svg)
![Qihoo%20106](https://img.shields.io/badge/Qihoo_106-106%2F106%20PASS-8a2be2.svg)

[为什么是 Go](#-为什么是-go对比-pi-的优化点) · [实测对比](#-实测与-pi-的头对头数据) · [架构](#-架构) · [快速开始](#-快速开始) · [移植边界](#-移植边界诚实声明) · [PORTING.md](PORTING.md)

</div>

---

## 🎯 为什么是 Go——对比 pi 的优化点

pi 是一个优秀的 TypeScript 编码代理，但"交付一个 agent"意味着交付 Node 运行时 + npm 依赖树。pi-go 把这件事变成 `go build` 一次：

| 维度 | pi（TypeScript） | pi-go（Go） |
|---|---|---|
| **分发** | Node ≥ 22.19 运行时 + npm 安装 | **单一静态二进制（~20 MB）**，复制即用 |
| **平台覆盖** | 跟随 Node 支持 | Windows / Linux / macOS **交叉编译一等公民** |
| **运行时依赖** | Node 生态依赖树 | **直接依赖仅 2 个**：`golang.org/x/sys` + `modernc.org/sqlite`（纯 Go SQLite，无 CGO、无原生模块编译） |
| **并发模型** | JS 事件循环 | **goroutine 原生并发**：流式事件、RPC 连接、并行工具调用各归其位，契合 agent 的 IO 密集负载 |
| **错误拦截** | 运行时 + 测试兜底 | 静态类型 + `go build` / `go vet`，**一大类错误前置到编译期** |
| **CI / 容器** | 镜像需带 Node 层 | scratch 基础镜像塞一个二进制即可 |

移植不是重写：模块结构、协议、行为与原版逐包对应（见 [模块清单](#-模块清单)），保证两边可以同题对跑、互相验证。

## 📊 实测：与 pi 的头对头数据

数据来自 [harness-bench](../../deepseek-harness/harness-bench)（单变量对比基准：同任务、同模型 `deepseek-v4-flash`、同冻结快照，只换 harness）。Qihoo 106 任务全集：

| 指标 | pi | pi-go |
|---|---:|---:|
| **通过率** | 103 / 106（97.17%） | **106 / 106（100%）** |
| 平均耗时 | 125.7s | 128.4s（基本持平，+2.1%） |
| 通过任务中位耗时（103 个 pi-PASS 任务） | 103.3s | **83.6s（快 ~19%）** |
| 干净配对任务中位耗时比 | — | **0.60** |
| 更快的任务数 | — | 70 / 106 |

**三个关键用例，pi-go 全部修复**：

| 任务 | pi | pi-go |
|---|---|---|
| `qi-061-periodic-status-rollup` | ❌ 超时 | ✅ 通过（还快 12.8s） |
| `qi-104-async-ops-window-rollup` | ❌ 超时 | ✅ 通过（还快 269.1s） |
| `qi-011-code-debug` | ❌ 验证失败 | ✅ 通过（score 0.8725） |

诚实说明：平均耗时两边持平（个别长尾任务拉高 pi-go 总量），优势集中在中位耗时与稳定性上——**更少超时、更稳的通过率**。

## 🏗 架构

```
                        ┌─────────────────────────────┐
                        │   cmd/pi（单一静态二进制）     │
                        └──────────────┬──────────────┘
                                       │
             ┌─────────────────────────┼──────────────────────────┐
             ▼                         ▼                          ▼
      coding-agent               protocol / client / server     session-backends
      交互式 REPL · 主题          CBOR framing · codec            SQLite（纯 Go）
      slash 命令 · 扩展系统        RPC 传输与连接管理               归一化权威表 · 写租约
      模型选择 · JSONL 导入导出          │                         搜索 · 迁移 · JSONL 导入
             │                         │
             ▼                         │
      tui ── 差分渲染 · Markdown/LaTeX │  agent ── agent loop · 工具调用
      终端图片(Kitty/iTerm2)           │           队列与状态管理 · 截断降级
      像素画布 · 富组件                 │           skills · compaction · hooks
             │                         ▼
             │                  ai ── 多 provider 统一抽象
             │                  OpenAI / Anthropic / Google / Azure / Bedrock /
             │                  Cloudflare / Mistral / OpenRouter / GitHub Copilot …
             │                  浏览器/设备码 OAuth · SSE 与 AWS event-stream 解析
             └────────> telemetry（厂商无关契约 + 一致性套件）
```

- **扩展系统**：完整移植原版扩展生命周期（工具 / 命令 / shortcut / flag / provider / hook 注册，含 `before_request`、`transform_context` 等全部生命周期事件），外加 `llama.cpp` 本地模型扩展与 Hugging Face 模型检索。
- **多厂商接入**：模型目录由已发布的 `pi-ai` 生成，覆盖国产厂商（Zai / Moonshot / MiniMax / Qwen / 小米 / 蚂蚁 Ling 等）与主流国际 provider。

## 📦 模块清单

| Go 包 | 对应 npm 包 | 状态 | 内容 |
|---|---|---|---|
| `telemetry` | `telemetry` | ✅ 完成 | 厂商无关契约、no-op/内存参考实现、adapter 一致性套件 |
| `ai` | `ai` | ✅ 完成 | 多 provider 抽象与适配、OAuth（Copilot/OpenRouter/Codex/xAI/Kimi/Radius…）、SSE/AWS event-stream、JSON 修复解析 |
| `agent` | `agent` | ✅ 完成 | agent loop、工具调用（sequential/parallel）、消息队列、harness（bash/edit/read/write、skills、compaction、hooks） |
| `protocol` / `client` / `server` | 同名包 | ✅ 完成 | CBOR framing、codec、RPC 传输、会话快照、测试配对辅助 |
| `session-backends/sqlite` | `session-backends/sqlite-node` | ✅ 完成 | 纯 Go SQLite、归一化权威表（事务内写入）、分支缓存、写租约、搜索与迁移 |
| `tui` | `tui` | ✅ 完成 | 差分渲染、Markdown/LaTeX、终端图片与像素画布、编辑器与选择器组件 |
| `coding-agent` → `cmd/pi` | `coding-agent` | ✅ 核心完成 | 交互模式、扩展系统、主题、模型选择、会话管理（JSONL 导入导出/fork）、HTML 导出 |
| `evals` | `evals` | ✅ 完成 | canonical hash、artifact schema、harness table、对比汇总 |

规模：337 个 Go 文件（含 66 个测试文件）、约 6.7 万行——与原版 23 万行 TS 的对应关系及逐文件镜像进度见 [PORTING.md](PORTING.md)。

## 🚀 快速开始

```bash
# 检查与测试
go build ./...
go vet ./...
go test ./... -count=1

# 构建 CLI
go build -o pi ./cmd/pi
./pi --help
```

**交叉编译**（无 CGO，任意平台一条命令）：

```bash
GOOS=linux   GOARCH=amd64 go build -o pi-linux-amd64 ./cmd/pi
GOOS=darwin  GOARCH=arm64 go build -o pi-darwin-arm64 ./cmd/pi
GOOS=windows GOARCH=amd64 go build -o pi.exe ./cmd/pi
```

## 🧭 移植边界（诚实声明）

pi-go 的原则是**忠实移植 + 边界透明**，三件事说在前面：

1. **刻意差异**（Go 侧的等价实现，不是缺陷）：
   - 扩展加载：Go 无法执行 TS/jiti 模块，采用进程内 `ExtensionFactory` + 目录/清单发现，生命周期与原版等价
   - UTF-16 孤立代理字符：Go 无对应表示，按非法 UTF-8 字节移除
   - TUI 渲染：纯终端实现（ANSI 真彩半块像素 + Kitty/iTerm2 图片协议），不是原版 canvas 像素级语义
2. **尚未逐文件 100% 镜像**：`coding-agent` 的部分对话框/选择器组件、个别 provider 的 OAuth 流程仍在收敛中，逐项清单见 PORTING.md 的"仍未完全转换"一节
3. **会话存储增强**：SQLite 后端在移植中升级为归一化权威表（事务内直接写入，旧 mutation-log 库自动回填）——这是相对原版的一项工程改进

TypeScript → Go 的映射约定（错误处理、判别联合、泛型约束等）与逐模块迁移记录，见 **[PORTING.md](PORTING.md)**。

## License

[MIT](LICENSE)