OpenCodeの設定 - プラグインのソースを表示

== 概要 ==
OpenCodeのプラグインシステムは、TypeScript / JavaScriptで記述したソースコードをOpenCodeの動作に組み込み、独自の機能拡張を実現する仕組みである。<br>
<br>
プラグインはフック (hook) ベースのイベント駆動型アーキテクチャを採用しており、<br>
セッションの開始・終了、ファイル操作、ツール実行、シェルコマンドの実行といった各種イベントに対して処理を追加できる。<br>
<br>
プラグインが提供する主な機能は以下の通りである。<br>
* セッション管理の拡張
*: セッションの作成・削除・アイドル状態等のイベントに反応して処理を追加する。
* ツール実行の制御
*: ツール実行前後に検証・変換・ログ記録等の処理を挿入する。
* 環境変数の注入
*: シェル実行時にプロジェクト固有の環境変数を動的に追加する。
* カスタムツールの定義
*: LLMが呼び出せる独自のツールを作成し、OpenCodeの機能を拡張する。
<br>
プラグインはプロジェクト固有 または グローバルに配置でき、OpenCode起動時に自動的に読み込まれる。<br>
<br><br>

== プラグインの基本構造 ==
プラグインは非同期関数として実装されており、コンテキストオブジェクトを引数として受け取り、フックオブジェクトを返す構造を持つ。<br>
<br>
基本的なプラグインの構造を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin } from "opencode/plugin"
 
 export const MyPlugin: Plugin = async ({ client, project, $, directory }) => {
    // 初期化処理をここに記述する
 
    return {
       "session.created": async ({ session }) => {
          // セッション作成時の処理
       },
       "tool.execute.before": async ({ tool, args }) => {
          // ツール実行前の処理
       }
    }
 }
 </syntaxhighlight>
<br>
コンテキストはデストラクチャリングで受け取ることが重要である。<br>
<br>
* 正しい記述方法
*: <code>async ({ client, project, $ }) => { ... }</code>
* 誤った記述方法
*: <code>async (client, project, $) => { ... }</code>
<br>
==== コンテキストオブジェクト ====
コンテキストオブジェクトには、プラグイン内で利用できる各種情報とAPIが含まれる。<br>
<br>
<center>
{| class="wikitable"
! プロパティ !! 説明
|-
| <code>client</code> || OpenCode SDKクライアント<br>ログ出力やAPI呼び出しに使用する。<br>例: <code>client.app.log("info", "メッセージ")</code>
|-
| <code>project</code> || プロジェクト情報<br>現在のプロジェクトのメタデータにアクセスできる。
|-
| <code>$</code> || シェルコマンド実行用のAPI (BunのShell API)<br>プラグイン内からシェルコマンドを実行する時に使用する。
|-
| <code>directory</code> || 現在の作業ディレクトリのパス
|-
| <code>worktree</code> || ワークツリー情報<br>Gitのワークツリーに関する情報にアクセスできる。
|-
| <code>app</code> || アプリケーション参照<br>OpenCodeアプリケーション全体への参照を提供する。
|}
</center>
<br>
==== フックオブジェクト ====
フックオブジェクトは、プラグインが対応する各イベントとその処理関数をマッピングしたオブジェクトである。<br>
<br>
フックオブジェクトの基本的な構造を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 return {
    // イベント名: 処理関数
    "session.created": async ({ session }) => { ... },
    "tool.execute.before": async ({ tool, args }) => { ... },
    "shell.env": async ({ env }) => { ... }
 }
 </syntaxhighlight>
<br>
フックの処理関数は非同期関数として定義して、イベントに応じたパラメータを受け取る。<br>
<br>
一部のフックでは、受け取ったパラメータを変更して返すことにより、OpenCodeの動作を変更できる。<br>
<br><br>

== ディレクトリ構造 ==
プラグインは以下の2つの場所に配置できる。<br>
<br>
* プロジェクト固有のプラグイン
*: <u>.opencode/plugins/</u>
*: 特定のプロジェクトにのみ適用される。
* グローバルプラグイン
*: <u>~/.config/opencode/plugins/</u>
*: 全てのプロジェクトで使用できる。
<br>
OpenCode起動時に上記のディレクトリが自動的にスキャンされ、プラグインが読み込まれる。<br>
<br>
npmパッケージとして配布されているプラグインは、<u>opencode.jsonファイル</u> の <u>plugins</u> フィールドに指定することで使用できる。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "plugins": [
       "opencode-plugin-example",
       "./local-plugin"
    ]
 }
 </syntaxhighlight>
<br>
プロジェクトにプラグインを追加する場合の推奨ディレクトリ構成を以下に示す。<br>
<br>
 <syntaxhighlight lang="bash">
 # 例: QML/C++プロジェクト

 .opencode/
 ├── plugins/
 │   ├── build-notify.ts       # CMakeビルド結果通知プラグイン
 │   ├── qml-hot-reload.ts     # QMLホットリロード検知プラグイン
 │   └── env-protection.ts     # 環境変数保護プラグイン
 └── package.json              # 依存関係の定義
 </syntaxhighlight>
<br><br>

