syokan は何をしますか?
syokan(召喚、"summon")は動詞です — LLM がリッチな UI を召喚します。 ユーザーが「syokan X」(日本語では「X を syokan」)と言ったら、それはそのデータをビューとして召喚するリクエストです。内部ではスキーマ駆動のビューレイヤーが動作しています。JSX を書く代わりに、JSON の呪文 — カタログコンポーネントのツリー — を話すと、syokan がそれを定義済みコンポーネントでレンダリングします。 あなたの仕事は、データをエンベロープにまとめて syokan に POST することです。 文章中では、syokan を裸の他動詞として使ってください(「do syokan」や「syokan する」とは決して使わないでください — syokan は単独で成立します)。
syokan がまだインストールされていない場合(syokan --help が失敗する場合)、またはユーザーが「onboarding」「set it up」「初めて使う」などと言った場合は、references/onboarding.md の手順に従って最初のスナップショットまで導いてください。環境を変更する操作(インストールなど)を静かに実行しないでください。インストールされていないことを報告し、実行前にユーザーの承認を得てください(自分でインストールしてはいけません)。
絶対条件
- スナップショットはエフェメラルです: ポストされたスナップショットには永続性の保証はありません。再構築可能で一時的なデータ(今日の RSS、進行中のレビューなど)のみを配置してください。再利用するレイアウトについては、テンプレートを保存して再現してください(テンプレートは永続化されます。以下の「再現性のためのテンプレート」を参照)。
- JSON のみ: サーバーは JSON エンベロープしか受け付けません。生の Markdown やプレーンテキストは拒否されます。散文を表示するには、
MarkdownDocまたはPlainTextノードでラップしてください。 - 厳密なスキーマ: props は厳密に検証されます。スキーマにないキーは拒否されます。余計なキーを発明しないでください。
- リーフノードは子を持てません:
StackとCardのみが子を受け入れます。リーフノードに子を付けると取り込み時に拒否されます。
構成から表示まで
syokan catalogで利用可能なタイプと props を確認します(以下の「カタログ」を参照)。- 表示したいデータをそれらのコンポーネントにマッピングします。最上位は通常、コンテナー(
Stackなど)で、アイテムを垂直に積み重ねます。 - エンベロープ JSON に変換します(以下の「エンベロープの形状」を参照)。必須なのは
rootだけです。 - CLI でポストします(以下の「ポスト」を参照)。成功するとビュー URL が表示されます。
以前に似たようなビューを構築したことがある場合は、ゼロから始めず、保存済みテンプレートをベースにしてください(以下の「再現性のためのテンプレート」を参照)。
エンベロープの形状
POST ボディには以下の項目のみを含めることができます。
id、createdAt、url は絶対に含めないでください。サーバーが割り当てます。
{
"root": { "type": "Stack", "props": {}, "children": [ /* カタログノード; 完全な例は references/examples.md を参照 */ ] }, // 必須。ビューツリー
"title": "今日のRSS", // オプション。リストとビューヘッダーに表示されます
"metadata": { "source": { "label": "daily-rss" } }, // オプション。出典ラベル
"schemaVersion": 1, // オプション。サーバーが補完します
"idempotencyKey": "rss-2026-06-28" // オプション。このビューに名前を付け、後で更新しても重複しないようにします
}
metadata.source は label 以外のキーも保持できます。url や fetchedAt を追加しても構いません(例:{ "label": "gh-review", "url": "https://example.com/..." })。
日次や繰り返しのビューの場合は、idempotencyKey に日付などを含めてください。syokan CLI が残りを処理します。まずそのキーをターゲットにし、既存のビューがなければ新しいビューを作成します。したがって、最初のポストでビューが作成され、それ以降同じキーでポストすると、同じビューがその場で更新され、重複しません。最初のポストかどうかを自分で追跡する必要はありません。(CLI ではなく HTTP API を直接呼び出す場合:POST /api/snapshots は常に作成してキーをタグ付けします。PUT /api/snapshots は既存のキーをターゲットにし、存在しない場合は 404 を返します — 作成時に存在しない場合のエンドポイントはないため、CLI はまず PUT を試し、404 の場合に POST にフォールバックします。)
カタログ
利用可能な type とその props 定義は syokan catalog から取得してください(決して md に転記せず、毎回ここから取得してください)。
出力は { "items": [{ "type", "props", "childrenTypes" }] } です。
props: そのタイプの props(JSON Schema 形式)。required/enum/format(httpUrl はuri、Time.datetimeはdate-time)/additionalProperties:false(未知のキーは拒否されます)を指定されたとおりに満たしてください。childrenTypes:nullは子を受け入れるコンテナー、[]は子を受け入れないリーフ、[..]はリストされたタイプのみが子になれることを意味します。
コンポーネントを組み合わせた完全な例については、references/examples.md を参照してください。
ポスト
組み立てたエンベロープをファイルまたは標準入力で渡します。成功するとビュー URL が標準出力に表示されます(syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan)。
その他のコマンド、サブコマンド、環境変数、終了コードについては syokan --help --json を参照してください。タイプと props については syokan catalog を参照してください。
ローカルファイルのプレビュー
ローカルファイルの場合、syokan <path> が最短ルートです — ファイル自体を syokan します。エンベロープ JSON はそのままポストされます。それ以外(markdown / log / txt / json など)は、自動的にライブ FileDoc にラップされます。CLI は絶対パスに解決してサーバーに渡し、サーバーがコンテンツを読み込み、拡張子からフォーマットを推測します(.md/.markdown → markdown、.json → code、その他 → text)。ビューが開いている間はファイルの編集を追跡します(再ポスト不要)。
syokan notes.md # markdown をレンダリング。保存するたびにビューが更新されます
syokan app.log # 等幅フォントで成長するログを表示します
複数のファイルを 1 つのビューにまとめたり、Heading などのノードと混在させたい場合は、自分で FileDoc ノードを配置してください(props: path、絶対パスのみ。FileDoc は読み取りと変更追跡を処理します)。
逆に、ファイルの内容を静的に固定して表示したい場合(追跡不要、または内容を変換する場合)は、ボディを MarkdownDoc / PlainText / Code ノードに配置してください。jq --rawfile を使えば JSON エスケープを気にせずにストリーム入力できます。
jq -n --rawfile body README.md \
'{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
| syokan
再現性のためのテンプレート
お気に入りのビューを毎回ゼロから作り直さないでください。syokan にテンプレートとして保存し、再利用してください。
テンプレートとは「保存されたエンベロープそのもの」です。スケルトンに {{...}} のようなマーカーを配置し、自分で埋めることもできます。
一致するテンプレートが存在する場合は、ゼロから構築せず、リストから ID を見つけて取得し、データを入れ替えてポストしてください。保存する価値のある新しいビューを作成したら、それを保存し、次回はそれを使って再現してください。サブコマンドの構文(templates list|add|get|rm)については、syokan --help --json を参照してください。