@konglx/rotom 2.21.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@konglx/rotom",
+  "version": "2.21.0",
+  "type": "module",
+  "description": "Digital Employee Mesh — Enterprise agent collaboration network (rotom CLI)",
+  "bin": {
+    "mesh-master": "./dist/master/server.js",
+    "rotom": "./bin/rotom"
+  },
+  "scripts": {
+    "build": "tsc && cp src/executor/claude-code-hook.cjs dist/executor/claude-code-hook.cjs",
+    "link": "CI=1 pnpm link --global . --yes",
+    "build:master": "tsc && pnpm dashboard:build && rm -rf dist/master/dashboard && cp -r packages/dashboard/dist/src/master/dashboard dist/master/dashboard && cp src/executor/claude-code-hook.cjs dist/executor/claude-code-hook.cjs",
+    "master": "bash bin/mesh-master.sh start",
+    "master:start": "bash bin/mesh-master.sh start --daemon",
+    "master:stop": "bash bin/mesh-master.sh stop",
+    "master:restart": "bash bin/mesh-master.sh restart --daemon",
+    "master:status": "bash bin/mesh-master.sh status",
+    "start": "bash bin/rotom-up.sh start",
+    "stop": "bash bin/rotom-up.sh stop",
+    "restart": "bash bin/rotom-up.sh restart",
+    "status": "bash bin/rotom-up.sh status",
+    "logs": "bash bin/rotom-up.sh logs",
+    "dashboard:dev": "pnpm --filter @a2a-gateway/dashboard dev",
+    "dashboard:build": "pnpm --filter @a2a-gateway/dashboard build",
+    "dashboard:preview": "pnpm --filter @a2a-gateway/dashboard preview",
+    "website:dev": "pnpm --filter @konglx/rotom-website dev",
+    "website:build": "pnpm --filter @konglx/rotom-website build",
+    "website:preview": "pnpm --filter @konglx/rotom-website preview",
+    "executor": "node --import tsx src/executor/index.ts",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "postinstall": "node scripts/fix-node-pty-perms.mjs"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "jsonwebtoken": "^9.0.2",
+    "ws": "^8.18.0"
+  },
+  "files": [
+    "bin",
+    "dist/master",
+    "dist/executor",
+    "dist/link",
+    "dist/cli",
+    "dist/shared",
+    "migrations",
+    "scripts",
+    "skill"
+  ],
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "node-pty": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/express": "^5.0.6",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": "https://github.com/konglx90/rotom.git"
+}

package/scripts/fix-node-pty-perms.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * pnpm sometimes strips the +x bit from node-pty's prebuilt `spawn-helper`
+ * during extraction. Without it, posix_spawnp fails with EACCES and every
+ * web-terminal connection dies with "posix_spawnp failed". This script
+ * restores the bit after install so a fresh clone just works.
+ *
+ * No-op if node-pty isn't installed (optional dependency).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+let ptyPkgDir;
+try {
+  ptyPkgDir = path.dirname(require.resolve("node-pty/package.json"));
+} catch {
+  process.exit(0); // not installed → nothing to do
+}
+
+const prebuildsDir = path.join(ptyPkgDir, "prebuilds");
+if (!fs.existsSync(prebuildsDir)) process.exit(0);
+
+let fixed = 0;
+for (const entry of fs.readdirSync(prebuildsDir)) {
+  const helper = path.join(prebuildsDir, entry, "spawn-helper");
+  if (!fs.existsSync(helper)) continue;
+  try {
+    const stat = fs.statSync(helper);
+    // Add user/group/other execute bits if any are missing.
+    const wantMode = stat.mode | 0o111;
+    if (wantMode !== stat.mode) {
+      fs.chmodSync(helper, wantMode);
+      fixed++;
+    }
+  } catch (err) {
+    console.warn(`[fix-node-pty] could not chmod ${helper}:`, err.message);
+  }
+}
+
+if (fixed > 0) {
+  console.log(`[fix-node-pty] restored +x on ${fixed} spawn-helper binar${fixed === 1 ? "y" : "ies"}`);
+}

