# @cr903/opencode-swarm 中文文档

规范地址：https://npmcn.com/package/%40cr903/opencode-swarm/

版本：1\.11\.0
npm 元数据更新时间：2026-11-07T04:48:36.343Z
中文译文更新时间：2026-11-10T21:58:35.589Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cr903/opencode-swarm
原文对照：https://npmcn.com/package/%40cr903/opencode-swarm/?lang=original
项目主页：https://github.com/CR903/opencode-swarm#readme
源码仓库：https://github.com/CR903/opencode-swarm

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

- 包体积（解压后）：425 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：4 个
- 首次发布：2026-11-02T03:01:29.564Z
- 最新版本发布：2026-11-07T04:48:36.176Z
- 近 30 天下载量：2986（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Swarm多会管弦乐为OpenCode:计划员分出任务,dev执行器,测试员独立验证,审查员审计语义. 原子队列 沙盒核查门 时间表审计 TUI板.

## 安装

```sh
npm install @cr903/opencode-swarm
```

也可以使用：`pnpm add @cr903/opencode-swarm`、`yarn add @cr903/opencode-swarm`、`bun add @cr903/opencode-swarm`

## README

# @cr903/opencode-swarm

Swarm 多会话编排插件（OpenCode v2）：planner 拆任务 → dev 实现 → tester 独立验收 → reviewer 语义评审 → 自动派下一单。从生产仓库提炼，300+ 回归用例锁定。

-   原子队列（tmp+fsync+rename / 目录锁 / CAS）+ FSM 状态机单源
-   门禁管道：verify 真跑 + verdict/commit 绑定 + policy 禁区 + secret 扫描 + diff/security（lint/type/tenant 可选）
-   时间线溯源（timeline.jsonl 可重放 rebuild）+ 本地事件通道（FileBus）
-   高风险软卡（人工 approve）、3-strike 熔断、revert 回门禁前、nightly 只读重跑、eval 导出
-   TUI 大屏（sidebar 窄卡 + 整页 board + footer 状态行，只读）

## 安装

```bash
opencode plugin add @cr903/opencode-swarm
# 或在 opencode.json(c) 里加：
# { "plugins": ["@cr903/opencode-swarm"] }
opencode service restart
```

要求：Node ≥ 18，git 可用。插件零运行时依赖（除 `@opencode/plugin` 与 TUI 的 `solid-js` / `@opentui/*`）。

## 上手（三步）

```bash
/swarm-init      # 安装配套文件到本项目：agents/*.md + .opencode/review/_default.md（已存在的不覆盖；skills 随插件自动注册）
/swarm-up --planner-model <p> --dev-model <d> --tester-model <t> --name <需求名>
# 默认主会话即 planner：直接在当前窗口
#plan 拆解 <需求或PRD路径>
/swarm-start     # 必须显式派发（up 只开轮不派发；未 start 前 dev/test 认领会被拒）
```

> 想恢复「另建一个 plan 会话」的旧行为：`/swarm-up ... --plan-session new`。

