Pi Agent: 扩展入门
最后更新：2026-08-31
扩展让 Pi Agent 从"够用"变成"好用"——别人写的扩展拿来用，自己写的扩展发出去。
1. 什么是扩展
扩展（Extension）是 Pi Agent 的插件机制，可以：
- 添加新的工具
- 添加新的技能
- 添加新的 LLM 提供商
- 添加新的命令
- 修改 Agent 行为
TEXT
📖 仅展示
扩展结构
├── manifest.yaml → 元数据（名称、版本、依赖）
├── tools/ → 工具定义
├── skills/ → 技能定义
├── providers/ → 提供商适配器
├── hooks/ → 钩子函数
└── templates/ → 提示词模板
2. 安装扩展
(1) 从官方仓库安装
BASH
pi-agent ext install github-tools
pi-agent ext install database-query
(2) 从 Git 仓库安装
BASH
pi-agent ext install git+https://github.com/user/pi-ext-custom.git
(3) 从本地目录安装
BASH
pi-agent ext install ./my_extension
(4) 管理已安装的扩展
BASH
pi-agent ext list # 列出已安装扩展
pi-agent ext update github-tools # 更新扩展
pi-agent ext remove github-tools # 卸载扩展
3. 创建扩展
(1) 脚手架
BASH
pi-agent ext create my_extension
生成目录结构：
TEXT
📖 仅展示
my_extension/
├── manifest.yaml
├── tools/
│ └── example.py
├── skills/
│ └── example.yaml
└── README.md
(2) manifest.yaml
YAML
name: my_extension
version: "1.0.0"
description: "我的自定义扩展"
author: "Alice"
min_pi_agent_version: "0.8.0"
dependencies:
- requests>=2.28.0
tools:
- tools/my_tool.py
skills:
- skills/my_skill.yaml
entry_point: hooks.py
(3) 定义工具
PYTHON
# tools/my_tool.py
from pi_agent import tool
@tool(
name="weather_query",
description="查询指定城市的天气信息",
parameters={
"city": {"type": "string", "description": "城市名称"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
}
)
def weather_query(city: str, unit: str = "celsius") -> dict:
import requests
resp = requests.get(f"https://wttr.in/{city}?format=j1")
data = resp.json()
temp = data["current_condition"][0]["temp_C"]
if unit == "fahrenheit":
temp = int(temp) * 9 // 5 + 32
return {"city": city, "temperature": temp, "unit": unit}
(4) 定义技能
YAML
# skills/my_skill.yaml
name: weather_advisor
description: "天气顾问，根据天气给出建议"
system_prompt: |
你是天气顾问，根据天气数据给出穿衣建议和出行提醒。
tools:
- weather_query
parameters:
temperature: 0.5
4. 扩展生命周期
(1) 钩子函数
PYTHON
# hooks.py
from pi_agent import ExtensionHook
class MyExtension(ExtensionHook):
def on_load(self, agent):
"""扩展加载时调用"""
print(f"✅ {agent.name} 已加载 my_extension")
def on_tool_call(self, agent, tool_name, params):
"""工具调用前调用"""
print(f"🔧 调用工具: {tool_name}")
def on_tool_result(self, agent, tool_name, result):
"""工具调用后调用"""
print(f"✅ 工具结果: {tool_name} → {result}")
def on_error(self, agent, error):
"""错误时调用"""
print(f"❌ 错误: {error}")
def on_unload(self, agent):
"""扩展卸载时调用"""
print(f"👋 my_extension 已卸载")
5. 发布扩展
(1) 打包
BASH
pi-agent ext package my_extension
# 生成 my_extension-1.0.0.tar.gz
(2) 发布到官方仓库
BASH
pi-agent ext publish my_extension
(3) 发布到 PyPI
BASH
cd my_extension
python -m build
twine upload dist/*
❓ 常见问题
Q 扩展和技能有什么区别？
A 技能是单个能力单元（一个提示词+工具组合），扩展是完整的插件包（可以包含多个工具、技能、提供商适配器、钩子等）。
Q 扩展之间的依赖怎么处理？
A 在 manifest.yaml 的 dependencies 中声明，Pi Agent 会自动解析和安装依赖。
Q 扩展有安全审查吗？
A 官方仓库的扩展经过审查。第三方扩展需要自行评估风险，建议在沙箱中先测试。
📖 小节
- 扩展是 Pi Agent 的插件机制，可添加工具、技能、提供商、命令
pi-agent ext install安装，pi-agent ext create创建- manifest.yaml 定义扩展元数据，tools/ 和 skills/ 放功能代码
- 钩子函数处理扩展生命周期事件
- 可发布到官方仓库或 PyPI
📝 作业
- 基础题（难度⭐）：安装一个官方扩展并使用其提供的工具。
- 进阶题（难度⭐⭐）：创建一个简单的天气查询扩展，包含工具和技能。
- 挑战题（难度⭐⭐⭐）：创建一个完整的扩展，包含工具、技能、钩子函数和单元测试。
