smallnest/pigo

pigo – 基于 Go 的 CLI 代码助手（pi 风格 AI 代理）

是什么 – pigo 是一个用 Go 编写的开源命令行 AI 代理，模仿了 pi 代码助手的功能。它可以读写文件、运行 shell 命令、获取网页内容，并调用大语言模型（LLM）来理解请求、修改代码并返回结果。该工具支持两种模式：

无头模式 (-p …) – 一次性提示，输出最终答案（或流式输出 JSON 事件）。
交互式 REPL – 终端 UI，可迭代地提问、运行工具并查看代理的推理过程。

主要功能（如 README 所述）

功能	说明
两种运行模式	`-p` 用于单次脚本/CI，或 REPL 用于交互式使用。
多种 LLM 提供商	OpenRouter（默认）、本地 Ollama、NVIDIA NIM、Anthropic、任何 OpenAI 兼容端点等。
内置工具集	`read`、`write`、`edit`、`grep`、`find`、`bash`（支持后台执行）、`todo`、`webfetch`、`websearch`、`memory_search`、`task` 等。
会话管理	列出、恢复或继续之前的会话；每个会话都会流式输出包含 `session_id` 的 JSON。
工具级允许/拒绝	`--allowed-tools`（白名单）和 `--disallowed-tools`（黑名单）——黑名单优先，且在任何工具提供给模型前强制执行。
项目信任	文件系统目录默认不信任；具有副作用的工具（`bash`、`write`、`edit`）除非使用 `--approve`，否则需要确认。
技能与插件	斜杠风格命令（`/skill-name`）从 `~/.agents/skills` 加载；外部插件可添加更多工具。
提示模板	可重用的 Markdown 提示片段（`/name` 展开）支持位置参数语法（`$1`、`${1:-default}`、`$@` 等）。
上下文压缩	当令牌窗口接近限制时自动摘要；也支持手动 `/compact`。
自更新	`pigo update` 可将二进制文件升级到最新 GitHub 发布版本。
SDK	核心代理可作为 `github.com/smallnest/pigo/agent` 导入，用于嵌入其他 Go 程序。
钩子	九个生命周期钩子点（如 `PreToolUse`、`UserPromptSubmit`），可运行 shell 命令并可阻止或修改执行。
GitHub PR 审查 Webhook	可选模式，当 PR 准备好审查时创建只读审查会话。

安装与快速入门（来自 README）

# 从源码构建（需要 Go 1.27+）
git clone https://github.com/smallnest/pigo.git
cd pigo
go build ./cmd/pigo   # 生成 ./pigo
# 或安装到 $GOPATH/bin
go install ./cmd/pigo

或使用一键脚本（Linux/macOS）获取预编译二进制文件：

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

设置 LLM 凭据后运行：

export OPENROUTER_API_KEY=sk-…   # 或其他提供者密钥
pigo -p "读取 README 并用三句话总结"   # 无头模式
pigo                                   # 启动 REPL
pigo -m ollama/qwen2.5-coder -u http://localhost:11434/v1 -p "解释 main.go 做了什么"

工作原理（高层架构）

CLI → 代理循环 – 命令行解析标志并启动代理运行时。
双层轮次循环 – 内层循环流式输出 LLM 回复，判断是否应调用工具，执行工具并反馈结果。外层循环检查后续消息，可能重启内层循环。
提供者抽象 – 模型 ID 通过启发式方法映射到具体提供者（OpenRouter、Ollama 等）；提供者处理对 LLM 网关的 HTTP 请求。
工具执行与信任门控 – 工具执行前，信任系统检查当前目录是否可信，以及工具是否在白名单/黑名单中允许。
会话与上下文处理 – 所有轮次均被存储；当令牌窗口接近模型限制时，上下文会自动摘要。
提示组装 – 系统提示由基础提示、环境信息、可选的 AGENTS.md 文件和任何 --append-system-prompt 参数构建。

何时使用 pigo

CI 中的自动代码修复 – 无头模式（-p）可脚本化用于 lint、运行测试，并让 LLM 编辑失败的文件。
本地开发辅助 – REPL 提供交互式“配对程序员”，可读取仓库、运行命令并建议更改。
自托管 LLM – 支持 Ollama 或任何 OpenAI 兼容端点，无需云 API。
可扩展工作流 – 通过插件添加自定义工具，或定义可重用的提示/技能用于特定领域任务。

限制 / 安全注意事项（来自 README）

具有副作用的工具需要目录信任或显式 --approve；在不信任的位置不会运行。
工具黑名单优先于白名单；黑名单阻止的工具无法通过 --approve 覆盖。
钩子以当前用户身份运行，不接收凭据，但仍可阻止执行。
代理 不支持并发安全 – Session 应由单个 goroutine 使用。

常用标志快速参考

标志	含义
`-p, --print`	无头模式的提示（或使用位置参数）。
`-m, --model`	模型标识符（默认 `openrouter/free`）。
`-u, --base-url`	覆盖提供者 URL（例如本地 Ollama）。
`-k, --api-key`	直接提供 API 密钥，覆盖环境/配置。
`-P, --protocol`	强制使用 `openai` 或 `anthropic` 协议。
`-o, --output-format`	`text`（默认）或 `stream-json`。
`-n, --no-tools`	禁用所有内置工具和插件发现。
`--allowed-tools` / `--disallowed-tools`	工具使用的白名单/黑名单。
`-a, --approve`	信任当前工作目录用于本次运行。
`--prompt-template`	加载额外的提示模板文件或目录。
`--system-prompt`	完全替换默认系统提示。
`--append-system-prompt`	将额外文本或文件内容附加到系统提示。

SDK 示例（来自 README）

import (
    "log"
    "os"
    "github.com/smallnest/pigo/agent"
)

func main() {
    sess, err := agent.New(
        agent.WithModel("claude-opus-4-8"),
        agent.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    )
    if err != nil { log.Fatal(err) }
    defer sess.Close()

    reply, err := sess.Prompt(context.Background(), "用一句话介绍什么是编码智能体")
    if err != nil { log.Fatal(err) }
    fmt.Println(reply)
}

SDK 与 CLI 默认一致（工具启用，除非请求否则无技能/记忆），可通过 WithTools、WithoutTools、WithSkills 等配置。

TL;DR

pigo 是一个 Go 原生、命令行的 AI 代码助手，可本地运行或对接云 LLM，提供丰富的文件系统和 shell 工具，支持脚本和交互式 REPL，并可通过插件、提示模板和 Go SDK 进行扩展。