Live2D Param

给 Live2D Cubism Editor 5.4 版本 辅助建模的小程序

系统要求

项目	要求
操作系统	Windows 10 / 11（64 位）
.NET Framework	4.x（Win10/11 系统自带 4.8，不需要额外安装任何东西）

关于Cubism版本限制

Live2D Cubism最低版本限制为 Editor 5.4 alpha1 版本

安装与卸载

安装

1. 到 Releases 下载 Live2D-Param-v0.0.1-alpha.1-Setup.exe
2. 双击运行，点「安装」。
3. 完成。

卸载

• 「设置 → 应用 → 已安装的应用」里找到 Live2D Param 0.0.1 alpha.1，点卸载；
• 或双击安装目录里的 Uninstall.exe

卸载会保留 %APPDATA%\Live2D Param（里面存着 Editor 给的访问令牌和你的偏好设置），这样重装之后不用再去 Editor 里重新授权一遍。想彻底清除就手动删掉那个目录。

卸载就是清空安装目录：里面的文件、子文件夹、快捷方式、卸载信息全都删掉，只有你放在那里的 配色方案\ 和 脚本\ 留着。因为卸载会清空整个文件夹，所以重要的东西别扔进根目录及其其他文件夹里面，除非你不想要了。

命令行参数

（安装包的文件名里带版本号，比如 Live2D-Param-v0.0.1-alpha.1-Setup.exe，下面简写成 Setup.exe）

Setup.exe                                       图形界面安装
Setup.exe /S                                    静默安装
Setup.exe /S /NODESKTOP                         静默安装且不建桌面快捷方式
Setup.exe /DIR="D:\somewhere"                   指定安装目录
Setup.exe /?                                    显示帮助

Uninstall.exe                                   图形界面卸载
Uninstall.exe /S                                静默卸载

静默模式没有界面，过程会写进 %TEMP%\Live2DParam-Setup.log，退出码 0 表示成功。

使用方法

一、在 Editor 侧准备

1. 启动 Cubism Editor 5.4
2. 打开菜单 [文件] → [外部应用程序的集成设置]。
3. 把连接开关打开，端口保持一致，默认 22033 的即可。

二、链接

4. 在Live2D Param里，左下角的 Editor端口 输入与 Editor里的端口一致的端口号（默认22033），再点**「连接」**。 此时 Editor 的对话框里会出现链接许可，把 「权限」 和 「编辑」 勾上。

三、使用

5. 点 「读取参数组」 拉取列表。

6. 改颜色：

   • 点「改色」列的色块 ,点某个预设直接选中；点右下角的 「自定义…」 会再打开一个三角取色窗口（详见下方「取色窗口」）；
   • 想批量改 → 先在列表里多选若干行（Ctrl / Shift），再点 「设为颜色…」；不选任何行则作用于全部；
   • 想改名 → 直接双击 「名称更改」 列改。

   改过的行会变成浅黄色底，右侧「待应用」列显示改了什么。此时还没写入 Editor。

   改错了可以按 Ctrl+Z 逐步「返回上一步」，或按 Ctrl+Y「前进一步」； 工具条上也有对应的两个图标按钮。按 Ctrl+Shift+Z 可以放弃全部更改。

7. 点 「应用更改」 写入 Editor。

   这一步 Editor 会弹出编辑对话框并临时锁定，处理过程中请不要操作 Editor。 如果中途想放弃，在那个对话框里点「取消」，所有改动会被整体回滚 —— 你选的颜色会保留在列表里，可以直接重试。

8. 想看操作记录，点工具条上的 「记录」 打开独立窗口，里面可以下载为 txt（下载出来的文件会被设为只读）。

---

脚本

点工具条上的 「脚本」 打开脚本窗口：左边是脚本列表（每行右边一枚「官方 / 我的」小标签），右边是选中脚本的说明和规则明细（逐条列出「什么条件 → 什么颜色」，还带小色块；有渐变的会画一条渐变预览），选中一个点「运行」，它就按规则把颜色填进列表。

