内容
# Pireel 代理插件
连接 **Codex**、**Claude Code** 或任何支持 MCP 的代理到 [Pireel Studio](https://pireel.com) — 一款用于谈话式视频的 AI 视频编辑器（画布跟随您的源视频）。您的代理获得完整的 Studio 工具集：基于文本的剪辑、故事板、设计图形、字幕、主题和本地媒体导入。
当工作室选项卡打开时，编辑实时应用到画布上。当它关闭时，数据级工具继续在云项目上工作（离线模式）；依赖视频的工具会要求打开选项卡。
托管设置指南（代理可读）：**https://pireel.com/connect-agent.md**
## 安装
### 最快捷 — 任意代理（Codex、Claude Code、Cursor、Cline、Gemini CLI…）
```bash
npx skills add pireel/pireel-agent
```
这安装了一个单独的 `pireel` 技能（其详细的剧本作为按需 `references/` 打包，因此您的技能列表保持干净 — 一条记录，而不是十条）。然后告诉您的代理 **"设置 Pireel"** — 该技能注册 MCP 服务器，驱动 OAuth 登录，并导入您的第一个视频。
### Codex（插件市场）
```bash
codex plugin marketplace add https://github.com/pireel/pireel-agent
codex plugin install pireel
codex mcp login pireel # 浏览器中进行 OAuth 登录
```
### Claude Code（仅 MCP）
```bash
claude mcp add --transport http pireel https://pireel.com/api/studio/mcp
```
Claude Code 在首次使用时提示进行 OAuth 登录。对于 `pireel` 技能，请使用上面的 `npx skills add` 或将 `pireel/skills/pireel/` 复制到 `.claude/skills/`。
## 更新
运行 `npx skills update pireel`（或重新运行 `npx skills add pireel/pireel-agent`）；Codex 用户可以通过插件市场进行更新。还有一个内置的提示：连接时，Pireel MCP 服务器会宣布其当前的技能基准，如果您安装的技能较旧，代理会提示您更新。
## 验证
要求代理调用 `get_state`：
- 组成快照 → 连接到实时工作室选项卡。
- `OFFLINE MODE` 快照 → 已连接；直接编辑最新的云项目。
- `no cloud project` → 已连接；导入视频或创建项目以开始。
## 导入本地视频
指向代理到本地文件路径 — 导入流程（`references/asset-import.md`）上传它（内容寻址，≤ 2 GB），在 `ffmpeg` 可用时探测元数据和转录音频，并注册项目。基于文本的编辑在打开任何浏览器之前立即生效。
## 计费
代理编排和每个 BYO 流程（`compose_block_brief` → 生成 → `apply_block`，`plan_brief` → `submit_plan`，`visual_brief` → `submit_visual`）都在 **您的代理订阅** 上运行，而不是 Pireel 积分。只有描述中带有 `[…CHARGES…]` 标记的工具才会扣除 Pireel 积分（图像/视频生成和 Pireel-LLM 回退）。
## 内部
- `pireel/.mcp.json` — MCP 服务器注册（OAuth）。
- `pireel/skills/pireel/SKILL.md` — 单个 `pireel` 技能：基本 + 路由到捆绑的引用（保持您的技能列表为一条记录）。
- `pireel/skills/pireel/references/` — 技能按需读取的剧本：`getting-started`（首次运行 MCP 连接 + OAuth + 首次导入），`pireel-basics`（模型 + 工具路由），`asset-import`，`talking-head-cleanup`，`compose-blocks`，`storyboard-draft`，`captions`，`export`，`product-help`，`known-errors`。
- `pireel/skills/pireel/scripts/import-media.mjs` — 本地媒体导入助手（Node ≥ 20，无依赖）。
## 许可证
Apache-2.0 — 请参阅 [LICENSE](./LICENSE)。 Pireel 版权所有。
