企业官网建设流程全解析

CLI-Anything Live2D：用 42+ 条命令在命令行完成 Live2D Cubism 模型全生命周期管理

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

本文以仓库中 SKILL.md 的能力清单为核心，结合 LIVE2D.md 与 live2d_cli.py 的源码实现，系统介绍如何在不依赖 Live2D Cubism Editor 的前提下，对.model3.json模型进行检视、校验、编辑、Lint、Diff、批处理与部署。读完本文，你将掌握这套 CLI 全部命令的分组、参数语义、自动备份机制与底层实现，可直接把它接入自己的模型资产管理流水线。

一、背景：为什么需要命令行管理 Live2D 模型

Live2D Cubism 模型本质上由一份model3.json清单文件与若干配套资源（.moc3、贴图、.motion3.json、.exp3.json、物理与姿态配置等）组成。日常工作中，角色升级、批量换装、Motion 时间参数微调、交付前巡检等场景若全部依赖图形化编辑器，会非常低效，也难以自动化。

CLI-Anything 仓库在 live2d/agent-harness 下提供了一个完整的命令行 harness，核心入口为cli-anything-live2d。其命令行入口定义于 live2d_cli.py，各子命令的解析、计算与编辑逻辑则按职责拆分到 core/ 目录下的多个解析器与处理器模块中。

该工具覆盖检视（Inspect）、校验（Validate）、编辑（Edit）、Lint、批处理（Batch）、Diff、HTML 预览、自动备份与回滚、文件打包与部署等多个维度，全部通过命令行完成，无需 Live2D Editor 或运行时环境参与。

二、安装与运行环境

2.1 依赖与版本

依据 setup.py，该包的技术要求为：

• Python ≥ 3.10；
• click>=8.1（CLI 框架）；
• 开发/测试可选依赖：pytest>=7、pytest-cov>=4。

包版本为0.3.0，在 CHANGELOG.md 中记录了 0.3.0（新增编辑、资源管理、生成、分析与工作流命令）与 0.2.0（首批只读命令）两个里程碑。

2.2 安装方式

在live2d/agent-harness目录下以可编辑模式安装：

pip install -e .

安装后由 setup.py 的 entry point 注册全局命令：

cli-anything-live2d --version # cli-anything-live2d, version 0.3.0

--version与全局--json选项在 live2d_cli.py 的 click 主命令组上定义：任意子命令都可追加--json以获得结构化输出（便于被脚本或 Agent 消费），例如cli-anything-live2d inspect model.model3.json --json。

2.3 面向的 Cubism 文件格式

三、命令全景：六大分组

SKILL.md 将命令划分为 Read（18）、Edit（10）、Generation（3）、Analysis（4）、Workflow（7）、Other（3）六大类。官方文档将整体命令面标注为42 个（SKILL.md 与 LIVE2D.md 均如此表述；若按两张命令表逐行统计则共 45 条命令，使用时应以实际 CLI 为准）。

3.1 Read 组（18 条）：检视与只读分析

3.2 Edit 组（10 条，全部自动备份）

3.3 Generation 组（3 条）

3.4 Analysis 组（4 条）

3.5 Workflow 组（7 条）

3.6 Other 组（3 条）

所有 Read 命令均支持--json输出；所有 Edit 命令在写盘前会自动备份（机制详见第 5 节）。

四、深度实操：按使用场景逐组讲解

4.1 检视与校验：从inspect到validate

模型总览。inspect走 load_model() 解析model3.json，输出 Version、Moc3 引用、贴图数、动作数（含分组数）、表情数，以及 Physics / Pose / UserData 是否挂载。实现见 live2d_cli.py#L131-L165。

完整性校验。validate除检查所有被引用文件是否存在外，还提供两个关键开关：

cli-anything-live2d validate model.model3.json cli-anything-live2d validate model.model3.json --verbose cli-anything-live2d validate model.model3.json --strict --min-moc3-size 1024

• --strict：拒绝占位符或不完整的生产导出；
• --min-moc3-size（默认 1024）：严格模式下.moc3的最小字节数门槛。

