# genanki からの移行

Canonical page: https://ankiforge.dev/ja/docs/genanki-migration/
Language: ja
Description: genanki のモデル、フィールド、デッキ、メディアを Anki Forge の概念に対応付け、識別情報を引き継ぐ条件を確認します。

ライブラリを選んでいる段階なら、[Anki Forge と genanki の比較](https://ankiforge.dev/ja/docs/anki-forge-vs-genanki/)を参照してください。

Anki Forge は安定したデータキー、検証済みの不変モデル、データを所有するメディアスナップショット、明示的なビルド・更新操作を使います。新しい作成モデルであり、genanki のオブジェクトや、削除済みの Anki Forge の Deck・lockfile インターフェースを模倣するものではありません。

| genanki の概念 | Anki Forge での対応 |
| --- | --- |
| 数値 ID を持つ Model | `NoteType.builder(stable_key)...build()` |
| 識別子として使うフィールド名 | 安定した Field キーと、独立した表示名 |
| フィールドの文字列を保持する Note | モデルを所有する `model.note().field(key, content)` |
| ノートをまとめる Deck | 既定デッキを持つ Project。必要に応じてノート単位の `.deck(name)` |
| パッケージのメディアファイルパス | データを所有する `Media.file(path)` の値。型付きコンテンツを通して自動収集 |
| パッケージの書き出し | `project.build(BuildOptions.to(path))` |
| フィールド由来の既定 GUID、または独自 GUID ルール | 明示的で安定した名前空間とノートキー |

```python
from ankiforge import Project, NoteType, Field, Template, BuildOptions

model = (NoteType.builder('vocabulary').name('Vocabulary')
    .field(Field('word', name='Word', required=True))
    .field(Field('meaning', name='Meaning'))
    .template(Template('recognition', '{{word}}', '{{FrontSide}}<hr>{{meaning}}'))
    .build())
project = Project('vocabulary-course', default_deck='Languages::Vocabulary')
project.add('dictionary:cell', model.note().field('word', 'cell').field('meaning', '细胞'))
project.build(BuildOptions.to('vocabulary.apkg'))
```

キーには永続的な業務識別子を使います。表示名の変更や定義の本文の変更で、キーを変えないでください。インポーターの明示的な要件として内容に基づく識別情報が必要な場合を除き、現在のフィールド内容をハッシュにしないでください。キーのないソースデータには、SDK の外でキーを割り当てて永続保存します。

テンプレート式は Field キーを使います。表示名は独立して翻訳でき、ライブラリがキー参照を Anki のフィールド名へコンパイルします。宣言の欠落や競合は、ノートを追加する前のモデル完成時に拒否されます。ノート追加時にはモデルの依存関係を自動収集し、1つのモデルキーに競合する定義がある場合は拒否します。

文字列はプレーンテキストです。意図的な HTML は `Content.html(...)` で包んでください。`media.image()` / `media.sound()` と `Content.sequence(...)` で内容を組み合わせます。元のパスを削除・編集してもファイルのスナップショットは残ります。直接記述した HTML・CSS・スクリプトから参照する依存関係は、モデルビルダーの `.asset(media)` または `project.add_asset(media)` で明示的に宣言します。

後続リリースでは、同じ名前空間とデータキーで新しい Project を作成し、`BuildOptions.to(next_path).update_from(previous_original_apkg)` を呼び出します。オリジナル APKG が完全な識別情報の証拠を提供します。この手順は任意の古いパッケージから識別情報を復元したり、既存の genanki の数値 ID・GUID を自動変換したりするものではありません。別途検証済みのデータ移行で対応関係を確立しない限り、新モデルでの最初の配布物は、識別情報を引き継がない意図的な境界として扱ってください。

[クイックスタート](https://ankiforge.dev/ja/docs/python-quickstart/)、[API リファレンス](https://ankiforge.dev/ja/docs/python-api/)、[更新ポリシー](https://ankiforge.dev/ja/docs/python-diagnostics/)を参照してください。