== プラグインの作成方法 ==
==== 基本的なプラグイン ====
最もシンプルなプラグインの例を以下に示す。<br>
<br>
以下に示すプラグインは、セッション作成時にログを出力するだけの基本的な実装である。<br>
<br>
* ファイルの配置場所の例
*: <u>.opencode/plugins/hello.ts</u>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin } from "opencode/plugin"
 
 export const HelloPlugin: Plugin = async ({ client }) => {
    client.app.log("info", "HelloPlugin: 読み込み完了")
 
    return {
       "session.created": async ({ session }) => {
          client.app.log("info", `新しいセッションが作成されました: ${session.id}`)
       },
       "session.deleted": async ({ session }) => {
          client.app.log("info", `セッションが削除されました: ${session.id}`)
       }
    }
 }
 </syntaxhighlight>
<br>
==== TypeScript / JavaScriptモジュール ====
OpenCodeのプラグインは、TypeScript または JavaScriptで記述できる。<br>
TypeScriptを使用すると、型チェックによる安全性が向上するため推奨される。<br>
<br>
TypeScriptプラグインの例を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin, tool } from "opencode/plugin"
 import { z } from "zod"
 
 export const FullExamplePlugin: Plugin = async ({ client, directory }) => {
    // 初期化処理
    const startTime = Date.now()
    client.app.log("info", "プラグイン初期化中...")
 
    return {
       "session.created": async ({ session }) => {
          client.app.log("info", `セッション開始: ${session.id}`)
       },
 
       "session.idle": async ({ session }) => {
          const elapsed = Date.now() - startTime
          client.app.log("info", `セッションがアイドル状態になりました (経過時間: ${elapsed}ms)`)
       },
 
       "session.deleted": async ({ session }) => {
          // 状態のクリーンアップ
          client.app.log("info", `セッション終了: ${session.id}`)
       },
 
       "tool.execute.before": async ({ tool, args }) => {
          client.app.log("debug", `ツール実行前: ${tool.name}`)
       }
    }
 }
 </syntaxhighlight>
<br><br>

== 利用可能なフック ==
==== セッションフック ====
セッションのライフサイクルに関連するフックである。<br>
<br>
<center>
{| class="wikitable"
|+ セッションフック一覧
! フック名 !! 説明 !! 用途
|-
| <code>session.created</code> || セッションが新規作成された時 || 初期化処理、ログ記録
|-
| <code>session.updated</code> || セッション情報が更新された時 || 状態の同期
|-
| <code>session.idle</code> || セッションがアイドル状態になった時 || 通知送信、リソース解放
|-
| <code>session.deleted</code> || セッションが削除された時 || クリーンアップ処理 (重要)
|-
| <code>session.status</code> || セッションのステータスが変化した時 || ステータス監視
|-
| <code>session.compacted</code> || セッションがコンパクションされた時 || コンパクション後の処理
|}
</center>
<br>
<code>session.deleted</code> フックでの状態クリーンアップは、メモリリーク防止のために特に重要である。<br>
<br>
==== ファイルフック ====
メッセージとメッセージパーツに関連するフックである。<br>
<br>
<center>
{| class="wikitable"
|+ ファイルフック一覧
! フック名 !! 説明
|-
| <code>message.updated</code> || メッセージが更新された時
|-
| <code>message.removed</code> || メッセージが削除された時
|-
| <code>message.part.updated</code> || メッセージパーツが更新された時
|-
| <code>message.part.removed</code> || メッセージパーツが削除された時
|}
</center>
<br>
==== ツールフック ====
ツールの実行に関連するフックである。<br>
ツールフックを使用すると、ツール実行前後に処理を追加したり、実行を制御したりできる。<br>
<br>
<center>
{| class="wikitable"
|+ ツールフック一覧
! フック !! 説明
|-
| <code>tool.execute.before</code> || ツール実行前に呼び出される。<br>入力値の検証や変更が可能である。<br><code>throw</code> でツール実行を中断できる。
|-
| <code>tool.execute.after</code> || ツール実行後に呼び出される。<br>ツールの出力結果に対して後処理を行える。
|}
</center>
<br>
ツールフックの使用例を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 "tool.execute.before": async ({ tool, args }) => {
    // 特定のツールの実行前に検証を行う
    if (tool.name === "bash" && args.command.includes("rm -rf")) {
       throw new Error("危険なコマンドの実行を拒否しました")
    }
 },
 
 "tool.execute.after": async ({ tool, args, result }) => {
    // ツール実行後にログを記録する
    client.app.log("info", `ツール実行完了: ${tool.name}`)
 }
 </syntaxhighlight>