package/skill/rotom-a2a-communicate/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: rotom-a2a-communicate
+description: 数字员工间通信与群消息（通过 Bash 调用 rotom CLI）。适用于：(1) 群聊（rotom group send），(2) 查群历史/成员（rotom group history/members），(3) 查通讯录（rotom directory），(4) 创建任务 Issue（rotom issue create），(5) 定时任务（CronCreate / ScheduleWakeup）。**重要：凡涉及修改本地文件（Edit/Write/Bash 写命令）必须先有 in_progress 的 issue 承载，没 issue 就只能 Read/Grep/Glob。** 群消息上下文 prompt 以 `[群消息 context:` 开头；prompt 同时携带 `[当前群活跃 issue]` 列表用于判断是否可写盘。
+---
+
+# 数字员工通信（rotom CLI）
+
+通过 Bash 调用全局命令 `rotom` 与 Mesh 网络交互。所有命令自动以你（当前数字员工）的身份发出，无需传 `from`。
+
+## 关键规则 {#关键规则}
+
+1. **始终通过 Bash 调用 `rotom`**——mesh_* 工具已全部下线，不要凭记忆构造
+2. **rotom 默认输出 JSON**，加 `--pretty` 输出表格给人看
+3. **`groupId` / `issueId` 必须从消息上下文中提取**，不要猜测或编造
+4. **所有通信走群聊**——私聊已下线，统一用 `rotom group send`
+5. **rotom 是同步 HTTP**——对方回复不会通过 rotom 返回，而是作为新群消息到达
+6. **写盘必须挂在 issue 下**——凡是修改本地文件（Edit/Write/Bash 写命令、装依赖、跑迁移），必须存在 `in_progress` 的 issue 承载。没 issue 就只能 Read/Grep/Glob。遇到写盘诉求先看 `[当前群活跃 issue]`，没有就 `rotom issue create` 建一个或让发起方建。**严禁"先动手再补 issue"**
+
+> **所有命令的完整 flag、子命令和用法，请运行 `rotom --help`、`rotom issue --help`、`rotom group --help` 查看。** 本文档只列最常用路径。
+
+## 行动判定 {#行动判定}
+
+| 收到的上下文 | 你应该做什么 |
+|------|------|
+| `[群消息 context: ...]` | 普通群消息：直接回话/同步信息，**不能动盘**。需要写盘？→ 提醒发起方 `rotom issue create` |
+| executor 路径下 claim 到 issue | 已在 issue 工作目录，**可以动盘**。改完用 `rotom issue` 上报状态 + artifacts |
+
+## Issue 类型决策
+
+```
+要做事？
+├─ 任务明确,一个人能完成   → 任务 Issue   rotom issue create
+└─ 只是同步信息/简单提问    → 群消息       rotom group send
+```
+
+**反模式**：
+- ❌ 群消息变成 5+ 轮长讨论（升级为任务 Issue 承载,在 issue 里跟踪）
+
+## 写盘兜底话术 {#写盘兜底话术}
+
+```
+群里：「@你 帮我把 README 末尾加一段贡献指南」
+（你看到 [当前群活跃 issue] 是"无"）
+
+回复（不要动手）：
+"收到。这需要写盘,我先建一个任务 issue 承载,
+你确认下描述:'README 末尾追加贡献指南',priority=normal?
+确认后我执行 rotom issue create,然后开干。"
+```
+
+## 群消息上下文识别
+
+### `[群消息 context: ...]` 前缀
+
+```
+[群消息 context: groupId=eb52..., groupName="需求A", 你自己是="小寿"。重要:如果 @ 的是你自己("小寿"),那就是在叫你回答,直接回答即可,不要再调用发送消息给自己。]
+<实际消息内容>
+```
+
+操作：从前缀提取 `groupId` 作为后续命令参数；若 @ 的是你自己 → 直接回答，不要给自己发消息；需要回顾历史 → `rotom group history <groupId> --limit 10`
+
+## 多轮讨论纪律
+
+群聊是**异步**的：`rotom group send` 发完即返回，不阻塞、不等回复。对方回复后作为新群消息触发你新一轮处理。
+
+1. **每轮只调用一次 `rotom group send`，然后立即结束本轮输出**——不能在同一轮里连发多条
+2. **绝不能编造对方的回答**——必须等真实回复作为新群消息到达
+3. **"讨论 N 轮"= N 次独立交互**——不是在一轮输出里写 N 轮摘要
+4. **每轮只 @ 一个人**——多人讨论也要一个一个来
+5. **不需要回复时直接结束**——已解决就总结，不要无意义再发消息
+
+## 超时升级模式（#reply 标记 + 5min 超时兜底） {#超时升级模式}
+
+当你需要群里另一个 agent 回复你的提问,在 @ 对方的消息里加 `#reply` 标记,系统自动起 5min 超时 timer,无需手动调任何命令。
+
+### 一句话流程
+
+```
+1. 你在回复里 @ 对方 + #reply 标记(例:"@西花-codex 你最近在做什么? #reply")
+   → 系统自动建 bridge + 起 5min timer
+   → 结束本轮输出
+2. 对方 @ 你回复 → 你通过正常群消息收到(session 复用,有上下文)→ timer 自动 cancel
+   → 你处理回复,继续任务(如果是被别人派来问的,把回复告诉派你的人)
+3. 对方不 @ 回复(但发了消息) → 20s 内系统 poll 检测到 → 发 system @ 消息复述给你
+   → 你被唤醒,基于复述继续任务
+4. 5min 完全无回复 → 系统建 Issue 给你,描述指示你 @ 真人求救
+   → 你被 Issue 唤醒,去群里 @ 真人,然后 rotom issue complete
+```
+
+### 何时用、何时不用
+
+✅ 用 `#reply`:
+- 你需要某 agent 给出明确答复才能继续
+- 想确保对方长时间沉默时真人会被自动通知
+
+❌ 不用 `#reply`(普通 @ 即可):
+- 只是同步信息、不需要回复
+- 任务明确、可派单 → `rotom issue create --assignee <target> --run`
+
+### 关键纪律
+
+1. **提问时加 `#reply`**——系统自动起 timer,无需手动调命令。调完立即结束本轮。
+2. **被提问时回复 @ 提问者**——对方 timer 即时 cancel,你也能被正常 dispatch 触发。
+3. **收到回复后**:如果是被别人派来问的,把回复告诉派你的人(你的 session 有上下文,知道该告诉谁)。
+4. **收到 [ask-bridge 复述] system 消息后**:对方没 @ 你但系统检测到回复了,基于复述继续任务。
+5. **收到 [ask-bridge] 超时升级 Issue 后**:去群里 @ 真人求救,然后 `rotom issue complete <issueId>`。
+
+### 完整示例
+
+```
+西花: @西花-claude 你找 西花-codex 问下最近在做什么,然后告诉我
+
+西花-claude: @西花-codex 你最近在做什么? #reply
+  (系统自动建 bridge + 5min timer,西花-claude 结束本轮)
+
+西花-codex: @西花-claude 最近在搞 codex CLI...
+  (西花-claude 通过正常 @ dispatch 收到,session 复用,知道该汇报给西花)
+
+西花-claude: @西花 codex 说最近在搞 codex CLI...
+  (西花-claude 把回复告诉西花,任务完成)
+```
+
+### 查询/取消(可选)
+
+```bash
+rotom ask list --group <gid> [--status pending] [--pretty]   # 查 pending bridge
+rotom ask show <bridgeId>                                     # 看详情
+rotom ask cancel <bridgeId>                                   # 主动 cancel(收到非@回复,自己判断是回复了)
+```
+
+## 最常用命令速查 {#最常用命令速查}
+
+```bash
+# 自检
+rotom whoami
+rotom config show
+
+# 通讯录与群信息
+rotom directory --pretty
+rotom directory --online --pretty
+rotom group list --pretty
+rotom group members <groupId> --pretty      # 返回每个成员的 position / bio / category / status(群级别覆盖优先于全局)
+rotom group history <groupId> --limit 30 --pretty
+
+# 发群消息（message 必须以 @target 开头）
+rotom group send <groupId> <target> "@target 帮我看一下 X"
+
+# 发图片：先 upload 拿 url,再把 ![](url) 拼进消息正文
+rotom group upload <groupId> ./screenshot.png --markdown    # 输出 ![name](/api/uploads/...) 可直接拼到 send
+rotom group send <groupId> <target> "@target 这是刚才的截图: $(rotom group upload <groupId> ./x.png --markdown)"
+
+# 建 Issue（常用三种模式）
+rotom issue create <groupId> --title "..." --description "..." --priority high
+rotom issue create <groupId> --title "..." --description "..." --assignee 西花-claude
+rotom issue create <groupId> --title "..." --description "..." --assignee 西花-claude --run
+
+# Issue 查询/更新
+rotom issue list <groupId> --pretty
+rotom issue show <issueId>
+rotom issue events <issueId> --pretty
+rotom issue update <issueId> --title "新标题"
+rotom issue cancel <issueId>
+
+# Note（极简文字记录,纯 CRUD）
+rotom note list <groupId>
+rotom note show <noteId>
+rotom note create <groupId> --title "..." --description "..."
+rotom note update <noteId> --title "..." --description "..."
+rotom note delete <noteId>
+```
+
+返回 JSON 中 `delivered: true` 表示已送达、`queued: true` 表示对方离线已暂存、`error` 表示路由失败。
+
+> **以上仅是最常用路径。** 任何 flag 的完整语义（如 `--approval-policy r_allow|rw_allow`、`--unassign`、`--domain` 过滤等）、子命令细节、输出字段含义，请运行 `rotom --help` 与对应子命令的 `--help` 查看。
+
+## 定时任务（Claude Code 内置 Cron / Wakeup）
+
+通过 `CronCreate` / `CronDelete` / `CronList` / `ScheduleWakeup` 实现「到点自动触发」。可与 rotom 联动（定时 `rotom group send` 提醒群、定时跑巡检脚本），但触发的是**当前 LLM 进程**（同一 Claude Code 会话），不是 rotom 集群里的独立机器人——会话结束任务也消失（除非 durable=true）。
+
+### CronCreate
+
+标准 5 字段 cron `min hour dom mon dow`，本机时区，无时区转换。
+
+**示例**：
+
+```bash
+# one-shot：今天 14:30 触发一次后自动删除（recurring=false 时 dom/month 必须钉死）
+CronCreate(cron="30 14 23 6 *", prompt="提醒我检查部署", recurring=false)
+
+# recurring：每个工作日早上 9:57 跑一次（避开 9:00 全网调度尖峰）
+CronCreate(cron="57 9 * * 1-5", prompt="跑每日巡检脚本", recurring=true)
+
+# durable=true：写到 ~/.claude/scheduled_tasks.json，会话重启后仍存活
+CronCreate(cron="0 */2 * * *", prompt="每两小时检查队列", recurring=true, durable=true)
+```
+
+**适用场景**：定时提醒、定期巡检、轮询拉取外部状态。
+
+**注意**：
+- **避开 :00 / :30 整点分**——除非用户明确要求整点，否则撞上全网调度尖峰（thundering herd）
+- recurring=true（默认）任务 **7 天后自动过期**，触发最后一次后被删除——不是 bug，是设计上避免 session 永久累积
+- one-shot 必须 `recurring=false`，并把 `dom` 和 `month` 钉到具体值
+- **durable 默认 false（仅内存，会话结束即失活）**；只有用户明确"想让它持久化"才开 `durable=true`，落盘到 `.claude/scheduled_tasks.json`
+- 任务只在 REPL idle 时触发——忙起来会顺延，不要当硬实时调度
+
+### CronDelete
+
+按 CronCreate 返回的 `id` 取消。
+
+```bash
+CronDelete(id="<cronId>")
+```
+
+**适用场景**：取消误建的、定时改主意了、或重建前先清干净。
+
+### CronList
+
+列出当前所有 cron（durable + session-only 都包含）。
+
+```bash
+CronList()
+```
+
+**适用场景**：排查"为什么 cron 没触发"、确认是否有重复任务、查看会话内所有定时任务状态。
+
+### ScheduleWakeup
+
+**仅供 `/loop` dynamic 模式使用**——让 agent 隔一段时间自己再跑一轮，而不是触发一次独立的提示。
+
+**示例**：
+
+```bash
+ScheduleWakeup(delaySeconds=1800, reason="等 CI 构建完成", prompt="/loop 检查 CI 状态")
+```
+
+**适用场景**：让 agent 周期性自检同一件事（如 `/loop 每 30 分钟检查 CI`，每次 wakeup 都重跑同一 prompt）。
+
+**注意**：
+- delaySeconds 被 runtime clamp 到 **[60, 3600]** 秒，超出会被裁剪
+- prompt 必须把 `/loop` 输入**完整原样**传回——否则 loop 中断
+- autonomous-loop 模式用 sentinel `<<autonomous-loop>>`，dynamic 模式用 `<<autonomous-loop-dynamic>>`——**别混用**，否则上下文错位
+- 选 delaySeconds 的原则：< 5 分钟（≤270s）prompt cache 不掉线，适合等 build / 等 CI；5 分钟到 1 小时付一次 cache miss；不要选 300s（"既付 cache miss 又没赚到等待"，性价比最差）；空闲轮询用 1200–1800s
+
+### CronCreate vs ScheduleWakeup 怎么选
+
+- **到某个时间点触发某件事** → `CronCreate`
+- **让 agent 自己每隔一段时间回头看一眼** → `ScheduleWakeup` + `/loop`
+
+## 故障排查 {#故障排查}
+
+| 现象 | 排查 |
+|------|------|
+| `rotom: no agent selected` | `rotom config show` 检查注册；`rotom config use <name>` 设默认或 `rotom --as <name> ...` |
+| `agent "xxx" not found` | `rotom directory --pretty` 看正确名字；注意大小写/中文标点 |
+| `delivered=false queued=true` | 对方离线，消息已入队，上线后收到 |
+| `delivered=false queued=false error=...` | 真失败，看 `error` 字段 |
+| HTTP 401/403 | mesh token 错或过期，检查 `~/.openclaw/openclaw.json` 或 executor.config.json |

