Fotor 图像视频 fotor-ai/fotor-agent-plugins

Fotor Plugin for Agents

用 Fotor 生成图片和视频，直接在 AI 智能体里完成。

智能体 ·功能 · Codex 配置 · Claude Code 配置 · Cursor 配置 · Pi 配置 · DeepSeek Harness 配置 ·文档

支持的智能体

| 智能体 | 状态 | 快速上手 |
| Codex | 已内置 | 安装并连接 |
| Claude Code | 已内置 | 安装并连接 |
| Cursor | 已内置 | 安装并连接 |
| Grok Bot | 通过 Cursor 包接入 | 安装并连接 |
| Pi | 已内置 | 安装并连接 |
| DeepSeek Harness | 独立仓库；外部桥接 | 安装并连接 |

本次快照包含 Codex、Claude Code、Cursor 和 Pi。安装和线上服务验收是两项独立检查，具体范围见下文验证说明。

两个发布通道都连接 Fotor 的生产服务和网站。测试通道用于预览插件改动，消耗的是你的生产账号和额度。
每个技能都自带四份运行时参考文档。平台安装、MCP 注册以及外部桥接配置，仍需单独作为前置条件完成。

功能

| 能力 | 你可以做什么 |
| 图片 | 生成图片，或用提示词和参考图编辑图片。 |
| 视频 | 用文本、帧或支持的媒体参考生成视频。 |
| 媒体上传 | 上传本地图片、视频和音频，供后续复用。 |
| 图片处理 | 放大图片、去除背景。 |
| 网站连接 | 用你授权的 MCP 身份打开 Fotor。 |
| 额度 | 查看现有额度，并按平台额度政策理解返回的限制说明。 |
| 任务结果 | 查看已提交的任务，获取可用结果。 |

可用模型、参数和操作由所连接的 Fotor 服务提供。

Codex

安装

请使用支持插件、且能访问这个公开仓库的 Codex 版本。安装公开包不需要登录 GitHub。如果 fotor-ai 已从其他来源注册过，请按切换发布通道操作。

正式发布版

从默认的 main 分支安装已发布的插件，无需选择分支。

codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git
codex plugin add fotor@fotor-ai

连接

1. 检查已安装的插件和启用状态：

codex plugin list --marketplace fotor-ai --json

2. 确认已安装包中的版本为 0.5.1、发布通道为 production、MCP 端点为 production 的 https://mcp.fotor.com/mcp。授权前先检查是否有单独设置的 Fotor MCP 覆盖项，它必须使用同一个 production 端点。
3. 新建一个 Codex 任务，输入：

Connect to Fotor and introduce its main features.

有效凭据会被复用。需要授权时，在外部浏览器完成 Codex 的登录流程，然后在本地化确认提示中选择「已登录并授权；在应用内浏览器打开 Fotor」。你也可以选择继续等待或取消。Codex 确认授权后，插件会在可见的应用内浏览器中打开网站登录链接。验证方式和手动兜底方案见连接工作流。

如果只想做只读检查、不打开网站，请输入：Check only the Fotor MCP connection.

更新

从当前选中的通道刷新并重新安装：

codex plugin marketplace upgrade fotor-ai
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

新建任务，确认版本、启用状态和端点。更新会保留已选分支；要切换通道，请用下一节。
已有的 fotor-codex 安装需要做一次性迁移；fotor-ai 内部的普通更新走「更新」一节。

迁移会改变安装标识。动手删除任何东西之前，先记录旧的 source/ref、作用域、版本和启用状态，并确认目标目录确实声明了 fotor-ai。仍声明 fotor-codex 的 source 装不了 fotor@fotor-ai。用宿主支持的方式保留必需的插件数据。绝不要为了迁就迁移去复制 token 或清空凭据。

在其他带有目录的检出之外，只删除旧的 Fotor 安装及其注册：

codex plugin remove fotor@fotor-codex
codex plugin marketplace remove fotor-codex

