智能体接入

Mediora Pro 可以让支持 MCP 的客户端查看媒体库、下载进度和任务，并在授权范围内执行操作。所有操作仍由你部署的 Mediora 服务处理。

连接

在 Mediora 打开“设置 → 智能体接入”，复制页面显示的 MCP 地址。
在客户端添加远程 MCP 服务，填入该地址。客户端若支持浏览器授权，按提示登录 Mediora、选择权限并同意授权。
返回 Mediora 的“当前授权”列表，查看“已连接”和最近调用的工具。
如果客户端无法完成浏览器授权，在同一页面生成手动凭证，复制页面给出的配置或命令。凭证只显示一次，仅提供给你决定授权的客户端，不要公开分享。

客户端必须能够访问这个地址。局域网地址只适用于同一网络或能访问该网络的客户端；云端客户端需要可从公网访问的 HTTPS 地址。部分客户端拒绝对局域网 HTTP 地址执行浏览器授权，可以改用页面上的手动凭证。各客户端的具体兼容性尚需在实际版本上验证，遇到授权失败时先看客户端错误信息。

使用 WorkBuddy 时，可以直接按下面的示例完成接入。

下载配套 Skill

在“智能体接入”页点击“下载 Skill”，解压到客户端支持的技能目录并重新加载客户端。Skill 随 Mediora 服务端一起构建，包含工具选择、确认规则和故障排查说明；具体安装目录以你使用的客户端文档为准。工具参数始终以 MCP 的 tools/list 为准。

示例：WorkBuddy 接入 Mediora

本例使用 WorkBuddy 桌面端和 Mediora 的手动 Agent 凭证。操作顺序为：安装 MCP 和 Skill → 提供 Agent 凭证 → 开启并信任自定义连接器 → 重启 WorkBuddy → 验证调用。

开始前，确认 Mediora 的 Pro 智能体接入可用，并且运行 WorkBuddy 的电脑能打开 Mediora 网页。NAS 上的 Mediora 应使用 NAS 的可达地址；只有 Mediora 与 WorkBuddy 在同一台电脑运行时，才使用 localhost 或 127.0.0.1。

1. 先让 WorkBuddy 完成 MCP 和 Skill 安装

在 Mediora 打开“设置 → 智能体接入”，点击“复制接入提示”。提示中已包含当前实例的 MCP 地址。
在同一页面点击“下载 Skill”，保存 mediora-agent-skill.zip。
在 WorkBuddy 的“专家·技能·连接器 → 技能 → 添加技能 → 上传技能”导入 ZIP，并在“已安装”确认 mediora-agent 已启用。
新建对话，粘贴接入提示，让 WorkBuddy 按提示配置名为 mediora 的 MCP 服务。提示缺少凭证时继续下一步；安装 Skill 和保存 MCP 地址都不能代替连接授权。

官方提供的本地技能包入口是“上传技能”，见 WorkBuddy 官方技能说明。不要只根据对话回复“安装成功”判断本地 ZIP 已导入，仍需在已安装列表核对。

2. 获取 Agent 凭证并发给 WorkBuddy

回到 Mediora 网页“设置 → 智能体接入”，找到“手动凭证”。
按需要选择权限。只验证连接时可选择“只读助手”；需要运行媒体任务、添加下载或修改工作流时，再选择对应权限。
点击“生成凭证”。在“凭证已生成”弹窗中选择“本地地址”或“外网地址”（页面提供这两项时），然后选择“MCP 配置”，点击“复制配置”。
把复制的完整 MCP 配置发给刚才的 WorkBuddy 对话，让它补齐 Mediora 连接凭证。

可以同时发送这段说明：

请使用下面的 MCP 配置完成 mediora 的凭证设置，保留已安装的 mediora-agent Skill。
凭证只用于 Authorization 请求头，不要在回复或日志中复述凭证。
先完成连接配置，不要添加下载、运行媒体任务或修改工作流。

Mediora 生成的配置类似下面这样；实际操作优先直接复制页面内容，不需要手动拼写地址或凭证：

{
  "mcpServers": {
    "mediora": {
      "type": "http",
      "url": "https://mediora.example.com/api/v1/agent/mcp",
      "headers": {
        "Authorization": "Bearer 替换为Mediora生成的Agent凭证"
      }
    }
  }
}

mediora.example.com 只是示例域名，请使用自己页面生成的地址。凭证位于 Authorization 请求头，Bearer 与凭证之间有一个空格。该配置对应 Streamable HTTP 传输。WorkBuddy 已配置其他 MCP 服务时，应保留已有配置并补充 mediora。凭证仅在生成时显示一次，保存到授权客户端后再关闭弹窗；不要把含真实凭证的配置发到公开群聊、截图或代码仓库。

3. 在自定义连接器中开启并点击“信任”

等 WorkBuddy 完成凭证配置后，打开左侧“专家·技能·连接器”，切换到“连接器”。
点击右上角“自定义连接器”，找到 mediora。
打开该连接器的开关，并点击“信任”，完成 WorkBuddy 对此 MCP 服务的确认。

较早版本可能从“插件 → MCP 服务器 → 配置 MCP”进入。入口名称会随 WorkBuddy 版本调整，当前连接器入口可参考 WorkBuddy 官方连接器说明。

4. 退出并重新启动 WorkBuddy

完成开关和信任后，退出 WorkBuddy，再重新启动应用，让新凭证、连接器和工具列表重新加载。重启后新建对话，再使用 Mediora。

