@te-river/opencode-team-mode 1.4.5 → 1.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +500 -474
  2. package/README.zh-CN.md +464 -446
  3. package/dist/agents.d.ts.map +1 -1
  4. package/dist/agents.js +122 -21
  5. package/dist/agents.js.map +1 -1
  6. package/dist/commands.d.ts.map +1 -1
  7. package/dist/commands.js +29 -12
  8. package/dist/commands.js.map +1 -1
  9. package/package.json +1 -1
package/README.zh-CN.md CHANGED
@@ -1,446 +1,464 @@
1
- # OpenCode TeamMode
2
-
3
- **[English](./README.md)** | **[中文](./README.zh-CN.md)**
4
-
5
- [![npm version](https://img.shields.io/npm/v/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
6
- [![npm downloads](https://img.shields.io/npm/dm/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
7
- [![license](https://img.shields.io/npm/l/@te-river/opencode-team-mode.svg)](./LICENSE)
8
-
9
- > 🤝 **[OpenCode 桌面版](https://opencode.ai) 多 Agent 团队协作插件**
10
- >
11
- > 为你的 OpenCode 桌面版添加一整支 AI 专家团队 —— 架构师、实现者、审查员、测试员、调研员，由 Team Lead 统一调度，通过简单的斜杠命令即可调用。
12
-
13
- ---
14
-
15
- ## ✨ TeamMode 是什么？
16
-
17
- TeamMode 将 OpenCode 桌面版从一个单 Agent 编码助手，升级为**一整个开发团队**。每个 Agent 拥有独立的角色定位、专业领域和行为风格 —— 就像真实的工程团队。
18
-
19
- 不再是一个 Agent 包揽所有事，你将获得：
20
-
21
- | Agent | 角色 | 使用场景 |
22
- |---|---|---|
23
- | 🎯 **Team Lead** | 调度者 | 需要规划 + 多步执行的复杂任务 |
24
- | 🏗️ **Architect** | 系统设计师 | 设计文档、模块结构、API 契约 |
25
- | 💻 **Implementer** | 代码实现者 | 编写生产代码、实现功能 |
26
- | 🔍 **Reviewer** | 代码审查员 | Bug 猎手、安全审查、质量检查 |
27
- | 🧪 **Tester** | 测试工程师 | 单元测试、集成测试、边界覆盖 |
28
- | 🔎 **Researcher** | 知识调研员 | 库评估、API 文档、最佳实践调研 |
29
-
30
- ---
31
-
32
- ## 🚀 快速开始
33
-
34
- ### 前置条件
35
-
36
- 1. **安装 OpenCode 桌面版**（如果还没有）：
37
-
38
- | 平台 | 安装命令 |
39
- |---|---|
40
- | macOS (Apple Silicon) | `brew install --cask opencode-desktop` |
41
- | macOS (Intel) | `brew install --cask opencode-desktop` |
42
- | Windows | `scoop bucket add extras && scoop install extras/opencode-desktop` |
43
- | Linux | 从 [opencode.ai/download](https://opencode.ai/download) 下载 |
44
-
45
- 或安装 **CLI/TUI** 版本：
46
- ```bash
47
- # 一键脚本（全平台）
48
- curl -fsSL https://opencode.ai/install | bash
49
-
50
- # 或通过 npm
51
- npm install -g opencode-ai
52
- ```
53
-
54
- 2. **Node.js ≥ 18**（用于 npm）
55
-
56
- ### 安装 TeamMode
57
-
58
- **方式 A — 一键安装脚本（推荐）：**
59
-
60
- macOS / Linux（bash）：
61
- ```bash
62
- curl -fsSL https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.sh | bash
63
- ```
64
-
65
- Windows（PowerShell）：
66
- ```powershell
67
- irm https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.ps1 | iex
68
- ```
69
-
70
- 脚本会自动安装 npm 包，并将插件注册到你的 `opencode.jsonc` 中。
71
-
72
- **方式 B — 手动 npm 安装：**
73
-
74
- ```bash
75
- # 1. 安装插件包
76
- npm install -g @te-river/opencode-team-mode
77
-
78
- # 2. 将插件添加到 opencode.jsonc
79
- # （见下方"配置"章节）
80
- ```
81
-
82
- **方式 C — 本地开发安装（从本仓库）：**
83
-
84
- ```bash
85
- git clone https://github.com/Te-River/Opencode-TeamMode.git
86
- cd Opencode-TeamMode
87
- npm install
88
- npm run build
89
- npm link
90
- ```
91
-
92
- ---
93
-
94
- ## ⚙️ 配置
95
-
96
- 安装后，将插件添加到你的 `opencode.jsonc`：
97
-
98
- ```jsonc
99
- {
100
- "$schema": "https://opencode.ai/config.json",
101
- "plugin": [
102
- "@te-river/opencode-team-mode@latest"
103
- ]
104
- }
105
- ```
106
-
107
- 就这么简单。插件会在 OpenCode 启动时自动注入所有团队 Agent 和命令，**无需手动复制任何 Agent 文件或命令定义**。
108
-
109
- > 💡 **提示：** 修改 `opencode.json` 后，请**重启 OpenCode 桌面版**使更改生效。
110
-
111
- > ⚠️ **模型选择很重要。** 工作流里的每一个判断——分诊、拆解、派发清单、
112
- > 整合、审查/测试闭环裁决——都经过 **Team Lead**。这个位置上放弱模型，
113
- > 专家再强也救不回整条流水线。请给你的 `team` agent 钉上你能负担的最强
114
- > 推理模型（配方见下方「自定义」节）。
115
-
116
- ### 全局安装（所有项目生效）
117
-
118
- 要在所有项目中启用 TeamMode，将插件添加到全局配置：
119
-
120
- ```jsonc
121
- // ~/.config/opencode/opencode.jsonc
122
- {
123
- "$schema": "https://opencode.ai/config.json",
124
- "plugin": [
125
- "@te-river/opencode-team-mode@latest"
126
- ]
127
- }
128
- ```
129
-
130
- ---
131
-
132
- ## 📖 使用方法
133
-
134
- ### 斜杠命令
135
-
136
- TeamMode 为 OpenCode 添加了六个斜杠命令，在聊天输入框中输入：
137
-
138
- | 命令 | Agent | 说明 |
139
- |---|---|---|
140
- | `/team-plan <任务>` | Architect | 创建详细的实现计划：架构、文件清单、任务拆解 |
141
- | `/team-implement <任务>` | Implementer | 为功能或任务编写生产代码 |
142
- | `/team-review [范围]` | Reviewer | 审查代码的 Bug、安全问题和质量问题 |
143
- | `/team-test [范围]` | Tester | 生成全面的测试，覆盖边界场景 |
144
- | `/team-research <主题>` | Researcher | 调研库、API 或最佳实践 |
145
- | `/team-run <任务>` | Team Lead | **完整工作流** — 端到端调度所有 Agent |
146
-
147
- #### 示例工作流
148
-
149
- ```bash
150
- # 1. 规划功能
151
- /team-plan 添加基于 OAuth2 和 JWT 的用户认证
152
-
153
- # 2. 审查计划后，开始实现
154
- /team-implement 按计划实现认证模块
155
-
156
- # 3. 审查代码
157
- /team-review src/auth/
158
-
159
- # 4. 编写测试
160
- /team-test src/auth/
161
-
162
- # 或者让 Team Lead 全程调度：
163
- /team-run 添加基于 OAuth2 和 JWT 的用户认证
164
- ```
165
-
166
- ### Agent 选择器
167
-
168
- 你也可以在 OpenCode 桌面版中使用 `@` 直接调用 Agent：
169
-
170
- - `@team` — 调度复杂任务
171
- - `@architect` — 设计系统或模块
172
- - `@implementer` — 编写代码
173
- - `@reviewer` — 审查代码质量
174
- - `@tester` — 编写测试
175
- - `@researcher` — 调研主题
176
-
177
- ### 演示
178
-
179
- 以下是一段会话实录的还原。Team 出厂即默认代理（退出方法见下方配置），
180
- 用户开新会话直接输入：
181
-
182
- > **用户：** 给我们的 Express API 加令牌桶限流——每用户每分钟 100 请求，
183
- > 超限返回 429。不要动 `src/legacy/` 下的任何东西。
184
-
185
- ```text
186
- team 拆解任务：设计 → 实现 → 审查 → 测试。
187
- 任务黑板：.git/opencode-team/20260831-143012/rate-limiter/（会话目录 + 任务板，都在 .git/ 内，闲置超 TTL 自动清理）
188
-
189
- ▸ @architect — 设计中（写入 01-architect-design.md）
190
- ✓ 内存令牌桶、按用户键控、429 + Retry-After
191
- 聊天里只有摘要，设计全文在黑板上
192
-
193
- ▸ @implementer — 实现中（Reads: 01；写 02-implementer-middleware.md）
194
- ✓ src/middleware/rateLimit.ts（新增），接入 src/app.ts（+3 行）
195
-
196
- ▸ @reviewer — 审查改动（Reads: 01、02；写 03-reviewer-findings-r1.md）
197
- ⚠ 1 个 MAJOR — 桶回充分两步读-改-写，并发下有竞态
198
- → 已自动转为修复任务，发现原文随任务书派给 @implementer
199
- （这一步没有要求用户拍板）
200
-
201
- ▸ @implementer r2 — 修竞态（Reads: 03-r1 §MAJOR；写 04-implementer-r2.md）
202
- ✓ 回充重构为单次原子更新
203
-
204
- ▸ @reviewer r2 — 只复审改动范围
205
- ✓ 通过 — r1 发现已解决，无回归
206
-
207
- ▸ @tester — 覆盖限流器与边界（写 05-tester-report.md）
208
- ✓ 14/14 通过 — 突发边界、窗口过期、并发回充、
209
- src/legacy/** 逐字节未变（用户边界写进了测试断言）
210
-
211
- team 完成。
212
- 限流器已交付：rateLimit.ts（新增）· app.ts（+3）· 14 测试全绿
213
- 审查闭环：1 个 major → 已修 → 清零
214
- 假设：仅内存存储——要接 Redis 说一声
215
- src/legacy/ 未动
216
- 任务黑板留在原地，TTL 到期自动回收
217
- ```
218
-
219
- 用户输入的消息只有第一条。reviewer 的发现直接变成 implementer 的下一张
220
- 工单；每份制品都留在黑板上而不是聊天里，只被需要它的那次派发读取。
221
-
222
- ### 桌面版专属特性
223
-
224
- 在 **OpenCode 桌面版** 中，你还能获得额外的 UX 体验：
225
-
226
- - 🎨 **Agent 颜色标识** — 每个 Agent 在聊天 UI 中有独立颜色，便于识别
227
- - 📋 **Agent 选择器** — 点击 Agent 下拉菜单，可视化切换团队 Agent
228
- - 🔀 **并行子任务** — Team Lead 可同时调度多个子 Agent，结果在并行面板中展示
229
- - 📊 **会话历史** — 所有团队交互都保存在桌面版侧边栏，可搜索回溯
230
-
231
- ---
232
-
233
- ## 🏗️ 架构
234
-
235
- ```
236
- opencode-team-mode/
237
- ├── package.json ← npm 包定义
238
- ├── tsconfig.json ← TypeScript 配置
239
- ├── src/
240
- │ ├── index.ts ← 插件入口（server() + config hook，id: "team-mode"）
241
- │ ├── agents.ts ← Agent 定义（prompts、模式、颜色）
242
- │ ├── commands.ts ← 命令定义（模板、Agent 绑定）
243
- │ ├── blackboard.ts ← 共享黑板 + TTL 自动清理清扫器
244
- │ └── types.ts ← 加载器契约类型定义（1.18.x）
245
- ├── scripts/
246
- │ ├── install.sh ← 一键安装脚本（bash）
247
- │ └── install.ps1 ← 一键安装脚本（PowerShell）
248
- ├── LICENSE ← Apache 2.0
249
- └── README.md ← 英文文档
250
- README.zh-CN.md ← 中文文档
251
- ```
252
-
253
- ### 工作原理
254
-
255
- 1. OpenCode 桌面版启动，加载 `opencode.json(c)`
256
- 2. 检测到 `plugin` 数组中的 `"@te-river/opencode-team-mode@latest"`，加载 npm 包
257
- 3. 加载器调用插件的 `server(input, options)`，注册 `config` hook；hook 向合并后的配置注入 6 个 Agent 和 6 个命令
258
- 4. 插件的 `id: "team-mode"` 作为插件名显示在桌面版 UI
259
- 5. Agent 和命令立即在桌面版 UI 中可用 —— 无需复制任何文件；同名 Agent 以用户自定义优先（插件绝不覆盖）
260
-
261
- ---
262
-
263
- ## 🗂️ 共享黑板（带自动清理）
264
-
265
- 子代理之间无法实时互发消息（平台限制），TeamMode 通过**严格所有权的文件黑板**让它们协作：
266
-
267
- - **会话隔离：** 每个会话拥有一个时间戳会话目录，多 Agent 任务在其内再各自
268
- 独立建任务目录：`<repo>/.git/opencode-team/<session-key>/<task-slug>/` ——
269
- 位于 `.git/` 内，**绝不污染**你的工作区和 commit（非 git 工作区自动回退到系统临时目录）。
270
- 正因为黑板现在会留到 TTL 清扫才消失，会话层让新对话几乎不可能撞上（或误读到）
271
- 上一场还没被收走的旧黑板 —— 时间戳精确到秒，理论上只有同一秒开跑的两个会话才会重名。
272
- - **文件所有权**：每个制品是一个"一主题一文件"，只由一个 Agent 写
273
- （`01-architect-auth-design.md`、`03-reviewer-auth-r1.md`）。单文件约 ≤100 行，
274
- 超长就拆主题文件而不是任其膨胀。
275
- - **写入即冻结**：修订 = 新的轮次后缀文件（`…-r2.md`）；绝不追加旧文件，
276
- 后续 Agent 也永远读不到过时轮次。
277
- - **Team Lead 是路由器**：每次 dispatch 携带清单——`Task:`（自包含任务书）、
278
- `Reads:`（仅列出该工作包需要的文件）、`Write to:`（该 Agent 本次拥有的唯一文件）。
279
- 子代理不读清单之外的任何东西，超长任务因此不会把无关上下文灌进子代理。
280
- - **`MANIFEST.md` 是 lead 的状态板**：文件索引 + 顶部 ≤50 行的 `## Current state`
281
- 节（阶段、仍然有效的决策、下一步），每轮闭环后更新——lead 跨长任务的压缩记忆。
282
- - Team Lead 同时强制执行审查/测试**反馈闭环**：Critical/Major 问题和产品 bug
283
- 自动转化为跟踪的修复任务，直到交付物收敛。
284
-
285
- ### Triage —— 提问不会变成代码修改
286
-
287
- Team Lead 对每条消息先分类再行动：咨询/提问只得到回答（零文件改动，发现缺陷
288
- 仅**提议**修复并等待你放行）；只有明确的行动指令才进入工作流。并且一旦你写明
289
- 了哪些能碰哪些不能碰，**这些边界高于一切规则**——lead 会在每次派发中原样重申。
290
-
291
- ### 清理 —— 只有 TTL 清扫器一条路
292
-
293
- | 责任方 | 时机 |
294
- |---|---|
295
- | 插件代码（进程内清扫器） | 启动时 + 每小时：清除空闲超过 **TTL** 的任务目录 |
296
-
297
- Team Lead 不再删除任务目录 —— 跑完的黑板原地留给你回看审计；回收由纯代码
298
- 完成，从不依赖模型"记得删"，崩溃/强杀留下的残骸同样会被清扫。清扫器对活跃
299
- 会话内的过期任务逐个回收，对整个闲置的会话目录一次性收走。TTL 可用
300
- `ttlDays` 调节。
301
-
302
- ### 自定义 TTL
303
-
304
- 默认为 **5 天**。想自定义，在 `opencode.jsonc` 中使用元组形式的插件声明：
305
-
306
- ```jsonc
307
- {
308
- "$schema": "https://opencode.ai/config.json",
309
- "plugin": [
310
- ["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]
311
- ]
312
- }
313
- ```
314
-
315
- `ttlDays` 接受 `(0, 365]` 内的天数；非法值静默回退到 5 天。
316
-
317
- ### 默认代理
318
-
319
- TeamMode 默认**把 Team 设为你的默认代理**——新会话直接由团队调度者接管。
320
- 占默认槽附带一个排序效应：选择器会把**默认代理钉在第一位**、其余按名称
321
- 字母升序，所以顺序为 **team, build, plan**。（想让 Team 排在 Plan 之下？
322
- 那必须放弃默认槽——见下方退出开关；按服务端的排序规则二者不可兼得。）
323
-
324
- 不想占用默认代理槽（`build` 保持默认，顺序 **build, plan, team**）则退出：
325
-
326
- ```jsonc
327
- {
328
- "plugin": [
329
- ["@te-river/opencode-team-mode@latest", { "defaultAgent": false }]
330
- ]
331
- }
332
- ```
333
-
334
- 用户显式配置的非 `build` 默认代理永远原样保留——插件从不覆写。
335
-
336
- **升级提示**：v1.4.4 曾短暂改为 opt-in（默认不占用）；v1.4.5 恢复
337
- Team-as-default 出厂行为。若你在 v1.4.4 期间加过 `{ "defaultAgent": true }`，
338
- 现在可以删掉该选项（或改为 `false` 主动退出）。
339
-
340
- ---
341
-
342
- ## 🔧 自定义
343
-
344
- ### Team Lead 的模型最关键
345
-
346
- Lead 是编排大脑：它给每条消息分类、把工作切成包、写每份派发清单、裁决
347
- reviewer/tester 的发现、合成最终交付。这里的质量问题会**沿流水线放大**——
348
- 平庸的 Lead 拆错任务、给专家的指令含糊、放走劣质产出；没有任何专家能
349
- 救回一份从一开始就派错的工单。
350
-
351
- 所以：**Lead 位上请放你负担得起的最强模型**。其他角色可以用便宜模型——
352
- 它们拿到的指令书精确、阅读范围受限，容错更高。按 agent 钉模型：
353
-
354
- ```jsonc
355
- {
356
- "agent": {
357
- // Team Lead —— 编排值得最好的模型
358
- "team": { "model": "anthropic/claude-opus-4-5" },
359
- // 专家角色 —— 便宜一档通常够用
360
- "implementer": { "model": "anthropic/claude-sonnet-4-6" }
361
- }
362
- }
363
- ```
364
-
365
- （以上模型 ID 仅为示例，换成你服务商实际提供的即可。你自定义的
366
- `agent.team` 永远优先于插件注入的版本。）
367
-
368
- ### 覆盖某个 Agent
369
-
370
- 在 `opencode.json` 中添加同名 Agent —— 你的定义会优先生效：
371
-
372
- ```jsonc
373
- {
374
- "agent": {
375
- "reviewer": {
376
- "model": "anthropic/claude-sonnet-4-6",
377
- "prompt": "你是一个极其严格的审查员。任何 lint 警告都必须打回。"
378
- }
379
- }
380
- }
381
- ```
382
-
383
- ### 添加自己的 Agent
384
-
385
- TeamMode 不阻止你添加更多 Agent，与团队 Agent 并存：
386
-
387
- ```jsonc
388
- {
389
- "agent": {
390
- "devops": {
391
- "mode": "subagent",
392
- "description": "处理 CI/CD、Docker 和部署任务",
393
- "prompt": "你是 DevOps 工程师..."
394
- }
395
- }
396
- }
397
- ```
398
-
399
- ### 禁用某个 Agent
400
-
401
- ```jsonc
402
- {
403
- "agent": {
404
- "researcher": { "disable": true }
405
- }
406
- }
407
- ```
408
-
409
- ---
410
-
411
- ## 📦 发布到 npm
412
-
413
- 如果你想发布自己的 fork：
414
-
415
- ```bash
416
- npm run build # 编译 TypeScript → dist/
417
- npm version patch # 更新版本号
418
- npm publish # 发布到 npm 仓库
419
- ```
420
-
421
- ---
422
-
423
- ## 🤝 贡献
424
-
425
- 欢迎贡献！以下方向特别需要帮助：
426
-
427
- - 🌐 **本地化** — 将 Agent prompt 翻译为其他语言
428
- - 🎨 **更多 Agent 角色** — DevOps、DBA、安全专家、UX 设计师
429
- - 🔧 **更多命令** — `/team-deploy`、`/team-docs`、`/team-refactor`
430
- - 📝 **更好的 Prompt** — 通过 Prompt 工程优化 Agent 行为
431
-
432
- ---
433
-
434
- ## 📄 许可证
435
-
436
- [Apache License 2.0](./LICENSE)
437
-
438
- ---
439
-
440
- ## 🔗 链接
441
-
442
- - [npm 包](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode`
443
- - [OpenCode 桌面版](https://opencode.ai) — 官网 & 下载
444
- - [OpenCode 文档](https://opencode.ai/docs) — 配置 & 插件文档
445
- - [OpenCode 插件 API](https://opencode.ai/docs/plugins) — 构建你自己的插件
446
- - [OpenCode GitHub](https://github.com/anomalyco/opencode) — OpenCode 源码
1
+ # OpenCode TeamMode
2
+
3
+ **[English](./README.md)** | **[中文](./README.zh-CN.md)**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
6
+ [![npm downloads](https://img.shields.io/npm/dm/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
7
+ [![license](https://img.shields.io/npm/l/@te-river/opencode-team-mode.svg)](./LICENSE)
8
+
9
+ > 🤝 **[OpenCode 桌面版](https://opencode.ai) 多 Agent 团队协作插件**
10
+ >
11
+ > 为你的 OpenCode 桌面版添加一整支 AI 专家团队 —— 架构师、实现者、审查员、测试员、调研员，由 Team Lead 统一调度，通过简单的斜杠命令即可调用。
12
+
13
+ ---
14
+
15
+ ## ✨ TeamMode 是什么？
16
+
17
+ TeamMode 将 OpenCode 桌面版从一个单 Agent 编码助手，升级为**一整个开发团队**。每个 Agent 拥有独立的角色定位、专业领域和行为风格 —— 就像真实的工程团队。
18
+
19
+ 不再是一个 Agent 包揽所有事，你将获得：
20
+
21
+ | Agent | 角色 | 使用场景 |
22
+ |---|---|---|
23
+ | 🎯 **Team Lead** | 调度者 | 需要规划 + 多步执行的复杂任务 |
24
+ | 🏗️ **Architect** | 系统设计师 | 设计文档、模块结构、API 契约 |
25
+ | 💻 **Implementer** | 代码实现者 | 编写生产代码、实现功能 |
26
+ | 🔍 **Reviewer** | 单维审查员 | 单维度审查（完整性 / 正确性 / 影响面）——lead 三路并行后合并 |
27
+ | 🧪 **Tester** | 测试工程师 | 单元测试、集成测试、边界覆盖、UI 验证 |
28
+ | 🔎 **Researcher** | 知识调研员 | 库评估、API 文档、最佳实践调研 |
29
+
30
+ ---
31
+
32
+ ## 🚀 快速开始
33
+
34
+ ### 前置条件
35
+
36
+ 1. **安装 OpenCode 桌面版**（如果还没有）：
37
+
38
+ | 平台 | 安装命令 |
39
+ |---|---|
40
+ | macOS (Apple Silicon) | `brew install --cask opencode-desktop` |
41
+ | macOS (Intel) | `brew install --cask opencode-desktop` |
42
+ | Windows | `scoop bucket add extras && scoop install extras/opencode-desktop` |
43
+ | Linux | 从 [opencode.ai/download](https://opencode.ai/download) 下载 |
44
+
45
+ 或安装 **CLI/TUI** 版本：
46
+ ```bash
47
+ # 一键脚本（全平台）
48
+ curl -fsSL https://opencode.ai/install | bash
49
+
50
+ # 或通过 npm
51
+ npm install -g opencode-ai
52
+ ```
53
+
54
+ 2. **Node.js ≥ 18**（用于 npm）
55
+
56
+ ### 安装 TeamMode
57
+
58
+ **方式 A — 一键安装脚本（推荐）：**
59
+
60
+ macOS / Linux（bash）：
61
+ ```bash
62
+ curl -fsSL https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.sh | bash
63
+ ```
64
+
65
+ Windows（PowerShell）：
66
+ ```powershell
67
+ irm https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.ps1 | iex
68
+ ```
69
+
70
+ 脚本会自动安装 npm 包，并将插件注册到你的 `opencode.jsonc` 中。
71
+
72
+ **方式 B — 手动 npm 安装：**
73
+
74
+ ```bash
75
+ # 1. 安装插件包
76
+ npm install -g @te-river/opencode-team-mode
77
+
78
+ # 2. 将插件添加到 opencode.jsonc
79
+ # （见下方"配置"章节）
80
+ ```
81
+
82
+ **方式 C — 本地开发安装（从本仓库）：**
83
+
84
+ ```bash
85
+ git clone https://github.com/Te-River/Opencode-TeamMode.git
86
+ cd Opencode-TeamMode
87
+ npm install
88
+ npm run build
89
+ npm link
90
+ ```
91
+
92
+ ---
93
+
94
+ ## ⚙️ 配置
95
+
96
+ 安装后，将插件添加到你的 `opencode.jsonc`：
97
+
98
+ ```jsonc
99
+ {
100
+ "$schema": "https://opencode.ai/config.json",
101
+ "plugin": [
102
+ "@te-river/opencode-team-mode@latest"
103
+ ]
104
+ }
105
+ ```
106
+
107
+ 就这么简单。插件会在 OpenCode 启动时自动注入所有团队 Agent 和命令，**无需手动复制任何 Agent 文件或命令定义**。
108
+
109
+ > 💡 **提示：** 修改 `opencode.json` 后，请**重启 OpenCode 桌面版**使更改生效。
110
+
111
+ > ⚠️ **模型选择很重要。** 工作流里的每一个判断——分诊、拆解、派发清单、
112
+ > 整合、审查/测试闭环裁决——都经过 **Team Lead**。这个位置上放弱模型，
113
+ > 专家再强也救不回整条流水线。如需自定义，还请给你的 `team` agent 钉上你能负担的最强
114
+ > 推理模型（配方见下方「自定义」节）。
115
+
116
+ ### 全局安装（所有项目生效）
117
+
118
+ 要在所有项目中启用 TeamMode，将插件添加到全局配置：
119
+
120
+ ```jsonc
121
+ // ~/.config/opencode/opencode.jsonc
122
+ {
123
+ "$schema": "https://opencode.ai/config.json",
124
+ "plugin": [
125
+ "@te-river/opencode-team-mode@latest"
126
+ ]
127
+ }
128
+ ```
129
+
130
+ ---
131
+
132
+ ## 📖 使用方法
133
+
134
+ ### 斜杠命令
135
+
136
+ TeamMode 为 OpenCode 添加了六个斜杠命令，在聊天输入框中输入：
137
+
138
+ | 命令 | Agent | 说明 |
139
+ |---|---|---|
140
+ | `/team-plan <任务>` | Architect | 创建详细的实现计划：架构、文件清单、任务拆解 |
141
+ | `/team-implement <任务>` | Implementer | 为功能或任务编写生产代码 |
142
+ | `/team-review [范围]` | Reviewer | 审查代码的 Bug、安全问题和质量问题 |
143
+ | `/team-test [范围]` | Tester | 生成全面的测试，覆盖边界场景 |
144
+ | `/team-research <主题>` | Researcher | 调研库、API 或最佳实践 |
145
+ | `/team-run <任务>` | Team Lead | **完整工作流** — 端到端调度所有 Agent |
146
+
147
+ #### 示例工作流
148
+
149
+ ```bash
150
+ # 1. 规划功能
151
+ /team-plan 添加基于 OAuth2 和 JWT 的用户认证
152
+
153
+ # 2. 审查计划后，开始实现
154
+ /team-implement 按计划实现认证模块
155
+
156
+ # 3. 审查代码
157
+ /team-review src/auth/
158
+
159
+ # 4. 编写测试
160
+ /team-test src/auth/
161
+
162
+ # 或者让 Team Lead 全程调度：
163
+ /team-run 添加基于 OAuth2 和 JWT 的用户认证
164
+ ```
165
+
166
+ ### Agent 选择器
167
+
168
+ 你也可以在 OpenCode 桌面版中使用 `@` 直接调用 Agent：
169
+
170
+ - `@team` — 调度复杂任务
171
+ - `@architect` — 设计系统或模块
172
+ - `@implementer` — 编写代码
173
+ - `@reviewer` — 审查代码质量
174
+ - `@tester` — 编写测试
175
+ - `@researcher` — 调研主题
176
+
177
+ ### 演示
178
+
179
+ 以下是一段会话实录的还原。Team 出厂即默认代理（退出方法见下方配置），
180
+ 用户开新会话直接输入：
181
+
182
+ > **用户：** 给我们的 Express API 加令牌桶限流——每用户每分钟 100 请求，
183
+ > 超限返回 429。不要动 `src/legacy/` 下的任何东西。
184
+
185
+ ```text
186
+ team 拆解任务：设计 → 实现 → 审查 → 测试。
187
+ 任务黑板：.git/opencode-team/20260831-143012/rate-limiter/（会话目录 + 任务板，都在 .git/ 内，闲置超 TTL 自动清理）
188
+
189
+ ▸ @architect — 设计中（写入 01-architect-design.md）
190
+ ✓ 内存令牌桶、按用户键控、429 + Retry-After
191
+ 聊天里只有摘要，设计全文在黑板上
192
+
193
+ ▸ @implementer — 实现中（Reads: 01；写 02-implementer-middleware.md）
194
+ ✓ src/middleware/rateLimit.ts（新增），接入 src/app.ts（+3 行）
195
+
196
+ ▸ @reviewer — 审查改动（Reads: 01、02；写 03-reviewer-findings-r1.md）
197
+ ⚠ 1 个 MAJOR — 桶回充分两步读-改-写，并发下有竞态
198
+ → 已自动转为修复任务，发现原文随任务书派给 @implementer
199
+ （这一步没有要求用户拍板）
200
+
201
+ ▸ @implementer r2 — 修竞态（Reads: 03-r1 §MAJOR；写 04-implementer-r2.md）
202
+ ✓ 回充重构为单次原子更新
203
+
204
+ ▸ @reviewer r2 — 只复审改动范围
205
+ ✓ 通过 — r1 发现已解决，无回归
206
+
207
+ ▸ @tester — 覆盖限流器与边界（写 05-tester-report.md）
208
+ ✓ 14/14 通过 — 突发边界、窗口过期、并发回充、
209
+ src/legacy/** 逐字节未变（用户边界写进了测试断言）
210
+
211
+ team 完成。
212
+ 限流器已交付：rateLimit.ts（新增）· app.ts（+3）· 14 测试全绿
213
+ 审查闭环：1 个 major → 已修 → 清零
214
+ 假设：仅内存存储——要接 Redis 说一声
215
+ src/legacy/ 未动
216
+ 任务黑板留在原地，TTL 到期自动回收
217
+ ```
218
+
219
+ 用户输入的消息只有第一条。reviewer 的发现直接变成 implementer 的下一张
220
+ 工单；每份制品都留在黑板上而不是聊天里，只被需要它的那次派发读取。
221
+
222
+ ### 桌面版专属特性
223
+
224
+ 在 **OpenCode 桌面版** 中，你还能获得额外的 UX 体验：
225
+
226
+ - 🎨 **Agent 颜色标识** — 每个 Agent 在聊天 UI 中有独立颜色，便于识别
227
+ - 📋 **Agent 选择器** — 点击 Agent 下拉菜单，可视化切换团队 Agent
228
+ - 🔀 **并行子任务** — Team Lead 可同时调度多个子 Agent，结果在并行面板中展示
229
+ - 📊 **会话历史** — 所有团队交互都保存在桌面版侧边栏，可搜索回溯
230
+
231
+ ---
232
+
233
+ ## 🏗️ 架构
234
+
235
+ ```
236
+ opencode-team-mode/
237
+ ├── package.json ← npm 包定义
238
+ ├── tsconfig.json ← TypeScript 配置
239
+ ├── src/
240
+ │ ├── index.ts ← 插件入口（server() + config hook，id: "team-mode"）
241
+ │ ├── agents.ts ← Agent 定义（prompts、模式、颜色）
242
+ │ ├── commands.ts ← 命令定义（模板、Agent 绑定）
243
+ │ ├── blackboard.ts ← 共享黑板 + TTL 自动清理清扫器
244
+ │ └── types.ts ← 加载器契约类型定义（1.18.x）
245
+ ├── scripts/
246
+ │ ├── install.sh ← 一键安装脚本（bash）
247
+ │ └── install.ps1 ← 一键安装脚本（PowerShell）
248
+ ├── LICENSE ← Apache 2.0
249
+ └── README.md ← 英文文档
250
+ README.zh-CN.md ← 中文文档
251
+ ```
252
+
253
+ ### 工作原理
254
+
255
+ 1. OpenCode 桌面版启动，加载 `opencode.json(c)`
256
+ 2. 检测到 `plugin` 数组中的 `"@te-river/opencode-team-mode@latest"`，加载 npm 包
257
+ 3. 加载器调用插件的 `server(input, options)`，注册 `config` hook；hook 向合并后的配置注入 6 个 Agent 和 6 个命令
258
+ 4. 插件的 `id: "team-mode"` 作为插件名显示在桌面版 UI
259
+ 5. Agent 和命令立即在桌面版 UI 中可用 —— 无需复制任何文件；同名 Agent 以用户自定义优先（插件绝不覆盖）
260
+
261
+ ---
262
+
263
+ ## 🗂️ 共享黑板（带自动清理）
264
+
265
+ 子代理之间无法实时互发消息（平台限制），TeamMode 通过**严格所有权的文件黑板**让它们协作：
266
+
267
+ - **会话隔离：** 每个会话拥有一个时间戳会话目录，多 Agent 任务在其内再各自
268
+ 独立建任务目录：`<repo>/.git/opencode-team/<session-key>/<task-slug>/` ——
269
+ 位于 `.git/` 内，**绝不污染**你的工作区和 commit（非 git 工作区自动回退到系统临时目录）。
270
+ 正因为黑板现在会留到 TTL 清扫才消失，会话层让新对话几乎不可能撞上（或误读到）
271
+ 上一场还没被收走的旧黑板 —— 时间戳精确到秒，理论上只有同一秒开跑的两个会话才会重名。
272
+ - **文件所有权**：每个制品是一个"一主题一文件"，只由一个 Agent 写
273
+ （`01-architect-auth-design.md`、`03-reviewer-auth-r1.md`）。单文件约 ≤100 行，
274
+ 超长就拆主题文件而不是任其膨胀。
275
+ - **写入即冻结**：修订 = 新的轮次后缀文件（`…-r2.md`）；绝不追加旧文件，
276
+ 后续 Agent 也永远读不到过时轮次。
277
+ - **Team Lead 是路由器**：每次 dispatch 携带清单——`Task:`（自包含任务书）、
278
+ `Reads:`（仅列出该工作包需要的文件）、`Write to:`（该 Agent 本次拥有的唯一文件）。
279
+ 子代理不读清单之外的任何东西，超长任务因此不会把无关上下文灌进子代理。
280
+ - **`MANIFEST.md` 是 lead 的状态板**：文件索引 + 顶部 ≤50 行的 `## Current state`
281
+ 节（阶段、仍然有效的决策、下一步），每轮闭环后更新——lead 跨长任务的压缩记忆。
282
+ - Team Lead 同时强制执行审查/测试**反馈闭环**：Critical/Major 问题和产品 bug
283
+ 自动转化为跟踪的修复任务，直到交付物收敛。
284
+
285
+ ### Ultra Review、流水线门禁与证据标准（v1.4.6）
286
+
287
+ - **Ultra Review**：每个非平凡变更由**三个并行 Reviewer 派单**审查，各管一个
288
+ 维度——完整性（需求覆盖）/ 正确性（逻辑与安全）/ 影响面（回归与波及面）——
289
+ 且各自被明令忽略其余两维。Lead 先把三份报告合并去重成一份按严重度分组的
290
+ 清单，再进入修复闭环。平凡变更可跳过审查，但须一行理由。
291
+ - **流水线门禁**：调研全部完成才定计划；设计先行于实现；实现归队才测试；
292
+ 测试通过才审查；用户可见的前端改动必须通过 UI 验证才算完成；最终报告
293
+ 等所有代理收工、看板状态属实。平凡任务跳过阶段须一行理由。
294
+ - **证据标准**："完成 / 修复 / 通过"的声明必须附可验证证据——命令输出、
295
+ 日志、diff、截图。纯叙述只是进度说明，不是证明（对子代理和 lead 同样生效）。
296
+ - **README 优先**：lead 在规划前先读项目 README（及 AGENTS.md / CLAUDE.md），
297
+ 并把有约束力的约定复述进每次派单；子代理对清单内项目约定视同强制。
298
+ - **逐字契约**：需要互通的并行实现代理，其数据契约（端点、字段名、类型）只写
299
+ 一份并**逐字**贴进每个相关派单——契约错配是集成 bug 之首。
300
+ - **CHANGELOG 维护**：项目带有 CHANGELOG.md 时，交付的改动会按
301
+ Keep a Changelog 风格追加条目。
302
+
303
+ ### Triage —— 提问不会变成代码修改
304
+
305
+ Team Lead 对每条消息先分类再行动：咨询/提问只得到回答（零文件改动，发现缺陷
306
+ 仅**提议**修复并等待你放行）；只有明确的行动指令才进入工作流。并且一旦你写明
307
+ 了哪些能碰哪些不能碰，**这些边界高于一切规则**——lead 会在每次派发中原样重申。
308
+
309
+ ### 清理 —— 只有 TTL 清扫器一条路
310
+
311
+ | 责任方 | 时机 |
312
+ |---|---|
313
+ | 插件代码（进程内清扫器） | 启动时 + 每小时：清除空闲超过 **TTL** 的任务目录 |
314
+
315
+ Team Lead 不再删除任务目录 —— 跑完的黑板原地留给你回看审计；回收由纯代码
316
+ 完成，从不依赖模型"记得删"，崩溃/强杀留下的残骸同样会被清扫。清扫器对活跃
317
+ 会话内的过期任务逐个回收，对整个闲置的会话目录一次性收走。TTL 可用
318
+ `ttlDays` 调节。
319
+
320
+ ### 自定义 TTL
321
+
322
+ 默认为 **5 天**。想自定义，在 `opencode.jsonc` 中使用元组形式的插件声明：
323
+
324
+ ```jsonc
325
+ {
326
+ "$schema": "https://opencode.ai/config.json",
327
+ "plugin": [
328
+ ["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]
329
+ ]
330
+ }
331
+ ```
332
+
333
+ `ttlDays` 接受 `(0, 365]` 内的天数；非法值静默回退到 5 天。
334
+
335
+ ### 默认代理
336
+
337
+ TeamMode 默认**把 Team 设为你的默认代理**——新会话直接由团队调度者接管。
338
+ 占默认槽附带一个排序效应：选择器会把**默认代理钉在第一位**、其余按名称
339
+ 字母升序，所以顺序为 **team, build, plan**。（想让 Team 排在 Plan 之下？
340
+ 那必须放弃默认槽——见下方退出开关；按服务端的排序规则二者不可兼得。）
341
+
342
+ 不想占用默认代理槽（`build` 保持默认，顺序 **build, plan, team**）则退出：
343
+
344
+ ```jsonc
345
+ {
346
+ "plugin": [
347
+ ["@te-river/opencode-team-mode@latest", { "defaultAgent": false }]
348
+ ]
349
+ }
350
+ ```
351
+
352
+ 用户显式配置的非 `build` 默认代理永远原样保留——插件从不覆写。
353
+
354
+ **升级提示**：v1.4.4 曾短暂改为 opt-in（默认不占用）；v1.4.5 恢复
355
+ Team-as-default 出厂行为。若你在 v1.4.4 期间加过 `{ "defaultAgent": true }`，
356
+ 现在可以删掉该选项（或改为 `false` 主动退出）。
357
+
358
+ ---
359
+
360
+ ## 🔧 自定义
361
+
362
+ ### Team Lead 的模型最关键
363
+
364
+ Lead 是编排大脑：它给每条消息分类、把工作切成包、写每份派发清单、裁决
365
+ reviewer/tester 的发现、合成最终交付。这里的质量问题会**沿流水线放大**——
366
+ 平庸的 Lead 拆错任务、给专家的指令含糊、放走劣质产出；没有任何专家能
367
+ 救回一份从一开始就派错的工单。
368
+
369
+ 所以：自定义模型时**Lead 位上请放你负担得起的最强模型**。其他角色可以用便宜模型——
370
+ 它们拿到的指令书精确、阅读范围受限，容错更高。按 agent 钉模型：
371
+
372
+ ```jsonc
373
+ {
374
+ "agent": {
375
+ // Team Lead —— 编排值得最好的模型
376
+ "team": { "model": "anthropic/claude-opus-4-5" },
377
+ // 专家角色 —— 便宜一档通常够用
378
+ "implementer": { "model": "anthropic/claude-sonnet-4-6" }
379
+ }
380
+ }
381
+ ```
382
+
383
+ （以上模型 ID 仅为示例，换成你服务商实际提供的即可。你自定义的
384
+ `agent.team` 永远优先于插件注入的版本。）
385
+
386
+ ### 覆盖某个 Agent
387
+
388
+ 在 `opencode.json` 中添加同名 Agent —— 你的定义会优先生效：
389
+
390
+ ```jsonc
391
+ {
392
+ "agent": {
393
+ "reviewer": {
394
+ "model": "anthropic/claude-sonnet-4-6",
395
+ "prompt": "你是一个极其严格的审查员。任何 lint 警告都必须打回。"
396
+ }
397
+ }
398
+ }
399
+ ```
400
+
401
+ ### 添加自己的 Agent
402
+
403
+ TeamMode 不阻止你添加更多 Agent，与团队 Agent 并存：
404
+
405
+ ```jsonc
406
+ {
407
+ "agent": {
408
+ "devops": {
409
+ "mode": "subagent",
410
+ "description": "处理 CI/CD、Docker 和部署任务",
411
+ "prompt": "你是 DevOps 工程师..."
412
+ }
413
+ }
414
+ }
415
+ ```
416
+
417
+ ### 禁用某个 Agent
418
+
419
+ ```jsonc
420
+ {
421
+ "agent": {
422
+ "researcher": { "disable": true }
423
+ }
424
+ }
425
+ ```
426
+
427
+ ---
428
+
429
+ ## 📦 发布到 npm
430
+
431
+ 如果你想发布自己的 fork：
432
+
433
+ ```bash
434
+ npm run build # 编译 TypeScript → dist/
435
+ npm version patch # 更新版本号
436
+ npm publish # 发布到 npm 仓库
437
+ ```
438
+
439
+ ---
440
+
441
+ ## 🤝 贡献
442
+
443
+ 欢迎贡献！以下方向特别需要帮助：
444
+
445
+ - 🌐 **本地化** — 将 Agent prompt 翻译为其他语言
446
+ - 🎨 **更多 Agent 角色** — DevOps、DBA、安全专家、UX 设计师
447
+ - 🔧 **更多命令** — `/team-deploy`、`/team-docs`、`/team-refactor`
448
+ - 📝 **更好的 Prompt** — 通过 Prompt 工程优化 Agent 行为
449
+
450
+ ---
451
+
452
+ ## 📄 许可证
453
+
454
+ [Apache License 2.0](./LICENSE)
455
+
456
+ ---
457
+
458
+ ## 🔗 链接
459
+
460
+ - [npm 包](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode`
461
+ - [OpenCode 桌面版](https://opencode.ai) — 官网 & 下载
462
+ - [OpenCode 文档](https://opencode.ai/docs) — 配置 & 插件文档
463
+ - [OpenCode 插件 API](https://opencode.ai/docs/plugins) — 构建你自己的插件
464
+ - [OpenCode GitHub](https://github.com/anomalyco/opencode) — OpenCode 源码