删除会清掉旧的已安装缓存。然后对已验证的目标执行上面的安装命令。检查 codex plugin list --marketplace fotor-ai --json 和 marketplace 列表：应当只有一个 Fotor 安装处于启用状态，版本、source 和生产 MCP 声明都符合预期。打开新任务。如果迁移失败，先移除任何不完整的新安装，再通过原生控件恢复记录下来的旧 source/ref 和插件。已经完成的删除步骤跳过；重复整套流程前先查看当前状态。

标识变更后能否复用凭据，需要单独验证；不要承诺安装成功就一定保留授权。

切换发布通道

fotor-ai marketplace 只用一个 source。先选好目标，再执行下面其中一组替换命令。执行 source 变更时，要避开另一个含有相同 marketplace 目录的检出。

选择生产或测试发布通道

生产发布

从默认 main 分支安装已发布的插件。不需要选择分支。

codex plugin marketplace remove fotor-ai
codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

测试发布

从 release/test 安装测试构建，用于预发布验证。

codex plugin marketplace remove fotor-ai
codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --ref release/test
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

切换后，打开新任务，核对目标版本和生产 MCP 端点。复用有效的生产授权。如果旧安装或独立覆盖配置用的是另一个服务，先停下来，通过宿主的控件更新该配置再连接；不要自动迁移它的凭据。

故障排查

仓库访问、残留安装和登录
- 仓库访问： 确认 Git 能访问这个公开仓库。GitHub 访问和 Fotor MCP 授权是两回事；把凭据放在仓库 URL 和插件文件之外。
- 版本或端点不符合预期： 检查市场源，重新安装，再开一个新任务。同时检查已安装的 MCP 声明，以及任何独立的 Fotor 覆盖配置。
- 需要授权： 在外部浏览器里走所选服务商的原生登录流程。如果存在同名的独立服务商 fotor，命令行提供 codex mcp login fotor。
- 网站或媒体操作失败： 保留实际错误和任务 ID（如果有）。连接、浏览器登录、媒体执行是三件独立的事，结果各自计算；参见下面的工作流参考。

Claude Code

Claude Code 安装

本指南面向支持插件和 Git 访问的 Claude Code 命令行。客户端验收基线是 2.1.296；其他命令行版本需要单独验证，Desktop/IDE 验收仍然暂缓。安装整个市场包即可，不需要解释器，也不需要构建步骤。

生产发布

从默认 main 分支安装已发布的插件。不需要选择分支。

claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --scope user
claude plugin install fotor@fotor-ai --scope user

开一个新的 Claude Code 会话。用 claude plugin list --json 检查 fotor@fotor-ai、版本 0.5.1 和启用状态。确认安装后的 .mcp.json 使用 https://mcp.fotor.com/mcp，连接前先解决冲突的主机覆盖配置。

Claude Code 连接

对智能体说 Connect to Fotor and introduce its main features. 也可以调用 /fotor:fotor-connect。只想做只读连接检查，就说 Check only the Fotor MCP connection.

用 /mcp 查看插件的服务商，通常是 plugin:fotor:fotor。复用 Claude 管理的有效 Fotor 凭据。原生状态要求登录时，用它提供的 Authenticate 操作，或使用支持的命令行入口：

claude mcp login plugin:fotor:fotor

在外部浏览器完成 OAuth，在本地化的 Continue / Wait / Cancel 提示里选 Continue，等客户端确认成功。在 Claude Code 命令行里，外部 OAuth 之后，用 Chrome 之类的外部浏览器打开一次已验证的交接链接；命令行打不开时，把未使用的链接复制到该浏览器手动打开。在 Claude Code Desktop 里，外部 OAuth 之后，用内置浏览器打开一次交接链接。所选浏览器的控制不可用时，说明这一限制，并提供未使用的链接和该浏览器的操作说明。手动交付不等于自动登录验证；Desktop 主机验收仍然单独进行。参见 Claude 认证与浏览器指引。
MCP 凭据仍保存在 Claude 支持的存储中。模型提问不会打开网站，建立连接也不会查询额度。声称成功之前，先核实网站的实际登录状态。

Claude Code 更新

刷新选定的源，更新包，然后启动新会话：

claude plugin marketplace update fotor-ai
claude plugin update fotor@fotor-ai
claude plugin list --json