脚本是一份声明式的 JSON，描述「什么样的参数组上什么颜色」。它特意不是可执行代码，两个原因都很实在：

• 本工具只用了系统自带的 .NET 编译器，跑不了 JS / Python 这类脚本语言；

两个来源：都在同一个文件夹里

| 来源 | |---|---|---| | 默认自带 | 名字是默认的（按名字上色.json 等 3 个） | 随程序走（内嵌在 exe 里），每次启动按当前版本覆盖写出 | | 你自己的 | 名字不跟默认撞的 *.json | 丢进「脚本」文件夹就会被列出来。想改官方脚本？给它改个文件名（例如 层级渐变-我的.json），它立刻变成你自己的脚本，程序再也不会覆盖它 |

格式

{
  "version": 1,
  "name": "按名字上色",
  "description": "显示在窗口里的一句话说明",
  "rules": [
    { "name": "*眼*", "color": "blue" },
    { "id": "ParamGroup*", "depth": 0, "cycle": ["red", "green", "blue"] },
    { "minDepth": 1, "color": "#8AC1FF" },
    { "name": "*", "gradient": "ask" }
  ]
}

一条规则 = 匹配条件 + 上色方式：

字段	含义
name	匹配参数组名称，支持 *（任意多个字符）和 ?（一个字符）；不写 = 不限
id	匹配参数组 ID，写法同上
depth	只匹配正好在第几层的组（0 = 顶层）
minDepth	只匹配第几层及更深的组
color	上什么色：red / orange / yellow / green / blue / purple / gray / default，或者 "#RRGGBB" 自定义色
cycle	命中多个组时按顺序轮流用这几个颜色（数组，元素写法同 color）
gradient	命中多个组时按顺序在这些色标之间平滑渐变：写 ["#RRGGBB", …] 就是固定色标；写 "ask" 则运行的时候弹个小窗口让你现选一个颜色，色带是「白 → 本色 → 黑」，但只截取前半段（白 → 本色），不会往黑里走

• color / cycle / gradient 三选一；
• 规则从上往下匹配，第一条命中的说了算；一条都没命中的组保持原样；
• 脚本名字默认取文件名（不含扩展名），写了 name 就以 name 为准；
• 匹配不区分大小写，中文关键词直接写就行（*手* 能同时命中「手臂」和「手指」）。

运行脚本会发生什么（重要）

• 结果只是填进列表当「待应用」改动（和「载入方案」是同一条路子），不会直接写进 Editor —— 看过没问题再点「应用更改」；
• 作用于全部参数组（脚本是批量规则，和「载入方案」一个口径；不是「设为颜色…」那种按选中行的行为）；
• 整个脚本算一步撤回，按 Ctrl+Z 一次退掉；
• 脚本里写了 "gradient": "ask" 的，运行前会弹一个临时小窗口让你选颜色（选完窗口就关掉、不留着）：选一个颜色，按顺序从白铺到它，最后一组正好是所选的颜色；窗口里能看到渐变预览，取消就等于没跑；
• 脚本打不开（JSON 写错了）时列表里会标上红色并显示具体错误，不影响其它脚本；
• 跑完脚本窗口会自己关掉（工具条上「运行后关掉窗口」那个勾选框说了算，默认勾上；取消勾选就能连着跑好几个脚本）。这个勾选会记住，下次打开还是上次的样子。关掉后接着看列表里的待应用改动、确认后点「应用更改」即可；没能跑起来时（还没读参数组、一条都没命中、取消了选色）窗口不关，会弹一句说明。

---

工作原理

通信

Editor 是 WebSocket 服务端，本工具是客户端；默认端口 22033；消息是 JSON（UTF-8 文本）。

