インストールとエクスポート(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 でレビューできます。

インストールでは構造とコンテンツを分けます。フォルダ、Base、フィールド、ビューはすぐに作成されます。ブラウザも CLI も、書き込み権限があればレコード、ドキュメント、Skill、AirApp などを直接マージします。先に確認するには、ブラウザで 先にレビューに回す を選ぶか、CLI に --require-review を付け、変更リクエストとして残します。テンプレートのサンプルレコードは標準で別途マージされます。

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

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

インストールにはワークスペースへの書き込み権限が必要です。 プレビューとインストールの両方でサーバーが確認します。owner・admin・member はインストールでき、viewer はできません。API キーにも書き込みレベルが必要です。セルフホストのシングルユーザー環境では、標準で管理権限があります。

ステップ 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)は再エクスポートしても保持されます。

インストールすることが信頼の判断

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

• 通常のパッケージでレコードがリレーションの値を持つ場合、インストール中にレコードをマージする必要があります。 CLI では --require-review を外します。ブラウザは理由を説明し、レビュー用のチェックボックスを表示しません。参照先 id はレコードのマージ後に存在するためです。フィールドを定義しただけで値がなければ、この要件は発生しません。テンプレートは標準でサンプルを別途マージするため、サンプル間のリレーションだけでアプリのコードとマニュアルのレビューを省略する必要は通常ありません。
• 絶対 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 · バックアップと復元 · トラブルシューティング