使用Go又重写pi agent, 以前重写是为了复制openclaw,这次纯粹是为了它的小巧灵。 还专门为项目写了本书： https://t.co/QuYqXR4CZW https://t.co/jIiZhn79Q7

smallnest/pigo

Source: https://github.com/smallnest/pigo

pigo

使用 Go 复刻的 pi AI Agent —— 一个面向命令行的编码智能体，同时支持无头（headless）脚本模式与交互式 REPL。

pigo 可以读写文件、执行命令、检索代码、抓取网页，并借助大模型完成从“读懂需求“到“改好代码“的闭环。它兼容 OpenAI / Anthropic 等多种协议网关，支持会话续跑、项目信任、技能（Skills）、插件与包管理。

模块路径：github.com/smallnest/pigo · Go 1.27+

📖 配套电子书《用 Go 编写 pi Agent》：write_pi_agent_in_go.pdf

目录

• 特性一览
• 架构总览
• 安装与构建
• 快速开始
• 命令行参数
• 模型与 Provider
• 内置工具
• 运行模式
• 系统提示词组装
• 项目信任
• 技能 Skills
• 插件
• 包管理
• 发布release
• 目录与环境变量
• 安全说明

特性一览

• 两种模式：无头 -p 一次性执行（适合脚本 / CI），或直接进入交互式 REPL。
• 多 Provider：OpenRouter（默认）、本地 Ollama、NVIDIA NIM、Anthropic、任意 OpenAI 兼容端点。
• 内置工具集：read / write / edit / grep / find / bash / todo / webfetch。
• 会话续跑：--list-sessions / --resume / --continue，无头与 REPL 均可续跑。
• stream-json 输出：逐行 JSON 事件，首个事件携带 session_id，便于调用方关联。
• 系统提示词分层组装：base 指令 + 环境块 + AGENTS.md（general→specific）+ --append-system-prompt。
• 项目信任：副作用工具（bash/write/edit）在未信任目录需确认，--approve 一次性授权。
• 技能与插件：~/.agents/skills 下的 /slash 命令、~/.pigo/plugins 下的外部插件。
• 上下文自动压缩：接近上下文窗口上限时自动摘要，亦可 /compact 手动触发。
• 包管理：pigo install npm:<pkg> 安装 pi 生态的 extension / skill / prompt / theme。

架构总览

pigo 的运行时分层架构：请求路径从用户经 CLI、Agent 循环、Provider 层直达 LLM 网关；工具路径从循环经工具执行器与信任闸门抵达本地环境；辅以会话存储与上下文压缩，并标注信任边界与外部网络边界。

更多分层图解（事件骨架、统一 Provider、工具批量执行、子 Agent 委派等）见配套电子书。

Agent 两层循环

运行时的核心是 internal/runtime/loop.go 的两层循环：内层 turn 循环反复「流式回复 → 停止原因分派 → 执行工具 → 回填」，直到某次助手消息不再发起工具调用；外层在内层收敛后消费 GetFollowUpMessages，有后续消息则重跑内层，否则结束。所有终止路径（自然结束 / error / aborted / 停止钩子 / 无后续消息）都汇于唯一出口 finish()。

交互式版本（含摘要卡片）见 docs/agent-loop-flowchart.html。

安装与构建

需要 Go 1.27 或更高版本。

# 克隆仓库
git clone https://github.com/smallnest/pigo.git
cd pigo

# 构建二进制（生成 ./pigo）
go build ./cmd/pigo

# 或安装到 $GOPATH/bin
go install ./cmd/pigo

# 也可以不构建，直接运行
go run ./cmd/pigo -p "1+1=?"

构建后可查看版本信息（版本号在正式发布时由 goreleaser 注入，源码构建显示 dev）：

pigo --version
# pigo dev (commit none, built unknown)

一键安装脚本（Linux / macOS）

install.sh 会自动检测操作系统 / 架构，从 GitHub Releases 下载最新的预编译二进制并安装到常用的 PATH 目录：

curl -fsSL https://raw.githubusercontent.com/smallnest/pigo/master/install.sh | sh

可用环境变量覆盖默认行为：

# 指定版本与安装目录
PIGO_VERSION=v0.2.0 PIGO_INSTALL_DIR="$HOME/bin" \
  curl -fsSL https://raw.githubusercontent.com/smallnest/pigo/master/install.sh | sh

Windows 请从 Releases 页面下载 .zip 手动解压。

下载预编译二进制

Releases 页面提供 Linux / macOS / Windows 的 amd64 与 arm64 预编译包（由 goreleaser 构建）。下载对应平台的压缩包解压即可使用。

