# my-opencode-toolkit 中文文档

规范地址：https://npmcn.com/package/my-opencode-toolkit/

版本：0\.8\.1
npm 元数据更新时间：2026-11-04T04:40:39.951Z
中文译文更新时间：2026-11-04T05:39:05.195Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/my-opencode-toolkit
原文对照：https://npmcn.com/package/my-opencode-toolkit/?lang=original
项目主页：https://github.com/1cyberlangke1/my-opencode-toolkit#readme
源码仓库：https://github.com/1cyberlangke1/my-opencode-toolkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：524 kB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：solid-js \>=1\.9\.0，@opentui/core \>=0\.5\.17，@opentui/solid \>=0\.5\.17，@opencode/plugin ^2\.0\.32
- 首次发布：2026-10-22T13:50:46.771Z
- 最新版本发布：2026-11-04T04:40:39.639Z
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

OpenCode 插件：系统通知、持久目标、定时任务与 TUI 面板

## 安装

```sh
npm install my-opencode-toolkit
```

也可以使用：`pnpm add my-opencode-toolkit`、`yarn add my-opencode-toolkit`、`bun add my-opencode-toolkit`

## README

# my-opencode-toolkit

[![ci](https://github.com/1cyberlangke1/my-opencode-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/1cyberlangke1/my-opencode-toolkit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/my-opencode-toolkit)](https://www.npmjs.com/package/my-opencode-toolkit) [![license](https://img.shields.io/npm/l/my-opencode-toolkit)](https://npmcn.com/package/my-opencode-toolkit/LICENSE)

OpenCode v2 插件，提供系统桌面通知、持久目标追踪（Goal）、定时与循环任务（Cron / Loop）以及 TUI 状态面板。

## 环境要求

-   OpenCode `2.x`
-   Node `>= 20`
-   Windows / macOS / Linux

## 安装

在全局或项目级 `opencode.json` 中将插件添加到 `plugins` 数组：

```json
{
  "plugins": ["my-opencode-toolkit"]
}
```

本地开发调试时，也可以直接指定本地目录路径：

```json
{
  "plugins": ["./path/to/my-opencode-toolkit"]
}
```

配置后重启 OpenCode 即可生效。

## 功能说明

### 系统桌面通知

-   当会话空闲（任务完成）、请求权限（`permission.asked`）或模型提问（`question`）时发送系统通知。
-   跨平台支持：Windows Toast（PowerShell）、macOS（osascript）、Linux（notify-send）。
-   当系统处于静音、专注助手拦截或缺少对应命令时静默跳过，不影响正常交互。

### 持久目标（Goal）

-   为会话设定高层目标后，会在每次空闲边界自动注入续作提示，直到任务标记完成或遇到明确阻塞。
-   自动累计每一步的 Token 输入、输出与缓存消耗；超出预设 Token 预算时自动暂停并等待确认。
-   用户手动打断时自动暂停；对子代理会话完全隔离，避免递归干扰。

### 定时任务与循环（Cron / Loop）

-   支持标准 5 字段 Cron 表达式（本地时区），支持创建重复或一次性任务。
-   支持循环任务（固定时间间隔或由模型动态决策下一次唤醒时机）。
-   仅在会话空闲时触发，会话繁忙或有待处理的用户输入时自动顺延，避免打断交互。

### 时间感知（Time）

-   每隔 N 步（`time.intervalSteps`，默认 3）向会话注入一条当前时间的合成消息，模型随时知道现在几点。
-   注入文本是纯格式化时间串（无语言前缀），格式模板与时区可在设置菜单自定义。
-   注入不触发新一轮对话（`resume: false`），只在会话活跃的 step 边界搭车送达。
-   子代理会话不注入；Plan 模式照常注入。

### TUI 状态面板

-   在侧栏展示当前持久目标、生效中的定时任务、工具调用频次与子代理运行状态。
-   在底部状态栏实时显示累计 Token 输入、输出、缓存及命中率。
-   提供图形化设置菜单（`/my-opencode-toolkit`），支持热切换所有开关与参数。
-   设置菜单直接显示当前版本并检查 npm 最新版；发现新版后加星标与警示色，确认后在 TUI 内原地显示更新进度，完成后提示重启 OpenCode，不弹出独立 shell 窗口。

### 自定义提供商管理（Provider）

-   专为第三方中转站、私有聚合网关与本地自建模型（vLLM / Ollama / LM Studio 等）设计，彻底摆脱手写复杂 JSON 的烦恼。
-   一键自动拉取：输入 Base URL 与可选 API Key 后，自动从 `/models` 端点拉取模型列表，并与 OpenCode 已知模型库进行模糊相似度匹配，自动填入上下文窗口、最大输出和工具调用能力；未匹配模型自动应用 128k 纯文本兜底。
-   能力 Emoji 化：直观使用 `🪟 128k`、`🛠️`（工具）、`👁️`（视觉）、`💬`（文本）紧凑呈现模型特征。
-   支持细粒度微调与单独重新匹配；支持手动添加自定义模型。
-   四重铁壁安全写入：基于 `jsonc-parser` 进行 AST 局部修改，100% 完整保留原有配置中的注释与缩进；前置语法错误拦截与内存自检、临时文件原子覆盖，绝不写坏 `opencode.json`。

## 命令与工具

### 斜杠命令（用户交互）

| 命令 | 说明 |
| --- | --- |
| `/my-opencode-toolkit` | 打开插件图形化设置菜单 |
| `/provider` | 打开自定义提供商管理菜单，添加或微调中转与本地模型 |
| `/goal <objective>` | 设置或覆盖当前会话的持久目标 |
| `/goal` | 查看当前目标状态与进度 |
| `/goal pause` / `resume` / `clear` / `edit` | 暂停 / 恢复 / 清除 / 编辑当前目标 |
| `/cron <expr> <prompt>` | 创建重复定时任务（5 字段 cron，本地时区） |
| `/cron once <expr> <prompt>` | 创建一次性定时任务 |
| `/cron list` | 查看当前会话的定时任务列表 |
| `/cron delete <id>` | 按 ID 删除指定的定时任务 |
| `/loop [interval] [prompt]` | 启动循环任务（不带间隔则为 dynamic 动态决策模式） |
| `/loop stop` | 停止当前会话的所有循环任务 |

### Agent 工具箱（模型调用）

| 工具 | 说明 |
| --- | --- |
| `create_goal` / `get_goal` / `update_goal` | 创建、查询当前目标以及更新目标状态（完成或阻塞） |
| `cron_create` / `cron_list` / `cron_delete` | 创建、查询与删除定时任务 |
| `schedule_wakeup` | 动态循环模式下设置下一次唤醒间隔时间 |

## 配置项

所有配置项均保存在 OpenCode 的插件存储中，推荐通过 `/my-opencode-toolkit` 设置菜单修改，也可在 `opencode.json` 的 `options` 字段作为初始默认值传入：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `lang` | `auto` | 界面语言（`auto` / `zh` / `en`） |
| `notification.enabled` | `true` | 通知总开关 |
| `notification.onComplete` | `true` | 会话空闲/任务完成时通知 |
| `notification.onQuestion` | `true` | 模型提问时通知 |
| `notification.onPermission` | `true` | 请求授权时通知 |
| `notification.onlyMainSession` | `true` | 仅通知主会话，忽略子代理事件 |
| `goal.enabled` | `false` | 是否启用持久目标功能（已弃用，官方已内置 `/goal`） |
| `goal.showInSidebar` | `true` | 是否在侧栏展示目标进度 |
| `scheduling.enabled` | `true` | 是否启用定时任务与循环功能 |
| `scheduling.showInSidebar` | `true` | 是否在侧栏展示定时任务 |
| `sidebar.showTools` | `false` | 是否在侧栏展示工具调用计数 |
| `sidebar.showSubagents` | `false` | 是否在侧栏展示子代理详情 |
| `contextStats.enabled` | `true` | 是否在底部状态栏展示 Token 统计 |
| `time.enabled` | `true` | 是否启用时间感知注入 |
| `time.mode` | `interval` | 触发模式：`interval` 按时间间隔；`steps` 按步数 |
| `time.intervalSeconds` | `300` | 按时间间隔模式下的注入间隔（秒数，最短 30 秒） |
| `time.intervalSteps` | `3` | 按步数模式下的注入间隔（步数，最小 1 步） |
| `time.format` | `YYYY-MM-DD HH:mm:ss` | 时间格式模板（token：`YYYY MM DD HH mm ss`） |
| `time.timezone` | （空） | IANA 时区名；空 = 宿主时区，非法值回落宿主 |
| `editor.enabled` | Windows 为 `true`，其它为 `false` | 是否启用外部编辑器支持（仅 Windows 默认开启，自动注入环境变量） |
| `editor.command` | Windows 为 `notepad`，其它为空 | 外部编辑器命令（如 `notepad`、`code --wait`、`nvim`） |
| `editor.showHint` | `true` | 是否在输入框底栏左侧显示外部编辑器快捷键提示 |

## 数据与隐私

-   数据均存放在 OpenCode 插件专有存储中，不创建独立的本地数据库文件。
-   不采集遥测数据；仅在用户主动打开“检查更新”时查询 npm registry，系统通知命令也不会上传会话内容。
-   会话删除时会自动清理该会话关联的所有目标、定时任务、循环、统计与角色缓存。

## 常见排查

### 插件未加载

-   确认 `opencode.json` 中配置的是 `plugins` 数组，而不是单数 `plugin`。
-   运行 `opencode plugin list` 查看插件是否已正常识别。
-   重启 OpenCode（已打开的既有会话不会动态重建工具列表，请在新会话中验证）。

### TUI 未显示侧栏或设置菜单

-   TUI 扩展仅在交互式 TUI 终端模式下加载，`opencode run` 等非交互模式不渲染侧栏。
-   若热重载后未生效，请完整重启 TUI 进程。

### 未收到桌面通知

-   检查操作系统通知设置是否允许通知，以及系统是否处于“专注助手 / 勿扰模式”。
-   确认系统中对应的通知执行环境正常（Windows 需 `powershell.exe`，macOS 需 `osascript`，Linux 需 `notify-send`）。

### 定时任务未按时触发

-   检查会话是否长期处于 active 目标进行中（定时任务会自动让路以避免打扰）。
-   Plan 模式下会顺延跳过任务，切回 Build 模式后按计划恢复。
-   确认定时任务是否已超过 7 天最大有效期，可通过 `/cron list` 查看当前任务状态。

## 本地开发

```bash
pnpm install
pnpm check      # 类型检查、代码检查、单元测试与打包校验
pnpm test:e2e   # 端到端自动化集成测试
pnpm test:e2e:update  # 真实 TUI 更新入口（本地 registry + 假更新命令）
```

发版在 GitHub Actions 手动运行 `publish` workflow，并选择 `patch`、`minor` 或 `major`；workflow 会同步版本文件、跑完整检查、提交、更新 `master`、打 tag 并发布 npm。

## 许可证

[MIT](https://npmcn.com/package/my-opencode-toolkit/LICENSE)

## 常见问题

### my-opencode-toolkit 是什么？

OpenCode 插件：系统通知、持久目标、定时任务与 TUI 面板

### 如何安装 my-opencode-toolkit？

在项目目录运行 npm install my-opencode-toolkit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opencode/plugin（^2\.0\.32）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### my-opencode-toolkit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/my-opencode-toolkit 是否存在。

### my-opencode-toolkit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### my-opencode-toolkit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### my-opencode-toolkit 可以商用吗？

my-opencode-toolkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### my-opencode-toolkit 还在维护吗？

最新版本 0\.8\.1 发布于 2026/11/04（今天）；至今共发布 44 个版本，其中过去 12 个月发布了 44 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。