核实已安装的版本、来源、启用状态和生产 MCP 端点。本地目录型 marketplace 直接读取文件，不走托管插件的缓存机制。缓存版本必须先改版本号，才能确认更新生效。

Claude Code marketplace 迁移

已有的 fotor-claude-code 安装需要一次性迁移到 fotor-ai。

迁移会改变安装身份。删除任何东西之前，先记录旧的 source/ref、scope、版本和启用状态，并确认目标目录确实声明了 fotor-ai。仍声明 fotor-claude-code 的源无法安装 fotor@fotor-ai。用宿主支持的控制手段保留必需的插件数据。绝不要为了迁就迁移而复制 token 或清除凭据。

下面的示例针对用户级安装。项目级/本地级安装请用原 scope 对应的控制手段；托管安装需要管理员操作。执行前先确认原生卸载命令支持 --keep-data。如果不支持，先停下来，用支持的控制手段保住需要的数据。

claude plugin uninstall fotor@fotor-claude-code --scope user --keep-data
claude plugin marketplace remove fotor-claude-code --scope user

--keep-data 保留旧插件的持久数据；它不会把这些数据、已保存的选项或凭据复制到新身份下。移除 marketplace 可能连带清掉剩余的插件状态，所以先检查选定的 scope。对核实过的目标执行上面的安装命令。检查 marketplace 源和 claude plugin list --json，确认只有一个启用的 fotor@fotor-ai，版本符合预期，生产 MCP 配置正确。然后启动新会话。

如果迁移失败，用同样的数据保留方式移除任何不完整的新安装，再恢复记录下来的旧 source/ref、scope 和插件。重试时先检查当前状态，已完成的移除步骤跳过。授权复用是另一项独立检查；不要清除或复制凭据。

Claude Code 渠道

两个渠道都使用生产 MCP 和额度。测试源固定为 release/test；稳定源使用 main。普通升级会保留所选分支。

显式替换用户级 marketplace 源删除 Claude 市场会卸载它的插件，还可能删掉插件保存的选项、密钥和数据。先检查当前作用域，保住需要的状态。只有你明确要更换来源时才用替换流程，绝不要把它当作日常的连接恢复或普通升级。下面的示例针对用户作用域；项目级或托管安装必须通过各自的控件处理。

生产版本

从默认 main 分支安装已发布的插件。不需要选分支。

claude plugin marketplace remove fotor-ai --scope user
claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --scope user
claude plugin install fotor@fotor-ai --scope user
claude plugin list --json

测试版本

从 release/test 安装测试构建，用于预发布验证。

claude plugin marketplace remove fotor-ai --scope user
claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git#release/test --scope user
claude plugin install fotor@fotor-ai --scope user
claude plugin list --json

用 claude plugin marketplace list --json 核对来源和分支，然后开一个新会话。保留现有的有效生产授权；不要从别的客户端复制 token，也不要为了绕过插件加载问题另建一个独立的 Fotor 服务器。

Cursor

Cursor 安装

本指南覆盖 Cursor IDE、Cursor CLI 和 Grok Bot，三者共用同一个 Cursor 包。使用完整包，包含 .cursor-plugin/plugin.json、mcp.json、技能、参考文档和资源。不需要解释器，也不需要构建步骤。Cursor Cloud Agent 的验收单独进行。

生产版本

先确认 main 里有 Cursor 目录和 plugins/cursor/fotor/ 包。用原生命令行注册选定的 Git 来源，然后打开 /plugin（显示该别名的客户端上是 /plugins），选 fotor-ai 并安装 Fotor。只注册不会安装插件。两个渠道都用生产 MCP 和账号。

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins
agent plugin marketplace list --format json
agent

命令行提供市场管理命令；安装要在它原生的 /plugin 界面里完成，不能通过 agent plugin install shell 命令。多个平台目录并存时，确认选中的包是 Cursor 包。账号级市场注册可能在本客户端配置之外也可见。

本地加载的替代方式