快速开始

# 1. 配置默认 Provider（OpenRouter）的 API Key
export OPENROUTER_API_KEY=sk-or-...

# 2. 无头模式跑一个 prompt，打印最终回答
pigo -p "读取 README 并用三句话总结"

# 3. 进入交互式 REPL（不带 -p 且 stdout 是终端时自动进入）
pigo

# 4. 用本地 Ollama 模型，无需联网
pigo -m ollama/qwen2.5-coder -u http://localhost:11434/v1 -p "解释 main.go 做了什么"

命令行参数

--subagent-rpc 为内部参数（进程隔离子 Agent 的 JSON-RPC 服务端），不用于直接调用。

使用例子：

# 位置参数等价于 -p
pigo "把 utils.go 里的 getUserName 重命名为 getUsername"

# 指定模型
pigo -m anthropic/claude-3.5-sonnet -p "审查 foo.go 的并发安全性"

# 自定义系统提示词（替换默认）
pigo --system-prompt "你是一个只用中文回答的 Go 专家" -p "什么是 goroutine 泄漏"

# 追加系统提示词：可多次，值为文件路径则读取文件内容，否则作字面文本
pigo --append-system-prompt ./CONVENTIONS.md \
     --append-system-prompt "回答尽量简洁" \
     -p "为这个包补充单元测试"

# 一次性授权工作目录，让 bash/write/edit 免逐次确认
pigo -a -p "运行 go test ./... 并修复失败的用例"

模型与 Provider

模型 id 通过启发式规则映射到具体 Provider（--protocol 显式指定时优先级最高）：

1. --protocol 显式选择 → openai（需配合 --base-url）或 anthropic（默认公有 Anthropic API）。
2. 预置目录命中 → 使用预置声明的 Provider（REPL 中可用 /models 查看、/model <id> 切换）。
3. ollama/ 前缀 或 base URL 含 11434 → 本地 Ollama。
4. nvidia/ 前缀 → NVIDIA NIM。
5. 按模型名推断 → 未设 --provider/--protocol/--base-url 时，从模型名的知名前缀推断其第一方内置 Provider（如 -m claude-opus-4-8 直连 Anthropic，无需再写 --provider）。
6. 其余 → OpenRouter（默认）。

优先级：显式 flag（--provider > --protocol）> 预置目录 > ollama//nvidia/ 前缀 > 模型名推断 > OpenRouter 默认。显式 --provider 始终胜出；给了 --base-url 会被视为自定义端点信号，跳过第 5 步推断。

按模型名推断的前缀对照（仅推断能唯一确定 Provider 的前缀；llama-*、qwq-*、gemma-*、mixtral-* 等被多家网关服务的家族，以及形如 provider/model 的 routed id，不推断，回落到 OpenRouter 默认）：

匹配大小写不敏感。推断命中后走与显式 --provider 相同的解析路径，使用该 Provider 的默认 base URL、协议与 <PROVIDER>_API_KEY 环境变量。

Key 解析顺序：OAuth token → --api-key → 环境变量 → 配置文件。其他 Provider（google/deepseek/xai/groq/mistral 等）遵循 <PROVIDER>_API_KEY 约定。

使用例子：

# 默认 OpenRouter
export OPENROUTER_API_KEY=sk-or-...
pigo -p "写一个快排"

# 任意 OpenAI 兼容端点，强制 openai 协议
pigo -P openai -u https://my-gateway.example.com/v1 -m my-model -k $MY_KEY -p "..."

# 公有 Anthropic API
export ANTHROPIC_API_KEY=sk-ant-...
pigo -P anthropic -m claude-3-5-sonnet-20241022 -p "..."

内置工具

工具集根植于当前工作目录，--no-tools 可整体禁用。

bash / write / edit 属于“副作用工具“，在未信任目录下需确认（见项目信任）。

运行模式

# 无头打印模式：只输出最终回答文本
pigo -p "总结这个仓库的架构"

# stream-json：逐行 JSON 事件，首个事件带 session_id
pigo -p "列出所有 Go 文件" --output-format stream-json

# 交互式 REPL：不带 -p 且 stdout 为终端时进入
pigo

# 会话管理
pigo --list-sessions              # 列出会话
pigo --resume 20260720-1530-abcd  # 续跑指定会话（无头/REPL 均可）
pigo --continue                   # 续跑最近一次会话

REPL 中的内置斜杠命令包括 /model、/models、/help、/compact、/fork、/clone、/tree、/export、/import、/copy、/session、/exit 等。

