@mu-cabin/muc-cli 0.6.3 → 0.6.5

package/README.md

@@ -4,6 +4,16 @@
 
 0.6.0 迁入新版命令契约。要求 **Node.js ≥ 22.16**，使用内置 SQLite，无需独立 Supervisor、Launcher、Keychain、TUI 或客户端。运行时依赖已打包进单个 `dist/muc.mjs`。
 
+## 0.6.5 群管理与后台恢复
+
+支持群详情、名称与入群设置、独立头像修改、退出／解散、成员与管理员管理、转让群主、入群申请处理和群公告。调用方式仍为 `muc exec groups.<操作> --profile-id <id>` 加 JSON stdin；参数见 [群管理契约](REFERENCE.md#群管理)。申请列表仅覆盖本地已接收通知。
+
+后台升级自动排空在途请求并切换，监听断线后沿用游标有限重连。远端请求等待目标账号启动或重连完成，最多 5 秒；超时或取消不发送请求，已停止或被踢下线的账号须显式恢复。
+
+## 0.6.4 大群 @ 名单接收修复
+
+移除接收、读取和发送链路对 @ 人员列表的 100 人限制，完整保留名单，避免大群消息导致整批入站校验失败、无法确认接收和后续消息积压。账号格式与报文大小校验保持不变。升级后需重启 daemon，新代码才会生效。
+
 ## 0.6.2 附件下载修复
 
 图片和文件可下载到操作系统允许写入的目录，包括 macOS `/tmp`、共享目录和目录符号链接。路径无效或目标文件已存在时返回明确错误与修复提示，不再误报后台不支持操作。下载仍不覆盖已有文件。
@@ -18,13 +28,13 @@
 
 ```powershell
 node --version
-npm.cmd install -g @mu-cabin/muc-cli@0.6.3
+npm.cmd install -g @mu-cabin/muc-cli@0.6.5
 muc.cmd --version
 muc.cmd login --account YOUR_ACCOUNT --profile-id default --remember
 muc.cmd whoami --profile-id default
 ```
 
-默认数据目录为 `%USERPROFILE%\.muc`。首次使用仍需管理员通过受保护 stdin 完成 `init`；升级已有配置无需重新初始化。更新前运行 `muc.cmd daemon stop`，安装后下次登录或查询会启动新版后台；使用自定义配置根时，停止和启动都指定同一 `--config-root`。
+默认数据目录为 `%USERPROFILE%\.muc`。首次使用仍需管理员通过受保护 stdin 完成 `init`；升级已有配置无需重新初始化。首次从旧双版本协议迁移时，更新前用旧 CLI 运行 `muc.cmd daemon stop`；使用自定义配置根时始终指定同一 `--config-root`。后续升级遵循下述自动切换规则。
 
 PowerShell 不支持 Bash 的 `<<'JSON'`。JSON 可用单引号字符串通过管道传入；Windows PowerShell 5.1 先设置 UTF-8，防止中文被转换为问号：
 
@@ -62,11 +72,15 @@ muc --output jsonl exec events.watch --profile-id default <<'JSON'
 JSON
 ```
 
-消费程序保存最后一条成功处理的事件游标，重连时通过 `cursor` 继续。`events.list` 用于持久化事件补取。后台离线期间的历史消息通过 `messages.list/search` 查询，不能把本地事件为空当作离线期间没有消息。
+`events.watch` 遇到后台升级或意外断线会有限重连，沿用原账号、筛选条件及最后成功输出的游标；尚无事件时保留初始订阅游标。收到明确的后台停止通知则结束，重连过程不会启动后台。消费程序仍须保存自己最后成功处理的游标；CLI 写入 stdout 不代表下游已经处理。`events.list` 用于持久化事件补取，后台离线期间的历史消息另查 `messages.list/search`。
 
 启动配置错误会直接返回原因，不再仅等待超时。`daemon logs` 返回安全的错误代码、说明和处理提示，不输出原始异常或凭据。
 
-普通命令按需启动 daemon；`daemon status/logs/stop` 不会启动后台。升级可执行文件前先停止相应配置根的 daemon，更新后再启动。被踢下线或主动停止的 profile 保留停止状态，须明确登录或 `runtime resume` 才能恢复。
+普通命令按需启动 daemon；`daemon status/logs/stop` 不会启动后台。新版 CLI 首次执行业务命令时，若正在运行的后台正式版本较旧，会先等待在途请求结束，再切换到当前可执行文件并确认就绪；并发命令共用一次切换。帮助、版本、状态、日志和只读管理查询不触发升级，旧 CLI 不自动降级较新的后台。`muc daemon restart` 可显式重启同一配置根。
+
+排空超时或取消会恢复旧后台接收请求，不强杀进程；旧后台停止后若新版启动失败，则明确报错并保留配置及数据库，不自动回滚。切换提示写入 stderr，业务写操作不会因断线自动重放。被踢下线或主动停止的 profile 保留停止状态，须明确登录或 `runtime resume` 才能恢复。
+
+同一 IPC 协议下，新增操作不会阻止已有操作运行；旧 daemon 缺少能力时，仅该操作返回 `OPERATION_UNSUPPORTED`。旧双版本协议与当前协议不兼容时返回 `INCOMPATIBLE_PROTOCOL`，按提示用旧 CLI 停止同配置根的后台后重试。
 
 完整参数见 [REFERENCE.md](REFERENCE.md)，agent 操作说明见 [skills/muc/SKILL.md](skills/muc/SKILL.md)。文件消息默认不附加尾注；文字和图片仍遵循原有尾注设置。发送结果不明时查询原 delivery/idempotency key，不自动重发。
 

package/REFERENCE.md

@@ -1,6 +1,6 @@
 # MUC 命令契约
 
-本文件描述 0.6.3 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
+本文件描述 0.6.5 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
 
 ## 命令结构
 
@@ -17,12 +17,12 @@ Windows 默认配置根为 `%USERPROFILE%\.muc`。PowerShell 若阻止 npm 生
 | `login --qr` | 在真实终端扫码登录 |
 | `whoami [--profile-id <id>]` | 核验当前用户 |
 | `profile list/create/update/login/logout` | 管理账号配置；修改输入来自 stdin |
-| `daemon start/stop/status/logs` | 管理同包后台进程 |
+| `daemon start/restart/stop/status/logs` | 管理同包后台进程 |
 | `runtime status/ensure/start/resume/stop` | 管理明确 profile 的连接状态 |
 | `manifest` | 查询当前操作契约 |
 | `exec <operation-id> --profile-id <id>` | 按 schema 执行业务操作 |
 
-操作 ID 与输入结构以 `src/ipc/v2/operations.ts` 和实际 `muc manifest` 为准，不在文档维护另一份静态覆盖矩阵。
+操作 ID 与输入结构以 `src/ipc/contracts/operations.ts`、`groups.ts` 和实际 `muc manifest` 为准，不在文档维护另一份静态覆盖矩阵。
 
 ## 输出与恢复
 
@@ -30,7 +30,13 @@ Windows 默认配置根为 `%USERPROFILE%\.muc`。PowerShell 若阻止 npm 生
 
 `events.watch` 使用 JSONL：先输出订阅 metadata，再输出事件。保留 `startedAtCursor`、`highWatermark` 和每条已处理事件的游标。消费进程退出不停止 daemon。
 
-写操作使用稳定 idempotency key；dry-run 与真正提交使用不同 key。提交结果不明时使用原 key 或 deliveryId 查询 `deliveries.get`，不新建 key 重发。
+升级或意外断线后，监听最多连续重连 8 次；成功输出事件后重新计数。保留 profile、过滤条件、最后成功写入 stdout 的游标，首条事件前使用初始订阅游标。重连仅连接已有后台，不启动或降级后台。明确停止通知正常结束；认证、协议、无效或已清理游标以及输出失败直接报错，不自动改用最新游标。SIGINT/SIGTERM 中止连接与等待，退出码为 130/143。下游消费仍需独立确认游标，不能据此承诺恰好一次处理或服务端离线消息完整覆盖。
+
+写操作使用稳定 idempotency key；dry-run 与真正提交使用不同 key。消息发送结果不明时使用原 key 或 deliveryId 查询 `deliveries.get`；群管理结果不明时读取群状态核实，不新建 key 重发。
+
+IPC 使用单一 `protocolVersion`；新增操作通过 capability 判断，不因构建版本或清单摘要变化拒绝连接。`OPERATION_UNSUPPORTED` 只影响该操作；`INCOMPATIBLE_PROTOCOL` 要求先用旧 CLI 停止同配置根的后台再运行当前 CLI，保留配置和数据库。
+
+业务命令比较 CLI 与后台的正式 `x.y.z` 版本：仅较新的 CLI 自动升级较旧后台，开发／预发布标识不自动比较。切换前排空在途请求，超时或取消恢复接收；不强杀、不回滚数据库、不重放未知写入。`daemon restart` 显式重启，仍不降级较新后台。帮助、版本、状态、日志、manifest 和只读管理查询不触发升级。旧后台若缺少协调停止接口，按 `DAEMON_UPGRADE_REQUIRED` 提示先用旧 CLI 停止。旧版监听进程需重新运行一次才能获得重连能力。 远端请求仅在目标账号正在启动或重连时等待就绪，最多 5 秒；超时返回 `RUNTIME_NOT_READY`，取消会终止等待，均不发送该请求。其他账号不会阻塞此等待，已停止或被踢下线的账号不会自动恢复。
 
 认证恢复由 daemon 负责。明确认证失效后才进入下一种凭据，网络失败不触发密码兜底；恢复耗尽后由用户重新登录指定 profile。
 
@@ -50,3 +56,36 @@ Windows 默认配置根为 `%USERPROFILE%\.muc`。PowerShell 若阻止 npm 生
 普通文件发送默认不带尾注（包括带说明的文件消息）；明确 `--tail` 才添加。文件上传须完成服务端扫描并取得未来有效期，才会进入消息发送；扫描失败不会降级发送过期文件。
 
 附件下载按操作系统权限处理输出目录，支持 `/tmp`、共享目录和目录符号链接；仍不覆盖已有文件。`OUTPUT_PATH_INVALID` 表示路径无效或不可用，`OUTPUT_EXISTS` 表示目标文件已存在。省略 `outputPath` 使用账号私有下载目录。
+
+@ 人员列表不设固定人数上限，不截断接收或发送的名单；账号格式、正文及传输报文大小校验仍适用。
+
+## 群管理
+
+以下接口使用 `groupId`。所有写操作还需 `idempotencyKey`，可选 `dryRun:true` 仅校验输入并读取目标，不提交远端修改；它不保证服务端最终授权。成员标识为 `{userId,appKey?}`，省略 `appKey` 使用当前租户。优先保留 `groups.members` 返回的应用标识。
+
+| 操作 | 额外输入 | 结果／行为 |
+| --- | --- | --- |
+| `groups.get` | 无 | 群主、管理员、名称、头像、成员数、加入状态及可获取的群设置 |
+| `groups.update` | `settings` | 至少一项：`name`（1–80 字）、`introduction`（最多 4096 字）、`joinMode`（`noVerify/needVerify/rejectAll`）、`enableMemberInvite`（布尔值） |
+| `groups.set-avatar` | `avatar:{sourcePath,name,mimeType,expectedSize}` | 本地 JPEG/PNG/WebP，最大 1 MiB |
+| `groups.leave` / `groups.dismiss` | 无 | 退出／解散群；成功后移除本地群缓存和活动会话，保留历史消息 |
+| `groups.members.add` | `members:[{userId,name,appKey?}]` | 添加 1–499 名成员 |
+| `groups.members.remove` | `members:[{userId,appKey?}]` | 移除成员；本人退出使用 `groups.leave` |
+| `groups.managers.add` / `groups.managers.remove` | `members:[{userId,appKey?}]` | 设置／取消管理员 |
+| `groups.transfer-owner` | `owner:{userId,appKey?}` | 转让群主，当前用户继续留群 |
+| `groups.apply` | `nickname` | 申请入群；请求被接受不代表已加入 |
+| `groups.applications.list` | 可选 `groupId,status,cursor,limit` | `status` 默认 `pending`，也可为 `approved/rejected/unavailable/all`；`limit` 默认 100，最大 200 |
+| `groups.applications.approve` / `groups.applications.reject` | `applicationId`；拒绝可带 `reason` | 处理列表返回的待处理申请，自动使用其申请人、应用标识和群昵称 |
+| `groups.bulletins.list` | 可选 `page,size` | 默认第 1 页、每页 20 条，最多 100 条；返回 `items,hasMore` |
+| `groups.bulletins.create` | `content`，可选 `subject` | 正文最多 32000 字，主题默认“群公告”；仅在服务端回执包含 ID 时返回 `bulletinId` |
+| `groups.bulletins.remove` | `bulletinIds` | 删除本群 1–100 条指定公告 |
+
+写入结果包含 `accepted`、`dryRun`、`refreshPending`。`accepted:true` 表示服务端已确认请求；`refreshPending:true` 表示随后本地投影或资料刷新失败，可重新读取群详情、成员、公告或同步会话，不应重发写操作。相同操作、参数和幂等键返回已保存结果，修改参数复用原键会报冲突。网络中断或进程中断导致结果未知时返回 `COMMIT_OUTCOME_UNKNOWN`，原键阻止再次发送；应读取远端状态核实，不能更换键绕过。
+
+申请列表来自 daemon 已接收并保存的群通知，返回 `source:"local-events",complete:false`；不是服务端完整待办列表，升级前或离线期间缺失的申请可能不在其中。分页沿用返回的 `nextCursor` 和相同筛选条件。远端同意／拒绝通知及本 CLI 的处理结果会更新本地申请状态。群类型和服务端角色权限决定实际可执行操作。
+
+```sh
+muc exec groups.update --profile-id PROFILE_ID <<'JSON'
+{"groupId":"GROUP_ID","settings":{"name":"项目讨论群"},"idempotencyKey":"group-rename-unique-001"}
+JSON
+```