opencode-zh-plugin

OpenCode 中文增强插件 — 通过官方 Plugin + Skill 机制实现 AI 回复中文化与 TUI 界面汉化。

配套工具：opencode-zh-desktop — 基于 CDP 的 Desktop 界面注入汉化。

English

工作原理

┌─────────────────────────────────────────────────┐
│              opencode-zh-plugin 架构              │
├─────────────────────────────────────────────────┤
│                                                  │
│  Server Plugin (./server)                        │
│  ┌──────────────────────────────────────────┐   │
│  │ experimental.chat.system.transform       │   │
│  │   → 注入 <language_directive> 到 system   │   │
│  │   → AI 全部输出（think/response）切换为中文 │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  TUI Plugin (./tui)                              │
│  ┌──────────────────────────────────────────┐   │
│  │ api.slots.register()                     │   │
│  │   → home_logo:   中文欢迎语               │   │
│  │   → home_footer: 中文帮助提示             │   │
│  │   → home_bottom: 中文使用提示             │   │
│  │   → sidebar_title: 中文"会话"标题         │   │
│  ├──────────────────────────────────────────┤   │
│  │ api.command.register()                   │   │
│  │   → /zh        启用中文模式               │   │
│  │   → /zh-off    关闭中文模式               │   │
│  │   → /zh-cn     切换简体中文               │   │
│  │   → /zh-tw     切换繁體中文               │   │
│  │   → /zh-status  查看语言设置              │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  Skill (skills/chinese-locale/SKILL.md)          │
│  ┌──────────────────────────────────────────┐   │
│  │ 中文交互规范（标点、术语、注释语言等）     │   │
│  │ 安装到 ~/.config/opencode/skills/ 后       │   │
│  │ agent 可按需加载作为行为参考              │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
└─────────────────────────────────────────────────┘

效果图

TUI 首页

TUI 中文模式

AI 中文推理

覆盖范围

表面	覆盖	说明
AI 回复语言（含推理过程）	✅	system.transform 注入中文指令
TUI 插槽区域	✅	home_logo / home_footer / home_bottom / sidebar_title
TUI slash 命令	✅	/zh 系列命令
TUI 硬编码字符串	❌	需上游 PR（#37434 被标 Not planned）
Desktop (Electron) UI	⚠️	配合 opencode-zh-desktop 使用
文档站点	❌	需 fork 或上游 PR

环境要求

项目	要求
OpenCode	>= 1.18.0
Node.js	>= 18.0.0（推荐 >= 20.0.0）

注意：本插件依赖 OpenCode 1.18.0 引入的 experimental.chat.system.transform hook，低版本无法生效。

组合覆盖（配合 opencode-zh-desktop）

层面	opencode-zh-plugin	opencode-zh-desktop
AI 回复 + 推理过程	✅	—
TUI 插槽 + 斜杠命令	✅	—
Desktop 菜单栏	—	✅
Desktop 子菜单	—	✅
Desktop 设置/对话框	—	✅
TUI/CLI 硬编码字符串	❌	❌
系统对话框	❌	❌

安装

方式一：opencode plugin add（推荐）

opencode plugin add opencode-zh-plugin

方式二：手动配置 opencode.json

在 ~/.config/opencode/opencode.json（全局）或项目目录 opencode.json 中添加：

{
  "plugin": [
    [
      "opencode-zh-plugin",
      {
        "enabled": true,
        "locale": "zh-CN",
        "systemPrompt": true,
        "tuiSlots": true,
        "commands": true
      }
    ]
  ]
}

方式三：从源码安装（本地开发）

git clone https://github.com/mike652638/opencode-zh-plugin.git
cd opencode-zh-plugin
bun install

在 opencode.json 中使用 file:// 引用：

{
  "plugin": [
    ["file://./opencode-zh-plugin", { "locale": "zh-CN" }]
  ]
}

安装 Skill（可选）

将 skills/chinese-locale/ 目录复制到 ~/.config/opencode/skills/：

cp -r skills/chinese-locale ~/.config/opencode/skills/

配置选项

选项	类型	默认值	说明
enabled	boolean	true	总开关
locale	"zh-CN" | "zh-TW"	"zh-CN"	中文变体（简体/繁体）
systemPrompt	boolean	true	注入中文回复指令到 system prompt
tuiSlots	boolean	true	替换 TUI 界面插槽为中文
commands	boolean	true	注册 /zh 系列 slash 命令

TUI 命令

命令	别名	说明
/zh	/chinese	启用中文模式
/zh-off	/chinese-off	关闭中文模式
/zh-cn	/chinese-cn	切换到简体中文
/zh-tw	/chinese-tw	切换到繁體中文
/zh-status	/chinese-status	查看当前语言设置

繁體中文

将 locale 设为 "zh-TW" 即可启用繁體中文模式：

{
  "plugin": [
    ["opencode-zh-plugin", { "locale": "zh-TW" }]
  ]
}

局限性

1. TUI 硬编码字符串无法覆盖：OpenCode TUI 的原生错误提示、帮助文本等硬编码英文字符串没有字符串级 override 机制，只能通过上游 PR 修复
2. Desktop UI 需配套工具：Electron 桌面应用的界面翻译需配合 opencode-zh-desktop 通过 CDP 注入方案实现
3. locale 切换需重启：通过 /zh-cn / /zh-tw 命令切换后，TUI 界面立即更新，但 AI 回复语言的切换需要更新 opencode.json 并重启 OpenCode
4. 不修改 OpenCode 源码：本插件完全通过官方 Plugin API 工作，零侵入

项目结构

opencode-zh-plugin/
├── package.json              # npm 包配置（exports["./server"] + exports["./tui"]）
├── tsconfig.json             # TypeScript 配置（SolidJS JSX）
├── src/
│   ├── server.ts             # Server plugin 入口
│   ├── tui.tsx               # TUI plugin 入口
│   ├── config.ts             # 插件选项 schema 与默认值
│   ├── locale/
│   │   └── strings.ts        # 中文字符串（简体 + 繁体）
│   ├── server/
│   │   └── system-transform.ts  # system.transform hook 实现
│   └── tui/
│       ├── slots.tsx         # TUI slot 替换组件
│       └── commands.ts       # 中文 slash 命令
├── skills/
│   └── chinese-locale/
│       └── SKILL.md          # Skill 定义
├── examples/
│   └── opencode.json         # 示例配置
└── README.md

技术栈

• Server Plugin：experimental.chat.system.transform hook — 每次对话时向 system prompt 注入中文指令
• TUI Plugin：api.slots.register() + api.command.register() — 替换 TUI 插槽 + 注册命令
• TUI 渲染：@opentui/solid JSX（<box>, <text> 内禀元素）
• Skill：Markdown 指令文件，agent 按需加载

相关项目

• opencode-zh-desktop — CDP 注入式 Desktop 界面汉化工具
• OpenCode — AI 编程 CLI
• OpenCode Desktop — 桌面应用

许可证

MIT © 2026 mike652638