opencode-tbot 0.1.19 → 0.1.21

package/README.ja.md

@@ -6,20 +6,26 @@
 
 > このプロジェクトは OpenCode チームによって開発されたものではなく、公式な関連もありません。
 
-## できること
+## 概要
 
 `opencode-tbot` を使うと、Telegram から OpenCode を操作できます。
 
 - テキストメッセージは現在アクティブな OpenCode セッションに転送されます。
-- Telegram の画像は OpenCode のファイルパートとしてアップロードされます。
-- Telegram の音声メッセージは、通常の prompt フローに入る前に OpenRouter で文字起こしできます。
-- OpenCode が発行した権限リクエストは、Telegram のインラインボタンから直接承認または拒否できます。
+- Telegram の写真と画像ドキュメントは OpenCode のファイルパートとしてアップロードされます。
+- Telegram の音声メッセージは明示的に拒否され、ローカライズされた返信を返します。
+- OpenCode が発行した権限リクエストは、Telegram のインラインボタンから承認または拒否できます。
 - セッション完了やエラーイベントは、紐付けられた Telegram チャットへ通知できます。
-- チャット状態は JSON の state ファイルに保存され、Node と Bun の両方のランタイムで動作します。
+- チャットの紐付け状態は JSON の state ファイルに保存されます。
+
+## 前提条件
+
+- このプラグインを読み込む OpenCode ホストプロセスが動作していること。
+- Telegram bot token を用意していること。
+- CLI とローカル開発には Node.js `>=22.12.0` が必要です。
 
 ## インストール
 
-次を実行します。
+推奨インストール方法:
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- install
@@ -39,11 +45,20 @@ OpenCode に登録済みの npm プラグイン spec を更新:
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
-OpenCode 上でプラグインが `file:///.../node_modules/...` のようなパスで表示される場合は、古いローカル npm インストールを削除します。
+### CLI オプション
 
-```bash
-npm uninstall opencode-tbot
-```
+`install` で利用可能:
+
+- `--bot-token <token>` Telegram bot token を非対話で設定
+- `--telegram-api-root <url>` Telegram Bot API のベース URL を上書き
+- `--plugin-spec <spec>` カスタム npm プラグイン spec を登録
+- `--skip-register` OpenCode 側のプラグイン登録は変更せず、プラグイン設定だけを書き換え
+- `--home-dir <path>` カスタム home ディレクトリを使用
+
+`update` で利用可能:
+
+- `--plugin-spec <spec>`
+- `--home-dir <path>`
 
 ## 設定
 
@@ -52,7 +67,11 @@ npm uninstall opencode-tbot
 1. `~/.config/opencode/opencode-tbot/config.json` のグローバルデフォルト
 2. `<worktree>/tbot.config.json` のプロジェクト上書き設定
 
-プロジェクト設定はグローバル設定に上書きマージされます。`telegram`、`state`、`openrouter` はセクション単位でディープマージされます。
+プロジェクト設定はグローバル設定に上書きマージされます。`telegram` と `state` はセクション単位でディープマージされます。
+
+古い `openrouter` 音声転写設定はランタイムでは無視され、インストーラーが設定を書き直す際にも削除されます。
+
+リポジトリには最小構成の参考として [tbot.config.example.json](./tbot.config.example.json) も含まれています。
 
 ### `tbot.config.json` の例
 
@@ -66,12 +85,6 @@ npm uninstall opencode-tbot
   "state": {
     "path": "./data/opencode-tbot.state.json"
   },
-  "openrouter": {
-    "apiKey": "your_openrouter_api_key",
-    "model": "openai/gpt-audio-mini",
-    "timeoutMs": 30000,
-    "transcriptionPrompt": ""
-  },
   "logLevel": "info"
 }
 ```
@@ -84,39 +97,27 @@ npm uninstall opencode-tbot
 | `telegram.allowedChatIds` | いいえ | `[]` | 許可する Telegram chat ID の配列。空の場合はすべての chat を受け付けます。 |
 | `telegram.apiRoot` | いいえ | `https://api.telegram.org` | Telegram Bot API のベース URL。テストやセルフホストのゲートウェイ向けです。 |
 | `state.path` | いいえ | `./data/opencode-tbot.state.json` | JSON state ファイルのパス。現在の OpenCode worktree からの相対パスとして解決されます。 |
