AI 接入：在 MiniCheck 上读片和写批注

这份说明是给 AI agent 读的。里面有房间端点、批注的数据结构、图形怎么画、四个审片状态怎么上报，以及纯 HTTP 和本地 MCP 两种接入方式。看完就能在一条 MiniCheck 上读片、读批注、写批注，并让客户的看片页亮起「AI 审片中」。

这是什么两种接入方式端点批注对象图形格式四个状态写批注错误码

1 · 一条片子就是一个 MiniCheck

一条片子开一个 MiniCheck，四位编号。接口根、编号、sharecode 不写在这份文档里 —— 它们是这条片子的门牌，放在看片页的源码里。抓源码取这三个东西： 一条命令就够（不要用浏览器渲染后的 DOM，抓原始 HTML 最省事）：

# 接口根：源码里 grep 这个变量名
curl -s "https://insigc.com/mc.html?c=XXXX&sharecode=..." | grep -o "MC_API_BASE = '[^']*'"
# → window.MC_API_BASE = 'https://...'

# 编号和 sharecode 就在你手上那条链接里：c=XXXX 和 sharecode=...

看片页里还有一段 AI-HANDOFF 注释写着全部端点，和一段运行时才填的 JSON （id="mcAiHandshake"，结构如下，但 curl 抓到的原始 HTML 里它是空的，别指望从源码里读到它）：

// 打开看片页，取这段 JSON（人看不到，抓源码或读 DOM 都行）
{
  "doc":       "https://insigc.com/ai.html",
  "page":      "https://insigc.com/mc.html?c=XXXX&sharecode=...",
  "room":      "XXXX",
  "api":       "https://<接口根>",
  "sharecode": "<门牌>",
  "flow":      [ "POST /api/room/{room}/join...", "..." ],
  "shapes":    [ "rect", "ellipse", "arrow", "..." ],
  "rules":     [ "..." ]
}

下文的 {api}、{code}、{sharecode} 都从这三个字段里取。 没有具体链接的人，读到这份文档也调不通 —— 接口根和门牌不在文档里。

每个请求都要带 ?sharecode=，值就是上面那个字段。少带一次就会被托管网关挡成「链接不完整」。

# 取到之后，读一个房间长这样
GET {api}/api/room/{code}?sharecode={sharecode}

sharecode 不是密钥，是托管网关的门牌：不带就被挡成「链接不完整」。写批注、上报状态、读转写，一律原样带上。

2 · 两种接入方式

有 MCP 装了 FitCheck 桌面版

本机 MCP 服务里已经有现成工具，一次调用完成，还能抽帧、探片子参数、读整片音频转写：

read_notes 读批注（可带定位图）
add_note / add_notes 写批注并画图形
read_transcript 读整片音频转写
frame_at 抓某一秒的画面看
inspect_clip 读分辨率/码率/帧率/时长

片子不出本机，MCP 只把批注和图片给你。

纯 HTTP 没装客户端也行

下面第 3 节的全部端点都是公开的，任何能发 HTTP 的 agent 都能用。最小闭环三步：

POST /join 进房拿 clientId
GET /api/room/{code} 读批注和片子信息
POST /note 写批注

拿不到画面时，用 video.url 自己取帧，别猜画面内容。

3 · 端点

下表 {code} 是四位 MiniCheck 编号，{SQ} 是 ?sharecode=...。

方法	路径	作用
GET	`/api/room/{code}{SQ}`	房间信息：`review`、`notes[]`、`video{}`、`ai{}`、`host{}`
POST	`/api/room/{code}/join{SQ}`	进房，返回 `clientId`。`{"name":"MiMo 剪辑审片客观","role":"ai"}` 走 AI 通道
POST	`/api/room/{code}/ai{SQ}`	上报审片状态，头 `x-mc-client`。`{"state":"reading","model":"MiMo 剪辑审片客观"}`
POST	`/api/room/{code}/beat{SQ}`	心跳。整场每 15~20 秒一次就够
POST	`/api/room/{code}/note{SQ}`	写一条批注，头 `x-mc-client`
PATCH	`/api/room/{code}/note/{id}{SQ}`	改文字、改出点（`t2`）
DELETE	`/api/room/{code}/note/{id}{SQ}`	删掉写错的批注
GET	`/api/room/{code}/transcript{SQ}`	整片音频转写（`{segs:[{t,txt}],text}`）。没有就回 `{empty:true}`
GET	`/api/room/{code}/thumb/{id}{SQ}`	那条批注的缩略图（JPG）
GET	`/api/room/{code}/poster{SQ}`	首帧海报（JPG）
GET	`/api/room/{code}/video{SQ}`	视频流，支持 Range

最小闭环（curl）

把上面取到的三个值填进来（{api} 来自 MC_API_BASE，{code} / {sharecode} 来自链接）：

# 0) 接口根 grep 源码里的 MC_API_BASE；编号和 sharecode 来自链接
API="{api}"; CODE="{code}"; SQ="{sharecode}"

# 1) 进房，走 AI 通道
curl -X POST "$API/api/room/$CODE/join?sharecode=$SQ" \
  -H "content-type: application/json" \
  -d '{"name":"MiMo 剪辑审片 客观","role":"ai"}'
# → {"clientId":"c_1a2b3c4d", ...}  后面所有请求都带这个 id

# 2) 报到：让客户的看片页亮起「AI 审片中」
curl -X POST "$API/api/room/$CODE/ai?sharecode=$SQ" \
  -H "content-type: application/json" \
  -H "x-mc-client: c_1a2b3c4d" \
  -d '{"state":"reading","model":"MiMo 剪辑审片 客观"}'

# 3) 读已有批注和片子信息
curl "$API/api/room/$CODE?sharecode=$SQ"

# 4) 写一条批注（带图形，坐标 0~1）
curl -X POST "$API/api/room/$CODE/note?sharecode=$SQ" \
  -H "content-type: application/json" \
  -H "x-mc-client: c_1a2b3c4d" \
  -d '{"t":3.2,"txt":"左上角提亮一档","cat":"pic","d":[{"type":"rect","x":0.08,"y":0.1,"w":0.2,"h":0.22}]}'

# 5) 全部写完
curl -X POST "$API/api/room/$CODE/ai?sharecode=$SQ" \
  -H "content-type: application/json" \
  -H "x-mc-client: c_1a2b3c4d" \
  -d '{"state":"reviewed"}'

4 · 批注对象

字段	类型	说明
`t`	number	时间点，秒，可带小数。写你实际看过的那个位置
`t2`	number?	出点。给了就是一段（`t2 - t ≥ 0.2`），时间轴上画成长条；不给就是单点。一段镜头里的问题（镜头太长、节奏、同一处持续不对）用区间比单点准。客户在页面上点这条的时间码，也能自己改起点和出点
`txt`	string	文字说明。要显示的内容全写这里，不要画进图里
`cat`	string	`pic` 画面（默认）· `sub` 字幕 · `done` 批完 · `pass` 交卷
`d`	array	图形数组，见第 5 节。要指出画面哪一块时用；不填就是一条只带文字的批注
`color`	string?	`#RRGGBB`。不填就跟你这个人的身份色
`id`	string?	不填服务端生成。重发同一个 id 不会重复入库

返回里还会带 at（时间戳）、by（clientId）、name（署名）、ai（是不是机器写的）、hasThumb。

5 · 图形格式

坐标全部 0~1 归一化：x=0.5, y=0.5 是画面正中，跟 1080p 还是 4K 无关。溢出画面会被拒。

type	字段	用途
`rect`	`x,y,w,h`	矩形框，圈一块区域
`ellipse`	`x,y,w,h`	圆圈，`x,y` 是外接矩形左上角
`arrow`	`x,y,w,h`	箭头：尾 `(x,y)` → 头 `(x+w, y+h)`，负值表示向左/向上指
`pen`	`pts:[[x,y],…]`	手画线
`sub`	`y0,y1`	横字幕带：上下两条线 + 半透明填充，左右不封边
`subv`	`x0,x1`	竖字幕带
`cross`	`x,y,w,h`	准星：横竖贯穿线，找中心、对水平

所有图元都可以带 c（#RRGGBB）和 lw（线宽 px，默认 3）。一条批注可以画多个图元：

"d": [
  {"type":"rect", "x":0.06, "y":0.08, "w":0.26, "h":0.3},
  {"type":"arrow", "x":0.62, "y":0.72, "w":-0.16, "h":-0.2}
]

画上去的图形，客户在页面上可以拖位置、拉大小、换颜色。所以位置给个大概就行，不用抠到像素。

6 · 四个状态，决定看片页亮什么灯

AI 一进房（role:"ai"）状态就是 reviewing。之后每次上报都会刷新计时：

state	什么时候报	客户看到
`reading`	开始读片	绿灯快闪 ·「正在读片」
`thinking`	看完了，在整理意见	绿灯慢闪 ·「正在整理意见」
`reviewing`	开始写批注	蓝灯呼吸 ·「AI 审片中」
`reviewed`	全部写完	蓝灯常亮 ·「AI 审片完毕」

reading / thinking 三分钟不续报会自己掉回 idle； reviewing 九十秒不续报，如果房间里已经有 AI 写的批注就翻成 reviewed，否则回 idle。所以每个阶段都报一次效果最好：只在开头报，客户中途就看不出机器走到哪一步了。

顶栏那颗按钮会跟着这四个状态变：「AI 审片中」蓝色呼吸 → 「AI 审片完毕」蓝色常亮。客户不用问就知道机器还在不在干活。

7 · 写批注的约定

下面这些不是必须执行的流程，是这条片子上的约定。怎么读片、用什么工具、写几条，由 AI 自己判断；想直接用 HTTP 也行，端点见第 3 节。 角度、身份数量、批注条数全部是可选的，唯一的硬要求是：每条批注都要能指出具体位置和时间点。

署名写「模型名 + 审片角度 + 主观/客观」。角度是可选的——从下面这张表里挑一个最贴近的就够了，也可以不带角度只写「模型名客观」。这张表是词汇约定（写错了客户在过滤器里筛不出来）， 不是检查清单：不要为了让每个角度都有代表性而各写一条。

角度	管什么
`剪辑审片`	节奏、转场、镜头衔接、多余的停留
`字幕审片`	压边、可读性、出现时长、错别字
`画质审片`	清晰度、压缩痕迹、噪点、色阶断层
`构图审片`	主体位置、裁切、留白
`平台适配审片`	安全区、底部文案区、右侧按钮列会不会挡住
`品牌审片`	logo 大小位置、品牌色、禁用词
`声音审片`	响度、音乐与口播的平衡、突变
`信息审片`	卖点是否在前三秒、行动号召有没有

例如「DeepSeek-V4.1 剪辑审片客观」「DeepSeek-V4.1 剪辑审片主观」「Claude 平台适配审片客观」。不要只写 bot、AI、assistant，也不要冒用客户的名字。 主观/客观写在署名最后两个词，客户靠它筛。看片页的过滤器里有「AI 客观」「AI 主观」两档 —— 名字里没有这两个字的，会被算成客观。所以标清楚不是礼貌问题，是功能问题。 需要按不同视角分开看时，才开多个身份：每个「角度 + 主观/客观」的组合单独 join 一次（各拿一个 clientId），名字分别是「模型 + 角度 + 主观/客观」。这样客户在批注列表里能一眼分开「这条是字幕角度提的」「这条是主观判断」。 AI 不占客户名额，开几个都不会把房间挤满。 但身份多少和批注多少是两件事。一个身份就能审完整片，这也是最常见的做法。 不要因为开了几个身份，就每个身份都硬凑几条批注——某个角度看下来没问题，就一条都不写，不要为了「这个身份有产出」而编。客户要的是一条能改的问题，不是每个角度各来一条的流水账。

客观和主观都要有，但一条批注只站一边。 客观 = 能验证的事实：「字幕底边被平台文案区压掉约五分之一」「第 12 秒画面偏暗」。主观 = 你的判断和喜好：「这段节奏拖了」「这个调色偏冷」「这个转场切早了」。 只写客观就成了一张 bug 清单 —— 客户看完知道哪几帧要改，但不知道这条片子「好不好看」。所以：一条片子至少要有一两条主观判断（节奏、调色、情绪、记不记得住），哪怕最后结论是「节奏没问题」也得说出来 —— 「没问题」本身也是判断，写进批注比不写有价值。署名里写明是哪一种，客户靠它筛。
每条说一件事。复述画面、写「整体观感良好但仍有提升空间」这类话，客户读不出要改什么。字少一点通常更清楚。
写之前先看那一帧。没看过的时间点不要写。frame_at 看一眼只要一秒，比写错一条被客户指出来便宜得多。不要写完一堆再按顺序倒推秒数 —— 客户一拖进度条就能看出对不上。
方位说法必须和图形对得上。说「上边缘被裁」，框就得贴着画面顶部；说「整体下移」，框就不会在画面底部。两者打架时，客户信图形、怀疑文字 —— 这比不写更糟。
写完抽查两条。挑两个时间点重新看一眼，确认画面和你写的一致。对不上就改文字；改不了就把这条删掉，留着比删掉伤得更重。
要指出画面哪一块就画图形。只在文字里描述方位，客户不知道你说的是哪儿。反过来，整段的问题用 t2 标区间比画一个框更准。
不要生成图片、不要在图上写字。图形客户能拖动对位、能跟着时间码走，图片不能。
cat=pass（交卷）只有客户自己能点。那是签字动作，AI 不用调。done（批完了）也只在客户明确说过之后再调。
批完回报：几条、在第几秒、什么问题。不要只说「标好了」。

客户自己会调的，不用替他定死

页面上的这些，客户随时能改。AI 给了就行，别当成一次性的最终稿：

项目	客户怎么调
起点 / 出点（`t` / `t2`）	点批注上的时间码，抽屉里改「设置出点」；也能拖时间轴对位
图形位置、大小	画面上直接拖动、拉边框
图形颜色、线宽	工具栏的色板和画笔粗细
批注文字	列表里点开就能改
署名和身份色	顶栏「批注用户」
交卷（`cat=pass`）	只有客户自己能点，AI 不参与

所以：位置给大概、说法给事实，剩下的让客户按自己的判断收。

8 · 错误码

状态	error	怎么办
401	`need-pass`	这条链接另设了取件码，找发链接的人要
403	`forbidden`	没进房或 `x-mc-client` 不对，先 `POST /join`
404	`no room`	四位编号不对，或者这条 MiniCheck 已经过期回收
410	`ended` / `closed`	片子已收卷，或者这个人已交卷，不再收普通批注
429	`too many` / `room full`	同 IP 进房太频，或者房间名额满了。一个 clientId 用一整场，不要每个请求都 join
403	`budget`	这一条链接的流量点用完了，发片人账号也没有余额。响应里的 `owner` 就是发片人昵称
403	`quota`	发片人的流量点用完了（写批注 / 上传会被拒）。响应里的 `owner` 就是发片人昵称

遇到 budget / quota 怎么说：这不是链接失效，也不是权限或接口问题，而是发片人的流量点用完了。响应体里的 owner 是发片人昵称， message 可以直接念给用户（形如「发送者的流量点用完了，请联系某某」）。 AI 应当原样转述这句话，并告诉用户：联系 owner 那位去充值， 充值后原来的链接可以直接继续播放，不需要重新上传片子。不要自己编造「接口需要 app key」「链接过期了」之类的解释 —— 那会让用户找错人、白折腾一轮。

补充：房间的 budget 是「一次交付的预算」，不是硬墙。房间超额但发片人账号还有余额时，视频照常放（响应里 budgetOver: true 同时 overFlow: true），只是会从账号余额里继续扣；只有两边都见底才会真正 403。所以看到 budgetOver: true 不必立刻让用户去充值，先看 overFlow 和有没有 budget 错误。

9 · 我们自己的 agent 用这两个 skill

银赛内部跑在 WorkBuddy 上的 agent，接入的是封装好的 skill，不用手写 HTTP：

minicheck-annotate：直接在看片页同款数据上标注——框、圈、箭头、字幕带画进画面，不是生成图片。
fitcheck-share：把本地视频传到 MiniCheck，拿一条能转发的审片链接。

这两个 skill 依赖本地 FitCheck 客户端（MCP）。没有客户端的 agent 按第 3 节的 HTTP 走，能力一样，只是少了本地抽帧和片子参数探测。

10 · 为什么批注要这么写

客户在浏览器里是拖时间轴看片的。批注没有时间码，他拖不到那一刻就看不见；没有图形，他看见一句话也不知道你指画面哪里。所以要指位置时顺手画一下，比写一段方位描述省事。

另一件事：客户端会把批注缩略图烧上图形和时间码。所以你画的框、圈、箭头，最后是直接出现在客户眼前的定位图上，而不是一串坐标。