# go-pi

**Repository Path**: hristo/go-pi

## Basic Information

- **Project Name**: go-pi
- **Description**: A Go implementation of the Pi Agent from 
pi-mono

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-02
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pi — AI 编码助手（Go 实现）

一个用 Go 编写的快速、单二进制 AI 编码助手。pi 支持连接多个 LLM 提供商，执行工具（文件读写编辑、bash 命令、代码搜索），帮助你在终端中编写、重构和调试代码。

本项目最初受 [pi coding agent](https://github.com/badlogic/pi-mono)（来自 `pi-mono` monorepo）启发并作为 Go 重新实现起步，现已发展为独立项目，拥有自己的架构和功能。

## 功能特性

- **交互式 TUI** — 完整的终端界面，支持流式输出、可滚动的消息历史、键盘驱动输入
- **打印模式** — 单次响应模式，适合脚本和管道操作（`pi -p "解释这个函数"`）
- **8 个 LLM 提供商** — OpenAI、Anthropic、Google Gemini、DeepSeek、Groq、Mistral、xAI、OpenRouter（25+ 模型）
- **7 个内置工具** — `read`、`write`、`edit`、`bash`、`grep`、`find`、`ls`
- **会话管理** — 基于 JSONL 的会话持久化，支持恢复、分叉和继续
- **思考级别** — 可配置的推理深度（off、minimal、low、medium、high、xhigh）
- **单二进制** — 10 MB 静态二进制，无运行时依赖

## 安装

### 从源码构建

需要 Go 1.24+。

```bash
git clone https://github.com/zhangheli/go-pi.git
cd go-pi
go build -o pi ./cmd/pi
```

将二进制文件移到 PATH 中：

```bash
mv pi /usr/local/bin/
```

### 预编译二进制

从 release 页面下载最新版本（即将推出）。

## 快速开始

```bash
# 设置所选提供商的 API Key
export OPENAI_API_KEY=sk-...

# 交互式 TUI 模式
pi

# 打印模式（单次响应）
pi -p "这段代码是做什么的？"

# 指定模型
pi --model claude-sonnet-4-20250514 "重构这个函数"

# 从 stdin 管道输入
cat main.go | pi -p "审查这段代码"

# 继续上次的会话
pi -c
```

## 配置

### API Key

为所选提供商设置环境变量：

| 提供商     | 环境变量                              |
|------------|---------------------------------------|
| OpenAI     | `OPENAI_API_KEY`                      |
| Anthropic  | `ANTHROPIC_API_KEY`                   |
| Gemini     | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`  |
| DeepSeek   | `DEEPSEEK_API_KEY`                    |
| Groq       | `GROQ_API_KEY`                        |
| Mistral    | `MISTRAL_API_KEY`                     |
| xAI        | `XAI_API_KEY`                         |
| OpenRouter | `OPENROUTER_API_KEY`                  |

或者在 agent 目录（默认 `~/.pi/agent/`）中创建 `auth.json` 文件：

```json
{
  "credentials": {
    "openai": { "type": "api_key", "value": "sk-..." },
    "anthropic": { "type": "api_key", "value": "sk-ant-..." }
  }
}
```

### 设置

创建 `~/.pi/agent/settings.json` 设置默认值：

```json
{
  "defaultProvider": "openai",
  "defaultModel": "gpt-4o",
  "defaultThinkingLevel": "medium",
  "theme": "dark"
}
```

### 自定义 Base URL

覆盖任意提供商的 API 端点：

| 提供商     | 环境变量              |
|------------|-----------------------|
| OpenAI     | `OPENAI_BASE_URL`     |
| Anthropic  | `ANTHROPIC_BASE_URL`  |
| Gemini     | `GEMINI_BASE_URL`     |

可用于代理服务器、本地模型（如 Ollama）或企业端点。

## CLI 参考

```
pi [OPTIONS] [MESSAGE]

选项：
  -h, --help                  显示帮助
  -v, --version               显示版本
  -p, --print                 打印模式（单次响应）
  --mode <text|json|rpc>      输出模式
  --provider <name>           LLM 提供商
  --model <id>                模型 ID
  --api-key <key>             API Key（覆盖环境变量）
  --thinking <level>          思考级别（off|minimal|low|medium|high|xhigh）
  -c, --continue              继续最近的会话
  -r, --resume                恢复会话（交互式选择器）
  --session <id>              打开指定会话
  --fork <id>                 分叉会话
  --no-session                不保存会话
  --session-dir <path>        会话目录
  --list-models [pattern]     列出可用模型
  -t, --tools <names>         工具白名单（逗号分隔）
  -nt, --no-tools             禁用所有工具
  -nbt, --no-builtin-tools    仅禁用内置工具
  --system-prompt <text>      覆盖系统提示
  --append-system-prompt <text> 追加系统提示
  --export <path>             导出会话为 HTML
  --offline                   离线模式
  --verbose                   详细输出
  --no-extensions             禁用扩展
  --no-skills                 禁用技能
  --no-context-files          禁用上下文文件
```

## 支持的模型

| 提供商     | 模型                                | API 格式            |
|------------|-------------------------------------|---------------------|
| OpenAI     | gpt-4o, gpt-4o-mini, o1, o3, o3-mini, o4-mini | OpenAI Chat Completions |
| Anthropic  | claude-sonnet-4, claude-haiku-4, claude-opus-4 | Anthropic Messages |
| Gemini     | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite | OpenAI 兼容 |
| DeepSeek   | deepseek-chat                       | OpenAI 兼容 |
| Groq       | llama-3.3-70b-versatile             | OpenAI 兼容 |
| Mistral    | mistral-large-latest                | OpenAI 兼容 |
| xAI        | grok-beta                           | OpenAI 兼容 |
| openrouter | 多种（通过 OpenRouter）              | OpenAI 兼容 |

## 架构

```
go-pi/
├── cmd/pi/main.go              # 入口、CLI 解析、模式路由
├── internal/
│   ├── agent/                  # 核心 agent 循环、模型注册表、类型定义
│   │   ├── loop.go             # RunLoop：LLM 流式调用 + 工具执行
│   │   ├── model_registry.go   # 提供商/模型注册和查找
│   │   ├── types.go            # Message、Tool、StreamEvent 类型
│   │   └── export.go           # 公共 API 导出
│   ├── auth/                   # API Key 管理（环境变量 + auth.json）
│   ├── cli/                    # CLI 参数解析和帮助文本
│   ├── config/                 # 版本、路径、agent 目录解析
│   ├── modes/
│   │   ├── interactive/        # TUI 模式：将 agent 循环与终端 UI 连接
│   │   └── print/              # 打印模式：单次流式响应
│   ├── providers/              # LLM 提供商实现
│   │   ├── openai/             # OpenAI Chat Completions（兼容提供商的基础）
│   │   ├── anthropic/          # Anthropic Messages API + SSE 解析
│   │   ├── gemini/             # Google Gemini（OpenAI 兼容端点）
│   │   ├── deepseek/           # DeepSeek（复用 openai.Stream）
│   │   ├── groq/               # Groq（复用 openai.Stream）
│   │   ├── mistral/            # Mistral（复用 openai.Stream）
│   │   ├── xai/                # xAI/Grok（复用 openai.Stream）
│   │   └── openrouter/         # OpenRouter（复用 openai.Stream）
│   ├── session/                # JSONL 会话持久化和生命周期管理
│   ├── settings/               # 用户设置（settings.json）
│   ├── tools/                  # 内置工具定义和执行器
│   └── tui/                    # 终端 UI（基于 tcell）
│       ├── tui.go              # 事件循环、布局、渲染
│       ├── message_view.go     # 可滚动的消息历史
│       ├── input.go            # 文本输入区域
│       └── footer.go           # 状态栏（模型、token、工作中指示器）
```

### Agent 循环

核心循环（`internal/agent/loop.go`）流程：

1. 通过流式调用将对话历史发送给 LLM
2. 累积助手的响应（文本 + 工具调用）
3. 如果存在工具调用，逐个执行并将结果追加到对话
4. 重复直到助手不再调用工具（最多 100 轮）

### 提供商抽象

所有提供商实现统一的 `StreamFn` 签名：

```go
type StreamFn func(ctx, model, messages, tools, opts) (<-chan StreamEvent, error)
```

OpenAI 兼容的提供商（DeepSeek、Groq、Mistral、xAI、OpenRouter）通过自定义 `BaseURL` 复用 `openai.Stream()`。Anthropic 和 Gemini 有各自的实现。

### 终端 UI

交互式终端 UI 基于 [tcell](https://github.com/gdamore/tcell)，包含：

- **消息视图** — 可滚动的对话历史，区分用户/助手/工具消息
- **输入区域** — 文本输入，Enter 发送，Ctrl+C 退出
- **底部状态栏** — 模型名称、提供商、token 用量、工作中指示器

## 键盘快捷键（交互模式）

| 按键      | 操作        |
|-----------|-------------|
| Enter     | 发送消息    |
| Ctrl+C    | 退出        |
| Escape    | 退出        |
| Ctrl+L    | 重绘屏幕    |
| PageUp    | 向上滚动    |
| PageDown  | 向下滚动    |

## 路线图

| 功能         | 状态   |
|--------------|--------|
| 交互式 TUI   | 已完成 |
| 打印模式     | 已完成 |
| 8 个提供商   | 已完成 |
| 7 个内置工具 | 已完成 |
| 会话管理     | 已完成 |
| 思考级别     | 已完成 |
| 扩展系统     | 计划中 |
| 上下文压缩   | 计划中 |
| RPC 模式     | 计划中 |

## 依赖

- [tcell](https://github.com/gdamore/tcell) — 终端 UI 库
- 仅使用标准库（net/http、encoding/json、os、sync 等）

## 许可证

MIT 许可证。详见 LICENSE 文件。