• 服务条款
• 隐私政策
• 退款政策
• 可接受使用政策
• 支持
• Agent 手册

Agent 使用手册

这本手册是写给已经在用 Claude Code、Codex、Gemini CLI 这类 Agent 的人看的：教你怎么让自己的 Agent 直接操控 Galanty 文影做视频——挑样片、改文案和配色、预览、导出，不用自己写 ffmpeg、字幕或配音脚本。

文影不自带编稿用的大模型。连上 Agent 之后，是你的 Agent（以及它登录的那个模型服务）帮你写分镜、写画面代码、改文案；画面渲染和视频导出在你自己的 Mac 上完成。配音在哪里做取决于你选的引擎：默认是本机，选了云端语音服务时旁白文字会发给那家服务，自定义命令程序会不会联网由它自己决定。打开「成片审片」时，已登录的 Agent 会收到成片抽帧、旁白与时间、未处理的批注；它自动重做某一幕时还会收到那一幕的画面代码和参数。

本地帮助与批注交接

App 的「帮助 → 产品与 Agent 手册」可离线打开随包手册；在 macOS 安装包中，Markdown 位于 Galanty.app/Contents/Resources/help/，无需读取 app.asar。Agent 先读该目录的 README.md 与 package.json，了解本包版本和渠道，再读 agent-guide.md、product-manual.md。连接后也可读固定资源 talkframe://manual/index、talkframe://manual/agent/zh、talkframe://manual/product/zh（英文后缀为 en）。

商店版的系统沙盒不允许 App 启动外部 Agent 程序，因此应用内的「交给 Agent」不会启动你的命令行。它仍可让你连接自己的 Agent：点「连接 Agent」复制 MCP 配置，在外部 Agent 添加后重载；点「复制给 Agent」将批注交给它。连接成功不会自动消费批注，仍需把复制的内容发给 Agent。Agent 读 get_job({jobId, detail:true}) 和 talkframe://guide/notes，认领、修改、编译并回写批注；你在 App 查看更新并播放确认。

1. 文影能让 Agent 做什么

连上之后，Agent 会用到下面这些工具（MCP 工具，一共 15 个），按用途分组：

起步：挑样片或模板

• list_templates——看文影自带的样片（编号 S 开头）和动画模板（随包的 T 号、你自己注册的 U 号）。
• fork_template——把某个样片或模板复制一份到你的工作区，当作新作品的起点。

出片

• make_video——用一句话描述、一份文档或一份分镜 JSON 生成视频。默认只编译画面、给你一个可以马上播放的链接，免费、不计导出次数；只有你明确说"要导出 MP4"，它才会消耗导出额度。
• import_storyboard——提交或校验分镜（JSON）。改完文案、画面组件参数后用它保存。
• estimate_duration——不渲染，先算一下当前分镜配音之后大概多长，够不够你要的时长。

看与确认

• preview_scene——看某一帧画面。可以直接告诉 Agent"看第几秒"或"哪句话"，它会定位到对应的幕和句子，不用猜帧数。
• wait_job——等一个任务做完（编译或导出完成）。
• review_render——让作品设定里选的 Codex、Claude Code 或 Gemini 命令行看成片抽帧打分（会联网；只在官网版、并且这台电脑装好登录了其中一个时可用，API Key 编稿服务做不了这一步），低于 8 分时最多重做最弱的一幕、复核 3 轮；结果仍需要你自己播放确认。商店版不能启动命令行，可以让你的 Agent 自己看 preview_scene 的抽帧。

改内容、加素材

• get_scene_runtime——给 Agent 看的"怎么写一幕画面代码"的说明。想要自己的画面（三维、图表、手绘、示意界面……）就让 Agent 先读它再写；满意的片子大多是这样自己写出来的，模板和样片只是起点。
• import_asset——导入你自己的图片、视频、图标或音效，换进分镜的素材槽；Manim、Blender、After Effects 这类软件导出的 MP4 也能这样放进片子。
• import_music——导入你自己的背景音乐，或 Agent 用代码合成的原创曲。
• search_icons——在文影自带的图标库里按关键词找图标。

管理任务与反馈

• get_job——查看某个任务的状态、进度、产物文件，或者列出所有任务。
• cancel_job——终止一个正在进行的任务。
• report_gap——当 Agent 发现"文影做不到"时记一笔，帮助以后改进；只记效果和尝试过的办法，不会把你的正文内容发走。

2. 官网版和 App Store 版的区别

两个渠道都能接 Agent，但接法和能碰到的文件不一样：

3. 连接你的 Agent

