mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-11-03 22:32:27 +08:00
Add 'docs/' from commit '51dddcb3f891d60bc38645e88b2dbd515344da81'
git-subtree-dir: docs git-subtree-mainline:0582d1b3d4git-subtree-split:51dddcb3f8
This commit is contained in:
RockChinQ
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "AI アシスタント開発コンテキスト"
|
||||
description: "AI コーディングアシスタントにページ全体をそのままコピー＆ペーストできる LangBot のコンテキスト：ディレクトリ構成、コンポーネントの構成方法、実行時の接続関係、開発環境のセットアップ。"
|
||||
---
|
||||
|
||||
<Info title="このページは AI コーディングアシスタント（Claude Code / Cursor / Copilot / Codex など）向けです。">
|
||||
このページの**すべての内容**をコピーして AI アシスタントに貼り付けてください。そうすれば、LangBot の全体アーキテクチャ、各コンポーネントの構成方法、実行時の接続関係、開発環境の設定方法を、あなたが逐一説明しなくても把握できます。
|
||||
</Info>
|
||||
|
||||
このページは各リポジトリのルートにある `AGENTS.md`（`CLAUDE.md` はそのシンボリックリンク）と内容を一致させており、LangBot プロジェクトの開発者および AI アシスタント向け「1 ページ入門」です。
|
||||
|
||||
## プロジェクト概要
|
||||
|
||||
LangBot はオープンソースの LLM ネイティブなインスタントメッセージングボット開発プラットフォームです。すぐに使える IM ボット開発体験を提供し、Agent、RAG、MCP などの LLM アプリケーション機能を内蔵し、世界の主要 IM プラットフォームに対応し、カスタム開発のための豊富な API を提供します。
|
||||
|
||||
LangBot は充実した Web フロントエンドを備えており、ほぼすべての操作をフロントエンドから行えます。
|
||||
|
||||
- **バックエンド**：Python（`>=3.11,<4.0`）、依存関係は `uv` で管理。Web フレームワークは Quart（Flask の非同期版）。HTTP API とビルド済みフロントエンドはいずれもバックエンドが `http://127.0.0.1:5300` で提供します。
|
||||
- **フロントエンド**：`web/` は **Vite + React Router 7 + shadcn/ui + Tailwind CSS** の SPA で、`pnpm` で管理します（注意：Next.js では**ありません**。`dev` スクリプトは `vite` です）。
|
||||
- **プラグインシステム**：プラグイン SDK、CLI（`lbp`）、プラグインランタイム、Box（サンドボックス）ランタイム、および LangBot とプラグインで共有されるエンティティ/API 定義は、すべて別リポジトリ [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk) にあります。LangBot は `pyproject.toml` でバージョン固定した `langbot-plugin` パッケージを通じて依存します。
|
||||
|
||||
## リポジトリ構成
|
||||
|
||||
```
|
||||
LangBot/
|
||||
├── main.py # エントリーシム -> langbot.__main__.main()
|
||||
├── pyproject.toml # Python プロジェクト + 依存（uv）、langbot-plugin==<x.y.z> を固定
|
||||
├── src/langbot/
|
||||
│ ├── __main__.py # 実際のエントリーポイント、CLI 引数（--standalone-runtime / --standalone-box / --debug）
|
||||
│ ├── pkg/ # コアバックエンドパッケージ
|
||||
│ │ ├── api/ # HTTP API コントローラ + サービス（Quart）
|
||||
│ │ ├── core/ # アプリ起動、ステージ、タスクマネージャ
|
||||
│ │ ├── platform/ # IM プラットフォームアダプタ、ボット管理、セッション管理
|
||||
│ │ ├── provider/ # LLM プロバイダ、リクエスタ、ツールプロバイダ
|
||||
│ │ ├── pipeline/ # パイプライン、ステージ、クエリプール
|
||||
│ │ ├── plugin/ # プラグインランタイムへのブリッジ（connector.py / handler.py）
|
||||
│ │ ├── box/ # コードサンドボックスサブシステム（Docker / nsjail / E2B バックエンド）
|
||||
│ │ ├── skill/ # スキルサブシステム
|
||||
│ │ ├── rag/ , vector/ # RAG とベクトルストア
|
||||
│ │ ├── command/ # 組み込みコマンド
|
||||
│ │ ├── persistence/ # ORM モデル + Alembic マイグレーション（SQLite & PostgreSQL）
|
||||
│ │ ├── storage/ # オブジェクト/ファイルストレージ抽象
|
||||
│ │ ├── config/, entity/, discover/, utils/, telemetry/, survey/
|
||||
│ ├── libs/ # 同梱 SDK（qq_official_api、wecom_api など）
|
||||
│ └── templates/ # 設定/コンポーネントテンプレート（例：templates/config.yaml）
|
||||
├── web/ # フロントエンド SPA（Vite + React Router 7 + shadcn + Tailwind）
|
||||
└── docker/ # docker-compose デプロイファイル
|
||||
```
|
||||
|
||||
## コンポーネントの構成方法
|
||||
|
||||
コアバックエンドパッケージ `src/langbot/pkg/` は責務ごとに疎結合なサブモジュールに分割されています：
|
||||
|
||||
| モジュール | 責務 |
|
||||
| --- | --- |
|
||||
| `core` | アプリケーションのライフサイクル：起動ステージが設定読み込み・DB 接続・各サブシステムの起動を順に行い、バックグラウンドタスクを管理。 |
|
||||
| `platform` | 各 IM プラットフォーム（Discord、Telegram、QQ、WeCom、Lark など）のアダプタ。メッセージ送受信、ボットとセッションの管理。 |
|
||||
| `provider` | LLM プロバイダとリクエスタ（OpenAI 互換および各社ネイティブ API）、Agent が呼び出すツールプロバイダ。 |
|
||||
| `pipeline` | メッセージ処理パイプライン：1 つのメッセージをトリガー・AI 処理・出力・安全の各ステージに通す。 |
|
||||
| `plugin` | LangBot 本体とプラグインランタイム間のブリッジ。接続・アクション送受信・イベント転送。 |
|
||||
| `box` | コードサンドボックスサブシステム。スキル/ツールに隔離されたコード実行環境を提供し、可用性に応じて Docker / nsjail / E2B を選択。 |
|
||||
| `skill` / `rag` / `vector` | スキル、検索拡張生成、ベクトルストアの機能。 |
|
||||
| `persistence` | ORM エンティティ定義と Alembic マイグレーション。単一のスクリプトセットで SQLite と PostgreSQL の両方に対応。 |
|
||||
|
||||
プラグイン側のコンポーネント（`langbot-plugin-sdk` で定義、`lbp comp` で生成）は 1 つの `BasePlugin` を中心に構成されます。現在 6 種類のコンポーネントに対応しています：
|
||||
|
||||
- **Command**：ユーザーが能動的に起動するコマンド（例：`!weather tokyo`）。
|
||||
- **Tool**：LLM が Agent 実行中に呼び出す関数（例：天気取得、データベース照会）。
|
||||
- **EventListener**：メッセージパイプライン中のイベントを監視するハンドラ（例：自動返信、コンテンツフィルタ）。
|
||||
- **KnowledgeEngine**：RAG が利用する、カスタムナレッジベースの検索/接続実装。
|
||||
- **Parser**：メッセージ/コンテンツのカスタム解析処理。
|
||||
- **Page**：プラグインが提供するカスタム Web ページ。LangBot 管理パネルに組み込めます。
|
||||
|
||||
各プラグインは独立したプロセスで実行され、プラグインランタイムがライフサイクルを統一管理します（発見 → 依存インストール → ロード → 初期化 → コンポーネント登録 → 準備完了 → 終了）。
|
||||
|
||||
## 実行時の接続関係
|
||||
|
||||
```
|
||||
┌──────────────┐ HTTP/API ┌──────────────┐
|
||||
│ ブラウザ/Web │ ────────────► │ │
|
||||
│ (Vite SPA) │ :3000/同一 │ LangBot │
|
||||
└──────────────┘ オリジン │ バックエンド │
|
||||
│ (Quart) │
|
||||
┌───────────────────────────┤ :5300 ├─────────────────────────┐
|
||||
│ stdio または WebSocket └──────────────┘ stdio または WebSocket │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ プラグイン │ 独立プロセス、 │ Box │ コードサンドボックス
|
||||
│ ランタイム │ 各プラグインを起動 │ ランタイム │ Docker/nsjail/E2B
|
||||
│ :5400 / :5401│ │ :5410 │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
- **フロントエンド ↔ バックエンド**：開発時はフロントエンドが `:3000` で単独動作し、`web/.env` の `VITE_API_BASE_URL` を通じてバックエンド `:5300` にアクセス。本番ではフロントエンドが静的ファイルにビルドされ、バックエンドが同一オリジンで提供します。
|
||||
- **バックエンド ↔ プラグインランタイム**：
|
||||
- LangBot を**直接起動**した場合（コンテナ外）、バックエンドが自らランタイムを**起動**し、**stdio** で通信します（軽量/個人向け）。stdio は**自動再接続できません**——切断後は LangBot の再起動が必要です。よくある障害は、前のバックエンドが残した**孤児ランタイムプロセス**が `5400`/`5401` を占有しているケースで、それを kill して再起動します。
|
||||
- LangBot を**コンテナ**で実行する場合、**WebSocket** で独立したランタイムに接続します（本番向け）。制御ポートは既定 `5400`、デバッグポートは `5401`。設定：`data/config.yaml` の `plugin.runtime_ws_url`（例：`ws://langbot_plugin_runtime:5400/control/ws`）。
|
||||
- **バックエンド ↔ Box ランタイム**：Box サブシステムは制御チャネル（既定ポート `5410`）で Box ランタイムに接続し、ランタイムが Docker / nsjail / E2B でサンドボックスコードを実行します。設定（`data/config.yaml` の `box:` セクション）：`box.enabled`（マスタースイッチ）、`box.backend`（`'local'`/`'docker'`/`'nsjail'`/`'e2b'`）、`box.runtime.endpoint`（外部 Box ランタイムの URL、例：`ws://127.0.0.1:5410`、空なら ローカル自動管理）。プラグインランタイムと同様、このエンドポイントを設定し `--standalone-box` で起動すると外部 Box ランタイムに接続できます。
|
||||
- ランタイム・CLI・SDK のデバッグ方法の詳細は[「プラグインランタイム、CLI、SDK のデバッグ」](/ja/develop/plugin-runtime)を参照。詳細なフラグとアーキテクチャは `langbot-plugin-sdk` リポジトリの `AGENTS.md` にあります。
|
||||
|
||||
## 開発環境のセットアップ
|
||||
|
||||
詳細は[「開発設定」](/ja/develop/dev-config)を参照。要点：
|
||||
|
||||
### バックエンド
|
||||
|
||||
```bash
|
||||
pip install uv
|
||||
uv sync --dev # uv が .venv/ を自動作成。エディタのインタプリタをそこに向ける
|
||||
uv run main.py # http://127.0.0.1:5300 で API + フロントエンドを提供
|
||||
```
|
||||
|
||||
初回起動時に設定ファイルが `data/config.yaml` に生成されます。既定は SQLite（設定不要）で、PostgreSQL にも対応。マイグレーションは起動時に自動実行されます。
|
||||
|
||||
### フロントエンド
|
||||
|
||||
Node.js と [pnpm](https://pnpm.io/ja/installation) が必要です。
|
||||
|
||||
```bash
|
||||
cd web
|
||||
cp .env.example .env # Windows: copy .env.example .env
|
||||
pnpm install
|
||||
pnpm dev # http://127.0.0.1:3000（npm install / npm run dev も可）
|
||||
```
|
||||
|
||||
`pnpm dev` は `web/.env` の `VITE_API_BASE_URL` を読み込み、開発時のフロントエンドがバックエンド `:5300` にアクセスできるようにします。
|
||||
|
||||
### コードフォーマット
|
||||
|
||||
CI で lint + format チェックが走ります。pre-commit フックをインストールして、同じチェックを各コミット前にローカルで実行してください：
|
||||
|
||||
```bash
|
||||
uv run pre-commit install
|
||||
```
|
||||
|
||||
### データベースマイグレーション
|
||||
|
||||
ORM モデルを変更したらマイグレーションを生成します：
|
||||
|
||||
```bash
|
||||
# プロジェクトルートで実行（data/config.yaml が必要）
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "変更内容の説明"
|
||||
```
|
||||
|
||||
`autogenerate` はスキーマ変更（列・テーブルの追加/削除、型変更）を検出しますが、**データマイグレーション**（JSON フィールドの内容変更など）は生成スクリプトに手書きする必要があります。`env.py` で `render_as_batch=True` が設定されており、SQLite の ALTER TABLE 制限が自動処理されるため、データベース種別ごとの分岐は不要です。マイグレーションは起動時に自動実行されます。
|
||||
|
||||
## 開発規約
|
||||
|
||||
- LangBot はグローバルなプロジェクトです：**すべてのコードコメントと docstring は英語**で、ユーザー向けの文字列はすべて **i18n** に対応する必要があります（最低限 `en_US` + `zh_Hans`、リポジトリに日本語がある箇所は `ja_JP` も）。
|
||||
- LangBot は toC・toB の両シナリオで採用されているため、常に互換性とセキュリティを考慮してください。
|
||||
- **コミットメッセージ形式**：`<type>(<scope>): <subject>`
|
||||
- `type`：`feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`chore` など。
|
||||
- `scope`：影響を受けるパッケージ/モジュール/ファイル/クラス。
|
||||
- `subject`：変更内容の簡潔な説明。
|
||||
|
||||
## Agent 向けの機能（MCP + スキル）
|
||||
|
||||
LangBot は設計上**AI エージェントに優しく**、HTTP API と厳密に整合した 3 つの
|
||||
Agent 向けサーフェスを提供します:
|
||||
|
||||
1. **MCP サーバー**: `src/langbot/pkg/api/mcp/` が `/mcp` で API の厳選サブセットを
|
||||
MCP ツールとして公開します（API キー認証、config.yaml の `api.global_api_key`
|
||||
を含む）。`server.py` がツールを定義し（service 層を直接呼び出す）、`mount.py`
|
||||
が ASGI ディスパッチャです。
|
||||
2. **リポジトリ内スキル**: `skills/` ディレクトリは LangBot の全 Agent スキル
|
||||
（プラグイン開発、コア開発、デプロイ、e2e、MCP 操作など）の**唯一の信頼できる
|
||||
情報源**です。ドキュメントとランディングページは内容を複製せず、ここへリンク
|
||||
します。
|
||||
3. **API キー認証**: `api.global_api_key`（config.yaml）はログインセッションなしで
|
||||
API と MCP を認証します。`docs/API_KEY_AUTH.md` を参照してください。
|
||||
|
||||
> **メンテナンスルール（重要）**: Agent からアクセス可能であるべき HTTP API
|
||||
> エンドポイントを追加・削除・変更する際は、`src/langbot/pkg/api/mcp/server.py`
|
||||
> の対応する MCP ツール**と** `skills/` 配下の関連スキル（特に
|
||||
> `skills/skills/langbot-mcp-ops`）の**両方**を必ず更新してください。API・MCP
|
||||
> ツール群・スキルは一つのシステムであり、ずれはバグです。
|
||||
|
||||
## いくつかの原則
|
||||
|
||||
- Keep it simple, stupid.
|
||||
- 必要がなければエンティティを増やさない。
|
||||
- 八荣八耻（八つの栄誉と八つの恥）：
|
||||
|
||||
以瞎猜接口为耻，以认真查询为荣。
|
||||
以模糊执行为耻，以寻求确认为荣。
|
||||
以臆想业务为耻，以人类确认为荣。
|
||||
以创造接口为耻，以复用现有为荣。
|
||||
以跳过验证为耻，以主动测试为荣。
|
||||
以破坏架构为耻，以遵循规范为荣。
|
||||
以假装理解为耻，以诚实无知为荣。
|
||||
以盲目修改为耻，以谨慎重构为荣。
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: "コンポーネントアーキテクチャ"
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "開発設定"
|
||||
---
|
||||
|
||||
LangBotはフロントエンドとバックエンドに分かれています。フロントエンドはVite + React Router + shadcnを使用して開発され、バックエンドはQuart(Flaskの非同期版)を使用して開発されています。
|
||||
|
||||
## バックエンド
|
||||
|
||||
コードは`pkg`ディレクトリにあり、ルートディレクトリの`main.py`ファイルによって起動されます。
|
||||
|
||||
依存関係をインストールします。依存関係の管理にはuvを使用します。
|
||||
|
||||
```bash
|
||||
pip install uv
|
||||
uv sync --dev
|
||||
```
|
||||
|
||||
バックエンドを起動します
|
||||
|
||||
```bash
|
||||
uv run main.py
|
||||
```
|
||||
|
||||
この時点で、設定ファイルは`data/config.yaml`ファイルに自動的に生成されます。
|
||||
|
||||
## フロントエンド
|
||||
|
||||
コードは`web`ディレクトリにあり、Node.jsと[pnpm](https://pnpm.io/installation)が必要です。
|
||||
|
||||
`.env.example`を`.env`にコピーして、値を入力します。
|
||||
|
||||
- Linuxおよびその他の環境での使用
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
- Windows環境での使用
|
||||
|
||||
```bash
|
||||
copy .env.example .env
|
||||
```
|
||||
|
||||
依存関係をインストールしてフロントエンドを起動します
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
|
||||
# pnpmがインストールされていない場合は、npmを使用して依存関係を解決して起動することもできます
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
その後、出力情報に従って、`http://127.0.0.1:3000`にアクセスして、スタンドアロンフロントエンドページを表示します。
|
||||
|
||||
<Info title="`pnpm dev`を使用してローカルで起動すると、環境変数`VITE_API_BASE_URL`がフロントエンドによって自動的に使用され、フロントエンドがローカルで実行中のバックエンドの`5300`ポートにアクセスできるようになります。">
|
||||
|
||||
本番環境では、フロントエンドは静的ファイルにプリコンパイルされ、バックエンドによって提供され、フロントエンドは同じドメインのバックエンドアドレスに自動的にアクセスします。
|
||||
</Info>
|
||||
|
||||
## コードフォーマット
|
||||
|
||||
リポジトリにはlintとformatのチェックワークフローが含まれており、コードをプッシュすると自動的にチェックされます。pre-commitを設定して、コードをローカルで事前にチェックしてください。
|
||||
|
||||
```bash
|
||||
uv run pre-commit install
|
||||
```
|
||||
|
||||
## APIドキュメント
|
||||
|
||||
各インターフェースを開発する前に、APIFoxでAPIドキュメントを作成します。[APIドキュメント(中国語)](https://ok52vhsenr.apifox.cn/)を参照してください。
|
||||
|
||||
## データベースマイグレーション
|
||||
|
||||
LangBotは[Alembic](https://alembic.sqlalchemy.org/)を使用してデータベースマイグレーションを管理しており、SQLiteとPostgreSQLの両方をシームレスにサポートします。データベース固有の分岐コードは不要です。
|
||||
|
||||
### マイグレーションファイルの場所
|
||||
|
||||
```
|
||||
src/langbot/pkg/persistence/alembic/versions/
|
||||
```
|
||||
|
||||
### 新しいマイグレーションの作成
|
||||
|
||||
**autogenerate** を使用してマイグレーションスクリプトを自動生成することを推奨します。ORMモデルとデータベーススキーマの差分を比較して生成します：
|
||||
|
||||
```bash
|
||||
# プロジェクトルートで実行（data/config.yaml が必要）
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "変更内容の説明"
|
||||
```
|
||||
|
||||
生成されたファイルは `src/langbot/pkg/persistence/alembic/versions/` に作成されます。生成されたスクリプトを確認・編集し、変更が正しいことを確認してからコミットしてください。
|
||||
|
||||
<Info>
|
||||
autogenerateは列の追加/削除、テーブルの変更、型の変更などを自動検出できます。ただし、**データマイグレーション**（JSONフィールドの内容変更など）は、生成されたスクリプトに手動でコードを追加する必要があります。
|
||||
</Info>
|
||||
|
||||
手動でマイグレーションファイルを作成することもできます。命名規則 `NNNN_description.py` に従ってください：
|
||||
|
||||
```python
|
||||
"""マイグレーションの説明
|
||||
|
||||
Revision ID: 0003_add_bot_description
|
||||
Revises: 0002_sample
|
||||
Create Date: 2026-04-08
|
||||
"""
|
||||
from alembic import op
|
||||
import sqlalchemy as sa
|
||||
|
||||
revision = '0003_add_bot_description'
|
||||
down_revision = '0002_sample' # 前のマイグレーションのrevisionを指定
|
||||
branch_labels = None
|
||||
depends_on = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
# スキーマ変更（SQLiteとPostgreSQLの両方で動作）
|
||||
op.add_column('bots', sa.Column('description', sa.String(512), server_default=''))
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.drop_column('bots', 'description')
|
||||
```
|
||||
|
||||
### マイグレーションパターン
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="スキーマ変更（列の追加/削除、テーブル作成）">
|
||||
```python
|
||||
def upgrade() -> None:
|
||||
# 列を追加
|
||||
op.add_column('table_name', sa.Column('new_col', sa.String(255), server_default=''))
|
||||
|
||||
# 新しいテーブルを作成
|
||||
op.create_table(
|
||||
'new_table',
|
||||
sa.Column('id', sa.Integer, primary_key=True, autoincrement=True),
|
||||
sa.Column('name', sa.String(255), nullable=False),
|
||||
)
|
||||
```
|
||||
|
||||
<Info>
|
||||
`env.py`で`render_as_batch=True`が設定されているため、AlembicはSQLiteのALTER TABLE制限を自動的に処理します（一時テーブルによる再構築）。データベースタイプによる分岐は不要です。
|
||||
</Info>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="データマイグレーション（データの読み取りと変更）">
|
||||
```python
|
||||
import json
|
||||
|
||||
def upgrade() -> None:
|
||||
conn = op.get_bind()
|
||||
rows = conn.execute(sa.text("SELECT uuid, config FROM pipelines")).fetchall()
|
||||
for row in rows:
|
||||
config = json.loads(row[1]) if isinstance(row[1], str) else row[1]
|
||||
config.setdefault('ai', {})['new_key'] = 'default_value'
|
||||
conn.execute(
|
||||
sa.text("UPDATE pipelines SET config = :cfg WHERE uuid = :uuid"),
|
||||
{"cfg": json.dumps(config), "uuid": row[0]}
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 動作の仕組み
|
||||
|
||||
マイグレーションはLangBot起動時に自動的に実行されます。手動コマンドは不要です：
|
||||
|
||||
1. 初回起動時、ベースラインバージョンが自動的にスタンプされます（既存データベースのマーキング）
|
||||
2. 以降の起動時、未適用のすべてのマイグレーションが適用されます（`alembic upgrade head`）
|
||||
|
||||
### CIテスト
|
||||
|
||||
リポジトリには`test-migrations.yml`ワークフローが含まれており、`persistence/`関連ファイルが変更された際に、SQLiteとPostgreSQLの両方でマイグレーションスクリプトが自動テストされます。
|
||||
|
||||
### CLIツール
|
||||
|
||||
```bash
|
||||
# マイグレーションを自動生成（ORMモデルとDBの差分を比較）
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "説明"
|
||||
|
||||
# データベースをアップグレード
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner upgrade
|
||||
|
||||
# 現在のリビジョンを表示
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner current
|
||||
|
||||
# リビジョンをスタンプ（マイグレーションを実行せず）
|
||||
uv run python -m langbot.pkg.persistence.alembic_runner stamp head
|
||||
```
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: "プラグインランタイム、CLI、SDKのデバッグ"
|
||||
---
|
||||
|
||||
<Info>
|
||||
プラグインランタイム、CLI、SDKはこちらでオープンソース化されています: https://github.com/langbot-app/langbot-plugin-sdk
|
||||
</Info>
|
||||
|
||||
LangBotはlangbot-plugin-sdkで定義されたエンティティに依存するため、新しいディレクトリでVS Codeを開き、LangBotとlangbot-plugin-sdk（git clone https://github.com/langbot-app/langbot-plugin-sdk）をサブディレクトリとして配置することをお勧めします。ディレクトリ構造は以下の通りです：
|
||||
|
||||
```bash
|
||||
langbot-projects
|
||||
├── LangBot
|
||||
├── langbot-plugin-sdk
|
||||
```
|
||||
|
||||
LangBotディレクトリに移動し、依存関係をインストールします：
|
||||
|
||||
```bash
|
||||
cd LangBot
|
||||
uv sync --dev
|
||||
```
|
||||
|
||||
この時点で、uvは自動的に仮想環境(.venv)を作成します。エディターがこの仮想環境を使用するかどうかを尋ねる場合は、`Yes`を選択してください。
|
||||
|
||||
<img
|
||||
width="600"
|
||||
src="/images/zh/develop/confirm_venv.png"
|
||||
/>
|
||||
|
||||
プロンプトが表示されない場合は、右下隅からPythonインタープリターのパスをvenv内のインタープリターに手動で設定してください。
|
||||
|
||||
次に、VS Code下部のターミナルを開きます。これにより自動的にvenvがアクティブ化されます。
|
||||
|
||||
または、この仮想環境を手動でアクティブ化できます：
|
||||
|
||||
```bash
|
||||
# .venvのパスに応じてコマンドを変更してください
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
## プラグインランタイムの起動
|
||||
|
||||
```bash
|
||||
python -m langbot_plugin.cli.__init__ rt
|
||||
```
|
||||
|
||||
プラグインランタイムは以下のパラメーターを受け入れます:
|
||||
|
||||
- `--debug-only`: `data/plugins`ディレクトリのプラグインを起動せず、デバッグ接続を通じたプラグインの読み込みのみを許可します。
|
||||
- `--ws-debug-port`: リッスンするデバッグポート、デフォルトは`5401`です。
|
||||
- `--ws-control-port`: リッスンする制御ポート(LangBotメインプログラム接続用)、デフォルトは`5400`です。
|
||||
- `-s`: `stdio`を使用して制御接続を受け入れます。**本番環境でのみ使用してください**。
|
||||
- `--skip-deps-check`: すべてのプラグイン依存関係がインストールされていることを確認するため、ランタイムは起動時に毎回すべてのインストール済みプラグインの依存関係をチェックしてインストールします。このパラメーターを使用してこのチェックを無効にします。
|
||||
|
||||
### LangBotでローカル修正したlangbot-plugin-sdkを使用する
|
||||
|
||||
メッセージエンティティやプラグインデータ定義などを変更した場合、実行時のデータ形式の互換性を確保するために、LangBot環境に更新する必要があります。
|
||||
|
||||
**LangBotディレクトリの仮想環境（.venv）がアクティブ化されたターミナル**で、langbot-plugin-sdkディレクトリに移動し、以下を実行します：
|
||||
|
||||
```bash
|
||||
uv pip install .
|
||||
```
|
||||
|
||||
これにより、修正したlangbot-plugin-sdkがLangBotの環境にインストールされます。
|
||||
|
||||
### LangBotをこのランタイムに接続する
|
||||
|
||||
LangBotの`data/config.yaml`で`plugin.runtime_ws_url`を`ws://localhost:5400/control/ws`に設定します。
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
runtime_ws_url: ws://localhost:5400/control/ws
|
||||
```
|
||||
|
||||
LangBot の仮想環境を有効にしたターミナルで、Python を直接使用してメインプログラムを起動し、`--standalone-runtime` を追加します（例：`python main.py --standalone-runtime`）。現在の仮想環境の Python を直接呼び出す場合、依存関係は再同期されないため、インストールしたローカルの langbot-plugin-sdk がリモート版で上書きされることはありません。\
|
||||
LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。
|
||||
|
||||
`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Runtime 側の認証は有効になりません。
|
||||
|
||||
### `lbp run` でプラグインをデバッグする
|
||||
|
||||
Multi-Workspace 版では、デバッグプラグインは `5401` ポートへ到達できるだけでは Runtime に接続できません。Workspace ごとに、有効期限付きの個別デバッグキーが必要です：
|
||||
|
||||
1. 上記の手順で LangBot と Plugin Runtime が起動し、接続済みであることを確認します。
|
||||
2. LangBot WebUI の「プラグイン」ページで「デバッグ情報」を開き、デバッグ URL とデバッグキーをコピーします。この操作には現在の Workspace のリソース管理権限が必要です。
|
||||
3. プラグインプロジェクトの `.env` に設定します：
|
||||
|
||||
```bash
|
||||
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
|
||||
PLUGIN_DEBUG_KEY=<WebUI からコピーしたデバッグキー>
|
||||
```
|
||||
|
||||
4. プラグインプロジェクトのディレクトリで起動します：
|
||||
|
||||
```bash
|
||||
python -m langbot_plugin.cli.__init__ run
|
||||
```
|
||||
|
||||
`.env` に保存せず、`python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<デバッグキー>'` を使用することもできます。キーは Workspace ごとに分離され、有効期限は 2 時間です。期限切れ、Runtime の再起動、または Workspace の切り替え後は WebUI から再取得してください。`DEBUG_RUNTIME_WS_URL` だけを設定したクライアントは拒否されます。
|
||||
|
||||
## Box Runtime を standalone モードで起動する
|
||||
|
||||
Box Runtime の制御接続ルールは Plugin Runtime と同じです。OSS standalone 開発では token は省略可能で、両側で `LANGBOT_BOX_CONTROL_TOKEN` が未設定の場合も接続できます：
|
||||
|
||||
```bash
|
||||
# ターミナル 1：langbot-plugin-sdk ディレクトリ
|
||||
python -m langbot_plugin.cli.__init__ box
|
||||
```
|
||||
|
||||
LangBot の `data/config.yaml` でローカル Box Runtime を指定します：
|
||||
|
||||
```yaml
|
||||
box:
|
||||
enabled: true
|
||||
backend: local
|
||||
runtime:
|
||||
endpoint: ws://127.0.0.1:5410
|
||||
```
|
||||
|
||||
```bash
|
||||
# ターミナル 2：LangBot ディレクトリ
|
||||
python main.py --standalone-runtime --standalone-box
|
||||
```
|
||||
|
||||
公開された 5410 ポートを保護する場合は、両方のプロセスを起動する前に、同じ 32 文字以上で空白を含まない高エントロピー値を設定してください：
|
||||
|
||||
```bash
|
||||
export LANGBOT_BOX_CONTROL_TOKEN='<両側で完全に同じ高エントロピーシークレット>'
|
||||
```
|
||||
|
||||
Box Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Box Runtime 側の認証は有効になりません。明示的に設定した値が 32 文字未満の場合は、引き続き両側で拒否されます。実際の値を設定ファイルや Git にコミットしないでください。
|
||||
|
||||
## langbot-plugin-sdkアーキテクチャ
|
||||
|
||||
このコードベースには以下が含まれています:
|
||||
|
||||
- `langbot_plugin.api`: プラグイン関連のエンティティとAPI定義。
|
||||
- `langbot_plugin.assets`: プラグインテンプレート。
|
||||
- `langbot_plugin.cli`: プラグイン開発CLIツール。
|
||||
- `langbot_plugin.entities`: APIで定義されていないプラグインシステム関連のエンティティ。
|
||||
- `langbot_plugin.runtime`: プラグインランタイムと基礎通信(stdioおよびwebsocket)の実装。
|
||||
|
||||
## `lbp` CLIツール
|
||||
|
||||
CLIツールは、ランタイムの起動、プラグインの初期化、プラグインコンポーネント管理、Marketplaceとのインタラクションなどの機能を提供します。
|
||||
|
||||
詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。
|
||||
Reference in New Issue
Block a user