在 IDE 里本地加载：把选好的完整包复制到 ~/.cursor/plugins/local/fotor/，重载窗口，然后检查 Customize。必须允许本地导入。同名的已安装市场插件优先；测试前先确认实际来源。指向本地插件目录之外仓库的符号链接，不属于受支持的安装方式。

命令行本地加载：启动新的原生会话：

agent --plugin-dir /absolute/path/to/fotor

确认版本 0.5.1、启用状态、已发现的技能，以及已安装的 mcp.json 里的 https://mcp.fotor.com/mcp URL。连接前先解决冲突的宿主覆盖配置。市场安装和本地加载是两条独立路径；不要用 Codex 或 Claude 的命令替代。

Grok Bot 安装与授权

1. 在 Cursor 里从 fotor-ai 市场安装 Fotor，使用上面选定的 Git 来源。只在市场注册并不等于安装插件。请使用账号级安装；本地 IDE 文件夹和命令行 --plugin-dir 加载不会建立账号共享。
2. 用同一个 Cursor 账号登录 Grok Bot。打开 Connect Apps，选中已安装/已连接的列表，从 fotor-ai 里找到 Fotor。宿主暴露版本和来源时，核对版本 0.5.1 和来源；仅凭账号共享无法验证已加载的文件。
3. 连接需要授权时，选择原生的 Authorize / Authenticate 操作，在外部普通浏览器里完成登录和同意。回到 Grok Bot；在对话流程中选 Continue，并确认原生连接结果。有可用授权时直接复用。
4. 确认显示 Connected，查看可用工具，然后问 Check only the Fotor MCP connection. 只读调用成功即验证了访问权限。这个请求不会打开网站，也不查询余额。

如果找不到 Fotor，通过原生控件检查账号、安装范围和团队策略。请使用 Grok Bot 自带的连接器控件，不要用本地命令行认证或复制 token。网站请求使用它实际可见的浏览器，并要求有已登录状态的证据；浏览器不可用时，使用明确标注的手动链接。上传请用可读的附件或 Bot 工作区文件。参见宿主专属认证与浏览器指南。

更新账号级安装的插件后，在 Grok Bot 里重新检查，并使用新对话。移除该安装或连接可能影响其他客户端或 Bot；先保留有效凭据并检查范围。网站交接、重启/过期后的复用、单个媒体工作流都需要单独检查；账号共享并不能全部覆盖这些。

Cursor 连接

让 Connect to Fotor and introduce its main features. 从原生斜杠菜单里选真正的连接技能，显式调用。再让 Check only the Fotor MCP connection 收尾，不要带网站链接。

用 IDE 的 MCP 控件或命令行 /mcp 查看实际插件服务器；Grok Bot 则用上文说的 Connect Apps。如果命令行在同一加载上下文里支持，agent mcp list、agent mcp list-tools <identifier>、agent mcp login <identifier> 提供原生查看和登录。Cursor 账号登录和 Fotor MCP OAuth 是两回事。

复用有效的 Fotor 凭据。需要授权时，在外部浏览器完成，选 Continue，等客户端确认成功。网站请求走 IDE 可见的内置浏览器、命令行允许的外部浏览器打开方式，或 Grok Bot 可用的可见浏览器。都不可用时，把未使用的链接交给指定浏览器，等确认。核对最终生产网站和登录状态。见 Cursor and Grok Bot native guidance。

Cursor 更新

Git 市场安装的话，先刷新选中的市场，再打开 /plugin，有更新操作就用：

agent plugin marketplace update fotor-ai
agent plugin marketplace list --format json
agent

启动新的命令行进程，核对已安装版本、解析出的 commit、包文件、技能和生产端点。注册可能存的是解析出的 commit，而不是会移动的分支；只看到刷新成功消息，不能证明升级成功。源仍被固定的话，重跑所选渠道的注册命令，先在新进程里检查。

重新注册被拒，或旧包仍生效，就记下当前源和范围，在 /plugin 里只卸载那个 Fotor 安装（有保留数据选项就保留），对你记下的用户自有市场运行 agent plugin marketplace remove fotor-ai，再重跑所选渠道的注册和原生安装步骤。在新进程里核对新文件。记为市场重置并重装，不是原生刷新成功。保留有效凭据；安装成功不代表授权延续。不要删团队/全局市场，也不要把账号登出当作升级步骤。