<br>
==== コマンドフック ====
LLMへのリクエストに関連するフックである。<br>
<br>
<center>
{| class="wikitable"
|+ LLMリクエスト関連フック
! フック !! 説明
|-
| <code>chat.params</code> || LLMに送信するパラメータを変更できる。温度設定やシステムプロンプトの動的変更に使用する。
|-
| <code>chat.message</code> || LLMから受信したメッセージに対応する処理を行う。
|}
</center>
<br>
==== シェルフック ====
シェルコマンドの実行に関連するフックである。<br>
<br>
<center>
{| class="wikitable"
|+ LLMリクエスト関連フック
! フック !! 説明
|-
| <code>chat.params</code> || LLMに送信するパラメータを変更できる。<br>temperature設定やシステムプロンプトの動的変更に使用する。
|-
| <code>chat.message</code> || LLMから受信したメッセージに対応する処理を行う。
|}
</center>
<br>
<code>shell.env</code> フックの使用例を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 "shell.env": async ({ env }) => {
    return {
       ...env,
       MY_PROJECT_API_URL: "https://api.example.com",
       MY_PROJECT_ENV: "development"
    }
 }
 </syntaxhighlight>
<br>
==== LSPフック ====
Language Server Protocol に関連するフックである。<br>
<br>
<center>
{| class="wikitable"
|+ LSP関連フック
! フック !! 説明
|-
| <code>lsp.diagnostics</code> || LSPの診断情報 (エラーや警告) が更新された時に呼び出される。<br>コード品質の監視や自動修正処理に使用する。
|}
</center>
<br>
下表に、その他の主要なフックを示す。<br>
<br>
<center>
{| class="wikitable"
|+ その他の主要なフック
! フック !! 説明
|-
| <code>permission.ask</code> || 権限確認ダイアログが表示される前に呼び出される。
|-
| <code>permission.replied</code> || 権限確認に対してユーザが返答した後に呼び出される。
|-
| <code>auth</code> || カスタム認証プロバイダを実装する時に使用する。
|}
</center>
<br><br>

== カスタムツールの作成 ==
プラグインでは <code>tool()</code> ヘルパー関数を使用してカスタムツールを定義できる。<br>
<br>
カスタムツールを定義すると、LLMがそのツールを呼び出してタスクを実行できるようになる。<br>
<br>
==== ツールの基本構造 ====
カスタムツールの基本構造を以下に示す。<br>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin, tool } from "opencode/plugin"
 
 export const CustomToolPlugin: Plugin = async ({ client }) => {
    const myTool = tool({
       name: "my_custom_tool",
       description: "このツールの説明。LLMがいつ使用するかを判断するために使用される。",
       parameters: {
          input: tool.schema.string().describe("処理する入力テキスト"),
          count: tool.schema.number().describe("繰り返し回数")
       },
       execute: async (args, context) => {
          // ツールの処理を実装する
          const result = args.input.repeat(args.count)
          return { output: result }
       }
    })
 
    return {
       tools: [myTool]
    }
 }
 </syntaxhighlight>
<br>
==== 引数スキーマ (Zod) ====
カスタムツールの引数スキーマはZodベースのヘルパーを使用して定義する。<br>
<br>
利用可能なスキーマ型を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 引数スキーマ型一覧
! スキーマ型 !! 説明 !! 使用例
|-
| <code>tool.schema.string()</code> || 文字列型 || ファイルパス、テキスト入力
|-
| <code>tool.schema.number()</code> || 数値型 || カウント、タイムアウト値
|-
| <code>tool.schema.boolean()</code> || 真偽値型 || フラグ、スイッチ
|-
| <code>tool.schema.enum([...])</code> || 列挙型 || 選択肢から1つを選ぶ引数
|-
| <code>tool.schema.optional(...)</code> || 省略可能な型 || 必須でない引数をラップする
|}
</center>
<br>
各スキーマ型に <code>.describe()</code> を連結することで、LLMへの説明を追加できる。<br>
説明は詳細に記述するほど、LLMがツールを正しく使用しやすくなる。<br>
<br>
 <syntaxhighlight lang="typescript">
 parameters: {
    path: tool.schema.string().describe("操作対象のファイルパス (絶対パスで指定)"),
    mode: tool.schema.enum(["read", "write", "append"]).describe("ファイル操作のモード"),
    encoding: tool.schema.optional(tool.schema.string()).describe("文字エンコーディング (省略時はUTF-8)")
 }
 </syntaxhighlight>
<br>
==== 複数ツールのエクスポート ====
1つのプラグインから複数のカスタムツールをエクスポートするには、<code>tools</code> フィールドに配列で指定する。<br>
<br>
 <syntaxhighlight lang="typescript">
 return {
    tools: [toolA, toolB, toolC]
 }
 </syntaxhighlight>
<br>
==== コンテキストアクセス ====
<code>execute</code> 関数の第2引数 <code>context</code> から、実行時の情報にアクセスできる。<br>
<br>
<center>
{| class="wikitable"
|+ コンテキストプロパティ一覧
! プロパティ !! 説明
|-
| <code>context.sessionID</code> || 現在のセッションID
|-
| <code>context.messageID</code> || 現在のメッセージID
|-
| <code>context.directory</code> || 現在の作業ディレクトリ
|-
| <code>context.worktree</code> || ワークツリー情報
|-
| <code>context.agent</code> || 実行中のエージェント情報
|-
| <code>context.signal</code> || キャンセル用のAbortSignal
|}
</center>
<br>
<code>context.signal</code> を使用することにより、長時間処理の途中でキャンセルに対応できる。<br>
<br><br>

