Pi Agent: 包管理
最后更新：2026-08-31
包是技能和工具的"快递箱"——封装好，一键安装，团队共享。
1. 什么是 Pi Agent 包
包（Package）是技能、工具、模板和配置的分发表：
TEXT
📖 仅展示
包 vs 扩展 vs 技能
├── 技能 → 单一能力（如 code_review）
├── 扩展 → 插件（含工具+技能+钩子）
└── 包 → 分发载体（可包含多个扩展+技能+模板）
2. 包管理命令
(1) 搜索包
BASH
pi-agent pkg search code-review
pi-agent pkg search --category devops
pi-agent pkg search --author alice
(2) 安装包
BASH
pi-agent pkg install code-review-tools
pi-agent pkg install devops-toolkit@1.2.0
pi-agent pkg install git+https://github.com/user/my-pkg.git
(3) 管理已安装包
BASH
pi-agent pkg list # 列出已安装包
pi-agent pkg info code-review-tools # 查看包详情
pi-agent pkg update # 更新所有包
pi-agent pkg update devops-toolkit # 更新指定包
pi-agent pkg remove code-review-tools # 卸载包
3. 创建包
(1) 包结构
TEXT
📖 仅展示
my-dev-tools/
├── pkg.yaml # 包描述文件
├── tools/
│ ├── git_helper.py
│ └── docker_tool.py
├── skills/
│ ├── code_review.yaml
│ └── deploy.yaml
├── templates/
│ └── commit_msg.yaml
└── tests/
└── test_tools.py
(2) pkg.yaml
YAML
name: my-dev-tools
version: "1.0.0"
description: "开发工具集"
author: "Alice"
license: "MIT"
repository: "https://github.com/alice/my-dev-tools"
min_pi_agent_version: "0.8.0"
dependencies:
- git-tools>=1.0.0
tools:
- tools/git_helper.py
- tools/docker_tool.py
skills:
- skills/code_review.yaml
- skills/deploy.yaml
templates:
- templates/commit_msg.yaml
categories:
- development
- devops
tags:
- git
- docker
- code-review
4. 版本管理
(1) 语义化版本
Pi Agent 包遵循 SemVer 规范：
TEXT
📖 仅展示
主版本.次版本.修订版本
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
主版本：不兼容的 API 变更
次版本：向下兼容的功能新增
修订版本：向下兼容的 Bug 修复
(2) 版本约束
YAML
dependencies:
- git-tools>=1.0.0 # 1.0.0 或更高
- docker-tools~=2.1 # 2.1.x（兼容 2.1）
- utils>=1.0,<2.0 # 1.x 系列
5. 发布包
(1) 打包
BASH
pi-agent pkg build my-dev-tools
# 生成 dist/my-dev-tools-1.0.0.tar.gz
(2) 发布到官方仓库
BASH
pi-agent pkg publish my-dev-tools
(3) 发布到 Git
BASH
git tag v1.0.0
git push origin v1.0.0
▶ 示例 1：完整发布流程（难度⭐⭐）
BASH
# 1. 验证包
pi-agent pkg validate my-dev-tools
# 2. 运行测试
pi-agent pkg test my-dev-tools
# 3. 构建包
pi-agent pkg build my-dev-tools
# 4. 发布
pi-agent pkg publish my-dev-tools
# 5. 验证安装
pi-agent pkg install my-dev-tools
pi-agent pkg info my-dev-tools
6. 包仓库
(1) 官方仓库
BASH
pi-agent pkg search --repo official
(2) 第三方仓库
YAML
# ~/.pi-agent/config.yaml
package_repos:
- name: official
url: "https://pkg.pi-agent.dev"
- name: company
url: "https://pkg.internal.company.com"
auth: token
(3) 私有仓库
BASH
pi-agent pkg install my-internal-pkg --repo company
Bob 的经验："团队内部建个私有仓库，把常用技能打包上传，新同事入职一条命令装齐。"
❓ 常见问题
Q 包和扩展有什么区别？
A 包是分发载体，扩展是运行时插件。一个包可以包含多个扩展。包侧重"分发和版本管理"，扩展侧重"功能加载"。
Q 包有依赖冲突怎么办？
A Pi Agent 使用类似 pip 的依赖解析器。如果冲突无法自动解决，会提示手动指定版本。
Q 如何更新包而不破坏现有配置？
A 次版本和修订版本更新是向下兼容的，直接
pi-agent pkg update 即可。主版本更新需要查看 CHANGELOG。📖 小节
- 包是技能、工具、模板的分发载体
- pkg.yaml 定义包元数据，支持依赖声明
- 语义化版本管理，约束语法与 pip 类似
- 支持官方仓库和私有仓库
- 完整的搜索、安装、更新、卸载、发布流程
📝 作业
- 基础题（难度⭐）：搜索并安装一个社区包，使用其提供的技能。
- 进阶题（难度⭐⭐）：创建一个包含 2 个工具和 1 个技能的包，本地安装测试。
- 挑战题（难度⭐⭐⭐）：为你的团队搭建私有包仓库，发布并安装内部工具包。