请求： {"Version":"1.1.0","Timestamp":…,"RequestId":"<uuid>","Type":"Request","Method":"…","Data":{…}}
响应： {"RequestId":"<同一个>","Type":"Response","Method":"…","Data":{…}}
错误： {"RequestId":"<同一个>","Type":"Error","Method":"…","Data":{"ErrorType":"…"}}
事件： {"Type":"Event","Method":"NotifyUndoCancel","Data":{…}}      ← Editor 主动推送

响应靠 RequestId 配对；事件靠 Method 分发。本工具会串行发送请求，遵守官方文档「等上一个命令的响应再发下一个」的规则。

回滚语义（重要）

• 用户在 Editor 对话框里点「取消」后，Editor 会用历史记录把模型恢复到编辑前状态，并且此后所有编辑 API 都返回错误；
• 只有 EditEnd(Cancel=false) 成功返回 true 才算真正提交。因此本工具直到最后一步成功才更新界面基线；
• 中途失败时会自动发一次 EditEnd(Cancel=true) 请求回滚，并且不碰你在列表里选的颜色 —— 它们继续保持「待应用」状态，方便你修正问题后直接重试；
• 万一回滚本身也失败了，日志会明确警告模型状态不确定、请用 Ctrl+Z 检查。

程序会持续监听 NotifyUndoCancel 事件，所以你中途取消时它会立刻知道。

---

从源码构建

特点：零构建依赖

构建只用 Windows 自带的 .NET Framework 编译器 csc.exe：

• 不需要 Visual Studio、不需要 .NET SDK、不需要 NuGet、不需要 npm；
• 产物是几十 KB 的原生单文件 exe，目标用户双击即跑，不需要装任何运行时（Win10/11 自带 .NET Framework 4.8）。

代价是只能用 C# 5 语法（系统自带的 csc 就是 C# 5）——不支持字符串插值、?.、nameof 等。代码里已经据此编写。

测试

针对模拟 Editor 的协议层联调

不需要真实 Editor，也不需要 Python：

cd test
npm install ws --cache "..\.npm-cache" --no-audit --no-fund   # 首次需要
.\run-client-tests.ps1

它会用 src\ 里的真实协议代码编译出一个控制台测试程序，然后对模拟 Editor 跑三个场景：

场景	验证内容
正常流程	连接 → 注册 → 令牌复用 → 权限查询 → 读取（含嵌套组递归解析）→ 改颜色改名 → 应用 → 读回确认 → 未开会话报错 → 目标不存在报错
用户中途取消	Editor 推送 NotifyUndoCancel 后，会话被正确标记失效，后续调用被拦下并给出说得清原因的错误
没有编辑权限	读取被干净地拒绝（而不是静默返回空列表），错误信息明确指出是权限问题

当前结果：三个场景共 59 项断言，全部通过。

cd test
npm start                 # 另开一个终端：起 mock（端口 22133）
npm run selftest          # mock 自身的协议自测（47 项断言）
npm run flagtest          # mock 的异常场景自测（31 项断言，自动起停实例）

# 单独调试某个场景
node mock-editor.js --port 22134 --cancel-after-ms 300
node mock-editor.js --port 22135 --deny-edit
node mock-editor.js --help

端口：测试统一用 22133–22135。22033 是 Cubism Editor 的默认端口，本机开着 Editor 时 mock 绑不上，测试探针会连到真实 Editor 上、报出一堆莫名其妙的失败。

说明：npm install ws 如果不指定 --cache，在受限环境下可能因为 npm 默认缓存在工作区之外而被拒绝。指定一个工作区内的缓存目录即可。模拟 Editor 只用于开发测试。

针对真实 Editor 的实机验证

# 只读：连接 + 读参数组结构，不改任何数据
.\tools\bin\clienttest.exe --port 22033 --mode live --reuse-token

# 写回：改名改色后**整体回滚**，并再次读取确认模型已恢复原样
.\tools\bin\clienttest.exe --port 22033 --mode write-probe --reuse-token

# 抓真实 Editor 的原始 JSON，核对字段名（文档不准时靠它）
.\tools\bin\clienttest.exe --port 22033 --mode dump --reuse-token

