@te-river/opencode-team-mode 1.5.5 → 1.5.7

package/README.zh-CN.md

@@ -1,576 +1,511 @@
-# OpenCode TeamMode
-
-**[English](./README.md)** | **[中文](./README.zh-CN.md)**
-
-[![npm version](https://img.shields.io/npm/v/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
-[![npm downloads](https://img.shields.io/npm/dm/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
-[![license](https://img.shields.io/npm/l/@te-river/opencode-team-mode.svg)](./LICENSE)
-
-> 🤝 **[OpenCode 桌面版](https://opencode.ai) 多 Agent 团队协作插件**
->
-> 为你的 OpenCode 桌面版添加一整支 AI 专家团队 —— 架构师、实现者、审查员、测试员、调研员，由 Team Lead 统一调度，通过简单的斜杠命令即可调用。
-
----
-
-## ✨ TeamMode 是什么？
-
-TeamMode 将 OpenCode 桌面版从一个单 Agent 编码助手，升级为**一整个开发团队**。每个 Agent 拥有独立的角色定位、专业领域和行为风格 —— 就像真实的工程团队。
-
-不再是一个 Agent 包揽所有事，你将获得：
-
-| Agent | 角色 | 使用场景 |
-|---|---|---|
-| 🎯 **Team Lead** | 调度者 | 需要规划 + 多步执行的复杂任务 |
-| 🏗️ **Architect** | 系统设计师 | 设计文档、模块结构、API 契约 |
-| 💻 **Implementer** | 代码实现者 | 编写生产代码、实现功能 |
-| 🔍 **Reviewer** | 单维审查员 | 单维度审查（完整性 / 正确性 / 影响面）——lead 三路并行后合并 |
-| 🧪 **Tester** | 测试工程师 | 单元测试、集成测试、边界覆盖、静态验证（构建 / 类型检查 / lint / API 测试） |
-| 🔎 **Researcher** | 知识调研员 | 库评估、API 文档、最佳实践调研 |
-
----
-
-## 🚀 快速开始
-
-### 前置条件
-
-1. **安装 OpenCode 桌面版**（如果还没有）：
-
-   | 平台 | 安装命令 |
-   |---|---|
-   | macOS (Apple Silicon) | `brew install --cask opencode-desktop` |
-   | macOS (Intel) | `brew install --cask opencode-desktop` |
-   | Windows | `scoop bucket add extras && scoop install extras/opencode-desktop` |
-   | Linux | 从 [opencode.ai/download](https://opencode.ai/download) 下载 |
-
-   或安装 **CLI/TUI** 版本：
-   ```bash
-   # 一键脚本（全平台）
-   curl -fsSL https://opencode.ai/install | bash
-
-   # 或通过 npm
-   npm install -g opencode-ai
-   ```
-
-2. **Node.js ≥ 18**（用于 npm）
-
-### 安装 TeamMode
-
-**方式 A — 一键安装脚本：**
-
-macOS / Linux（bash）：
-```bash
-curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.sh | bash
-```
-
-Windows（PowerShell）：
-```powershell
-irm https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.ps1 | iex
-```
-
-**方式 B — 手动配置：**
-
-在你的 `opencode.jsonc` 中添加插件：
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "@te-river/opencode-team-mode@latest"
-  ]
-}
-```
-
-OpenCode 启动时会自动安装插件。
-
-> **提示：** 修改 `opencode.json` 后，**重启 OpenCode Desktop** 使配置生效。
-
----
-
-## ⚙️ 配置
-
-插件会在 OpenCode 启动时自动注入所有团队 Agent 和命令，**无需手动复制任何 Agent 文件或命令定义**。
-
-> ⚠️ **模型选择很重要。** 工作流里的每一个判断——分诊、拆解、派单、
-> 整合、审查/测试闭环裁决——都经过 **Team Lead**。这个位置上放弱模型，
-> 专家再强也救不回整条流水线。如需自定义，还请给你的 `team` agent 钉上你能负担的最强
-> 推理模型（配方见下方「自定义」节）。
-
-### 全局安装（所有项目生效）
-
-要在所有项目中启用 TeamMode，将插件添加到全局配置：
-
-```jsonc
-// ~/.config/opencode/opencode.jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "@te-river/opencode-team-mode@latest"
-  ]
-}
-```
-
----
-
-## 📖 使用方法
-
-### 斜杠命令
-
-TeamMode 为 OpenCode 添加了六个斜杠命令，在聊天输入框中输入：
-
-| 命令 | Agent | 说明 |
-|---|---|---|
-| `/team-plan <任务>` | Architect | 创建详细的实现计划：架构、文件清单、任务拆解 |
-| `/team-implement <任务>` | Implementer | 为功能或任务编写生产代码 |
-| `/team-review [范围]` | Reviewer | 审查代码的 Bug、安全问题和质量问题 |
-| `/team-test [范围]` | Tester | 生成全面的测试，覆盖边界场景 |
-| `/team-research <主题>` | Researcher | 调研库、API 或最佳实践 |
-| `/team-run <任务>` | Team Lead | **完整工作流** — 端到端调度所有 Agent |
-
-#### 示例工作流
-
-```bash
-# 1. 规划功能
-/team-plan 添加基于 OAuth2 和 JWT 的用户认证
-
-# 2. 审查计划后，开始实现
-/team-implement 按计划实现认证模块
-
-# 3. 审查代码
-/team-review src/auth/
-
-# 4. 编写测试
-/team-test src/auth/
-
-# 或者让 Team Lead 全程调度：
-/team-run 添加基于 OAuth2 和 JWT 的用户认证
-```
-
-### Agent 选择器
-
-你也可以在 OpenCode 桌面版中使用 `@` 直接调用 Agent：
-
-- `@team` — 调度复杂任务
-- `@architect` — 设计系统或模块
-- `@implementer` — 编写代码
-- `@reviewer` — 审查代码质量
-- `@tester` — 编写测试
-- `@researcher` — 调研主题
-
-### 演示
-
-以下是一段会话实录的还原。Team 出厂即默认代理（退出方法见下方配置），
-用户开新会话直接输入：
-
-> **用户：** 给我们的 Express API 加令牌桶限流——每用户每分钟 100 请求，
-> 超限返回 429。不要动 `src/legacy/` 下的任何东西。
-
-```text
-team   路由：产品行为变更 → implementer → tester → reviewer
-       （3 次派发 → 触发审批门）
-
-       调研：已读 README、src/app.ts、src/middleware/*
-       阻塞性问题：无 —— 1 条假设列在下方
-
-       计划
-       目标：令牌桶限流，100 请求/分/用户，429 + Retry-After
-       范围：src/middleware/rateLimit.ts（新增）、src/app.ts（+3 行）
-       流水线：implementer → tester → reviewer（correctness）
-       假设：内存桶而非 Redis —— 要改说一声
-       边界：src/legacy/** 不动
-       批准后开工？
-
-用户   批准，开始
-
-team   ▸ @implementer — STATUS: done
-       CHANGES: src/middleware/rateLimit.ts（新增）· src/app.ts（+3）
-       HANDOFF: bucket {tokens, lastRefill}；refill() 单次原子完成
-       EVIDENCE: tsc 无错误（输出见上）
-
-       ▸ @tester — STATUS: done · VERDICT: pass（14/14）
-       FINDINGS: 覆盖突发边界、窗口过期、并发回充；
-                 src/legacy/** 逐字节未变
-       EVIDENCE: vitest 14 passed
-
-       ▸ @reviewer — STATUS: done · VERDICT: approve（correctness）
-       FINDINGS: 无 Critical/Major；1 条 Minor（日志噪音）已记录
-
-team   完成。
-       限流器已交付：rateLimit.ts（新增）· app.ts（+3）· 14 测试全绿
-       审查：通过 · 假设：仅内存存储 · src/legacy/ 未动
-```
-
-用户只输入了任务本身和"批准，开始"。流水线是路由表查表的结果；执行在
-计划获批前一步不动；每次交接都是结构化骨架——零文件仪式。
-
-### 桌面版专属特性
-
-在 **OpenCode 桌面版** 中，你还能获得额外的 UX 体验：
-
-- 🎨 **Agent 颜色标识** — 每个 Agent 在聊天 UI 中有独立颜色，便于识别
-- 📋 **Agent 选择器** — 点击 Agent 下拉菜单，可视化切换团队 Agent
-- 🔀 **并行子任务** — Team Lead 可同时调度多个子 Agent，结果在并行面板中展示
-- 📊 **会话历史** — 所有团队交互都保存在桌面版侧边栏，可搜索回溯
-
----
-
-## 🧯 上下文治理（tm_* + R6 + R2）—— v1.5.1 起提供
-
-> ⚠️ 需 `@te-river/opencode-team-mode@1.5.1` 或更新（2026-09-08 发布）。
-> 配置里钉 `@latest` 的用户，下次启动自动升级。
-
-**JIT 层 2 工具（`tm_read` / `tm_grep` / `tm_bash` / `tm_fetch`）。**
-大体积工具输出是上下文成本的主要来源：智能体每走一步都要重发整个窗口。
-tm_* 工具先用受治理的管线执行内置能力：超过 `TM_OFFLOAD_THRESHOLD`
-token 的结果**不进窗口**——全量写入本地 run 存储，模型只拿一张句柄
-“提货单”，附内容感知预览（JSON 键结构 / CSV 表头+形状 / 日志
-ERROR×N 统计 / 代码签名清单 / 二进制元信息，硬上限 80 token）。
-确实需要全文时，用 HMAC 签名、限本 run、带有效期的句柄经 `tm_fetch`
-分段取回。`tm_bash` 仅放行只读命令白名单，失败以结构化错误返回。
-
-**R6 环境变量保护（现已升级为审批门控）。** TeamMode 激活时，模型无法
-静默读取环境变量。env 导出命令（`printenv`、`env`、`Get-ChildItem env:`
-等）与环境文件（`.env`、shell rc 文件）会走 OpenCode **官方确认弹窗**：
-你会在桌面收到一次原生确认，超过 `TM_ASK_TIMEOUT_MIN`（默认 10 分钟）
-无人响应即**自动拒绝**——插件超时只会拒绝，绝不为模型自我放行。通配符
-表达不了的形态（命令里内嵌的 `$VAR` / `${VAR}` / `$env:`、命令替换、
-子 shell/转义写法）以及 `tm_*` 包装通道仍维持**代码级硬拦**（没有弹窗
-可钻）。tm_* 包装工具同样过这套检查（不给包装层留后门）。审计日志只记
-工具名 + 模式类别 + 裁决事件（`ask` / `allowed-once` / `allowed-always` /
-`rejected` / `timeout-rejected` / `degraded`）——绝不记录命令文本、路径、
-变量名或值。
-
-**R2 危险操作（同一个确认弹窗）。** 删除（`rm`/`del`/`Remove-Item`/
-`rmdir`）、git 发布（`git push`/`git commit`）、网络（`curl`/`wget`/
-`Invoke-WebRequest`/`Invoke-RestMethod`）、包安装与发布（`npm install`/
-`npm publish`/`pip install`/`winget`/`choco`）、进程/系统（`taskkill`/
-`Stop-Process`/`kill`/`shutdown`/`format`）、权限（`chmod`/`takeown`/
-`icacls`）——都不再静默放行，而是弹同一个官方确认框，超时未响应即自动
-拒绝。日常验证栈（`npm test`、`tsc`、`git status`/`diff`）**不在**门控
-之列，团队协作照常无打扰运行。
-
-> ⚠️ **批准弹窗时请选 once（仅此一次），不要选 always。** 真实宿主实测：
-> always 记录的泛化规则远比当次命令宽——对 `Get-ChildItem env:PATH` 选
-> always 会记下 `Get-ChildItem *`，此后所有 `Get-ChildItem` 都不再弹窗。
-> 只有 once 能让每次危险操作继续单独过人手。
-
-> 延后是**按会话**生效的：只有运行 TeamMode 注入角色的会话（或已弹过这类
-> 确认框的会话）里的 env 读取才会被放行给弹窗；其他会话（如原生
-> `build`/`plan`）里守护仍然直接硬拦——那里根本没有弹窗兜底。宿主对复合
-> 命令（`a; b`）按段评估、单次弹窗批准整条；任一子段是 env 读取时守护整条
-> 拦截。
-
-> 权限协议已在真实 `opencode serve` 宿主（1.18.29）上经 SSE 事件捕获实测
-> 核验；桌面弹窗的渲染本身仍需在真实 Desktop 会话里目视确认一次。非交互
-> `opencode run` 下，无人应答的 `ask` 会被立即自动拒绝（没有人类可弹）。
-
-| 环境变量 | 默认 | 作用 |
-|---|---|---|
-| `TM_ENV_PROTECT` | `strict` | R6 模式：`strict` / `standard` / `off`（off 同时解除审批计时器） |
-| `TM_ASK_TIMEOUT_MIN` | `10` | R6/R2 确认弹窗无人应答后自动拒绝的分钟数；最小 3 分钟（宿主的 `permission.replied` 经事件总线到达插件约延迟 ~120 秒——更小的值会把刚获批的请求误拒） |
-| `TM_ENV_PROTECT_EXTRA_DENY` | — | 追加拦截正则（分号分隔；始终硬拦，不走弹窗） |
-| `TM_OFFLOAD_THRESHOLD` | `2000` | 卸载阈值（token，chars/4 估算） |
-| `TM_PREVIEW_MAX_TOKENS` | `80` | 预览硬上限 |
-| `TM_FETCH_MAX_LINES` | `2000` | tm_fetch 单段上限 |
-| `TM_BLACKBOARD_DIR` | `.blackboard/` | 卸载载荷存储 |
-| `TM_TRAJECTORY_DIR` | `.trajectory/` | 只追加工具调用账本 |
-| `TM_BLACKBOARD_TTL` | `7` | 存储保留天数 |
-| `TM_BASH_READONLY_ALLOWED` | 内置表 | tm_bash 只读白名单 |
-| `TM_PTC_MAX_PROGRAM_CHARS` | `4000` | PTC 程序源码长度上限（字符） |
-| `TM_PTC_MAX_CALLS` | `20` | PTC 单次运行桥接调用数上限（1–200） |
-| `TM_PTC_MAX_ERRORS` | `3` | PTC 单次运行错误数上限（1–50） |
-| `TM_PTC_TIMEOUT_MS` | `60000` | PTC 单次运行墙钟超时（5 秒–10 分钟） |
-| `TM_PTC_ENGINE` | `auto` | PTC 引擎：`auto`（worker→inline 降级）/ `worker` / `inline` |
-
----
-
-## ⚡ 批量编排（`tm_ptc_run`）—— v1.5.2 起提供
-
-> 已随 **v1.5.2**（2026-09-10）发布。需 `@te-river/opencode-team-mode@1.5.2` 或更新。
-
-`tm_ptc_run` 让专家代理编写**一个异步程序**，在单次回合中执行 N 次受治理的
-`tm_*` 调用——运行期间零 LLM 往返，仅将聚合摘要返回上下文。设计用于批量
-只读任务：多文件侦察、批量 grep + read 聚合、交叉引用搜索结果。
-
-### 工作原理
-
-代理使用 `tm.read(args)`、`tm.grep(args)`、`tm.bash(args)`、`tm.fetch(args)`
-编写程序体——参数与四个受治理工具相同。每次调用返回 `{ok:true, data}`（已受
-治理：内联文本或卸载句柄）或 `{ok:false, error:{tool,phase,line?,message}}`。
-程序 `return` 一个值；它会被 JSON 序列化进聚合摘要。
-
-包含 `require`、`import`、`process`、`globalThis`、`Deno`、`Bun`、`fs`、`net`
-或 `child_process` 的程序会在执行前被拒绝（静态预扫描，辅助防护）。
-
-### 预算（仅收紧）
-
-调用方可收紧 `max_calls`、`max_errors` 和 `timeout_ms`——超过 `TM_PTC_*` 上限
-的值会被钳制到上限；低于下限的值会被钳制到下限。触达任一预算即整体停止运行；
-已产出的输出不会丢失。
-
-### 引擎（`TM_PTC_ENGINE`）
-
-| 模式 | 行为 |
-|---|---|
-| `auto`（默认） | 优先尝试 `worker_threads`；失败时降级为 `node:vm`，摘要标记 `degraded-engine` |
-| `worker` | 强制使用 worker 引擎（失败时返回 engine-error） |
-| `inline` | 强制使用 `node:vm` 引擎（30 秒编译超时斩杀同步忙等；await 间隙残余已记录） |
-
-worker 引擎在专用线程中运行程序，`env:{}` 清空 process.env、`resourceLimits`
-限量、硬墙钟 `terminate()`。所有治理（P2 路径范围、P3 白名单、R6、阈值卸载、
-TTL）对每次桥接调用生效——PTC 不是绕过层。
-
-### 访问权限
-
-五个专家代理（`implementer`、`tester`、`architect`、`reviewer`、`researcher`）
-的白名单中包含 `tm_ptc_run`。`team` lead 不包含——它负责编排，不运行批量程序。
-
----
-
-## 🏗️ 架构
-
-```
-opencode-team-mode/
-├── package.json          ← npm 包定义
-├── tsconfig.json         ← TypeScript 配置
-├── src/
-│   ├── index.ts          ← 插件入口（server()：config + R6 tool.execute.before + 审批门 event 钩子 + tool 段）
-│   ├── agents.ts         ← Agent 定义（prompts、模式、颜色）
-│   ├── commands.ts       ← 命令定义（模板、Agent 绑定）
-│   ├── blackboard.ts     ← 共享黑板 + TTL 自动清理清扫器
-│   ├── envprotect.ts     ← R6 环境变量读取保护 + R2 确认弹窗模式集（弹窗 vs 硬拦）
-│   ├── approval-gate.ts  ← 统一审批门：官方弹窗超时自动拒绝（绝不自我放行）
-│   ├── tm/               ← JIT 层 2 工具（tm_read / tm_grep / tm_bash / tm_fetch / tm_ptc_run）
-│   └── types.ts          ← 加载器契约类型定义（1.18.x）
-├── scripts/
-│   ├── install.sh        ← 一键安装脚本（bash）
-│   └── install.ps1       ← 一键安装脚本（PowerShell）
-├── pt07/                 ← PT-07 基线任务集（种子化 A/B token 测量）
-├── LICENSE               ← Apache 2.0
-└── README.md             ← 英文文档
-    README.zh-CN.md       ← 中文文档
-```
-
-### 工作原理
-
-1. OpenCode 桌面版启动，加载 `opencode.json(c)`
-2. 检测到 `plugin` 数组中的 `"@te-river/opencode-team-mode@latest"`，加载 npm 包
-3. 加载器调用插件的 `server(input, options)`，注册 `config` hook；hook 向合并后的配置注入 6 个 Agent 和 6 个命令。同一次调用还会安装 R6 的 `tool.execute.before` 防护、武装 R6/R2 统一审批门（官方确认弹窗 + `TM_ASK_TIMEOUT_MIN` 超时自动拒绝，经 `event` 钩子驱动），并注册受治理的 `tm_*` 工具（见下文“上下文治理”）
-4. 插件的 `id: "team-mode"` 作为插件名显示在桌面版 UI
-5. Agent 和命令立即在桌面版 UI 中可用 —— 无需复制任何文件；同名 Agent 以用户自定义优先（插件绝不覆盖）
-
----
-
-## 🗂️ 协作机制：结构化交接优先，文件其次（混合制）
-
-子代理之间无法实时互发消息（平台限制），TeamMode 通过**结构化回复骨架**协调它们，
-文件黑板只保留给超大产出：
-
-- **回复骨架（主通道）**：每个专家的最终回复以
-  `STATUS: / CHANGES: / FINDINGS: / EVIDENCE: / HANDOFF:` 开头，全文 ≤50 行。
-  这个尺寸的产出直接内联传递——零文件 I/O，没有"文件没写上"这种故障面。
-  Lead 把 `HANDOFF` 原文转贴进下一次派单，并对骨架做机器校验
-  （缺失 → 带 skeleton 原文重试一次 → 仍违规则降级记入报告）。
-- **黑板文件（仅例外）**：完整产出确实超过 ~50 行时（如完整架构设计文档），
-  派单点名唯一文件：
-  `<repo>/.git/opencode-team/<session-key>/<task-slug>/NN-<role>-<topic>.md`
-  ——位于 `.git/` 内，**绝不污染**工作区和 commit（非 git 工作区回退系统临时目录）。
-  写入即冻结：修订 = 新的轮次后缀文件（`…-r2.md`）；会话目录层让新对话
-  不会撞上尚未清扫的旧黑板。
-- **没有 MANIFEST.md**：lead 的状态记忆就是它的 todo list。
-- **反馈闭环**：Critical/Major 发现和产品 bug 自动转化为跟踪的修复任务，
-  直到交付物收敛（最多 2 轮，之后升级给用户）。
-
-### 确定性路由、审批门与自适应评审（v1.4.7）
-
-- **路由表**：lead 按任务形状查固定流水线行——提问 → 直接回答；纯文档 →
-  implementer；产品行为变更 → implementer → tester → reviewer；多模块/跨接口
-  功能 → architect → implementer → tester → reviewer(s)；未知外部技术 →
-  researcher 前置。流水线有固定下限：产品变更路由到少于 3 次派发即是路由 bug；
-  把一个请求拆成多个 <2 派发的子任务以规避审批门 = 协议违规。
-- **审批门（按计数触发）**：预计派发 ≥2 → lead 先调研（亲自读仓库；仅未知外部
-  技术才派 researcher），呈交 ≤30 行计划，然后**等待你的批准**才执行任何东西。
-  0-1 次派发的小任务以 1-2 行通报直接开工。执行中发现需要第 2 次派发 →
-  暂停等批准。阻塞性不确定**立即批量问一次**——不猜测、不挤牙膏。
-- **自适应评审**：默认 1 个 reviewer 派单（correctness 维度）；仅高风险画像
-  ——鉴权/安全面、跨模块数据契约、≥3 文件的公共 API 变更——才升级为
-  3 维并行（完整性 / 正确性 / 影响面）。
-- **静态验证**：tester 通过构建、类型检查、静态分析、API/单元测试验证。
-  禁止即兴发明浏览器自动化（headless 截图、DOM stub）；用户可见前端改动
-  以 `UI NOT VERIFIED: <待人工检查项>` 如实收尾，除非项目本身已带真实
-  浏览器测试设施。
-- **无仪式捷径**：lead 已亲自验证的根因（file:line 证据）直接变成修复规格
-  派给 implementer——调查性派单服务于未知，不服务于仪式感。
-- **简明纪律**：路由选择是查表；用户可见的计划性文字 ≤5 行。
-- **证据标准（保留）**："完成 / 修复 / 通过"的声明必须附可验证证据——命令
-  输出、日志、diff。纯叙述只是进度说明，不是证明。
-- **逐字契约（保留）**：需要互通的并行实现代理，其数据契约（端点、字段名、
-  类型）逐字贴进每个相关派单——契约错配是集成 bug 之首。
-- **文档同步（CHANGELOG + AGENTS.md）**：交付的改动在 CHANGELOG.md 存在时按
-  Keep a Changelog 风格追加条目；当改动会影响 AGENTS.md 所记录的内容
-  （构建/测试命令、约定、项目结构、agent 指引）时同步更新它；任一文件缺失
-  时提议代建。阅读去重：README 由 lead 亲自阅读（宿主不会注入）；
-  AGENTS.md/CLAUDE.md 若宿主已注入则直接使用上下文中的副本——仅在确实缺失时
-  才打开文件；专家不会自己去重读这些文档——约定由 lead 蒸馏进派单。
-
-### Triage —— 提问不会变成代码修改
-
-Team Lead 对每条消息先分类再行动：咨询/提问只得到回答（零文件改动，发现缺陷
-仅**提议**修复并等待你放行）；只有明确的行动指令才进入工作流。并且一旦你写明
-了哪些能碰哪些不能碰，**这些边界高于一切规则**——lead 会在每次派发中原样重申。
-
-### 清理 —— 只有 TTL 清扫器一条路
-
-| 责任方 | 时机 |
-|---|---|
-| 插件代码（进程内清扫器） | 启动时 + 每小时：清除空闲超过 **TTL** 的任务目录 |
-
-Team Lead 不再删除任务目录 —— 跑完的黑板原地留给你回看审计；回收由纯代码
-完成，从不依赖模型"记得删"，崩溃/强杀留下的残骸同样会被清扫。清扫器对活跃
-会话内的过期任务逐个回收，对整个闲置的会话目录一次性收走。TTL 可用
-`ttlDays` 调节。
-
-### 自定义 TTL
-
-默认为 **5 天**。想自定义，在 `opencode.jsonc` 中使用元组形式的插件声明：
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    ["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]
-  ]
-}
-```
-
-`ttlDays` 接受 `(0, 365]` 内的天数；非法值静默回退到 5 天。
-
-### 默认代理
-
-TeamMode 默认**把 Team 设为你的默认代理**——新会话直接由团队调度者接管。
-占默认槽附带一个排序效应：选择器会把**默认代理钉在第一位**、其余按名称
-字母升序，所以顺序为 **team, build, plan**。（想让 Team 排在 Plan 之下？
-那必须放弃默认槽——见下方退出开关；按服务端的排序规则二者不可兼得。）
-
-不想占用默认代理槽（`build` 保持默认，顺序 **build, plan, team**）则退出：
-
-```jsonc
-{
-  "plugin": [
-    ["@te-river/opencode-team-mode@latest", { "defaultAgent": false }]
-  ]
-}
-```
-
-用户显式配置的非 `build` 默认代理永远原样保留——插件从不覆写。
-
-**升级提示**：v1.4.4 曾短暂改为 opt-in（默认不占用）；v1.4.5 恢复
-Team-as-default 出厂行为。若你在 v1.4.4 期间加过 `{ "defaultAgent": true }`，
-现在可以删掉该选项（或改为 `false` 主动退出）。
-
----
-
-## 🔧 自定义
-
-### Team Lead 的模型最关键
-
-Lead 是编排大脑：它给每条消息分类、按路由表查流水线、写每份派单、裁决
-reviewer/tester 的发现、合成最终交付。这里的质量问题会**沿流水线放大**——
-平庸的 Lead 拆错任务、给专家的指令含糊、放走劣质产出；没有任何专家能
-救回一份从一开始就派错的工单。
-
-所以：自定义模型时**Lead 位上请放你负担得起的最强模型**。其他角色可以用便宜模型——
-它们拿到的指令书精确、阅读范围受限，容错更高。按 agent 钉模型：
-
-```jsonc
-{
-  "agent": {
-    // Team Lead —— 编排值得最好的模型
-    "team": { "model": "anthropic/claude-opus-4-5" },
-    // 专家角色 —— 便宜一档通常够用
-    "implementer": { "model": "anthropic/claude-sonnet-4-6" }
-  }
-}
-```
-
-（以上模型 ID 仅为示例，换成你服务商实际提供的即可。你自定义的
-`agent.team` 永远优先于插件注入的版本。）
-
-### 覆盖某个 Agent
-
-在 `opencode.json` 中添加同名 Agent —— 你的定义会优先生效：
-
-```jsonc
-{
-  "agent": {
-    "reviewer": {
-      "model": "anthropic/claude-sonnet-4-6",
-      "prompt": "你是一个极其严格的审查员。任何 lint 警告都必须打回。"
-    }
-  }
-}
-```
-
-### 添加自己的 Agent
-
-TeamMode 不阻止你添加更多 Agent，与团队 Agent 并存：
-
-```jsonc
-{
-  "agent": {
-    "devops": {
-      "mode": "subagent",
-      "description": "处理 CI/CD、Docker 和部署任务",
-      "prompt": "你是 DevOps 工程师..."
-    }
-  }
-}
-```
-
-### 禁用某个 Agent
-
-```jsonc
-{
-  "agent": {
-    "researcher": { "disable": true }
-  }
-}
-```
-
----
-
-## 📦 发布到 npm
-
-如果你想发布自己的 fork：
-
-```bash
-npm run build        # 编译 TypeScript → dist/
-npm version patch    # 更新版本号
-npm publish          # 发布到 npm 仓库
-```
-
----
-
-## 🤝 贡献
-
-欢迎贡献！以下方向特别需要帮助：
-
-- 🌐 **本地化** — 将 Agent prompt 翻译为其他语言
-- 🎨 **更多 Agent 角色** — DevOps、DBA、安全专家、UX 设计师
-- 🔧 **更多命令** — `/team-deploy`、`/team-docs`、`/team-refactor`
-- 📝 **更好的 Prompt** — 通过 Prompt 工程优化 Agent 行为
-
----
-
-## 📄 许可证
-
-[Apache License 2.0](./LICENSE)
-
----
-
-## 🔗 链接
-
-- [npm 包](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode`
-- [OpenCode 桌面版](https://opencode.ai) — 官网 & 下载
-- [OpenCode 文档](https://opencode.ai/docs) — 配置 & 插件文档
-- [OpenCode 插件 API](https://opencode.ai/docs/plugins) — 构建你自己的插件
-- [OpenCode GitHub](https://github.com/anomalyco/opencode) — OpenCode 源码
+# OpenCode TeamMode
+
+**[English](./README.md)** | **[中文](./README.zh-CN.md)**
+
+[![npm version](https://img.shields.io/npm/v/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
+[![npm downloads](https://img.shields.io/npm/dm/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
+[![license](https://img.shields.io/npm/l/@te-river/opencode-team-mode.svg)](./LICENSE)
+
+> 🤝 **你的 OpenCode 刚刚招了一个团队。**
+>
+> 六个专职 agent——主脑（Lead）、架构师、实现者、评审、测试、研究员——配上受治理的工具、结构化交接和"先出计划等你批准"的门禁。一个插件，零配置文件要拷。
+
+> 💡 **建议在中或大型项目下使用该模式。** 治理层（审批门禁、上下文卸载、工具白名单）在代码库有真实体量时是资产，在小脚本和一次性问答上则主要是开销。把团队用在配得上它的地方。
+
+---
+
+## 太长不看
+
+> **懒人路径：** 把下面这段话粘给任意编码 agent，让它替你装：
+>
+> ```text
+> 安装 OpenCode 插件 @te-river/opencode-team-mode：按照
+> https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/docs/installation.md
+> 的指引完成安装，并按该指南里的检查项验证。
+> ```
+>
+> **装好后只需要记住一条命令：** `/team-run <任务>` —— Team Lead 会先出计划、
+> 等你批准、然后调度整个团队干活。
+
+剩下的都是细节。想看的时候按图索骥：
+
+**[为什么](#-为什么是-teammode) · [团队阵容](#-团队阵容) · [安装](#-安装) · [使用](#-使用) · [工具与安全](#-受治理的工具与安全) · [搜索](#-真正好用的网络搜索中国可用) · [配置](#️-配置) · [运作方式](#️-团队怎么运作) · [FAQ](#-faq) · [卸载](#️-卸载)**
+
+---
+
+## 🤔 为什么是 TeamMode？
+
+单个 agent 包打一切的下场你多半见过：上下文窗口塞满 5000 行的文件转储，
+一个脚本能干的事跟 bash 磨二十个回合，子 agent 悄悄读你的 `.env`，以及
+所谓的"联网调研"——其实全靠模型编。
+
+TeamMode 对每一个的回应：
+
+| 痛点 | TeamMode 的回答 |
+|---|---|
+| 🔥 **上下文爆炸** | 所有受治理工具的输出超过 2000 token 就卸载到本地 run 存储，换成 80 token 的预览 + HMAC 句柄。agent 需要什么再分页取什么——窗口永远淹不了。 |
+| 🐌 **回合开销** | `tm_ptc_run`：agent 写**一个程序**，单回合内发起 N 次受治理调用。运行期间零 LLM 回合。 |
+| 🕳️ **静默副作用** | R6/R2 审批门禁：环境变量读取和危险操作走 OpenCode 官方确认弹窗，10 分钟没人理自动拒绝。插件从不代替你批准——它只会拒绝。 |
+| 🌫️ **幻觉式调研** | 联网是双角色的授权 + 白名单受治理工具链。抓不到的事实就报告为缺口——绝不编造。 |
+
+底下还有流程纪律：确定性路由表、≥2 次派工先出 ≤30 行计划等你批、agent
+之间用 `STATUS/CHANGES/FINDINGS/EVIDENCE/HANDOFF` 结构化交接、以及静态
+验证（构建 / 类型检查 / 测试）说了算，不靠感觉。
+
+这套纪律也正是"**建议中大型项目使用**"的原因：两三个文件的小脚本，团队
+本来就没多少可治理的东西。
+
+---
+
+## 👥 团队阵容
+
+| Agent | 角色 | 什么时候用 |
+|---|---|---|
+| 🎯 **Team Lead** (`@team`) | 编排者 | 需要规划 + 多步执行的复杂任务 |
+| 🏗️ **Architect** | 系统设计 | 设计文档、模块结构、API 契约 |
+| 💻 **Implementer** | 写代码 | 做功能、写生产代码 |
+| 🔍 **Reviewer** | 维度审计 | 默认单维度评审；高风险变更才三维度并行 |
+| 🧪 **Tester** | 测试工程师 | 带真边界条件的测试；静态验证（构建 / 类型检查 / lint）；经 `tm_browser` 的治理化 UI 验证 |
+| 🔎 **Researcher** | 找资料 | 本地仓库优先，然后才是网络——两个联网角色之一（另一个是 Lead） |
+
+开箱即用时 **Team 就是你的默认 agent**——新会话直接进编排者（可在
+[配置](#️-配置)里关掉）。
+
+---
+
+## 📦 安装
+
+### 方式一：让 agent 替你装（推荐）
+
+把这段话粘给任意编码 agent——它会改配置、提醒你重启、并完成验证：
+
+```text
+安装 OpenCode 插件 @te-river/opencode-team-mode：按照
+https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/docs/installation.md
+的指引完成安装，并按该指南里的检查项验证。
+```
+
+（该指南就是完整的手动流程——配置文件位置、插件条目、重启、验证、更新、
+卸载。你的 agent 会忠实执行，不需要其他任何东西。）
+
+### 方式二：一行脚本
+
+macOS / Linux（bash）：
+
+```bash
+curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.sh | bash
+```
+
+Windows（PowerShell）：
+
+```powershell
+irm https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.ps1 | iex
+```
+
+### 方式三：手动
+
+把插件加进 `opencode.jsonc`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "@te-river/opencode-team-mode@latest"
+  ]
+}
+```
+
+OpenCode 下次启动时装好。
+
+### ⚠️ 现在读一遍，以后省一小时
+
+- **改完配置要重启。** 碰了 `opencode.json` 之后，完全退出再启动 OpenCode（桌面版从托盘退出，不是只关窗口）。
+- **插件更新：重跑安装脚本即可。** 安装器是幂等的——重跑会补齐配置（已存在则跳过）、清掉过期插件缓存、并重解析 npm 安装的副本。之所以需要这一步：OpenCode 按 spec 字符串缓存插件，新版本发布后不会重新解析 `@latest`（上游已知问题）。想手动操作的话：
+
+  | 系统 | 缓存位置 |
+  |---|---|
+  | macOS / Linux | `rm -rf ~/.cache/opencode/packages/@te_river+opencode-team-mode@latest` |
+  | Windows | `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\opencode\cache\packages\@te_river+opencode-team-mode@latest"` |
+
+  如果插件还被 npm 装进了 `~/.config/opencode`，package-lock 会钉住版本——在那里再跑一次 `npm install @te-river/opencode-team-mode@latest`。完整配方（含 agent 更新提示词）见[安装指南·更新](./docs/installation.md)。
+- **前置条件：** [OpenCode](https://opencode.ai)（桌面版或 CLI）+ Node ≥ 18。
+
+### 验证
+
+重启后打开 agent 选择器，看到 **team、architect、implementer、reviewer、
+tester、researcher** 就齐了——团队已就位。
+
+---
+
+## 📖 使用
+
+### 斜杠命令
+
+| 命令 | Agent | 说明 |
+|---|---|---|
+| `/team-plan <任务>` | Architect | 带架构、文件清单、任务拆解的实施计划 |
+| `/team-implement <任务>` | Implementer | 为功能或任务写生产代码 |
+| `/team-review [范围]` | Reviewer | 审计 bug、安全问题、质量隐患 |
+| `/team-test [范围]` | Tester | 带边界条件的全面测试 |
+| `/team-research <主题>` | Researcher | 本地仓库优先；网络走受治理工具 |
+| `/team-run <任务>` | Team Lead | **完整流程**——计划 → 批准 → 编排 → 验证 |
+
+也可以直接 `@` 提及：`@team`、`@architect`、`@implementer`、`@reviewer`、
+`@tester`、`@researcher`。
+
+### 一次运行长什么样
+
+Team 默认就是默认 agent，所以你只管在全新会话里打字：
+
+> **你：** 给我们的 Express API 加令牌桶限流——每用户每分钟 100 次，超了返回 429。别碰 `src/legacy/` 底下任何东西。
+
+```text
+team   路由：产品行为变更 → implementer → tester → reviewer
+       （3 次派工 → 触发审批门禁）
+
+       计划
+       目标：令牌桶限流，100 req/min/user，429 + Retry-After
+       范围：src/middleware/rateLimit.ts（新增）、src/app.ts（+3 行）
+       流水线：implementer → tester → reviewer（正确性）
+       假设：内存桶，不上 Redis——要改就说
+       边界：src/legacy/** 不碰
+       批准后开工？
+
+你     批准，干
+
+team   ▸ @implementer — STATUS: done
+       CHANGES: src/middleware/rateLimit.ts (new) · src/app.ts (+3)
+       EVIDENCE: tsc 干净
+
+       ▸ @tester — STATUS: done · VERDICT: pass (14/14)
+       FINDINGS: 突发边沿、窗口过期、并发补充已覆盖；
+                 src/legacy/** 逐字节未动
+
+       ▸ @reviewer — STATUS: done · VERDICT: approve（正确性）
+
+team   完成。rateLimit.ts (new) · app.ts (+3) · 14 测试全绿
+       评审：approve · 假设：仅内存 · src/legacy/ 未动
+```
+
+你输入了任务和四个字。计划是查路由表，执行等你的批准，agent 之间的交接
+全部走结构化骨架——没有文件仪式，没有靠猜。
+
+---
+
+## 🧰 受治理的工具与安全
+
+TeamMode 加的每个工具都跑在**同一条治理管线**下：超过 `TM_OFFLOAD_THRESHOLD`
+token 的输出永不进入上下文窗口——卸载到 run 存储，换成内容感知预览 +
+HMAC 句柄，agent 真需要 payload 时用 `tm_fetch` 分页取。
+
+| 工具 | 功能 | 角色 |
+|---|---|---|
+| `tm_read` / `tm_grep` / `tm_bash` / `tm_fetch` | 受治理的文件读 / 正则搜索 / 只读 shell（白名单）/ 句柄分页 | 全部六个 agent |
+| `tm_memory` | 项目 + 全局记忆库（Markdown + frontmatter）：add / search / list / forget | 全部六个 agent |
+| `tm_ptc_run` | 批量编排：一个程序、N 次受治理调用、零 LLM 回合 | 全部六个 agent |
+| `tm_search` | 多引擎网络搜索，返回提取去重后的命中列表 | Lead + Researcher |
+| `tm_webfetch` | 白名单页面的单次受治理 GET（搜索页自动提取） | Lead + Researcher |
+| `tm_browser` | 交互式浏览器会话（headful CDP）：open / navigate / read / screenshot / close | Lead + Researcher + Tester（仅 UI 验证） |
+
+> **固定工具优先级阶梯（每个任务都适用）：① TeamMode 受治理工具（`tm_*`）
+> → ② 用户 MCP/插件工具 → ③ 模型自己的推理。** 它同时是回退链：某个受治理
+> 工具报错（这台机器没浏览器、主机被拦），agent 会说明情况降到下一级，
+> 而不是躺平。
+
+所有受治理工具都**支持并行**：宿主可以把一批 `tm_search` / `tm_webfetch` /
+`tm_fetch` 调用并发执行——每次调用拿到自己的 step id 和自己的 payload，
+互不串扰（并行测试套件钉死了这一点）。
+
+### 上下文治理：卸载、句柄、预览
+
+大的工具输出是上下文成本的主要来源——每一步都要重发整个窗口。所以超过
+`TM_OFFLOAD_THRESHOLD` 的结果写进本地 run 存储（`<repo>/.git/opencode-team/`，
+永不污染工作树），换成带内容感知预览的句柄：JSON 键 / CSV 表头+形状 /
+日志 ERROR×N 统计 / 代码签名 / 二进制元数据，硬顶 80 token。agent 真需要
+payload 时用 `tm_fetch`（HMAC 签名、run 域、带过期）分页读。`tm_bash`
+只放行只读命令（白名单），失败以结构化错误返回，不糊原始转储。
+
+### 项目 + 全局记忆（tm_memory）
+
+耐久的事实——构建命令、环境怪癖、架构决策、你的约定——以人可编辑的
+Markdown + frontmatter 存放：
+
+- **`project`**（默认）：`<repo>/.git/opencode-team/memories/…` —— 每 checkout 一份，贴近 git。
+- **`global`**：`~/.opencode-team/memories/global/`（可用 `TM_MEMORY_GLOBAL_DIR` 覆盖）——**跟着你走遍所有项目**。
+
+动作：`add` / `search`（确定性关键词打分）/ `list` / `forget`；每条记忆
+上限 4000 字符。agent 被要求先搜记忆再做项目假设，也把来之不易的事实
+存下来留给下个会话。
+
+### 🌐 真正好用的网络搜索（中国可用）
+
+`tm_search` 是开放式查询的前锋：**一次调用、一个 query、干净结果**。引擎
+URL 替你拼好、走受治理管线抓取、压缩成编号的"标题+链接"命中列表——
+agent 永远看不到原始搜索页的噪音。
+
+| 引擎 | 说明 |
+|---|---|
+| `bing`（默认） | cn.bing.com；`bing-int` 强制国际版结果（`ensearch=1`） |
+| `sogou` / `so`（360） | 国产引擎，CJK 内容友好 |
+| `baidu` | 反爬最凶，但有时是唯一的中文特化索引；失败时会点名替代引擎 |
+| `bilibili` | 视频搜索 |
+| `moegirl` | MediaWiki 搜索 API——词条标题 + 摘要，结构化 |
+| `npm` | registry 搜索 → name@version + 描述，结构化 |
+| `github` | 仓库搜索 API → star 数 + 描述，结构化 |
+
+九个引擎在中国大陆**全部免 Key 可达**，且全部在种子域名白名单内。空结果
+（反爬拦截页）时错误信息会点名替代引擎，不让 agent 卡死。另两条通道补全
+能力面：
+
+- `tm_webfetch` —— 已知 URL，单次受治理 GET。它抓到的搜索引擎页面同样
+  自动提取为命中列表。`registry.npmjs.org/<pkg>/latest` 这类 JSON 端点
+  原样透传。
+- `tm_browser` —— JS 渲染页：驱动你自己的 Chromium 系浏览器，CDP pipe
+  headful 运行，隔离临时 profile，**域名白名单在网络层逐请求强制**
+  （`Fetch.requestPaused` → 非白名单主机直接 `BlockedByClient`）。
+
+种子白名单（两个工具共用）：`mobile.moegirl.org.cn`、`search.bilibili.com`、
+`cn.bing.com`、`www.bing.com`、`www.baidu.com`、`www.sogou.com`、
+`www.so.com`、`registry.npmjs.org`、`api.github.com`——用
+`TM_WEBFETCH_ALLOWED_DOMAINS` 扩展（`"*"` 放开全部主机）。architect /
+implementer / reviewer **没有**联网授权——网络问题会报告为缺口，绝不编造。
+tester 仅持有 `tm_browser`，用于本项目的治理化 UI 验证（本地开发服务器、
+预览路由）；开放网络抓取仍归两个联网角色。
+
+### 安全：R6 + R2 审批门禁
+
+**R6 环境变量保护。** TeamMode 激活时，模型不能悄悄读环境变量。env 读取
+（`printenv`、`env`、`Get-ChildItem env:` 等）和 env 文件（`.env`、shell rc）
+走 OpenCode **官方确认弹窗**；没人应答的弹窗在 `TM_ASK_TIMEOUT_MIN`（默认
+10 分钟）后**自动拒绝**。通配符表达不了的 env 读取（命令内嵌 `$VAR` /
+`${VAR}` / `$env:`、命令替换）和 `tm_*` 包装通道保持**硬拦截**——没有弹窗
+可钻。审计日志只记录工具名 + 模式类别 + 裁决——绝不记录命令文本、路径、
+变量名或值。
+
+**R2 危险操作（同一个弹窗）。** 删除、git 发布、网络抓取、包安装/发布、
+进程/系统、提权——统统不允许静默放行。日常验证栈（`npm test`、`tsc`、
+`git status`）**不在**门禁内，日常开发不受打扰。
+
+> ⚠️ **批准弹窗时选"一次"，别选"总是"。** 在真实宿主上验证过，"总是"记录
+> 的规则远比你看到的那条命令宽：用"总是"批准 `Get-ChildItem env:PATH`
+> 会存下 `Get-ChildItem *`，之后所有 `Get-ChildItem` 都不再弹窗。
+
+> 弹窗改道是按会话的：env 读取只在运行 TeamMode 注入 agent 的会话里才走
+> 弹窗；其他会话里守卫保持硬拦截。`headless opencode run` 会立即自动拒绝
+> 没人应答的 `ask`（没有人可问）。
+
+### 仓库卫生
+
+卸载/轨迹/记忆存储都在 `<repo>/.git/opencode-team/`（非 git 目录则用系统
+临时目录）——**永不进工作树**。每个 agent 被要求完工前删掉自己的临时文件，
+一次性产物进系统临时目录。TTL 清扫器在启动时 + 每小时回收过期任务目录；
+Team Lead 自己从不删黑板，你可以随时审计任何一次运行。
+
+---
+
+## ⚙️ 配置
+
+插件在启动时注入一切——没有 agent 文件要拷。
+
+> **模型选择很关键。** 分诊、拆解、派工简报、汇总、评审裁决——全从 Team
+> Lead 一点上过。那个座位坐个弱模型，专家再强也白搭。把你能拿到的最强
+> 推理模型钉在 `team` 上：
+
+```jsonc
+{
+  "agent": {
+    "team": { "model": "anthropic/claude-opus-4-5" },         // Lead 配最强
+    "implementer": { "model": "anthropic/claude-sonnet-4-6" } // 专家角色便宜模型够用
+  }
+}
+```
+
+**全局安装** —— 把插件条目放进 `~/.config/opencode/opencode.jsonc`，每个项目都有团队。
+
+**不想让 Team 占默认位：**
+
+```jsonc
+{
+  "plugin": [
+    ["@te-river/opencode-team-mode@latest", { "defaultAgent": false }]
+  ]
+}
+```
+
+你自己定义的同名 agent 永远优先；插件从不覆盖用户定义。覆盖、加人、停用
+见[自定义](#-自定义)。
+
+### 环境变量
+
+| 环境变量 | 默认 | 用途 |
+|---|---|---|
+| `TM_ENV_PROTECT` | `strict` | R6 模式：`strict` / `standard` / `off`（off 同时解除审批计时器） |
+| `TM_ASK_TIMEOUT_MIN` | `10` | 无人应答弹窗自动拒绝前等待的分钟数（硬下限 3——宿主的应答事件到插件晚约 120 秒） |
+| `TM_ENV_PROTECT_EXTRA_DENY` | — | 额外拦截模式（正则；永远硬拦截，不走弹窗） |
+| `TM_OFFLOAD_THRESHOLD` | `2000` | 卸载阈值（token，CJK 感知估算） |
+| `TM_PREVIEW_MAX_TOKENS` | `80` | 预览硬顶 |
+| `TM_FETCH_MAX_LINES` | `2000` | tm_fetch 单页行数上限 |
+| `TM_BLACKBOARD_DIR` / `TM_TRAJECTORY_DIR` | `<repo>/.git/opencode-team/…` | 卸载存储 / 轨迹账本（tmpdir 回退；显式值 = 绝对或项目相对） |
+| `TM_BLACKBOARD_TTL` | `7` | 存储保留天数 |
+| `TM_BASH_READONLY_ALLOWED` | 内置表 | tm_bash 白名单 |
+| `TM_WEBFETCH_ALLOWED_DOMAINS` | 九个种子主机 | tm_webfetch / tm_search / tm_browser 白名单（`"*"` 全开；空 = 全拒） |
+| `TM_BROWSER_PATH` | 自动探测 | tm_browser 可执行文件覆盖（按 OS 探测 Edge/Chrome/Chromium） |
+| `TM_BROWSER_HEADLESS` | `auto` | `1` 无头（CI）/ `0` 有头 / `auto`（仅无显示的 Linux 用无头） |
+| `TM_MEMORY_GLOBAL_DIR` | `~/.opencode-team/memories/global/` | tm_memory GLOBAL 作用域存储 |
+| `TM_PTC_MAX_PROGRAM_CHARS` | `4000` | PTC 程序源码上限 |
+| `TM_PTC_MAX_CALLS` | `20` | PTC 单次运行桥接调用预算（1–200） |
+| `TM_PTC_MAX_ERRORS` | `3` | PTC 单次运行错误预算（1–50） |
+| `TM_PTC_TIMEOUT_MS` | `60000` | PTC 单次运行墙钟超时（5s–10min） |
+| `TM_PTC_ENGINE` | `auto` | `auto`（worker→inline 降级）/ `worker` / `inline` |
+
+---
+
+## ⚙️ 团队怎么运作
+
+子 agent 之间不能实时互发消息（平台限制），所以 TeamMode 用**结构化回复
+骨架**协调——每个专家的回复都是 `STATUS: / CHANGES: / FINDINGS: / EVIDENCE:
+/ HANDOFF:`，≤50 行，Lead 原文转投给下一次派工。文件是例外不是常规：超过
+约 50 行的交付物写**一个**指名的黑板文件，放在 `<repo>/.git/opencode-team/`
+下（round 后缀，工作树分毫不动）。
+
+- **路由表：** 提问 → 直接回答；纯文档 → implementer；产品行为变更 →
+  implementer → tester → reviewer；多模块 → architect → implementer →
+  tester → reviewer(s)；陌生技术 → researcher 先行。固定下限——产品变更
+  路由低于 3 次派工就是路由 bug。
+- **审批门禁（计数式）：** ≥2 次派工 → 计划（≤30 行）→ **等你批准** → 执行。
+  阻塞性问题立刻批量问，不猜、不挤牙膏。
+- **自适应评审：** 默认一名评审；高风险画像（鉴权/安全面、跨模块契约、
+  公共 API）才三维度并行。
+- **静态验证：** 构建 / 类型检查 / lint / 测试。禁止临时起意的浏览器自动化；
+  未验证的 UI 工作以 `UI NOT VERIFIED: <待人工检查项>` 收尾。
+- **证据标准：** "完成 / 修好 / 通过"必须带可验证证据——输出、日志、diff。
+
+---
+
+## 🔧 自定义
+
+**覆盖某个 agent** —— 同名即覆盖：
+
+```jsonc
+{
+  "agent": {
+    "reviewer": {
+      "model": "anthropic/claude-sonnet-4-6",
+      "prompt": "你是个极严格的评审。有 lint 警告一律打回。"
+    }
+  }
+}
+```
+
+**在团队旁加自己的 agent：**
+
+```jsonc
+{
+  "agent": {
+    "devops": {
+      "mode": "subagent",
+      "description": "负责 CI/CD、Docker 和部署任务。",
+      "prompt": "你是 DevOps 工程师……"
+    }
+  }
+}
+```
+
+**停用一个：** `"researcher": { "disable": true }`。
+
+**黑板保留期** 用元组形式：`["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]`（有效区间 (0, 365]，非法值回退 5）。
+
+---
+
+## ❓ FAQ
+
+**会不会很烧 token？**
+恰恰相反，省 token 就是设计目标。卸载 + 80 token 预览 + PTC 批量程序的存在
+理由就是：五 agent 流水线要是裸接一个上下文窗口，那才叫烧 token。治理本身
+就是省 token 的机制。
+
+**联网安全吗？**
+这是全插件防守最严的面：两个完整联网角色 + 仅浏览器的 tester 授权、域名
+白名单、重定向逐跳复检、浏览器
+网络层强制、env 文件 URL 拒绝，且每个 payload 都走同一套卸载治理。白名单
+页面不可能把抓取弹到站外。
+
+**插件为什么不自动更新？**
+OpenCode 按 spec 字符串缓存插件，从不重新解析 `@latest`（上游问题，不是
+我们的）。**重跑安装脚本就是更新**（它会清缓存、重解析 npm 副本）；或者
+手动删缓存目录。配方在上面和[安装指南](./docs/installation.md)里。
+
+**agent 能并行调工具吗？**
+能——而且是为并行**专门设计**的：并行的 `tm_search` / `tm_webfetch` /
+`tm_fetch` 拿到互不相同的 step id 和互相隔离的 payload。这里出回归，测试
+套件会在它到你面前之前先红。
+
+**CLI（TUI）能用吗，还是只有桌面版？**
+都能。桌面版多了彩色 agent 选择器和并行面板；受治理工具和整个工作流与
+宿主无关。无显示的 Linux 上 `tm_browser` 自动转无头。
+
+**确认弹窗我不理会会怎样？**
+`TM_ASK_TIMEOUT_MIN`（默认 10 分钟）后自动拒绝。插件从不自我批准——它
+能站的队只有"你"或者"没人"。
+
+---
+
+## 🗑️ 卸载
+
+1. 从配置文件的 `"plugin"` 数组里移除该条目。
+2. 想回收磁盘就删缓存目录（见[安装](#-现在读一遍以后省一小时)里的表格）。
+3. 重启 OpenCode。agent、命令、工具全部消失；`<repo>/.git/opencode-team/`
+   下的存储（全局记忆在 `~/.opencode-team/`）都是普通文件，随时可删。
+
+没有 DLL 受伤。工作树什么都没写。
+
+---
+
+## 🏛️ 架构（给好奇的人）
+
+```
+opencode-team-mode/
+├── src/
+│   ├── index.ts          ← 插件入口（config + R6 守卫 + 审批门禁 + 工具段）
+│   ├── agents.ts         ← Agent 结构（mode、颜色、温度、白名单矩阵）
+│   ├── prompts/          ← Agent 提示词（lead / specialists / shared）——测试钉死
+│   ├── commands.ts       ← 斜杠命令定义
+│   ├── blackboard.ts     ← 共享黑板 + TTL 清扫
+│   ├── envprotect.ts     ← R6 门面（patterns / 分类器 / 门禁谓词 / hook）
+│   ├── approval-gate.ts  ← 统一审批门禁（弹窗超时自动拒绝）
+│   ├── tm/               ← 受治理工具：pipelines / store / preview / guard / refs /
+│   │                        webfetch / search / memory / browser / shell-bridge / ptc/（9 模块）
+│   └── types.ts          ← 加载器契约类型（1.18.x）
+├── docs/installation.md  ← agent 可消费的安装指南
+├── scripts/              ← 一行安装脚本（bash / PowerShell）
+├── pt07/                 ← PT-07 基线套件（种子化 A/B token 测量）
+└── README.*.md           ← 你在这里（有两个版本）
+```
+
+加载器只调一次 `server(input, options)`：`config` 钩子注入六个 agent 和六个
+命令，同一次调用装上 R6 `tool.execute.before` 守卫、通过 `event` 钩子布防
+审批门禁、注册 `tm_*` 工具。用户自定义的同名 agent 永远赢——插件从不覆盖。
+
+---
+
+## 🤝 参与贡献
+
+欢迎 issue 和 PR。特别需要：agent 提示词的多语言化、更多角色、更多命令
+模板，以及各搜索引擎真实行为的实测报告（它们经常改版；提取器的过滤故意
+放宽，但不会读心术）。
+
+---
+
+## 📄 许可
+
+[Apache License 2.0](./LICENSE)
+
+---
+
+## 🔗 链接
+
+- [npm 包](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode`
+- [安装指南](./docs/installation.md) — 完整的手动 / agent 可消费流程
+- [OpenCode Desktop](https://opencode.ai) — 官网与下载
+- [OpenCode 文档](https://opencode.ai/docs) — 配置与插件文档
+- [OpenCode 插件 API](https://opencode.ai/docs/plugins) — 开发你自己的插件