HEVC Transcodelocal quality-gated encode

让 AI 助手帮你看队列、查原因(MCP 接入)

最后更新 2026-10-25 · Hoelee Enterprise · 638, Jalan Raja Muda, Aulong, 34000 Taiping, Perak, Malaysia · me@hoelee.com

让 Claude、Cursor 或任何支持 MCP 的助手读你的转码队列,并且在安全边界内控制它。

HEVC Transcode 自带一个本机 MCP 服务:它跑在你自己的机器上,只跟已经在 127.0.0.1:8790 运行的控制台说话,永远不直接碰你的视频文件。它能做的事,你自己点界面 也能做 —— 它只是替你省下那些点击。

助手能做什么

工具回答什么问题你可以这样问
get_status_summary一眼看全:每条车道的状态、积压多少项与预计要多久、今天的战果、需决定项按类的计数、基础设施失败、磁盘/授权/后端守卫、最近事件(含发起方)。"现在队列在干什么?"
explain_items为什么:某个文件夹下接下来要处理的项、待决定项(每一项为什么被拒、试过哪些挡位、SSIM 到多少),或某一个文件的逐次尝试留痕(后端/设备/挡位/命令/失败历史)。"这个文件夹为什么跳过 327 个?"
get_recent_activity最近的运行记录与事件,最新在前。每条事件都写明发起方:业主在界面上点的、AI 助手、还是软件自己。"我离开的时候有失败吗?"
control_lanes开始一条车道、做完当前这一项再停、或立刻停。默认是「做完当前这一项」;「立刻停」会丢掉正在编码那一项的进度,必须明确要求。"GPU 车道做完当前这个就停。"
trigger_operation扫描文件夹、跑后端自检、或导出质检/空间报告。它立刻返回一个任务号;任务在跑时再问一次会跟上同一个任务(`reused: true`),不会重复扫盘。"扫一下有没有新视频。"
preview_decision_action对待决定项的干跑:这一类涉及几项、多少源数据、这一类允许哪些动作,并给出一个一次性确认令牌(5 分钟)。什么都不会被改变。"如果我放行那 12 个会怎样?"
apply_decision_action执行预览过的动作。必须带预览给的令牌;如果类、动作、条数或条目集在这期间变了,服务端会拒绝并要求重新预览。助手的指令是先问你,再动手。"好,放行。"

它做的每一个动作都会写进事件日志,发起方标记为 ai-agent —— 所以「昨晚助手做了什么」是控制台能回答的问题。

它不能做什么(这是设计,不是限制)

两步接入(约 2 分钟)

  1. 先让 HEVC Transcode 跑起来。控制台在 127.0.0.1:8790(只在本机;除非你自己 开了局域网访问)。
  2. 把服务加进你的助手。最省事:设置 → AI 助手(MCP)→ 复制配置,它会把你这份安装的 正确路径拼成 JSON 放进剪贴板。

    想自己写,长这样:

    {
      "mcpServers": {
        "hevc-transcode": {
          "command": "C:\\Users\\\\AppData\\Local\\Programs\\HEVC-Transcode\\python\\pythonw.exe",
          "args": ["-m", "rt.mcp_server", "serve"]
        }
      }
    }
    • Claude Desktop:设置 → Developer → Edit Config → 粘进 claude_desktop_config.json → 重启 Claude。
    • Cursor:设置 → MCP → Add new MCP server → 粘同一段。
    • 其它客户端:只要支持 MCP over stdio 就行 —— 这就是一个普通 stdio 进程。
  3. 问它一句。试「现在转码队列在干什么?」。它答出真实数字,就通了。

值得问的问题

看起来不对劲的时候

现象什么意思怎么办
ERR_SUPERVISOR_DOWN控制台没在跑,或换了端口 先把 HEVC Transcode 打开,再问一次
助手里看不到这些工具改完配置没重启客户端重启助手
回答里出现 reused: true同一个扫描/自检已经在跑,服务跟进了既有任务, 没有重复扫盘不用处理,等它跑完(回答里会写它已经跑了多久)
ERR_CONFIRM_MISMATCH预览之后、执行之前掉进了一个文件 让它重新预览 —— 令牌绑定的就是那一组确切的条目
ERR_LICENSE_REQUIRED软件许可协议还没接受 在软件窗口里点同意 —— 助手不能代签

错误码

助手拿到这些码时,应该解释清楚然后停下来,而不是盲目重试。列在这里,是为了排障时能直接引用 那个确切的字符串。

全部 17 个错误码(点开)
错误码含义
ERR_ANSWER_TOO_LONG答案超出体积预算,被裁剪了(看 `truncated`)。
ERR_ARG_INVALID某个参数的值不被接受。
ERR_ARG_MISSING缺少必填参数(例如 `scope=file` 时的 `file_id`)。
ERR_CLASS_NOT_BATCHABLE这一类不能做批量处理。
ERR_CONFIRM_EXPIRED确认令牌超过 5 分钟了 —— 重新预览一次。
ERR_CONFIRM_MISMATCH预览之后类、动作、条数或条目集变了(期间掉进了一个文件)—— 重新预览一次。
ERR_CONFIRM_MISSING调用没有带 `confirm_token`。
ERR_CONFIRM_REQUIRED这个动作需要确认令牌:先预览一次。
ERR_CONFIRM_USED这个令牌已经用过了。令牌设计上就是一次性的。
ERR_HTTP控制台有回答,但不是预期的 JSON(可能是反代页、被拒绝,或后台任务已达上限)。
ERR_LICENSE_REQUIRED软件许可协议还没接受,或当前授权不允许这个动作。只能由业主本人在软件窗口里点同意 —— 助手不能代签。
ERR_NOT_FOUND那条车道、队列行或工具不存在。
ERR_SUPERVISOR_DOWN连不上本机控制台(127.0.0.1:8790)。
ERR_TIMEOUT控制台没有及时回答(它正忙着扫描或预览)。
ERR_UNMAPPED控制台拒绝了,但没有对应的专用错误码;原因在消息里。
ERR_UNSUPPORTED_ACTION这个车道或这一类决定不允许该动作。
ERR_UNSUPPORTED_OP后台任务类型只能是 scan / report / doctor。

隐私 —— 这一段请一定看

  1. 你不问,它不外发。只有你向助手提问时它才去读状态,后台没有任何自动上传。
  2. 视频画面永不上传。发给 AI 服务商(Claude / Cursor 等)的只有文字:队列进度、 画质分数、文件名。你的视频文件本身,一个字节都不会离开这台机器。
  3. 随时可以关。从客户端配置里删掉这一项即可;如果连文件名都不能出内网,可以把客户端指向 本机运行的离线模型(Ollama 之类)。

HEVC Transcode 自己不发任何遥测。

需要 HEVC Transcode 1.1.0 或更新版本。MCP 服务是一个普通 stdio 进程, 不带任何额外依赖 —— 它用的就是软件里已经装好的那个 Python。

← 返回产品页