> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# バージョニングと公開

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

## 公開ワークフロー

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

    ```bash theme={null}
    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..." } }'
    ```
  </Step>

  <Step title="新しいVersionを公開する">
    ドラフトの準備ができたら、semverバージョン番号とオプションのリリースノートを指定して公開します：

    ```bash theme={null}
    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を使用：

    ```typescript theme={null}
    const version = await client.publishVersion("slack-tools", {
      version: "1.3.0",
      releaseNotes: "Added thread reply support",
    });
    ```
  </Step>

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

    ```bash theme={null}
    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" }'
    ```

    変更は即座に反映されます。
  </Step>

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

## Versionの解決

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

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

```bash theme={null}
# 公開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を以前のものに変更するだけです：

```bash theme={null}
# 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は完全なスナップショットを保存します：

```typescript theme={null}
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を通じて実行履歴を取得できます：

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

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

## ベストプラクティス

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

## 関連ドキュメント

* [REST API](/ja/pages/toolbox/developer/api) -- Versionルートを含む完全なエンドポイントリファレンス
* [SDK](/ja/pages/toolbox/developer/sdk) -- プログラムによるVersion管理
* [セキュリティとアクセス制御](/ja/pages/toolbox/advanced/security) -- Versionを公開できるユーザー