pigo 使用手册Manual

简介Introduction

pigo 提供两类能力：

pigo offers two kinds of capabilities:

• Agent 模式——以 flag 驱动，针对单条 prompt 运行 Agent 循环，适合脚本化与流水线；也可不带 -p 进入交互式 REPL。
• 包管理——通过 install / list / uninstall / update 子命令，从 npm 安装 pi 生态的扩展、技能、命令模板与主题。

• Agent mode — flag-driven, runs one agent loop for a single prompt (great for scripting and pipelines); omit -p to enter the interactive REPL.
• Package manager — install extensions, skills, command templates, and themes from the pi ecosystem on npm via the install / list / uninstall / update subcommands.

运行架构Runtime Architecture

下图展示 pigo 的高层运行架构：主请求路径（用户 → CLI → Agent 循环 → Provider → LLM 网关）、外部依赖，以及信任边界（pigo 进程 vs 外部网络，副作用工具经 Trust Gate 进入本地文件系统与 Shell）。

A high-level runtime view of pigo: the primary request path (user → CLI → agent loop → provider → LLM gateway), external dependencies, and trust boundaries (the pigo process vs. the external network, with side-effecting tools crossing the Trust Gate into the local filesystem and shell).

在新标签页打开交互式架构图 ↗Open the interactive diagram in a new tab ↗

安装与构建Install & Build

一键安装脚本（Linux / macOS）One-line installer (Linux / macOS)

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

Detects your OS/arch, downloads the latest prebuilt binary from GitHub Releases, and installs it into a common PATH directory:

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

可用环境变量覆盖：PIGO_VERSION（指定版本）、PIGO_INSTALL_DIR（安装目录）、GITHUB_TOKEN（提高 API 速率限制）。

Override with env vars: PIGO_VERSION (pin a version), PIGO_INSTALL_DIR (install dir), GITHUB_TOKEN (raise API rate limit).

从源码构建Build from source

pigo 使用 Go 编写（需 Go 1.27+）。

pigo is written in Go (requires Go 1.27+).

# 克隆并构建clone and build
git clone https://github.com/smallnest/pigo.git
cd pigo
go build -o pigo ./cmd/pigo

# 或直接安装到 $GOBINor install into $GOBIN
go install github.com/smallnest/pigo/cmd/pigo@latest

快速开始Quick Start

# 1) 用 Agent 跑一条 promptrun a prompt with the agent
pigo -p "读取 README 并用中文总结read the README and summarize it"

# 2) 进入交互式 REPLenter the interactive REPL
pigo

# 3) 安装一个 pi 扩展包install a pi extension
pigo install npm:pi-mcp-adapter

# 4) 查看已安装的包list installed packages
pigo list

运行 AgentRunning the Agent

Agent 模式对单条 prompt 运行一次 Agent 循环，退出码反映成功（0）或失败（1），便于在管道中组合。不带 -p 且 stdout 是终端时自动进入交互式 REPL。

Agent mode runs a single agent loop for one prompt; the exit code reflects success (0) or failure (1), so it composes well in pipelines. Without -p and with a TTY on stdout, pigo enters the interactive REPL.

# 打印模式：仅输出最终文本print mode: emit only the final text
pigo -p "解释这段代码explain this code" -m openrouter/free

# 流式 JSON 事件（行分隔），适合程序消费line-delimited JSON events for programmatic use
pigo -p "..." --output-format stream-json

# prompt 也可作为位置参数传入the prompt can be a positional arg too
pigo "帮我写一个 Go 的快排write a quicksort in Go"

常用 flagCommon flags

模型与 ProviderModels & Providers

pigo 从 --model 解析对应的内置 Provider，API Key 从环境变量取用（<PROVIDER>_API_KEY）。解析规则如下：

pigo resolves a built-in provider from --model and reads the API key from the environment (<PROVIDER>_API_KEY). Resolution rules:

1. 若显式指定 --protocol（openai/anthropic），优先于一切启发式；openai 需配合 --base-url。
2. 预置目录中的模型 id 使用其自带 Provider（OpenRouter / NVIDIA / Ollama）。
3. ollama/ 前缀或指向 11434 端口的 base URL → 本地 Ollama。
4. nvidia/ 前缀 → NVIDIA NIM。
5. 其余一律走 OpenRouter（OpenAI 兼容网关）。

1. An explicit --protocol (openai/anthropic) beats every heuristic; openai requires --base-url.
2. Model ids in the preset catalog use their declared provider (OpenRouter / NVIDIA / Ollama).
3. ollama/ prefix or a base URL on port 11434 → local Ollama.
4. nvidia/ prefix → NVIDIA NIM.
5. Everything else → OpenRouter (OpenAI-compatible gateway).

# 本地 Ollamalocal Ollama
pigo -p "你好hello" -m ollama/qwen2.5

# 自建 OpenAI 兼容端点self-hosted OpenAI-compatible endpoint
pigo -p "..." -P openai -u https://my-endpoint/v1 -m my-model

包管理概览Package Manager Overview