源码位于 live2d_cli.py#L170-L203，底层由 core/validator.py 的validate_model/validate_all实现。校验失败时进程以非零退出码（sys.exit(1)）结束，便于 CI 集成；仓库在 tests/test_validator.py 中对该能力有独立测试。

动作与表情检视。motions -g可按分组过滤并展示每个动作的fade时间（live2d_cli.py#L208-L232）；motion-info解析.motion3.json输出时长、FPS、Loop、曲线数、片段数与关键帧点总数；expr-info则展示.exp3.json的版本、整体 FadeIn/FadeOut 与参数表。param-list更进一步，跨所有动作与表情汇总唯一参数 ID 及其被引用位置（live2d_cli.py#L1792-L1855），这对排查“某个参数到底被谁驱动”非常有用。

贴图、物理与 moc3。textures借助 core/texture_info.py 读取贴图真实尺寸、文件大小与格式，缺失文件会标❌ MISSING（live2d_cli.py#L320-L345）。physics输出每个物理设置的输入/输出参数、顶点数及归一化区间（live2d_cli.py#L348-L380）；moc3验证二进制文件头并报告版本与大小（core/moc3_parser.py）。

依赖、比较与导出。deps由 core/dependency.py 构建“动作/表情 → 参数”依赖图，并按引用次数降序排列。compare（core/comparer.py）给出增/删/改的粗粒度结论；diff（core/differ.py）则在 texture/motion/expression/field/param 五个维度输出每条差异，用于精确评审。

export支持--format json|csv与--out，CSV 输出形如type,group,name,file（motion 行带分组名）。manifest则对模型本体、moc3、贴图、动作、表情及物理/姿态/用户数据逐文件计算 SHA256 与大小（live2d_cli.py#L1557-L1635），适合做交付物指纹登记。

4.2 目录级扫描与统计

cli-anything-live2d scan ./models/ # 递归发现所有 .model3.json cli-anything-live2d scan ./models/ --validate # 顺带逐个校验 cli-anything-live2d stats ./project/ # 项目级统计

scan由 core/scanner.py 支撑，-v/--validate会在列出每个模型后立即校验引用完整性（live2d_cli.py#L627-L664）。stats汇总目录内模型数、动作数、表情数、贴图数、动作分组集合及磁盘占用（live2d_cli.py#L1647-L1705），可快速估算一个模型项目库的体量。

4.3 编辑：十条自动备份的写操作

SKILL.md 强调“Edit commands auto-backup”——这正是该工具与直接改 JSON 的本质区别。每个编辑命令在写盘前都会调用auto_backup(p)（core/backup.py），把当前model3.json快照存入模型旁的备份目录，之后无论改错什么都能用undo回滚。

动作编辑。edit-motion通过-g（分组名）与-i（分组内 0 起索引）定位目标，支持--fade-in/--fade-out/--file三个修改维度，索引越界或分组不存在会直接抛错：

cli-anything-live2d edit-motion model.model3.json -g Idle -i 0 --fade-in 0.3 cli-anything-live2d edit-motion model.model3.json -g Idle -i 0 --fade-out 0.2 --file motions/idle_v2.motion3.json

对应实现见 live2d_cli.py#L701-L742。add-motion指定--group与--file（默认淡入淡出 0.5s），分组不存在会自动创建；rm-motion需-g与-i，并带 click 的确认提示（Are you sure?）。rename-group --old <name> --new <name>对分组重命名，重名分组会被拒绝。

表情与贴图。add-expr -n <name> -f <file>去重后追加表情；rm-expr -n <name>带确认提示；edit-texture -i <idx> --path <path>按下标替换贴图路径并显示old → new。

模型级引用。edit-model一次可替换多个模型级引用：

cli-anything-live2d edit-model model.model3.json --moc3 model_v2.moc3 --physics model.physics3.json

表达式参数微调。param-edit直接作用于.exp3.json：按-p/--param-id（如ParamEyeLOpen）与-v/--value修改参数值，还可选传--fade-in/--fade-out覆盖该参数的渐入渐出。若参数 ID 不存在则自动追加新参数条目（live2d_cli.py#L1104-L1148）。

全局引用改名。find-replace会在贴图、动作、表情（含表达式显示名）、以及 moc3/physics/pose/userdata 这些顶层字段中做文本级替换，--dry-run可先预览改动清单：

