Plugin 是一组可分发的 skills、hooks、agents 或 MCP 配置。命令行接受的插件 ID 格式是 name@marketplace；安装命令一次只接收一个插件。
注册 Marketplace
peri plugin marketplace add user/repository
peri plugin marketplace list
peri plugin marketplace update <marketplace-name>
peri plugin marketplace remove <marketplace-name>来源可以是 GitHub 简写、URL 或本地路径。第三方 marketplace 中的内容不是 Peri 核心仓库的一部分，安装前应检查来源和脚本。
查找与安装
peri plugin search <关键词>
peri plugin info <name@marketplace>
peri plugin install <name@marketplace> --scope user可用 scope：
| Scope | 用途 |
|---|---|
user |
当前用户的多个项目共享 |
project |
随项目配置使用 |
local |
只在本机当前项目使用 |
要安装多个插件，逐条运行 peri plugin install。把多个名称放在同一条命令后会被 CLI 拒绝。
生命周期
peri plugin list
peri plugin list --json
peri plugin disable <name@marketplace> --scope user
peri plugin enable <name@marketplace> --scope user
peri plugin update <name@marketplace>
peri plugin uninstall <name@marketplace>
peri plugin cleanupcleanup 用于清理 7 天未使用的孤儿插件文件；它不等同于卸载仍在配置中引用的插件。
生效与安全
插件可能同时改变 Agent 指令、hook 行为和 MCP 工具面。安装或更新后重新启动 Peri，再分别检查 /plugin、/hooks 与 /mcp。不要把“插件已安装”当作所有组成部分都已成功连接。
插件内容以 Peri 进程的用户权限运行或影响 Agent 决策。安装前审查来源；不要把 API key 写进插件仓库；高风险插件先在临时项目和 Default 权限模式下验证。