== プラグインの実用例 ==
==== 環境変数保護 ====
機密ファイル (環境変数ファイル、認証情報ファイル等) へのアクセスを禁止するプラグインの実装例を以下に示す。<br>
<br>
* ファイルの配置場所の例
*: <u>.opencode/plugins/env-protection.ts</u>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin } from "opencode/plugin"
 
 export const EnvProtection: Plugin = async ({ client }) => {
    const sensitivePatterns = [/\.env/, /credentials/, /\.secret/]

    return {
       "tool.execute.before": async ({ tool, args }) => {
          if (tool.name === "read" && sensitivePatterns.some(p => p.test(args.path))) {
             throw new Error("Access denied to sensitive files")
          }
       }
    }
 }
 </syntaxhighlight>
<br>
このプラグインは、<code>read</code> ツールが機密ファイルにアクセスしようとした時に例外をスローして処理を中断する。<br>
<br>
==== セッション通知 ====
セッションがアイドル状態になった時にログを出力するプラグインの実装例を以下に示す。<br>
この例を応用することで、外部の通知サービスへの連携も実現できる。<br>
<br>
* ファイルの配置場所の例
*: <u>.opencode/plugins/notification.ts</u>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin } from "opencode/plugin"
 
 export const NotificationPlugin: Plugin = async ({ client }) => {
    return {
       "session.idle": async ({ session }) => {
          client.app.log("info", "Session completed")
          // ここに外部通知サービスへのAPI呼び出し等を追加できる
       }
    }
 }
 </syntaxhighlight>
<br>
==== カスタムツール定義 ====
プロジェクト固有のカスタムツールを定義するプラグインの実装例を以下に示す。<br>
この例では、指定したファイルのメタデータ (行数、サイズ等) を取得するツールを定義している。<br>
<br>
* ファイルの配置場所の例
*: <u>.opencode/plugins/custom-tools.ts</u>
<br>
 <syntaxhighlight lang="typescript">
 import { Plugin, tool } from "opencode/plugin"
 import { stat, readFile } from "fs/promises"
 
 export const CustomToolsPlugin: Plugin = async ({ client }) => {
    const fileInfoTool = tool({
       name: "get_file_info",
       description: "指定したファイルのメタデータ (行数、ファイルサイズ等) を取得する",
       parameters: {
          path: tool.schema.string().describe("情報を取得するファイルのパス")
       },
       execute: async (args, context) => {
          const stats = await stat(args.path)
          const content = await readFile(args.path, "utf-8")
          const lines = content.split("\n").length

          return {
             size: stats.size,
             lines: lines,
             modified: stats.mtime.toISOString()
          }
       }
    })
 
    return {
       tools: [fileInfoTool]
    }
 }
 </syntaxhighlight>
<br><br>

== 依存関係の管理 ==
プラグインで外部npmパッケージを使用する場合は、<u>.opencode/package.jsonファイル</u> に依存関係を定義する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "name": "opencode-plugins",
    "version": "1.0.0",
    "dependencies": {
       "axios": "^1.6.0",
       "zod": "^3.22.0"
    },
    "devDependencies": {
       "typescript": "^5.3.0",
       "@types/node": "^20.0.0"
    }
 }
 </syntaxhighlight>
