疑难排查¶

症状、成因，以及要检查什么。

工具打不开¶

运行脚本后什么都没发生。

Harmony 通过 PATH 上的系统 Python 3.9 启动用户脚本，而 3.10 或更新版本会被悄悄忽略 —— 没报错，没窗口，什么都没有。装上 Python 3.9 再试。

脚本不在 Scripts 菜单里。

OctoSceneAssembler.js 必须散放在 <version>-scripts/ 里，不能放在子文件夹里，而 Python 包必须在一个名字正好是 octoSceneAssembler 的文件夹里。见安装。

标签没起作用¶

head-Peg 给了我一个叫 head-Peg 的 drawing。

标签必须是分隔符之间的完整一段。Peg 不是标签；P 才是。写 head-P 或 head=P。

sky-0007 没被读成深度。

单纯的数字被故意设计成不是标签 —— 序列文件里全是数字，而一个叫 0007 的帧绝不能变成一条深度指令。写 Z0.1、0.5F 或 10B。

我名字里有一部分不见了。

解析器从右往左读标签，遇到第一段不是标签的就停下。如果你名字里某个真实的词碰巧是个合法标签（…-P），改用等号形式：two-part-name=P。

完整语法：标签。

一个文件夹没被分流¶

它作为普通文件夹进来了，没去它的磁铁。

要么没有磁铁匹配这个名字，要么这个磁铁是停用的。OSA 会在导入时说明：

'PROPS' magnet is off: 'PROPS' came in as a plain folder, nothing was routed

检查 Magnets 区块，并记住匹配不区分大小写，会尝试精确、前缀和后缀 —— 最长的匹配胜出。见磁铁。

Assemble 按钮是灰的¶

反馈栏上有一条红色消息。红色是唯一会禁用按钮的颜色，而那条栏会点名 blocker。解决它，按钮就回来了。

帧类动词被拒绝¶

Enable 'Split/Merge Frames' checkbox to merge/suck frames

这个保护开关默认关闭，在 Browser 的 Settings 区块里。结构编辑重排的是一份计划；帧编辑重排的是时间。见 拆分与合并。

Merge 或 Split 变灰了¶

把鼠标停上去 —— 提示会说明为什么。Merge 至少需要两个节点；Split 需要有东西可拆。一个不给理由就变灰的条目是 UI bug，不是规则。

素材没到位¶

读报告。每一次拒绝都有一个 kind：

Kind	检查
`import-failed`	源文件是否还在、是否可读
`format-mismatch`	扩展名在内容上撒了谎 —— 一个被改过名的文件
`element-swap`	一个 Original Bitmap 的 drawing 仍然是 TVG
`utransform`	转换被拒绝了；常见于不受支持的来源
`no-bridge`	Harmony 在，但脚本桥从没打开过 —— 重启 Harmony

完整列表：Assemble。

一条矢量轨在 Original Bitmap 里消失了¶

它没消失 —— 它没被写出去，而且它还在你的树里。Original Bitmap 没有 art layer，所以矢量落不到那儿。要么把这个 drawing 切到 Art Layers，要么把那条轨移到一个是 Art Layers 的 drawing 上。见 Original Bitmap。

"Could not auto-save the session to disk"¶

一条黄色的临时消息。树还在内存里，Assemble 也照样能用 —— 但崩溃的安全网掉了。

原因在日志里，而且会点名成因：

%APPDATA%/Toon Boom Animation/Toon Boom Harmony Premium/octo_scene_assembler/osa.log

找 Autosave: could not write the file:。常见成因是磁盘满了、文件夹被锁，或者杀毒软件占着 sessions 目录。

会话没回来¶

没有出现那条栏。 会话是按场景存的 —— 用另一个名字保存的场景就是另一个会话。另外：一次成功的 Restore 会删掉它恢复的那个会话，而 Dismiss 是故意删掉它。

那条栏说会话读不了。 文件和它那一份备份都解析失败了。OSA 会告诉你，而不是悄无声息地从空白开始，因为什么都不被告知，正是人们断定自动保存从来没起过作用的原因。

见 会话与崩溃恢复。

Harmony 在 Assemble 途中崩溃了¶

Assemble 不是事务 —— Harmony 把整个构建攒成一次 undo，所以崩溃或取消会留下已经创建好的节点。

恢复办法：用 Harmony 自己的 undo，然后修好树再装配一次。你的 staging 树仍然描述着所有没落地的东西，因为 OSA 只压平落地了的东西。

Node View 看起来是堆着的，不是排布好的¶

节点叠在一起说明布局那一趟没跑 —— 到报告里找 phase-error。Wide Bus 会安置每一个节点，所以堆成一坨是失败，不是风格。

报 bug¶

? → About 里有报告需要的三样东西：版本、授权状态和 Machine ID。

附上 osa.log。技术支持靠它读懂你的 Harmony 干了什么，而不需要你的场景。