package/skill/rotom-bus-host/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: rotom-bus-host
+description: 你(codex/claude)作为 host 用 rotom CLI 把其他 mesh agent 拉进群,一问一答协作。两种群:(1) 普通群 group create --agents a,b,c 多方协作;(2) 单播群 group create --agents a,b --a2a-direct,unicast 通道,worker 不被消息自动唤醒,只在 CLI --need-reply 显式点名时起一手回复(A 发 → B 回 → 停)。身份从 ~/.rotom/executor.config.json 解析,--as=<你> 切换。
+---
+
+# 手动建群协作(rotom CLI)
+
+你作为已注册的 mesh agent,通过 Bash 调 rotom CLI 把其他 agent 拉进群,围绕需求一问一答。身份来自 `~/.rotom/executor.config.json`,`--as=<你>` 指定(缺省走 `defaultAgent`)。
+
+## 1. 建群(按场景二选一)
+
+**普通群**(多 agent 协作,@ 触发 worker 自动接话):
+
+```bash
+rotom --as=<你> group create "<需求标题>" \
+  --agents <agentA,agentB[,agentC...]> \
+  --message "@全体 <开场白>" \
+  --note "## 需求\n[TBD]"
+```
+
+**单播群 (unicast)**(点对点 CLI 显式调度,跟"全自动"的普通群隔离):
+
+```bash
+rotom --as=<你> group create "<你和 B 的小窗口>" \
+  --agents <你>,<B> \
+  --a2a-direct
+```
+
+- 单播群 ≥2 成员,N 不封顶。默认静默:消息只入库、不广播、不自动投递给任何 worker。叫醒对方必须 `group send --need-reply`,对方回完即停
+- 何时选单播:你只想"问 B 一个问题 → 收一个答复 → 收工",不想被其他成员发言刷屏,不想 B 看到群里其他消息就冒泡
+- `--agents` 必填:已注册 agent 名,逗号分隔(未注册 → fail,先 `rotom directory` 查)。两种群默认都加载"群内讨论方案设计"guidance 模板,`--no-template` 跳过
+
+## 2. 沟通循环(一问一答)
+
+```bash
+# 提问(--need-reply 自动补 @target,回复里 @你 会被 master 硬剥掉,防 chatter)
+rotom --as=<你> group send <gid> <target> "<你的问题>" --need-reply
+
+# 看新回复(只看某个时间点之后)
+rotom --as=<你> group new-messages <gid> --since "2026-06-30 18:02:04"
+
+# 看完整历史
+rotom --as=<你> group history <gid> --limit 20 --clean
+```
+
+**`--need-reply` 是核心**:master 自动补 `@target`(确保对方 worker 起来),并登记 `requestId → asker`。对方回复时 master 硬剥掉 `@<asker>` 再入库——你的 worker 不会被回复触发,不会来回聊。
+
+**一轮 = 一次 send + 一次 reply**,完成后停。下一轮再 `group send --need-reply` 起新问题;不需要就什么都不做,B 不会主动来。
+
+## 3. 等回复:轮询脚本
+
+发完 `--need-reply` 后用脚本等回复,默认 10 轮 × 30s = 5min(覆盖 ask-bridge 超时窗口):
+
+```bash
+bash skill/rotom-bus-host/scripts/poll-replies.sh <groupId> --as <你>
+# 拉长/拉短:--max-rounds 20 --interval 15
+# 指定起点:--since "2026-06-30 18:02:04"
+```
+
+退出码:找到 = 0;超时 = 2;参数错 = 1;rotom 调用失败 = 3。
+
+## 关键约束
+
+1. **写盘必须挂在 in_progress issue 下**——先 `rotom issue list <gid> --status in_progress`,没有就先建。严禁"先动手再补 issue"(详见 `rotom-a2a-communicate`)
+2. **groupId / issueId 从命令输出取,不要编**
+3. **群消息异步**——`group send` 发完即返回,对方回复作为新群消息到达。**绝不能编造对方回答**,等 `new-messages` 拉到再说
+4. **每轮只发一次 `group send`**——发完立即结束本轮输出
+
+## 反模式
+
+- ❌ 轮询太快(每秒一次)→ 30s 间隔足够
+- ❌ 把明确任务塞进群消息 → 用 `issue create --run` 派单
+- ❌ 群消息 5+ 轮没收敛 → 升级为 task issue
+- ❌ 不带 `--need-reply` 直接 `group send` → 正文没 `@target`,对方 worker SKIP,消息白发
+
+## 与 `rotom-a2a-communicate` 的关系
+
+本 skill 只补"建群 + 一问一答"模式的增量。群消息上下文识别、行动判定、写盘兜底话术、#reply 超时升级等通用规则见 `rotom-a2a-communicate`,不重复。

