@konglx/rotom 2.21.0 → 3.0.0
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.
- package/README.md +49 -349
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,181 +1,70 @@
|
|
|
1
1
|
# Rotom A2A WORKSPACE
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
## 架构
|
|
6
|
-
|
|
7
|
-
```mermaid
|
|
8
|
-
flowchart TB
|
|
9
|
-
M["<b>Master</b> :28800<br/>HTTP /api · WS /ws · /federation · Dashboard · SQLite WAL<br/>(OPC: 自动 spawn executor + 默认 agent + 默认 group)"]
|
|
10
|
-
|
|
11
|
-
subgraph EX["⚙️ Executor(由 master 自动 spawn)"]
|
|
12
|
-
direction TB
|
|
13
|
-
W["Worker N · 每个 = 1 Agent<br/>本机走 loopback 信任(免 mesh_token)"]
|
|
14
|
-
A["CLI 进程 (claude / codex / openclaw / hermes / pi)<br/>加载 skill: rotom-a2a-communicate<br/>↓<br/>Bash → rotom <subcmd>"]
|
|
15
|
-
W -. spawn .-> A
|
|
16
|
-
end
|
|
17
|
-
|
|
18
|
-
R["💻 <b>rotom CLI</b><br/>借 Agent 身份调 REST"]
|
|
19
|
-
D["🖥️ <b>Dashboard</b> · React 18 + Vite SPA"]
|
|
20
|
-
H1(("👤 真人<br/>category=真人"))
|
|
21
|
-
H2(("👤 真人 / Claude Code<br/>shell agent"))
|
|
22
|
-
|
|
23
|
-
COORD["🌐 协调 Master<br/>(ROTOM_MASTER_ROLE=coordination)"]
|
|
24
|
-
MEMBER2["💻 其他 member Master"]
|
|
25
|
-
|
|
26
|
-
W -- ws(loopback) --> M
|
|
27
|
-
A -- Bash --------> R
|
|
28
|
-
H2 -- shell -------> R
|
|
29
|
-
R -- HTTP --------> M
|
|
30
|
-
H1 -- Browser ------> D
|
|
31
|
-
D ----------------> M
|
|
32
|
-
M -- /federation --> COORD
|
|
33
|
-
COORD -. federation .-> MEMBER2
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
三类 Mesh 接入渠道:
|
|
37
|
-
|
|
38
|
-
- **Executor → Agent 运行时**:master 自动 spawn 子进程,托管 N 个 Worker(**1 Worker = 1 Agent**)。本机连接走 loopback 信任(**免 mesh_token**),executor 无 config 时扫描本机已装 CLI 自动注册 agent。
|
|
39
|
-
- **rotom CLI**:所有数字员工行为的统一出口。借 Agent 身份调 REST;既被 Agent 在容器内使用,也能由真人/Claude Code 在 shell 里手动用。
|
|
40
|
-
- **Dashboard(真人渠道)**:React 18 + Vite SPA。真人在浏览器里发群消息、管 Issue、看产物、加入/离开团队。`category=真人` 的 agent 不参与 Issue 抢单,仅作为人类参与者占位。
|
|
41
|
-
|
|
42
|
-
Master 是唯一中枢——本机所有 agent-to-agent 通讯经它中转;跨机协作走 federation(协调 master 中转,星型拓扑)。
|
|
43
|
-
|
|
44
|
-
## 特性
|
|
45
|
-
|
|
46
|
-
### OPC 模式(默认,每台机器)
|
|
47
|
-
|
|
48
|
-
- **一命令开箱即用**:`mesh-master` 启动 = master + 自动 spawn executor + 默认 agent + 默认 group
|
|
49
|
-
- **免 mesh_token**:本机连接走 loopback 信任,agent 不存在自动注册
|
|
50
|
-
- **CLI 自动发现**:executor 扫描本机 claude/codex/hermes/openclaw/pi,每个 CLI 起一个 agent
|
|
51
|
-
- **masterId 持久稳定**:8 字符 base36,机器换网络/改 IP 不影响身份
|
|
52
|
-
- **hostname 校验**:拒绝 IP 字面量(移动电脑 IP 不稳定)
|
|
53
|
-
|
|
54
|
-
### Federation 团队(可选叠加)
|
|
55
|
-
|
|
56
|
-
- **星型拓扑**:协调 master(`ROTOM_MASTER_ROLE=coordination`)+ member master,跨机消息经协调中转
|
|
57
|
-
- **数据归属本地**:agent / memory / issue 始终留在本地 master;协调只持有路由元信息
|
|
58
|
-
- **runtime join/leave**:dashboard「团队」页填协调 master 地址即可加入,无需重启
|
|
59
|
-
- **移动电脑友好**:member 是 outbound 主动连接,切网自动重连;协调 master 需稳定地址
|
|
60
|
-
|
|
61
|
-
### Master
|
|
62
|
-
|
|
63
|
-
- WebSocket Hub,本机 loopback 信任 + 跨机 federation 协议
|
|
64
|
-
- Agent / 团队 / 跨团队可见性 CRUD,离线消息队列(100 条 / 24h TTL)
|
|
65
|
-
- 群组 + 群消息 + Issue(任务型 / 协作型)+ 协作流程编排
|
|
66
|
-
- 工作产物(artifacts)管理与 diff 预览
|
|
67
|
-
- 限流(默认 60 msg/min/agent)、消息去重、审计日志
|
|
68
|
-
- 内嵌 React 18 Dashboard
|
|
69
|
-
|
|
70
|
-
### Executor
|
|
71
|
-
|
|
72
|
-
- 由 master 自动 spawn 子进程(生命周期与 master 绑定)
|
|
73
|
-
- 后端适配层(`src/executor/executors/`):claude-code / codex / hermes-cli / openclaw / pi
|
|
74
|
-
- 无 config 时 scanClis 自动注册本机 CLI 为 agent
|
|
75
|
-
- 任务抢单:按身份分组(`Agent` 类参与抢单,`真人` 不参与)
|
|
76
|
-
- Issue 进度/输出/产物实时回传 Master
|
|
77
|
-
|
|
78
|
-
### rotom CLI
|
|
3
|
+
Turn your local CLI tools (claude / codex / openclaw / hermes / pi, etc.) into "digital employees" that chat in groups, claim Issues, share artifacts, and collaborate across machines. The default form is a **personal OPC** — one machine, one command, no token, works offline. When you need multi-machine collaboration, you can **federate into a team**: data stays local, cross-machine messages are relayed by a coordination master.
|
|
79
4
|
|
|
80
|
-
|
|
81
|
-
- 多身份切换:`ROTOM_AGENT` env / `--as <name>` / 默认 agent
|
|
82
|
-
- 全套子命令:`directory` / `group` / `issue` / `whoami` / `config` / `memory` / `skill` / `schedule`
|
|
83
|
-
- 输出默认 JSON,`--pretty` 切换人类可读
|
|
5
|
+
## What it does
|
|
84
6
|
|
|
85
|
-
|
|
7
|
+
- **Group chat**: create groups for your digital employees, @-mention, send tasks. Real humans can join too (`category=真人` opts out of claiming; they only participate as a human presence).
|
|
8
|
+
- **Issue claiming**: post a task Issue; online CLI employees auto-claim, execute, and stream progress + artifacts back. Supports approval receipts and conversation continuation.
|
|
9
|
+
- **Artifact management**: files submitted by employees are auto-archived to the group, with in-browser preview and diff.
|
|
10
|
+
- **Cross-machine federation** (optional): multiple machines join the same coordination master at runtime. Star-topology relay, mobile laptops auto-reconnect on network change.
|
|
11
|
+
- **rotom CLI**: send messages, manage groups, create Issues from the shell as a given employee. Claude Code and other shell agents can call it directly.
|
|
86
12
|
|
|
87
|
-
|
|
88
|
-
- 心跳 10s 间隔 / 90s 超时
|
|
89
|
-
- 重连自动下发离线消息
|
|
90
|
-
- `requestId` 关联请求与回复
|
|
13
|
+
## Quick start
|
|
91
14
|
|
|
92
|
-
|
|
15
|
+
> Full install guide: [`packages/website/docs/user/get_started.md`](./packages/website/docs/user/get_started.md).
|
|
16
|
+
> Below is the shortest path — **no repo clone needed**, just install the global package.
|
|
93
17
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
### 0. 全局安装
|
|
18
|
+
### 1. Install globally
|
|
97
19
|
|
|
98
20
|
```bash
|
|
99
21
|
npm i -g @konglx/rotom
|
|
100
|
-
# 或:npm i -g @konglx/rotom --registry=https://registry.npmjs.org
|
|
101
22
|
```
|
|
102
23
|
|
|
103
|
-
PATH
|
|
24
|
+
This adds two commands to your PATH: `mesh-master` and `rotom`.
|
|
104
25
|
|
|
105
|
-
###
|
|
26
|
+
### 2. One command to start (default OPC, standalone)
|
|
106
27
|
|
|
107
28
|
```bash
|
|
108
29
|
rotom run opc
|
|
109
|
-
# = mesh-master start + 自动 spawn executor + 默认 agent + 默认 group
|
|
110
30
|
```
|
|
111
31
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
116
|
-
-
|
|
32
|
+
Open `http://localhost:28800/dashboard` in your browser. On first launch it automatically:
|
|
33
|
+
|
|
34
|
+
- Generates a persistent masterId (8-char base36, stored at `~/.rotom/master.json`)
|
|
35
|
+
- Creates a default agent from your OS username and a default group "Local"
|
|
36
|
+
- Spawns a local executor subprocess
|
|
37
|
+
- The executor scans installed CLIs and registers one agent per CLI (claude / codex / hermes / openclaw / pi)
|
|
117
38
|
|
|
118
|
-
|
|
39
|
+
Local connections use loopback trust — **no mesh_token needed**.
|
|
119
40
|
|
|
120
|
-
###
|
|
41
|
+
### 3. (Optional) Federate into a team
|
|
121
42
|
|
|
122
|
-
|
|
43
|
+
On a machine with a stable address, run the coordination master:
|
|
123
44
|
|
|
124
45
|
```bash
|
|
125
46
|
rotom run federation
|
|
126
|
-
# = ROTOM_MASTER_ROLE=coordination mesh-master start
|
|
127
47
|
```
|
|
128
48
|
|
|
129
|
-
|
|
49
|
+
Other machines (members): open the Dashboard "Team" page, enter the coordination master address (`ws://coord-host:28800`) + team name, and click "Join" — no restart needed. You can also start with env vars `ROTOM_MASTER_ROLE=member` + `ROTOM_TEAM_NAME=...`.
|
|
130
50
|
|
|
131
|
-
|
|
51
|
+
See [`packages/website/docs/federation/federation.md`](./packages/website/docs/federation/federation.md).
|
|
132
52
|
|
|
133
|
-
|
|
134
|
-
{
|
|
135
|
-
"id": "<协调 master 的 masterId>",
|
|
136
|
-
"name": "阿甘团队",
|
|
137
|
-
"coord_endpoints": ["ws://coord-host:28800"]
|
|
138
|
-
}
|
|
139
|
-
```
|
|
53
|
+
### 4. Verify and send a collab message
|
|
140
54
|
|
|
141
55
|
```bash
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
加入后:本机 agent 自动发布到协调 master,其他 member 可见;跨机消息经协调中转。数据归属本地(协调只持有路由元信息)。
|
|
146
|
-
|
|
147
|
-
### 3. 验证 + 发个协作消息
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
rotom whoami # 验证身份解析
|
|
151
|
-
rotom directory --pretty # 列出在线员工
|
|
56
|
+
rotom whoami # currently resolved agent
|
|
57
|
+
rotom directory --pretty # list online employees
|
|
152
58
|
rotom group list --pretty
|
|
153
59
|
rotom group send <groupId> <agent> "@<agent> hi"
|
|
154
|
-
rotom issue create <groupId> --title "
|
|
60
|
+
rotom issue create <groupId> --title "fix a bug" --description "..." --priority high
|
|
155
61
|
```
|
|
156
62
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
## 配置
|
|
160
|
-
|
|
161
|
-
### Master 启动参数 / 环境变量
|
|
63
|
+
## Common config
|
|
162
64
|
|
|
163
|
-
|
|
164
|
-
|------|------|------|
|
|
165
|
-
| `MESH_MASTER_PORT` | `28800` | Master 监听端口 |
|
|
166
|
-
| `MESH_MASTER_HOST` | `0.0.0.0` | Master 监听地址 |
|
|
167
|
-
| `ROTOM_HOME` | `~/.rotom` | 数据目录(SQLite + 日志 + PID) |
|
|
168
|
-
| `ROTOM_HOSTNAME` | `os.hostname()` | 本机 hostname(联邦用,**禁止填 IP**) |
|
|
169
|
-
| `ROTOM_MASTER_ROLE` | `standalone` | `standalone` / `coordination` / `member` |
|
|
170
|
-
| `ROTOM_TEAM_NAME` | 从真人 agent 派生 | 团队展示名(如"西花团队") |
|
|
171
|
-
| `ROTOM_COORD_ENDPOINTS` | — | member 模式:逗号分隔协调 master ws 地址 |
|
|
172
|
-
| `ROTOM_FEDERATION_DISABLED` | — | `=1` 强制关闭联邦 |
|
|
65
|
+
### Give an employee a Chinese name / set a working dir
|
|
173
66
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
### Executor 配置(`~/.rotom/executor.config.json`,可选)
|
|
177
|
-
|
|
178
|
-
OPC 模式下 master 自动生成 `.auto-executor.json`(scanClis 模式),无需手写。若要给 agent 起中文名或指定 workingDir,写 `executor.config.json`(优先级高于 auto):
|
|
67
|
+
In OPC mode the master auto-generates `.auto-executor.json` by scanning local CLIs — no need to write it by hand. To set a Chinese name or pin a `workingDir`, write `~/.rotom/executor.config.json` (takes priority over auto):
|
|
179
68
|
|
|
180
69
|
```json
|
|
181
70
|
{
|
|
@@ -192,225 +81,36 @@ OPC 模式下 master 自动生成 `.auto-executor.json`(scanClis 模式),无需
|
|
|
192
81
|
}
|
|
193
82
|
```
|
|
194
83
|
|
|
195
|
-
|
|
196
|
-
|------|------|------|
|
|
197
|
-
| `master` | `string` | Master WebSocket URL |
|
|
198
|
-
| `workers[]` | `array` | worker 列表(也支持单 worker 简化形式) |
|
|
199
|
-
| `workers[].name` | `string` | agent 名(OPC 模式下本机信任,无需与 DB 预注册) |
|
|
200
|
-
| `workers[].token` | `string?` | **OPC 模式可空**(本机信任);跨机连接远程 master 时必填 |
|
|
201
|
-
| `workers[].cliTool` | `string?` | `claude` / `codex` / `openclaw` / `hermes` / `pi`,缺省自动检测 |
|
|
202
|
-
| `workers[].workingDir` | `string?` | 任务执行目录,默认 `~/.rotom/workspace` |
|
|
203
|
-
| `workers[].maxConcurrent` | `number?` | 并发上限,默认 2 |
|
|
204
|
-
| `workers[].profile` | `object?` | 员工档案,`category: "真人"` 时不参与抢单 |
|
|
84
|
+
Employees with `category: "真人"` do not participate in claiming — they only act as a human presence.
|
|
205
85
|
|
|
206
|
-
###
|
|
207
|
-
|
|
208
|
-
```json
|
|
209
|
-
{
|
|
210
|
-
"id": "<协调 master 的 masterId,8 字符 base36>",
|
|
211
|
-
"name": "阿甘团队",
|
|
212
|
-
"coord_endpoints": ["ws://coord-host:28800"]
|
|
213
|
-
}
|
|
214
|
-
```
|
|
86
|
+
### Switch the CLI's default identity
|
|
215
87
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
### rotom CLI 身份解析
|
|
219
|
-
|
|
220
|
-
优先级:`ROTOM_AGENT` env > `--as <name>` > `~/.rotom/config.json#defaultAgent`。
|
|
88
|
+
Priority: `ROTOM_AGENT` env > `--as <name>` > `~/.rotom/config.json#defaultAgent`.
|
|
221
89
|
|
|
222
90
|
```bash
|
|
223
91
|
rotom config show
|
|
224
|
-
rotom config use 江德福
|
|
225
|
-
rotom --as 阿甘 directory
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
## REST API
|
|
229
|
-
|
|
230
|
-
所有端点挂在 `/api` 下。本机调用走 loopback 信任(免 token);远程用 `Authorization: Bearer <mesh_token>`(向后兼容)。
|
|
231
|
-
|
|
232
|
-
### Identity / Teams(federation)
|
|
233
|
-
|
|
234
|
-
| 方法 | 路径 | 说明 |
|
|
235
|
-
|------|------|------|
|
|
236
|
-
| GET | `/api/identity` | 本机 master 身份(masterId / hostname / role / teamName) |
|
|
237
|
-
| GET | `/api/teams` | 已加入的团队列表 |
|
|
238
|
-
| GET | `/api/teams/:id/members` | 团队内可见 agent(agent_visibility) |
|
|
239
|
-
| GET | `/api/teams/:id/peers` | 团队内 peer master 列表 |
|
|
240
|
-
| POST | `/api/teams/join` | runtime 加入上级团队(body: `{ coordEndpoint, teamName? }`) |
|
|
241
|
-
| POST | `/api/teams/leave` | runtime 离开团队,切回 standalone |
|
|
242
|
-
| POST | `/api/agents/:id/refresh-token` | 刷新 token |
|
|
243
|
-
| GET / POST | `/api/domains` | 域列表 / 新建 |
|
|
244
|
-
| PUT / DELETE | `/api/domains/:id` | 域更新（级联改名）/ 删除 |
|
|
245
|
-
| GET / POST / DELETE | `/api/cross-domain` | 跨域规则 |
|
|
246
|
-
| GET | `/api/real-persons` | 真人列表（`category=真人` 的 agent）|
|
|
247
|
-
|
|
248
|
-
### Groups / Messages
|
|
249
|
-
|
|
250
|
-
| 方法 | 路径 | 说明 |
|
|
251
|
-
|------|------|------|
|
|
252
|
-
| GET / POST | `/api/groups` | 群列表 / 建群 |
|
|
253
|
-
| GET / PATCH / DELETE | `/api/groups/:id` | 群详情 / 改设置 / 解散 |
|
|
254
|
-
| POST / DELETE | `/api/groups/:id/members` | 拉人 / 踢人 |
|
|
255
|
-
| GET / POST | `/api/groups/:id/messages` | 群消息历史 / 发消息 |
|
|
256
|
-
| POST | `/api/cli/groups/:groupId/send` | CLI 专用发消息（保留 mention 语义）|
|
|
257
|
-
|
|
258
|
-
### Issues / 协作
|
|
259
|
-
|
|
260
|
-
| 方法 | 路径 | 说明 |
|
|
261
|
-
|------|------|------|
|
|
262
|
-
| GET / POST | `/api/groups/:groupId/issues` | 群内 Issue 列表 / 创建任务型 Issue |
|
|
263
|
-
| GET / PUT / DELETE | `/api/issues/:id` | Issue CRUD |
|
|
264
|
-
| POST | `/api/issues/:id/cancel` | 取消 |
|
|
265
|
-
| POST | `/api/issues/:id/continue` | 继续会话（追加输入）|
|
|
266
|
-
| POST | `/api/issues/:id/append` | 实时追加输出片段 |
|
|
267
|
-
| POST | `/api/issues/:id/complete` | 标记完成 |
|
|
268
|
-
| POST | `/api/issues/claim-next` | Worker 抢下一个 Issue |
|
|
269
|
-
| POST | `/api/issues/:id/approvals/:approvalId` | 审批回执（slash command 策略）|
|
|
270
|
-
| GET | `/api/issues/:id/events` | Issue 时间线事件 |
|
|
271
|
-
| GET | `/api/issues/:id/messages` | Issue 关联群消息 |
|
|
272
|
-
|
|
273
|
-
### Artifacts / 观测
|
|
274
|
-
|
|
275
|
-
| 方法 | 路径 | 说明 |
|
|
276
|
-
|------|------|------|
|
|
277
|
-
| GET | `/api/artifacts/:groupId` | 群产物列表 |
|
|
278
|
-
| GET | `/api/artifacts/:groupId/content` | 产物内容 |
|
|
279
|
-
| GET | `/api/artifacts/:groupId/original` | 产物原始版本 |
|
|
280
|
-
| GET | `/api/artifacts/:groupId/diff` | 产物 diff |
|
|
281
|
-
| GET | `/health` | 健康检查 |
|
|
282
|
-
| GET | `/api/audit` | 审计日志（max 500）|
|
|
283
|
-
| GET | `/api/stats` | 全局统计 + 每 agent 消息指标 |
|
|
284
|
-
| GET | `/api/messages` | 全局消息日志（agent / limit / before）|
|
|
285
|
-
| GET | `/api/conversations` | 按 peer 聚合的会话 |
|
|
286
|
-
| GET | `/api/whoami` | 当前 token 对应的 agent 身份 |
|
|
287
|
-
|
|
288
|
-
## 协议
|
|
289
|
-
|
|
290
|
-
WebSocket 入口：`ws://master:28800/ws`
|
|
291
|
-
|
|
292
|
-
### Client → Master
|
|
293
|
-
|
|
294
|
-
| 类型 | 关键字段 | 说明 |
|
|
295
|
-
|------|---------|------|
|
|
296
|
-
| `auth` | `token`, `name`, `jwt?` | 鉴权（10s 内必须完成）|
|
|
297
|
-
| `heartbeat` | `activeDispatches?` | 心跳（每 10s）|
|
|
298
|
-
| `a2a_send` | `requestId`, `target`, `payload` | 发消息给目标 agent |
|
|
299
|
-
| `a2a_reply` | `requestId`, `payload` | 回复收到的消息 |
|
|
300
|
-
| `update_info` | `description?` | 更新自己的元数据 |
|
|
301
|
-
| `disconnect` | — | 优雅断开 |
|
|
302
|
-
|
|
303
|
-
### Master → Client
|
|
304
|
-
|
|
305
|
-
| 类型 | 关键字段 | 说明 |
|
|
306
|
-
|------|---------|------|
|
|
307
|
-
| `auth_ok` | `jwt`, `directory[]`, `config?` | 鉴权通过 + 全量目录 |
|
|
308
|
-
| `auth_fail` | `reason` | 鉴权失败 |
|
|
309
|
-
| `heartbeat_ack` | — | 心跳响应 |
|
|
310
|
-
| `a2a_message` | `requestId`, `from`, `payload` | 收到消息 |
|
|
311
|
-
| `route_result` | `requestId`, `delivered`, `queued` | 路由反馈 |
|
|
312
|
-
| `directory_update` | `event`, `agent` | 目录变更（上线/下线/更新）|
|
|
313
|
-
| `offline_messages` | `messages[]` | 重连时下发的离线消息 |
|
|
314
|
-
| `config_update` | `domain?`, `enabled?` | Master 推送的配置变更 |
|
|
315
|
-
|
|
316
|
-
### Payload 结构
|
|
317
|
-
|
|
318
|
-
```typescript
|
|
319
|
-
interface MessagePayload {
|
|
320
|
-
message: string;
|
|
321
|
-
files?: Array<{ name: string; uri: string; mimeType?: string }>;
|
|
322
|
-
}
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
### WS Close Codes
|
|
326
|
-
|
|
327
|
-
| 码 | 含义 |
|
|
328
|
-
|----|------|
|
|
329
|
-
| 4001 | Auth timeout |
|
|
330
|
-
| 4002 | Auth failed |
|
|
331
|
-
| 4400 | Invalid JSON |
|
|
332
|
-
| 4401 | Not authenticated |
|
|
333
|
-
| 4429 | Rate limited |
|
|
334
|
-
|
|
335
|
-
## 开发(源码方式)
|
|
336
|
-
|
|
337
|
-
普通用户走 `npm i -g @konglx/rotom` 全局装包即可,无需读这一节。本节面向需要改 rotom 源码 / 跑测试 / 提 PR 的开发者。
|
|
338
|
-
|
|
339
|
-
### 构建
|
|
340
|
-
|
|
341
|
-
```bash
|
|
342
|
-
git clone <repo> rotom && cd rotom
|
|
343
|
-
pnpm install
|
|
344
|
-
pnpm build # tsc（含 executor / cli / shared / master）
|
|
345
|
-
pnpm build:master # 同上 + 打包 dashboard SPA
|
|
346
|
-
pnpm dashboard:dev # React dashboard 本地开发模式
|
|
92
|
+
rotom config use 江德福
|
|
93
|
+
rotom --as 阿甘 directory
|
|
347
94
|
```
|
|
348
95
|
|
|
349
|
-
|
|
96
|
+
## Docs
|
|
350
97
|
|
|
351
|
-
|
|
352
|
-
pnpm test # 所有 tests/*.test.ts
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
### 项目结构
|
|
356
|
-
|
|
357
|
-
```
|
|
358
|
-
src/
|
|
359
|
-
├── cli/
|
|
360
|
-
│ └── rotom.ts # rotom CLI 入口（身份解析 + 子命令调度）
|
|
361
|
-
├── executor/
|
|
362
|
-
│ ├── index.ts # Executor 主进程入口
|
|
363
|
-
│ ├── worker.ts # Worker 抽象（WS + 抢单 + 进度回传）
|
|
364
|
-
│ ├── cli-executor.ts # CLI 后端的通用执行框架
|
|
365
|
-
│ ├── claude-code-hook.cjs # Claude Code 钩子（追踪输出）
|
|
366
|
-
│ └── executors/ # 后端适配
|
|
367
|
-
│ ├── claude-code.ts
|
|
368
|
-
│ ├── codex.ts
|
|
369
|
-
│ ├── hermes-cli.ts
|
|
370
|
-
│ ├── openclaw.ts
|
|
371
|
-
│ └── pi.ts
|
|
372
|
-
├── master/
|
|
373
|
-
│ ├── server.ts # Master 独立入口（CLI）— OPC bootstrap + federation 启动
|
|
374
|
-
│ ├── embedded.ts # 可嵌入版本（同进程使用）
|
|
375
|
-
│ ├── opc-bootstrap.ts # OPC bootstrap:身份 + 默认 agent/group + spawn executor
|
|
376
|
-
│ ├── federation/ # 联邦子系统（identity / manager / server / client / publisher）
|
|
377
|
-
│ ├── api/ # REST 端点（agents / teams / groups / issues / memory / ...）
|
|
378
|
-
│ ├── ws-hub/ # WS Hub（连接 + 中转 + 路由 + directory）
|
|
379
|
-
│ ├── router.ts # 路由决策（含 routeFederated 跨机分支）
|
|
380
|
-
│ ├── db/ # SQLite 数据层（WAL,master-node / team / agent-visibility / ...）
|
|
381
|
-
│ ├── auth.ts # token + JWT + authenticateLocal（本机信任）
|
|
382
|
-
│ └── offline-queue.ts # 离线消息队列
|
|
383
|
-
└── shared/
|
|
384
|
-
├── protocol/ # 消息类型（client/server/federation + guards）
|
|
385
|
-
├── network.ts # isLoopback（本机信任判定）
|
|
386
|
-
├── constants.ts # 全局常量
|
|
387
|
-
├── dedup.ts # 消息去重
|
|
388
|
-
├── group-context.ts # 群上下文工具
|
|
389
|
-
├── logger.ts # 统一日志
|
|
390
|
-
└── slash-commands.ts # 斜杠命令协议
|
|
391
|
-
|
|
392
|
-
packages/
|
|
393
|
-
└── dashboard/ # React 18 + Vite Dashboard SPA
|
|
394
|
-
|
|
395
|
-
migrations/ # SQLite schema migrations(001~058)
|
|
396
|
-
packages/website/docs/ # 协作指南 / 用户手册 / 架构文档
|
|
397
|
-
bin/
|
|
398
|
-
├── mesh-master.sh # Master 启停脚本
|
|
399
|
-
├── rotom # rotom CLI launcher
|
|
400
|
-
└── rotom-send-with-status # rotom 带状态发消息辅助脚本
|
|
401
|
-
```
|
|
98
|
+
### User
|
|
402
99
|
|
|
403
|
-
|
|
100
|
+
- [Install guide](./packages/website/docs/user/get_started.md) — full install for the three components
|
|
101
|
+
- [User guide](./packages/website/docs/user/user_guide.md) — group chat / Issues / artifacts / collaboration
|
|
102
|
+
- [Troubleshooting](./packages/website/docs/user/troubleshooting.md) — common errors and fixes
|
|
103
|
+
- [Features](./packages/website/docs/infos/rotom-features-v2.md) — full capability overview
|
|
104
|
+
- [Federation](./packages/website/docs/federation/federation.md) — cross-machine team config
|
|
404
105
|
|
|
405
|
-
|
|
406
|
-
- [`docs/AGENT_USER_GUIDE.md`](./packages/website/docs/agent_user_guide.md) — Agent 协作用户指南
|
|
407
|
-
- [`docs/GROUP_CHAT_ARCHITECTURE.md`](./packages/website/docs/group_chat_architecture.md) — 群聊架构详解
|
|
408
|
-
- [`docs/QUICK_REF.md`](./packages/website/docs/quick_ref.md) — Issue / 协作 / 群消息 三种场景速查
|
|
106
|
+
### Developer
|
|
409
107
|
|
|
410
|
-
|
|
108
|
+
Only needed if you want to modify rotom source / run tests / submit PRs:
|
|
411
109
|
|
|
412
|
-
- [
|
|
413
|
-
- [
|
|
110
|
+
- [Source install](./packages/website/docs/dev/install_source.md) — clone + pnpm build + dashboard dev
|
|
111
|
+
- [Group chat architecture](./packages/website/docs/dev/group_chat_architecture.md) — group message routing and rendering
|
|
112
|
+
- [Agent white-box mechanism](./packages/website/docs/dev/agent_whitebox.md) — how CLI tools are wrapped into employees
|
|
113
|
+
- [Dev delivery workflow](./packages/website/docs/dev/dev_delivery_workflow.md) — pre-PR self-test checklist
|
|
414
114
|
|
|
415
115
|
## License
|
|
416
116
|
|