<br>
OpenCodeの起動時に <code>bun install</code> コマンドが自動的に実行されるため、手動でインストールコマンドを実行する必要はない。<br>
<br>
依存関係の管理に関する注意事項を以下に示す。<br>
* <u>package.jsonファイル</u> は、必ず <u>.opencode/ディレクトリ</u> に配置する。
*: プロジェクトルートの <u>package.jsonファイル</u> とは別ファイルである。
*: <br>
* Bunが使用されるため、npm、yarn、pnpmとは異なる場合がある。
*: Bunに対応したパッケージを使用することを確認する。
* TypeScriptを使用する場合は、型定義パッケージ (<u>@types/*</u>) も依存関係に含める。
<br><br>

== 推奨される事柄 ==
==== エラーハンドリング ====
プラグインのフック内では、適切なエラーハンドリングを実装する。<br>
<br>
<u>エラーが発生した場合でも、OpenCodeの動作が停止しないように注意する。</u><br>
<br>
 <syntaxhighlight lang="typescript">
 "session.created": async ({ session }) => {
    try {
       await initializeSession(session.id)
    }
    catch (error) {
       client.app.log("error", `セッション初期化エラー: ${error}`)
       // エラーを再スローしないことで、OpenCodeの動作を継続させる
    }
 }
 </syntaxhighlight>
<br>
==== セッション削除時のクリーンアップ ====
セッションごとに状態を保持する場合は、<code>session.deleted</code> フックで必ずクリーンアップを行う。<br>
クリーンアップを怠るとメモリリークの原因となる。<br>
<br>
 <syntaxhighlight lang="typescript">
 export const StatefulPlugin: Plugin = async ({ client }) => {
    const sessionState = new Map<string, any>()
 
    return {
       "session.created": async ({ session }) => {
          sessionState.set(session.id, { startTime: Date.now() })
       },
       "session.deleted": async ({ session }) => {
          // 必ずクリーンアップする
          sessionState.delete(session.id)
       }
    }
 }
 </syntaxhighlight>
<br>
==== ログ出力 ====
プラグイン内のログ出力は <code>console.log()</code> ではなく、<code>client.app.log()</code> を使用する。<br>
<code>client.app.log()</code> を使用することにより、OpenCodeのログシステムと統合されて適切に管理される。<br>
<br>
 <syntaxhighlight lang="typescript">
 // 正しい方法
 client.app.log("info", "処理完了")
 client.app.log("error", "エラーが発生しました")
 client.app.log("debug", "デバッグ情報")
 
 // 避けるべき方法
 console.log("処理完了")
 </syntaxhighlight>
<br>
==== その他のベストプラクティス ====
* TypeScriptを使用して型安全性を確保する。
*: TypeScriptの型チェックにより、ランタイムエラーを事前に防止できる。
*: <br>
* 公式フックのみを使用する。
*: 非公式・内部フックは将来のバージョンで変更される可能性がある。
*: <br>
* 大規模なプラグインはモジュールに分割する。
*: 機能ごとにファイルを分割して保守性を高める。
*: <br>
* プラグインの初期化処理は軽量に保つ。
*: 起動時の重い処理はOpenCodeのレスポンス性に影響する可能性がある。
<br><br>

== トラブルシューティング ==
==== プラグインが読み込まれない場合 ====
プラグインが認識されない場合は、以下の項目を確認する。<br>
<br>
===== 配置ディレクトリの確認 =====
プラグインファイルが正しいディレクトリに配置されているか確認する。<br>
<br>
* プロジェクト固有
*: <u>.opencode/plugins/</u>
* グローバル
*: <u>~/.config/opencode/plugins/</u>
<br>
===== ファイル拡張子の確認 =====
プラグインファイルの拡張子が <u>.ts</u> または <u>.js</u> であることを確認する。<br>
他の拡張子のファイルは自動読み込みの対象外である。<br>
<br>
===== ログレベルの設定 =====
OpenCodeのログレベルを <code>DEBUG</code> に設定することにより、詳細な読み込み情報を確認できる。<br>
<br>
 <syntaxhighlight lang="sh">
 OPENCODE_LOG_LEVEL=DEBUG opencode
 </syntaxhighlight>
<br>
==== メモリリークが発生する場合 ====
セッション削除時のクリーンアップが実装されているか確認する。<br>
<code>session.deleted</code> フック内で、セッションに紐付いた全ての状態を削除しているか確認する。<br>
<br>
 <syntaxhighlight lang="typescript">
 "session.deleted": async ({ session }) => {
    // Map、Set、その他のデータ構造からセッションのデータを削除する
    mySessionData.delete(session.id)
    myCache.delete(session.id)
 }
 </syntaxhighlight>
<br>
==== 依存関係の問題が発生する場合 ====
外部パッケージが見つからないエラーが発生した場合は、以下を確認する。<br>
<br>
* <u>package.jsonファイル</u> が <u>.opencode/ディレクトリ</u> に配置されているか確認する。
*: プロジェクトルートではなく、<code>.opencode/</code> 直下に配置する必要がある。
*: <br>
* <code>bun install</code> が正常に実行されたか確認する。
*: 手動で <code>bun install</code> を実行して、エラーメッセージを確認する。
<br>
 cd .opencode && bun install
<br>
==== プラグインの処理が期待通りに動作しない場合 ====
* デストラクチャリングの記述方法を確認する。
*: コンテキストは単一パラメータとしてデストラクチャリングする必要がある。
*: 正しい記述方法: <code>async ({ client, project }) => { ... }</code>
*: <br>
* フック名のスペルミスを確認する。
*: フック名が誤っていると処理が呼び出されない。
*: 公式ドキュメントでフック名を確認する。
*: <br>
* <code>throw</code> の使用状況を確認する。
*: <code>tool.execute.before</code> で例外をスローした場合、ツールの実行が中断される。
*: 意図しない <code>throw</code> がないか確認する。
<br><br>
<br><br>

== プラグインマーケットプレイス ==
OpenCodeはプラグインマーケットプレイス機能を提供しており、コミュニティが提供するプラグインを簡単にインストールできる。<br>
<br>
==== マーケットプレイスからのプラグイン追加 ====
マーケットプレイスからプラグインを追加するには、以下のコマンドを使用する。<br>
<br>
 <syntaxhighlight lang="sh">
 # マーケットプレイスにプラグインを追加
 /plugin marketplace add <マーケットプレイス名>/<プラグイン名>
 
 # 例: Microsoft Docs MCPを追加
 /plugin marketplace add microsoftdocs/mcp
 </syntaxhighlight>
<br>
==== プラグインのインストール ====
追加したマーケットプレイスからプラグインをインストールするには、以下のコマンドを使用する。<br>
<br>
 <syntaxhighlight lang="sh">
 # プラグインをインストール
 /plugin install <plugin-name>@<marketplace-name>
 
 # 例: Microsoft Docsプラグインをインストール
 /plugin install microsoft-docs@microsoft-docs-marketplace
 </syntaxhighlight>
<br>
==== Microsoft Docs MCPの設定例 ====
Microsoft Docs MCPを使用すると、OpenCodeからMicrosoftおよびAzureの公式ドキュメントにアクセスできる。<br>
公式ドキュメントを検索し、コードサンプルを取得し、詳細な技術情報を参照できる。<br>
<br>
 <syntaxhighlight lang="sh">
 # Microsoft Docs MCPをマーケットプレイスに追加
 /plugin marketplace add microsoftdocs/mcp
 
 # Microsoft Docs プラグインをインストール
 /plugin install microsoft-docs@microsoft-docs-marketplace
 </syntaxhighlight>
<br><br>

== よく使用されるプラグイン ==
OpenCodeのエコシステムには多くのコミュニティプラグインが存在する。<br>
<br>
使用される頻度の高い便利なプラグインをカテゴリ別に示す。<br>
<br>
==== 認証関連プラグイン ====
認証関連のプラグインを使用すると、APIクレジットの代わりに既存のサブスクリプションを使用できる。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明 !! opencode.jsonの設定
|-
| opencode-openai-codex-auth || ChatGPT Plus/Proのサブスクリプションを使用してOpenAI Codexバックエンドを利用する。<br>OAuth認証をサポートする。 || <code>"opencode-openai-codex-auth"</code>
|-
| opencode-gemini-auth || 既存のGeminiプランを使用してGoogleアカウントで認証する。<br>API課金の代わりにGeminiプランを使用できる。 || <code>"opencode-gemini-auth"</code>
|-
| opencode-antigravity-auth || Antigravityの無料モデルを使用してAPI課金なしでモデルを利用する。<br>GeminiおよびAnthropicモデルに対応する。 || <code>"opencode-antigravity-auth"</code>
|-
| opencode-google-antigravity-auth || Google Antigravity OAuthを使用する拡張版。<br>Google検索サポートと堅牢なAPI処理を提供する。 || <code>"opencode-google-antigravity-auth"</code>
|}
</center>
<br>
==== 開発環境プラグイン ====
開発環境を拡張するプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明 !! opencode.jsonの設定
|-
| opencode-daytona || Daytonaサンドボックス内でOpenCodeセッションを自動実行する。<br>Git同期とライブプレビュー機能を提供する。 || <code>"opencode-daytona"</code>
|-
| opencode-devcontainers || 複数ブランチのdevcontainer分離を実現する。<br>シャロークローンと自動割り当てポートをサポートする。 || <code>"opencode-devcontainers"</code>
|-
| opencode-morph-fast-apply || Morph Fast Apply APIを使用した高速なコード編集を実現する。<br>10,500+ tokens/secの編集速度と遅延編集マーカーを提供する。 || <code>"opencode-fast-apply"</code><br>パッケージ名が異なる
|-
| opencode-type-inject || ファイル読み込み時にTypeScript/Svelteの型を自動注入する。<br>型参照ツールを提供する。 || <code>"@nick-vi/opencode-type-inject"</code><br>スコープ付きパッケージ
|}
</center>
<br>
==== エージェント・オーケストレーションプラグイン ====
AIエージェントの動作を拡張・調整するプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明 !! opencode.jsonの設定
|-
| opencode-background-agents || Claude Codeスタイルのバックグラウンドエージェントを提供する。<br>非同期委任とコンテキスト永続化をサポートする。 || <code>"@zenobius/opencode-background"</code><br>パッケージ名が異なる
|-
| oh-my-opencode || バックグラウンドエージェント、LSP/AST/MCPツール、厳選されたエージェントを提供する。<br>詳細は専用ページを参照のこと。 || <code>"oh-my-opencode"</code>
|-
| micode || 構造化されたブレインストーム→計画→実装のワークフローを提供する。<br>セッション継続性とサブエージェントオーケストレーションをサポートする。 || <code>"micode"</code>
|-
| opencode-workspace || バンドルされたマルチエージェントオーケストレーションハーネスを提供する。<br>16コンポーネントを1つのインストールで利用できる。 || npmに未公開
|}
</center>
<br>
==== 通知・モニタリングプラグイン ====
セッション状態の通知や使用状況の追跡を行うプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明 !! opencode.jsonの設定
|-
| opencode-notify || タスク完了時のネイティブOS通知を提供する。<br>バックグラウンドタスクの完了を通知する。 || <code>"opencode-notify"</code>
|-
| opencode-notificator || デスクトップ通知とサウンドアラートを提供する。<br>OpenCodeセッションの状態変化を通知する。 || npmに未公開
|-
| opencode-notifier || 権限、完了、エラーイベントのデスクトップ通知とサウンドアラートを提供する。 || <code>"@mohak34/opencode-notifier"</code><br>スコープ付きパッケージ
|-
| opencode-wakatime || Wakatimeを使用してOpenCodeの使用状況を追跡する。<br>コーディング時間の自動記録を行う。 || <code>"opencode-wakatime"</code>
|-
| opencode-quota || プロバイダー間のクォータとトークン使用量を追跡する。<br>自動トースト通知とスラッシュコマンドを提供する。 || <code>"opencode-quota"</code>
|}
</center>
<br>
==== その他のユーティリティプラグイン ====
その他の便利なプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明 !! opencode.json設定
|-
| opencode-helicone-session || リクエストグループ化のためのHeliconeセッションヘッダーを自動注入する。<br>API使用状況の分析に使用する。 || <code>"opencode-helicone-session"</code>
|-
| opencode-dynamic-context-pruning || トークン使用量を最適化する。<br>古いツール出力をコンテキストから削除する。 || <code>"@tarquinen/opencode-dcp"</code><br>スコープ付きパッケージ
|-
| opencode-supermemory || Supermemoryを使用してセッション間の永続メモリを提供する。<br>長期的なコンテキスト保持を実現する。 || <code>"opencode-supermemory"</code>
|-
| opencode-agent-memory || Lettaエージェントにインスパイアされた永続的な自己編集可能メモリブロックを提供する。<br>エージェントの記憶を保持する。 || <code>"opencode-agent-memory"</code>
|-
| opencode-direnv || セッション開始時にdirenv環境変数を自動的に読み込む。<br>Nix flakesとの相性が良い。 || npmに未公開
|-
| opencode-scheduler || launchd (Mac) または systemd (Linux) を使用して定期的なジョブをスケジュールする。<br>cron構文をサポートする。 || <code>"opencode-scheduler"</code>
|-
| opencode-websearch-cited || 対応プロバイダーのネイティブウェブ検索サポートを追加する。<br>Google groundedスタイルの引用付き検索を提供する。 || <code>"opencode-websearch-cited"</code>
|-
| opencode-md-table-formatter || LLMが生成したMarkdownテーブルを整形する。<br>テーブルの可読性を向上させる。 || <code>"@franlol/opencode-md-table-formatter"</code><br>スコープ付きパッケージ
|-
| opencode-shell-strategy || 非対話型シェルコマンドの指示を提供する。<br>TTY依存操作によるハングを防止する。 || npmに未公開
|}
</center>
<br>
==== プラグインのインストール方法 ====
プラグインをインストールするには、<u>opencode.jsonファイル</u> の <u>plugin</u> フィールドにパッケージ名を指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "$schema": "https://opencode.ai/config.json",
    "plugin": [
       "opencode-wakatime",
       "opencode-notify",
       "@sveltejs/opencode"
    ]
 }
 </syntaxhighlight>
<br>
スコープ付きnpmパッケージ (例: <u>@sveltejs/opencode</u>) もサポートされている。<br>
<br>
==== 公式エコシステムリソース ====
OpenCodeのエコシステムに関する情報は、以下のリソースから入手できる。<br>
<br>
* [https://opencode.ai/docs/ecosystem/ OpenCodeの公式エコシステムページ]
*: 公式にリストされたプラグインとプロジェクトを確認できる。
*: <br>
* [https://github.com/awesome-opencode/awesome-opencode awesome-opencode GitHubリポジトリ]
*: コミュニティによって管理される厳選リスト
*: プラグイン、テーマ、エージェント、リソースが含まれる。
*: <br>
* [https://opencode.cafe opencode.cafe]
*: コミュニティ駆動のマーケットプレイス
*: 拡張機能、プラグイン、ツールを閲覧・共有できる。
<br><br>

== opencode-auto-resume ==
opencode-auto-resumeは、LLMセッションがタイムアウトやエラーで停止した時に自動的に復旧させるプラグインである。<br>
<br>
ストリームが停止したセッションやツール呼び出しを生テキストとして出力してしまう状態、幻覚ループ、サブエージェント終了後に親セッションがビジーのままになる孤児親状態等を検出して、ユーザ介入なしで回復させる。<br>
<br>
==== 主な機能 ====
opencode-auto-resumeが提供する主な機能を以下に示す。<br>
<br>
* ストール回復
*: LLMからの応答ストリームが48秒以上停止した時に、自動的に <u>continue</u> プロンプトを送信して再開する。
*: 試行回数は指数関数的バックオフで制御され、最大3回まで再開を試みる。
*: 再開時は最後のセッションメッセージから <u>agent</u>、<u>model</u>、<u>provider</u> を抽出して、ユーザが選択した設定を保持する。
*: <br>
* ツール呼び出しの生テキスト検出
*: モデルがXML形式のツール呼び出し (<code>&lt;tool&gt;...&lt;/tool&gt;</code>) を生テキストとして出力した場合に検出する。
*: 検出時には専用の回復プロンプトを送信して、ツールを実際に実行させる。
*: <br>
* 幻覚ループ検出
*: 同じ壊れた出力を繰り返し生成している状態を検出する。
*: 10分以内に3回以上 <u>continue</u> が必要になった場合、リクエストを中断してクリーンな状態から再開する。
*: <br>
* 孤児親セッション検出
*: サブエージェントが終了したにも関わらず親セッションがビジーのまま固定される問題を検出する。
*: ビジーカウントが1より大きい状態から1に減少し、15秒経過しても変化がない場合に回復処理を行う。
*: <br>
* ESC取消の検出
*: ユーザが[ESC]キーでリクエストをキャンセルした場合は、以後の自動再開を行わない。
<br>
==== npm版のインストール (推奨) ====
npmパッケージとして公開されているopencode-auto-resumeは、パッケージマネージャーでインストールして <u>opencode.json / opencode.jsonc</u> ファイルに登録する。<br>
<br>
プラグインをインストールする。<br>
<br>
 npm install opencode-auto-resume
<br>
インストール後、<u>opencode.json / opencode.jsonc</u> ファイルの <code>plugin</code> フィールドにパッケージ名を追加する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "$schema": "https://opencode.ai/config.json",
    "plugin": [
       "opencode-auto-resume"
    ]
 }
 </syntaxhighlight>
<br>
オプションを指定する場合は、<code>[プラグイン名, オプションオブジェクト]</code> の配列形式で登録する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "plugin": [
       [
          "opencode-auto-resume",
          {
             "chunkTimeoutMs": 45000,
             "gracePeriodMs": 3000,
             "maxRetries": 3
          }
       ]
    ]
 }
 </syntaxhighlight>
<br>
==== GitHub版のインストール ====
GitHubリポジトリから直接取得する場合は、OpenCodeのグローバルプラグインディレクトリにクローンしてビルドする。<br>
<br>
グローバルプラグインディレクトリにクローンする。<br>
<br>
 git clone https://github.com/Mte90/opencode-auto-resume.git ~/.config/opencode/plugins/opencode-auto-resume
<br>
プラグインディレクトリに移動する。<br>
<br>
 cd ~/.config/opencode/plugins/opencode-auto-resume
<br>
依存関係をインストールしてビルドする。<br>
<br>
 bun install
 bun run build
<br>
ビルド後、<u>opencode.json / opencode.jsonc</u> ファイルの <code>plugin</code> フィールドにビルド済みのエントリポイントを絶対パスで指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "plugin": [
       [
          "file:///home/<ユーザ名>/.config/opencode/plugins/opencode-auto-resume/dist/index.js",
          {
             "chunkTimeoutMs": 45000,
             "maxRetries": 3
          }
       ]
    ]
 }
 </syntaxhighlight>
<br>
更新する場合は、クローンしたディレクトリに移動して、以下に示すコマンドを実行する。<br>
<br>
 cd ~/.config/opencode/plugins/opencode-auto-resume
 
 git pull
 bun run build
<br>
==== 設定方法 ====
opencode-auto-resumeの動作は、<u>opencode.json / opencode.jsonc</u> ファイルの <code>plugin</code> フィールドで指定したオプションオブジェクトによって調整できる。<br>
<br>
===== 設定オプション =====
<center>
{| class="wikitable"
|+ opencode-auto-resumeの設定オプション
! オプション名 !! デフォルト値 !! 説明
|-
| <code>chunkTimeoutMs</code> || 45000 || ストリームが停止したと判断するまでの無通信タイムアウト (ミリ秒)
|-
| <code>gracePeriodMs</code> || 3000 || 回復処理を実行する前に待つ猶予時間 (ミリ秒)
|-
| <code>checkIntervalMs</code> || 5000 || タイマ監視のポーリング間隔 (ミリ秒)
|-
| <code>maxRetries</code> || 3 || 自動再開を試行する最大回数
|-
| <code>baseBackoffMs</code> || 1000 || 初回再試行までの待ち時間 (ミリ秒)
|-
| <code>maxBackoffMs</code> || 8000 || バックオフの上限時間 (ミリ秒)
|-
| <code>subagentWaitMs</code> || 15000 || 孤児親セッションと判断するまでの待ち時間 (ミリ秒)
|-
| <code>loopMaxContinues</code> || 3 || 幻覚ループ検出のウィンドウ内での最大 <u>continue</u> 回数
|-
| <code>loopWindowMs</code> || 600000 || 幻覚ループ検出のウィンドウ時間 (ミリ秒、デフォルト10分)
|}
</center>
<br>
==== 動作確認 ====
プラグインが正常に読み込まれているかは、OpenCodeの起動ログで確認できる。<br>
<br>
 OPENCODE_LOG_LEVEL=DEBUG opencode
<br>
以下に示すようなログが出力されれば、プラグインは正常に動作している。<br>
<br>
 opencode-auto-resume ready. timeout=45000ms...
<br>
実際の動作確認としては、セッションを48秒以上アイドル状態にすると自動的に <u>continue</u> が送信される。<br>
<br>
ログに <u>Stream stall</u> や <u>Ready-to-continue pattern detected</u> が出力されていれば、回復処理が実行されている。<br>
<br>
回復動作が多すぎる場合は <code>chunkTimeoutMs</code> の値を大きくし、反応が遅い場合は <code>checkIntervalMs</code> の値を小さくするとよい。<br>
<br>
<u>ただし、[ESC]キーでキャンセルしたセッションは自動再開の対象外となる。</u><br>
<br><br>

== 参考リンク ==
* [https://opencode.ai/docs OpenCode公式ドキュメント]
* [https://opencode.ai/docs/plugins OpenCode公式ドキュメント - Plugins]
* [https://github.com/opencode-ai/opencode OpenCode GitHubリポジトリ]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,OpenCode,Plugin,TypeScript,JavaScript,Hook,Tool,AI,Development,Programming,SUSE,Linux
|description={{PAGENAME}} - OpenCodeのプラグインシステムに関する設定・実装ガイド | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]