在交互终端输入时，pigo 会用灰色文字提示最近匹配的输入或斜杠命令； 输入 /model 时还会从最近使用的模型和内置模型目录中匹配。按 Tab 或右方向键接受当前提示；当有多个匹配时，按上/下方向键可在候选提示之间 循环选择上一个或下一个，继续输入则会实时缩小匹配范围。

系统提示词组装

系统提示词按三层顺序拼装（internal/runtime/prompt.go）：

1. base 指令：默认的 coding-assistant 提示词，可用 --system-prompt 整体替换。
2. 环境块：工作目录、OS/架构、当前日期。
3. AGENTS.md 注入：从仓库根目录到当前工作目录，由通用到具体依次拼接——越靠近工作目录（越具体）的 AGENTS.md 排在越后，优先级更高。

--append-system-prompt 的内容追加在最后，按参数顺序排列；每个值若为存在的普通文件则读取文件内容，否则作为字面文本，空条目跳过。

项目信任

副作用工具（bash / write / edit）在未信任或未决定的目录下需要逐次确认。信任状态按目录三态（Trusted / Untrusted / Undecided）持久化为 JSON。

• 首次在某目录启动 REPL 时会提示是否信任。
• --approve / -a 为本次运行一次性授予会话级信任，跳过首次提示并免逐次确认。

技能 Skills

技能是带 YAML frontmatter（name、description，可选 allowed-tools、model）的 Markdown 文件，位于 ~/.agents/skills（可用 PIGO_SKILLS_DIR 覆盖）：

• 支持扁平的 *.md 与嵌套的 <name>/SKILL.md。
• 每个技能在 REPL 中暴露为 /skill-name 斜杠命令（展开正文为 prompt，支持 $ARGUMENTS 替换），也可作为子 Agent 工具运行。
• --no-skills 禁用技能发现；格式错误的技能会被非致命地跳过。

插件

外部插件从 $PIGO_HOME/plugins（默认 ~/.pigo/plugins）发现：

• 容错发现——启动失败的插件会被记录并跳过。
• 插件可提供额外工具，并订阅 Agent 生命周期事件。
• --no-tools 会整体跳过插件发现。

包管理

安装 pi 生态的包（extension / skill / prompt / theme）。install 需要 PATH 上有 npm。

# 安装（仅支持 npm: 源，支持 scoped 包与指定版本）
pigo install npm:pi-mcp-adapter
pigo install npm:@scope/[email protected]

# 列出已安装的包
pigo list

# 更新（无参数则更新全部）
pigo update
pigo update pi-mcp-adapter

# 卸载
pigo uninstall pi-mcp-adapter

包类型（extension / skill / prompt / theme）会分别分发到对应目录，安装记录写入 lockfile。

发布（Release）

使用 goreleaser 构建跨平台二进制并发布到 GitHub Release。

# 校验配置
goreleaser check

# 本地试跑（快照，不发布）
goreleaser release --snapshot --clean

# 正式发布：打 tag 并推送，GitHub Actions 自动触发
git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0

推送 v* tag 会触发 .github/workflows/release.yml，由 goreleaser 构建 Linux/macOS/Windows × amd64/arm64 的归档包、生成 checksums 并创建 Release。版本号 / commit / 构建时间通过 -ldflags 注入 main 包，可用 pigo --version 查看。

目录与环境变量

内置 Provider 一览（--provider）

--provider <name> 直接选中某个内置 Provider，使用其默认 base URL、协议与 API Key 环境变量（可用 --base-url 或 <PROVIDER>_BASE_URL 覆盖，--api-key 或对应环境变量提供 Key）。下表与注册表 internal/provider/registry.go 保持一致，pigo --help 也会列出同样的清单。

base_url 覆盖优先级：--base-url > provider 专有 *_BASE_URL 环境变量 > 泛化 <PROVIDER>_BASE_URL（provider 名大写、- 转 _）> 注册表默认值。任意 Provider 也支持泛化的 <PROVIDER>_API_KEY 约定作为 Key 回退。

火山方舟（volcengine）部分模型需以「推理接入点 ID（endpoint id）」而非模型名调用，此时用 -m <endpoint-id> 指定即可；本仓库预置的 doubao-seed-1-6 走模型名方式。

安全说明

• pigo 会向解析出的 Provider 端点发起外部网络请求。
• bash / write / edit 会在本地产生副作用，仅由项目信任机制把关；--approve 会跳过逐次确认，请在受信任的目录中使用，权衡便利与安全。
• 处理来自文件、命令输出、网页等外部来源的内容时应视为不可信数据。

许可证

参见仓库根目录的 LICENSE。