karasu アプリの使い方

English · 日本語（このファイル）

karasu には、.krs ファイルをリアルタイムで操作可能な図に変換するグラフィカルアプリが付属しています。利用方法は 2 通りあります。

karasu serve — ディレクトリ内の .krs ファイルを監視し、保存のたびにブラウザで再描画する、ローカルのプレビュー専用サーバー。編集は普段使いのエディタで続けたまま、プレビューだけが追従します。
ブラウザ版プレイグラウンド https://karasu.kompiro.dev/ — エディタ・ファイルツリー・ライブプレビューを備えたフル機能版。すべてブラウザ内で動作し、インストール不要・データは外部に出ません。

どちらも同じプレビューペインを共有するため、後述のプレビューペインの節はどちらの使い方にも当てはまります。

`karasu serve` — 手元のファイルをプレビューする

.krs ファイルを含むディレクトリで serve を実行します。

# .krs ファイルのあるディレクトリで
npx --yes karasu@latest serve

# ディレクトリとポートを指定する場合
npx --yes karasu@latest serve ./architecture --port 4000

karasu serve
  Directory : /path/to/architecture
  Preview   : http://localhost:3000

Watching for .krs file changes...

表示された URL（既定は **http://localhost:3000**）を開きます。どのファイルを表示するかは URL のパスで決まります。

URL	表示されるファイル
`/`	`index.krs`（`.krs` が 1 つだけならそのファイル）
`/payment`	`payment.krs`
`/org`	`org.krs`

serve はプレビュー専用で、エディタは内蔵しません。次の短いループで作業します。

普段使いのエディタ（または VS Code 拡張）で .krs を編集する。
保存する。
サーバーが変更を検知してブラウザに通知し、図が自動で再描画される。手動リロードは不要。

構文エラーがある間は、直前の正常な図が 「outdated」 バナー付きで表示され続けます。詳しくは診断を参照してください。

アプリがサポートするエントリファイルは index.krs です。トップレベルのモデルをここに置けば / でそのまま開けます。

ブラウザ版プレイグラウンド

とりあえず karasu を試したいだけなら https://karasu.kompiro.dev/ を開いてください。エディタを有効にした同じアプリです。

.krs 構文ハイライト付きの Monaco エディタ（ライト / ダークテーマ）。
.krs / .krs.style ファイルを作成・リネーム・削除できるファイルツリー。すべてブラウザ内（OPFS）に保存されるため、再訪時も作業が残り、サーバーには一切送信されません。
入力に追従して更新される、後述と同じプレビューペイン。

プレイグラウンドは既定で index.krs を開きます。編集機能についてはエディタを参照してください。

プレビューペイン

プレビューペインはアプリの中核で、serve でもプレイグラウンドでも同一です。

図のビュー

モデルは 4 つのビューで表示でき、ビュータブまたはキーボードショートカットで切り替えます。

ビュー	ショートカット	内容
System	`Ctrl/Cmd+1`	サービス・システムのアーキテクチャ
Deploy	`Ctrl/Cmd+2`	デプロイトポロジ（物理構造）
Org	`Ctrl/Cmd+3`	チームとロール（組織構造）
CRUD	`Ctrl/Cmd+4`	ユースケース × リソースの読み書きマトリクス

System / Deploy / Org が表す 3 つの次元についてはコアコンセプトで説明しています。

図の操作

ズーム — 図の上でマウスホイールを回す。
パン — クリックしてドラッグする。
ドリルダウン — 子を持つノードをクリックして内部へ降りる。深さはパンくずリストで追跡される。
ノード詳細 — リーフノード（または情報ボタン）をクリックすると、id・説明・タグ・関連する接続を表示するサイドパネルが開く。
ビュー間ナビゲーション — 関連するビューへジャンプする。例えば System のサービスから、それが動作する Deploy、所有する Org のチームへ移動。

診断

パースエラー・警告・情報メッセージは図の上部のバナーに表示されます。エラーがある間は最後に正常にパースできた図が表示され続け、 「⚠ Diagram is outdated — fix errors to update」 と表示されるため、タイプミスで画面が真っ白になることはありません。

プレビューの 2 つの操作面

プレビューの操作は、何をするかで 2 つの面に分かれています。描かれる図を変える コントロールは、図のすぐ上のパンくず行に。図を外へ持ち出すコントロールは上端の ツールバーに置かれます。両方をツールバーに並べていた頃は、通常のウィンドウ幅で 2 行に折り返していました。

パンくず行 — 図を変えるもの

