> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makkii.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# zip の形式

> ワークスペース zip の構造、マニフェスト、救出バックアップ zip との違い

Storm Code が扱う zip は2種類あります。**目的が違うので、混同しないでください。**

| 種類               | 作られる場所                                        | 取り込めるか               |
| ---------------- | --------------------------------------------- | -------------------- |
| **ワークスペース zip**  | `File > Export Zip...`、選択画面のエクスポート            | そのまま取り込めます           |
| **救出バックアップ zip** | [旧データの救出画面](/storm-code/guides/legacy-rescue) | **中の `code.zip` だけ** |

## ワークスペース zip

平文で、フォルダ構造もそのままです。展開すれば普通のエディタで開けます。

```
my-project.zip
├── .scode/
│   ├── workspace.json      # 形式の種類とバージョン
│   └── snippets.json       # Design のスニペット
├── main.lua
├── lib/
│   └── util.lua
├── ui/
│   └── pfd.design
└── images/
    └── icon.png
```

### マニフェスト

`.scode/workspace.json` に形式の種類とバージョンが入ります。

```json theme={null}
{ "kind": "storm-code-workspace", "version": 3 }
```

**名乗ったバージョンに対応していなければ、明示的に拒否します。**
中途半端に読み込んでデータを壊すことはしません。

<Note>
  マニフェストが入っていない普通の zip は、パスと拡張子の検証だけを通して受け入れます。
  他のツールで作った zip を取り込みたい場合に使えます。
</Note>

### 入るもの・入らないもの

| 対象                     | zip                  |
| ---------------------- | -------------------- |
| ファイルとフォルダ              | 入る                   |
| Design (`.design`)     | 入る                   |
| 画像                     | 入る (ツリーが参照している実体を同梱) |
| スニペット                  | 入る                   |
| ファイル履歴                 | **入らない**             |
| パネル幅・開いていたタブ・カーソル位置    | **入らない**             |
| ログイン情報・MCP トークン・API キー | **入らない**             |

詳しくは [zip でバックアップ・移行する](/storm-code/guides/backup)を参照してください。

### 取り込み時の検証

| 内容          | 挙動                                |
| ----------- | --------------------------------- |
| パスの文法違反・重複  | 診断として列挙し、**1件でもあれば中断**            |
| 許可していない拡張子  | 無視し、スキップした一覧を表示                   |
| 読めない Design | **その `.design` だけを飛ばし、飛ばしたものを表示** |

Design だけ扱いが違うのは、1件のために zip 全体を拒否すると、
同じ zip の通常のコードまで取り込めなくなるためです。

## 救出バックアップ zip

[旧公開版のデータ](/storm-code/guides/legacy-rescue)を救出したときに作られます。

```
storm-code-legacy-backup-<日時>.zip
├── README.txt              # 使い方と制限
├── .scode/
│   └── workspace.json      # { "kind": "storm-code-legacy-backup", "version": 1 }
├── code.zip                # 通常のコード ← これだけ取り込めます
├── designs/
│   └── <元のパス>.json     # 旧 Design。自動変換しません
└── raw/
    ├── indexeddb.json      # 元のデータベースをそのまま退避
    └── local-storage.json  # 旧バージョンの作業状態
```

<Warning>
  **外側の zip をそのままインポートしないでください。**
  `.scode/workspace.json` の `kind` が違うため拒否されます。
  これは誤って取り込ませないための印です。

  取り込めるのは中の `code.zip` だけです。
</Warning>

`code.zip` はマニフェストを持たない普通の zip です。
ファイルを取り出すだけで、コードは変換されません。

### 取り出しに失敗した場合

**中途半端な `code.zip` を成功として出すことはありません。**

完全に復元できない場合は `code.zip` と `designs/` を含めず、
`raw/` だけを残して `EXTRACTION-ERROR.txt` に理由を記録します。

### `raw/` の形式

元のデータベースの内容をそのまま退避したものです。
各値は型を示すタグ付きで保存され、バイト列は base64 です。
配列の空き要素も区別されます。

対応できない型や循環参照があった場合、黙って落とすことはせず、明示的に失敗させます。