完整操作手册见 [`docs/swarm-使用手册.md`](https://npmcn.com/package/%40cr903/opencode-swarm/docs/swarm-%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C.md)，设计说明见 [`docs/swarm-SPEC.md`](https://npmcn.com/package/%40cr903/opencode-swarm/docs/swarm-SPEC.md)。

## 命令速查

`/swarm-up /swarm-start /swarm-status /swarm-drained /swarm-halt /swarm-retry /swarm-revert /swarm-nightly /swarm-eval /swarm-runs /swarm-switch /swarm-migrate /swarm-models /swarm-mode /swarm-clean`（共 17 个，另有 `/swarm-board` TUI 大屏）。

工具（agent 调用）：`swarm_plan / swarm_claim / swarm_next / swarm_done / swarm_test / swarm_review / swarm_approve / swarm_halt / swarm_revert / swarm_read_queue / swarm_config`。

角色：`swarm-plan`（只拆不写）→ `swarm-dev`（一次一单）→ `swarm-test`（独立验证，write/edit deny）→ `swarm-reviewer`（只审不改，subagent）。

## 插件 options（opencode.json）

```jsonc
{
  "plugins": [["@cr903/opencode-swarm", {
    "queue": ".swarm/queue.jsonl",   // 兼容旧调用；默认按 run 切分到 .swarm/runs/<id>/
    "maxRetries": 3,                 // test fail 熔断阈值
    "verifyTimeoutMs": 300000,
    "allowlist": ["task"],           // 追加到 verify_cmd 白名单
    "autoWake": true,
    "policyDeny": [],                // 追加禁区
    "sensitivePaths": [],            // 命中即按高风险提示
    "gates": { "lint": true, "type": true, "tenant": true },  // 默认关闭的门
    "executor": "hybrid"             // sessions | subagents | hybrid（默认 hybrid：dev/plan 走会话，test/reviewer 走子代理）
  }]]
}
```

## 门禁说明

-   `verify`：白名单裸命令（禁 shell 拼接），异步跑 + 硬超时 + 输出截断。
-   `lint` 默认跑 `make gate`（可 `lint_cmd` 覆盖）；`type` **必须显式传 `type_cmd`**（本包不假设技术栈，未传直接拒收并指引）；`tenant` 默认跑包内 `lib/swarm-tenant-check.mjs`，检查脚本按 `SWARM_TENANT_CHECK` 环境变量 → 当前仓库 `smarterlab-backend/scripts/tenant-check.sh` 查找，缺失给明确指引退出（自备脚本或传 `tenant_cmd`）。
-   `review=true` 的任务 test pass 后进 `reviewing`，`swarm_review` 出结论（`Important` 必答，`Nit` 不拦，`wontfix` 须写 reason）。

## 运行时产物（在你的项目里，不进包）

```
.swarm/runs/<runId>/{queue.jsonl,timeline.jsonl,events.jsonl,round.json,meta.json}
  round.json = { name, sessions:{plan,dev,test}, members:{<sessionID>: {role, at}} }
               members 记录主会话/子代理等非角色会话，供「会话 → run」反查（footer 跟随 / sidebar 高亮）
  meta.json  = { name, createdAt, executor, roleModels{dev,dev_backend,dev_frontend,test,reviewer}, startedAt?, pendingStart?, prdPath? }
               pendingStart=true 表示「up 已开轮、尚未 /swarm-start」，dev/test 认领会被拒；
               roleModels 按需：backend→dev_backend、frontend→dev_frontend（legacy dev 通配），test/reviewer 按需索要
.swarm/secret-baseline.json   # secret 门基线（只报新增）
.swarm/current                # 当前轮指针（并行多轮时仅作兜底：run 解析优先会话/任务归属）
.swarm/eval/<month>.jsonl     # /swarm-eval 导出
```

## 测试

```bash
npm test   # node --test tests/（单元 + 端到端 + board 数据层，随功能增长）
```

## 1.1.0 行为变更（并行多轮修复）

-   **默认主会话即 planner**：`/swarm-up` 不再另建 plan 会话（`plan = 发起命令的会话`）；旧行为用 `--plan-session new`。
-   **`/swarm-start` 是唯一派发授权**：`/swarm-up` 只开轮不派发；`pendingStart` 期间 `swarm_claim / swarm_next` 拒收（`force:true` 逃生）。
-   **run 解析不再只看全局指针**：`显式 run > 任务归属（task_id）> 会话绑定 > .swarm/current`，并行两轮互不抢指针。
-   **命名/跟随**：`round.name` 与 `meta.name` 同步双写；sidebar 以 `meta.name` 为规范名；footer/sidebar 高亮按 `round.sessions + round.members`（主会话、子代理）跟随。
-   空入队（全部被校验拒）不再改轮名。

## 版本与兼容

-   跟随 OpenCode v2 插件契约（`@opencode/plugin ^2`）；采用 OpenCode 新版时先跑 `npm test`。
-   agents 目录使用 Markdown agent 文件（v1 frontmatter，OpenCode 兼容读取）；skills 由插件在 setup 时自动注册。

## License

MIT — 见 [LICENSE](https://npmcn.com/package/%40cr903/opencode-swarm/LICENSE)。

## 常见问题

### @cr903/opencode-swarm 是什么？

Swarm多会管弦乐为OpenCode:计划员分出任务,dev执行器,测试员独立验证,审查员审计语义\. 原子队列 沙盒核查门 时间表审计 TUI板\.

### 如何安装 @cr903/opencode-swarm？

在项目目录运行 npm install @cr903/opencode-swarm，或使用 pnpm add / yarn add / bun add。

### @cr903/opencode-swarm 支持 TypeScript 吗？

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

### @cr903/opencode-swarm 支持 ESM 还是 CommonJS？

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

### @cr903/opencode-swarm 需要什么版本的 Node\.js？

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

### @cr903/opencode-swarm 可以商用吗？

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

### @cr903/opencode-swarm 的下载量有多少？

根据 npm 官方下载统计，@cr903/opencode-swarm 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,986 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cr903/opencode-swarm 还在维护吗？

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