アイコンモード — サービスアイコンとプレーンな図形を切り替える。
グループ化（System ビュー、モデルに organization ブロックがある場合）— チームを選ぶと、各チームが所有するサービスを折り畳み可能な境界フレームで囲む。フレームごとに ⊖/⊕ トグルがある。
ファセット（System ビュー、モデルが facet を宣言または参照している場合）— 強調したい facet を選ぶ。所属要素に色付きのリングが付き、それ以外は減光し、 legend に色の凡例が出る。メニューは開いたままなので続けて複数選べる。複数の facet に属する要素には所属数だけリングが重なり、順序は常に同じなので 2 枚のカードを一目で比較できる。overlay は グループ化と直交する — team / boundary のバンド表示と同時に読める — し、ドリルダウン・畳み込み・書き出しでも残る。選択はビューア側の状態で、.krs には何も書かれない。選択を解除すれば図は元の見た目に完全に戻る。同じメニューの下部にある所属一覧は、もう一方の問い —— facet X に属する要素はどれか —— に 1 つのパネルで答える。各 facet の description・ポリシーリンク・所属要素の一覧が出る。この一覧はコンパイルのたびに facets プロパティから導出されるので、保守する対象ではない。facet 名をクリックすると、メニューと同じように強調のオン / オフが切り替わる。
すべて畳む / すべて展開（System ビュー）— ビューに畳めるものがあるとき —— チーム境界フレーム または external / infra のレイヤー帯 —— それらをまとめて一括開閉するボタン。すべて畳むと俯瞰ビューになる（「既定で畳んでおき、必要な所だけ開く」）。グループ化していなくても、external / infra 帯があれば表示される。単一・非グループ化の system では、すべて展開方向で全サービスをその場に一括展開する（各サービスの domain が境界フレームに入る）—— すべて畳むの一括版。トグルは全畳み ⇄ 全開きの二値なので、external / infra 帯を持つモデル（帯は起動時は開いている）はまず「すべて畳む」表示になり、すべて畳む → すべて展開の順で全展開に到達する。帯の無いモデルは 1 クリックで展開できる。多数のサービスを開くと意図的に overload ヒントが出る。すべて畳むで 1 クリックで俯瞰へ戻れる。
エンティティ（System ビュー、エンティティを持つ domain までドリルしている場合）— ユースケースビューをその domain のエンティティビューに切り替える。
ツリー表示（Org ビュー）— 組織のグリッド表示をツリー表示に切り替える。
全レイヤー表示 — すべてのドリルダウン階層を重ねて描画する。

ウィンドウが狭いときは、パンくずを潰す代わりにその下へ折り返します。

ツールバー — 図を持ち出すもの

エクスポート — 現在のビューを SVG で保存。分割ボタンのメニューからは、ドリルダウンツリー、全ビューを束ねた 1 枚の SVG、手作業で編集できる draw.io（mxGraph XML）、そして同じ全ビュー SVG をダウンロードせず新しいタブで開く全ビューを開くも選べる。
Share — モデルを URL に載せた共有リンクをコピーする。
Docs — 組み込みのタグ / アノテーションリファレンスを図の横に並べておけるポップアウトウィンドウで開く。公開ドキュメントサイトへのリンクも同じメニューにある。
フォーカス（Ctrl/Cmd+Shift+F）— プレビューを全幅に広げる。

エディタ（プレイグラウンド）

エディタが利用できる場合（serve ではなくプレイグラウンド）、.krs の記述は次の機能で支援されます。

.krs / .krs.style の構文ハイライト。システム設定に追従するライト / ダークテーマ。
フォーマット（Shift+Alt+F、または ⌥ Format ボタン）で .krs を整える。 .krs.style ファイルでは代わりに ✨ Tidy ボタンが重複ルールをまとめる。
入力に追従して再描画されるライブプレビュー（保存不要）。
折りたたみ可能なサイドバー（Ctrl/Cmd+B）。ファイルツリー（Ctrl/Cmd+Shift+E）と現在のモデルのアウトライン（Ctrl/Cmd+Shift+O）を切り替えられる。アウトラインのノードを選択すると図中でハイライトされる。

編集ペインには Chat と Settings タブもあります。Chat は .krs の下書きや編集を支援する任意の AI アシスタントで、利用するには事前に Settings で API キーを保存する必要があります。

キーボードショートカット

ショートカット	動作
`Ctrl/Cmd+Shift+P`	コマンドパレットを開く — 全コマンドを検索して実行
`Ctrl/Cmd+1` … `Ctrl/Cmd+4`	System / Deploy / Org / CRUD ビューへ切り替え
`Ctrl/Cmd+Shift+F`	プレビューフォーカス（全幅）を切り替え
`Ctrl/Cmd+B`	サイドバーを切り替え（プレイグラウンド）
`Ctrl/Cmd+Shift+E`	ファイルツリーを表示（プレイグラウンド）
`Ctrl/Cmd+Shift+O`	アウトラインを表示（プレイグラウンド）
`Shift+Alt+F`	現在の `.krs` をフォーマット（プレイグラウンド）