本地安装的话，从所选渠道拿到新的完整包，只替换那个包，重载 IDE 或开新的命令行会话。本地替换不同于 Git 市场刷新和缓存升级。

Cursor 市场迁移

目录标识是 fotor-ai；早期开发目录用的是 fotor-cursor。本地 --plugin-dir 或 IDE 本地文件夹加载没有市场注册可改名。替换完整包，目录基名保持 fotor，重载或开新会话，核对版本和源。
要处理真正旧版应用市场的注册，先核对目标目录，记录来源和启用状态，再用所属 Cursor 安装自带的控制项移除旧的 Fotor 注册，并从新来源安装。不要改用其他宿主的命令。应用市场改名需要单独做迁移检查；安装或更新成功，并不能证明迁移完成。保留凭据；如果新安装失败，就恢复记录下来的旧来源。

Cursor 渠道

两个渠道都使用生产环境的 MCP 和额度。选择一个 Git 应用市场来源，或一个本地包，然后验证新会话使用的是预期版本。切换渠道不等于切换 MCP 环境。

选择生产版或测试版发布渠道

生产版发布

先确认 main 包含 Cursor 目录和 plugins/cursor/fotor/ 包。用原生命令行注册选定的 Git 来源，然后打开 /plugin（在显示该别名的客户端上是 /plugins），选择 fotor-ai 并安装 Fotor。只注册并不会安装插件。两个渠道都使用生产环境的 MCP 和账号。切换前记录当前来源和安装范围。只保留一个选定的 Fotor 来源；如果重新注册被拒绝，或一直停留在旧提交，就用原生控制项卸载该 Fotor 安装，只移除你之前自己拥有的 Fotor 应用市场，再重新注册选定的来源。保留凭据，并在新会话中验证新安装的文件。

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins
agent plugin marketplace list --format json
agent

测试版发布

先确认 release/test 包含 Cursor 目录和 plugins/cursor/fotor/ 包。用原生命令行注册选定的 Git 来源，然后打开 /plugin（在显示该别名的客户端上是 /plugins），选择 fotor-ai 并安装 Fotor。只注册并不会安装插件。两个渠道都使用生产环境的 MCP 和账号。切换前记录当前来源和安装范围。只保留一个选定的 Fotor 来源；如果重新注册被拒绝，或一直停留在旧提交，就用原生控制项卸载该 Fotor 安装，只移除你之前自己拥有的 Fotor 应用市场，再重新注册选定的来源。保留凭据，并在新会话中验证新安装的文件。

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins --git-ref release/test
agent plugin marketplace list --format json
agent

Pi

Pi 安装

生产版发布

从默认 main 分支安装已发布的插件。不需要选择分支。先确认选定的修订版本包含 Pi 包和根 Pi 清单。安装只加载技能；Fotor MCP 需要单独注册。

pi install https://github.com/fotor-ai/fotor-agent-plugins
pi list

Pi 安装的是 Package，不是 Marketplace 条目。根清单只选择 Pi 技能。Git 安装需要 Git 和 Pi 配置的包管理器，尽管 Fotor 没有依赖或运行时脚本。本地独立包可以用 pi install /absolute/path/to/fotor 安装；本地源就地加载。

Pi MCP 注册与连接

安装 Package 不会注册 MCP。先检查 /mcp 和生效的用户/项目配置；保留已有的不同 fotor 注册，添加前先解决这个选择。声明式示例描述了生产条目：

pi mcp add fotor --url https://mcp.fotor.com/mcp --exposure deferred --description "Connect to Fotor's production MCP service."

需要授权时，使用 Pi 原生的 /mcp 登录或 pi mcp login fotor。在外部普通浏览器中完成 OAuth，通过对话选择 Continue / Wait / Cancel，继续前先验证原生回调。Pi 的模型服务商登录是分开的。工具发现、覆盖和恢复请参考 Pi authentication。

