karasu アプリの使い方
English · 日本語(このファイル)
karasu には、.krs ファイルをリアルタイムで操作可能な図に変換するグラフィカル
アプリが付属しています。利用方法は 2 通りあります。
karasu serve— ディレクトリ内の.krsファイルを監視し、保存のたびに ブラウザで再描画する、ローカルのプレビュー専用サーバー。編集は普段使いの エディタで続けたまま、プレビューだけが追従します。- ブラウザ版プレイグラウンド https://karasu.kompiro.dev/ — エディタ・ ファイルツリー・ライブプレビューを備えたフル機能版。すべてブラウザ内で動作し、 インストール不要・データは外部に出ません。
どちらも同じプレビューペインを共有するため、後述の プレビューペインの節はどちらの使い方にも当てはまります。
karasu serve — 手元のファイルをプレビューする
Section titled “karasu serve — 手元のファイルをプレビューする”.krs ファイルを含むディレクトリで serve を実行します。
# .krs ファイルのあるディレクトリでnpx --yes karasu@latest serve
# ディレクトリとポートを指定する場合npx --yes karasu@latest serve ./architecture --port 4000karasu serve Directory : /path/to/architecture Preview : http://localhost:3000
Watching for .krs and .krs.style file changes...表示された URL(既定は **http://localhost:3000**)を開きます。どのファイルを 表示するかは URL のパスで決まります。
| URL | 表示されるファイル |
|---|---|
/ |
index.krs(.krs が 1 つだけならそのファイル) |
/payment |
payment.krs |
/services/order |
services/order.krs |
serve はプレビュー専用で、エディタは内蔵しません。次の短いループで
作業します。
- 普段使いのエディタ(または VS Code 拡張)で
.krsを編集する。開いているファイルでも、それが import するファイルや@importする.krs.styleでもよい。 - 保存する。
- サーバーが変更を検知してブラウザに通知し、図が自動で再描画される。手動 リロードは不要。
構文エラーがある間は、直前の正常な図が 「outdated」 バナー付きで表示され 続けます。詳しくは診断を参照してください。
アプリがサポートするエントリファイルは
index.krsです。トップレベルの モデルをここに置けば/でそのまま開けます。
ブラウザ版プレイグラウンド
Section titled “ブラウザ版プレイグラウンド”とりあえず karasu を試したいだけなら https://karasu.kompiro.dev/ を開いて ください。エディタを有効にした同じアプリです。
.krs構文ハイライト付きの Monaco エディタ(ライト / ダークテーマ)。.krs/.krs.styleファイルを作成・リネーム・削除できるファイルツリー。 すべてブラウザ内(OPFS)に保存されるため、再訪時も作業が残り、サーバーには 一切送信されません。- 入力に追従して更新される、後述と同じプレビューペイン。
プレイグラウンドは既定で index.krs を開きます。編集機能については
エディタを参照してください。
初めて開いたとき:Welcome とガイドツアー
Section titled “初めて開いたとき:Welcome とガイドツアー”初めて訪れたときは、プレイグラウンドが Welcome ダイアログとともに開き、 3 つの入口を示します。
- サービス分割を設計する:
service-splitサンプルを新しいプロジェクトとして開き、 5 ステップのガイドツアーを始めます。現在のアーキテクチャ、それを持つチーム(Org ビュー)、 計画中のアーキテクチャと現在の比較(差分モード)、移行途中の状態 (@migration_target、@planned)、結果の共有のしかたを順に見ます。ツアーは左下の小さな パネルで、ツアーを終了でどのステップからでも終えられ、最後のステップでは エディタに進むで終わります。 操作を頼むステップ(ドリル、チーム依存の表示、共有か書き出し)は、その操作をすると ✓ を 示します。先へ進むのは、見終わったときに次へを押してからです。 EC サイトが自分の業務から遠ければ、Step 1 で同じガイドを給与システムの題材 (payroll-splitサンプル)に切り替えられ、戻ることもできます。切り替えはサンプルと 一致するコピーがあればそれを使い、無ければ新しいコピーを開きます。 - 既存のシステムを理解する:Getting Started プロジェクトで 4 ステップのガイドツアーを 始めます。システム全体、どう動いているか(Deploy ビュー)、誰が持っているか(Org ビュー)、 見つけたことの共有のしかたを順に見ます。サンプルのままの Getting Started があればそれを使い、 無ければ新しいコピーを開くので、編集した内容はそのまま残ります。
- アーキテクチャの変化を追う:
service-splitサンプルを新しいプロジェクトとして開き、 4 ステップのガイドツアーを始めます。移行を今のシステムと比べた差分(差分モード)、モデルにある 移行の印(@migration_target、@planned、@deprecated)、目標を移行と比べた差分(残りの仕事)、 現在地の共有のしかたを順に見ます。
3 つのツアーの使い方は同じです。Welcome のサンプルが既存のプロジェクトを書き換えることはありません。
特定の場所へのリンク(ギャラリーの example や #krs-… のパーマリンク)から開いたとき、
一度どれかを選んだあとは、Welcome は出ません。コマンドパレット(Ctrl/Cmd+Shift+P)の
Show Welcome… で再び開けます。同じパレットの Restart Guided Tour… は、
最後に始めたガイドを Step 1 からやり直します。以前使ったプロジェクトを、そこでの編集ごと使います。
そのプロジェクトが無ければ Welcome の入口と同じように(給与のガイドは切り替えと同じように)開き、まだどのツアーも始めていなければ
サービス分割を設計するを始めます。
ツアーの途中でページを再読み込みしたり、アドレス欄からアプリを開き直したりすると、ツアーのプロジェクトで 同じステップに戻ります。特定の場所を開くリンク(ギャラリーの example、パーマリンク、別のプロジェクト)から 開いたときはツアーは戻らず、戻りたいときは Restart Guided Tour… を使います。
プレビューペイン
Section titled “プレビューペイン”プレビューペインはアプリの中核で、serve でもプレイグラウンドでも同一です。
モデルは 4 つのビューで表示でき、ビュータブまたはキーボードショートカットで 切り替えます。
| ビュー | ショートカット | 内容 |
|---|---|---|
| System | Ctrl/Cmd+1 |
サービス・システムのアーキテクチャ |
| Deploy | Ctrl/Cmd+2 |
デプロイトポロジ(物理構造) |
| Org | Ctrl/Cmd+3 |
チームとロール(組織構造) |
| CRUD | Ctrl/Cmd+4 |
ユースケース × リソースの読み書きマトリクス |
System / Deploy / Org が表す 3 つの次元については コアコンセプトで説明しています。
- ズーム — 図の上でマウスホイールを回す。
- パン — クリックしてドラッグする。
- ドリルダウン — 子を持つノードをクリックして内部へ降りる。深さはパンくず リストで追跡される。
- ノード詳細 — リーフノード(または情報ボタン)をクリックすると、id・説明・ タグ・関連する接続を表示するサイドパネルが開く。
- 定義へジャンプ — ノードを Cmd/Ctrl+クリックすると、エディタがそのノードを定義した 行へ移る。定義が別のファイルにあればそのファイルを開く。子を持つノードもドリル せずにジャンプする。詳細パネルの ↗ エディタへジャンプ も同じ動作をする。
- edge を焦点に — edge をクリックすると、両端のノードとその 2 つの間の edge 全部を、ラベルを省略せずに描いた 2 枚目の canvas がプレビューの上に開く。密な図 では長いラベルが短く描かれ、重なるラベルは描かれないので、全文はここで読む。
- ノードを焦点に — ノードに hover すると、そのノードに繋がらない edge が薄く
なる。角に出る ⇄ 関係 を押すと、そのノードと接続先が開く。片側にそれに依存する
ノード、反対側にそれが依存するノードが並ぶ。中のノードや edge をクリックすると
そこへ移り、ドラッグで表示範囲を動かせる(文字の上で押すと文字を選択する)。← 戻る で戻り、Esc で閉じる。
マウスを使わない場合: touch の端末ではノードの ⓘ を tap し、詳細パネルの ⇄ 関係 を
押す。キーボードでは Outline でノードを選び、コマンドパレット(
Ctrl/Cmd+Shift+P) から Show Relations of Highlighted Node を実行する。開いた中は Tab でノードと edge を移り、Enter か Space で focus のあるものを開く。 - ビュー間ナビゲーション — 関連するビューへジャンプする。例えば System のサービスから、それが動作する Deploy、所有する Org のチームへ移動。
database キャンバスのエッジの色
Section titled “database キャンバスのエッジの色”System ビューで database をクリックすると、簡易 ER ビューに降りる。ストアの
table リーフと、その間の関連が描かれる。関連の色は、その関連を誰が確認したかを表す。
線種はふだんと同じ意味で、実線が sync、破線が async。下の色は既定スタイルのもので、
.krs.style で変えられる。
| 色(dark / light テーマ) | タグ | 意味 |
|---|---|---|
スレートグレー、エッジの既定色(#94A3B8 / #64748B) |
なし | .krs に table → table エッジとして記録されている。手書き、または translate --from db が宣言された外部キーから出力したもの。確認済み。 |
スカイブルー(#38BDF8 / #0369A1) |
[projected] |
.krs には無い。両端の entity がともにこのストアの table に対応している entity 関連から描いたもの。entity 層の断定であり、ストアに対しては誰も記録していない。 |
暖色寄りのグレー(#A8A29E / #78716C) |
[inferred] |
translate --from db が命名規約(外部キー宣言の無い <stem>_id / <stem>_code 列)から推測して書いたもの。関連を確認できたらタグを消す。 |
- 記録済みエッジと投影エッジが同じ 2 つの table を結ぶときは、記録済みのほうだけが 描かれる。
- 図の凡例にはこれらの色は出ない。色は既定スタイルから来ており、モデルの
legendブロックから来ているのではないため。 - このビューはストアの完全な ER 図ではない。記録済みエッジは常に描かれるが、
entity関連が投影されるのは、両端の entity がともにこのストアの table に対応しているとき だけ。何が描かれないかは ストアスコープの ER ビュー、 描画時に付くタグの一覧は エッジへの自動タグ を参照。
パースエラー・警告・情報メッセージは図の上部のバナーに表示されます。エラーが ある間は最後に正常にパースできた図が表示され続け、 「⚠ Diagram is outdated — fix errors to update」 と表示されるため、タイプ ミスで画面が真っ白になることはありません。
プレビューの 2 つの操作面
Section titled “プレビューの 2 つの操作面”プレビューの操作は、何をするかで 2 つの面に分かれています。描かれる図を変える コントロールは、図のすぐ上のパンくず行に。図を外へ持ち出すコントロールは上端の ツールバーに置かれます。両方をツールバーに並べていた頃は、通常のウィンドウ幅で 2 行に折り返していました。
パンくず行 — 図を変えるもの
Section titled “パンくず行 — 図を変えるもの”- グループ化(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 ビュー)— 組織のグリッド表示をツリー表示に切り替える。
- チーム依存(Org ビュー、
organizationを宣言したモデルのみ)— 組織のグリッド 表示を、導出されたチーム依存グラフに切り替える。どのチームがどのチームに依存 しているかをownsと論理エッジの join から導く。.krsにこれを宣言する構文は 無く、同じ導出はkarasu team-dependenciesが表として出力する。実線がsync、 破線がasync、薄い線は一方が他方の org ツリー上の内側にいる対。所有チームに 解決しなかった端点の件数がフッタに出るので、疎なグラフは「疎結合な組織」では なく「ownsの記述不足」として読める。フッタの 2 行目は、囲みを跨いで所有されて いるノード(あるチームが持つノードが、別のチームが持つノードの内側にある状態)の 件数。呼び出しではなく囲みについての事実なので、ここでは矢印として描かない (同じ境界を論理エッジが跨ぐかどうかは別の話)。一覧はkarasu team-dependenciesが出す。 - 全レイヤー表示 — すべてのドリルダウン階層を重ねて描画する。
ウィンドウが狭いときは、パンくずを潰す代わりにその下へ折り返します。
ツールバー — 図を持ち出すもの
Section titled “ツールバー — 図を持ち出すもの”- エクスポート — 現在のビューを SVG で保存。分割ボタンのメニューからは、 ドリルダウンツリー、全ビューを束ねた 1 枚の SVG、手作業で編集できる draw.io(mxGraph XML)、そして同じ全ビュー SVG をダウンロードせず新しい タブで開く全ビューを開くも選べる。
- Share — モデルを URL に載せた共有リンクをコピーする。
karasu serveでは、 リンクの宛先は手元のサーバーではなく公開版の app(https://karasu.kompiro.dev) になり、受け取った人は karasu を動かしていなくても開ける。 - Docs — 組み込みのタグ / アノテーションリファレンスを図の横に並べておける ポップアウトウィンドウで開く。公開ドキュメントサイトへのリンクも同じメニューにある。 リファレンスが答えるのは「何が書けるか」で、どのタブからもガイドと記法クックブック (いつ使うか)、Examples ギャラリー(どう描かれるか)へのリンクが出る。 ポップアウトの中でも同じ。
- フォーカス(
Ctrl/Cmd+Shift+F)— プレビューを全幅に広げる。
エディタ(プレイグラウンド)
Section titled “エディタ(プレイグラウンド)”エディタが利用できる場合(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 キーを
保存する必要があります。
Settings には、図 1 枚を超えて残る設定を置いています。言語・テーマ・ 表示・Chat の API キーです。
表示 → ノードの表示では、ノードの描かれ方を選べます。
- シェイプカード(既定) — 内容に合わせて幅が変わるカード。
- アイコンカード(非推奨) — すべてのノードを固定サイズで描き、種別の
アイコンを添えます。ラベルの長さにかかわらずレイアウトが一定に保たれます。
このモードは非推奨であり、将来のメジャーバージョンで削除します(削除する版は未定です)。 外部 SVG
アイコン(
shape: url())を使ったシェイプカードへ移行してください。シェイプ モードでも、宣言したカード枠が描かれ、アイコンの縦横比が保たれるようになった ため、枠も絵も失わずに移行できます(docs/spec/style.ja.mdの shape プロパティ節を参照)。
表示の設定は編集ペインの中にあるため、プレビューだけを描画する karasu serve
では利用できません。言語・テーマ・Chat の API キーも同じ場所にあり、同じ制約を
受けます。
キーボードショートカット
Section titled “キーボードショートカット”| ショートカット | 動作 |
|---|---|
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 をフォーマット(プレイグラウンド) |
- コアコンセプト — 各ビューが描画する論理 / 物理 / 組織の 3 次元。
- ガイド — モデルの設計・読解・進化を題材にした タスク指向のウォークスルー。
- 構文リファレンス と
タグ・アノテーション — アプリが描画する
.krs言語。
© 2026 Hiroki Kondo · Licensed underApache-2.0