PhotoFresco

面向 AI Agent 的 PhotoFresco

让 AI Agent 在你批准的 PhotoFresco 窗口中编辑图像：图层、蒙版、预览和导出。

PhotoFresco 是一款免费的 Photoshop 级图像编辑器，可在浏览器中运行：支持图层、蒙版、调整图层、选区、画笔、PSD 导入和导出，以及完整的撤销历史记录。本仓库将 AI Agent 接入其中。Agent（Claude、Cursor、VS Code、Codex、任何 MCP 客户端，或通过命令行运行的脚本）可操控你自己电脑上的 PhotoFresco 窗口。你可以查看每项更改、允许连接、选择 Agent 可以执行的操作，并随时暂停或停止。编辑操作本身在编辑器中进行，因此每项更改都会记录在历史记录中，可以像你自己的操作一样撤销。

上方录制的是一次真实会话：一个 MCP 客户端调用此服务操作编辑器，并以无头模式录制。类别：设计 / 图像编辑。

本仓库包含：

• MCP 服务（photofresco mcp）：每项编辑器操作对应一个工具，以图像形式提供预览，以文件或资源形式导出。指南：MCP.md。
• Agent Skill（skills/photofresco）：指导 Agent 何时以及如何有效使用 PhotoFresco。
• 命令行（photofresco <command>）：打开、运行已保存的工作流、导出、停止。指南： CLI.md。
• 本地连接器（供其他三项功能共用的库）：CONNECTOR.md。

编辑器本身不在本仓库中；连接器会在 photofresco.com 打开编辑器。

要求

• Node.js 22 或更高版本。
• 已安装基于 Chromium 的浏览器：Google Chrome、Microsoft Edge 或 Chromium 120 或更高版本。 不会下载任何内容。如有需要，可将 --browser（或 PHOTOFRESCO_BROWSER）指向其他浏览器。
• 已在 macOS 上验证；Windows 和 Linux 已实现，但尚未验证。

配置 Agent

一键安装（Cursor、VS Code、LM Studio）：

每个按钮都会要求应用添加 photofresco 服务，该服务通过 npx 从版本 0.1.0 的 GitHub 源代码归档（提交 328cfaf）启动（不会从 npm registry 获取任何内容）。它不会授予任何文件夹访问权限：在应用的 MCP 设置中，向 mcp 后添加 --read 和 --write 参数，即可允许 Agent 打开和保存文件。

或者，将服务添加到下方客户端的 MCP 配置中。选择 Agent 可以从中打开文件的文件夹（--read），以及可以将导出文件保存到的文件夹（--write）。不设置这些参数时，Agent 仍可编辑和预览，但无法访问你的文件。

npm 发布尚未完成。 photofresco npm 包将于 2026 年 10 月中旬发布，因此下方的 npx -y [email protected] 命令目前尚不可用。在此之前，请使用 --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco（同一版本，来自 GitHub）替换 [email protected]，安装插件，或者像下方那样从本仓库的克隆运行：用 node /path/to/photofresco-agent/src/bin/photofresco.js 替换 npx -y [email protected] 部分（无需 npm install）。

从克隆运行（目前即可使用；MCP SDK 已打包，无需安装任何内容）：

git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent

然后，将此条目添加到任何读取 mcpServers 的客户端（Claude Desktop、Cursor、Windsurf、Kiro 及大多数其他客户端），并将 /Users/you 替换为你自己的主目录：

