バージョニングと公開

概要

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は変更されません。

公開ワークフロー

ドラフトを編集する

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..." } }'

新しい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",
});

公開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" }'

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

開発を続ける

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

Versionの解決

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

リクエストボディに version フィールドが含まれている場合、その正確なVersionが使用されます。
それ以外の場合、現在公開されている（アクティブな）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を廃止する前に、依存している利用者がいないことを確認してください。

Docs

バージョニングと公開

概要

コンセプト

ドラフトとVersion

不変のスナップショット

公開ワークフロー

Versionの解決

ロールバック

Version API

Versionデータモデル

使用量の追跡

ベストプラクティス

関連ドキュメント

​概要

​コンセプト

​ドラフトとVersion

​不変のスナップショット

​公開ワークフロー

​Versionの解決

​ロールバック

​Version API

​Versionデータモデル

​使用量の追跡

​ベストプラクティス

​関連ドキュメント

概要

コンセプト

ドラフトとVersion

不変のスナップショット

公開ワークフロー

Versionの解決

ロールバック

Version API

Versionデータモデル

使用量の追跡

ベストプラクティス

関連ドキュメント