vignette-catalog-compose-notebook

ビネットカタログで作業する

カタログは、catalog.toml と、実行例であると同時にインポート可能なヘルパーモジュールでもある、自己完結型の marimo ノートブックで構成されています。 <skill-dir> をインストール済みのこのスキルに解決し、その Python スクリプトを直接実行して uv の shebang が適用されるようにします。 <skill-dir>/scripts/catalog-session.py がセッションのライフサイクル全体を管理します。カタログカーネルの起動、再利用、状態確認、実行、停止を確実に行い、シェルラッパーを経由しても動作します。 場当たり的な nohup やバックグラウンド実行で marimo を起動してはいけません。また、pgrep、ss、curl、/api/sessions からセッションの状態を手作業で再構築してはいけません。 ヘルパーが失敗した場合は、ほかのことを試す前に、出力をそのまま報告してください。

まずリクエストの内容を振り分ける

• 特定のノートブックを開く、実行する、または表示する場合、あるいは「このカタログを起動して」という場合は、以下の高速手順に従ってから終了します。 この経路ではノートブックの仕様、無関係なノートブック、データ参照を読まないでください。
• すでに起動中のノートブックの入力を変更する場合は、marimo-pair のコードモードを使って既存のセッションを再利用します。 現在のカーネルが復旧不能な場合を除き、2つ目のカーネルを起動しないでください。
• 新しいノートブックを作成する場合、またはデータに関する質問に回答する場合は、作成ワークフローに従います。
• オープンエンドのリサーチの場合、仕組みについては作成ワークフローを使い、リサーチの方法論はこのスキルではなくユーザーとリポジトリに委ねます。

高速手順：特定のノートブックを開く

1. リポジトリの AGENTS.md と catalog.toml を読みます。 認証要件、文書化されたブラウザーアクセス方法、[getting_started].first_notebook を確認します。起動に不要な注意事項とノートブックのコードは読み飛ばしてください。

2. ユーザー向けのホストを選び、次のコマンドを1つ実行します。このコマンドは、該当するノートブックの健全なセッションを再利用するか、新たに起動し、セルの実行を確実にして結果を出力します。

   <skill-dir>/scripts/catalog-session.py open [--host <documented-address>] [notebooks/<name>.py]
   

   ノートブックを省略すると、[getting_started].first_notebook が開きます。 対話型で起動する場合、ユーザーに再度指定を求めず、ユーザー、システム、またはリポジトリが文書化しているアクセス経路を選択します。 ユーザーのブラウザーが実行マシン上で動作していると決めつけないでください。 直接アクセスする場合は、文書化されている Tailscale または LAN のアドレスかホスト名にバインドします。表示されるホスト名をバインドアドレスと異なるものにする場合は、--url-host <hostname> を使います。 ヘルパーは marimo のアクセストークンを無効にするため、文書化された環境で全インターフェースへのバインドが必要な場合（ローカルホストとリモートの両方から同時にアクセスする場合など）に限り、--host 0.0.0.0 --url-host <hostname> を使います。 ローカルのみでアクセスする場合、または直接アクセス経路が不明な場合はホストオプションを省略し、出力された URL が実行マシン上でのみ有効であることを明示します。リモートアクセスにトンネルが必要な場合は SSH フォワーディングを使います。

   ホストオプションが適用されるのは、新しいサーバーを起動する場合だけです。 open が、選択したホスト名では到達できないと報告されている URL のセッションを再利用した場合は、不一致を報告し、要求された起動が成功したと主張しないでください。 ユーザーの既存の指示で再起動が許可されている場合、または許可を得た場合を除き、そのセッションの作業状態を維持してください。

3. url=、session=、および cells= の行をそのまま報告します。 cell_error= の行は、ノートブックが実行されたものの、失敗したセルがあることを示します。これらを報告し、反復作業のためにセッションは起動したままにします。 セッション状態に関する追加質問には <skill-dir>/scripts/catalog-session.py status --cells で回答し、セルを再実行するには run <port> を使います。自分が所有するセッションを停止するには stop <port> を使います。

ワークフローの構成

一般的なノートブックの作成には marimo-notebook を、ライブカーネルを使う操作には必ず marimo-pair を使用します。 リポジトリの指示、catalog.toml、およびこのスキルのノートブック契約が、より具体的な場合は一般的な marimo-notebook のアドバイスより優先されます。 いずれかのプロジェクトスキルが存在しない場合は、そこで作業を止め、暗黙にインストールするのではなく、リポジトリに記載されたインストールコマンドをユーザーに提示します。

1. リポジトリの AGENTS.md、catalog.toml、および [data].caveats で指定されているパスを読みます。 マニフェストを使って候補となるノートブックを探し、実際のコードと docstring を読みます。 マニフェストは厳選されたルーティングテーブルであり、すべてのノートブックやヘルパーを網羅しているとは限りません。

2. 質問に答えるための最短の経路を選びます。 既存のノートブックのワークフローがすでに適している場合は、その入力を変更します。 それ以外の場合は、構成したノートブックを作成し、リクエスト、解析、結合、プロットを再実装するのではなく、最も近いヘルパーをインポートします。 ノートブックを作成または変更する際は、references/notebook-contract.md を読みます。

3. 新しい構成では、初期設定用のインポートを含む、最小限の有効な marimo スキャフォールドを作成します。 適応または構成するノートブックを catalog-session.py open notebooks/<name>.py で開き、高速パスのアクセスルールに従ってホストオプションを追加します。 報告された URL とセッション ID を marimo-pair で使用します。保存済みファイルを検証するまでは、アクティブなランタイムを信頼できる情報源とします。

4. ライブカーネルで作業します。 永続化するセルの編集には marimo-pair のコードモードを使い、変更した各セルを実行してから、返されたテーブルとレンダリングされた図を確認して解釈します。 リモートや REST の調査は、範囲を限定したクエリから始め、意図的に範囲を広げます。 回答に必要な依存関係はすべてノートブックに含め、スクラッチ状態だけに置かないようにします。

5. 保存済みノートブックをクリーンな状態から検証します。

   bash <skill-dir>/scripts/validate-notebook.sh notebooks/<name>.py
   

   バリデーターは、固定バージョンの marimo チェック、安定した Ruff ルールセット、初回実行、および失敗したセルの明示的なスキャンを実行します。これは、失敗を報告しても marimo が終了コード 0 で終了することがあるためです。 デフォルトではソースとスナップショットを復元します。カタログのポリシーでフォーマットとスナップショットの更新が求められる場合に限り、--write を渡します。 生成されたセッションスナップショットと分析出力については、カタログ独自のポリシーに従います。

6. 実行した内容、確認した内容、回答とその限界、さらにセッションが引き続き役立つ場合はライブ URL を報告します。 不要になったセッションは <skill-dir>/scripts/catalog-session.py stop <port> で停止します。 構成したノートブックを再利用可能なビネットとしてキュレーションすることをユーザーが希望する場合に限り、catalog.toml に追加します。

カタログ全体の検証を求められた場合は、catalog.toml が網羅的だと仮定せず、実際のノートブックファイルを列挙します。カタログが生成されたスナップショットを追跡している場合は、使い捨てのワークツリーまたはアーカイブで各ファイルを検証します。