> ## 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を理解するための基本用語とドメインモデル

これらのコアコンセプトを理解することで、Jinba Toolbox を効果的に活用し、プラットフォームを自信を持って操作できるようになります。

## 主要な用語

| 用語               | 定義                                                                           | 例                                     |
| ---------------- | ---------------------------------------------------------------------------- | ------------------------------------- |
| **Organization** | ToolSetを所有するチームまたは企業。ユーザーはロール（owner、admin、member）を持つ1つ以上のOrganizationに所属します。 | `acme-corp` -- AIツールのコレクションを共有するチーム   |
| **ToolSet**      | 共有の実行環境を持つ関連ツールのコレクション。npmパッケージやDockerイメージに相当します。Organizationに属します。          | `slack-tools` -- Slack連携ツールのセット       |
| **Tool**         | ToolSet内の個別の実行可能ユニット。入出力スキーマとTypeScriptまたはPythonで記述されたコードを持ちます。              | `post-message` -- Slackチャンネルにメッセージを送信 |
| **Run**          | Toolの1回の実行レコード。入力、出力、ログ、ステータス、実行時間を保存します。                                    | チャンネルとテキストのパラメータで`post-message`を実行    |
| **Version**      | ある時点のToolSetの不変スナップショット。セマンティックバージョニング（semver）を使用します。                        | `1.2.0` -- `slack-tools`の公開リリース       |
| **Sandbox**      | ツールのコードが実行される隔離されたコンテナ環境。安全でない操作がホストシステムに影響するのを防ぎます。                         | PythonツールをRunするE2Bコンテナ                |

## ドメインの関係性

Jinba Toolbox のエンティティは明確な階層で構成されています：

```
Organization
  └── ToolSet
        ├── Tool (1:N)
        ├── Version (1:N)
        └── Run (1:N)
```

* **Organization**は1つ以上の**ToolSet**を含みます。
* **ToolSet**は1つ以上の**Tool**を含み、複数の公開済み**Version**を持てます。
* 各**Run**はToolSet内のToolの1回の実行を記録します。
* **ユーザー**はロールが割り当てられたメンバーシップを通じてOrganizationに所属します。

### エンティティ関係図

```
┌──────────┐
│   User   │
└────┬─────┘
     │
     ├─────1:N─────┐
     │              │
     │         ┌────┴─────┐
     │         │  ApiKey   │
     │         └──────────┘
     │
     └─────N:M─────┐
                    │
        ┌───────────┴───────────┐
        │  OrganizationMember   │  (role: owner / admin / member)
        └───────────┬───────────┘
                    │
        ┌───────────┴───────────┐
        │     Organization      │
        └───────────┬───────────┘
                    │
                   1:N
                    │
        ┌───────────┴───────────┐
        │       ToolSet         │
        └───────────┬───────────┘
                    │
         ┌──────────┼──────────┐
         │          │          │
        1:N        1:N        1:N
         │          │          │
    ┌────┴────┐ ┌───┴───┐ ┌───┴──────┐
    │  Tool   │ │  Run  │ │ Version  │
    └─────────┘ └───────┘ └──────────┘
```

## Organization

Organization はトップレベルの所有単位です。すべてのToolSet、APIキー、課金はOrganizationに属します。

* ユーザーは複数のOrganizationのメンバーになれます。
* 各メンバーシップには**ロール**があります：`owner`、`admin`、`member`。
* APIキーはOrganizationにスコープされ、`read`、`write`、`execute`、`admin`の権限スコープを持ちます。

## ToolSet

ToolSetは、共有のSandbox設定を持つ関連ツールをグループ化します。主なプロパティは以下の通りです：

| プロパティ          | 説明                                                                              |
| -------------- | ------------------------------------------------------------------------------- |
| **Slug**       | Organization内で一意の、URLフレンドリーな識別子                                                 |
| **Sandbox設定**  | 実行環境の定義：プロバイダー（E2BまたはDaytona）、言語（TypeScriptまたはPython）、パッケージ、リソース制限              |
| **Visibility** | アクセス制御：`private`（Organization内のみ）、`public`（誰でも）、`restricted`（特定のOrganizationのみ） |
| **Tags**       | カタログでの検索に使用可能なラベル                                                               |

## Tool

Toolは最小の実行可能ユニットです。各Toolは以下を定義します：

| プロパティ          | 説明                               |
| -------------- | -------------------------------- |
| **Slug**       | ToolSet内で一意の、URLフレンドリーな識別子       |
| **入力スキーマ**     | 実行前に入力を検証するJSON Schema           |
| **出力スキーマ**     | 期待される出力構造を記述するJSON Schema        |
| **Code**       | 実行可能なソースコード（TypeScriptまたはPython） |
| **Entrypoint** | オプションのカスタムエントリポイント関数名            |

入出力スキーマは自動的にバリデーションされます。入力がスキーマに一致しない場合、Sandboxリソースが消費される前に実行が拒否されます。

## Version

Versionは、ToolSetの不変スナップショットです。公開されたVersionは変更できません。

* Versionは**セマンティックバージョニング**に従います（例：`1.0.0`、`1.2.3`）。
* Versionの公開時に、その時点のすべてのTool、スキーマ、コードがキャプチャされます。
* ToolSetの`latestVersion`フィールドは、最新の公開Versionを常に指します。
* AIエージェントや外部の利用者は、安定性のために特定のVersionにピン留めすることを推奨します。

## Run

Runは1回のツール実行を表し、その詳細をすべて記録します：

| フィールド        | 説明                                               |
| ------------ | ------------------------------------------------ |
| **Status**   | `pending`、`running`、`success`、`failed`、`timeout` |
| **Input**    | バリデーション済みの入力パラメータ                                |
| **Output**   | ツールが返す構造化された結果                                   |
| **Logs**     | Sandboxからキャプチャされたstdoutとstderr                   |
| **Duration** | ミリ秒単位の実行時間                                       |
| **Error**    | Runが失敗した場合のエラー詳細                                 |

Runはツール実行の完全な可観測性を提供し、障害のデバッグやパフォーマンスの監視を容易にします。

## Sandbox実行

すべてのツールは隔離されたSandboxコンテナ内で実行されます。Sandboxシステムはプラグイン可能なプロバイダーアーキテクチャで構築されています：

| プロバイダー      | 説明                                    |
| ----------- | ------------------------------------- |
| **E2B**     | 高速起動と幅広い言語サポートを持つクラウドベースのSandbox      |
| **Daytona** | オンプレミス実行が必要なチーム向けのセルフホスト型Sandboxオプション |

Sandboxプロバイダーは、ToolSetレベルで設定されます。ToolSet内のすべてのToolは、言語ランタイム、インストール済みパッケージ、リソース制限を含む同一のSandbox設定を共有します。

## アクセス制御

Jinba Toolbox は複数のレイヤーでアクセス制御を提供します：

* **Organizationメンバーシップ**により、ToolSetの管理やRunの閲覧権限を管理します。
* **ToolSetのVisibility**（`private`、`public`、`restricted`）により、ツールの検索・実行権限を制御します。
* **APIキースコープ**（`read`、`write`、`execute`、`admin`）により、プログラムからのアクセスに対するきめ細かな権限制御を提供します。

## 次のステップ

<CardGroup cols={2}>
  <Card title="クイックスタート" icon="bolt" href="./quickstart">
    ToolSetを作成してツールを実行する
  </Card>

  <Card title="Webコンソール" icon="desktop" href="./console/overview">
    ツール管理のためのWebインターフェースを探索する
  </Card>
</CardGroup>