cli-anything-live2d find-replace model.model3.json -f "old_tex" -r "new_tex" --dry-run cli-anything-live2d find-replace model.model3.json -f "v1" -r "v2"

见 live2d_cli.py#L1334-L1401。

4.4 撤销与备份治理

• undo model.model3.json：恢复最近一次自动备份；--list列出全部备份（含大小），--backup <file>指定恢复某一版本。
• restore-file：--file指定要恢复的文件。需要说明的是，自动备份只保存.model3.json本体，恢复其他文件时工具会提示交给版本控制（git）处理（live2d_cli.py#L1460-L1498）。
• backup-clean --keep N（默认保留 10 份）：轮转清理过期备份，支持--dry-run。

4.5 批量编辑

batch把单条编辑命令推广到整个目录，是换装/统一命名规范等批处理场景的主力：

cli-anything-live2d batch ./models/ --set-fade-in 0.3 --dry-run cli-anything-live2d batch ./models/ --set-fade-out 0.2 --set-moc3 shared.moc3 cli-anything-live2d batch ./models/ --add-motion-group Tap --add-motion-file motions/tap.motion3.json

支持的操作包括--set-fade-in、--set-fade-out、--add-motion-group+--add-motion-file、--add-expr-name+--add-expr-file、--set-moc3。--dry-run只打印“would change”而不写盘；真正执行时每个模型都会先自动备份再保存（live2d_cli.py#L941-L1029）。

4.6 生成：模板与骨架文件

• init my-character：在当前目录（或-d指定目录）生成my-character/完整模板骨架并打印生成的文件列表，随后可直接基于model3.json编辑搭建（live2d_cli.py#L598-L624，core/template.py）；
• gen-motion tap --duration 2.0 --fps 30：生成骨架.motion3.json，默认时长 2.0s、FPS 30、Loop 开启（--loop默认 True），--out可指定输出路径（live2d_cli.py#L1708-L1738）；
• gen-expr happy --fade-in 0.5 --fade-out 0.5：生成骨架.exp3.json，工具会提示随后可用param-edit填充参数（live2d_cli.py#L1741-L1765）。

4.7 Lint、运行时兼容性与贴图图集分析

Lint。lint基于 core/linter.py 执行命名、贴图尺寸、结构等最佳实践检查，输出按 error/warning/info 三级着色并给出修复建议（fix_hint）。级别过滤由--level控制：

cli-anything-live2d lint model.model3.json # 默认仅显示 warning 及以上 cli-anything-live2d lint model.model3.json --level info

存在 error 时退出码非零，见 live2d_cli.py#L1032-L1067。

运行时兼容性。runtime-check --target可指定cubism-viewer、web-sdk、yoyo或all（默认 all）。各目标的检查要点（live2d_cli.py#L1958-L2043）包括：

• 通用：moc3 缺失/过小（<1024 字节）、贴图缺失或超 4096px、无动作；
• web-sdk：无 physics 文件（推荐）、淡入淡出过长（>1.0s）会提示“网页端可能显得迟钝”；
• cubism-viewer：无表情、缺少 Idle 动作分组（Viewer 惯例）；
• yoyo：缺少 Idle 分组为 error；Idle 动作未做到 ≤0.5s 快速淡入则告警。

贴图图集分析。atlas --merge会寻找 ≤512×512 的小贴图并给出合并建议；atlas --split --max-size 2048则标出超过尺寸上限的超大贴图，用于优化加载：

cli-anything-live2d atlas model.model3.json --merge cli-anything-live2d atlas model.model3.json --split --max-size 4096

孤儿文件检测。orphan对比“模型引用集合”与“目录真实文件集合”，报告未被任何引用引用到的文件（自动跳过备份目录与隐藏文件），帮你清理历史遗留资源（live2d_cli.py#L1404-L1457）。

4.8 部署与交付：snapshot / watch / flatten / pack / migrate / yoyo-check

HTML 预览。snapshot由 core/snapshot.py 生成深色主题的 HTML 预览页并内嵌贴图预览；--embed将贴图以 base64 内联，得到单文件自包含预览，方便直接发给他人审阅：