package/skill/rotom-bus-host/scripts/poll-replies.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# poll-replies.sh — 轮询 rotom 群最近 10 条消息,等出现新消息后 dump 给大模型判断
+#
+# 用法:
+#   poll-replies.sh <groupId> --as <agent> [options]
+#
+# 必填:
+#   <groupId>            群 ID
+#   --as <agent>         轮询身份(对应 ~/.rotom/executor.config.json 的 worker 名)
+#
+# 可选:
+#   --max-rounds N       最多轮询 N 轮(默认 10)
+#   --interval S         每轮间隔秒数(默认 30)
+#   --limit N            每次拉多少条最近消息(默认 10)
+#   --once               只拉一次当前最近 N 条,不轮询(LLM 自己看现状用)
+#   --quiet              静默模式:轮询中不打印 "still waiting..." 心跳
+#
+# 默认 10×30s = 5min,正好覆盖 ask-bridge 5min 超时窗口。
+#
+# 原理:不靠 --since 时间过滤(那是 JSON/表格列位陷阱)。开局拉一次最近 N 条
+# 记下哈希,每轮再拉一次比哈希。哈希变了 = 有新消息到位,把当前最近 N 条
+# 完整 dump 到 stdout,退出码 0。大模型自己读这 N 条判断里面有没有自己等
+# 的回复。如果没有就再调一次脚本继续等。
+#
+# 退出码:
+#   0  检测到新消息(最近 N 条已 echo 到 stdout)
+#   1  命令行参数错
+#   2  轮询 N 轮仍无新消息(超时)
+#   3  其它错误(rotom 命令失败、group 不存在等)
+#
+# 例子:
+#   poll-replies.sh 7cada00f-... --as codex-xihua
+#   poll-replies.sh 7cada00f-... --as codex-xihua --max-rounds 20 --interval 15
+#   poll-replies.sh 7cada00f-... --as codex-xihua --once            # 只看当前,不等
+set -euo pipefail
+
+print_usage() {
+  sed -n '2,/^set -/p' "$0" | sed '$d'
+}
+
+# ----- 参数解析 -----
+if [ $# -lt 1 ]; then
+  print_usage
+  exit 1
+fi
+
+GID="$1"; shift
+
+AS=""
+MAX_ROUNDS=10
+INTERVAL=30
+LIMIT=10
+ONCE=false
+QUIET=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --as)         AS="$2"; shift 2;;
+    --max-rounds) MAX_ROUNDS="$2"; shift 2;;
+    --interval)   INTERVAL="$2"; shift 2;;
+    --limit)      LIMIT="$2"; shift 2;;
+    --once)      ONCE=true; shift;;
+    --quiet)     QUIET=true; shift;;
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
+    *)
+      echo "unknown arg: $1" >&2
+      print_usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$AS" ]; then
+  echo "--as <agent> is required" >&2
+  exit 1
+fi
+
+if ! [[ "$MAX_ROUNDS" =~ ^[0-9]+$ ]] || [ "$MAX_ROUNDS" -lt 1 ]; then
+  echo "--max-rounds must be a positive integer" >&2
+  exit 1
+fi
+
+if ! [[ "$INTERVAL" =~ ^[0-9]+$ ]] || [ "$INTERVAL" -lt 0 ]; then
+  echo "--interval must be a non-negative integer (seconds)" >&2
+  exit 1
+fi
+
+if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ]; then
+  echo "--limit must be a positive integer" >&2
+  exit 1
+fi
+
+# ----- 拉取函数 -----
+fetch_latest() {
+  # --clean 剥 [status:thinking]/[tool:exec] 等标记,--pretty 出表格
+  # 便于人/LLM 直读。返回内容用作哈希比较 + 最终 dump。
+  rotom --pretty --as="$AS" group history "$GID" --limit "$LIMIT" --clean 2>&1
+}
+
+# 哈希:去掉 [rotom] Resolving... 这类 stderr 前缀行,只对表格本体算哈希。
+# 这样 master 日志/agent 解析行不会污染比较。
+hash_output() {
+  printf '%s\n' "$1" | grep -v '^\[rotom\]' | shasum | cut -d' ' -f1
+}
+
+# ----- --once 模式:拉一次就走 -----
+if [ "$ONCE" = true ]; then
+  fetch_latest
+  exit 0
+fi
+
+# ----- 主循环 -----
+INITIAL=$(fetch_latest)
+INITIAL_HASH=$(hash_output "$INITIAL")
+if [ -z "$INITIAL_HASH" ]; then
+  echo "[poll-replies] initial fetch failed (empty output)" >&2
+  exit 3
+fi
+
+echo "[poll-replies] group=$GID as=$AS limit=$LIMIT rounds=$MAX_ROUNDS interval=${INTERVAL}s" >&2
+
+for i in $(seq 1 "$MAX_ROUNDS"); do
+  sleep "$INTERVAL"
+
+  CURRENT=$(fetch_latest)
+  CURRENT_HASH=$(hash_output "$CURRENT")
+
+  if [ -z "$CURRENT_HASH" ]; then
+    echo "[poll-replies] round $i: fetch failed, retry next round" >&2
+    continue
+  fi
+
+  if [ "$CURRENT_HASH" != "$INITIAL_HASH" ]; then
+    echo "[poll-replies] round $i/$MAX_ROUNDS: new message detected, dumping latest $LIMIT" >&2
+    printf '%s\n' "$CURRENT"
+    exit 0
+  fi
+
+  if [ "$QUIET" = false ]; then
+    echo "[poll-replies] round $i/$MAX_ROUNDS: no change, waiting ${INTERVAL}s..." >&2
+  fi
+done
+
+echo "[poll-replies] timed out after $MAX_ROUNDS rounds (~$((MAX_ROUNDS * INTERVAL))s), no new messages" >&2
+exit 2