一键连接还没上线，目前都是"复制配置 → 粘贴进 Agent 自己的配置文件"。以下按 Agent 分节，每节都给出官网版和 App Store 版两条路。

Claude Code

官网版

1. 打开文影 → 设置 → 更多（开发者）→「MCP：让 Agent 使用工作台」。
2. 配置目标选 Claude Code，点「复制文影 MCP 配置」。
3. 粘贴进 .mcp.json，和已有的 mcpServers 合并，不要覆盖其他服务器。复制出来的内容形如下面这样（这是源码环境的写法；安装包复制出来的 command 是文影自己的程序路径，还会多一项 ELECTRON_RUN_AS_NODE，照复制的原样粘贴即可，不用另装 Node.js）：

{
  "mcpServers": {
    "talkframe": {
      "command": "node",
      "args": ["<这台电脑上文影的安装路径>/scripts/mcp-server.mjs"],
      "cwd": "<这台电脑上文影的安装路径>",
      "env": {
        "DVS_WORKSPACE": "<你的工作区路径>",
        "DVS_DATA": "<数据目录>"
      }
    }
  }
}

1. 可选：点「复制项目提示」，粘贴进项目的 AGENTS.md 或 CLAUDE.md，让 Claude Code 一开始就知道怎么用文影。
2. 重新打开 Claude Code，或让它重新加载 MCP 配置。

App Store 版

打开文影 → 设置 → 更多（开发者）→「连接 Agent」，面板会显示本机地址和口令。当前先用 HTTP 直连；小包发布后再选 stdio 转发：

# 直连（不用安装任何东西）：口令只在这台电脑上有效，不要提交到 Git
claude mcp add --scope user --transport http galanty http://127.0.0.1:<端口>/mcp --header "Authorization: Bearer <口令>"

# 或者用本机桥（需要 Node.js 20+，npm 包即将发布）：可以把项目里的文件交给 App，成片和预览帧下载到 galanty-out/
claude mcp add --scope user galanty -- npx -y @galanty/mcp

实际地址、端口和口令以 App 设置面板里显示的为准，直接复制即可。

Codex

官网版

1. 打开文影 → 设置 → 更多（开发者）→「MCP：让 Agent 使用工作台」。
2. 配置目标选 Codex，点「复制文影 MCP 配置」。
3. 粘贴进 Codex 的 config.toml，内容形如下面这样（同样以复制出来的为准）：

[mcp_servers.talkframe]
command = "node"
args = ["<这台电脑上文影的安装路径>/scripts/mcp-server.mjs"]
cwd = "<这台电脑上文影的安装路径>"
startup_timeout_sec = 30
tool_timeout_sec = 600
# 自动批准文影的工具调用；想每次确认就删掉下一行
default_tools_approval_mode = "approve"

[mcp_servers.talkframe.env]
DVS_WORKSPACE = "<你的工作区路径>"
DVS_DATA = "<数据目录>"

1. 可选：把「项目提示」粘贴进项目的 AGENTS.md。
2. 重新打开 Codex 或重启当前会话。

App Store 版

同样在「连接 Agent」面板里看地址和口令，当前先用 HTTP 直连；小包发布后再选 stdio 转发：

# 直连（不用安装任何东西）：口令只在这台电脑上有效，不要提交到 Git
[mcp_servers.galanty]
url = "http://127.0.0.1:<端口>/mcp"
http_headers = { Authorization = "Bearer <口令>" }
tool_timeout_sec = 600
# 自动批准文影的工具调用；想每次确认就删掉下一行
default_tools_approval_mode = "approve"

# 或者用本机桥（需要 Node.js 20+，npm 包即将发布）：可以把项目里的文件交给 App，成片和预览帧下载到 galanty-out/
# codex mcp add galanty -- npx -y @galanty/mcp

Gemini CLI

官网版

1. 打开文影 → 设置 → 更多（开发者）→「MCP：让 Agent 使用工作台」。
2. 配置目标选 Gemini，点「复制文影 MCP 配置」。
3. 粘贴进 .gemini/settings.json，和已有的 mcpServers 合并：

{
  "mcpServers": {
    "talkframe": {
      "command": "node",
      "args": ["<这台电脑上文影的安装路径>/scripts/mcp-server.mjs"],
      "cwd": "<这台电脑上文影的安装路径>",
      "env": {
        "DVS_WORKSPACE": "<你的工作区路径>",
        "DVS_DATA": "<数据目录>"
      }
    }
  }
}

1. 可选：把「项目提示」粘贴进项目的 AGENTS.md。
2. 重新打开 Gemini CLI。

