Pro
中文
登录账户 下载 Mac 版
下载 Mac 版

帮助文档 / API 与智能体

Claude、Codex 和 MCP:智能体工具

Phosphene 是一个本地服务器(Studio),浏览器页面、Mac 应用和智能体工具都通过同一套 HTTP API 与它通信(API.md)。在 agents/ 里有两个小工具建立在它之上:

是什么如何运行
agents/phosphene_cli.pyphosphene 命令:生成视频 / 图片 / 语音 / 音乐,列出任务,等待,取回文件,查看状态任意 python3(3.9+,仅标准库)
agents/phosphene_mcp.py一个 MCP 服务器(stdio),功能相同,供 Claude Code、Codex 或任何 MCP 客户端使用同上

两者都是 agents/phosphene_client.py 之上的薄封装,所以它们用同样的方式找到 Studio,在 Studio 没有运行时说的话也一样。

连接智能体

Mac 应用(5.0.9 或更高版本):打开 Phosphene,然后选择 帮助 → Connect an agent。选择 Claude Code、Codex 或你的桌面客户端,复制命令或配置。应用会提供适合你这份安装的准确路径,包括 Pro。智能体工作时请保持 Phosphene 打开。如果之后的更新改变了路径,请从同一个菜单重新复制一份连接。

Pinokio:启动 Phosphene,然后在 Pinokio 显示的 Studio 地址上打开 /agents/info。默认安装使用 http://127.0.0.1:8198/agents/info。其中的 agents 部分会给出命令和配置。这个地址是给 Pinokio 用的;Mac 应用改用它的“帮助”菜单。

MCP 工具:phosphene_status、phosphene_make_video、phosphene_make_image、phosphene_make_speech、 phosphene_make_music、phosphene_list_jobs、phosphene_wait、phosphene_fetch、phosphene_stop。 渲染要几分钟:make_* 工具加入队列并返回任务 id;phosphene_wait 最多阻塞 timeout_sec(默认 1500 秒),可以再次调用。

CLI

phosphene status
phosphene video "A night ferry crosses a dark harbour in light rain ..." --seconds 5 --out ./clips
phosphene video "..." --engine h3 --quality draft --seconds 10 --wait
phosphene video "..." --image still.png             # image to video (the picture is uploaded first)
phosphene image "a travel poster of a red tram" --n 2 --aspect 3:4 --out ./stills
phosphene jobs ; phosphene wait JOB --out DIR ; phosphene fetch JOB --out DIR ; phosphene stop
phosphene servers                                    # every studio answering on this Mac

任何命令加上 --json 都会输出机器可读的结果。退出码:0 成功,1 Studio 拒绝了请求或任务失败(会打印它的说明),2 参数有误,3 Phosphene 没有运行。 (这里的 phosphene 就是 python3 agents/phosphene_cli.py;你可以随意设置别名。)

工具如何找到 Studio

Studio 的端口取决于它在哪里运行:Pinokio 里是 8198,开发配置是 8199,Mac 应用里是 8930-8999 中的一个空闲端口(PanelProcess.freePort),用 LTX_PORT 可以指定任意端口。所以:

  1. 如果设置了 PHOSPHENE_URL,就只用它,不用别的。
  2. 每个 Studio 在监听端口绑定后,都会写入 ~/.phosphene/servers/<port>.json,停止时再删除它(agent_discovery.py)。只有当记录里的 pid 还活着,并且该 URL 对 GET /agents/info 回答 "app": "phosphene" 时,这条记录才会被信任。最新的优先。 PHOSPHENE_DISCOVERY_DIR 可以移动这个文件夹;PHOSPHENE_DISCOVERY=0 会关闭这种登记。
  3. 没有记录时(较旧的 Studio):依次尝试 8198、8199,再尝试 8930-8999。

没有任何响应时:“Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.”(CLI 退出码 3;MCP 工具会报错,而不是崩溃。)

免费版、Pro 和许可

这些工具不增加任何路由,也不做任何决定。每个请求都是页面自己也会发出的请求(/queue/add、/speech/generate、/upload、/status、/file),所以 Studio 会应用同样的检查:这台 Mac 能运行什么、模型许可(在用户接受之前返回 HTTP 451),以及免费版和 Pro 包含什么。表单无法把 Pro 的速度配置带进任务(make_job 从白名单构建 params;test_agent_tools.py 把它固定住了)。我们刻意没有任何工具可以接受模型许可:替别人接受就是替他们同意,所以这件事要由用户本人在 Phosphene 里完成一次。

GET /agents/info

{"app": "phosphene", "api": 1, "url": "http://127.0.0.1:8198", "port": 8198, "pid": 123,
 "version": "5.0.0", "distribution": "pinokio" | "mac-app", "edition": "free" | "pro", "profile": "production",
 "pro": {"active": false, ...},                       // GET /pro/status
 "engines": {"ltx": {"available": true, "qualities": [...]},
             "h3": {"available": false, "qualities": [...], "lengths": ["3s", "5s", "10s", "15s", ...]},
             "speech": {...}, "music": {...}, "image": {...}},
 "outputs_dir": "...",
 "agents": {"cli": "...", "mcp": "...", "python": "...", "mcp_config": {...}, "claude_code": "...", "codex": "..."}}

开销很小(不遍历磁盘),可以放心轮询。测试:test_agent_tools.py。

来源:docs/AGENT_TOOLS.md,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。