问「Connect to Fotor and introduce its main features.」或调用 /skill:fotor-connect。主机能定位外部普通浏览器时，网站流程会在其中打开新的已验证链接；否则提供一个链接供立即手动打开。原生打开器成功不代表网站已登录。明确只请求 MCP 时不会创建网站链接。

Pi 更新

只更新记录的 Fotor 源，使用相同的安装范围：

pi update <recorded-source>
pi list

pi update --extensions 更新所有已安装的 Package；裸 pi update 更新 Pi 本身。重启 Pi，验证解析的修订版本、包版本、实际技能和生产 MCP。Git 标签和提交选择器保持固定；分支更新后检查实际安装的文件。

Pi 渠道

Git Package 的身份是不带 ref 的仓库 URL。每个配置只保留一个 Fotor 源。记录旧源和范围以便恢复，只移除那个 Package，再安装选定的渠道；保留 MCP 注册和授权。渠道包含 Pi 包后才能使用。只在项目范围下使用时，才给原生安装/移除命令追加 --local。

生产发布

从默认 main 分支安装已发布的插件。不需要选择分支。先确认所选修订包含 Pi 包和根 Pi 清单。安装只加载技能；Fotor MCP 需单独注册。记录当前来源和作用域，用 pi remove <recorded-source> 移除该包，然后在同一作用域安装所选来源。保留 MCP 配置和凭据；在新会话中确认只有一个生效的 Fotor 包。

pi install https://github.com/fotor-ai/fotor-agent-plugins
pi list

测试版本

从 release/test 安装测试构建，用于预发布验证。先确认所选修订包含 Pi 包和根 Pi 清单。安装只加载技能；Fotor MCP 需单独注册。记录当前来源和作用域，用 pi remove <recorded-source> 移除该包，然后在同一作用域安装所选来源。保留 MCP 配置和凭据；在新会话中确认只有一个生效的 Fotor 包。

pi install https://github.com/fotor-ai/fotor-agent-plugins@release/test
pi list

DeepSeek Harness

DeepSeek Harness 在命令和原生标识符中缩写为 dsh。它的 Fotor Bundle 只通过独立的 dsh-fotor-plugin 仓库 分发。本快照只包含安装指引，不含 DeepSeek Harness 包。仓库根目录仍是 Pi 入口。

DeepSeek Harness 安装

正式发布版

First verify that the selected revision contains the DeepSeek Harness Bundle. Install the fixed external bridge separately, then add this package to the chosen profile. Both components stay disabled until local setup.

dsh plugin --profile web add "git+https://github.com/fotor-ai/dsh-fotor-plugin.git" --ignore-scripts

Installing Fotor does not install mcp-remote. Install the pinned external bridge from the independent package's JSON materials, resolve the installed Bundle path and configure skills before authorizing and enabling MCP. Both native components are disabled by default. Follow the complete installation guide, configuration example and authorization instructions. Preserve the daily browser and external credential store.

The declared host range is >=0.2.1-rc.2 <0.3.0-0; actual acceptance is limited to the recorded Linux Web 0.2.1-rc.2 baseline. A matching version is not automatically tested.

Migrate an existing subdirectory installation

Existing installations from this repository do not migrate through an ordinary update. Record the source, profile, package-manager store, installed path and external configuration; stop both Fotor components and remove only their external override rows. Natively remove the old Bundle using dsh plugin --profile web remove fotor --config.ignore-scripts=true, then add the independent source above in the original profile/store. Resolve the new path and restore one complete configuration with the new absolute skill directory. Keep the external bridge, credential directory, model configuration and connection/security parameters unchanged.

Retain exactly one fotor source and one component pair. Future native updates follow the independent repository. Historical v0.5.0 snapshots remain unchanged; the old subdirectory is not a continuing installation or update channel. See maintenance instructions.

Documentation

- Codex plugin guide
- Claude Code plugin guide
- Cursor plugin guide
- Pi plugin guide
- DeepSeek Harness installation guide (separate repository)

Verification scope

Package checks cover files, references, and configuration. Verify installation, MCP authorization and calls, website login, credit links, uploads, and media execution separately in the selected host and environment. A release or model query does not establish successful website login or completed media results.

License

Apache-2.0