バージョニングと公開

Jinba Toolboxがセマンティックバージョニングに基づく不変のToolSetバージョンをどのように管理するかを理解する

​

概要

Jinba Toolboxは、不変のスナップショットを持つsemverベースのバージョニングシステムを採用しています。各ToolSetはドラフト（編集可能な作業コピー）と公開済みVersionの一覧を管理します。公開すると、すべてのToolコード、スキーマ、Sandbox設定を含むToolSetの完全なスナップショットが、変更不可能なVersionとして凍結されます。

この設計により再現性が保証されます。Version 1.0.0 を実行すると、いつどこから呼び出しても常に同じコードが実行されます。

​

コンセプト

​

ドラフトとVersion

ToolSet
├── Draft (editable working copy)
└── Versions (immutable releases)
    ├── v1.2.0 [published]
    ├── v1.1.0
    └── v1.0.0

状態	説明
ドラフト	編集可能な作業コピー。Web UIまたはAPIを通じて変更可能。test エンドポイントでのみ実行可能。
Version	不変のリリース。公開後は変更不可。run エンドポイントで使用される。
公開済み	APIが現在配信しているアクティブなVersion。ToolSetごとに同時に1つの公開Versionのみ。

​

不変のスナップショット

各Versionは、公開時点のToolSetの完全なスナップショットを取得します：

• すべてのToolコードとエントリーポイント
• 入力スキーマと出力スキーマ
• Tool名と説明
• Sandbox設定（プロバイダー、言語、パッケージ、リソース）

これにより、後でドラフトを更新しても、既存のVersionは変更されません。

​

公開ワークフロー

1. ドラフトを編集する

   WebコンソールまたはAPIを通じて、ドラフト内のToolに変更を加えます。テストエンドポイントを使用して動作を検証します：

   curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/tools/post-message/test \
     -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{ "input": { "channel": "#test", "text": "Testing..." } }'
   
2. 新しいVersionを公開する

   ドラフトの準備ができたら、semverバージョン番号とオプションのリリースノートを指定して公開します：

   curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/versions \
     -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{
       "version": "1.3.0",
       "releaseNotes": "Added thread reply support"
     }'
   

   またはSDKを使用：

   const version = await client.publishVersion("slack-tools", {
     version: "1.3.0",
     releaseNotes: "Added thread reply support",
   });
   
3. 公開Versionを設定する

   APIが配信するVersionを選択します。新しく公開されたVersionが自動的にアクティブになるわけではありません。明示的に設定する必要があります：

   curl -X PUT https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
     -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{ "version": "1.3.0" }'
   

   変更は即座に反映されます。

4. 開発を続ける

   公開後もドラフトはそのまま残るため、ライブの公開Versionに影響を与えることなく、次のVersionに向けて反復的に開発を続けられます。

​

Versionの解決

run エンドポイント経由でToolを実行する際、Jinba Toolboxは使用するVersionを以下のように解決します：

1. リクエストボディに version フィールドが含まれている場合、その正確なVersionが使用されます。
2. それ以外の場合、現在公開されている（アクティブな）Versionが使用されます。

# 公開Versionを使用
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" } }'

# 特定のVersionを使用
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" }, "version": "1.2.0" }'

​

ロールバック

ロールバックは、公開Versionを以前のものに変更するだけです：

# v1.2.0に戻す
curl -X PUT https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.2.0" }'

Versionは不変であるため、ロールバック時にデータが失われることはありません。新しいVersionは引き続き利用可能で、いつでも再アクティブ化できます。

​

Version API

メソッド	エンドポイント	説明
GET	/v1/orgs/:orgId/toolsets/:slug/versions	全Versionの一覧
POST	/v1/orgs/:orgId/toolsets/:slug/versions	新しいVersionの公開
GET	/v1/orgs/:orgId/toolsets/:slug/versions/:version	Versionの詳細を取得
PUT	/v1/orgs/:orgId/toolsets/:slug/published-version	アクティブな公開Versionの設定

​

Versionデータモデル

公開された各Versionは完全なスナップショットを保存します：

interface ToolSetVersion {
  id: string;
  toolSetId: string;
  version: string;              // semver文字列（例: "1.3.0"）
  sandbox: SandboxConfig;       // 凍結されたSandbox設定
  tools: ToolSnapshot[];        // 凍結されたTool定義とコード
  releaseNotes?: string | null;
  publishedBy: string;          // 公開者のユーザーID
  publishedAt: string;          // ISO 8601タイムスタンプ
}

interface ToolSnapshot {
  id: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  code: string;
  entrypoint?: string;
}

​

使用量の追跡

Jinba Toolboxは、Versionごとの API呼び出し回数を追跡します。使用統計はWebコンソールで確認するか、APIを通じて実行履歴を取得できます：

const runs = await client.listRuns();
// アプリケーションロジックでVersionごとにフィルタリング

使用量データは、古いVersionを廃止しても安全かどうかを判断するのに役立ちます。

​

ベストプラクティス

• セマンティックバージョニングに従う — 破壊的なスキーマ変更にはメジャーバンプ、新しいToolや機能にはマイナーバンプ、修正にはパッチバンプを使用してください。
• リリースノートを記述する — Version間の変更点をチームが理解するのに役立ちます。
• 公開前にテストする — 不変のVersionを作成する前に、test エンドポイントでドラフトを検証してください。
• MCPの公開ステップを省略しない — MCPエンドポイントはドラフトではなく公開Versionを配信します。
• Versionごとの使用状況を監視する — Versionを廃止する前に、依存している利用者がいないことを確認してください。

​

関連ドキュメント

• REST API — Versionルートを含む完全なエンドポイントリファレンス
• SDK — プログラムによるVersion管理
• セキュリティとアクセス制御 — Versionを公開できるユーザー