-| `openrouter.apiKey` | いいえ | `""` | OpenRouter API key。音声文字起こしを有効にする場合のみ必要です。 |
-| `openrouter.model` | いいえ | `openai/gpt-audio-mini` | 音声文字起こしに使う OpenRouter モデル。 |
-| `openrouter.timeoutMs` | いいえ | `30000` | 音声文字起こしのタイムアウト時間（ミリ秒）。 |
-| `openrouter.transcriptionPrompt` | いいえ | `""` | 文字起こしプロンプトに追加される任意の補足指示。 |
 | `logLevel` | いいえ | `info` | プラグインのログレベル。ログは `client.app.log()` 経由で出力されます。 |
 
-## ランタイム上の前提
-
-必須:
-
-- `telegram.botToken`
+### 補足
 
-任意:
-
-- `telegram.allowedChatIds`
-- `telegram.apiRoot`
-- `state.path`
-- `openrouter.apiKey`
-- `openrouter.model`
-- `openrouter.timeoutMs`
-- `openrouter.transcriptionPrompt`
-- `logLevel`
+- `state.path` は現在の OpenCode worktree からの相対パスとして解決されます。
+- `telegram.allowedChatIds` を空のままにすると、bot は任意の chat からのメッセージを受け付けます。本番では制限を設定してください。
+- 権限承認とセッション通知はプラグインの hook で処理されます。
+- `/language` は現在 English、简体中文、日本語 をサポートしています。
 
-補足:
+## クイックスタート
 
-- `state.path` のデフォルトは `./data/opencode-tbot.state.json` で、現在の OpenCode worktree からの相対パスとして解決されます。
-- ログは `client.app.log()` 経由で出力されます。
-- 権限承認とセッション通知はプラグインの hook で処理されます。
+1. `npm exec --package opencode-tbot@latest opencode-tbot -- install` でプラグインをインストールします。
+2. 特定の chat のみ許可したい場合は、`tbot.config.json` で `telegram.allowedChatIds` を設定します。
+3. 対象の worktree で OpenCode を起動し、プラグインランタイムを読み込ませます。
+4. Telegram で `/status` を実行し、接続を確認します。
+5. `/new [title]` を実行するか、テキストメッセージを直接送信して使い始めます。
 
 ## コマンド
 
 - `/start` 短いウェルカムメッセージとクイックスタート手順を表示
-- `/status` OpenCode のヘルス、パス、LSP、MCP の状態をまとめて表示
+- `/status` OpenCode のヘルス、パス、プラグイン、LSP、MCP の状態をまとめて表示
 - `/new [title]` 新しい OpenCode セッションを作成
 - `/agents` または `/agent` 利用可能な agent を一覧表示し、アクティブな agent を切り替え
 - `/sessions` 利用可能なセッションを一覧表示し、アクティブなセッションを切り替え
@@ -124,7 +125,11 @@ npm uninstall opencode-tbot
 - `/model` または `/models` 利用可能なモデルを一覧表示し、アクティブなモデルを切り替え
 - `/language` bot の表示言語を切り替え
 
-コマンド以外のテキストメッセージは prompt として扱われ、OpenCode に送信されます。OpenRouter が設定されている場合、Telegram の `voice` メッセージは文字起こし後に同じ prompt フローへ入ります。Telegram の画像は OpenCode のファイルパートとして転送されます。
+メッセージ処理:
+
+- コマンド以外のテキストは prompt として扱われ、OpenCode に送信されます。
+- Telegram の写真と画像ドキュメントは OpenCode のファイルパートとして転送されます。
+- Telegram の音声メッセージは未対応で、ローカライズされた拒否メッセージを返します。
 
 ## 開発
 