{
  "mcpServers": {
    "photofresco": {
      "command": "node",
      "args": ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Claude Code：

claude mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Claude Desktop：claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "photofresco": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Cursor：~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目），使用与 Claude Desktop 相同的 mcpServers 条目。

VS Code：工作区中的 .vscode/mcp.json，或选择 MCP: Open User Configuration 为所有工作区配置：

{
  "servers": {
    "photofresco": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Windsurf（Cascade）：在 mcp_config.json 中使用与 Claude Desktop 相同的 mcpServers 条目（Cascade → MCPs → Open MCP config file）。

Gemini CLI：

gemini mcp add -s user photofresco npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex：

codex mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

OpenCode：项目中的 opencode.json，或用于所有项目的 ~/.config/opencode/opencode.json（从克隆运行，如上所述）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "photofresco": {
      "type": "local",
      "command": ["node", "/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"],
      "enabled": true
    }
  }
}

Kiro：将上方克隆配置中的 mcpServers 条目添加到 ~/.kiro/settings/mcp.json（所有工作区）或 .kiro/settings/mcp.json（单个工作区）。

Cline：将本仓库提供给 Cline；llms-install.md 会引导它完成安装、连接和停止。

此服务已使用官方 MCP TypeScript 客户端通过 stdio 进行测试；这些条目遵循各应用文档规定的 stdio 格式。选项：

选项	含义
--read <folder>	Agent 可以从此文件夹打开图像文件（可重复指定）
--write <folder>	Agent 可以将导出文件保存到此文件夹及其新建子文件夹中（可重复指定）
--overwrite	导出文件可以替换 --write 文件夹中的现有文件（Agent 也必须请求此权限）
--tools <groups>	作为工具列出的操作：essentials（默认，最多 40 个工具）、all，或以逗号分隔的组列表（MCP.md）
--profile <folder>	浏览器配置文件夹；也可使用 ephemeral 创建一次性配置文件
--browser <path>	要使用的 Chromium 内核浏览器（与 PHOTOFRESCO_BROWSER 相同）

MCP Bundle（Claude Desktop 和其他可安装 .mcpb 文件的应用）：运行 node scripts/build-mcpb.mjs，即可从本仓库构建 dist/photofresco-mcp-0.1.0.mcpb 及其 SHA-256（使用相同 Node.js 版本即可复现）。该 Bundle 会启动相同的服务，并且和插件一样，不授予任何文件夹访问权限。每个 GitHub 版本发布都会附带此文件；其 SHA-256 即 server.json（Official MCP Registry 条目）中的 fileSha256。

Docker（适用于要求服务在容器中运行的 MCP 注册表）：运行 docker build -t photofresco-mcp .，然后运行 docker run -i --rm photofresco-mcp，即可通过 stdio 运行服务。此镜像不包含浏览器，因此只会列出工具；在其中调用 photofresco_connect 会失败并返回 browser_not_found。如上所述，使用本地安装来编辑图像。

会话流程

1. Agent 调用 photofresco_connect。PhotoFresco 会在独立窗口中打开，并显示一个连接码；Agent 会告诉你相同的连接码。核对后点击允许。
2. 会话开始时没有任何权限。Agent 会请求所需权限（读取、编辑、导出；仅云端和付费 AI 需要发送和消费），你可以在权限对话框中选择。你授予权限后，相应的编辑工具就会显示给 Agent。
3. Agent 每次编辑操作都使用一个工具，查看预览并撤销不满意的操作。你自行编辑时，Agent 会暂停，直到你按下继续。点击停止会结束会话；关闭窗口也会结束会话。

只有在 Agent 调用 photofresco_connect 后才会打开窗口：启动服务和列出工具不会启动浏览器。

安装为插件

此仓库也可用作 Claude Code、Codex、Cursor、Gemini CLI、Hermes Agent、OpenClaw、 Antigravity、Devin 和 Kiro 的插件：安装一次即可添加 MCP 服务和 Agent Skill。客户端会复制此仓库，并通过 node <plugin folder>/src/bin/photofresco.js mcp 启动服务； 不会从 npm 下载任何内容，因为 MCP SDK 已打包在可读的 vendor/ 中。必须在 PATH 中安装 Node.js 22 或更高版本。

安装插件不会授予任何文件夹权限：Agent 会编辑 PhotoFresco 窗口中打开的图像，你需要自行在其中打开和保存文件。如需让 Agent 访问文件，请按上述说明使用 --read 和 --write 配置服务。

Claude Code（在会话中执行；在 Claude Code 2.1.275 或更高版本中，第三行会一步完成两项操作）：

/plugin marketplace add photofresco/photofresco-agent
/plugin install photofresco@photofresco
/plugin install photofresco --marketplace photofresco/photofresco-agent

Codex：

codex plugin marketplace add photofresco/photofresco-agent
codex plugin add photofresco@photofresco

Gemini CLI：

gemini extensions install https://github.com/photofresco/photofresco-agent

Gemini CLI 只会向扩展传递少量环境变量，因此 PHOTOFRESCO_BROWSER 不会传递给此扩展；如果浏览器位于标准位置之外，请使用上述 MCP 配置。

Cursor：在 PhotoFresco 出现在列表中后，从自定义中安装；或者将此仓库复制到 ~/.cursor/plugins/local/photofresco，然后重新加载窗口。

Hermes Agent（需使用支持 Agent Plugins 且包含 hermes plugins validate 的版本）。插件默认处于禁用状态；启用后，服务和 skill 会在下一个会话中加载：

hermes plugins install photofresco/photofresco-agent --no-enable
hermes plugins enable photofresco

OpenClaw（它会要求你检查源代码，然后接受插件的 MCP 服务和 skill）：

openclaw plugins install photofresco --marketplace photofresco/photofresco-agent

Antigravity（CLI）：

agy plugin install https://github.com/photofresco/photofresco-agent

Devin（CLI；也可在应用中选择自定义 → 插件 → 添加插件 → 从仓库）：

devin plugins install photofresco/photofresco-agent

Kiro：选择Powers → Add Custom Power → Import power from GitHub，然后输入 https://github.com/photofresco/photofresco-agent。

清单文件包括 .claude-plugin/（Claude Code，也供 Devin 读取）、plugin.json 和 mcp.json （Agent Plugins 标准，供 Codex、Hermes Agent 和 Kiro 使用）、 .cursor-plugin/plugin.json（Cursor 和 OpenClaw 使用，OpenClaw 通过它读取 .mcp.json）、 gemini-extension.json（Gemini CLI）、mcp_config.json（Antigravity）以及 openclaw.plugin.json （OpenClaw 和 ClawHub 元数据）。

Agent 技能

skills/photofresco 中的 Agent Skill 会教会支持 skill 的 Agent（Claude Code、Codex、Cursor 等）何时使用 PhotoFresco、如何连接并请求权限、如何执行“定位 → 编辑 → 预览 → 撤销”循环，以及相关工作流、导出、所有错误代码和命令行用法。它不会配置 MCP 服务；请按上述说明完成配置。使用 skills CLI 将其安装到当前项目中（为当前用户安装请添加 -g）：

npx skills add photofresco/photofresco-agent

使用 npx skills remove photofresco 将其移除。操作参考是服务自身的工具列表（photofresco_list_tool_groups，或命令行中的 photofresco ops）。

命令行

同一个软件包还会安装 photofresco 命令，供有 shell 但没有 MCP 客户端的脚本和 Agent 使用。它通过后台连接器进程驱动同类经批准的窗口。在 npm 软件包发布之前（2026 年 10 月中旬），请从克隆的仓库运行，而不要执行 npm install -g：alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js"。

npm install -g [email protected]
photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
  --export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stop

connect 会打开 PhotoFresco 并打印连接码；请确认窗口显示相同的代码，然后点击 Allow 并选择权限。run 会在新标签页中打开图像，运行已保存的工作流（即编辑器的 Actions 面板导出的可移植文件），并且仅在 SHA-256 匹配后才写入导出文件。stop 会结束会话、关闭窗口并停止连接器进程。

命令	功能
connect	如有需要则启动连接器，打开 PhotoFresco 并配对（由你点击 Allow）
status	查看连接器、窗口、会话、权限和已授权文件夹
request-access <list>	申请更多权限（read,edit,export,external-write,spend）
documents, attach <id>	列出已打开的文档；指定另一个文档
open <file>	在新标签页中打开已授权文件夹内的图像
run <workflow.json>	使用 --open、--input 和 --export 运行工作流（或 --action <id>）
export <file>	将文档导出为 PNG、PSD 或 .pfd，保存到已授权文件夹
exec <op> [params-json]	运行一项编辑器操作
ops [prefix], describe <op>	查看本会话可运行的操作及其参数
outcome <request-id>	连接中断后查看先前请求的结果
disconnect, stop	结束会话；stop 还会关闭窗口和连接器
mcp	上文所述的 MCP 服务

每条命令都支持 --json（在标准输出中返回一个对象，失败时也一样），并会返回有文档说明的退出代码（0 表示成功，2 表示用法错误，3 表示未连接，4 表示路径被拒绝，5 表示编辑器拒绝，8 表示已取消，75 表示仍在等待你操作）。完整参考：CLI.md。

此工具会运行、发送和获取的内容

在 macOS 上使用 Chrome for Testing 145 针对本地编辑器构建版本进行观察，并将所有细节记录在 DISCLOSURE.md 中；未观察到的内容会在其中标明。

运行的内容

• 一个 Node.js 进程：客户端启动的 MCP 服务（客户端关闭时该进程结束），或每条 photofresco 命令，以及每个数据文件夹对应的一个后台连接器进程（执行 photofresco stop、关闭其窗口，或在没有窗口或命令运行一分钟后，该进程结束）。
• 只有 Agent 连接时才会启动一个浏览器进程树：你安装的 Chrome、Edge 或 Chromium，使用专用配置文件和 DevTools 管道启动（--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions）。它会显示普通的可见窗口（上方演示是在无头模式下录制的）。绝不会打开、读取或连接你日常使用的浏览器配置文件。
• 不会运行其他程序、shell 命令、安装程序、服务、登录项或扩展。

本地文件和通信渠道

• 数据文件夹：~/Library/Application Support/PhotoFresco Connector（macOS）、 %LOCALAPPDATA%\PhotoFresco Connector（Windows）或 ~/.local/share/photofresco-connector （Linux）。其中包含浏览器配置文件（Cookie，以及你在其中登录后的登录状态、缓存、 编辑器的本地存储和自动保存数据）、锁文件；对于命令行，还包含 cli/，其中有 Unix 套接字（位于权限为 0700 的文件夹中，权限为 0600）、每次启动时随机生成的密钥和 connector.log（不含机密的事件：获准访问的文件夹路径、读取或写入的文件路径、大小和 SHA-256；不含密钥、文件内容或像素；最多 4 MiB）。
• 你的文件：Agent 打开文件时，只能在 --read 文件夹中读取（最多 32 MiB）；导出时，只能 在 --write 文件夹中写入，并通过临时文件在其 SHA-256 匹配后重命名到目标位置。只有 指定 --overwrite 且 Agent 请求覆盖时，才会替换现有文件。
• 不监听网络端口。 浏览器通过专用管道控制；命令行使用本地套接字。观察结果： 服务和连接器进程中均没有 TCP 套接字。

网络

• 连接器、MCP 服务和命令行本身不会发出网络请求。npx/npm install 会先从 npm 注册表 下载软件包（发布 npm 版本之前，一键按钮会改为从 GitHub 下载此仓库的源代码压缩包）； 安装插件时，Agent 客户端会从 GitHub 复制此仓库；启动服务不会下载任何内容。
• 浏览器会打开 https://photofresco.com/app/?pf_ref=mcp（或 cli），这是一个用于归因的 非机密标签，并像正常访问一样加载编辑器。由于浏览器是自动化控制的，因此不会显示第三方 广告。
• 连接器窗口默认关闭会话录制。 编辑器能够识别连接器打开的窗口（这是链接或网站都 无法建立的专用通道），并以“数据与隐私”中未允许任何项目的状态启动，因此不会上传 你的文件中的任何内容：没有会话录制、诊断信息、Agent 打开的文件副本或使用事件。观察 结果：从连接到会话结束期间没有录制或遥测请求，包括 Agent 导入照片之后。允许 Agent 只会启用其中的“外部 Agent”。
• 除非你在该窗口的“数据与隐私”中开启录制，否则录制会一直关闭。 开启后，系统会向 PhotoFresco 发送输入事件、编辑器命令、文档名称、输入的文本（密码和电子邮件字段会被 屏蔽），以及在该窗口中打开的每张图像的副本，包括 Agent 通过连接器打开的文件（每张 最多 16 MiB，每次页面加载最多 6 张）；还会发送诊断信息（错误、功能事件、性能信息、 设备配置文件）和保护隐私的使用事件（referral、open、edit、export，标记为 automated；不含文件名或像素）。通过连接器打开的 photofresco.com 普通访问默认开启 录制。
• 浏览器自身的后台流量（更新、安全浏览）遵循其默认设置；未经测量。尚未核实生产网站的 第三方请求。

Agent 会收到什么

• 仅限你授权的内容：会话状态、文档状态、操作结果、**预览（像素）**和导出的文件。Agent 收到的所有内容都会发送给该 Agent 的模型提供商，并受该提供商的政策约束。
• 付费 AI 功能只有在你授予“支出”权限并设置额度后才会运行；向 PhotoFresco 服务（云文档、 AI）发送数据需要“发送”权限。
• 窗口会显示连接者身份：MCP 客户端在握手时发送的名称（“ via MCP”），或命令行中 的 --client（默认为“Terminal via CLI”）。

控制权始终在你手中：每次连接都需要你允许；会话开始时不授予任何权限；点击“停止”、关闭 窗口、重新加载或离开编辑器都会结束会话。关闭连接器也会关闭其窗口。

卸载

从客户端配置中移除 MCP 条目（或运行 photofresco stop 和 npm uninstall -g photofresco），或者移除插件（在 Claude Code 中运行 /plugin uninstall photofresco@photofresco，运行 codex plugin remove photofresco@photofresco、gemini extensions uninstall photofresco、 hermes plugins remove photofresco、openclaw plugins uninstall photofresco、 agy plugin uninstall photofresco、devin plugins remove photofresco，或在 Cursor 中选择 Customize，以及在 Kiro 中打开 Powers 面板）。运行 npx skills remove photofresco 移除技能，并删除上文所述的数据文件夹。不会安装其他内容。

支持

• 问题和错误：请访问 GitHub issues 或发送邮件至 [email protected]。
• 文档：与 AI Agent 搭配使用 PhotoFresco。
• 隐私政策：photofresco.com/docs/privacy。
• 服务条款：photofresco.com/docs/terms。
• 网站：photofresco.com。

许可证

此代码库（MCP 服务、命令行、连接器和技能）根据 MIT License 发布。PhotoFresco 编辑器和 photofresco.com 服务不在此列。