pigo 可安装 pi 生态发布到 npm 的四类包，并把内容分发到 pigo 现有发现机制能识别的目录，无需额外配置：

pigo installs four kinds of packages from the pi ecosystem on npm, distributing their contents into the directories pigo already discovers — no extra config:

安装信息记录在 lockfile（$PIGO_HOME/packages.json）中，作为 list/uninstall/update 的事实来源。

Install records live in a lockfile ($PIGO_HOME/packages.json), the source of truth for list/uninstall/update.

install

安装一个或多个 pi 包。流程为：解析引用 → npm pack 拉取并解压 → 分类 → 按类型分发 → 写 lockfile。

Install one or more pi packages. Flow: resolve reference → npm pack fetch & extract → classify → distribute by type → write lockfile.

# 安装最新版install the latest version
pigo install npm:pi-mcp-adapter

# 指定版本 / 作用域包pin a version / scoped package
pigo install npm:pi-mcp-adapter@1.2.0
pigo install npm:@myscope/pi-theme

# 一次安装多个（某个失败不影响其余）install several at once (one failure won't block the rest)
pigo install npm:pi-mcp-adapter npm:pi-some-skill

安装成功后打印 Installed <name>@<ver> (<types>) — N file(s)。多包安装时，若任一失败退出码为 1，但其余包照常安装。

On success it prints Installed <name>@<ver> (<types>) — N file(s). For multi-package installs, any failure yields exit code 1 while the others still install.

list

列出全部已安装的包，每行以制表符分隔 名称　版本　类型　来源，便于用 cut -f 等工具消费。

List all installed packages, one per line, tab-separated as name　version　type　source — easy to pipe through cut -f.

pigo list
# pi-mcp-adapter    1.2.0    extension    npm:pi-mcp-adapter
# pi-demo-skill     0.3.1    skill        npm:pi-demo-skill

# 未安装任何包时when nothing is installed
pigo list
# no packages installed

uninstall

卸载包：删除 lockfile 中记录的全部落地文件，再移除该条目。支持一次卸载多个。

Uninstall a package: delete every file recorded in the lockfile, then remove the entry. Multiple names allowed.

pigo uninstall pi-mcp-adapter
pigo uninstall pi-mcp-adapter pi-demo-skill

• 按路径长度降序删除，并对目录使用 RemoveAll，确保 payload 目录被整体清理。
• 某个记录文件若已不存在，跳过并继续，最终仍会移除 lockfile 条目（收敛到"已卸载"状态）。
• 卸载未安装的包会报错 package not installed: <name> 并以非零码退出。

• Deletes longest paths first and uses RemoveAll on directories, so payload dirs are cleared whole.
• A missing recorded file is skipped; the lockfile entry is still removed (converges to "uninstalled").
• Uninstalling a package that isn't installed errors with package not installed: <name> and exits non-zero.

update

把已安装的包更新到 npm 上的最新版本。

Update installed packages to the latest version on npm.

# 更新指定包（可多个）update named packages (one or more)
pigo update pi-mcp-adapter

# 不带包名：遍历更新全部已安装包no name: update every installed package
pigo update

• 先拉取并分类最新版本，仅当版本与已装不同才「卸旧文件 → 重新分发 → 更新 lockfile 版本」。
• 已是最新版时打印 <name> is up to date，不做无谓改动。
• 失败安全：网络或分类失败发生在任何删除之前，原安装保持不变，不会留下损坏状态。
• 无参 update 逐包尽力而为，任一失败则退出码非零。

• Fetches and classifies the latest first; only when the version differs does it "remove old files → redistribute → bump the lockfile version".
• Already current prints <name> is up to date and makes no changes.
• Fail-safe: network or classification failures happen before any deletion, so the existing install stays intact.
• Argument-less update is best-effort per package; any failure yields a non-zero exit code.

目录与环境变量Paths & Environment Variables

常见问题FAQ

提示找不到 npm？"npm not found"?

install/update 依赖本机 npm。请先安装 Node.js（自带 npm），并确认 npm 在 PATH 中。

install/update need npm. Install Node.js (which bundles npm) and make sure npm is on your PATH.

安装报"unrecognized pi package"？"unrecognized pi package"?

该包不含任何可识别的 pi 元数据或结构特征（如 bin、SKILL.md、commands/），因此不是 pi 包，pigo 拒绝安装且不写 lockfile。

The package has no recognizable pi metadata or structure (like bin, SKILL.md, commands/), so it isn't a pi package; pigo refuses to install it and leaves the lockfile untouched.

只支持 npm 来源吗？Is only npm supported?

本版本仅支持 npm:（含作用域包）。github:/file: 等来源不在当前范围内。

This version supports only npm: (including scoped packages). Sources like github:/file: are out of scope.

update 会做版本大小比较吗？Does update compare version ordering?

当前仅比较 npm pack 返回的版本字符串是否与已装版本相同，不做 semver 大小判断——即"更新到 latest"。

It only checks whether the version string returned by npm pack differs from the installed one — no semver ordering. In other words, "update to latest".