App Store 版

# 直连（不用安装任何东西）：口令只在这台电脑上有效，不要提交到 Git
gemini mcp add --scope user --transport http galanty http://127.0.0.1:<端口>/mcp --header "Authorization: Bearer <口令>"

# 或者用本机桥（需要 Node.js 20+，npm 包即将发布）：可以把项目里的文件交给 App，成片和预览帧下载到 galanty-out/
gemini mcp add --scope user galanty -- npx -y @galanty/mcp

以上命令按各 Agent 本机版本的 --help 核对过写法；具体参数名可能随 Agent 自身版本更新而变化，连不上时以该 Agent 自己的帮助文档为准。

4. 验证连接

配置好之后，跟你的 Agent 说一句话确认连上了，例如：

"文影有哪些样片？随便说几支。"

Agent 应该会读到 talkframe://samples 这份资源，报出几个 S 开头编号的样片标题。如果它说不知道文影是什么，或者报错找不到工具，看第 8 节「排错」。

5. 做第一支视频

连上之后，可以直接把下面三句话之一发给 Agent（换成你自己的内容）：

1. "挑一支最像『产品介绍』的样片，复制一份，改成讲我们这个新功能，先给我看预览，不用导出。"
2. "把这份 PDF 做成一支 30 秒的竖版视频：/绝对路径/我的文档.pdf，先播给我看。"
3. "刚才那支视频，配乐换成更欢快的，第 5 秒那句说完多停一秒，再给我看一次。"

Agent 通常会先读 talkframe://guide 和样片列表，挑一支最像的复制起步，改完用只编译的方式给你一个播放链接；只有你明确说"导出"或"给我 MP4"，它才会消耗导出额度生成文件。

6. 常用说法

不用记工具名，正常说话就行，Agent 会挑合适的工具去做：

想要更好看：可以这样要求

下面这些说法来自文影自己做样片的经验，都是建议，你想要别的效果就直接说：

7. 文件与隐私

• 官网版：Agent 和 App 共用同一个工作区文件夹，正文和素材都在本机。你的 Agent 读到的正文和素材，会照它自己的设置发给它所用的模型服务；选"连接 AI 编稿"时正文和编稿要求会发给编稿服务；配音与成片审片的去向见本页开头。
• App Store 版 · HTTP 直连：Agent 只能碰到 App 沙盒工作区里的文件，碰不到你项目目录里的东西。
• App Store 版 · 本机桥：你传给工具的本地文件或目录路径（比如 import_asset 的 filePath、make_video 的 codeDir）会被上传进 App 的工作区；做好的视频和预览帧会下载回你项目目录下的 galanty-out/。
• 口令只在本机 127.0.0.1 有效，不要提交到 Git 或分享出去；同机其他程序若获得口令也能操作你的工作区；不要公开。
• 导出额度和水印规则跟是否用 Agent 无关：免费档每月可导出 7 次，按本机时区的日历月计算，下月 1 日恢复；Pro 不限次、没有水印。

更完整的隐私说明见隐私政策；App 本身的常见问题见支持。

8. 排错

连不上 / Agent 报错找不到工具

• 确认文影已经打开——本机桥和直连都需要 App 在运行。
• 官网版：确认粘贴的配置和文件路径没有被改动，mcpServers 里确实有 talkframe 这一项。
• App Store 版：确认用的地址、端口和口令是设置面板里当前显示的那一份。

口令过期或重置过

在设置里点过「重置口令」之后，旧口令立刻失效。把已经 add 过的连接删掉，用新命令重新添加一次。

端口变了

文影优先复用上次用过的端口；如果被其他程序占用，会换一个。重新打开设置面板里的地址复制一次即可。

Agent 找不到某个文件

HTTP 直连只能用 App 工作区里的文件；请先通过 App 导入，或用官网版。未来本机桥小包发布后，才可通过它转发项目里的本地文件。

导出额度用完了

免费档每月 7 次，下月 1 日（本机时区）恢复。想现在就要无水印、不限次的导出，需要开通 Pro；想继续免费，就先用只编译的播放链接。

本机桥 npx -y @galanty/mcp 还装不上

本机桥小包目前还没有正式发布到 npm，这段时间请先用 HTTP 直连那一条路。

命令本身报错

Claude Code、Codex、Gemini CLI 各自的命令格式会随自己的版本更新；上面的写法是按当前版本的 --help 核对的，如果你那边的参数名不一样，以你本机那个 Agent 自己的帮助文档为准。还是解决不了，发邮件到 support@galanty.cn，参见支持。