帮助文档 / API 与智能体
Claude、Codex 和 MCP:智能体工具
Phosphene 是一个本地服务器(Studio),浏览器页面、Mac 应用和智能体工具都通过同一套 HTTP API 与它通信(API.md)。在 agents/ 里有两个小工具建立在它之上:
| 是什么 | 如何运行 | |
|---|---|---|
agents/phosphene_cli.py | phosphene 命令:生成视频 / 图片 / 语音 / 音乐,列出任务,等待,取回文件,查看状态 | 任意 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 可以指定任意端口。所以:
- 如果设置了
PHOSPHENE_URL,就只用它,不用别的。 - 每个 Studio 在监听端口绑定后,都会写入
~/.phosphene/servers/<port>.json,停止时再删除它(agent_discovery.py)。只有当记录里的 pid 还活着,并且该 URL 对GET /agents/info回答"app": "phosphene"时,这条记录才会被信任。最新的优先。PHOSPHENE_DISCOVERY_DIR可以移动这个文件夹;PHOSPHENE_DISCOVERY=0会关闭这种登记。 - 没有记录时(较旧的 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,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。