opencode-tbot 0.1.33 → 0.1.34

package/README.zh-CN.md

@@ -4,27 +4,28 @@
 
 [English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
 
-> 本项目并非由 OpenCode 官方团队开发。
+> 本项目并非由 OpenCode 官方团队开发，也不隶属于 OpenCode 官方。
 
 ## 概览
 
-`opencode-tbot` 允许你直接在 Telegram 中操作 OpenCode。
+`opencode-tbot` 让你可以在 Telegram 中直接操作 OpenCode，并为每个聊天维护一份绑定状态。
 
-- 文本消息会转发到当前 OpenCode 会话。
-- Telegram 图片会作为 OpenCode 文件片段上传。
-- 图片轮次会在临时 fork 会话中执行，避免后续纯文本上下文被污染。
-- Telegram 语音消息会被明确拒绝。
-- OpenCode 的权限请求可以直接在 Telegram 中审批。
+- 纯文本消息会转发到当前 OpenCode 会话。
+- Telegram 照片和图片文档会作为 OpenCode 文件片段上传。
+- 图片轮次会在临时 fork 会话中执行，避免后续纯文本对话继承图片上下文。
+- OpenCode 发起的权限请求可以直接在 Telegram 内联按钮里审批或拒绝。
 - 会话错误事件可以回推到已绑定的 Telegram chat。
-- 聊天绑定状态会保存在 JSON 状态文件中。
+- 语音消息会被明确拒绝，并返回本地化提示。
+- 聊天绑定和会话选择状态会保存在 JSON 状态文件中。
 
 ## 环境要求
 
 - 一个正在运行、并会加载该插件的 OpenCode Host 进程。
 - 一个 Telegram bot token。
-- Node.js `>=22.12.0`。
+- Node.js `>=22.12.0`，用于 CLI 和本地开发。
+- `pnpm`，用于仓库开发。
 
-## 安装
+## 安装与更新
 
 推荐安装方式：
 
@@ -32,22 +33,33 @@
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-安装器会全局注册插件、更新实际生效的 OpenCode 全局配置文件、写入默认运行时配置，并打印 OpenCode 配置路径、插件配置路径与默认日志目录。
+安装器会：
+
+- 在全局 OpenCode 插件列表中注册 `opencode-tbot@latest`
+- 更新实际生效的 OpenCode 全局配置文件
+- 写入或合并全局插件运行时配置
+- 打印 OpenCode 配置路径、插件配置路径和默认插件日志目录
 
 如果 `~/.config/opencode/opencode.jsonc` 已存在，安装器会优先更新它；否则会使用 `~/.config/opencode/opencode.json`。
 
-查看 CLI 版本：
+查看已安装 CLI 版本：
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- --version
 ```
 
-更新 OpenCode 中注册的 npm 插件 spec：
+只更新 OpenCode 中注册的 npm 插件 spec，而不改 bot token：
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
+`install` 是默认命令。例如，下面这种写法也适合非交互安装：
+
+```bash
+npm exec --package opencode-tbot@latest opencode-tbot -- --bot-token <token>
+```
+
 ### CLI 参数
 
 `install` 支持：
@@ -55,7 +67,7 @@ npm exec --package opencode-tbot@latest opencode-tbot -- update
 - `--bot-token <token>` 非交互写入 Telegram bot token
 - `--telegram-api-root <url>` 覆盖 Telegram Bot API 根地址
 - `--plugin-spec <spec>` 注册自定义 npm 插件 spec
-- `--skip-register` 只重写插件配置，不改 OpenCode 插件注册
+- `--skip-register` 只重写插件配置，不修改 OpenCode 插件注册
 - `--home-dir <path>` 使用自定义 home 目录
 
 `update` 支持：
@@ -65,15 +77,23 @@ npm exec --package opencode-tbot@latest opencode-tbot -- update
 
 ## 配置
 
-运行时配置只从 `~/.config/opencode/opencode-tbot/config.json` 加载。
+运行时配置只会从以下路径加载：
 
-OpenCode 的插件注册信息保存在全局 OpenCode 配置中：优先使用 `~/.config/opencode/opencode.jsonc`，否则使用 `~/.config/opencode/opencode.json`。
+- `~/.config/opencode/opencode-tbot/config.json`
 
-遗留的 `<worktree>/tbot.config.json` 会在运行时被忽略；如果检测到，插件会记录一条警告，提示你把配置迁移到全局文件。
+OpenCode 的插件注册信息保存在全局 OpenCode 配置中：
 
-遗留的 `openrouter` 语音转写配置会在运行时被忽略；安装器重写配置时也会自动移除它们。
+- 如果存在，使用 `~/.config/opencode/opencode.jsonc`
+- 否则使用 `~/.config/opencode/opencode.json`
 
-### 全局 `config.json` 示例
+本插件不会从 `.env` 读取运行时配置，请使用全局 JSON 配置文件。
+
+遗留行为说明：
+
+- `<worktree>/tbot.config.json` 会在运行时被忽略；如果检测到，插件会记录警告，提示你迁移配置
+- 遗留的 `openrouter` 语音转写配置会在运行时被忽略；安装器重写配置时也会自动移除
+
+### `config.json` 示例
 
 ```json
 {
@@ -112,69 +132,77 @@ OpenCode 的插件注册信息保存在全局 OpenCode 配置中：优先使用
 
 | 字段 | 必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `telegram.botToken` | 是 | - | Telegram bot token。通常由安装器写入。 |
+| `telegram.botToken` | 是 | - | Telegram bot token。通常由安装器写入全局插件配置。 |
 | `telegram.allowedChatIds` | 否 | `[]` | 允许访问的 Telegram chat ID。为空时接受任意 chat。 |
-| `telegram.apiRoot` | 否 | `https://api.telegram.org` | Telegram Bot API 根地址。 |
+| `telegram.apiRoot` | 否 | `https://api.telegram.org` | Telegram Bot API 根地址，适合测试或自建网关。 |
 | `state.path` | 否 | `./data/opencode-tbot.state.json` | JSON 状态文件路径，相对当前 OpenCode worktree 解析。 |
-| `prompt.waitTimeoutMs` | 否 | `1800000` | 单次异步 prompt 生命周期的最大等待时间。 |
-| `prompt.pollRequestTimeoutMs` | 否 | `15000` | 每次恢复轮询请求的超时时间。 |
-| `prompt.recoveryInactivityTimeoutMs` | 否 | `120000` | 仅在 OpenCode 长时间没有新进展时生效的恢复超时。 |
-| `logging.level` | 否 | `info` | 结构化日志级别。 |
+| `prompt.waitTimeoutMs` | 否 | `1800000` | 单次异步 prompt 生命周期的总等待上限。 |
+| `prompt.pollRequestTimeoutMs` | 否 | `15000` | 每次向 OpenCode 发起恢复轮询请求时的超时时间。 |
+| `prompt.recoveryInactivityTimeoutMs` | 否 | `120000` | 仅在长时间没有新进展时生效的恢复超时。 |
+| `logging.level` | 否 | `info` | Host 和文件日志共用的结构化日志级别，会规范化为 `debug`、`info`、`warn` 或 `error`。 |
 | `logging.sinks.host` | 否 | `true` | 是否通过 `client.app.log({ body: ... })` 写入 OpenCode Host 日志。 |
 | `logging.sinks.file` | 否 | `true` | 是否写入插件自己的 JSONL 文件日志。 |
-| `logging.file.dir` | 否 | `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot` | 插件日志目录。 |
+| `logging.file.dir` | 否 | `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot` | 插件 JSONL 日志目录。相对路径会基于当前 OpenCode worktree 解析。 |
 | `logging.file.retention.maxFiles` | 否 | `30` | 最多保留多少个插件日志文件。 |
 | `logging.file.retention.maxTotalBytes` | 否 | `314572800` | 插件日志文件总大小上限。 |
-| `logLevel` | 否 | `info` | `logging.level` 的兼容别名。 |
+| `logLevel` | 否 | `info` | `logging.level` 的兼容别名。仍然可用。 |
 
 ### 说明
 
 - `state.path` 会相对当前 OpenCode worktree 解析。
-- Telegram prompt 采用 async-first：插件先提交异步 prompt，再通过消息与状态恢复最终回复。
+- `logging.file.dir` 如果是相对路径，也会相对当前 worktree 解析。
+- Telegram prompt 采用 async-first：插件先提交 `session.promptAsync()`，再通过消息与状态恢复最终回复。
 - 如果 `telegram.allowedChatIds` 为空，bot 会接受任意 chat 的消息；生产环境建议显式限制。
 - 权限审批与会话错误通知通过插件 hooks 处理。
-- `/language` 当前支持 English、简体中文、日语。
-- 默认会双写日志：OpenCode Host 日志 + 插件 JSONL 文件日志。
+- `/language` 当前支持 English、简体中文、日语，并会同步当前 chat 的 Telegram 命令描述。
 - 文件日志默认只记录元数据，不记录 prompt 正文、附件内容、原始 URL 或 secrets。
 
-## 日志
-
-- OpenCode Host 日志目录：`%USERPROFILE%/.local/share/opencode/log`
-- 插件日志目录：`%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`
-- 文件格式：JSONL，每行一条结构化事件
-- 关键关联字段：`runtimeId`、`operationId`、`correlationId`、`updateId`、`chatId`、`sessionId`、`projectId`
-- 常见组件：`runtime`、`telegram`、`opencode`、`prompt`、`plugin-event`、`storage`
-- 默认保留策略：最多 30 个文件，总大小不超过 300 MB
-
 ## 快速开始
 
 1. 运行 `npm exec --package opencode-tbot@latest opencode-tbot -- install`。
-2. 如需限制可访问 chat，在 `~/.config/opencode/opencode-tbot/config.json` 中设置 `telegram.allowedChatIds`。
-3. 在目标 worktree 中启动 OpenCode。
+2. 如果需要限制可访问 chat，在 `~/.config/opencode/opencode-tbot/config.json` 中设置 `telegram.allowedChatIds`。
+3. 在目标 worktree 中启动 OpenCode，让插件运行时被加载。
 4. 在 Telegram 中执行 `/status` 验证连通性。
-5. 执行 `/new [title]`，或者直接发送文本/图片开始使用。
+5. 运行 `/new [title]`，或直接发送文本消息开始使用。
 
 ## 命令
 
-- `/start` 显示欢迎信息和快速开始说明
-- `/status` 显示 OpenCode 健康状态、路径、LSP、MCP 等信息
-- `/new [title]` 创建新会话
-- `/agents` 或 `/agent` 列出并切换 agent
-- `/sessions` 列出并切换会话
-- `/cancel` 取消重命名，或中止当前正在运行的请求
-- `/model` 或 `/models` 列出并切换模型
-- `/language` 切换显示语言
+| 命令 | 作用 |
+| --- | --- |
+| `/start` | 显示欢迎消息和快速开始说明。 |
+| `/status` | 汇总展示 OpenCode 健康状态、版本、工作区路径、插件列表、LSP 状态和 MCP 状态。 |
+| `/new [title]` | 在当前项目中创建一个新的 OpenCode 会话。 |
+| `/agents` 或 `/agent` | 列出可用 Agent 并切换当前 Agent。 |
+| `/sessions` | 列出可用会话、切换当前会话，并提供重命名操作。 |
+| `/cancel` | 取消待输入的会话重命名，或中止当前会话正在运行的请求。 |
+| `/model` 或 `/models` | 列出可用模型、切换当前模型，并在可用时选择推理级别。 |
+| `/language` | 切换当前 chat 的 bot 显示语言。 |
 
-消息处理规则：
+### 消息行为
 
 - 非命令文本会作为 prompt 发送给 OpenCode。
-- Telegram 图片会作为 OpenCode 文件片段上传。
-- 图片消息会在临时 fork 会话中处理。
-- `/cancel` 会同时中止 OpenCode 会话和本地 Telegram 等待状态。
-- Telegram 语音消息不受支持，会收到本地化拒绝提示。
+- Telegram 照片和图片文档会作为 OpenCode 文件片段转发。
+- 图片附件会在当前会话的临时 fork 中处理，避免污染后续纯文本上下文。
+- `/cancel` 会同时中止 OpenCode 会话请求和本地 Telegram 等待状态，让下一次 prompt 能立即开始。
+- Telegram 语音消息暂不支持，会收到本地化拒绝提示。
+
+## 日志
+
+- OpenCode Host 日志目录：`%USERPROFILE%/.local/share/opencode/log`
+- 插件日志目录：`%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`
+- 文件格式：追加写入的 JSONL，每行一个结构化事件
+- 关联字段：`runtimeId`、`operationId`、`correlationId`、`updateId`、`chatId`、`sessionId`、`projectId`
+- 常见组件：`runtime`、`telegram`、`opencode`、`prompt`、`plugin-event`、`storage`
+- 默认保留策略：最多保留最新 30 个文件，且总大小不超过 300 MB
 
 ## 开发
 
+安装依赖：
+
+```bash
+pnpm install
+```
+
 构建：
 
 ```bash
@@ -187,12 +215,26 @@ pnpm build
 pnpm typecheck
 ```
 
-运行测试：
+运行默认测试集：
 
 ```bash
 pnpm test
 ```
 
+运行最接近 CI 的集成路径：
+
+```bash
+npm install -g opencode-ai
+OPENCODE_HOST_E2E=1 pnpm test
+```
+
+PowerShell 写法：
+
+```powershell
+npm install -g opencode-ai
+$env:OPENCODE_HOST_E2E="1"; pnpm test
+```
+
 正常使用应依赖“全局安装的 npm 插件 + 全局 OpenCode 配置”。本仓库不再默认提供 `.opencode/plugins` bridge。
 
 如果你在本仓库里做源码调试，需要手动创建 `.opencode/plugins/opencode-tbot.ts`：
@@ -207,8 +249,12 @@ export { default } from "../../src/plugin.ts";
 
 ### 需要一个正在运行的 OpenCode 实例吗？
 
-需要。这个仓库只提供 Telegram 集成层，依赖加载它的 OpenCode Host 进程。
+需要。本仓库只提供 Telegram 集成层，依赖加载该插件的 OpenCode Host 进程。
+
+### 为什么 OpenCode 里会显示 `file:///.../node_modules/...` 形式的插件路径？
+
+这通常表示某个本地项目在自己的 `node_modules` 中安装了 `opencode-tbot`。CLI 检测到这种布局时会给出警告。请在那个项目里执行 `npm uninstall opencode-tbot` 移除本地包，然后改用推荐的 `npm exec --package ...` 安装流程。
 
 ### 这是 OpenCode 官方项目吗？
 
-不是。它集成 OpenCode，但不是 OpenCode 官方项目。
+不是。它集成 OpenCode，但并非 OpenCode 官方团队开发。

package/dist/plugin.js

@@ -3120,14 +3120,16 @@ function normalizePermissionReply(value) {
 function extractSessionErrorMessage(error) {
 	if (error instanceof Error && error.message.trim().length > 0) return error.message.trim();
 	if (!isPlainRecord(error)) return null;
+	if (typeof error.message === "string" && error.message.trim().length > 0) return error.message.trim();
 	if (isPlainRecord(error.data) && typeof error.data.message === "string" && error.data.message.trim().length > 0) return error.data.message.trim();
 	return asNonEmptyString(error.name);
 }
 function normalizeForegroundSessionError(error) {
 	if (error instanceof Error) return error;
-	if (isPlainRecord(error) && typeof error.name === "string" && error.name.trim().length > 0) {
+	if (isPlainRecord(error)) {
 		const normalized = new Error(extractSessionErrorMessage(error) ?? "Unknown session error.");
-		normalized.name = error.name.trim();
+		const normalizedName = asNonEmptyString(error.name);
+		if (normalizedName) normalized.name = normalizedName;
 		if (isPlainRecord(error.data)) normalized.data = error.data;
 		return normalized;
 	}
@@ -3920,14 +3922,18 @@ function normalizeError(error, copy) {
 		message: copy.errors.contextOverflow,
 		cause: extractMessage(error.data) ?? null
 	};
-	if (isNamedError(error, "APIError")) return {
-		message: copy.errors.providerRequest,
-		cause: joinNonEmptyParts([
-			extractMessage(error.data),
-			extractStatusCode(error.data, copy),
-			extractRetryable(error.data, copy)
-		])
-	};
+	if (isNamedError(error, "APIError")) {
+		const providerMessage = extractMessage(error.data);
+		return {
+			message: copy.errors.providerRequest,
+			cause: joinNonEmptyParts([
+				getProviderCompatibilityHint(providerMessage),
+				providerMessage,
+				extractStatusCode(error.data, copy),
+				extractRetryable(error.data, copy)
+			])
+		};
+	}
 	if (isNamedError(error, "NotFoundError")) return {
 		message: copy.errors.notFound,
 		cause: extractMessage(error.data) ?? null
@@ -3945,6 +3951,10 @@ function normalizeError(error, copy) {
 		cause: extractMessage(error) ?? stringifyUnknown(error)
 	};
 }
+function getProviderCompatibilityHint(message) {
+	if (!message) return null;
+	return /tool_choice parameter does not support being set to required or object in thinking mode/iu.test(message) ? "Current model/reasoning mode is incompatible with tool calling. Switch to a compatible model or disable thinking mode." : null;
+}
 function isBadRequestError(error) {
 	return !!error && typeof error === "object" && "success" in error && error.success === false;
 }
@@ -5837,14 +5847,15 @@ function getTelegramBotRuntimeRegistry() {
 //#region src/plugin.ts
 async function ensureTelegramBotPluginRuntime(options) {
 	const runtimeStateHolder = getTelegramBotPluginRuntimeStateHolder();
-	const cwd = resolvePluginRuntimeCwd(options.context);
-	if (runtimeStateHolder.state && runtimeStateHolder.state.cwd !== cwd) {
+	const explicitCwd = resolveExplicitPluginRuntimeCwd(options.context);
+	if (runtimeStateHolder.state && explicitCwd === null) return runtimeStateHolder.state.runtimePromise;
+	if (runtimeStateHolder.state && explicitCwd !== null && runtimeStateHolder.state.cwd !== explicitCwd) {
 		const activeState = runtimeStateHolder.state;
 		runtimeStateHolder.state = null;
 		await disposeTelegramBotPluginRuntimeState(activeState);
 	}
 	if (!runtimeStateHolder.state) {
-		const runtimePromise = startPluginRuntime(options, cwd).then((runtime) => {
+		const runtimePromise = startPluginRuntime(options, resolvePluginRuntimeCwd(options.context), requirePluginClient(options.context)).then((runtime) => {
 			if (runtimeStateHolder.state?.runtimePromise === runtimePromise) runtimeStateHolder.state.runtime = runtime;
 			return runtime;
 		}).catch((error) => {
@@ -5852,7 +5863,7 @@ async function ensureTelegramBotPluginRuntime(options) {
 			throw error;
 		});
 		runtimeStateHolder.state = {
-			cwd,
+			cwd: explicitCwd ?? resolvePluginRuntimeCwd(options.context),
 			runtime: null,
 			runtimePromise
 		};
@@ -5869,7 +5880,7 @@ async function resetTelegramBotPluginRuntimeForTests() {
 	runtimeStateHolder.state = null;
 	await disposeTelegramBotPluginRuntimeState(activeState);
 }
-async function startPluginRuntime(options, cwd) {
+async function startPluginRuntime(options, cwd, client) {
 	const bootstrapApp = options.bootstrapApp ?? bootstrapPluginApp;
 	const prepareConfiguration = options.prepareConfiguration ?? preparePluginConfiguration;
 	const startRuntime = options.startRuntime ?? startTelegramBotRuntime;
@@ -5877,7 +5888,7 @@ async function startPluginRuntime(options, cwd) {
 		cwd,
 		config: options.config
 	});
-	const { config, container } = bootstrapApp(options.context.client, preparedConfiguration.config, { cwd: preparedConfiguration.cwd });
+	const { config, container } = bootstrapApp(client, preparedConfiguration.config, { cwd: preparedConfiguration.cwd });
 	try {
 		if (preparedConfiguration.ignoredProjectConfigFilePath) container.logger.child({ component: "runtime" }).warn({
 			cwd: preparedConfiguration.cwd,
@@ -5904,7 +5915,19 @@ async function startPluginRuntime(options, cwd) {
 	}
 }
 function resolvePluginRuntimeCwd(context) {
-	return context.worktree ?? context.directory ?? process.cwd();
+	return resolveExplicitPluginRuntimeCwd(context) ?? process.cwd();
+}
+function resolveExplicitPluginRuntimeCwd(context) {
+	return normalizePluginRuntimePath(context?.worktree) ?? normalizePluginRuntimePath(context?.directory);
+}
+function requirePluginClient(context) {
+	if (context?.client) return context.client;
+	throw new Error("OpenCode plugin context.client is required.");
+}
+function normalizePluginRuntimePath(value) {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : null;
 }
 async function disposeTelegramBotPluginRuntimeState(state) {
 	await (state.runtime ?? await state.runtimePromise.catch(() => null))?.dispose();