karasu アプリの使い方

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

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

• karasu serve — ディレクトリ内の .krs ファイルを監視し、保存のたびに ブラウザで再描画する、ローカルのプレビュー専用サーバー。編集は普段使いの エディタで続けたまま、プレビューだけが追従します。
• ブラウザ版プレイグラウンド https://karasu.pages.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 はプレビュー専用で、エディタは内蔵しません。次の短いループで 作業します。

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

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

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

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

とりあえず karasu を試したいだけなら https://karasu.pages.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」 と表示されるため、タイプ ミスで画面が真っ白になることはありません。

ツールバー

プレビューのツールバーには次の機能があります。

• アイコンモード — サービスアイコンとプレーンな図形を切り替える。
• 全レイヤー表示 — すべてのドリルダウン階層を重ねて描画する。
• エクスポート — 現在のビューを SVG で保存。分割ボタンのメニューからは、 ドリルダウンツリー、全ビューを束ねた 1 枚の SVG、手作業で編集できる draw.io（mxGraph XML）もエクスポートできる。
• リファレンス — 組み込みのタグ / アノテーションリファレンスを、図の横に 並べておけるポップアウトウィンドウで開く。
• フォーカス（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 をフォーマット（プレイグラウンド）

関連項目

• コアコンセプト — 各ビューが描画する論理 / 物理 / 組織の 3 次元。
• ガイド — モデルの設計・読解・進化を題材にした タスク指向のウォークスルー。
• 構文リファレンス と タグ・アノテーション — アプリが描画する .krs 言語。