cli-anything-live2d snapshot model.model3.json cli-anything-live2d snapshot model.model3.json --embed --out preview.html

监听自动校验。watch以--interval（默认 2.0s）轮询目录，跟踪模型及贴图/动作/表情文件的时间戳变化，一旦变更立即对该模型的父级做自动校验并输出结果，Ctrl+C 退出（live2d_cli.py#L1171-L1225）。

展平部署目录。flatten --out-dir ./deploy/收集模型全部依赖（含动作内联的Sound音频字段）并复制到单一目录，同时自动改写model3.json内所有引用为纯文件名。若出现同名冲突会直接报错中止，避免覆盖（live2d_cli.py#L1858-L1955）：

cli-anything-live2d flatten model.model3.json --out-dir ./deploy/ --dry-run

打包与迁移。pack model.model3.json -o out.zip将模型与全部依赖打进 zip（可用--no-motions/--no-expressions裁剪内容，见 live2d_cli.py#L518-L552，底层 core/packager.py），并列出缺失文件。migrate --target-version 3负责格式版本升级，例如 v1→v2 补Motions结构、v2→v3 补Groups数组，支持--dry-run且写盘前自动备份（live2d_cli.py#L1273-L1331）。

Yoyo 桌面宠物就绪检查。yoyo-check面向 Yoyo 桌面宠物运行时的特殊约束：

cli-anything-live2d yoyo-check model.model3.json cli-anything-live2d yoyo-check model.model3.json --require-motion idle --require-motion tap

默认要求存在idle分组（大小写均可接受），错误或警告会分类输出（live2d_cli.py#L557-L595）；tests/test_yoyo_pipeline.py 覆盖了该检查以及 core/yoyo_pipeline.py 的导出管线。

五、实现机制：自动备份、JSON 输出与错误处理

从源码看，这套 CLI 的工程设计有三个可复用的点：

1. 统一的输出层。全局_json_output标志配合output()/_print_dict()/_print_list()（live2d_cli.py#L54-L89）让每条命令天然具备“人类可读文本 / 机器可解析 JSON”双形态，方便被脚本与 Agent 直接调用。
2. 自动备份先写盘。所有 Edit 命令均先auto_backup(p)再save_model(info)，由 core/backup.py 统一管理快照目录（目录内以.live2d-backups标识，orphan会跳过它）。配合undo即构成“修改—可逆”的安全闭环。
3. 统一错误处理。@handle_error装饰器（live2d_cli.py#L92-L111）将FileNotFoundError、ValueError、IndexError归一化为带错误码的退出行为，JSON 模式下以结构化{"error": ...}输出——这对 CI 与 Agent 编排非常友好。

测试方面，仓库除包内 tests/test_core.py 外，还在 live2d/agent-harness/tests 下提供test_new_features.py、test_validator.py、`test_yoyo_pipeline.py，覆盖校验、Yoyo 管线与 0.3.0 新增特性（CHANGELOG 记录 0.3.0 新增 40 个测试）。

六、与 SKILL.md 配合：Agent 原生工作流

SKILL.md 本身以机器可读的 front-matter（name: cli-anything-live2d、category: graphics）声明技能身份，正文即命令索引。对 Agent/LLM 而言，它的价值在于：给定一个 Live2D 模型目录，Agent 可以按「scan→validate→inspect/lint→ 按需edit-*→flatten/pack」的链路完成从审查到交付的全部动作，且全程可回滚、可 JSON 化对接。该技能文件同时被打包进 Python wheel（见 setup.py 的package_data），说明“CLI 能力 + 技能说明”是随发行版一起分发的一体化方案。

七、延伸阅读

• 技能命令清单（本文骨架来源）：live2d/agent-harness/cli_anything/live2d/skills/SKILL.md
• Harness 架构与文件格式参考：live2d/agent-harness/LIVE2D.md
• 版本演进记录：live2d/agent-harness/CHANGELOG.md
• CLI 入口与全部命令实现：live2d/agent-harness/cli_anything/live2d/live2d_cli.py
• 核心解析与处理模块：live2d/agent-harness/cli_anything/live2d/core
• 安装元数据：live2d/agent-harness/setup.py
• 测试用例：live2d/agent-harness/tests

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything