インストールとエクスポート(packages)

パッケージとは、Busabase の space のサブツリーを git リポジトリ上の普通のファイルとして表現したものです。busabase.json マニフェストと、content/ ツリー — 本物の markdown ドキュメント、本物の Base 定義、そして 1 行 1 レコードの JSON — で構成されます。busabase-cli export がパッケージを書き出し、ダッシュボードの GitHub からインストール… ダイアログ、または busabase-cli install が GitHub URL から space に取り込みます。テンプレート、スキル、ナレッジベースまるごとを誰かに渡すための仕組みであり、パッケージは単なるファイルなので、相手は space に触れる前に中身を読み、diff を取り、pull request でレビューできます。

install はデフォルトで承認優先であり、パッケージを 2 つに分けて扱います。構造 — フォルダ、Base とそのフィールド・ビュー — は即座に作成されます。未マージの Base には id がなく、id がなければビューもフィールドもレコードもぶら下げる先がないからです。コンテンツ — レコード、ドキュメント、スキル、AirApp — はレビュー待ちの Change Request として届きます(install は待機件数を表示し、busabase-cli change-requests list で一覧できます)。つまり、見知らぬリポジトリが自分の space にできるのは空のテーブルを並べることまでで、そこに書き込まれた中身は、あなたが読んでマージするまで一切有効になりません。

ダッシュボードからインストールする

パッケージのインストールに CLI は必須ではありません。サイドバーの アクティビティ と並ぶショートカット群のなか、お気に入りと Base ツリーの上に GitHub からインストール… があります。開くとダイアログが 3 ステップで進みます。URL を貼る、何が作成されるかを読む、確定する。

インストールは space の owner/admin の操作です。 プレビューとインストールの両方でサーバーが検証します。パッケージにはスキルや AirApp — つまりこの space のエージェントが実行するコード — を含められるからです。サイドバーの項目は、それを使えるロールにのみ表示されます。メンバーが施錠された扉を見せられることはありません。いずれにせよ、最終的な判断はサーバー側の検証です。セルフホストのシングルユーザーサーバーでは検証すべきロールがないため、全員が通ります。

ステップ 1 — URL

リポジトリ URL という入力欄が 1 つだけあり、CLI と同じ URL を受け付けます(https://github.com/owner/repo、必要なら /tree/<ref>[/<subdir>] を続ける)。ブラウザ側で確認するのは空でないことだけで、残りはすべてサーバーの判断です。GitHub のホストのみを受け付け、ホスト名を解決し直してプライベートアドレスやループバックを指すものを拒否し、そのうえでダウンロードしたものが本当にパッケージかを確認します。URL を編集すると下のプレビューは消えるので、画面に残っているものが別のリポジトリについての答えになることはありません。

ステップ 2 — プレビュー

プレビュー はパッケージを取得し、インストールすると何が起きるかを見せます。リポジトリを取りに行くのはブラウザではなくサーバーで、返ってくるのは概要です。

• パッケージ自身の情報 — 名前、説明、そして busabase.json が宣言していればバージョン・作者・ライセンス — に加えて、実際に解決された取得元が owner/repo <ref> 時点 <subdir> 内 の形で示されます。
• 作成される内容 — ノードツリー。各行にアイコン・名前・slug が並び、Base には フィールド N 件 · レコード N 件、スキル・AirApp・drive には ファイル N 件 が付きます。その下に合計が出ます。フォルダ · ドキュメント · Base · レコード · ファイル。
• すでに使われている名前 — 既存の内容と衝突する slug のすべて。リネームが有効なら、実際にどの slug でインストールされるかも表示されます。
• 確認しておくこと — CLI が表示するのと同じ警告(スキップされたバイナリ、破棄された添付の値など)。

プレビューの下に 3 つのオプションがあります。

プレビューを飛ばす方法はありません。プレビューが画面に出るまで インストール ボタンは存在しません。CLI では --dry-run は任意ですが、ダッシュボードではこれが唯一の入口です。

未解決の衝突が残っている間、またはレビューなしでしかインストールできないパッケージでチェックが外れている間、インストール ボタンは無効のままです。後者の場合は赤い このパッケージはレビューなしでしかインストールできません という通知が理由を説明し、行き止まりにせずチェックボックスを指し示します。

ステップ 3 — 結果

実行中はスピナーと「少し時間がかかることがあります。項目は 1 つずつ作成されます。」が表示されます。プログレスバーはなく、項目は 1 つずつ作成されます。

終わるとダイアログは <フォルダ> にインストールしました と、作成された件数 — フォルダ · Base · ビュー · ドキュメント · レコード · ファイル — に置き換わります。そして肝心なのはここからです。

• 保留があれば 「N 件の変更リクエストが待っています」 と、受信トレイへ直接飛ぶ 今すぐレビューする リンクが出ます。パッケージの内容は提案された状態で、まだ反映されていません。
• レビューせずにそのままインストールする にチェックしていた場合は 「すべてマージされました。パッケージはスペースで有効になっています。」 と表示されます。

完了 でダイアログを閉じ、ダッシュボードを再読み込みします。構造は即座に作成されるため、レコードがすべてレビュー待ちであってもツリーは変わっています。

うまくいかなかった場合、ダイアログは汎用のエラーではなくサーバー自身のメッセージをそのまま表示します — 「Not a Busabase package — expected busabase.json at …」、ホスト拒否のメッセージ、ロール不足のメッセージ。役に立つのはまさにその文言なので、そのまま見せています(これらはサーバーのメッセージで、UI の言語に合わせて翻訳されることはありません)。

コマンドラインからインストールする

npx busabase-cli install https://github.com/acme/support-kb-template

まず --dry-run から始めてください。正確なノードツリー、Base ごとのレコード件数、すべての衝突を表示し、何も作成しません。プライベートリポジトリからインストールする場合は GITHUB_TOKEN を設定します。

ダッシュボードか CLI か

どちらも同じインストールを実行します。同じパッケージ形式、同じ計画、同じ 5 パスの apply、同じ承認優先の分割です。違いは選ぶ前に知っておく価値があります。

実際上の影響はこうです。Busabase Cloud では、運用者がトークンを設定していない限りプライベートリポジトリをダッシュボードからインストールできません。その場合は自分のトークンを使う CLI を使ってください。また export にはダッシュボードの対応機能がまったくありません。これは CLI コマンドです。

URL がバージョンの固定になる

任意の git ref が使えます — ブランチ、タグ、コミット SHA のいずれでも。再インストールする予定のもの、チームメイトに渡すものにはタグを使ってください。知らないうちに中身が変わらない唯一の形式です。

ノードをパッケージとしてエクスポートする

エクスポートは CLI のみで、ダッシュボードに対応機能はありません。

npx busabase-cli export support-kb -o ./support-kb-template

指定したノード自身がパッケージになり、その子ノードが content/ 配下に置かれます:

busabase.json
content/getting-started.md
content/cms/_folder.json
content/cms/blog/base.json
content/cms/blog/records.ndjson
content/cms/agent-integrations/base.json
content/pdf-summarizer/_node.json
content/pdf-summarizer/SKILL.md

どのファイルも人が読むためのものです。ドキュメントは YAML frontmatter 付きの本物の .md、base.json は Base のフィールドとビュー、records.ndjson は 1 行 1 つの JSON オブジェクト(値は slug をキーとする)、スキルや AirApp 自身のファイルはそのまま格納されます。push すればインストール可能になります:

cd ./support-kb-template
git init && git add . && git commit -m "Add support-kb package"
git remote add origin https://github.com/acme/support-kb-template.git && git push -u origin main

出力は決定的です。space が変わっていなければ 2 回エクスポートしてもバイト単位で同一のファイルが得られるため、GitHub の diff は変更点を正確に示します — レコードを 1 件編集すれば、変わるのは 1 行だけです。再エクスポート時はまず content/ をクリーンにするので、削除したノードのファイルがリポジトリに残り続けることはありません。busabase.json に手で追記した内容(version、author、license、tags)は再エクスポートしても保持されます。

レビューを飛ばすのは作者を信頼するということ

事前に知っておくべき制限

• レコードが relation の値を持つパッケージは、レビューなしでしかインストールできません。 CLI は理由を示して事前に拒否し、--auto-merge を付けて再実行するよう促します。ダッシュボードは同じ判断を、チェックボックスを指し示す通知として表示します。理由はどちらも同じです:relation は自分が指すレコードの id を保持しますが、その id はレコードがマージされて初めて存在するため、承認優先のままインストールすると relation がすべて空になってしまうからです。これを引き起こすのは実際の値だけです。relation フィールドを定義しているだけで、まだ何も紐づいていない Base は、ほかの内容と同じく承認優先でインストールできます。
• 絶対 URL でないアップロード URL を返すホストでは、バイナリファイルはスキップされます — 典型的にはローカルファイルシステムストレージを使う自己ホスト環境で、そのアップロード URL は自身の Web UI しか扱い方を知りません。install は警告してファイル名を示し、それ以外はすべてインストールします。S3/R2/MinIO を使うホスト(Cloud を含む)では通常どおりアップロードされます。また、スキル・AirApp・drive の内部に含まれるテキスト(markdown、JSON、SVG)はアップロードではなくインライン展開されるため、どちらのホストでも影響を受けません。
• 同じパッケージを 1 つの space に 2 回インストールすることはできません。 Base の slug は space 内で一意、ノードの slug はフォルダ内で一意なので、2 回目は計画段階で衝突した slug を列挙して失敗します。--rename — ダッシュボードでは 衝突した項目を別名でインストールする — が逃げ道です — -2、-3 としてインストールし、すべての relation をリネーム後の Base に向け直します。

設定

これは busabase-cli にのみ関係します。ダッシュボードはどのホストのどの space にいるかをすでに把握しており、あなた自身として認証されます。busabase-cli の他の場面と同じ優先順位です:

install/export がホストに接続できない、または 401/403 が返る場合はトラブルシューティングを参照してください。

関連ページ:ノードタイプ · Change Requests · バックアップと復元 · トラブルシューティング