*スペース（アーティファクト）の仕様メモ ― 大きな画像の登録を中心に

Museのスペース（アーティファクト）に大きな画像を登録しようとして分かった仕様と対処法のメモです。
検証済みのものと、手法だけ紹介する未検証のものを分けて書きます。
検証は2026-11-15、衣装ギャラリー系のスペース（アイテム登録アクションを持つもの）で行いました。

**前提：スペースへのデータの渡り方

-スペースのアクション経由でデータを渡すとき、画像のようなバイナリデータもBase64という形式の文字列に変換されて「文字データ」としてやり取りされる
-Base64化するとデータ量は元の約1.33倍になる。一度に扱える文字量には限りがあるため、数MB級の画像は数百万文字の文字列になり、そのままでは渡しきれない
-実測では、数万文字の規模でも転送途中で文字化けや重複が起きて登録に失敗した。小さい画像や文字情報だけなら問題なく渡せる
-なお、生成した画像の原画ファイル自体はMuseの環境内にファイルとして保存されており、ライブラリからは開ける。失敗するのはスペース内ギャラリーへの「控え」の登録だけ

**保存形式は2種類ある

-blob形式：アクションでアップロードすると、スペース側に画像のコピーが保存される（blob_keyが付く）。元ファイルを消しても残るが、登録のたびにデータ全量を運ぶ必要がある。保存先は相対URLのため、Muse側からハッシュ照合ができず「登録できたが中身が化けていないか」を検証できない
-asset_key参照形式：スペースにバンドルされたアセット台帳への参照で持つ形式。データの運搬が不要で軽い。内蔵アイテム（アバターのライブラリ由来など）はこの形式になっている

**実証した方法：編集ビルダーにファイルを直接読ませる（検証済み）

-スペースの「編集（ビルド）」経路では、作業担当（ビルダー）がワークスペース上のファイルを直接読んで取り込むことができる。チャット経由でBase64を運ばないので、大きな画像でも化けない
-実測：約887KB・832×1216のPNGで、元ファイルと取り込み後のコピーのmd5が一致した（バイト同一、原寸のまま画質低下なし）
-取り込まれたアイテムはasset_key参照形式で登録された
-手順の型は次のとおり
--1. Museに「ファイルを直接読む経路で取り込んで」とスペースの編集を依頼する
--2. 取り込みの確定に所有者側の取り込みアクション（seed相当）の実行が必要な場合がある。この種の所有者専用アクションは委譲先（サブエージェント）からは実行できず（owner_requiredと返る）、メインのClaude本人が実行する
--3. 登録されたアイテムのキー形式（asset_keyかblobか）を確認する

**できなかったこと（検証済み）

-ワークスペースのフォルダ（アバターの生成物置き場など）にファイルを置いただけでは、取り込みアクションの対象にならない。取り込みの供給元はスペースにバンドルされたアセット台帳だけだった
-つまり「実体は置いておいて参照だけにする」方式は、参照先を台帳に載せる工程（上の編集経路）とセットでないと成立しない

**削除時の注意（検証済み）

-asset_key参照形式のアイテムは、アイテムの行を消しても台帳側にアセットが残っていると、取り込みアクションの実行時に復活する
-完全に消すには、編集経路でアセットと取り込み登録を取り除いてから、アイテムの行を消す

**分割アップロード方式（手法の解説・こちらでは未検証）

大きなデータを小さな断片に分けて送り、受け取る側で結合して元に戻す「分割アップロード（chunked upload）」という、ファイル転送では一般的な手法です。共有された資料をもとに紹介します。

-手順
--1. スペース側に、データの受け取りを「開始 → 断片の追記 → 完了（結合）」の3段階で行う仕組み（アクション）を用意する
--2. 画像をプレビュー用に軽量化（縮小やWebP化など）したうえで、Base64文字列を一定の文字数ごとに分割し、順番に送信する
--3. 完了時に、送信前と結合後のデータの指紋（SHA-256ハッシュ）を照合し、欠落や文字化けがないことを確認する
-運用のポイント
--ギャラリーにはプレビュー版、原画はファイルとして保存、という住み分けが現実的。原画まで分割転送しようとすると断片が100個以上になり、作業量が膨らむ
--プレビューは多少の画質劣化を許容し、軽く作るのが向いている
--トークン消費について：保存データが増えてもトークン使用量は減らない。消費は保存量ではなく、読み書きや転送など「処理した量」に応じて増える。分割転送の作業自体も、文字として経由する量ぶんのトークンを消費するので、その意味でもプレビューは軽いほど有利
-前提として、受け側に3段階受け取りのアクションを追加実装する必要がある。こちらの環境では未検証で、上記の「直接読ませる方法」で足りたため実装はしていない

**その他の仕様メモ（ついでに分かったこと）

-スペースやドキュメントの中のリンクから、ワークスペースのファイルを開くことはできない（相対リンク、sandbox形式のリンク、絶対パス、いずれも遷移が塞がれている。検証済み）。ファイルを開けるリンクはチャットの中に限る
-スペースの識別子（スラッグ）はタイトルから自動生成されるが、日本語タイトルの漢字は中国語読み（拼音）で音訳されることがある（例：使用状況 → shi-yong-zhuang-kuang、書架 → shu-jia）。気になる場合は英語の名前で作るとよい。スラッグは作成後に変更できない
-スペースの作成・編集は作業担当（ビルダー）が行い、チャットのClaudeは依頼と指示を渡す、という分担になっている。所有者専用アクションの実行可否など、担当によってできることが違う場面がある