# awesome-codex-subagents-opencode 中文文档

规范地址：https://npmcn.com/package/awesome-codex-subagents-opencode/

版本：0\.2\.1
npm 元数据更新时间：2026-11-03T04:24:41.775Z
中文译文更新时间：2026-11-03T04:36:07.444Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/awesome-codex-subagents-opencode
原文对照：https://npmcn.com/package/awesome-codex-subagents-opencode/?lang=original
项目主页：https://github.com/He-Xun/awesome-codex-subagents-opencode#readme
源码仓库：https://github.com/He-Xun/awesome-codex-subagents-opencode

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

- 包体积（解压后）：694 kB，193 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-11-03T02:46:16.811Z
- 最新版本发布：2026-11-03T04:24:41.219Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

174个Codex子代理定义适用于OpenCode，具有5种语言的语言环境感知描述

## 安装

```sh
npm install awesome-codex-subagents-opencode
```

也可以使用：`pnpm add awesome-codex-subagents-opencode`、`yarn add awesome-codex-subagents-opencode`、`bun add awesome-codex-subagents-opencode`

## README

# awesome-codex-subagents → OpenCode

[English](https://npmcn.com/package/awesome-codex-subagents-opencode/README.md) | **简体中文**

> **174 个专家 agent，一条命令装进 OpenCode。**

![OpenCode 的 @ 菜单，显示 reviewer、debugger 等 agent 及其权限](https://npmcn.com/package/awesome-codex-subagents-opencode/docs/menu-preview.svg)

OpenCode 自带的 subagent 只有 `general` 和 `explore` 两个。当你需要一次真正到位的 PR 级代码审查、一份能落地的威胁建模、一次跨文件的架构重构规划，往往只能靠主 agent 一边读上下文一边现编 —— 既占上下文，质量也不稳定。

这个仓库把它变成了开箱即用的东西：

```bash
npx awesome-codex-subagents-opencode --global
```

装完重启 OpenCode，敲 `@reviewer` 就能让一个只读的审查者独立跑完整个 diff，只把结论 带回你的对话。它不会污染主上下文，也不会顺手改你的文件。不需要 clone，也不需要先装依赖。

## 它解决什么问题

| 痛点 | 这个仓库的做法 |
| --- | --- |
| 长任务把主上下文塞满 | 每个 agent 在独立子会话里跑，只回传结论 |
| 审查类工作容易越界改代码 | 99 个只读 agent 用 `permission` 硬性限制，连写文件都不允许 |
| 换模型就得改一堆配置 | **一个模型都不写死**，subagent 自动继承你当前的模型 |
| `@` 菜单全是英文看不懂 | 中文系统自动装中文描述，也可随时切换 |
| 不知道自己该用哪个 | 按领域分组，从 `debugger` 到 `hipaa-compliance` 都有 |

## 覆盖范围

174 个 agent，覆盖 13 个领域：

| 领域 | 代表 agent |
| --- | --- |
| 核心开发 | `backend-developer` `frontend-developer` `code-mapper` |
| 语言与框架 | `python-pro` `typescript-pro` `golang-pro` `rust-engineer` …31 个 |
| 基础设施 | `kubernetes-specialist` `terraform-engineer` `docker-expert` |
| 质量与安全 | `reviewer` `security-auditor` `debugger` `test-automator` |
| 数据与 AI | `data-engineer` `ml-engineer` `eval-engineer` |
| LLM 工程 | `llm-architect` `prompt-engineer` `mcp-developer` |
| 设计与产品 | `ui-designer` `product-manager` `ux-researcher` |
| 专项领域 | `fintech-engineer` `payment-integration` `blockchain-developer` |
| 合规法务 | `hipaa-compliance` `gdpr-ccpa-compliance` `license-engineer` |

完整清单见 [`agents/`](https://npmcn.com/package/awesome-codex-subagents-opencode/agents)。

* * *

## 快速开始

最快的方式不需要 clone：

```bash
npx awesome-codex-subagents-opencode --global
```

把 174 个 agent 装进 `~/.config/opencode/agents`，重启 OpenCode 后即可用 `@agent名` 调用。

> **包名就是命令。** `npx ocagents` 这类简写不能用 —— npm 会去找同名包并失败。 请始终使用上面的完整包名。

只想装一部分？174 个会让 `@` 菜单很长，也会稀释模型的自动选择：

```bash
npx awesome-codex-subagents-opencode --global --preset minimal
```

### 或者从仓库安装

想读源码或自己改的话。下面所有命令都假定你**已经在仓库目录内**：

```bash
git clone https://github.com/He-Xun/awesome-codex-subagents-opencode.git
cd awesome-codex-subagents-opencode

node install.mjs            # -> 在运行命令的项目里创建 ./.opencode/agents
node install.mjs --global   # -> ~/.config/opencode/agents（所有项目生效）
```

零依赖，只需 Node 18+。

> 脚本会自己解析路径，所以从任意目录执行 `node /path/to/repo/install.mjs --global` 也可以， 不需要先 `cd`。

### 参数

```
-g, --global          装到 ~/.config/opencode/agents
    --dir <path>      装到指定目录
    --lang <code>     描述语言（默认跟随系统）
    --preset <name>   只装预设子集（minimal / web / backend）
    --only <a,b>      只装指定 agent
    --skip <a,b>      排除指定 agent
    --list-presets    查看预设
    --dry             只预览，不写文件
-h, --help            查看帮助
```

`--flag value` 和 `--flag=value` 两种写法都支持。

### 用 npm 脚本（在仓库根目录）

```bash
npm run install:global      # 装到全局
npm run install:local       # 装到当前项目
npm run verify              # 校验所有产物
npm run switch -- --to=en   # 切换描述语言
npm run presets             # 查看可用预设
```

### 预设

| 预设 | 数量 | 内容 |
| --- | --- | --- |
| `minimal` | 10 | 审查、定位、改代码、写测试 |
| `web` | 15 | 前端 / UI / 可访问性 |
| `backend` | 17 | 服务端 / 数据库 / 基础设施 |

预设就是纯文本名单（`presets/*.txt`），可以直接改或加新的。

## 三个设计取舍

这三点决定了它和「直接把文件复制过来」的差别：

**1\. 不写死模型。** 源仓库每个 agent 都绑定了 `gpt-6.1-sol`，这个模型在你的 provider 上大概率不存在，硬套过去等于 174 个 agent 全部不可用。本仓库**完全不输出 `model` 字段**， 让 subagent 继承调用方的模型 —— 换 provider、换模型都不用重新生成。

**2\. MCP 依赖去厂商化。** 源仓库有 agent 绑定 OpenAI 自家的文档服务。这里替换成通用的 `websearch` + `webfetch`，任何厂商的文档都能查。

**3\. 语言只翻描述，不翻正文。** 详见下方[为什么](https://npmcn.com/package/awesome-codex-subagents-opencode/#readme-%E4%B8%BA%E4%BB%80%E4%B9%88%E5%8F%AA%E7%BF%BB%E8%AF%91-description) —— 中文 反而更费 token，全量汉化是负优化。

* * *

## 项目来源

本仓库是 [VoltAgent/awesome-codex-subagents](https://github.com/VoltAgent/awesome-codex-subagents) （6.4k star）的 OpenCode 移植版。上游提供的是 Codex 格式的 `.toml` 定义，本项目将其 转换为 OpenCode 的 Markdown agent 格式，并解决了上述三个移植问题。

**只做格式适配，不改写 prompt 语义**：正文原文照搬，便于上游更新时重新生成。

上游更新后重新生成：

```bash
cd awesome-codex-subagents-opencode      # 切到仓库根目录
git clone --depth 1 https://github.com/VoltAgent/awesome-codex-subagents.git ../src
node tools/codex-subagents-to-opencode.mjs ../src/categories agents
```

* * *

## 描述语言：随系统自动选择，可随时切换

**prompt 正文始终是英文**，只有 `description`（也就是 `@` 菜单里显示的那一行）会跟着语言变化。

### 安装时自动检测

`tools/install.mjs` 按以下顺序决定语言，**没有匹配译表时回退到英语**：

1.  `--lang=xx` 或环境变量 `OPENCODE_SUBAGENTS_LANG`
2.  `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`
3.  `Intl` 报告的系统 locale
4.  回退 → 英语

内置语言：**English (en) · 简体中文 (zh) · Español (es) · Русский (ru) · 한국어 (ko)**。

`--lang` 接收的是**语言代码**，也就是 ISO 639-1 的两位标签（`zh`、`es`、`ru`、`ko`、`en`）。 它同时也是 `tools/i18n/` 下译表的文件名，所以两者不会对不上。 完整的系统 locale（`zh-CN`、`es_ES`、`pt_BR`）只是检测时的**输入**，不是传给 `--lang` 的值。

> 当 `LANG` 或 `LC_ALL` 已设置但没有对应译表时，结果是英语，而不是再从 `Intl` 推断另一个 locale。显式设置了环境变量，就按用户意图处理。

```bash
node install.mjs                          # 跟随系统 locale
node install.mjs --lang=en                # 强制英文
node install.mjs --lang=zh                # 强制中文
node install.mjs --only=reviewer,debugger # 只装部分
```

系统 locale 的映射规则：先去掉地区部分，再与已有译表匹配。

| 系统 locale | 解析为 | 原因 |
| --- | --- | --- |
| `zh-CN`、`zh-TW` | `zh` | 基础 `zh` 有译表 |
| `es_ES`、`es-MX` | `es` | 基础 `es` 有译表 |
| `ru_RU` | `ru` | 基础 `ru` 有译表 |
| `ko_KR` | `ko` | 基础 `ko` 有译表 |
| `en_US` | `en` | 基础 `en` 有译表 |
| `de_DE` | `en` | 没有 `de` 译表 → 回退英语 |

### 随时切换

`--dir` 默认是 `./.opencode/agents`：

```bash
cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/switch-lang.mjs --list                                   # 查看可用语言
node tools/switch-lang.mjs --to=zh                                  # 切中文
node tools/switch-lang.mjs --to=en                                  # 切回英文
node tools/switch-lang.mjs --to=zh --dir=~/.config/opencode/agents  # 指定目录
node tools/switch-lang.mjs --to=zh --dry                            # 预演
```

切换器**只改写 frontmatter 里的 description 那一行**，正文和权限原样保留，并保持原有的 引号风格，因此中英来回切换不会产生多余 diff（已验证 174 个文件往返 0 差异）。

### 添加新语言

在 `tools/i18n/` 下新建 `<lang>.json`，`<lang>` 是 ISO 639-1 语言代码，也就是你传给 `--lang` 的值（法语用 `fr.json`，德语用 `de.json`）。键为 agent 名：

```json
{
  "reviewer": "需要 PR 式评审，聚焦正确性、安全性、行为回归与测试缺失时使用。",
  "debugger": "需要做深度缺陷定位时使用。"
}
```

无需改代码，`install.mjs` / `switch-lang.mjs` 会自动发现，随后即可用 `--lang=fr` 选择。 缺条目时该 agent 保留英文。

只用基础语言码，不要带地区：文件名必须是 `fr.json` 而不是 `fr-FR.json`，因为检测时会先 去掉地区部分再匹配。

内置译表遵循的敬语规范（贡献新语言时请沿用）：

| 语言 | 体裁 | 句式 |
| --- | --- | --- |
| `es` | 仅用正式体 `usted`，不用 `tú`/`vosotros` | `Úselo cuando …` |
| `ru` | 仅用 `вы` 敬语，不用 `ты` | `Используйте, когда …` |
| `ko` | 仅用 `-십시오` / `-합니다` 正式体，不用 반말 | `…할 때 사용하십시오.` |

* * *

## 为什么只翻译 description

先看实测数据。同一份内容的中英对照：

| 分词器 | 英文 | 中文 | 差值 |
| --- | --- | --- | --- |
| GPT-4o (o200k) | 1196 | 1479 | +23.7% |
| DeepSeek-V2 | 1324 | 1427 | +7.8% |
| GLM-4 | 1202 | 1307 | +8.7% |
| Qwen 2.5 | 1203 | 1351 | +12.3% |

来源：[Chinese vs. English Tokens](https://markhuang.ai/blog/chinese-token-myth)。

国产模型分词器对中文友好得多（从 +24% 降到 +8%），但**方向从未逆转：中文更费 token**。 英文可以整词压成单个 token，汉字基本一字一 token 或更多。

换算到本仓库：中文 description 字符数少 66%，但 token 数**增加约 50%**。全量汉化正文会让 327k 字符的 prompt 再涨约 8%。

所以：**语言的价值是可读性和触发准确性，不是省 token。** 想省 token 应该精简 agent 数量， 而不是换语言。

* * *

## 设计细节

### 1\. 不写死模型

源文件里的 `model = "gpt-6.1-sol"` 是 Codex 专用模型，换到 OpenCode 上大概率不存在。 转换器**完全不输出 `model` 字段**，让 subagent 继承调用方 agent 的模型 —— 这是 OpenCode 的文档行为，好处是与 provider 无关，换模型不用重跑转换。

需要给特定 agent 钉死模型时：

```bash
cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/codex-subagents-to-opencode.mjs <src> agents \
  --model-map=gpt-6.1-sol=anthropic/claude-sonnet-5,gpt-6-luna=anthropic/claude-haiku-5
```

### 2\. MCP 依赖去厂商化

Codex 允许在 agent 文件内联 `[mcp_servers.NAME]`，OpenCode 不允许（必须写在 `opencode.json`）。仓库里的两个依赖处理如下：

| 源 MCP | 处理 | 原因 |
| --- | --- | --- |
| `openaiDeveloperDocs`（docs-researcher） | 替换为 `websearch` + `webfetch` | 无需 API key，但只索引 OpenAI 自家文档，与通用适配相悖 |
| `chrome_devtools`（browser-debugger） | 保留依赖 | 本身开源，且无通用替代品 |

替换规则集中在 `MCP_REPLACEMENTS` 常量，需要时可扩展。

### 3\. 权限映射

Codex 的 `sandbox_mode` 是沙箱级强制，OpenCode 的 `permission` 是 allow/ask/deny 三级：

| Codex | OpenCode |
| --- | --- |
| `read-only` | `edit: deny`, `bash: deny` |
| `workspace-write` | `edit: allow`, `bash: allow` |

174 个 agent 中 99 个只读、75 个可写。

**例外**：有 3 个只读 agent 的核心工作离不开执行命令 —— `debugger` 要看 stack trace 和 失败测试、`performance-engineer` 要跑测量、`security-auditor` 要复现问题。它们设成 `bash: ask`（每条命令仍需你批准），既保持只读语义，又不至于完全不可用。 名单在 `READ_ONLY_NEEDS_SHELL` 常量里。

* * *

## 字段映射

| Codex (`.toml`) | OpenCode (`.md`) |
| --- | --- |
| `name` | 文件名 `xxx.md`（同时是 agent id） |
| `description` | frontmatter `description` |
| `model` | **不输出**，继承父 agent（可用 `--model-map` 覆盖） |
| `model_reasoning_effort` | frontmatter `reasoningEffort` |
| `developer_instructions` | 正文（prompt，原文保留） |
| `sandbox_mode` | frontmatter `permission` |
| `[mcp_servers.*]` | 不进入文件，转换报告里列出 |
| 分类目录 | frontmatter `color`（仅视觉区分） |

正文中的 `Codex` 会被替换为 `the parent agent`，避免提示词指向另一个产品。

* * *

## CLI 参数

| 参数 | 说明 |
| --- | --- |
| `--only=reviewer,debugger` | 只转换指定 agent |
| `--category=04,05` | 按分类目录前缀过滤 |
| `--skip=a,b` | 追加要跳过的 agent |
| `--all` | 连 Codex 专用 agent 也一并转换 |
| `--dry` | 只打印报告，不写文件 |
| `--model-map=k=v,...` | 覆盖模型映射 |
| `--lang=zh` | 把 `description` 本地化成中文，正文保持英文（默认自动检测，见上） |
| `--keep-reasoning` | 保留 `reasoningEffort` 字段 |

默认跳过 `agent-installer`、`workflow-orchestrator`：它们的 prompt 讲的是 「往 `~/.codex/agents/` 里装文件」，移植到 OpenCode 后语义为空。

* * *

## 对非 GPT 与开源模型的说明

-   **`reasoningEffort` 是 GPT 系专属参数。** 只有 OpenAI 风格的接口认识它；Claude、Llama、 Mistral、Gemma、GLM、DeepSeek、Qwen 以及多数开源权重模型都会忽略。 **默认不再输出**，如果你的 provider 支持，再用 `--keep-reasoning` 恢复。
-   若给特定 agent 钉模型，用 `--model-map`。值的形式是 `provider/model-id`，provider 前缀取自你自己的 `opencode.json`：`--model-map=gpt-6.1-sol=<provider>/<model-id>`。

* * *

## 已知限制

1.  **自动触发很弱（平台机制）**。OpenCode 把 subagent 列表以 `id: description` 拼进 task 工具的 description，只靠文本让模型自行判断。内置 `explore` 的 description 带具体例句， 更容易被选中。174 个候选会稀释信号 —— 这是 OpenCode 的行为，不是转换问题。 建议要么用 `--only` 只装常用子集，要么始终 `@agent名` 手动调用。
    
2.  **常驻上下文成本**。全量安装会让 task 工具描述增加约 7.5k token。
    
3.  **prompt 同质化**。源仓库 174 份 prompt 共用一个模板 （`Working mode / Focus on / Quality checks / Return`），长度 129/174 落在 1–2k 字符区间， 差异主要在领域词汇。不要期待它们之间有精细分工。
    
4.  **`browser-debugger` 需要 chrome-devtools MCP**（默认 `localhost:3000/mcp`）。 未配置时该 agent 会被加载但缺少工具。
    

* * *

## 仓库结构

```
.
├── bin/{cli,lang}.mjs                    # npm 包入口（ocagents / ocagents-lang）
├── tools/
│   ├── install.mjs                       # 安装（系统语言 + 预设）
│   ├── switch-lang.mjs                   # 随时切换 description 语言
│   ├── detect-lang.mjs                   # 语言检测（含回退到英语）
│   ├── validate.mjs                      # 校验产物、译表、预设（CI 用）
│   ├── i18n/{en,zh}.json                 # description 译表，加语言只需加文件
│   ├── codex-subagents-to-opencode.mjs   # 从上游 TOML 重新生成 agents/
│   ├── analyze-subagents.mjs             # 产物分析
│   ├── compare-lang.mjs                  # 中英文 token 成本对比
│   └── verify-load.mjs                   # 验证 OpenCode 能否正确加载
├── presets/{minimal,web,backend}.txt     # 装哪些 agent 的预设名单
├── agents/                                # 174 个 OpenCode agent（英文基准）
├── .github/workflows/validate.yml         # CI
├── package.json
├── README.md                              # English
├── README.zh-CN.md                        # 本文件
└── LICENSE
```

`agents/` 是英文基准版本，可以直接复制到任意 OpenCode 项目使用。 想换描述语言用 `switch-lang.mjs`，不要手动改。

## 校验

```bash
npm run verify
```

检查 frontmatter 合法性、`mode: subagent`、无硬编码 model、权限键有效、prompt 完整且无 `Codex` 残留、译表与 agent 一一对应、预设引用的 agent 都存在。

CI 在 Node 18 / 20 / 22 上运行，并额外验证「从上游重新生成的结果与提交版本一致」， 防止产物悄悄漂移。

* * *

## 许可证

本仓库的转换脚本与 README 以 MIT 发布。 `agents/` 下的内容派生自 [VoltAgent/awesome-codex-subagents](https://github.com/VoltAgent/awesome-codex-subagents)， 同样为 MIT，版权归原作者及贡献者所有。

## 常见问题

### awesome-codex-subagents-opencode 是什么？

174个Codex子代理定义适用于OpenCode，具有5种语言的语言环境感知描述

### 如何安装 awesome-codex-subagents-opencode？

在项目目录运行 npm install awesome-codex-subagents-opencode，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ocagents、ocagents-lang、awesome-codex-subagents-opencode、awesome-codex-subagents-opencode-lang，可以用 npx ocagents 直接运行。

### awesome-codex-subagents-opencode 支持 TypeScript 吗？

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

### awesome-codex-subagents-opencode 支持 ESM 还是 CommonJS？

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

### awesome-codex-subagents-opencode 需要什么版本的 Node\.js？

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

### awesome-codex-subagents-opencode 可以商用吗？

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

### awesome-codex-subagents-opencode 还在维护吗？

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