5. 验证 MCP 调用和 Skill 加载

在新对话中发送：

请使用 mediora-agent Skill，检查 mediora MCP 是否可用。
读取当前可用工具，并调用 mediora_get_overview，告诉我 Mediora 当前状态和已授予的权限。
分别报告 MCP 调用是否成功、mediora-agent Skill 是否已加载。
这次只查询信息，不要添加下载、启动任务、重试任务或修改工作流。

确认 WorkBuddy 实际调用了 Mediora 工具并返回当前状态，再回到 Mediora 的“当前授权”点击刷新，查看最近使用时间、连接状态及工具调用记录。只看到“配置已保存”或“Skill 已安装”时，仍需完成这一步验证。

验证成功后，就可以按授权范围使用，例如“查看当前运行中的任务和最近失败记录”。需要整理文件时，按本页“先预演，再整理”的流程操作。

遇到问题时

现象	检查方式
Skill 已安装，但提示缺少凭证或 `AGENT_TOKEN_INVALID`	回 Mediora 生成手动凭证，把完整的“MCP 配置”发给 WorkBuddy；确认请求头包含有效凭证，并完成开启、信任和重启。
配置已保存，但对话里没有 Mediora 工具	在“自定义连接器”中确认 `mediora` 已开启并已信任，退出并重新启动 WorkBuddy，再新建对话。
一直无法连接或超时	检查 MCP 地址是否能从 WorkBuddy 所在电脑访问；NAS 地址不要写成这台电脑的 `localhost`。使用外网地址时，继续检查下文的反向代理配置。
提示需要 Pro，或缺少操作权限	在 Mediora 确认智能体接入权益和该凭证的权限。新增权限时重新生成相应凭证、更新 WorkBuddy 配置并重启。
MCP 已连接，但没有加载 Skill	在 WorkBuddy 的技能“已安装”列表中检查 `mediora-agent` 是否存在且已启用，再新建对话验证。

权限和确认

创建授权时只选实际需要的权限。下载会落到 Mediora 已配置的下载目录；工作流的智能体修改会先保存为待确认草稿，网页确认前不会自动响应新的下载。取消任务默认只取消当前一轮，停止后续计划需要明确选择。

授权详情可以查看权限、有效期和最近调用。客户端停用或凭证泄露时，从“当前授权”撤销对应授权，并移除客户端保存的凭证。常规设置里的 API 令牌不能代替 Agent 凭证；账户改密或数据库恢复后，旧 Agent 授权也可能失效。

撤销授权阻止后续调用，不等于取消已经受理的后台任务。需要停止已启动的一轮时，回到对应任务或工作流执行页另行取消。

智能体模板

整理、刮削和 STRM 页面提供“智能体模板”入口。模板固定允许的来源目录、目标及规则，启用后才供对应授权调用；应先用普通手动任务验证规则，再开放模板。

智能体发起下载或启用工作流时，支持 MCP 表单确认的客户端会弹出确认。没有表单确认能力的客户端仍应显示工具调用确认；执行前请核对链接、目录和触发范围。

先预演，再整理

需要整理临时文件夹时，先让智能体选择一个已保存的整理任务或已启用的整理模板，再指定来源文件夹。智能体会列出每个媒体文件的目标路径、会跳过的文件和预计覆盖数；目标媒体库只能来自所选任务或模板，不能临时指定。一次最多预演 500 个媒体文件。

核对方案后再让智能体执行。方案有效期为 10 分钟，只能执行一次；来源文件、目标状态或整理设置发生变化时，需要重新预演。识别结果不确定时，先核对候选和目标路径，再决定是否确认；不确定性本身不会授权覆盖目标文件。支持 MCP 表单确认的客户端会在执行前展示文件数、目标目录、覆盖数和不确定项数。

执行后可以在媒体整理页查看这一次的运行进度；完成时会收到成功和失败数量汇总。预演只生成方案，不移动或覆盖媒体文件。

反向代理与迟迟不返回

反向代理必须把 Authorization 请求头转发给 Mediora；MCP 使用持续连接，应关闭该路径的响应缓冲并延长读取超时。例如 Nginx 代理到 Mediora 时，在现有代理规则中为 /api/v1/agent/mcp 设置：

location /api/v1/agent/mcp {
    proxy_pass http://mediora_upstream;
    proxy_http_version 1.1;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

把 mediora_upstream 换成你现有配置中的上游地址。如果工具调用迟迟不返回，先核对代理是否缓冲、超时是否过短，再到 Mediora 的智能体操作记录查看调用是否到达。重新授权前不要反复生成凭证；如果账户密码或邮箱变过，需要重新走浏览器授权。

实测边界

WorkBuddy 示例记录的是桌面端手动凭证接入流程。其他客户端，以及 OAuth、表单确认、不同网络和代理环境的兼容性，仍需在对应版本上分别验证。

连接​

下载配套 Skill​

示例：WorkBuddy 接入 Mediora​

1. 先让 WorkBuddy 完成 MCP 和 Skill 安装​

2. 获取 Agent 凭证并发给 WorkBuddy​

3. 在自定义连接器中开启并点击“信任”​

4. 退出并重新启动 WorkBuddy​

5. 验证 MCP 调用和 Skill 加载​

遇到问题时​

权限和确认​

智能体模板​

先预演，再整理​

反向代理与迟迟不返回​

实测边界​

连接