--reuse-token 复用 %APPDATA%\Live2D Param\token.txt，授权过一次之后就不用每次重新勾选。

write-probe 是自带回滚的：所有改动都在同一个编辑会话里完成，最后用 EditEnd(Cancel=true) 让 Editor 依据历史记录整体回滚，然后再读一次确认名称、颜色类型、自定义色三项都恢复成原值。既能确认写入路径正确，又不在模型上留下痕迹。实测（真实 Editor）：

[PASS] 改名真的生效了（读回 "qqqqsss_写入测试"）    ← 证明写入字段是 Name
[PASS] 预设色写入生效（读回 red）
[PASS] 自定义色写入生效（读回 #FF00AA）
[PASS] EditEnd(Cancel=true) 返回 true，表示已回滚到编辑前状态
[PASS] 回滚后名称 / 颜色类型 / 自定义色均已恢复

手动验证清单

连接、读取、写入、回滚都已自动化覆盖。仍建议人工确认的只剩「观感」层面的东西：

1. 打开 Editor 5.4 alpha1 + 一个模型，切到建模模式，打开集成开关；
2. 启动本工具 → 连接 → 在 Editor 对话框里勾选「权限」+「编辑」；
3. 读取参数组 → 确认列表里的组名和颜色与 Editor 参数面板里的一致；
4. 改一两个组的颜色 → 应用 → 回到 Editor 里确认颜色真的变了；
5. 重开一次工具 → 连接 → 确认不需要重新勾选权限（令牌复用生效）；
6. 改颜色后在 Editor 里按 Ctrl+Z → 确认撤销历史是干净的（读取操作没有污染历史记录）。

---

已知限制

1. 只支持 Cubism Editor 5.4 alpha1 及以上。
2. 只有 Windows 版。核心逻辑与界面没有强绑定，但界面用的是 WinForms。
3. 预设色的色块是按截图采样值画的。预设色的实际 RGB 由 Editor 内部决定，API 不返回、字节码里也没有；这里的值是拿 Editor 取色界面的截图逐像素采出来的，观感与 Editor 一致。写回时只发送预设的名字，最终颜色仍以 Editor 为准。只有 LabelColorType = "Custom" 时颜色才由 #RRGGBB 精确决定。
4. 应用期间 Editor 会被锁定，这是 Editor 侧的设计（弹出模态编辑对话框），不是本工具造成的。
5. 本版本不支持修改参数组的 ID（NewId）。API 是支持的，但界面没做，避免误操作破坏模型。
6. 读取时若模型特别大，GetParameterStructure 的响应可能较大，第一次读取会稍慢（已把 JSON 长度上限放开）。
7. 令牌以明文存在 %APPDATA%\Live2D Param\token.txt（与官方 Python 样例的做法一致）。它只能用于连本机的 Editor，但如果你在共享电脑上使用，请留意这一点。
8. 端口可能被别的程序占用。Editor 默认用 22033，如果本机已有别的服务占着这个端口，Editor 就无法监听，工具也就连不上。改端口即可 —— 两边都改（Editor 的集成设置对话框 + 本工具顶部的端口输入框）。

参考资料

• Live2D Cubism Editor 外部应用程序的集成（官方手册）
• Live2D Cubism Editor 外部集成 API（官方手册）
• 本文档对应版本：5.4 alpha1 编辑 API（中文）
• 官方样例 CubismExternalAppPluginSamples（分支 54alpha，04_EditSample）

最后声明

这个软件都是使用的dsh编写的，我自己都还不知道有什么bug等等。如果要用后果自负。 关于这个软件，是因为是自己做建模的时候因为一些小癖好，还有重复性的工作等等才写的这个软件，实际上还是自用的，但是如果你也想用的话自行下载。 同时也欢迎更多的人一起来完善这个软件，目前这个软件就只是支持一个小小的改文件夹颜色的功能，但其实脑子里面还有好多功能没写。 最重要的是我不会UI啊，怎么写都好丑的。