Pi Agent 教程
什么是 Pi Agent?
Pi Agent 是一款运行在终端里的 AI 编程代理,可以在命令行中直接与 AI 对话,完成代码编写、文件操作、命令执行、Git 操作等开发任务,大幅提升开发效率。
Pi Agent 的核心特点
- 终端原生:在命令行中工作,无需离开开发环境
- 多模型支持:可对接 OpenAI、DeepSeek、本地模型(llama.cpp)等
- 工具调用:读写文件、执行命令、Git 操作等
- Skills 技能系统:可扩展的提示词与工具包
- 上下文管理:支持长对话与项目级记忆
- 安全可控:项目信任机制与权限控制
典型使用场景
- 代码生成与修改
- Bug 排查与修复
- 代码审查与重构
- 项目脚手架搭建
- 自动化脚本编写
快速上手示例
# 在项目目录启动
pi
# 进入对话后
> 帮我写一个 Python 快排函数
> 修复这个文件里的 bug
> 给项目添加 README与 Claude Code / Codex 的对比
Pi Agent 属于同类终端 AI 编程代理产品,核心差异在于模型提供商配置更灵活、支持本地模型,且内置了完整的技能(Skills)与扩展系统。
Pi Agent 简介
Pi Agent 简介
Pi Agent 是一个开源的终端 AI 编程代理,让你用自然语言与代码库交互。
工作原理
你在终端输入指令
↓
Pi Agent 将指令发送给 AI 模型(可配置)
↓
模型返回操作计划(读文件/写文件/执行命令)
↓
Pi Agent 执行操作并汇报结果
↓
多轮对话直到任务完成核心能力
1. 文件读写:创建、修改、删除文件
2. 命令执行:在项目内运行命令并读取输出
3. 代码搜索:全局搜索与定位代码
4. Git 操作:提交、分支、diff 查看
5. 上下文记忆:记住项目结构与历史决策
6. 多模型切换:OpenAI / DeepSeek / 本地模型安装方式
# npm 安装
npm install -g pi-agent
# 或源码安装
git clone https://github.com/pi-agent/pi
cd pi && npm install && npm run build快速开始
# 首次运行会引导配置 API Key
pi
# 直接提问
pi "解释这个项目的架构"
# 指定模型
pi --model deepseek-chat "优化这段代码"适合谁用
✓ 经常写代码的开发者
✓ 需要快速原型验证的工程师
✓ 维护多项目的开发者
✓ 想用 AI 提升效率的程序员Pi Agent 核心概念
Pi Agent 核心概念
理解 Pi Agent 的核心概念,才能高效使用它。
1. 会话(Session)
一次对话从启动到结束称为一个会话
- 会话内模型记忆上下文
- 可保存/恢复历史会话
- 会话按项目隔离2. 上下文(Context)
模型看到的信息范围:
- 系统提示词(角色定义)
- 项目结构信息
- 历史对话内容
- 工具执行结果
上下文窗口有限,重要信息可手动补充3. 工具(Tools)
模型可调用的能力:
- read_file 读取文件
- write_file 写文件
- edit_file 编辑文件
- run_command 执行命令
- search_code 代码搜索
- git_commit Git 提交
- list_dir 列出目录4. 技能(Skills)
可复用的提示词包:
- 定义特定任务的指令
- 可附带脚本/参考文件
- 按需自动触发或手动调用
- 类似 Claude Code 的 Skills5. 信任模式(Trust)
控制 Agent 可执行的操作:
- 项目信任:允许在该项目执行命令
- 命令白名单:只允许特定命令
- 手动确认:每次执行前询问6. 配置(Config)
配置文件定义:
- 模型提供商与 API Key
- 默认行为与权限
- 主题与快捷键
- 提示词模板Pi Agent 安装
Pi Agent 安装
Pi Agent 支持多种安装方式,按需选择。
1. 前置要求
Node.js ≥ 18
Git
一个 AI 模型 API Key(OpenAI/DeepSeek/其他)2. npm 安装(推荐)
npm install -g pi-agent
# 验证
pi --version3. Homebrew 安装(macOS)
brew install pi-agent4. 源码安装
git clone https://github.com/pi-agent/pi.git
cd pi
npm install
npm run build
npm link
# 验证
pi --help5. Docker 安装(可选)
docker pull pi-agent/pi
docker run -it --rm -v $(pwd):/workspace pi-agent/pi6. 首次启动配置
# 运行 pi,按引导配置
pi
# 手动创建配置
mkdir -p ~/.config/pi-agent
cat > ~/.config/pi-agent/config.json <<'EOF'
{
"provider": "openai",
"apiKey": "sk-xxx",
"model": "gpt-4o"
}
EOF7. 常见问题
1. 权限不足:用 sudo 或设置 NODE_PATH
2. Node 版本过低:升级 Node ≥ 18
3. 网络问题:设置代理 npm config set proxyPi Agent 认证与模型配置
Pi Agent 认证与模型配置
配置 API Key 与模型是使用 Pi Agent 的第一步,支持多种 AI 提供商。
1. OpenAI 配置
# 方式一:交互配置
pi setup
# 方式二:配置文件
cat > ~/.config/pi-agent/config.json <<'EOF'
{
"provider": "openai",
"apiKey": "sk-your-key",
"model": "gpt-4o",
"baseUrl": "https://api.openai.com/v1"
}
EOF2. 环境变量方式
# 避免把 Key 写进配置文件
export OPENAI_API_KEY="sk-xxx"
export PI_AGENT_PROVIDER="openai"
export PI_AGENT_MODEL="gpt-4o"3. 多提供商切换
# 命令行指定
pi --provider openai --model gpt-4o
pi --provider deepseek --model deepseek-chat
pi --provider anthropic --model claude-sonnet-4
# 会话内切换
> /model deepseek-chat4. 代理与网络配置
# 配置文件
{
"provider": "openai",
"apiKey": "sk-xxx",
"baseUrl": "https://api.openai.com/v1",
"httpProxy": "http://127.0.0.1:7890"
}
# 环境变量
export HTTPS_PROXY="http://127.0.0.1:7890"5. 验证配置
# 测试连接
pi "你好,请回复 1"
# 查看当前配置
pi config show6. 安全提示
1. API Key 不要提交到 Git
2. 使用 .env 或密钥管理器
3. 团队共享时用服务端代理隐藏 Key
4. 定期轮换 KeyPi Agent DeepSeek
Pi Agent 接入 DeepSeek
DeepSeek 是国内流行的 AI 模型,Pi Agent 原生支持接入,性价比高。
1. 获取 DeepSeek API Key
1. 注册 platform.deepseek.com
2. 创建 API Key(需充值)
3. 复制 key 备用2. 配置 Pi Agent
# 配置文件
cat > ~/.config/pi-agent/config.json <<'EOF'
{
"provider": "deepseek",
"apiKey": "sk-your-deepseek-key",
"model": "deepseek-chat",
"baseUrl": "https://api.deepseek.com/v1"
}
EOF
# 或环境变量
export DEEPSEEK_API_KEY="sk-xxx"
export PI_AGENT_PROVIDER="deepseek"3. 选择模型
deepseek-chat: 通用对话,适合日常编程
deepseek-coder: 代码专项,编程任务更强
deepseek-reasoner: 推理模型,复杂任务
# 指定模型
pi --model deepseek-coder4. 验证连接
pi "用 Python 写一个冒泡排序"
# 成功则输出代码,失败会提示认证/网络错误5. 切换回其他提供商
# 命令行
pi --provider openai --model gpt-4o
# 会话内
> /provider deepseek
> /model deepseek-chat6. 常见问题
1. 401 错误:API Key 错误或未生效
2. 余额不足:DeepSeek 控制台充值
3. 限流:降低并发,等待重试
4. 响应慢:deepseek-reasoner 推理较慢属正常PI Agent 第一次对话
Pi Agent 第一次对话
完成配置后,体验 Pi Agent 的首次对话。
1. 启动
# 进入项目目录
cd my-project
pi2. 简单提问
> 你好,请介绍一下你自己
Pi: 我是 Pi Agent,运行在终端里的 AI 编程助手。
我可以帮你写代码、改 bug、执行命令、管理 Git...3. 让 AI 写代码
> 写一个 Python 函数,计算斐波那契数列
Pi: 我来创建 fib.py
[✓] 已创建文件 fib.py
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
...
> 好的,帮我运行测试一下
[✓] 已执行: python fib.py
0 1 1 2 3 5 8 13 21 344. 修改代码
> 把斐波那契改成迭代实现,避免递归栈溢出
Pi: [✎] 正在编辑 fib.py...
已完成修改,并运行验证通过。5. 解释代码
> 解释一下项目里 main.py 的作用
Pi: 读取 main.py...
main.py 是程序入口,主要做了三件事:
1. 解析命令行参数
2. 加载配置文件
3. 启动 HTTP 服务6. 对话技巧
1. 明确目标:"把 x 改成 y"
2. 给出约束:"不要用第三方库"
3. 要求验证:"改完帮我运行测试"
4. 指定文件:"只改 src/utils.py"
5. 追问细节:"为什么这么实现?"Pi Agent 交互模式
Pi Agent 交互模式
Pi Agent 提供 REPL 交互模式,支持多行输入、快捷键与命令。
1. 进入交互模式
# 直接运行进入 REPL
pi2. 基本输入
> 你的指令
# 单行输入直接回车发送
# 多行输入
> /multiline
> 第一行
> 第二行
> /end
# 或者粘贴多行文本3. 常用交互命令
/help 查看帮助
/model xxx 切换模型
/context 查看上下文占用
/clear 清空对话历史
/save 保存会话
/load 恢复会话
/trust 信任当前项目
/quit 退出(或 Ctrl+D)4. 流式输出
Pi Agent 支持流式响应:
- 模型思考时实时显示
- 工具调用时显示操作日志
- 可随时 Ctrl+C 中断当前响应5. 中断与重试
Ctrl+C 中断当前生成
/r 重新生成上一条
Ctrl+R 重新开始新话题6. 输出渲染
Pi Agent 美化终端输出:
- 代码块高亮
- diff 绿色/红色显示
- 文件操作图标(✓ ✎)
- 错误红色提示Pi Agent 非交互模式
Pi Agent 非交互模式(One-shot)
非交互模式适合脚本化、CI/CD 与管道调用。
1. 直接传参
# 单次提问
pi "总结这个项目的架构"
# 指定文件上下文
pi -f src/main.py "优化这个文件的性能"
# 多文件
pi -f src/a.js -f src/b.js "对比这两个文件"2. 输出格式控制
# 输出到文件
pi "生成 README" > README.md
# 静默模式(只输出最终结果)
pi --quiet "列出所有测试命令"
# JSON 输出(供程序解析)
pi --json "分析代码问题"3. 管道使用
# 代码进管道
cat error.log | pi "分析这个错误日志,给出解决方案"
# 结果进管道
pi "生成 10 个测试用例" | grep "test_"4. 脚本中调用
#!/bin/bash
# 批量处理脚本
for file in src/*.py; do
pi -f "$file" "检查这个文件的代码质量"
done5. CI/CD 集成
# GitHub Actions 示例
- name: AI Code Review
run: |
pi --json "审查本次改动的潜在问题" > review.json
# 后续解析 review.json6. 常用非交互参数
--provider 指定提供商
--model 指定模型
-f, --file 附加文件上下文
--json 输出 JSON
--quiet 静默
--no-tools 禁用工具调用(纯对话)PI Agent 上下文管理
Pi Agent 上下文管理
上下文窗口有限,合理管理上下文让对话更准确、成本更低。
1. 上下文构成
模型收到的信息:
1. 系统提示词(角色与规则)
2. 会话历史(之前的对话)
3. 文件内容(读取的文件)
4. 工具输出(命令结果)
5. 手动附加的信息2. 查看上下文占用
> /context
上下文: 12,345 tokens / 128,000 (9.6%)
├── 系统提示词: 1,200
├── 会话历史: 9,845
└── 文件内容: 1,3003. 控制文件读取
# 只读关键文件,避免污染上下文
> 只读 src/config.js,分析里面的配置
# 明确不要读取
> 不要读 node_modules,只看 src 下的文件
# 指定行范围
> 读取 utils.py 的 100-200 行4. 压缩与裁剪
/compact 压缩早期对话(保留要点)
/clear 清空全部历史
/forget 忘记指定话题
/context set 5000 手动设置上下文上限5. 注入系统提示词
# 配置文件中的 systemPrompt
{
"systemPrompt": "你是资深 Python 工程师,回答要简洁,附代码示例。"
}
# 会话内
/system 接下来的回答一律用中文6. 项目记忆
# 项目级记忆文件(类似 CLAUDE.md)
> 记住:本项目使用 pnpm,Node 20
> 记住:接口统一返回 {code, msg, data}
# 记忆保存在 .pi/memory.md
# 每次会话自动加载7. 省钱技巧
1. 长对话及时 /compact
2. 不相关的文件别读
3. 简单任务用小模型(deepseek-chat)
4. 复杂任务才开推理模型Pi Agent 会话管理
Pi Agent 会话管理
Pi Agent 支持会话的保存、恢复与多会话并行,方便长期项目维护。
1. 会话保存
# 保存当前会话
> /save
已保存会话: my-project-2026-08-18
# 指定名称
> /save 重构数据库层2. 恢复会话
# 列出会话
> /sessions
- 重构数据库层 (昨天)
- my-project-2026-08-18 (今天)
# 恢复
> /load 重构数据库层
已恢复会话,共 23 轮对话3. 会话存储位置
# 每个项目独立存储
.pisession/
├── sessions/
│ └── 2026-08-18T10-30-00.json
└── history/
# 全局会话
~/.config/pi-agent/sessions/4. 导出与分享
# 导出为 Markdown 对话记录
> /export chat.md
# 导出 JSON(供程序处理)
pi --session 重构数据库层 --export chat.json5. 自动保存
# 配置自动保存
{
"session": {
"autoSave": true,
"autoSaveInterval": 60, # 秒
"maxHistory": 50 # 保留会话数
}
}6. 多会话并行
# 开多个终端,不同项目/任务各开一个会话
终端1: 重构用户模块
终端2: 排查登录 bug
终端3: 写测试用例
# 会话之间互不影响,按项目隔离Pi Agent 键盘快捷键定制
Pi Agent 键盘快捷键定制
Pi Agent 的快捷键可以完全自定义,贴合个人使用习惯。
1. 默认快捷键
Enter 发送消息
Shift+Enter 换行
Ctrl+C 中断
Ctrl+D 退出
Ctrl+R 重新生成
Ctrl+L 清屏
↑/↓ 历史命令
Tab 补全2. 配置快捷键
# config.json
{
"keybindings": {
"send": "Enter",
"newline": "Shift+Enter",
"interrupt": "Ctrl+C",
"regenerate": "Ctrl+R",
"clearScreen": "Ctrl+L",
"historyPrev": "Up",
"historyNext": "Down"
}
}3. 自定义命令快捷键
{
"keybindings": {
"switchModel": "Ctrl+M", # 快速切换模型
"toggleTrust": "Ctrl+T", # 切换信任模式
"contextInfo": "Ctrl+Shift+C" # 查看上下文
}
}4. 快捷键冲突处理
# 终端可能占用某些组合键
# 检查终端自己的快捷键设置
# 换用不冲突的组合如 Ctrl+Shift+*
# 查看当前生效绑定
> /keybindings5. 常见自定义需求
1. 发送改为 Ctrl+Enter(防止误触)
2. 多行模式默认开启
3. 模型切换绑定到 F 键
4. 代理模式开关快捷键Pi Agent 主题定制
Pi Agent 主题定制
Pi Agent 支持自定义终端界面主题,包括颜色、符号与布局。
1. 选择内置主题
# 内置主题列表
> /theme
dark (默认)
light
dracula
monokai
nord
> /theme dracula2. 配置文件指定
{
"theme": {
"name": "custom",
"colors": {
"primary": "#6366f1",
"success": "#22c55e",
"error": "#ef4444",
"warning": "#f59e0b",
"info": "#0ea5e9",
"muted": "#6b7280",
"background": "#1e293b",
"text": "#e2e8f0"
}
}
}3. 自定义符号
{
"theme": {
"icons": {
"file_created": "✓",
"file_edited": "✎",
"file_deleted": "✗",
"command_run": "❯",
"thinking": "…",
"assistant": "✦",
"user": "❯",
"tool": "⚙"
}
}
}4. 代码块样式
{
"theme": {
"codeBlock": {
"background": "#0f172a",
"border": "#334155",
"keyword": "#c084fc",
"string": "#86efac",
"number": "#fbbf24",
"comment": "#64748b"
}
}
}5. 提示符(Prompt)定制
{
"prompt": {
"showModel": true, # 显示当前模型
"showTokens": false, # 显示 token 数
"showTime": true, # 显示时间
"template": "\[\[[model]]\] [[time]] ❯ "
}
}Pi Agent 提示词模板
Pi Agent 提示词模板
提示词模板让常用指令可复用,保证输出风格与质量稳定。
1. 创建模板
# 模板目录
~/.config/pi-agent/prompts/
# 或项目级 .pi/prompts/
# 示例: code-review.md
你是资深代码审查员。请审查提供的代码,重点检查:
1. 潜在 bug 与边界情况
2. 性能问题
3. 代码规范
4. 安全隐患
输出格式:按严重程度(高/中/低)列出问题清单,附修复建议。2. 使用模板
# 会话内调用
> /prompt code-review -f src/app.js
# 自动加载模板并附加文件
# 命令行
pi --prompt code-review -f src/app.js3. 模板变量
# 模板支持变量
你在审查 {{language}} 项目,重点关注 {{focus}}。
# 调用时传入
> /prompt review --var language=Python --var focus=安全性4. 内置模板
code-review 代码审查
explain 解释代码
test-generator 生成测试
refactor 重构建议
commit-message 生成提交信息
readme 生成 README
debug 调试分析
security 安全审计5. 模板最佳实践
1. 明确定位:模板开头说明角色
2. 具体指令:给出检查点与输出格式
3. 可参数化:用变量提升复用性
4. 版本管理:模板纳入 Git 管理
5. 团队共享:放在项目 .pi/prompts/ 里Pi Agent Skills 技能系统
Pi Agent Skills 技能系统
Skills 是 Pi Agent 的可扩展能力单元,把特定任务的指令、脚本与参考打包复用。
1. Skills 是什么
一个 Skill 包含:
- SKILL.md: 技能说明与使用指令
- scripts/: 可选辅助脚本
- references/: 参考文档
- assets/: 静态资源2. 创建 Skill
# 目录结构
~/.config/pi-agent/skills/
└── python-project-setup/
└── SKILL.md
# SKILL.md 示例
---
name: python-project-setup
description: 初始化标准 Python 项目结构
triggers:
- 创建 Python 项目
- 初始化项目
---
# Python 项目初始化
当用户要求创建 Python 项目时:
1. 创建 src/ 与 tests/ 目录
2. 生成 pyproject.toml
3. 配置虚拟环境
4. 创建 README.md 与 .gitignore3. 使用 Skill
# 自动触发(根据 description/triggers)
> 帮我初始化一个 Python 项目
# 手动调用
> /skill python-project-setup4. 带脚本的 Skill
# scripts/deploy.sh
#!/bin/bash
# 部署脚本,由 Agent 调用
# SKILL.md 中说明
# 当执行部署时运行: bash scripts/deploy.sh5. 管理 Skills
/skills 列出所有技能
/skill install <name> 安装技能
/skill remove <name> 移除技能
/skill update <name> 更新技能
# 项目级技能(团队共享)
.pisills/
└── project-rules/
└── SKILL.md6. Skills 最佳实践
1. description 写清楚适用场景
2. 指令要具体可执行
3. 脚本保持幂等(可重复执行)
4. 团队约定放进项目级 Skills
5. 定期整理更新Pi Agent 配置详解
Pi Agent 配置详解
配置文件控制 Pi Agent 的全局行为,支持分层配置。
1. 配置优先级
命令行参数 > 项目配置 > 用户配置 > 默认配置
位置:
- 用户级: ~/.config/pi-agent/config.json
- 项目级: .pi/config.json
- 环境变量: PI_AGENT_*2. 核心配置项
{
"provider": "openai", // 提供商
"apiKey": "sk-xxx", // API Key
"model": "gpt-4o", // 默认模型
"baseUrl": "https://...", // 自定义端点
"temperature": 0.7, // 随机性 0-2
"maxTokens": 4096, // 最大输出
"stream": true // 流式输出
}3. 行为配置
{
"autoApprove": false, // 自动批准工具执行
"confirmCommands": true, // 命令执行前确认
"allowedCommands": ["git", "npm", "python"], // 白名单
"defaultTrust": "ask", // 项目信任默认行为
"showDiff": true, // 显示文件改动 diff
"historyLimit": 50 // 历史条数
}4. 模型配置多实例
{
"profiles": {
"fast": { "provider": "deepseek", "model": "deepseek-chat" },
"smart": { "provider": "openai", "model": "gpt-4o" },
"local": { "provider": "ollama", "model": "qwen2.5-coder" }
}
}
# 使用: pi --profile smart5. 查看与修改配置
pi config show # 查看生效配置
pi config set model gpt-4o
pi config unset apiKey
pi config path # 配置文件路径6. 常见配置场景
1. 公司代理:配置 httpProxy
2. 本地模型:provider=ollama
3. 安全环境:autoApprove=false
4. 中文输出:systemPrompt 指定
5. 限流环境:降低并发与超时Pi Agent 安全与项目信任
Pi Agent 安全与项目信任
Agent 能执行命令与写文件,安全机制至关重要。
1. 项目信任模型
首次在项目目录启动:
> 是否信任此项目? [y/N]
- 信任:允许执行命令与文件操作
- 不信任:仅只读操作与对话
信任状态保存在 .pi/trusted 标记2. 命令白名单
{
"allowedCommands": ["git", "npm", "pnpm", "python", "node"],
"blockedCommands": ["rm -rf", "sudo", "mkfs", "dd"]
}
# 白名单外的命令需要确认
> 即将执行: sudo apt install xxx
> 确认执行? [y/N]3. 敏感操作保护
# 以下操作默认需要确认
- 删除文件/目录
- 修改权限
- 安装系统级软件
- 操作 Git 远程仓库
- 发送网络请求4. 环境变量隔离
{
"sandbox": {
"env": { "HOME": "/tmp/pi-home", "GITHUB_TOKEN": "" },
"allowedEnv": ["PATH", "LANG"]
}
}5. 审计日志
# 所有操作记录
~/.config/pi-agent/logs/audit.log
[2026-08-18 10:30:01] run_command: git status
[2026-08-18 10:30:15] write_file: src/app.js
# 查看
> /audit
> /audit --filter "write_file"6. 安全最佳实践
1. 不信任来源不明的项目
2. 生产环境关闭 autoApprove
3. 定期查看审计日志
4. API Key 严格保密
5. 重要操作前备份
6. 不把敏感文件(如 .env)让 Agent 读取上传Pi Agent 扩展入门
Pi Agent 扩展入门
Pi Agent 的扩展系统让你添加自定义工具、命令与事件处理,定制自己的 Agent。
1. 扩展类型
1. 自定义工具(Tools): 新能力(如调用内部 API)
2. 自定义命令(Commands): 斜杠命令
3. 事件监听(Events): 对话/工具事件钩子
4. 提示词扩展: 修改系统提示
5. Skills: 技能包(上一章)2. 扩展目录
用户级: ~/.config/pi-agent/extensions/
项目级: .pi/extensions/
每个扩展一个目录,含 manifest.json 与代码3. 最小扩展示例
# ~/.config/pi-agent/extensions/hello/
# manifest.json
{
"name": "hello",
"version": "1.0.0",
"description": "示例扩展",
"entry": "index.js"
}
# index.js
module.exports = {
name: "hello",
// 注册自定义工具
tools: [{
name: "get_time",
description: "获取当前时间",
execute: async (args, ctx) => {
return new Date().toLocaleString();
}
}],
// 注册斜杠命令
commands: [{
name: "hello",
description: "打招呼",
handler: async (args, ctx) => {
ctx.say("Hello from extension!");
}
}]
};4. 启用扩展
/extensions 查看已加载扩展
/extensions enable hello
/extensions disable hello
# 使用扩展命令
> /hello
> 现在几点?(Agent 会调用 get_time 工具)5. 扩展开发要点
1. manifest.json 声明元数据
2. 入口文件导出注册函数
3. 工具描述写清楚,利于模型调用
4. 错误处理要完善
5. 用 ctx 访问会话上下文与工具Pi Agent 自定义工具开发
Pi Agent 自定义工具开发
自定义工具让 Agent 获得新能力,如查询内部系统、调用公司 API。
1. 工具定义结构
// 一个工具 = 描述 + 参数 schema + 执行函数
{
name: "search_products",
description: "搜索商品库,返回匹配商品列表",
parameters: {
type: "object",
properties: {
keyword: { type: "string", description: "搜索关键词" },
limit: { type: "number", description: "返回条数", default: 10 }
},
required: ["keyword"]
},
execute: async ({ keyword, limit }, ctx) => { ... }
}2. 完整示例:查询天气
// extensions/weather/index.js
const fetch = require("node-fetch");
module.exports = {
name: "weather",
tools: [{
name: "get_weather",
description: "查询指定城市的天气情况",
parameters: {
type: "object",
properties: {
city: { type: "string", description: "城市名,如 北京" }
},
required: ["city"]
},
async execute({ city }, ctx) {
const resp = await fetch(
`https://wttr.in/${encodeURIComponent(city)}?format=3`
);
const text = await resp.text();
return text.trim();
}
}]
};3. 工具上下文(ctx)
ctx 提供的能力:
ctx.say(text) // 向用户输出
ctx.runCommand(cmd) // 执行命令
ctx.readFile(path) // 读文件
ctx.writeFile(path, content) // 写文件
ctx.getProjectDir() // 项目目录
ctx.setData(key, val) // 会话内缓存
ctx.getData(key)4. 注册与测试
# 重启或 /reload 后生效
> /extensions reload
# 测试
> 北京今天天气怎么样?
Pi: 正在查询天气... [调用 get_weather]
北京: +28°C 晴5. 最佳实践
1. description 写清用途,模型才能正确调用
2. 参数 schema 详细,必填参数明确
3. 返回结构化文本或 JSON
4. 失败返回友好错误信息
5. 敏感操作前请求用户确认
6. 工具越聚焦越好,一个工具一件事Pi Agent 事件系统
Pi Agent 事件系统
事件系统允许扩展在关键节点执行钩子,实现日志、监控、拦截等能力。
1. 事件类型
对话事件:
session.start 会话开始
session.end 会话结束
message.before 消息发送前
message.after 消息响应后
工具事件:
tool.before 工具调用前
tool.after 工具调用后
tool.error 工具出错
文件事件:
file.read 读取文件
file.write 写入文件
file.delete 删除文件
命令事件:
command.before 命令执行前
command.after 命令执行后2. 事件监听示例
// extensions/audit/index.js
module.exports = {
name: "audit-log",
events: {
"tool.before": async ({ tool, args }, ctx) => {
console.log(`[${new Date().toISOString()}] 调用 ${tool}: ${JSON.stringify(args)}`);
},
"file.write": async ({ path }, ctx) => {
// 敏感文件拦截示例
if (path.endsWith(".env")) {
throw new Error("禁止修改 .env 文件");
}
},
"message.after": async ({ response }, ctx) => {
// 统计 token
const tokens = estimateTokens(response);
ctx.setData("totalTokens", (ctx.getData("totalTokens") || 0) + tokens);
}
}
};3. 拦截与放行
// 事件处理函数可抛出错误阻止操作
events: {
"command.before": async ({ command }) => {
if (command.includes("rm -rf")) {
throw new Error("检测到危险命令,已拦截");
}
}
}4. 事件与上下文
// 在事件中访问会话数据
events: {
"session.start": async (data, ctx) => {
ctx.setData("startTime", Date.now());
ctx.say("会话开始,欢迎!");
},
"session.end": async (data, ctx) => {
const duration = Date.now() - ctx.getData("startTime");
console.log(`会话时长: ${duration}ms`);
}
}5. 应用场景
1. 操作审计与安全拦截
2. 用量统计与成本监控
3. 自定义日志与告警
4. 自动化工作流(如自动提交)
5. 团队合规检查Pi Agent 命令与快捷键注册
Pi Agent 命令与快捷键注册
扩展可以注册自定义斜杠命令与快捷键,扩展交互入口。
1. 注册斜杠命令
// extensions/git-helper/index.js
module.exports = {
name: "git-helper",
commands: [{
name: "pr", // /pr
description: "基于当前分支创建 PR 描述",
args: [{ name: "target", required: false, description: "目标分支" }],
async handler({ target = "main" }, ctx) {
const diff = await ctx.runCommand("git diff origin/" + target + "...HEAD");
const prompt = `根据以下 diff 生成 PR 描述:
${diff}`;
return ctx.askAI(prompt); // 调用模型
}
}]
};2. 命令参数解析
commands: [{
name: "deploy",
description: "部署到指定环境",
args: [
{ name: "env", required: true, choices: ["dev", "prod"] },
{ name: "tag", required: false }
],
async handler({ env, tag = "latest" }, ctx) {
await ctx.runCommand(`deploy.sh --env ${env} --tag ${tag}`);
ctx.say(`已部署到 ${env}(${tag})`);
}
}]
// 使用: /deploy prod --tag v1.2.03. 注册快捷键
// 扩展注册快捷键
module.exports = {
name: "shortcuts",
keybindings: [{
keys: ["Ctrl+Alt+D"],
description: "快速部署",
action: async (ctx) => {
await ctx.runCommand("npm run deploy");
}
}]
};4. 命令帮助与发现
> /help
自定义命令:
/pr 基于当前分支创建 PR 描述
/deploy 部署到指定环境
/hello 打招呼
# 命令自动补全(Tab)
> /de[Tab] → /deploy5. 最佳实践
1. 命令名简短、语义清晰
2. description 帮助用户理解
3. 参数尽量可选并给默认值
4. 处理异常并给出提示
5. 支持 --help 说明用法Pi Agent 包管理
Pi Agent 包管理
Pi Agent 提供扩展与技能的包管理,方便安装、更新与卸载。
1. 技能包管理
# 安装技能
> /skill install python-setup
# 从市场搜索
> /skill search "测试"
找到 3 个技能:
- unit-testing: 生成单元测试
- e2e-testing: 端到端测试
- coverage: 覆盖率分析
# 卸载
> /skill remove unit-testing2. 扩展包管理
# 安装扩展
> /extensions install audit-log
# 从本地目录安装
> /extensions install /path/to/ext
# 更新
> /extensions update all
# 卸载
> /extensions uninstall audit-log3. 包源配置
{
"packages": {
"registry": "https://pi-agent.dev/registry", // 官方源
"allowPrivate": true, // 允许私有源
"scopes": ["@company"] // 私有 scope
}
}4. 离线安装
# 打包
pi pack ./my-skill -o my-skill.pi
# 安装
> /skill install ./my-skill.pi
# 导出发送
pi pack --all -o backup/
# 其他机器
pi import backup/5. 依赖管理
# 扩展的 package.json 声明依赖
{
"name": "weather",
"dependencies": {
"node-fetch": "^3.0.0"
}
}
# 安装时自动解析依赖
# 更新时检查兼容性Pi Agent 多平台部署
Pi Agent 多平台部署
Pi Agent 除了终端使用,还可以部署到服务器、CI、Docker 等环境。
1. 服务器部署(无头模式)
# 安装
npm install -g pi-agent
# 环境变量配置(避免交互)
export PI_AGENT_PROVIDER=deepseek
export DEEPSEEK_API_KEY=sk-xxx
export PI_AGENT_NONINTERACTIVE=1
# 使用
cd /opt/project
pi "检查代码并运行测试"2. Docker 部署
# Dockerfile
FROM node:20-alpine
RUN npm install -g pi-agent
WORKDIR /workspace
ENTRYPOINT ["pi"]
# 运行
docker build -t pi-agent .
docker run --rm -v $(pwd):/workspace -e DEEPSEEK_API_KEY=sk-xxx pi-agent "分析这个项目"3. CI/CD 集成(GitHub Actions)
# .github/workflows/ai.yml
name: AI Code Review
on: pull_request
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm install -g pi-agent
- name: AI Review
env:
DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
run: |
pi --json "审查 PR 改动,列出问题与建议" > review.json
- name: Post Comment
run: |
# 用 gh 发布评论
gh pr comment "$PR_NUMBER" --body-file review.md4. 定时任务
# crontab 示例:每天检查依赖更新
0 9 * * * cd /opt/project && pi "检查依赖版本,有更新则列出" >> /var/log/pi-deps.log
# systemd timer 同样适用5. 多环境配置管理
# 每个环境独立配置文件
export PI_AGENT_CONFIG=/etc/pi-agent/prod.json
# prod.json
{
"provider": "deepseek",
"model": "deepseek-chat",
"autoApprove": false,
"allowedCommands": ["git", "npm", "node", "python"]
}Pi Agent 与 llama.cpp 本地模型
Pi Agent 接入 llama.cpp 本地模型
Pi Agent 可以对接 llama.cpp 运行的本地模型,数据不出本机,私密又省钱。
1. 安装 llama.cpp
# 源码编译
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make -j
# 或用包管理器
# brew install llama.cpp
# 下载模型(如 Qwen2.5-Coder)
wget https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct-GGUF/resolve/main/qwen2.5-coder-7b-instruct-q4_k_m.gguf2. 启动 OpenAI 兼容服务
# llama.cpp 提供 OpenAI 兼容 API
./llama-server -m qwen2.5-coder-7b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 8080 -c 8192
# 验证
curl http://127.0.0.1:8080/v1/models3. 配置 Pi Agent
{
"provider": "openai-compatible",
"baseUrl": "http://127.0.0.1:8080/v1",
"model": "qwen2.5-coder-7b-instruct",
"apiKey": "local" # 本地无需真实 Key
}
# 或命令行
pi --provider openai-compatible --base-url http://127.0.0.1:8080/v1 --model qwen2.5-coder-7b-instruct4. 其他本地推理引擎
Ollama:
ollama run qwen2.5-coder
# 配置: baseUrl http://127.0.0.1:11434/v1
LM Studio:
# 内置 OpenAI 兼容服务,端口 1234
vLLM:
# 高性能生产级,同样兼容 OpenAI API5. 本地模型优劣势
优势:
- 数据完全本地,隐私安全
- 无 API 费用,适合高频使用
- 无网络依赖
劣势:
- 需要较好硬件(GPU 更佳)
- 模型能力弱于云端大模型
- 上下文窗口受显存限制
建议:简单任务用本地,复杂任务用云端Pi Agent CLI 参考手册
Pi Agent CLI 参考手册
Pi Agent 命令行参数的完整参考。
1. 基本用法
pi [options] [prompt]
# 不带 prompt 进入交互模式
# 带 prompt 执行一次性任务2. 模型与提供商
--provider <name> 提供商(openai/deepseek/anthropic/ollama)
--model <name> 模型名
--base-url <url> 自定义 API 端点
--api-key <key> API Key(或用环境变量)
--profile <name> 使用配置 profile
--temperature <num> 温度 0-2
--max-tokens <num> 最大输出 token3. 上下文与文件
-f, --file <path> 附加文件(可多次)
-d, --dir <path> 附加目录说明
--ignore <pattern> 忽略文件(glob)
--cwd <path> 指定工作目录
--system <text> 覆盖系统提示词
--prompt-file <path> 从文件读取提示词4. 输出控制
--json JSON 输出
--quiet 静默(仅最终结果)
--no-stream 关闭流式
--verbose 详细日志
--debug 调试模式
-o, --output <path> 输出到文件5. 行为控制
--no-tools 禁用工具调用
--auto-approve 自动批准工具操作
--trust 信任当前项目
--non-interactive 非交互模式
--timeout <sec> 超时时间
--retries <num> 失败重试次数6. 会话与配置
--session <name> 使用指定会话
--continue 继续上次会话
--config <path> 指定配置文件
config show 查看配置
config set <key> <val> 设置配置
--version 版本号
--help 帮助7. 示例汇总
pi # 交互
pi "写个快排" # 一次性
pi -f src/main.py "优化性能" # 带文件
pi --json "分析问题" # JSON
pi --profile smart "重构模块" # 用配置
pi --continue "继续刚才的任务" # 续会话Pi Agent 配置参考手册
Pi Agent 配置参考手册
config.json 完整配置项参考。
1. 模型配置
{
"provider": "deepseek", // 默认提供商
"apiKey": "", // 密钥
"model": "deepseek-chat", // 默认模型
"baseUrl": "", // API 地址
"temperature": 0.7,
"maxTokens": 4096,
"stream": true,
"timeout": 120,
"profiles": { // 多配置档
"fast": { "model": "deepseek-chat" },
"smart": { "model": "gpt-4o" }
}
}2. 交互与界面
{
"theme": { "name": "dark" },
"keybindings": {},
"prompt": {
"showModel": true,
"showTokens": false
},
"multiline": {
"enabled": false,
"trigger": "/multiline"
},
"history": {
"enabled": true,
"maxEntries": 100
}
}3. 安全与权限
{
"autoApprove": false,
"confirmCommands": true,
"allowedCommands": ["git", "npm"],
"blockedCommands": ["rm -rf"],
"defaultTrust": "ask",
"sandbox": { "env": {} },
"audit": { "enabled": true, "path": "logs/audit.log" }
}4. 会话与记忆
{
"session": {
"autoSave": true,
"autoSaveInterval": 60,
"maxHistory": 50,
"storageDir": ".pisession"
},
"memory": {
"enabled": true,
"file": ".pi/memory.md",
"maxTokens": 2000
}
}5. 扩展与技能
{
"extensions": {
"dir": "~/.config/pi-agent/extensions",
"enabled": ["audit-log", "weather"]
},
"skills": {
"dir": "~/.config/pi-agent/skills",
"autoTrigger": true
},
"packages": {
"registry": "https://pi-agent.dev/registry"
}
}6. 网络与代理
{
"httpProxy": "",
"httpsProxy": "",
"noProxy": "",
"request": {
"maxRetries": 3,
"retryDelay": 1000,
"concurrency": 4
}
}Pi Agent 支持的 AI 提供商
Pi Agent 支持的 AI 提供商
Pi Agent 支持多家 AI 提供商,可按需求灵活切换。
1. 云端服务商
OpenAI
provider: openai
model: gpt-4o / gpt-4o-mini / o3-mini
环境变量: OPENAI_API_KEY
DeepSeek
provider: deepseek
model: deepseek-chat / deepseek-coder / deepseek-reasoner
环境变量: DEEPSEEK_API_KEY
Anthropic
provider: anthropic
model: claude-sonnet-4 / claude-opus-4
环境变量: ANTHROPIC_API_KEY
Google
provider: google
model: gemini-pro
环境变量: GOOGLE_API_KEY
阿里云通义
provider: dashscope
model: qwen-max / qwen-plus
环境变量: DASHSCOPE_API_KEY
智谱 GLM
provider: zhipu
model: glm-4
环境变量: ZHIPU_API_KEY2. 兼容 OpenAI 协议的服务
provider: openai-compatible + baseUrl
Ollama: http://127.0.0.1:11434/v1
llama.cpp: http://127.0.0.1:8080/v1
LM Studio: http://127.0.0.1:1234/v1
vLLM: http://your-server:8000/v1
Moonshot: https://api.moonshot.cn/v1
Minimax: https://api.minimaxi.com/v13. 配置示例
# 使用 ollama 本地模型
pi --provider openai-compatible --base-url http://127.0.0.1:11434/v1 --model qwen2.5-coder:7b4. 选择建议
日常编码: DeepSeek(性价比高)/ OpenAI
复杂推理: OpenAI o 系列 / Anthropic
本地私密: Ollama + Qwen2.5-Coder
国内稳定: DeepSeek / 通义 / GLM
企业合规: 私有化部署 + vLLM5. 故障排查
1. 401: Key 无效或 provider 配置错
2. 429: 限流,降低频率或换模型
3. 404: model 名不对
4. 超时: 检查网络/代理
5. 总是报错: pi --debug 查看详细日志Pi Agent 见问题排查
Pi Agent 常见问题排查
汇总 Pi Agent 使用中常见问题的解决方法。
1. 安装问题
问题: npm install -g pi-agent 失败
解决:
- 检查 Node 版本 ≥ 18
- 设置镜像 npm config set registry https://registry.npmmirror.com
- 查看错误日志 npm install -g pi-agent --loglevel verbose2. 启动问题
问题: 运行 pi 报错
解决:
- pi --version 检查安装
- 检查配置文件语法(JSON 校验)
- 查看日志: ~/.config/pi-agent/logs/error.log
- 重置配置: mv ~/.config/pi-agent ~/.config/pi-agent.bak3. 连接/认证问题
问题: 401 Unauthorized
解决:
- 检查 API Key 是否正确
- 确认 provider 与 Key 匹配
- Key 是否有余额/权限
问题: 连接超时
解决:
- 检查网络与代理(HTTPS_PROXY)
- baseUrl 是否正确
- 防火墙是否放行4. 模型响应问题
问题: 响应乱码
解决: 检查终端编码(UTF-8)
问题: 响应被截断
解决: 调大 maxTokens
问题: 回答不准确
解决:
- 提供更多上下文(-f 附加文件)
- 切换更强的模型
- 明确指令与约束5. 工具执行问题
问题: 命令被拒绝执行
解决: 检查信任状态与命令白名单
问题: 文件操作被拒
解决: /trust 信任项目
问题: 工具报错
解决: 查看工具输出,修复后重试(/r)6. 性能问题
问题: 响应很慢
解决:
- 换更快的模型(deepseek-chat)
- 减少附加文件大小
- /compact 压缩上下文
- 检查网络延迟7. 调试技巧
pi --debug "任务" # 详细日志
pi --verbose # 完整请求信息
> /context # 上下文占用
> /audit # 操作记录
查看日志目录排查Pi Agent 斜杆命令手册
Pi Agent 斜杠命令手册
斜杠命令是会话内的控制指令,以 / 开头。
1. 基础控制
/help 显示帮助
/clear 清空对话历史
/quit 退出(或 Ctrl+D)
/system 设置系统提示词
/multiline 多行输入模式
/end 结束多行输入2. 模型与提供商
/model <name> 切换模型
/provider <name> 切换提供商
/profile <name> 切换配置档
/temperature <num> 设置温度
/tokens 查看 token 统计3. 上下文管理
/context 查看上下文占用
/context set <n> 设置上下文上限
/compact 压缩历史
/forget <topic> 忘记指定话题
/memory 查看项目记忆
/remember <txt> 添加记忆4. 会话管理
/save [name] 保存会话
/load [name] 恢复会话
/sessions 列出会话
/export [file] 导出对话
/rename <name> 重命名会话
/delete <name> 删除会话5. 安全与信任
/trust 信任当前项目
/untrust 取消信任
/audit 查看审计日志
/permissions 查看权限配置
/allow <cmd> 添加命令白名单
/deny <cmd> 添加命令黑名单6. 扩展与技能
/skills 列出技能
/skill install <name> 安装技能
/skill remove <name> 移除技能
/extensions 列出扩展
/extensions reload 重载扩展
/prompt <name> 调用提示词模板7. 界面与主题
/theme [name] 切换主题
/keybindings 查看快捷键
/font 调整字体
/clear-screen 清屏(Ctrl+L)8. 调试
/debug 开启调试模式
/verbose 详细输出
/status 状态信息(版本/模型/环境)
/retry 重试上一条(/r)Pi Agent 总结与生态
Pi Agent 总结与生态
回顾 Pi Agent 的核心能力,并了解周边生态与学习资源。
核心能力回顾
1. 终端 AI 编程代理:自然语言驱动开发
2. 多模型支持:云端 + 本地灵活切换
3. 工具系统:文件/命令/Git 全流程
4. Skills 技能:可复用能力包
5. 扩展体系:自定义工具/命令/事件
6. 安全机制:信任、白名单、审计
7. 会话与记忆:长任务与项目上下文典型工作流
日常编码:
pi "实现用户登录接口"
→ Agent 创建文件 → 写代码 → 运行测试
代码审查:
pi -f src/app.js "审查这段代码"
→ 分析问题 → 给出建议 → 可一键修复
项目维护:
pi "看看最近的 bug,给我修复方案"
→ 读取代码 → 定位问题 → 修改验证
批量任务:
for f in src/*.js; do pi -f $f "重构"; done周边生态
同类工具: Claude Code / OpenAI Codex / Aider
模型生态: DeepSeek / Qwen / Llama 本地模型
集成: CI/CD、IDE(插件开发中)、Docker
社区: GitHub 讨论、Discord、开发者文档学习路径建议
1. 掌握交互模式与常用命令
2. 学会配置多模型与代理
3. 为项目写记忆文件提升效果
4. 沉淀个人 Skills 与提示词模板
5. 进阶:开发自定义扩展/工具
6. 生产环境:接入 CI、权限与审计最佳实践清单
✓ 每次任务目标明确
✓ 关键文件用 -f 提供
✓ 敏感操作保持手动确认
✓ 长任务定期 /compact
✓ 重要项目写 memory.md
✓ 团队统一 Skills 与模板
✓ 定期查看审计日志第 1 / 30 节