Spine Render

lyco-ai-toolkit

マルチモーダル AI リソースパイプライン：1 つのコマンドで Minecraft スキン、Bedrock モデル、BGM、立ち絵、歌詞を生成します。

Owner: lilyco-42（云枢智创数码信息科技服务工作室） 調査と意思決定の記録は _RESEARCH/ にあります。

できること

lyco-cli bundle --prompt 'a quiet librarian' --out out
# => out/
#      skin.png        64x64 Minecraft 皮肤（合法，可校验）
#      model.geo.json  Bedrock 几何（Blockbench 可导入）
#      bgm.wav         背景音乐
#      portrait.png    立绘 512x512
#      lyrics.txt      分段歌词
#      manifest.json   每个产物的 backend 与 placeholder 标记

すべてのサブコマンド

lyco-cli bundle    整包：skin + model + bgm + portrait + lyrics + manifest
lyco-cli skin      template | validate | info | quantize | generate
lyco-cli bsm       humanoid | validate | info | glb-info | from-glb
lyco-cli bgm       背景音乐
lyco-cli lyrics    分段歌词
lyco-cli portrait  单张立绘
lyco-cli mcp       在 stdin/stdout 上跑 MCP server，给 agent 用

agent（MCP）との連携

lyco-cli mcp は MCP サーバーで、改行区切りの JSON-RPC 2.0 を送受信します。12 個のツールを lilyco_agent / Claude Code / Cursor に公開します：skin_template、skin_validate、 skin_quantize、model_humanoid、model_validate、glb_info、model_from_glb、 lyrics_generate、lyrics_validate、bgm_generate、portrait_generate、bundle。

手動で試す場合：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize"}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | lyco-cli mcp

構成

lyco-ai-toolkit/
+-- crates/
|  +-- lyco-cli/        统一入口（clap）
|  +-- lyco-mc-skin/    F1  64x64 box-UV、调色板量化、皮肤校验
|  +-- lyco-bsm/        F2/F3 Bedrock 几何、玩家模型、GLB 解析、体素化转换
|  +-- lyco-audio/      F6  WAV 编解码、生成后端（stub + 子进程）
|  +-- lyco-image/      F7  程序化立绘、生成后端
|  +-- lyco-lyrics/     F8  歌词解析与结构校验、生成后端
|  +-- lyco-bundle/     S5  编排 + 自描述 manifest
|  +-- lyco-mcp/        F9  MCP server（JSON-RPC over stdio）
+-- _RESEARCH/          lyco skill 预研报告（00-04）
+-- scripts/            测试夹具生成器（造 GLB）

3 つの設計原則

1. デコードはエンコードより重要です。 音声、画像、歌詞は書き出した後に必ず読み戻して検証します。子プロセスの終了コードを、生成成功の証拠として扱うことは決してありません。
2. プレースホルダーは明確に示す必要があります。 組み込みの stub バックエンドは、CLI、manifest の placeholder フィールド、notes の 3 か所に表示されます。これにより、1 つの bundle が 5 回の本物の生成のように見えることはありません。
3. モデルが必要な処理は子プロセスの背後に隠します。 ACE-Step / ComfyUI / あらゆる LLM の CLI について前提を置かず、引数の形式だけを定め、--backend で指定します。

生成：Kaggle の無料 GPU

スキン生成は実際に実行できます —— ローカルに GPU は必要ありません：

lyco-cli skin generate --backend kaggle --owner <you> --slug lyco-skin-gen --seeds 7,42

Rust で生成したノートブックを Kaggle に送信し、無料の Tesla T4 上で AliceKJ/BLOCKv0.6 を実行します。完了までポーリングし、生成物を取得した後、ローカルで overlay の修復、構造検証、人型プレビューを行います。

意図的に役割を分けています。Kaggle は代替不可能な処理（GPU 推論）だけを担い、UV の知識と修復ロジックは Rust に任せます。 生成されるノートブックにUV テーブルは含まれず、CI でこれを確認します。

その他のモデルが必要な処理（音声エンジン、画像エンジン、LLM）は、引き続き --backend '<コマンドライン>' の子プロセス境界を使います。

F11 Spine：レンダリングと、パッケージに含めて配布しない理由

lyco-cli spine info model.atlas        # 页 / region / 是否声明 size、pma
lyco-cli spine normalize model.atlas   # 从 PNG 头补/修 size，幂等
lyco-cli spine version model.skel      # 读出需要的 Spine 版本