package/README.md

@@ -2,24 +2,30 @@
 
 A Telegram plugin for driving [OpenCode](https://opencode.ai) from chat.
 
-[English](./README.md) | [简体中文](./README.zh-CN.md)
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
 
 > This project is not built by the OpenCode team and is not affiliated with them.
 
-## What It Does
+## Overview
 
 `opencode-tbot` lets you operate OpenCode from Telegram.
 
 - Text messages are forwarded to the active OpenCode session.
-- Telegram images are uploaded as OpenCode file parts.
-- Telegram voice messages are explicitly rejected with a localized error reply.
-- Permission requests raised by OpenCode can be approved or rejected directly from Telegram inline buttons.
+- Telegram photos and image documents are uploaded as OpenCode file parts.
+- Telegram voice messages are explicitly rejected with a localized reply.
+- Permission requests raised by OpenCode can be approved or rejected from Telegram inline buttons.
 - Session completion and error events can be reported back to the bound Telegram chat.
-- Chat state is stored in a JSON state file that works in both Node and Bun runtimes.
+- Chat bindings are stored in a JSON state file.
+
+## Requirements
+
+- A running OpenCode host process that loads the plugin.
+- A Telegram bot token.
+- Node.js `>=22.12.0` for the CLI and local development workflow.
 
 ## Install
 
-Run:
+Recommended install:
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- install
@@ -39,23 +45,34 @@ Update the registered npm plugin spec in OpenCode:
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
-Remove a legacy local npm install if OpenCode is showing the plugin as a `file:///.../node_modules/...` path:
+### CLI Options
 
-```bash
-npm uninstall opencode-tbot
-```
+`install` supports:
+
+- `--bot-token <token>` set the Telegram bot token non-interactively
+- `--telegram-api-root <url>` override the Telegram Bot API root
+- `--plugin-spec <spec>` register a custom npm plugin spec
+- `--skip-register` only rewrite plugin config without touching OpenCode plugin registration
+- `--home-dir <path>` use a custom home directory
+
+`update` supports:
+
+- `--plugin-spec <spec>`
+- `--home-dir <path>`
 
 ## Configuration
 
-The runtime config is loaded in this order:
+Runtime config is loaded in this order:
 
-1. global defaults from `~/.config/opencode/opencode-tbot/config.json`
-2. project overrides from `<worktree>/tbot.config.json`
+1. Global defaults from `~/.config/opencode/opencode-tbot/config.json`
+2. Project overrides from `<worktree>/tbot.config.json`
 
 Project config is merged on top of the global config. `telegram` and `state` are deep-merged by section.
 
 Legacy `openrouter` voice-transcription settings are ignored at runtime. When the installer rewrites the config, it removes them.
 
+The repository also includes [tbot.config.example.json](./tbot.config.example.json) as a minimal reference.
+
 ### Example `tbot.config.json`
 
 ```json
@@ -82,29 +99,25 @@ Legacy `openrouter` voice-transcription settings are ignored at runtime. When th
 | `state.path` | No | `./data/opencode-tbot.state.json` | JSON state file path, resolved relative to the current OpenCode worktree. |
 | `logLevel` | No | `info` | Plugin log level. Logs are emitted through `client.app.log()`. |
 
-## Runtime Expectations
-
-Required:
-
-- `telegram.botToken`
-
-Optional:
+### Notes
 
-- `telegram.allowedChatIds`
-- `telegram.apiRoot`
-- `state.path`
-- `logLevel`
+- `state.path` is resolved relative to the current OpenCode worktree.
+- If `telegram.allowedChatIds` is left empty, the bot accepts messages from any chat. Restrict it in production.
+- Permission approvals and session notifications are handled through plugin hooks.
+- `/language` currently supports English, Simplified Chinese, and Japanese.
 
-Notes:
+## Quick Start
 
-- `state.path` defaults to `./data/opencode-tbot.state.json` and is resolved relative to the current OpenCode worktree.
-- Logs are emitted through `client.app.log()`.
-- Permission approvals and session notifications are handled through plugin hooks.
+1. Install the plugin with `npm exec --package opencode-tbot@latest opencode-tbot -- install`.
+2. Set `telegram.allowedChatIds` in `tbot.config.json` if you want to restrict the bot to specific chats.
+3. Start OpenCode in the target worktree so the plugin runtime can load.
+4. In Telegram, run `/status` to verify the connection.
+5. Run `/new [title]` or send a text message directly to start working.
 
 ## Commands
 
 - `/start` show a short welcome message and quick-start steps
-- `/status` show aggregated OpenCode health, path, LSP, and MCP status
+- `/status` show aggregated OpenCode health, path, plugin, LSP, and MCP status
 - `/new [title]` create a new OpenCode session
 - `/agents` or `/agent` list available agents and switch the active one
 - `/sessions` list available sessions and switch the active one
@@ -112,7 +125,11 @@ Notes:
 - `/model` or `/models` list available models and switch the active one
 - `/language` switch the bot display language
 
-Any non-command text message is treated as a prompt and sent to OpenCode. Telegram images are forwarded as OpenCode file parts. Telegram voice messages are not supported and receive a localized rejection reply.
+Message handling:
+
+- Non-command text is treated as a prompt and sent to OpenCode.
+- Telegram photos and image documents are forwarded as OpenCode file parts.
+- Telegram voice messages are not supported and receive a localized rejection reply.
 
 ## Development
 

package/README.zh-CN.md

@@ -2,24 +2,30 @@
 
 一个通过 Telegram 驱动 [OpenCode](https://opencode.ai) 的插件。
 
-[English](./README.md) | [简体中文](./README.zh-CN.md)
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
 
 > 本项目并非由 OpenCode 团队开发，也不隶属于 OpenCode 官方。
 
-## 项目说明
+## 项目概览
 
 `opencode-tbot` 允许你直接在 Telegram 中操作 OpenCode。
 
-- 文本消息会转发到当前 OpenCode 会话。
-- Telegram 图片会作为 OpenCode 文件片段上传。
+- 文本消息会转发到当前激活的 OpenCode 会话。
+- Telegram 照片和图片文档会作为 OpenCode 文件片段上传。
 - Telegram 语音消息会被明确拒绝，并返回本地化提示。
 - OpenCode 触发的权限请求可以直接在 Telegram 内联按钮中批准或拒绝。
-- 会话完成和错误事件可以主动回推到绑定的 Telegram chat。
-- 聊天状态通过 JSON 状态文件持久化，可兼容 Node 和 Bun 运行环境。
+- 会话完成和错误事件可以回推到绑定的 Telegram chat。
+- 聊天绑定状态通过 JSON 状态文件持久化。
+
+## 环境要求
+
+- 一个正在运行、并会加载该插件的 OpenCode Host 进程。
+- 一个 Telegram bot token。
+- Node.js `>=22.12.0`，用于 CLI 和本地开发流程。
 
 ## 安装
 
-执行：
+推荐安装方式：
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- install
@@ -39,11 +45,20 @@ npm exec --package opencode-tbot@latest opencode-tbot -- --version
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
-如果 OpenCode 把插件显示成 `file:///.../node_modules/...` 路径，可删除旧的本地 npm 安装：
+### CLI 参数
 
-```bash
-npm uninstall opencode-tbot
-```
+`install` 支持：
+
+- `--bot-token <token>` 非交互式写入 Telegram bot token
+- `--telegram-api-root <url>` 覆盖 Telegram Bot API 根地址
+- `--plugin-spec <spec>` 注册自定义 npm 插件 spec
+- `--skip-register` 只重写插件配置，不改动 OpenCode 的插件注册
+- `--home-dir <path>` 使用自定义 home 目录
+
+`update` 支持：
+
+- `--plugin-spec <spec>`
+- `--home-dir <path>`
 
 ## 配置
 
@@ -54,7 +69,9 @@ npm uninstall opencode-tbot
 
 项目配置会覆盖全局默认值；`telegram` 和 `state` 会按分段进行深合并。
 
-遗留的 `openrouter` 语音转写配置在运行时会被忽略；安装器重写配置时会自动清理这些字段。
+遗留的 `openrouter` 语音转写配置在运行时会被忽略；安装器重写配置时也会自动移除这些字段。
+
+仓库内还提供了 [tbot.config.example.json](./tbot.config.example.json) 作为最小配置参考。
 
 ### `tbot.config.json` 示例
 
@@ -82,29 +99,25 @@ npm uninstall opencode-tbot
 | `state.path` | 否 | `./data/opencode-tbot.state.json` | JSON 状态文件路径，相对当前 OpenCode worktree 解析。 |
 | `logLevel` | 否 | `info` | 插件日志级别。日志统一通过 `client.app.log()` 上报。 |
 
-## 运行时约定
-
-必填：
+### 说明
 
-- `telegram.botToken`
+- `state.path` 会相对当前 OpenCode worktree 解析。
+- 如果 `telegram.allowedChatIds` 为空，bot 会接受任意 chat 的消息；生产环境建议显式限制。
+- 权限审批和会话通知通过插件 hook 处理。
+- `/language` 当前支持 English、简体中文、日本語。
 
-可选：
+## 快速开始
 
-- `telegram.allowedChatIds`
-- `telegram.apiRoot`
-- `state.path`
-- `logLevel`
-
-说明：
-
-- `state.path` 默认是 `./data/opencode-tbot.state.json`，并相对当前 OpenCode worktree 解析。
-- 日志通过 `client.app.log()` 统一输出。
-- 权限审批和会话通知由插件 hook 处理。
+1. 使用 `npm exec --package opencode-tbot@latest opencode-tbot -- install` 安装插件。
+2. 如果你只想允许特定聊天使用 bot，请在 `tbot.config.json` 中设置 `telegram.allowedChatIds`。
+3. 在目标 worktree 中启动 OpenCode，让插件运行时被加载。
+4. 在 Telegram 中执行 `/status` 验证连接是否正常。
+5. 执行 `/new [title]`，或者直接发送文本消息开始使用。
 
 ## 命令
 
 - `/start` 显示简短欢迎信息和快速开始说明
-- `/status` 显示 OpenCode 健康状态、路径、LSP 和 MCP 信息
+- `/status` 显示 OpenCode 健康状态、路径、插件、LSP 和 MCP 信息
 - `/new [title]` 创建新的 OpenCode 会话
 - `/agents` 或 `/agent` 列出可用 agent 并切换当前 agent
 - `/sessions` 列出会话并切换当前会话
@@ -112,7 +125,11 @@ npm uninstall opencode-tbot
 - `/model` 或 `/models` 列出可用模型并切换当前模型
 - `/language` 切换 bot 显示语言
 
-任意非命令文本都会被当作 prompt 发送给 OpenCode。图片会作为 OpenCode 文件片段上传。Telegram 语音消息当前不受支持，bot 会直接返回本地化拒绝提示。
+消息处理规则：
+
+- 任意非命令文本都会被当作 prompt 发送给 OpenCode。
+- Telegram 照片和图片文档会作为 OpenCode 文件片段上传。
+- Telegram 语音消息当前不受支持，bot 会直接返回本地化拒绝提示。
 
 ## 开发
 
@@ -140,7 +157,7 @@ pnpm test
 
 ### 我需要一个正在运行的 OpenCode 实例吗？
 
-需要。这一仓库提供的是 Telegram 集成层，依赖加载它的 OpenCode Host 进程。
+需要。这个仓库提供的是 Telegram 集成层，依赖加载它的 OpenCode Host 进程。
 
 ### 这是 OpenCode 官方项目吗？