builtin-tool

組み込みツール作成ガイド

組み込みツールは、エージェントのランタイムから呼び出せるパッケージです。5つの側面があります。

側面	配置場所	対象
マニフェストと型	src/{manifest,types,systemRole}.ts	LLM（ツール仕様とシステムプロンプト）
ExecutionRuntime	src/ExecutionRuntime/	サーバー／デスクトップ／あらゆるランタイムの呼び出し元
Executor	src/client/executor/	フロントエンド（ストア／サービスをラップ）
クライアント UI	src/client/{Inspector,Render,…}/	チャット UI
レジストリ連携	packages/builtin-tools/src/*.ts + src/store/tool/slices/builtin/executors/index.ts	フレームワーク

---

まずはこちらをお読みください

質問	ドキュメント
ファイルはどこにありますか？ 各側面の役割は何ですか？ どのように連携しますか？	architecture.md
ツールの命名、API の設計、マニフェスト、executor、ExecutionRuntime の記述方法は？	tool-design.md
Inspector／Render／Placeholder／Streaming／Intervention／Portal の構築方法は？	ui/

---

このスキルを使用する場面

• 新しい packages/builtin-tool-<name>/ パッケージを作成する
• 既存の組み込みツールに新しい API メソッドを追加する
• ツールの6つのクライアント側 UI のいずれかを構築またはスタイル変更する
• ツールを中央レジストリに登録する
• 「ツールが見つからない／API が見つからない／レンダリングが表示されない／プレースホルダーが停止する」エラーをデバッグする

トップレベルの設計原則

1. lobe-<domain> 識別子は永続的です。 メッセージ履歴に保存されます。名前を変更する場合は、新しい名前とともに従来のエイリアスを残す必要があります（listLocalFiles／searchLocalFiles を listFiles／searchFiles に変更した後も維持されている、packages/builtin-tool-local-system/src/client/Inspector/index.ts の // Legacy aliases エントリーを参照）。最初から正しく決めてください。
2. ApiName は as const オブジェクトです。 TS enum ではありません。BaseExecutor が反復処理するランタイムリストも兼ねています。
3. 3 つの結果フィールドは、それぞれ対象が異なります。
   • content: string → LLM が読み取ります
   • state: Record<…> → UI の pluginState です。結果ドメインのみを含め、すべてのパラメーターをそのまま返してはいけません
   • error: { type, message, body? } → LLM と UI の両方で使います。type は安定したコードです
4. 実行処理とフロントエンドの接続を分離します。
   • src/ExecutionRuntime/ — React や Zustand に依存しない純粋なランタイムです。コンストラクター経由でサービスを受け取ります。新しいロジックの標準的な配置先です。
   • src/client/executor/ — ExecutionRuntime を呼び出す BaseExecutor サブクラスです（フロントエンド専用の場合は、直接データやサービスを保持します）。
5. UI はデフォルトで「何もしない」状態にします。 Inspector は必須です（ヘッダーストリップ）。Render／Placeholder／Streaming／Intervention／Portal は、表示する具体的なものがある場合にのみ追加します。レジストリが空でも問題ありません。
6. スタイルには createStaticStyles + cssVar.* を使います（ランタイムコストゼロ）。実行時の値が本当に必要な場合に限り、createStyles + token を使います。生の antd ではなく、@lobehub/ui のコンポーネントを使ってください。
7. i18n キーは packages/locales/src/default/plugin.ts にあります。 Inspector のタイトルは t('builtins.<identifier>.apiName.<api>') から取得し、引数のストリーミング中にも表示されるようにしてください。
8. 長時間実行される呼び出しが失敗した場合、確認するだけでなく続行できるようにします。 たとえば、callSubAgent が途中で停止したとき、ユーザーが「続けて」と言った場合です。そのため、修正では callSubAgent に任意の subAgentId を追加し、同じサブエージェントのスレッドに新しい指示を追加します。モデルが最初から再試行する前に呼び出す必要がある、新たな「実行を検索する」APIは追加しません。ユーザーがその API を単独で求める場合にのみ、新しい API を追加してください。

---

パッケージのレイアウト（推奨、2026 年以降の規約）

packages/builtin-tool-<name>/
├── package.json
└── src/
    ├── index.ts              # exports manifest + types + systemRole + Identifier (no React, no stores)
    ├── manifest.ts           # BuiltinToolManifest with JSON Schema for every API
    ├── types.ts              # ApiName const + Params/State interfaces per API
    ├── systemRole.ts         # System prompt teaching the model when/how to use the APIs
    ├── ExecutionRuntime/     # ✅ Default home for runtime logic (server- or anywhere-callable)
    │   └── index.ts
    └── client/
        ├── index.ts          # Re-exports for the registries
        ├── executor/         # ✅ Frontend executor — extends BaseExecutor, often delegates to ExecutionRuntime
        │   └── index.ts
        ├── Inspector/        # required — header chip per API
        ├── Render/           # optional — rich result card
        ├── Placeholder/      # optional — skeleton during streaming/execution
        ├── Streaming/        # optional — live output renderer (e.g. RunCommand, WriteFile)
        ├── Intervention/     # optional — approval / edit-before-run UI
        ├── Portal/           # optional — full-screen detail view
        └── components/       # shared subcomponents used by the surfaces above

古いパッケージ（builtin-tool-calculator など）では、引き続き src/client/ と同じ階層に src/executor/ があります。これは従来の構成です。計画的なリファクタリングなしに移動しないでください。 新しいパッケージと、既存のパッケージに追加する新しい API では、上記のレイアウトに従ってください。

package.json の exports マップ：

"exports": {
  ".":                  "./src/index.ts",
  "./client":           "./src/client/index.ts",
  "./executor":         "./src/client/executor/index.ts",
  "./executionRuntime": "./src/ExecutionRuntime/index.ts"
}

---

作成チェックリスト

PR を作成する前に、次の点を確認してください。

• 識別子が lobe-<domain> の形式に従っており、安定している（メッセージ履歴に残る）。
• すべての <Name>ApiName の値について、manifest の api[] エントリー、executor のメソッド、Inspector、i18n の apiName.* キーが揃っている。
• Params インターフェースが JSON Schema と一致し、State インターフェースが executor の戻り値と UI が読み取る内容に一致している。
• システムプロンプトで、混同しやすい API を区別し、バッチ処理版を案内している。
• 実行時ロジックは ExecutionRuntime/ に配置し、client/executor/ はストアやサービスを接続して処理を委譲するだけにする。
• executor は単一の toResult() 経由で { success, content, state, error? } を返し、content は必ず空でない（デフォルト値は error.message）。
• Inspector が isArgumentsStreaming、isLoading、partialArgs、pluginState がない場合に対応している。
• Render はデータが揃うまで null を返し、詳細な結果を持つ API に対してのみ作成されている。
• API の実行に体感できる遅延がある場合（検索、一覧表示、クロール）、プレースホルダーを追加している。
• 増分出力を生成する API（コマンド実行、ファイル書き込み、コード実行）にストリーミングを追加している。
• manifest で humanIntervention が設定されている場合、Intervention を追加している。
• すべてのレジストリファイルを更新している（architecture.md → Registry wiring を参照）。
• i18n キーを packages/locales/src/default/plugin.ts に追加し、開発用シードを en-US／zh-CN に追加している。
• bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>' が成功する。
• bun run type-check が成功する。

---

参考ツール

最も近いものを選んで参考にしてください。

ツールの種類	まず読むもの
UI 状態を持たない純粋な計算	packages/builtin-tool-calculator/ — ExecutionRuntime は executor を再利用します（mathjs／nerdamer の処理はどこでも利用可能）
ドメインエンティティの CRUD	packages/builtin-tool-task/ — Inspector と Render の一式、バッチ処理版
UI の比重が大きい（Inspector／Render／Placeholder／Portal）	packages/builtin-tool-web-browsing/ — 検索結果の UI、詳細表示用の Portal
すべてのサーフェスを備えたデスクトップ／ファイルシステム（Streaming と Intervention を含む）	packages/builtin-tool-local-system/ — ExecutionRuntime が ILocalSystemService を注入し、executor がこれを呼び出します
サーバーサイドのみ（クライアント executor なし）	packages/builtin-tool-web-browsing/ — ExecutionRuntime のみがエクスポートされ、チャットクライアントでは実行されません
実行前に人間の承認が必要	packages/builtin-tool-local-system/src/client/Intervention/ — API ごとの承認コンポーネント