lyco-spine-render は Spine の骨格にポーズを付け、CPU 上で PNG を描画できます（describe / render --animation NAME）。実際のアークナイツのデータで検証済みです：Spine 3.8.99、52 mesh、508 三角形。

ただし、このリポジトリのバイナリには含めて配布しません。理由は明確です：

• 公式の Spine ランタイムにリンクしており、これは Spine Runtimes License Agreement（商用ライセンス） の対象です。
• このリポジトリのソースコードは MIT ライセンスですが、そこからビルドしたバイナリは MIT ライセンスではありません —— 配布にはご自身の Spine ライセンスが必要です。
• そのため、デフォルトの CI ではコンパイルできることだけを検証し、artifact は生成しません。windows-binary では MIT のみで提供できる lyco-cli.exe を配布します。

このバイナリを入手するには、リポジトリ内の build from source workflow（workflow_dispatch）を使います： ご自身の fork で実行し、ご自身のライセンスのもとでビルドします。生成物はその実行のみに含まれます。

入力項目：

• target —— デフォルトは lyco-spine-render。lyco-cli または both も選択できます。
• runner —— デフォルトは windows-latest。ubuntu-latest も選択できます。
• spine_lib —— リンクする Spine ランタイムの git URL（デフォルトは rusty_spine3.8）
• spine_rev —— そのランタイムの revision。commit / tag / branch のいずれも指定できます。

spine_lib と spine_rev は実際に反映されます：workflow はビルドを始める前に crates/lyco-spine-render/Cargo.toml の該当行を書き換えるため、別のランタイムを試すこともできます。 ランタイムの URL、revision、ライセンスリンクはビルド開始時に表示され、キャッシュ key にも含まれます。 revision を変更しても、古い生成物が誤って使われることはありません。

キャッシュ：デフォルトの CI とこの workflow では、2 層のキャッシュを使用します ——
~/.cargo/git/db と ~/.cargo/git/checkouts（Spine ランタイムの git 依存関係の clone。コールドスタートで最も時間がかかる処理）、および rust-cache が管理する target/ の増分コンパイルです。

注意：pma は Spine 4.x のキーです。 3.8 の atlas に pma: true を書き込むと、3.8 ランタイムは そのファイルをまったく読み込めなくなります —— 実測で確認済みです（アークナイツ素材プールの 561 グループ中、243 グループに含まれています）。対処方法は 2 つあります：

• レンダリング時に自動で除去：lyco-spine-render は読み込み前に 3.8 が認識できないフィールドを除去します（一時 atlas に書き込み、使用後に削除）。561/561 グループすべてを読み込み、レンダリングできます。
• オフラインで修復：lyco-cli spine normalize <atlas> --strip-3-8 で、除去した内容をファイルに書き戻します。

検証

CI の実行ごとに、test → clippy -D warnings → build → 6 グループのスモークテスト → fmt を実行します。 スモークテストでは外部実装と照合して検証します：Python の wave で生成した WAV をデコードし、PNG ヘッダーを直接読み取ってサイズを確認し、その場で GLB を生成して変換に入力し、実際の MCP セッションも 1 回実行します。

既知の課題

• 実際の ACE-Step / ComfyUI / 混元 3D / LLM の連携には GPU マシンが必要です（スキンは Kaggle で動作確認済みです）。
• keep-percent=12% のヒューリスティックでは、一部の seed で残りがほとんどない overlay の矩形がすべて削除されることがあり、実際の衣服の細部が失われる可能性があります。値を下げるべきか、人の目で判断する必要があります。
• BGM は現在 WAV 形式です。mp3 への変換には ffmpeg が必要です。
• 変換後のモデルのテクスチャは「各ボックスの平均色」であり、元のメッシュテクスチャを UV に再マッピングしたものではありません。
• 変換後のモデルを Blockbench にインポートできるかは人手で未検証です（自動化で検証できるのは schema 層までです）。

用語の訂正

調査の初稿では「YSM/BSM は BlockBench 形式」と記載していましたが、誤りです。_RESEARCH/02-niche-knowledge.md の第 5 節で訂正しました： Blockbench にこれらの形式はなく、ライセンスは GPL-3.0 です。YSM は Yes Steve Model mod の暗号化バイナリで、BSM は存在しません。本プロジェクトが採用するのは、オープンな Bedrock geometry です。

ライセンス

MIT