@q253595422/dsh-imagegen-video 1.30.4 → 1.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,129 @@ Attribution for third-party code is in [NOTICE](./NOTICE).
5
5
 
6
6
  ## Releases
7
7
 
8
+ ### 未发布 — 导演台在桌面 App 里顶部两颗按钮点不动
9
+
10
+ 只在 macOS 桌面 App(Electron)里出现,浏览器与 web 宿主都复现不出来,所以拖了这么久:宿主的窗口拖动条 `[data-window-drag]` 被 Electron 当成标题栏(`-webkit-app-region: drag`),**它不是一个 CSS 层,点在那里的事件由浏览器进程吃掉、页面根本收不到**。导演台面板是 `position: fixed; inset: 0`、`.shell` 又几乎铺满窗口,于是它最上面那一排——左栏的折叠与关闭——正好落在宿主窗口左上角那块拖动区里。
11
+
12
+ - **修复**:给 `.shell` 补 `-webkit-app-region: no-drag`。动态面板不该被窗口手势穿透。规则挂在 `.shell` 而不是 `.root`,因为 `.root` 是 `pointer-events: none`,它根本不参与命中测试,拖动区照样赢。
13
+ - **为什么以前测不出来**:`app-region` 在普通浏览器里是空操作,预览页、headless、web 宿主全都测不到。这次的证据是真 Electron 窗口(`titleBarStyle: 'hidden'`,与桌面版同款)里的一次真实 OS 点击:同一枚按钮、同一个坐标——不加规则时 DOM 收不到任何事件,加了之后立刻触发;同一窗口里放在拖动区外的对照按钮两种情况都正常,所以不是点击本身没到。
14
+ - **回归守卫**:`verify-ui-contracts.mjs` 新增一条源码断言(`-webkit-app-region: no-drag` 必须在 `.shell` 上),并做过反向注入验证——把这条规则删掉,断言立刻报出这个失败。这条只能从源码守,因为任何浏览器都看不见这个差别。
15
+
16
+ ### 1.33.1 — 局域网部署不再 403;多模型对比从历史打开不再空白
17
+
18
+ 两条都来自用户上报(#50 / #49)。数据层没有改动:两处的磁盘与路由本来都是对的,坏在门口那道守卫和面板那一句 `Promise.all`。
19
+
20
+ - **#50 局域网访问时全部接口 403**:`isLoopbackRequest` 只认「连接来自回环地址」,而浏览器直连本机网卡(`192.168.x.y`)时 `remoteAddress` 永远是那个网卡地址——于是宿主把 `webServer.host` 绑到具体网卡后,插件每一条 `/api/dsh-imagegen` 都回 `403 forbidden: loopback-only`。现在认两种权威之一:连接来自回环,**或**请求的 `Host` 精确等于监听绑定地址。绑定地址本身就是用户的显式选择,所以它授予权威;`0.0.0.0` / `[::]` 是通配、不是某个地址,一律不授予。真正防 DNS rebinding 的 `sec-fetch-site` 与 Origin 同源检查对两种权威都照旧生效——Host 校验只是让 Origin 比较有了意义,不是替代它。**没有新增 `allowLan` 开关**:多一个开关就多一个「开了就全放行」的误配面。绑定地址按运行时值宽松读取而不是按类型收窄——本地 devDependency 的 `Config.host` 还只写了两个字面量,照类型写会让新宿主支持的网卡地址在类型层就被抹掉。
21
+ - **#49 多模型对比重启后点开只剩提示词**:`loadHistoryGroup` 用的是 `Promise.all`——对比组每个模型一个成员条目,**任何一个成员任何一张图取不到**(文件被清理、404、一次瞬时失败),整批 rejected,`setImages` 与 `setBoardView` 都不执行,结果板停在「提示词 + N 张」的空白。单条生成只有一个成员,所以照常出图;四条模型的对比把「什么都不显示」的概率放大了四倍,正好是报告里的形状。现在每个成员各自 settle,一个坏成员只损失它自己。失败数**如实返回**而不是吞掉:静默少画两张会被读成「这次对比只出了两张」。
22
+ - **两条都是可复跑的用例,不是「改完看着没问题」**:`smoke-lan-bind-auth.mjs` 把真实路由表起在本机网卡上走真实 HTTP,10 条——含「外域 Host」「外域 Host 且自带自洽 Origin」「cross-site」「Origin 不匹配」四种仍然 403,以及**不传 `bindHost` 时局域网客户端保持旧 403** 这条反向控制(没有它,「一律放行」也能让正例全绿)。`smoke-history-group-images.mjs` 6 条,最后一条是反向对照:同样的输入交给旧的 `Promise.all` 折叠必须整组失败——否则断言太弱,测不出这个 bug。两个都进了 `pnpm test`,另有 `test:lan-auth` / `test:history-group` 单独入口。`smoke-lan-bind-auth.mjs` 自己探测本机非回环 IPv4,探测不到就明确 SKIP(不是「绿」)——测试只在作者那台机器上过,等于没测。
23
+
24
+ ### 1.33.0 — 导演台换成真 3D + 时间轴;画布补上层级、锁定隐藏、套图、找节点、体检与目录
25
+
26
+ 本版把 `v1.32.0` 的「静态构图导演台」升成「一段能播的镜头」。完整说明见 [docs/releases/v1.33.0.md](./docs/releases/v1.33.0.md)。
27
+
28
+ - **视口换成 three.js 真深度缓冲**:原来那层是手写的 2D 画家算法(metaball 球拼人、逐球排序)。它做不到的不是「不够精致」,而是**遮挡**——立方体摆在人前面挡不住人。换 three 的全部理由就是这一件事,已由 `verify-stage-3d.mjs` 的 V3 用像素证据守住(立方体在前 → 人偶只剩头肩)。人偶仍是同一份骨架求解与关节半径,两个渲染器画出同一种体型。
29
+ - **底部时间轴**:播放/暂停/逐帧/循环、2–15 秒、30fps、拖动 scrub、逐轨关键帧菱形、五种运动轨迹。时间以「秒」存、帧号是渲染期派生量;整份时间轴集中在 `stage.timeline` 而不是散落到 actor/camera 上,删角色时轨道不会成孤儿;关键帧所有字段可选,同一时刻「转身」与「摆姿势」是一条而不是两条。
30
+ - **轨迹与位置关键帧不是互斥的**:牧野在这一点上报 `motionPathsCannotCoexistWithPositionKeyframes`,我们选「活动区间内轨迹覆盖位置关键帧」。轨迹段在轨道上画成琥珀横条——一段区间用横条、一个时刻用菱形。
31
+ - **导出视频走宿主 ffmpeg 而不是 WebCodecs**:宿主本来就有 ffmpeg(`src/clip-compose.ts`),放上去之后画幅不受浏览器编码器能力表限制,也不用给用户看「当前浏览器不支持此画幅的 H.264 编码」。代价是逐帧上传(一帧 1–3MB,串行),取舍与「中止时已上传的帧靠会话超时清理」这个已知缺口都写进了 `stage-export.ts`。
32
+ - **没有 WebGL 就退回 2D**,不报错也不白屏。这条同时是验收里必须显式断言的原因:3D 静默回退会让一张「看起来还行」的截图其实验的是早就不用了的渲染器。`stage-preview-shot.mjs` 因此先断言视口 canvas 真有 WebGL 上下文,再加 `launchChrome({ gpu: true })`——那个 helper 的默认 `--disable-gpu` 会让 `getContext('webgl2')` 返回 null。
33
+ - **从截图里捞回并修掉的三个真问题**:① 结尾那颗关键帧菱形被轨道的 `overflow-x: hidden` 裁成「◀」——`left: 100%` 配 `margin-left` 只把中心拉回,右半边仍探到轨道外,改成 `calc(<百分比> - 3.5px)` 并给滚动容器留 `padding-inline`;② 轨迹条用 `brand-primary` 混色,而这套主题的品牌色**就是黑与白**(浅 `#0f1115` / 深 `#f9fafb`),`color-mix` 混出 `oklab(0.177 …)` 一条灰带,换成 `state-warn-primary`(两主题下都是 `#f59e0b`);③ 首帧取景贴着几何包围球算,最边上那个角色名标签被视口切掉一半(「角色B」只剩「角色」),放宽到 1.6 倍并改成首帧自适应取景。
34
+ - **调研结论留档**:[`docs/research/muye-director-desk.md`](./docs/research/muye-director-desk.md) 记录牧野工作台那块导演台的实测证据(WebGL2 真 3D、蒙皮 GLB 的 `JOINTS_0`/`WEIGHTS_0` 映射、固定 30fps 的校验文案、导出自动建节点连线)与「我们跟了什么、没跟什么」。
35
+ - **人形是放样出来的人体,不再是关节球串**:每一段(骨盆、腹胸、颈、头、大臂、小臂、大腿、小腿、手、脚)都是一串椭圆截面的放样面——胸腔左右宽前后薄、小腿肚后厚前薄、大腿上粗下细。原来那版是「每个关节一颗球 + 每根骨一根等粗圆柱」,横截面永远是圆,于是躯干是一根管子、大臂是一根管子,远看是球关节木偶、近看是几根香肠。肩肘膝胯踝保留外露小球:木偶人偶本来就这样,也补上两段放样弯到极限时的缝。「生成参考图」一并改走 3D——视口里是人体、导出却是 2D 球串的话,用户拿到的是一张和眼前完全不同的图。四处硬伤(头是扁碟、头又撑成 5.5 头身的大鸡蛋、肩线落在颈上导致手臂浮空、骨盆底是平切圆盘)都是拿放大图看出来的,现在由 `smoke-stage-humanoid.mjs` 的 11 条几何断言守着,做过反向注入(把头改回扁碟 → H1 / H11 立刻红)。
36
+ - **木偶的样子主要来自材质与光**:原来只有环境光 1.15 + 一盏平行光、无阴影,等于把形体全抹平。现在环境光 0.22 + 半球光 + 开投影的主光 + 冷色背光,木身 `#d9b483` 与关节 `#a7814f` 分两档颜色(浅木身配深关节才是木制人偶的辨认特征)。找过现成模型:唯一能直接下载的 CC0 木偶只有 6 个网格、肘膝不能弯;Mixamo 派生的 `Xbot.glb` 不能随包分发;`mannequin.js` 是 GPL-3.0。所以问题不在造型来源,在渲染。
37
+ - **导演台视口拖动/滚轮/重置一度全是死的**:面板把拖动写进自己的 `view` state,而它没有任何消费方——3D 场景的 `orbit()`/`zoom()`/`resetView()` 写好了却没有调用方;就算调用了也不动,因为它们只改 `orbitState`,出帧靠 `render(stage)`。现在 `StageViewRenderer` 加了三个可选转发方法,场景在相机变化后自己重画一帧。`stage-preview-shot.mjs` 补了一条逐字节对比拖动前后画布的断言。
38
+ - **验证**:`pnpm run test:stage` 79 条离线断言(含真 ffmpeg 编码 6 帧 → 真 mp4)、`verify-stage-3d.mjs` 真浏览器真 GPU 5 条、`stage-preview-shot.mjs` 五种宽度两套主题的截图 + WebGL 断言;画布侧 9 个纯函数套件(geometry 71 / layers 12 / node-flags 16 / prompt-set 14 / node-search 21 / health 18 / align 21 / history 23 / example 8)与新反向用例组全部接入 `pnpm test`;全量 `pnpm test` 与 `pnpm typecheck` 无回归。
39
+
40
+ - **图层顺序:置顶 / 置底 / 上移一层 / 下移一层**。这一版之前画布上**没有层级概念**:绘制顺序就是 `document.nodes` 的数组顺序,由「谁先被创建」决定,用户看不见也改不了。于是后来放上去的卡永远盖住先放的(想在图上面写字,字必须比图晚创建,否则被压在图底下、框选也选不到),而被盖住时画布只会描一条黄边说「这张被挡住了」,却不能把它拿到前面来。现在四个动作各有三个入口:右键菜单、⌘K 目录、键位(`⌥]` / `⌥[` 走一格,加 `⇧` 走到底,与 Figma 一致)。**顺序存在数组里,不新增 `z` 字段**:老文档零迁移、不会有「两个节点 z 相同」的并列态、撤销栈里一次层级调整就是一次普通的数组变化;末尾在最上面。**多选当刚体**:`layer-order.ts` 先把整组折成一个槽位再跨过紧邻的那一张,逐个 `splice` 会让三张卡的内部次序反转(a,b,c 变 c,b,a),而用户没有要求过。**`coveredNodes` 跟着改了语义**:原来只按几何包含判定谁盖住谁、不看绘制顺序,层级可改之后就成了真 bug——小卡明明画在上面却被报成被盖住,而置顶之后提示还不消失;现在方向由下标唯一决定。**关掉 react-flow 的选中提权**(默认给选中节点加内联 `z-index: 1000`,被置底的卡一点中就跳回最上层,刷新后又是对的),`flowNodes` 显式写下标为 `zIndex`。验证:`smoke-canvas-layers.mjs` 12 条(整组跨一位、已到位不动、幂等、上移再下移回原样、不复制对象)+ `smoke-canvas-geometry.mjs` 的 G10–G12(层级决定方向、置顶后不再报、三张嵌套)+ 契约组 11 条(一次 `mutate`、`moved === false` 不写、四行接到对的方向、右键四个方向齐、键位读 `event.code`)+ 反向注入 7 条。
41
+ - **真机截图捞回来的一个真问题**:被完全盖住的那张卡上,「与「X」完全重叠」的琥珀徽标**自己也被盖住了**。它原本挂在被盖住卡片的右下角,而那恰好是它最不能待的地方——以前只是靠着 react-flow 给选中节点加的内联 `z-index: 1000`(拖动会选中被拖的那张)碰巧浮上来;选中提权一关,它就彻底消失,截图里只剩一圈也在下面的黄边。现在徽标由画布覆盖层 `.world` 按被盖住卡片的右下角绘制:它说的是画布层面的事实(谁压着谁),就该由画布这一层来说,坐标跟着世界变换一起平移缩放。
42
+ - 上面这条由两条反向断言守住:徽标回到卡片内 → 红;覆盖层不再画它 → 红。加上 `smoke.mjs` 的 (7e):右键四行都在且带键位、置顶真的写进文档、置底后一次撤销回原样、已在最下面再置底既不写也说出来。
43
+ - **拖动时的吸附参考线**。吸附(`snapOffset`)一直都在,但它只改坐标、不留痕迹:卡片在离邻居 3px 时自己「跳」到贴边,用户看到的是一次无法解释的位移。现在拖到对齐位时画一条红线(`snapGuides`),松手就消失——线与吸附**分开算**:吸附拿拖动原点和位移,线拿「已经落位之后」的位置,只问「谁跟谁重合」;写成一个函数会让「吸附算错」和「线画错」两种症状混在同一个返回值里。容差是世界像素的半个像素(位置在拖动里被取整,所以「重合」就是精确相等,留半个吸收缩放浮点误差),同一条坐标上的多根线合并成一个区间——一列整齐的卡只画一条长线而不是三条重叠的。与节点过滤同一条纪律:只对着画面上的卡吸附与画线,对着藏起来的卡会让可见的那张停在空处、而画面上没有任何东西解释它为什么停在那里。测试:`smoke-canvas-geometry.mjs` 的 GG1–GG6 + 契约组 3 条 + 反向注入 4 条。
44
+ - **节点锁定 / 隐藏**。上一版把叠放顺序交给了用户,跟着来的第一件事就是「我不想动它」和「我现在不想看见它」。锁定(`⌥⇧L`)拒绝四件事:拖动、删除、批量删除、整理画布——锁不住 Delete 的锁等于没锁,而用户正因为相信它锁上了才敢把它留在那里。隐藏(`⌥⇧H`)把卡片从渲染、框选、`⌘A`、缩略图、`fitView` 里一起摘掉,**连线跟着一起消失**(只过滤卡片会在画面上留下一条通往空气的线,那比整条线不画更让人困惑)。两个标记都住在 `node.metadata` 里,老文档零迁移。三个刻意的取舍:① 锁定按「这组里还有没锁的吗」决定方向,混选时按下去是**锁**而不是一个永远猜不准的三态开关;② 复制 / 粘贴 / 原地复制**都清掉标记**——复制一张锁住的卡,用户要的是「再来一份能动的」,复制一张藏起来的卡则会让粘贴完屏幕上什么都没有;③ 隐藏是单向门,所以底栏常驻一条「N 张卡片已隐藏 / 全部显示」,找节点(`⌘F`)也仍能搜到藏起来的卡并标出「已隐藏」,跳过去时自动把它叫回来。测试:`smoke-canvas-node-flags.mjs` 16 条(严格 `true`、引用相等、顺序、`unlockedIds` 不改入参、连线两端、复制真实路径)+ 契约组 9 条 + 反向注入 7 条。
45
+ - **套图(提示词组):N 条不同提示词各出一张**。原来画布上只有 `count`(同一条出 N 张,用来挑最好的一张);套图是它的反面——一个配置卡上挂一组带标题的提示词(正面 / 侧面 / 背面…),跑一次各出一张,标题落到结果卡上。**两者的语义相反,没有合并**:把套图做成 `count` 的扩容会让填 3 想出三视图的人拿到三张一样的正面。住在自己的字段 `node.metadata.promptSet`(`{id,title,prompt}[]`,上限 12),老文档零迁移。UI 是 composer 那一侧的三态切换(单张 / 套图);卡片上只显示一枚只读徽标「套图 · N 条」——**不在卡片上再加编辑入口**,否则撞「一个提示词只准有一个编辑入口」那条守卫(那条守卫守的是「看起来能编辑、写入却没人读」的假入口)。提交路径按套图跑:每条独立 `api.taskSubmit`、各自 taskId、各自占位卡、各自标题,回填路径按 taskId 配 asset 天然就是「一个任务一个占位」。三条边界全在纯函数层 `canvas/prompt-set.ts`:空提示词条目丢弃(否则白跑一次)、标题截 24 字、超上限截断——写侧 `normalizePromptSet` 保留空条目(用户正在打字,保存瞬间消失会让光标跳走),读侧才丢。测试:`smoke-canvas-prompt-set.mjs` 14 条 + 契约组 1 条(三处入口 + locales 三块数量)。
46
+ - **调研留档与一个可复跑的大图基准**:[`docs/research/canvas-workflow-benchmark.md`](./docs/research/canvas-workflow-benchmark.md) 对照 LibTV / Figma Weave / ComfyUI,按 P0 保存恢复、P1 定位与编辑响应、P2 复用交付给出固定场景与验收门槛;`scripts/benchmark-canvas-interaction.mjs` 在 200 / 1000 节点上量缩放帧耗时、平移帧间隔与搜索命中时间(`long-animation-frame` 优先,取不到时退回 `longtask`),只量不写宿主画布,声明为手动脚本——它需要一个已经导入基准画布的真宿主,天然进不了门禁。
47
+
48
+ - **刚装好的画布不再自带一份「已保存的画布」**:以前打开画布标签页时,只要画布库是空的就立刻 `canvasCreate` 落盘一份,并往里塞一对示例节点(标题「示例:第一张图」+ 一句柴犬提示词)。用户从没建过它,下拉里却多一份,删掉还得多按一次;更糟的是空态(那排快捷卡)因此永远渲染不出来——种子固定注入两个节点,`nodes.length === 0` 从未成立。现在首屏与「+」给的都是**内存草稿**(状态条如实写「未保存」),只有用户真往里放了东西(建节点 / 落图 / 粘贴 / 拖文件)才创建画布;删掉最后一份画布同样回到空草稿,而不是悄悄补一份新的。示例种子与它的三语文案随之下线。反向注入实测:把挂载时的 `canvasCreate` 放回去 → E1 红(「opening the canvas with an empty library creates no canvas on disk」)。
49
+ - **测试不再往用户真实的数据目录里写画布**:上面那条「首次打开就落盘」是产品行为,另有一条测试侧的:`~/.dsh/dsh-imagegen/canvas/` 与测试目录只差一个 `DSH_HOME`,不设它就等于指到家目录,而 `canvas/create` 是真写盘。2026-10-13 到 10-15 三天里这样攒下 1408 条 `gone`/`deck`/`extract`/`polish`/`files`(内容是一个 `report.txt`),用户的画布下拉从可用变成 1425 条滚不完的列表。`smoke.mjs` 早在 `c10cf07` 就有了隔离,但那补的是**一个脚本**而不是一条规则。新增 `scripts/verify-test-isolation.mjs`:扫出所有会写画布的脚本,要求它们的 `DSH_HOME` 指向 `mkdtempSync()` 建出的目录;接进 `pnpm test` 与 `test:negative`(新组 `isolation`)。判据是「赋值成了什么」而不是「有没有赋值」——反向验证在这上面连挂三次:注掉的赋值、字符串字面量、`= previousDshHome`(恢复原值)都曾被当成隔离证据,每次都是「缺陷还在、守门却绿」。反向注入实测:把 `smoke.mjs` 的 `mkdtempSync` 赋值注掉 → 守门红(退出码 1)。
50
+ - **整理画布(⌥⇧F)**:一张有向图排成从左到右的列。分层不另起一套,直接复用执行器用的 `planLayers`——整理出来的第 N 列就是运行时第 N 层,看图顺序与跑图顺序不会打架。四条硬边界:**有环拒绝**(环上的节点没有「第几层」,照排会得到一张井然有序却跑不起来的图);**没接线的卡片不混进第一层**(它们不是流程源头,落在流程下方两倍行距的停放带里,保持原有左右顺序);**原地整理**(锚点是当前包围盒左上角,视野不动,否则按下按钮的瞬间像点空了);**幂等**(连按两次逐字节相同)。层内按用户原来的 `y` 排序而不是边的插入顺序——他有意摆在上面的那张卡,整理后还在上面。整件事是一次 `mutate`,撤销按一下就回到整理前。反向注入 8 条(几何组 7 条 + 契约组 1 条视口)。
51
+ - **运行前就说清楚哪张卡跑不了**:`canvas/readiness.ts` 把「缺什么」从卡片内的一枚徽标扩成一次全图扫描,与 `node-body.tsx` 读同一组事实(标注卡不算提示词、空 asset 不算参考图、`renderer: 'code'` 免模型渠道)。「运行工作流」旁边的箭头按钮现在会写「2 个节点没准备好:缺提示词」而不是等用户按下去、跑到一半才发现。
52
+ - **上一次运行的失败留在画布上**:`canvas/run-marks.ts` 把结局折成两种标记——实线红「这次失败」、虚线橙「被跳过,没跑」。只有 `completed` / `cycle` 不留痕;`cancelled` 也落痕,因为「按停之前就已经失败」的节点是真的坏了。新一轮开始时清空,单节点重试只摘自己那颗红标(下游仍没有产物,标记不能跟着清)。缩到 40% 时颜色会先糊掉,所以两种标记同时用线型区分。反向注入 6 条(其中一条「取消分支漏落痕」正是新断言当场抓出来的:纯函数说对、接线没做)。
53
+ - **全部功能目录(⌘K / 底栏放大镜)**:画布的能力原来散在底栏 14 格、节点悬停条、右键菜单三处,每一处只在自己那类动作里给得全,于是「拼接视频」要先选中两段视频才看得见。现在一张 47 行的可搜索表把全场动作收在一起:六个分组(添加 / 运行 / 编辑 / 视图 / 画布 / 帮助),中英文同义词都能搜(「接片」「排版」「ffmpeg」「storyboard」),↑↓ 只在能点的行之间走,回车执行。**不可用的行不隐藏**,压暗并写明原因(「先选中至少两段视频」)——藏起来等于告诉用户「这个功能不存在」。每一行都由 `Record<CapabilityId, () => void>` 强制接上一段真代码,契约组比对目录与动作表两侧的 id,多一行少一行都红。反向注入 6 条(几何组 4 条:只搜标题 / 藏起不可用项 / 方向键停在灰行 / 灰行排前面;契约组 2 条:某行没接 / 执行前不关弹窗)。
54
+ - **顺手修掉的两个「声明被浏览器丢弃」**:`--dsw-alias-border-secondary`(画布提案条的接受/丢弃按钮)与 `--dsw-specific-sidebar-nav-item-hover`(侧栏入口的悬停底色)在 DSH 里都不存在,整条 `border` / `background` 声明会被丢掉——按钮没边框、入口悬停毫无反馈。换成契约文档给的 `border-l2` 与 `interactive-bg-hover`。这条是 `verify-native-ui` 在 `DSH_ASAR_DIR` 指到真机安装目录时才会报的,平时 skip 所以一直没露。
55
+ - **找节点(⌘F / 左下放大镜)**:画布少则五张卡、多则上百张,用户知道「我要找那张写着樱花的图」,却只能缩到 10% 自己扫。现在一个搜索框同时搜标题、正文、提示词、模型名:中英文、全角空格、多词「都要命中」;同一张卡只出一条结果(字段按 标题 > 正文 > 提示词 > 模型 逐级退让),结果行显示的是**命中的那段原文**而不是标题——搜「樱花」命中一张叫「街景」的图时,只显示标题这一行就解释不了自己为什么在结果里。回车跳过去、选中它、并把它放进视野正中:视野计算走有单测的 `focusViewport`(0 尺寸视口、Infinity 输入、缩放夹取都在那里守住,NaN 一进 `transform` 整个画布会变空白且不报错),顶栏与底栏是浮层,所以可画区域从顶栏下方算起。⌘F 原本会拉起浏览器的页内查找——在一个铺满画布的应用里,那个框永远找不到用户想找的**卡片**。
56
+ - **画布体检:一次看全「这张图为什么跑不起来」**:执行器的报错是「跑到哪一步才说哪一步坏了」,用户面对一张图要改一个、跑一次、再撞下一个。`canvas/graph-health.ts` 一次算全五类问题——环、残线(指向已删除节点的连线)、空配置(没有上游输入)、未就绪配置(缺提示词 / 模型 / 渠道)、孤立产物。三条与执行器对齐的口径:环的判定直接复用 `planLayers`(两份图论逻辑迟早分叉成「体检说能跑、按下却失败」);环只描**真正在环上**的节点,不含挂在环后面的下游(否则用户顺着高亮找不到那根首尾相接的线);残线绝不因为它把某个节点算成「有上下游」。清单出现在「运行工作流」的选项菜单里——用户打开它正是在问「这一次怎么跑」——每一条都可点,点了跳到那张卡并选中。阻断项永远排在提醒项前面:一条「这张图有环」如果排在「有张图没人用」后面,用户可能根本滚不到。
57
+ - **空画布多一张「载入示例」**:前五张快捷卡都在要求用户先知道自己要放什么、怎么连,而第一次打开画布的人恰恰不知道。第六张一次落一条 提示词 → 配置卡 的链(列间距取整理画布同一档,两卡中心线严格对齐),选中配置卡并提示「按生成就能出图」。整件事是**一次** `mutate`:分几次写会在撤销栈里留下几条记录,按一次 Ctrl+Z 只撤回半条示例,剩下的半条既跑不了也删不干净。
58
+ - **历史面板:一次退回「还没乱的那一版」**:撤销一次只退一步,而真实用法是「刚才连着做了七八件事,想退回还没乱的那一版」——那时用户不知道要按几次,也不敢按。现在**按住 Shift / Option 点撤销**、或**右键撤销**,弹出这张画布的全部历史:每步一行(「移动 3 个节点」「删除图片节点」),点一行就退回那一步。文案与撤销按钮调同一个 `describeStep`,两处不可能对不上。三条边界:当前状态也占一行(不可点,否则用户以为最上面那行就是现在);坏快照**截断不跳过**(`stepsBack` 是相对栈深的偏移,跳一格会让下面每行都退到错的地方);只动视口的一步不列出。回退 N 步是一次文档替换而不是循环 `undo()`——栈同步改、`document` state 不是,中间帧读到的 `documentRef` 还是旧的。重做栈逐条回填,所以退回去之后 Ctrl/⌘+Shift+Z 仍能一步步走回来。规范在 `history-model.ts` 的 `historyRows`(单测 19 → 23 条),面板只负责画。
59
+ - **⌥ 系列快捷键在 macOS 上从来没生效过**:真机实测(headless Chrome + CDP 派发原生键码)确认,按住 Option 时 `event.key` 是**该布局下的组合字符**——⌥F 给 `ƒ`、⌥A 给 `å`、⌥H 给 `˙`。所以 `altKey && key === 'f'` 永远不成立,「整理画布」的 ⌥⇧F 自上线起按了没反应且不报错,源码读起来却一切正常。全部改按 `event.code`(物理键位)。同时补上一组对齐键位:⌥⌘← / → / ↑ / ↓ 四边对齐,⌥⌘H / V 水平、垂直居中,⌥⌘E 水平等距(垂直等距没有键位——写在表里而按不出来比不写更坏)。键位只在 `ShortcutHelp.tsx` 的 `CANVAS_SHORTCUTS` 写一份,多选对齐条的 tooltip 通过 `shortcutKeysFor` 反查,两处不会走散。
60
+ - **目录从 30 行长到 47 行**:补进历史面板与 8 个对齐/分布动作(选中不足两张 / 三张时压暗并说明原因),全部接真代码。
61
+ - **历史面板的两个「点下去之前先知道」**:悬停某一行时,画布上这一步会动的那几张卡描一圈虚线(`outline`,不改几何,指针扫过一列行时画布不抖;预览不写文档,否则撤销栈里会多出几十条空步骤);退回去之后选中这一步动过的卡,并与目标文档求交(「删除」类步骤点名的节点已经不存在,不筛就会选中幽灵)。Esc、点一行、关面板三个出口都清预览。
62
+ - **目录行尾的键位徽章**:每行显示对应快捷键,没有的不显示、不留空列;灰行不显示(等于承诺能用)。键位只从 `shortcutKeysFor` 取一份。做这件事时揪出一个一直在撒谎的文案:`canvas.duplicate` 写的是「创建副本 (Ctrl+D)」,macOS 上按的是 ⌘D,而这半句括号也不参与反查,于是目录里那一行永远没有徽章。现在文案只留动作名,右键菜单与节点工具条改走 `labelWithKeys`;`canvas.paste` 同一类问题,快捷键表里这两条也补了 `action`。
63
+ - **预览构建的两个打包清单漏项**(`three` 的裸包名与它的 `examples/jsm` 子路径分别列):漏掉时预览页整块白屏,报的是 `three is not defined` / `unexpected require`,读起来像 3D 那一块的 bug,实际缺的是清单里的一行。
64
+ - **一条只看得见第一处的守卫**:套图「编辑器不许进参数排」的契约检查只取第一个 `.composerControls` 块,注入点在它之后,于是缺陷回来、检查照样绿(反向用例组报 FALSE GREEN)。改成按标签配对切出所有参数排逐个检查;contracts 组 93/93 现在全部能打红。
65
+ - **多选对齐条(左/中/右、上/中/下、水平/垂直等距)**:选中两张以上时,底栏上方出现一条 8 枚按钮的对齐条;两张时两枚「等距」压暗并**写出原因**(「至少要选中三个节点」)——一枚只是灰着、不说为什么的按钮会让用户以为是自己选择方式不对。规则全在 `canvas/align-model.ts`(21 条单测):只动选中、**分组是刚体**(只选中组里一个成员时,整组按同一个整数 delta 平移,否则用户以为只对齐了一张卡、实际把组拆了)、内部跑到**不动点**(宽度奇偶不同的卡居中时半像素取整会让第二轮再动一像素,所以交给界面的必须是映射的不动点)、结果全在整数格点上。接线侧钉了三条:一次 `mutate`(撤销一次退回到对齐前,而不是「按一次退一张卡」)、`moved === 0` 不写(已经对齐的图按一下不该多出一条空撤销)、拒绝与「没变」都说出来。
66
+ - **对齐条为什么不在 `bottom: 66px`**:它第一版就是又一个绝对定位浮层,真浏览器布局守卫当场量到它在 860px 及以下压住缩放排 805–7625px²。底栏、缩放排、缩略图当年各自绝对定位时犯过同一个错,改成同一条 `flex-wrap` 行之后才不再互相压住。现在拼接条与对齐条都是那一行的成员、各自 `flex-basis: 100%` 独占一行,几何上不可能重叠;守卫也扩到 8 个两两组合,失败时逐对报面积。
67
+ - **撤销/重做按钮说得出「这一步是什么」**:`canvas/history-model.ts`(23 条单测)把前后两份快照折成一句话——新增 / 删除 / 移动 / 编辑 / 连线 / 断线 / 分组 / 改标题 / 换背景,互相独立的两类合成「改了 N 项」。三条口径:删节点**连带**删掉的线不算第二次变化(否则每次删卡都变成「混合操作」,tooltip 永远说不出「撤销删除」);新节点自带的自动连线归给新增;只动视口不报成改了节点。`arrange` 刻意不由纯函数产出——「整理画布」与「多选手拖一批节点」在两份快照里是同一件事,猜错就是撒谎。接线侧每 160ms 防抖算一次:`document` 在拖动时每帧都换对象,不防抖等于每像素 `JSON.parse` 一次几十 KB 的栈顶快照。
68
+ - **分镜镜头时长按模型收窄,台词装不下时说一句**:`SHOT_SECONDS` 补上 12 / 15,并按所选模型**显式声明**的 `catalog.durations` 收窄——模型只收 6/10/15 就只列这三个,而不是拿一个 4 秒去换一次 400。这里刻意用 `catalog.durations` 而非 `durationsOf(catalog)`:后者在模型未声明时返回面板通用默认 `[5,10]`,会把 Seedance 实际支持的 4–15 一起抹掉。老文档里存着当前模型不收的秒数时把该值插到选项最前,不静默改写文档。`shotSpeechFit` 按 4.5 字/秒 + 2 秒表演余量估时,超了在这一镜下面单独显示一行警示——是**提醒**不是**错误**:不染红边框、不禁用运行按钮。
69
+ - **分镜执行接上身份参考;「接上一镜尾帧会丢参考」写在板上**:`submitShot` 原先只做了 `carry` 的尾帧 → 首帧,`castRefsFor` / `castPromptOf` 只在两个 composer 里被调用,所以钉住「阿禾」后在分镜里连跑十条,十条都没有她的图。现在 `cut` 与 `carry` 首镜带最多 4 张身份参考(`MAX_SHOT_REFERENCES`),第一张进 `frames.image`、其余进 `frames.images`,读不出的那张跳过而不是整镜失败;顺带修掉 `castLine` 的 0 基序号(提示词里原本写「参考图 0 是角色…」)。`carry` 第 2 镜起带不上参考**不是漏接线而是契约互斥**(`first_frame` / `last_frame` 与 `reference_image` 在 Seedance / MiniMax 里不能混用)——接缝优先是对的,但用户只会在成片里看见她悄悄变了,所以板上多一行说明会丢哪些镜头、丢几个,对应行挂一枚「不带身份参考」角标:一粒角标而不是整行染色,这一镜仍然能跑。反向注入实测:把 `castSlots` 写死成 0 时所有源码 grep 仍绿,只有 SB5 的运行时断言变红(请求体里没有那张图)。
70
+ - **「镜头衔接」下拉在 380px 卡片里被截断**:那一格只有 65px,而 `接上一镜尾帧` 需要 94px;英文 186px、俄文 203px(那一格缩到 27px,几乎只剩箭头)。根因是三格 `flex: 1` 的 basis 为 0、永远等分。改成按内容起算 + 允许换行:中文仍是一行 26px,英俄各两行 58px,镜头列表本来就是 `flex: 1` 的滚动区,少 32px 挤不掉底部按钮。三种改法在真浏览器上量过 380 / 420 / 560px × 三语;`verify-canvas-layout.mjs` 新增三语量宽断言,反向注入(退回三格等分)实测变红。
71
+
72
+ ### 1.32.0 — 姿势人偶升级成导演台:一个场景、多个角色、多台机位;画布底栏改成三档层级
73
+
74
+ 本版把 `v1.31.0` 的「原生姿势节点」升成导演台。完整说明见 [docs/releases/v1.32.0.md](./docs/releases/v1.32.0.md)。
75
+
76
+ - **卡片瘦身 + 全屏编辑面**:卡片只剩「预览 + 机位名 + 打开导演台 + 预设条 + 生成参考图」;摆位与摆姿搬进全屏三栏面板(左栏场景与角色/机位列表、中央视口带视角切换与视锥、右栏场景参数、底部机位截图与场景描述)。
77
+ - **一个场景里多个角色**:每个角色各自成一张遮罩、按中心深度排序合成。合并进同一个距离场会把接壤处的轮廓融成一块——后排的人会像贴在前面那人身上的一个鼓包,前后关系丢失。
78
+ - **加角色立刻重新取景**:新角色排在右侧 1.2 m,不重新取景它会站到画外,用户会以为按钮没生效。这牵出更深的一处:环绕相机的水平注视点原先硬编码在原点,三个人并排时只拉远相机不够,画面中心仍盯着原点、第三人被裁。现在 `PoseCamera` 带可选 `targetX` / `targetZ`(缺省 0,姿势面板行为不变)。
79
+ - **老文档零迁移**:只有 `metadata.pose` 的节点按单角色舞台读出,不写盘、不改字节;写盘时 `stage` 与 `pose` 双写(`pose` 镜像 `actors[0].rig`),带三个角色的文档在旧版插件里仍是一张能用的姿势人偶;读盘以 `stage` 为准。
80
+ - **成品仍是普通图片**:机位截图导出 1280×1280 PNG 落成节点 `asset`,下游全链路零改动。
81
+ - **两条检查是从真机走查里回来的**:遮罩贴回时漏了 `fieldCell` 倍放大(人偶体块只有骨架的 1/2.4),以及上面那条水平注视点。二者都写进了 `scripts/smoke-pose-stage.mjs`(20 条)与真浏览器守卫 `scripts/verify-pose-panel.mjs`。
82
+ - **底栏从「18 个同权重图标」改成三档层级**:原来一排 17 个 40px 方块加 5 条竖线,每个都得悬停才知道是什么,读不出「从这里开始」。现在(1)左侧一个**实底 `+`** 收掉文本 / 画板 / 姿势 / 分镜 / 文件 / 配置六个建节点图标,点开是它们各自的菜单,`+` 在任何画布应用里都是「新建」;(2)5 条竖线换成留白的分组间隔——1px 线在 13 个格子上画出了一张表格,每格看起来同权;(3)右侧**「运行工作流」带文字**,箭头并进同一块药丸只开选项菜单——一排纯图标只能靠逐个悬停学会,而「把这张图跑成片」是画布存在的理由。(1)和(3)与弹簧引擎的边界是显式的:`+` 仍是 40px 方块、照常参与悬停放大,只是多了个实底类 `.dockPrimary`;带文字的主动作用 `data-dock-static` 退出引擎——引擎写的是内联 `width`,那会把文字药丸压到 40px 并裁掉标签。真机走查还捞到两个离线测不出的:`+` 菜单最初借 `.contextMenu` 又覆盖了它的 `transform`,弹出位置偏了 52.5px;分组间隔取 10px 时 900px 面板下「删除」掉到第二行,看起来像少了一个按钮——现在收到 6px,并在 `scripts/verify-canvas-layout.mjs` 补上**行数检查**(720px 及以上必须单行;反向注入把间隔调宽,860px 立刻变红)。
83
+
84
+ ### 1.31.0 — 画布四件新事:Agent 改画布前先提案、连线说明用途、节点成组、原生姿势人偶
85
+
86
+ 本版是 `v1.30.4` 之后累积 40 个提交的一次发出,含四块独立内容与两条社区 issue 的修复。完整说明见 [docs/releases/v1.31.0.md](./docs/releases/v1.31.0.md)。
87
+
88
+ - **Agent 写画布先出提案,用户点头才落盘**:八个画布工具此前一调用就改文件,乐观锁挡得住「两个写入者同时改」、挡不住「用户不在场」——模型可以在用户睡觉时把画布重排一遍。现在写操作产出提案(存 `canvas/proposals/`,与 `pages/` 分开),画布右上浮出提案条,常驻一句「接受之前画布不会有任何变化」。接受是增量的:只增删提案点名的节点与连线,用户在这期间改的标题、拖过的坐标都留着。
89
+ - **连线有了语义角色**(`input` / `first` / `last` / `reference`)。首尾帧以前是「`connections` 数组前两张图」,删一条边再重连就把首尾帧对调,画布上看不出区别。`role` 是可选字段,1429 份真实画布零迁移、往返 0 变化。
90
+ - **生成前自动补边**:图拖到配置节点旁边却没拉线时,生成会完全忽略它。现在提交那一刻把边缘间距在 1.5 个目标节点短边内、尚未连入的图片补成连线,最多 4 张;只在提交时补、不在拖拽时猜,且不夺已有角色。
91
+ - **节点成组**:框选 → 右键「成组」,拖任一个整组一起动。协议只加可选字段 `groups?`,不升 version;1429 份画布全量往返 0 份凭空长出 `groups`。
92
+ - **原生姿势节点**:17 关节层级 + 正向运动学 + 透视投影,纯 Canvas 2D 手写,不引 three.js(WebGL 在远程桌面/禁用加速时是最容易失效的一环)。11 个预设、逐关节三轴滑杆、导出 1024×1024 PNG。它不是新节点类型,而是 `type: 'image'` + `metadata.pose`,下游全链路零改动。
93
+ - **一条过期的提议会把整张画布对 Agent 锁死**:用户在接受之前随手删掉一个提议点名的节点,那条提议就应用不上了。`draftOf` 每叠加一次就抛错,于是这张画布上的 `add_canvas_node` / `update_canvas_node` / `connect_canvas_nodes` **全部永久失败**——只有用户碰巧去点一次「接受」才能恢复(`acceptOne` 遇到同一条提议会自己把它移除,判断是「它不可能再生效,留着只会挡住队列」)。两处对同一件事有两种判断,没有道理。现在读、写都跳过并移除这种提议,并在 note 里如实说明「N 条提议已作废」——写路径也照常工作,不再被一条早已作废的提议挡住。反向注入实测:只跳过不清理 → F22 红;写路径不说 → F22 红;读路径不说 → F22 红。
94
+ - **`update_canvas_node` 能改 config 节点产出什么了,也能改节点尺寸**:`add_canvas_node` 收 `mode` / `width` / `height`,`update_canvas_node` 一个都不收——于是「加的时候选错了」只能删了重建,而重建会换掉节点 id、坐标和已经连好的线。探针实测:update 传 `mode` / `width` / `height` 全部被静默忽略,工具还回一句「This call changed nothing」,模型会以为改成了。现在三个字段都与 add 对齐;`mode` 只接受 config 节点(写到图片节点上直接报错,而不是在文档里长出一个谁也不读的键),非法值仍由 schema 的 enum 与工具内的 `parseMode` 拦。反向注入实测:三个字段都不认 → F23 红;不拦非 config → F23 红;`parseMode` 放行 → 宿主的 enum 先挡下了,这一层测不到(注释里已写明)。
95
+ - **一条用户已经改过的提案,不再让 `read_canvas` 整个失败**:用户在接受之前自己删掉了提案点名的节点,那条提案就对不上了。`read_canvas` 和写工具走的是同一个叠加草稿(`draftOf`),于是**只读工具也抛错**——探针实测:「A pending change on this canvas no longer applies…」,模型连「画布现在长什么样」都看不到,而用户那边一切正常(`acceptOne` 自己会把过期提案移除)。现在读路径跳过应用不了的提案,并如实说明「N 条改动对不上、已略过」;写路径仍报错(起点不确定时继续算,会把那条坏掉的差异固化进新提案)。同时把「待确认 N 条」改成只数真正叠进草稿的条数,否则会出现「1 条待确认」加「另有 1 条已略过」这种总数只有一条的自相矛盾。反向注入实测:读路径退回抛错 → F22 红;只数总数 → F22 红;跳过但不报告 → F22 红。
96
+ - **config 节点会告诉 Agent 它产出什么,Agent 也能造出视频配置节点**:config 的 `metadata.mode`(image / video / text)决定按 run 得到图片、视频还是文字,但 `projectNode` 没投影它——模型只看到「这是个 config」,判断不出该不该往这里连图片。同一处还有一句恒为真的死判断:`createNode` 里「`metadata.mode` 没设就写成 `image`」,而 `metadata.mode` 从来没被赋过值,于是 Agent **根本造不出视频配置节点**(而视频配置正是「连两张图做插帧」的那个)。现在 `mode` 进投影、进参数表(enum 由 schema 挡非法值)、进文本渲染的标签(`[config:video]`),省略时仍默认 `image`。反向注入实测:去掉投影 → F21 红;把取值固定回 `image` → F21 红。
97
+ - **`add_canvas_node` 把一直生效的 `width` / `height` 写进了参数表**:`createNode` 从第一天就在读这两个键,传了也确实生效,但 schema 里没声明——模型只能靠猜,猜不到就用默认尺寸。现在补上声明,并用一条断言把「schema 声明的参数」与「代码真正接受的参数」锁在一起,免得下次再漂。反向注入实测:删掉声明 → F20 红。
98
+ - **Agent 加的节点依次排开,不再全叠在原点**:`add_canvas_node` 的说明写着「Omit x/y to place it in a free column to the right of the existing nodes」,实现却把缺省钉成 `0,0`。探针实测:连着加 A、B、C 三个节点,三个坐标都是 `(0,0)`——用户打开画布只看到最上面那一个,还以为 Agent 只加了一个。现在省略 x 就落在「现有节点最右边 + 一个列间距」,间距取画布自己的 `NODE_GAP`(90),模型明确给了坐标则照用、不被覆盖。反向注入实测:去掉自动摆放 → F19 红。
99
+ - **Agent 删掉节点时,分组里不再留下指向它的悬空 id**:用户在画布上把几个节点框成一组,Agent 只认识节点和连线,删掉其中一个之后组里仍留着那个 id——探针实测 `groups[0].nodeIds` 是两个,其中一个已不存在。画布自己删节点走的是 `pruneGroupsField`(去掉悬空成员、清空则整组消失、本来没有 `groups` 字段就继续没有),提案这条接受路径漏了它。现在 `apply` 复用同一个函数,两种删除语义不再各写一套。这一条同时守住老画布:写回时若 `groups` 变成 `undefined` 就删掉这个键,`pruneGroupsField` 的意义正是「1429 份不带 `groups` 的老画布,第一次删节点不该因此长出一个 `groups: []`」。反向注入实测:去掉 `pruneGroupsField` → F17 红;把「没有键」改成「写空数组」→ F17/F18 各自红。
100
+ - **`list_canvases` 带出待确认条数,两个工具的计数对得上了**:`nodeCount` 只数已保存的节点,Agent 刚提议的节点不在里面,而 `read_canvas` 看得到——探针实测 list 说 1 个、read 说 2 个。两个数字打架,模型会以为自己提议失败,于是再提一遍。现在每行多一个 `pending`(复用下拉「待确认」标记的 `countByCanvas`,不为每份画布各扫一遍目录),`nodeCount + pending` 正好等于 `read_canvas` 给出的节点数;渲染成文本时也会写明「N change(s) awaiting the user's accept」。反向注入实测:去掉 `pending` → F16 红。
101
+ - **`read_canvas` 与写工具用同一个起点,读得到自己刚提议的改动**:写工具一直在「真实文档 + 本待确认提案」的草稿上算(这是连着的两步操作能成立的前提),但 `read_canvas` 只读真实文档。于是 Agent 刚提议加了一个节点、回头一读却是空白画布,还附一句「This canvas is empty. Create nodes, wire them…」——模型以为自己没加成功,再添加一遍。探针实测:`add` → `read`(0 个节点)→ 再 `add`,同一个标题落进两条提案。现在读写共用同一个 `draftOf()`,读到的这份还明确标注「这些只是提议,用户没接受、他看到的画布上还没有」。测试套件里 B1 原来断言「读工具仍然说空,这正是还没接受该有的样子」——那条断言把缺陷写成了规格,现在改成正面要求,并补上「接受之后这句必须消失」(否则模型每次读都被告知有未接受的改动,于是反复提议同一件事)。反向注入实测:把 `read_canvas` 改回只读真实文档 → B1 红。
102
+ - **Agent 改连线角色时,改的是那一条线,不是被当成「什么都没改」**:`connect_canvas_nodes` 发现两端已经连着就直接返回,哪怕这次明确传了不同的 `role`。真实用法正好踩在这里——Agent 先 `connect(A → B)`(默认 `input`),接着说「把这张设成首帧」再调一次带 `role: 'first'` 的连接。第二次调用被当成无改动,工具还回一句「This call changed nothing, so there is no pending change to accept」,模型于是以为自己设好了;而视频插帧读的正是 `role`,用户拿到的是首尾帧用错了图。更深一层:`diffOf` 只比连线的 **id 集合**,从不比内容,所以「改一条已有连线的角色」在提案机制里根本不存在——即使工具改了草稿也算不出差异。现在协议里加了 `updatedConnections`(只带真正变过的键,与 `updatedNodes` 同源),`diffOf` 按 `roleOf` 的语义比对(`'input'` 与「没有 role」等价),`apply` 找不到那条边(用户已断开)时明确报 `proposal-stale` 而不是静默跳过,`coerceProposal` 也把认不得的角色当坏文件挡在队列外。界面上这类改动单独一句「调整 N 条线的角色」,三份语言表都补齐了。反向注入实测:恢复「边已存在就 return」→ F13 红;`diffOf` 不比对角色 → F13 红;`apply` 找不到边时改成 `continue` → F14 红;去掉角色白名单 → R5h 红。
103
+ - **读不懂的提案不再永久卡在队首**:`proposals/` 是旁路目录,谁都能往里写(老版本写的、手工改过的)。一条 `change.title` 是数字、或者补丁里字段类型不对的提案,之前读得出来、排进队列,接受时 `apply` 成功返回,`store.save` 却因为文档不合法抛「malformed canvas document」——而「应用不了就自己出队」那条路只在 `apply` 返回 `undefined` 时才走到,于是它一直占着队首:用户点多少次都是同一条错误,后面本来能用的提案全被挡住。现在两道门:读入时把 `change.title` 的类型一并校验(形状不对就当坏文件跳过,与其余字段一致),接受前再用文档校验器验一遍结果——不合格按「永远应用不了」处理,移除并如实报错。探针实测过前一种在修复前后从「点不动」变成「根本不出现在队列里」。反向注入实测:去掉读入校验 → R5f 红;去掉接受后校验 → R5g 红(报的正是那句 `malformed canvas document`)。
104
+ - **接受提案期间切了画布,不会再把当前画布换成另一本**:`acceptProposal` 要先写本地编辑、再等接受接口返回,两个网络往返之间用户完全可能点开别的画布。返回的文档属于**那本**画布,此前直接 `setDocument` 就会把眼前的画布换成另一本的内容,而项目下拉仍指着当前这本,旧 `revision` 还会顺着下一次 autosave 写到错的画布上。`writeCanvas` 早就为同一种竞态装了 `live.id !== next.id` 的守门,这条路径漏了。现在两个位置都检查画布有没有换过(成功路径与错误路径各一处),换过就原地返回——提案在服务端已经应用,切回去读到的就是新文档。反向注入实测:删掉那道检查、把它挪到 `setDocument` 之后,各自变红。
105
+ - **本地编辑保存失败时,接受提案先停下**:接受前要先把用户那笔还没 autosave 的编辑写出去,但 `flushPendingCanvas` 返回 `void`——`writeCanvas` 内部的失败被吞成 `false`,调用方 `await` 一个「什么都没有」也就看不出区别。于是写入失败照样接受,服务端基于它那份没有这笔编辑的文档应用提案、返回整份新文档,客户端用它覆盖本地并推进 `syncedRef`:用户刚拖的节点、刚改的标题彻底消失,autosave 也不会补写。现在 flush 返回成败,失败就中止并说明原因,屏幕上的编辑原样留着。反向注入实测:去掉那道检查、把返回值改回 `void`,各自变红。
106
+ - **提案摘要按当前语言渲染,不再永远是中文**:提案条上其余每一行都走语言表,只有摘要这一行是 Agent 工具用中文拼好后写进提案文件的——英文、俄文用户看到的是中文。现在服务端只记结构化数量(`counts`),句子由客户端按当前语言渲染;旧提案(已落在磁盘上、没有 `counts`)退回它自带的那句。反向注入实测:服务端不写 `counts`、俄文表漏一个键,S1/S2/S3 各自变红。
107
+ - **顺带删掉的连线不再算作一条独立改动**:删节点时,`diffOf` 把它连带消失的连线也记进 `removedConnectionIds`,提案条于是显示「删除 1 个节点、断开 1 条线」,让用户以为漏了一条改动。`apply` 删节点时本来就会过滤这些线,diff 现在同样只报「两端都还在、却没了」的。
108
+ - **连发的提案不再随机重排**:Agent 一次任务连发多条提案时常落在同一毫秒,而队列的 tie-break 是 `id.localeCompare`——uuid 是随机的,于是顺序也跟着随机(探针实测八次里两次被重排),用户看到「先加节点、再连线」被翻成反的。时间戳现在在进程内严格递增。
109
+ - **过期的提案不再卡在队首挡住后面所有改动**:`apply` 是纯函数,一条提案点名的节点被删掉后,以后每一次接受都会失败。它此前会一直留在队列头,而界面只让用户点队首那一条——后面本来能应用的提案全被它挡着,用户连点三次「接受」看到的都是同一条 `proposal-stale`,队列一动不动,除非自己想到去点「丢弃」。探针实测确认过这个死锁。现在过期提案在接受失败的同时把自己从列表里移除:错误照旧报(用户需要知道这条没生效),但那把卡住队列的钥匙由服务端收走。反向注入实测:去掉那行移除,R5c / R5d 各自变红。
110
+ - **接受提案现在可以撤销**:接受是一次真正的画布改动,但它此前完全没进撤销栈。用户接受后觉得不对、按 Cmd+Z,弹掉的是他上一次手动编辑——接受的结果跟着一起消失,那笔更早的工作再也回不来,而界面上看起来「撤了一次」。现在接受成功时先记一份快照再换文档(顺序反了会压进「接受之后」的文档,撤销变成空操作),失败路径不记(文档没变,空转的历史项会让下一次撤销失灵)。反向注入实测:去掉快照、以及把快照挪到换文档之后,各自都让验收脚本变红。
111
+ - **接受「改节点」的提案不再回退用户刚拖的坐标**:Agent 改动过的节点此前被记成**整份节点**,接受时整份替换文档里的那份——于是「提议把标题改成 X」之后用户把节点拖到别处、再点接受,节点会静静跳回提议时的位置。探针实测:拖到 `1234,567`,接受后回到 `100,100`;而提案条上正写着「接受之前,画布不会有任何变化」。现在 `updatedNodes` 记的是**字段补丁**:`{id, fields, metadata}`,接受时只在当前文档上覆盖提案点名的那些键,`metadata` 也逐键合(用户之后换的模型、点上的 cast 不会被「改一个 prompt」顺带抹掉)。旧格式的提案文件(整份节点)在读取时归一成补丁,结果与它当初的意图一致。
112
+ - **接受的连线必须两端都还在**:`apply` 加连线时此前只查 id 是否重复,不查端点。用户在提议之后删掉下游节点,接受照样成功,文档里于是留下一条指向不存在节点的边——画布自己的删除语义是「删节点连带删连线」,两边不一致会渲染出一条画不出来的幽灵边。现在端点缺一个就报 `proposal-stale`,与「提案点名的节点已经被删」同一类结局。
113
+ - **反向验证**:把 `nodePatchOf` 换回整份节点、把 `apply` 换回整份替换、删掉端点校验,F10 / F11 / F12 各自变红(实测 3 failed / 20 passed),还原后 23 项全绿。
114
+ - **Agent 写画布先出提案,用户点头才落盘**:八个画布工具此前一调用就改文件,模型可以在用户不在场时把画布重排一遍。现在写操作产出提案(存 `canvas/proposals/`,与 `pages/` 分开),画布右上浮出提案条,写明「接受之前,画布不会有任何变化」。接受时**增量**应用:只增删提案点名的节点与连线,用户在这期间改的标题、拖过的坐标都留着;两个窗口同时写由 `save(next, revision)` 那把乐观锁挡下,报 `canvas-conflict` 让用户重试。
115
+ - **接受一条不作废后面几条**:每条提案都记 `baseRevision`,但接受时**不拿它当闸门**。按 revision 比对会砸在最常见的路径上——Agent 一次任务连着提议三条(加节点、加配置节点、连线),三条的 baseRevision 是同一个数;用户接受第一条后 revision +1,第二三条全被判过期,界面写着「还有 2 条在后面」却一条都点不动。它想防的三件事各有更合适的机制:`apply` 的增量语义(不覆盖用户编辑)、`save` 的乐观锁(并发)、`apply` 返回 `undefined`(节点已被删)。接受逻辑收敛到 `ProposalStore.acceptOne`,路由与测试跑的是同一段代码——此前测试自己重写了一遍流程,于是测试绿着、线上坏着。
116
+ - **提案条的浮层位置量出来,不写死**:它与画布的 `.errorToast` 曾都定在 `top: 14px`,而注释还写着「刻意错开」——注释描述意图,不是代码。现在画布实测顶栏高度后传给提案条(窄面板下顶栏 `flex-wrap` 换成两行,47px→83px),提案条按实测值排在它下面;错误提示出现时再用 `max()` 取两者较高的那个。真机验收脚本把顶栏(真实规模:选择器 + 标题 + 七个 30px 图标按钮)、错误提示、提案条三样一起画出来量命中,写死 `top` 会立刻变红。
117
+ - **删除画布时清掉它的提案**,不留下永远不再展示的孤儿文件;清理失败不影响删除本身。
118
+ - **接受提案前先把本地未同步的编辑写出去**:用户在拖动节点之后、autosave 的 650 ms 计时器到期之前点了「接受」,那笔拖动还只在浏览器内存里。accept 接口只带 `canvasId` + `proposalId`,服务端基于自己那份文档应用提案并返回整份新文档——客户端直接拿它替换本地视图,拖动就被静默抹掉,而且因为 `syncedRef` 同时被推进,autosave 也不会再补写。实测确认过:不先写就接受时,节点停在 `0,0` 而不是 `1234,567`。现在 `acceptProposal` 先 `await flushPendingCanvas()`(走与 autosave 同一条写入路径,含冲突读回重试),再发 accept。
119
+ - **下拉里能看到别的画布上有改动在等**:提案条只显示**当前打开**那本画布的待确认改动,Agent 在别的画布上提了改动、用户切走之后就再没有地方能看到它们。列表接口现在带回每份画布的 `proposalCount`(一次 readdir,不逐画布读盘),下拉的选项写作「标题 · 有 N 条待确认」;没有提案的画布不带这个字段,而不是写 0。
120
+ - **这些标记会自己更新,不用切画布**:`proposals` 接口现在一次遍历同时返回「本画布的提案」和「每份画布的条数」,画布每 5 秒轮询提案时顺带刷新下拉。此前只在切画布时刷一次——用户停在画布 B、Agent 在画布 A 上提了改动,那条提示永远不会出现。一份画布都没打开时也照常轮询(空 `canvasId` 只返回计数、不返回任何提案),不然「刚打开面板」那段时间下拉是空的。
121
+ - **非 JSON 响应不再是一句「(HTTP 404)」(#48)**:此前生图链路上 9 处 `JSON.parse` 失败分支各自拼一句 `上游接口返回了非 JSON 响应(HTTP 404)`,既不带请求地址,也没说返回的其实是一页 HTML。事后形态最难查:网关把 `/models` 挂在根上(「检测模型」绿灯),而 `/images/generations` 只在 `/v1` 下(每次生成必失败),用户拿不到任何自查线索。现在报错形如 `上游接口返回了非 JSON 响应(HTTP 404, text/html):https://host/images/generations —— 返回的是网页而不是接口响应,通常说明渠道的 API 地址少了路径(例如末尾缺 /v1)或填成了站点首页`。空响应体、二进制响应体、纯文本各有对应的一句,纯文本给截断摘要而不是把整页 markup 贴进来。
122
+ - **同一句判定只写一处**:新增 `src/upstream-diagnosis.ts`(`bodyShapeOf` / `diagnoseNonJsonBody` / `requestAddress`)。视频引擎 1.30.x 已经单独修过这个 HTML 判定并留了内联正则——同一件事第二份实现,正是这次三条链路各说各话的原因。现在视频引擎的 `readJsonWithText` 也改用共享判定。
123
+ - **括号里只报媒体类型,不带参数**:最初把整条 `Content-Type` 写进句子,于是消息里出现 `text/html; charset=utf-8`。视频套件 `V1m`(「返回的 markup 不得被贴进消息」)因此在一条**根本不含 markup** 的消息上变红——守门抓错了对象,和它要防的 bug 一样费事。现在 `mediaTypeOf()` 只留 `text/html`;消息短一截,`charset=` 也不再把读者的注意力从「你的地址填错了」上带走。
124
+ - **错误码一律不变**(仍 `upstream-invalid` / `video-submit-failed` / `video-upload-failed` 等):这次改的是那句话,不是失败分类,面板与诊断按码分组的行为不动。**不做 `/v1` 自动回退**——那会静默改写用户填的地址语义,且无真网关可验;把地址与原因说清楚比替用户猜更诚实。
125
+ - **Magpie 网关能发现图像模型了(#47)**:Magpie 的 `/v1/models` 只返回聊天模型,图像条目在 `?kind=image` 后面(老版本认 `X-Magpie-Drawers: 1` 头)。旧实现「第一个返回记录的候选就赢」,普通列表必然先命中,于是「检测模型」绿灯、图像模型恒为 0。现在图像发现自己走一遍带 `kind=image` 的候选并带头,且兼容 Magpie 两种私有形状(`kind:"image"`、嵌套 `modalities.output:["image"]`)。
126
+ - **回退有两条,不止一条**:`?kind=image` 报错或 404 要退回普通候选;**作用域列表返回 200 但里面认不出图像模型**(网关静默忽略未知参数)时也要回退再合并。少了后一条,结果就是「检测成功但一个模型都没有」。聊天模型列表不受影响:不请求 `kind=image`、不带 Magpie 头。
127
+ - **测试**:新增 `scripts/smoke-upstream-diagnosis.mjs`(7 组,驱动真实生成路径断地址与成因、且断言 markup 不进来)与 `scripts/smoke-magpie-discovery.mjs`(10 组)。均已接入 `pnpm test` 与 `test:negative`(新组 `magpie` / `diagnosis`)。反向用例实测能打红:magpie 4/4、diagnosis 3/3,各自因**目标断言**变红。
128
+ - **反向用例本身踩到的两个坑**(都已修):① 把两种 Magpie 形状的注入写成「全部条目标成图像」,会先撞上另一条用例的断言,报成「RED but wrong reason」;并列的识别条件必须各自独立注入。② 注入 HTML 判定时若连 `/v1` 那句一起删,会先命中 `/v1/` 断言——注入要只摘掉它要证明的那一个条件。
129
+ - **边界如实说明**:没有对真实 Magpie 实例发起过调用,全部基于 issue 里用户实测的接口行为与桩 fetch;`?kind=all` 未实现(issue 标为「必要时」)。
130
+
8
131
  ### 1.30.4 — 接通 Nbility 的 MiniMax-H3;修好 DSH 0.2.2-rc.3 的侧栏回归
9
132
 
10
133
  - **版本说明**:1.30.1 与 1.30.3 这两个号从未打过 tag。1.30.1 的内容随 1.30.2 一起发过;1.30.3 那次 Release 在跑之前被取消,仓库里没有 `v1.30.3`,npm 上也没有。为避免复用已被占用的号,本次以 **1.30.4** 发出,**包含 1.30.3 说明页里的全部内容**,外加 `v1.30.2` 之后完成的侧栏修复。
package/README.md CHANGED
@@ -83,6 +83,7 @@ dsh plugin --profile web add ./q253595422-dsh-imagegen-video-X.Y.Z.tgz
83
83
  | **无限画布** | 把提示词、参考图和生成节点连成可迭代的创作流程。 |
84
84
  | **视频节点与拼接** | 视频节点与图片节点同一套控制;多选后按画布位置拼成一条成片。 |
85
85
  | **分镜节点** | 一列镜头各出一段视频,可接上一镜尾帧;成品就是普通视频节点,同样能拼接。 |
86
+ | **3D 导演台** | 一个场景摆多个角色与机位,时间轴打关键帧,导出视频或参考图。 |
86
87
  | **时间线与身份锚定** | 成片可以在时间线里排序、裁剪、加转场再拼;钉住的角色/物品会跟着后续每一次生成。 |
87
88
  | **电商套图** | 从商品参考图生成主图、卖点图、场景图等成套素材。 |
88
89
  | **服饰穿戴** | 商品试穿与角色搭配;人物、服装、姿势来自内置图库,自己的模特库就在人物图库里,也可上传或 AI 生成。 |
@@ -103,7 +104,20 @@ dsh plugin --profile web add ./q253595422-dsh-imagegen-video-X.Y.Z.tgz
103
104
  <details>
104
105
  <summary><b>画布、文件节点与技能细节</b></summary>
105
106
 
106
- - 支持图片、文本、视频、生成配置、文件与**分镜**节点;图片节点可标注、移除背景或拆分图层。
107
+ - 支持图片、文本、视频、生成配置、文件、**导演台**与**分镜**节点;图片节点可标注、移除背景或拆分图层。
108
+ - **导演台**(原「姿势节点」):一个场景里摆多个角色、多台机位、天空与地面,视口是 three.js 真三维——前后遮挡成立(立方体摆在人前就真的挡住人),没有 WebGL 的机器自动退回 2D,不报错、不白屏。底部时间轴固定 30fps:播放 / 暂停 / 逐帧 / 循环、时长 2–15 秒、拖动 scrub、逐轨关键帧菱形与五种运动轨迹。顶栏「导出视频」逐帧渲染后交给宿主 ffmpeg 编成 mp4,落成一个普通视频节点并与导演台连线;「生成参考图」导出的就是视口里那一帧(1280×1280 PNG)。成品仍是普通图片 / 视频节点,下游生成与导出不需要知道「导演台」存在。老画布里的姿势节点按单角色舞台读出来,零迁移。
109
+ - **节点成组**:框选几个节点右键「成组」,之后拖任一个整组一起动;解散、改名、删成员都会自动收拾。框的位置由成员算出来,不存第二份坐标。
110
+ - **图层顺序**:置顶 / 置底 / 上移一层 / 下移一层,右键菜单、⌘K 目录、键位(`⌥]` / `⌥[`,加 `⌥⇧` 置顶置底)三个入口。顺序存在节点数组里、不新增 `z` 字段,老文档零迁移;多选时整组当刚体跨一位,不会把组内次序弄反。
111
+ - **锁定 / 隐藏**:`⌥⇧L` 锁定的卡片不再跟随拖动、也不会被删除或批量整理(仍可选中,否则没法解锁);`⌥⇧H` 隐藏的卡片从渲染、框选、`⌘A`、缩略图、`fitView` 一起摘掉,连线同步消失,底栏留一条「N 张卡片已隐藏 / 全部显示」把它叫回来。复制出来的卡片不带这两个标记。
112
+ - **全部功能目录(⌘K)与找节点(⌘F)**:一张可搜索的目录把六个分组、四十多个动作收在一起,中英文同义词都能搜,↑↓ 只在能点的行之间走;不可用的行不隐藏,压暗并写明原因。找节点同时搜标题、正文、提示词与模型名,结果行显示命中的那段原文,回车跳过去、选中它并居中。
113
+ - **画布体检与整理画布**:体检一次算全五类问题(环、残线、空配置、未就绪配置、孤立产物),按「阻断项在前」排好,每一条都能点过去;整理画布(`⌥⇧F`)把有向图排成从左到右的列,遇到环直接拒绝,没接线的卡片停在流程下方的停放带里,连按两次结果不变。
114
+ - **多选对齐**:选中两张以上时底栏上方出现对齐条(左/中/右、上/中/下、水平/垂直等距),只动选中、分组当刚体、结果取整并跑到不动点;不够两张、三张时按钮压暗并写出原因。
115
+ - **撤销说得出「这一步是什么」,历史面板能一次退几格**:撤销按钮的提示由 `history-model` 把两份快照折成一句话;按住 Shift / Option 点撤销或右键撤销,列出每一步并可直接跳回,跳回是一次文档替换,重做栈仍可逐步走回来。
116
+ - **套图(提示词组)**:一张配置卡上挂一组带标题的提示词(正面 / 侧面 / 背面…),一次提交各出一条,每条是独立任务、落成自己的占位卡与标题。它和「生成数量」是两件事:数量是同一条出 N 张,套图是 N 条各出一张。
117
+ - **首次打开画布**:空态只给内存草稿(状态条如实写「未保存」),不放一份用户没建过的画布;六张快捷卡里有一张「载入示例」,一次落一条提示词 → 配置卡的链,按生成就能出图。
118
+ - **连线说清用途**:连线可标首帧 / 尾帧 / 素材,视频插帧不再按数组顺序猜。标记只在画布上生效,老画布保持原样。
119
+ - **生成前自动连边**:图拖到配置节点旁边却没拉线时,提交生成那一刻会把近处的图补成连线(边缘距离在 1.5 个节点短边内,最多 4 张),补出来的线看得见、删得掉、一步就能撤销。
120
+ - **Agent 改画布先出提案**:对话里的 Agent 想增删节点、连线时,改动先出现在画布右上的提案条上,写明「接受之前画布不会有任何变化」;接受是增量的,你自己拖过的坐标、改过的标题都留着。
107
121
  - **分镜**:一个节点就是一列镜头,每镜一条提示词与一个时长,顺序即片序。可以「每镜独立」一次提交全部待生成的镜头,也可以「接上一镜尾帧」一次跑一镜——用上一镜的最后一帧当这一镜的第一帧。每一镜的成品都是普通视频节点,预览、下载、收藏、重试和拼接都走原来那条链路;分镜自己有「拼接全部镜头」,交给同一套本机 ffmpeg 和同一张顺序确认卡。
108
122
  - **时间线**:画布底部的胶片按钮把选中的成片按阅读顺序排成一条,可以重排、逐段设入点/出点、给每条接缝选硬切 / 叠化 / 淡入淡出并调时长,也可以整体关掉声音。面板上显示的总时长与最终文件一致。
109
123
  - **身份锚定**:任意有图的图片节点右键「钉为身份参考」,选角色 / 物品 / 风格并起名。之后每一次图像与视频生成都会自动带上这些参考,提示词里补一句说明谁是第几张;连线仍然优先,二者去重合并。定义存在节点上,重拍那张图就能改脸。
@@ -386,7 +400,7 @@ dsh plugin --profile web add ./q253595422-dsh-imagegen-video-X.Y.Z.tgz
386
400
  <img src="docs/images/wechat-group-qr.png" alt="微信群「龙虾吹水🦞群」的加群二维码" width="360" />
387
401
  </div>
388
402
 
389
- > 二维码 7 天内有效(2026 年 11 月 13 日前)。过期或人数已满时,请改到
403
+ > 二维码 7 天内有效(2026 年 11 月 21 日前)。过期或人数已满时,请改到
390
404
  > [Issues](https://github.com/q253595422/dsh-imagegen-video/issues) 提问题,
391
405
  > 并提醒维护者换一张新码。安全敏感的问题不要发在群里,也不要贴 API 密钥。
392
406
 
@@ -0,0 +1,189 @@
1
+ # v1.31.0 — 画布四件新事:Agent 改画布前先提案、连线说清用途、节点成组、原生姿势人偶
2
+
3
+ > **版本说明**:本版把 `v1.30.4` 之后累积的 40 个提交一次发出,没有中间版本。四块内容彼此独立,另有两条社区 issue(#47 / #48)的修复和一个侧栏入口修复。
4
+
5
+ 本版四块:
6
+
7
+ 1. **Agent 写画布先出提案**,用户点头才落盘——这是本版最大的一块,含 20 余处配套修复。
8
+ 2. **连线有了语义角色**(首帧 / 尾帧 / 素材),生成前还会自动补上「就在旁边、却没连过来」的图。
9
+ 3. **节点可以成组**,框选之后一起搬。
10
+ 4. **原生姿势节点**:自己算骨骼、自己画参考图,不依赖任何 3D 引擎。
11
+
12
+ ## 一、Agent 改画布之前,先问用户
13
+
14
+ ### 之前是什么样
15
+
16
+ 画布的八个 Agent 工具一调用就写文件。乐观锁挡得住「两个写入者同时改」,挡不住「用户根本不在场」——模型可以在用户睡觉时把整张画布重排一遍,用户第二天打开看到的既成事实,没有任何一步可以拒绝。
17
+
18
+ ### 现在
19
+
20
+ 写操作产出一个**提案**,存在 `canvas/proposals/` 下,与 `pages/` 完全分开。画布右上浮出提案条,常驻一句「接受之前画布不会变化」。用户点「接受」才真正落盘,点「丢弃」就当没发生过。
21
+
22
+ 三条设计上的硬约束,每一条背后都有一个具体的代价:
23
+
24
+ - **绝不碰 `pages/`。** 提案是旁路文件。哪怕这一层坏掉、写满磁盘,用户的画布一字未动。这是它敢接管全部 Agent 写操作的前提。
25
+ - **提案按顺序叠加。** `connect_canvas_nodes` 要能连上 `add_canvas_node` 刚提议的节点,所以第 N 条提案是在「真实文档 + 前 N−1 条提案」上算出来的。否则 Agent 一连串操作里除了第一条全部失败。
26
+ - **接受一条不作废后面几条。** 每条提案都记 `baseRevision`,但接受时**不拿它当闸门**:Agent 一次任务连着提议三条时,三条的 baseRevision 是同一个数,拿它比对会让用户接受第一条之后的第二三条全被判过期——界面写着「还有 2 条在后面」却一条都点不动。
27
+
28
+ 接受是**增量**的:只增删提案点名的节点与连线,用户在这期间改的标题、拖过的坐标都留着。两个窗口同时写由 `save(next, revision)` 那把乐观锁挡下,报 `canvas-conflict` 让用户重试。
29
+
30
+ ### 这一块顺带修掉的 20 余处
31
+
32
+ 提案机制一落地,「哪些地方还没对齐」就全暴露出来了。逐条都做过反向注入验证(把那处改动还原,对应断言必须变红):
33
+
34
+ | 问题 | 后果 |
35
+ | --- | --- |
36
+ | 一条过期提议把整张画布对 Agent 锁死 | 这张画布上所有写工具永久失败,只有用户碰巧点一次「接受」才能恢复 |
37
+ | 过期的 `read_canvas` 直接抛错 | 模型连「画布现在长什么样」都看不到 |
38
+ | 过期提案卡在队首 | 用户连点三次「接受」都是同一条错误,后面的提案全被挡住 |
39
+ | 读不懂的提案永久卡队首 | 手工改过的一次坏文件,让整条队列点不动 |
40
+ | 接受「改节点」的提案回退用户刚拖的坐标 | 提议改标题,用户把节点拖到别处再接受,节点跳回提议时的位置 |
41
+ | 接受提案没进撤销栈 | 按 Cmd+Z 弹掉的是上一次手动编辑,那笔更早的工作再也回不来 |
42
+ | 接受前不写本地未同步的编辑 | 刚拖的坐标被静默抹掉,autosave 也不会补写 |
43
+ | 本地保存失败时照样接受 | 用户那笔编辑彻底消失 |
44
+ | 接受期间切了画布 | 眼前的画布被换成另一本的内容,旧 revision 还顺着下次 autosave 写到错的画布上 |
45
+ | 连发的提案随机重排 | 「先加节点、再连线」被翻成反的(探针实测八次里两次) |
46
+ | 提案摘要永远是中文 | 英文、俄文用户看到中文 |
47
+ | Agent 删节点后分组里留下悬空 id | 组里指向一个已不存在的节点 |
48
+ | `read_canvas` 读不到自己刚提议的改动 | 模型以为没加成功,再添加一遍,同一个标题落进两条提案 |
49
+ | `list_canvases` 与 `read_canvas` 的节点数打架 | 模型以为提议失败,再提一遍 |
50
+ | `update_canvas_node` 不收 `mode` / `width` / `height` | 「加的时候选错了」只能删了重建,而重建会换掉节点 id 和已经连好的线 |
51
+ | `config` 节点不告诉 Agent 自己产出什么 | Agent 造不出视频配置节点(而视频配置正是「连两张图做插帧」的那个) |
52
+ | `add_canvas_node` 收 `width` / `height` 但没写进参数表 | 模型只能靠猜,猜不到就用默认尺寸 |
53
+ | 省略坐标时节点全叠在原点 | 连着加三个,用户只看到最上面那一个 |
54
+ | Agent 改连线角色被当成「什么都没改」 | 模型以为自己设好了首帧,用户拿到的是首尾帧用错了图 |
55
+
56
+ 界面这边也有两处:下拉里能看到**别的画布**上有改动在等(选项写作「标题 · 有 N 条待确认」),并且这些标记每 5 秒自己刷新一次,不用切画布;提案条的浮层位置按画布**实测**顶栏高度算,窄面板下顶栏换成两行时它也跟著下移,不再压住顶栏。
57
+
58
+ ## 二、连线说清用途;生成前自动补边
59
+
60
+ ### 连线语义角色
61
+
62
+ 连线以前只有 `from` / `to` 两个字段。视频首尾帧只能按 `connections` 数组顺序取前两张图——删一条边再重连就把首尾帧对调,而画布上看不出任何区别。
63
+
64
+ 现在连线有四个角色:
65
+
66
+ | 角色 | 含义 | 外观 |
67
+ | --- | --- | --- |
68
+ | `input` | 普通输入(缺省) | 与以前**一像素不差** |
69
+ | `first` | 首帧 | 加粗,进门端画实心点 |
70
+ | `last` | 尾帧 | 同上 |
71
+ | `reference` | 素材 | 虚线,降透明度 |
72
+
73
+ 右键菜单可设、可清除。首尾帧改用 `framePair()`:显式 `first` / `last` 优先,没标注时**完整退回**今天的数组顺序取法,所以老画布的行为一点不变。
74
+
75
+ **1429 份真实画布零迁移**:`role` 是可选字段,缺省即 `input`;回写时 `role: 'input'` 要删字段而不是写 `'input'`——「没有字段」是这批老画布的唯一形态,让它继续是唯一形态。全量往返实测:连线 0 变化、节点 0 变化、没有凭空长出 `role`。
76
+
77
+ ### 生成前自动连边
78
+
79
+ 用户把一张图拖到配置节点旁边,看起来显然是「要用这张」,但画布语义只认连线,于是生成时那张图完全不参与。
80
+
81
+ 现在提交生成的那一刻,把**边缘间距在 1.5 个目标节点短边以内、且尚未连入**的图片自动补成连线,最多 4 张(与引擎侧参考图上限一致)。三条约束:
82
+
83
+ - **只在提交时补,不在拖拽时猜。** 拖到附近就自己长出一条线,用户不接受也没法拒绝;提交是明确的意图表达,补上的线看得见、删得掉、一步就能撤销。
84
+ - **只补近的,不做全画布匹配。** AutoLink 式的全画布匹配会让远处一张看不出是哪张的图莫名参与生成。
85
+ - **补边不夺角色。** 只有 keyframe 模式才给补出来的边标 `first` / `last`,其余模式补的是普通输入,与手拉的线完全一样。
86
+
87
+ 补边与占位节点在同一个操作里,一次进历史,撤销一次就回到生成前。composer 会预告「将自动关联 N 张」,与实际补边共用同一个纯函数。
88
+
89
+ ## 三、节点成组
90
+
91
+ 框选几个节点 → 右键「成组」,之后拖其中任何一个,整组一起动。解散、改名、删成员后自动收拾。
92
+
93
+ 协议只加一个可选字段 `CanvasDocument.groups?`,**不升 version**。1429 份真实画布全量往返:1429/1429 载入成功,除 `revision` / `updatedAt` 外 0 变化,**0 份凭空长出 `groups`**。
94
+
95
+ 三条模型约束(`group-model.ts`,唯一解析处):
96
+
97
+ 1. **一个节点最多属于一个组。** 允许重叠就得决定「拖这个节点时另一个组的框跟不跟」,这个问题没有对错只有例外。
98
+ 2. **组不存坐标。** 框每次由成员节点的包围盒算出来。存一份坐标就多一份要和节点同步的状态,而移动节点的路径有拖拽、吸附、撤销、Agent 写入四条,漏一处框就飘走。
99
+ 3. **空组自动消失。** 成员被删光的组既没框可画也没东西可拖,留着只会在右键菜单里变成点不动的条目。
100
+
101
+ 两个值得记的取舍:
102
+
103
+ - 「空数组」与「没有这个字段」都落成**删字段**。否则 `pruneGroups(groupsOf(doc))` 在文档本来没有 `groups` 时返回 `[]`,第一次删节点就让全部老画布多出一个字段。与 `withRole(x, 'input')` 同一策略。
104
+ - 框体 `pointer-events: none`,只有标题条可点。框画在节点之上,吃指针会吞掉框内节点的拖拽、画布平移与框选——而这正是成组后最常用的三个动作。
105
+
106
+ 过程中修掉三个真问题:清空组名时默认名算成自己(「组 1」→「组 2」,每次清空往后跳一号);重命名用闭包读 state,导致 Esc 取消后 blur 仍提交、Enter 提交后 blur 又提交一次(撤销要按两次);`CanvasWorkspace` 里手抄了一份 `ContextMenuState` union,与真类型是两份,加第四种菜单目标时悄悄不认——改为单一来源。
107
+
108
+ ## 四、原生姿势人偶
109
+
110
+ 画布里的 3D 姿势参考不再是外挂工具,而是一个自己会算的节点。
111
+
112
+ - **17 个关节的层级 + 正向运动学 + 透视投影**,纯 Canvas 2D 手写。**不引 three.js**:这里要的东西只有一次投影 + 一次画家算法排序,而引一个 3D 引擎会给浏览器 bundle 增加约 670 KB,还要用户有可用的 WebGL——WebGL 恰恰是最容易在远程桌面、禁用硬件加速、老显卡上失效的那一环。一个姿势参考工具在那种环境里整块白掉,比画得糙得多。
113
+ - **求解完按最低点统一落地。** 固定下沉量在蹲姿上差 15 cm、跑步差 20 cm,那正是「人物浮在空中」的来源;落地只需要一个最小值。
114
+ - **取景按姿势自己的包围盒算,不按固定机位。** 蹲姿比站姿矮一大截,同一个距离要么把它缩成画面中央一小团,要么裁掉举起的手。
115
+ - **默认 3/4 视角。** 正面看坐姿看不出「坐」:大腿朝正前方被透视压成一个点。
116
+ - **11 个预设**(站立 / T 姿 / 挥手 / 双手举起 / 侧身 / 坐 / 蹲 / 背身 / 耸肩 / 迈步 / 跑)+ 逐关节三轴滑杆,按躯干、左右臂、左右腿五组分列。
117
+ - **导出 1024×1024 的 PNG**,不带辅助线,落成节点的普通图片资产。
118
+
119
+ 关键的架构选择:**它不是新节点类型**,而是 `type: 'image'` + `metadata.pose`。导出之后就是一张普通图片,下游的生成、标注、图库、导出全链路零改动——它们都不需要知道「姿势」这件事存在。
120
+
121
+ 校验器只拒绝「有但类型不对」,缺项按 0 度处理:过严的代价不是「拒收这次请求」,而是**这份文档再也存不下去**,用户手里的画布就此变成一个存一次报一次错的画布。
122
+
123
+ 真机量过三种节点宽度(320 / 260 / 220 px),滑杆最窄仍有 132 px。
124
+
125
+ ## 五、上游诊断:#48 与 #47
126
+
127
+ 这两条社区 issue 同源于「上游地址形态 + 响应不可诊断」。
128
+
129
+ ### #48 非 JSON 响应不再是一句「(HTTP 404)」
130
+
131
+ 此前生图链路上 9 处 `JSON.parse` 失败分支各自拼一句「上游接口返回了非 JSON 响应(HTTP 404)」,既不带请求地址,也没说返回的其实是一页 HTML。事后形态最难查:网关把 `/models` 挂在根上(「检测模型」绿灯),而 `/images/generations` 只在 `/v1` 下(每次生成必失败),用户拿不到任何自查线索。
132
+
133
+ 现在报错形如:
134
+
135
+ ```
136
+ 上游接口返回了非 JSON 响应(HTTP 404, text/html):https://host/images/generations
137
+ —— 返回的是网页而不是接口响应,通常说明渠道的 API 地址少了路径(例如末尾缺 /v1)或填成了站点首页
138
+ ```
139
+
140
+ 空响应体、二进制响应体、纯文本各有对应的一句;纯文本给截断摘要,而不是把整页 markup 贴进来。**错误码一律不变**(`upstream-invalid` / `video-submit-failed` / `video-upload-failed`),这次改的是那句话,不是失败分类,面板与诊断按码分组的行为不动。
141
+
142
+ 同一句判定收进 `src/upstream-diagnosis.ts`(`bodyShapeOf` / `diagnoseNonJsonBody` / `requestAddress`)。视频引擎 1.30.x 早已单独修过同一件事并留了内联正则——同一件事第二份实现,正是这次三条链路各说各话的原因,现在视频引擎也改用共享判定。
143
+
144
+ **刻意不做 `/v1` 自动回退**(issue 建议的第 3 条):那会静默改写用户填的地址语义,且没有真网关可验。把地址与原因说清楚,比替用户猜地址更诚实。
145
+
146
+ ### #47 Magpie 网关能发现图像模型了
147
+
148
+ Magpie 的 `/v1/models` 只返回聊天模型,图像条目在 `?kind=image` 后面(老版本认 `X-Magpie-Drawers: 1` 头)。旧实现「第一个返回记录的候选就赢」,普通列表必然先命中,于是「检测模型」绿灯、图像模型恒为 0。
149
+
150
+ 现在图像发现自己走一遍带 `kind=image` 的候选并带头,且兼容两种私有形状(`kind: "image"`、嵌套 `modalities.output: ["image"]`)。
151
+
152
+ **回退有两条,不止一条**:`?kind=image` 报错或 404 要退回普通候选;**作用域列表返回 200 但里面认不出图像模型**(网关静默忽略未知参数)时也要回退再合并。少了后一条,结果就是「检测成功但一个模型都没有」。聊天模型列表不受影响:不请求 `kind=image`、不带 Magpie 头。
153
+
154
+ ## 六、DS Bot 团队视图里的生图入口
155
+
156
+ DS Bot 0.3.6 的团队视图把宿主的整条品牌行和新会话行都设成 `display: none !important`,并用 `shadow("sidebar.workspaces")` 接管工作区插槽。于是 `newSessionButton()` 与品牌锚点全部落空,`sidebarRoot()` 四条分支同时失败、返回 undefined,切换器根本没挂载——切到 bot 视图后「生图」就没了入口。
157
+
158
+ 修法是新增一条判据 `ownsColumnChrome()`:**自身持有品牌/页脚锚点、可见、且是纵向堆叠**的框就是侧栏列。判据必须看锚点**存在性**而非可见性,否则被隐藏的品牌行会把真列误判成普通包裹层。另外 `placeTabs()` 的 fallback 落位从「列首」改为「区域块之前」——列首在 macOS 是红绿灯拖拽条,压上去会破坏窗口拖拽。
159
+
160
+ 真实 Chrome 复核过:修复前 `rootFound=false`、`tabsMounted=false`;修复后 `rootIsColumn=true`、`tabsParentIsColumn=true`、264×36 落在区域块上方。
161
+
162
+ ## 边界如实说明
163
+
164
+ - **提案机制不改变画布的存储格式**:提案是旁路文件,用户不接受就永远不落盘。代价是 `canvas/proposals/` 会随 Agent 使用增长,删除画布时会一并清掉它的提案。
165
+ - **自动连边只补 4 张**,与引擎侧参考图上限一致;多出来的仍然要用户自己拉线。
166
+ - **连线角色只在画布上生效**:只读 `from` / `to` 的纯函数(workflow 分层、技能输入解析)不受影响。角色只决定「谁当首帧、谁当尾帧、谁只是素材」,不改变图的结构。
167
+ - **姿势人偶是参考图,不是 3D 模型**:它是 2D 渲染出来的一张静态 PNG,没有骨骼绑定、没有动画、不能旋转到任意角度之后继续精确对齐。
168
+ - **#47 没有对真实 Magpie 实例发起过调用**,全部基于 issue 里用户实测的接口行为与桩 fetch;`?kind=all` 未实现(issue 标为「必要时」)。
169
+ - **DS Bot 团队视图的验证面**:复刻真实结构的 fixture + 真实 Chrome 复核,没有在 DS Bot 0.3.6 里逐态走查全部折叠状态。
170
+
171
+ ## 测试
172
+
173
+ 新增 11 个离线套件,全部接入 `pnpm test`:
174
+
175
+ | 套件 | 覆盖 |
176
+ | --- | --- |
177
+ | `smoke-canvas-connection-role.mjs` | 老画布兼容的最后一道闸:没设过角色的画布一个字都不许变 |
178
+ | `smoke-canvas-auto-link.mjs` | 阈值、上限、去重、角色分配逐条钉住 |
179
+ | `smoke-canvas-group.mjs` | 一个节点只属一个组、框由成员算出、空组自动消失 |
180
+ | `smoke-canvas-agent.mjs` | Agent 八个工具与提案的叠加语义 |
181
+ | `smoke-canvas-proposal-routes.mjs` | 接受 / 丢弃路由,与界面走同一段代码 |
182
+ | `smoke-canvas-proposal-summary.mjs` | 摘要按当前语言渲染 |
183
+ | `smoke-pose.mjs` | 存储往返、合法降级、畸形拒收、落地、左右不换、转身换边、取景不裁 |
184
+ | `smoke-magpie-discovery.mjs` | 两条回退路径各自独立 |
185
+ | `smoke-upstream-diagnosis.mjs` | 驱动真实生成路径,断言地址与成因、且 markup 不进来 |
186
+ | `verify-canvas-proposal-bar.mjs` | 真机量顶栏高度,提案条不压住换行后的顶栏 |
187
+ | `verify-pose-panel.mjs` | 真 Chrome 里量三种节点宽度下滑杆的最小宽度 |
188
+
189
+ 反向用例新增 `magpie` / `diagnosis` 两组,实测打红:magpie 4/4、diagnosis 3/3。
@@ -0,0 +1,64 @@
1
+ # v1.32.0 — 姿势人偶升级成导演台:一个场景、多个角色、多台机位
2
+
3
+ > **版本说明**:本版把 `v1.31.0` 里的「原生姿势节点」升成「导演台」。节点类型没变(仍是 `type: 'image'` + metadata 活数据 + 导出 PNG),老画布零迁移。
4
+
5
+ ## 之前是什么样
6
+
7
+ 一个姿势节点就是**一个人**:17 个关节、11 个预设、一张 1024 PNG。想画两个人对话,只能放两个独立节点——它们各自有自己的相机、自己的地面、自己的光照,拼在一起像是两张贴图并排,而不是一个场面。
8
+
9
+ ## 现在
10
+
11
+ 一块卡片瘦成「预览 + 机位名 + 打开导演台 + 预设条 + 生成参考图」,摆位与摆姿搬进全屏面板:
12
+
13
+ - **左栏**:场景列表(机位与角色一起列,可搜索、可增删)。
14
+ - **中央视口**:导演视角 / 机位视角切换,拖动环绕,滚轮缩放,X/Y/Z 罗盘,机位视锥线框。
15
+ - **右栏**:场景缩放/平移/旋转、天空色、全景背景、角色标签、当前角色或机位的参数。
16
+ - **底部**:机位截图、一句话场景描述。
17
+
18
+ ### 三个角色、三种姿势,一张画面
19
+
20
+ 多角色不是把所有人的球体并进同一个距离场——距离场是**屏幕空间**的,合并之后两个人接壤处的轮廓会被 smooth-min 融成一块,后排的人像贴在前面那人身上的一个鼓包,前后关系彻底丢失。每个角色各自成一张遮罩、按中心深度排序、依次贴上去,遮挡才成立。
21
+
22
+ ### 加了人就立刻重新取景
23
+
24
+ 新角色排在已有角色右边 1.2 m。不重新取景的话它会站到画面外,用户看到的是一张没变化的图,只会以为按钮没生效,然后一直点,最后堆出五个看不见的人。
25
+
26
+ 这条也牵出一个更深的问题:环绕相机原先只有 `targetY`,**水平注视点被硬编码在原点**。三个人并排时只把相机拉远是不够的——画面中心仍然盯着原点,第三人被裁在画外。现在 `PoseCamera` 带可选的 `targetX` / `targetZ`(缺省即 0,姿势面板的行为不变),取景会真的把画面中心挪到人群中间。
27
+
28
+ ### 老文档零迁移
29
+
30
+ - 只有 `metadata.pose` 的老节点:按单角色舞台读出来,不写盘、不改字节。
31
+ - 写盘时 `stage` 与 `pose` 一起写,`pose` 镜像 `actors[0].rig`——一份带三个角色的文档在旧版插件里仍是一张能用的姿势人偶,而不是一张读不懂的图片。
32
+ - 读盘以 `stage` 为准:`pose` 没有能力表达其余两个角色。
33
+
34
+ ### 成品仍是普通图片
35
+
36
+ 机位截图导出一张 1280×1280 PNG,落成节点的 `asset`。下游的生成、标注、图库、导出都不必知道「导演台」存在。
37
+
38
+ ## 底栏:从 18 个图标到三档层级
39
+
40
+ 原来的底栏是一排 17 个 40px 方块,外加 5 条 1px 竖线。每个都是一个同权重的图标,只有悬停才显示名字——用户要找「新建」,得把整排读完。竖线还让每一格看起来像表格里的一个单元格。
41
+
42
+ 现在只有三档:
43
+
44
+ 1. **一个实底 `+`**(左)。文本、画板、姿势、分镜、文件、配置六种节点收进它的菜单。`+` 是「新建」的通用形状,不必再解释。
45
+ 2. **一排低调的图标**(中)。工具、图片、模板库、技能库、时间线、背景、快捷键、撤销重做、删除。分组靠留白——1px 线画出来的是表格,不是分组。
46
+ 3. **一个带文字的主动作**(右)。「运行工作流」说自己的名字,右侧箭头并进同一块药丸、只开选项菜单。在画布上它是最常用的一步,一排纯图标只能靠逐个悬停学会。
47
+
48
+ 两处与弹簧引擎的边界是显式的:实底 `+` 仍是 40px 方块(照常被放大),带文字的主动作用 `data-dock-static` 退出引擎——引擎写的是内联 `width`,那会把文字药丸压回 40px 并裁掉标签。
49
+
50
+ ## 这一版没做
51
+
52
+ - **多机位切换成片**:机位能加、能切、能各自取景,但还不能一次导出「每个机位一张」。
53
+ - **AI 搭场景**:底部那行场景描述存在节点上,还没有接到生成链——静默丢掉用户敲的字比留一个不触发的字段更糟,所以它先被完整保存。
54
+ - **全景球是真球面**:现在按水平旋转贴一条环绕带。完整球面反投影要逐像素求逆矩阵,代价远高于它带来的收益。
55
+ - **视口内直接拖角色站位**:站位在右栏用 X/Z 数字框改。
56
+
57
+ ## 验证
58
+
59
+ - `scripts/smoke-pose-stage.mjs`(20 条):老文档兼容、双写镜像、加角色/机位不重叠、畸形缩放不塌成一点、取景跟人群中心、**每个角色的每个关节都投影在画面内**、提示词往返、站位参与变换。
60
+ - `scripts/verify-pose-panel.mjs`:真浏览器量 320×360 / 240×360 / 220×300 三档,钉住「打开导演台」按钮不被挤掉、机位名不与按钮重叠、矮卡片里预览收缩而不是把导出按钮顶出去、最后一枚预设可滚达。
61
+ - `pnpm test` 全绿(含 native-UI 契约与 z-index 契约)。
62
+ - `scripts/verify-canvas-layout.mjs`:五档面板宽度量底栏与缩放条/小地图的重叠与越界,并**数行数**——720px 及以上必须单行。这条是拿真机发现的:分组间隔取 10px 时,900px 面板下「删除」单独掉到第二行,看着像少了一个按钮,而重叠与越界两条都看不见它(那枚磁贴仍在画布内、不碰任何东西)。
63
+
64
+ 其中两条检查是从真机走查里回来的:遮罩贴回时漏了 `fieldCell` 倍放大(人偶体块只有骨架的 1/2.4),以及上面那条水平注视点。