@mu-cabin/muc-cli
v0.6.7
Published
Standalone agent-first MUC CLI with an embedded background daemon
Readme
MUC CLI
面向 agent 的独立 MUC 命令行工具。CLI 与后台 daemon 由同一个 muc 可执行文件运行;后台维护账号连接、认证恢复、消息和事件,监听消费者退出后仍继续运行。
0.6.0 迁入新版命令契约。要求 Node.js ≥ 22.16,使用内置 SQLite,无需独立 Supervisor、Launcher、Keychain、TUI 或客户端。运行时依赖已打包进单个 dist/muc.mjs。
内置表情
emojis.list 列出 85 个内置表情,全部标记为 reactionAllowed: true。把任一条目的 id(如 [收到])原样传给 reactions.add 即可回应消息。
0.6.5 群管理与后台恢复
支持群详情、名称与入群设置、独立头像修改、退出/解散、成员与管理员管理、转让群主、入群申请处理和群公告。调用方式仍为 muc exec groups.<操作> --profile-id <id> 加 JSON stdin;参数见 群管理契约。申请列表仅覆盖本地已接收通知。
后台升级自动排空在途请求并切换,监听断线后沿用游标有限重连。远端请求等待目标账号启动或重连完成,最多 5 秒;超时或取消不发送请求,已停止或被踢下线的账号须显式恢复。
0.6.4 大群 @ 名单接收修复
移除接收、读取和发送链路对 @ 人员列表的 100 人限制,完整保留名单,避免大群消息导致整批入站校验失败、无法确认接收和后续消息积压。账号格式与报文大小校验保持不变。升级后需重启 daemon,新代码才会生效。
0.6.2 附件下载修复
图片和文件可下载到操作系统允许写入的目录,包括 macOS /tmp、共享目录和目录符号链接。路径无效或目标文件已存在时返回明确错误与修复提示,不再误报后台不支持操作。下载仍不覆盖已有文件。
0.6.3 Windows 兼容修复
修复 Windows 已有后台锁文件被 Unix 权限检查误判,导致 login 等命令无法启动后台的问题;单实例互斥继续由 Windows 命名管道保证。JSON stdin 支持 UTF-8 BOM 和 CRLF。源码清理和离线打包不再需要 Bash 或 rm。
Windows 安装与运行
安装 Node.js 22.16 或更新版本,在 PowerShell 中运行(npm.cmd / muc.cmd 可避开 .ps1 执行策略限制):
node --version
npm.cmd install -g @mu-cabin/[email protected]
muc.cmd --version
muc.cmd login --account YOUR_ACCOUNT --profile-id default --remember
muc.cmd whoami --profile-id default默认数据目录为 %USERPROFILE%\.muc。首次使用仍需管理员通过受保护 stdin 完成 init;升级已有配置无需重新初始化。首次从旧双版本协议迁移时,更新前用旧 CLI 运行 muc.cmd daemon stop;使用自定义配置根时始终指定同一 --config-root。后续升级遵循下述自动切换规则。
PowerShell 不支持 Bash 的 <<'JSON'。JSON 可用单引号字符串通过管道传入;Windows PowerShell 5.1 先设置 UTF-8,防止中文被转换为问号:
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
'{"limit":20}' | muc.cmd exec chats.list --profile-id default
'{"includeSelf":false}' | muc.cmd --output jsonl exec events.watch --profile-id defaultCMD 可使用 echo {"limit":20} | muc.cmd exec chats.list --profile-id default。复杂 JSON 使用 UTF-8 文件重定向:muc.cmd exec chats.list --profile-id default < request.json。JSON 中的 Windows 路径使用 C:/Users/NAME/Downloads/file.png 或双反斜杠,含空格的命令行路径用双引号包围。密码仍只在用户终端的隐藏提示或受保护 stdin 输入。
配置和登录
默认数据目录为 ~/.muc;MUC_CONFIG_DIR 或全局 --config-root 可指定隔离目录。首次部署用 muc init 从受保护 stdin 接收管理员提供的租户和端点配置。
muc profile list
muc login --account YOUR_ACCOUNT --profile-id default --remember
muc whoami --profile-id default
muc daemon status用户在自己的终端通过隐藏提示输入密码;非交互环境使用 --password-stdin 或受保护的 JSON stdin。禁止明文密码参数和聊天中粘贴密码。--remember 显式启用原版的机器绑定密码加密,--no-remember 在成功登录后移除已记住的密码。
账号、端点和偏好存入 config.json,会话及租户敏感信息存入 credentials.json,均为 0600。认证先核验当前 token;明确失效后依次尝试 tokenPwd、记住的密码。网络失败不会自动降级凭据,已绑定账号重新登录不会主动重建 tokenPwd。
查询与监听
muc exec chats.list --profile-id default <<'JSON'
{"limit":20}
JSON
muc --output jsonl exec events.watch --profile-id default <<'JSON'
{"includeSelf":false}
JSONevents.watch 遇到后台升级或意外断线会有限重连,沿用原账号、筛选条件及最后成功输出的游标;尚无事件时保留初始订阅游标。收到明确的后台停止通知则结束,重连过程不会启动后台。消费程序仍须保存自己最后成功处理的游标;CLI 写入 stdout 不代表下游已经处理。events.list 用于持久化事件补取,后台离线期间的历史消息另查 messages.list/search。
启动配置错误会直接返回原因,不再仅等待超时。daemon logs 返回安全的错误代码、说明和处理提示,不输出原始异常或凭据。
普通命令按需启动 daemon;daemon status/logs/stop 不会启动后台。新版 CLI 首次执行业务命令时,若正在运行的后台正式版本较旧,会先等待在途请求结束,再切换到当前可执行文件并确认就绪;并发命令共用一次切换。帮助、版本、状态、日志和只读管理查询不触发升级,旧 CLI 不自动降级较新的后台。muc daemon restart 可显式重启同一配置根。
排空超时或取消会恢复旧后台接收请求,不强杀进程;旧后台停止后若新版启动失败,则明确报错并保留配置及数据库,不自动回滚。切换提示写入 stderr,业务写操作不会因断线自动重放。被踢下线或主动停止的 profile 保留停止状态,须明确登录或 runtime resume 才能恢复。
同一 IPC 协议下,新增操作不会阻止已有操作运行;旧 daemon 缺少能力时,仅该操作返回 OPERATION_UNSUPPORTED。旧双版本协议与当前协议不兼容时返回 INCOMPATIBLE_PROTOCOL,按提示用旧 CLI 停止同配置根的后台后重试。
完整参数见 REFERENCE.md,agent 操作说明见 skills/muc/SKILL.md。文件消息默认不附加尾注;文字和图片仍遵循原有尾注设置。发送结果不明时查询原 delivery/idempotency key,不自动重发。
从旧 CLI 迁移
0.6.1 支持单账号平铺配置和 activeProfile + profiles 多账号配置;后者保留全部 profile,并将默认账号映射为 selectedProfileId。不同租户、缺失默认账号或无法解密的记住密码会拒绝迁移并保留原文件。
迁移后会在启动时登记消息数据库中的账号,确保群信息和消息同步可正常落库。
首次启动会识别当前配置根中的旧版 config.json / credentials.json,保留设备、插槽、账号、token、记住密码和消息尾注,并生成私有的 *.v1.backup.json 备份。迁移只处理所选配置根;旧后台仍运行时会拒绝迁移。旧消息日志、assistant 配置和旧版命令不迁入。
旧 send/history/listen/assistant/daemon-* 命令改用新版 exec 和 daemon 命令,Skill 合并为 skills/muc。此版本不提供 TUI、机器人执行后端和独立升级控制面。不要直接将旧二进制指向迁移后的目录;回退须停止新后台后在独立目录恢复旧备份及原 remember.salt。
开发
pnpm --filter @mu-cabin/muc-cli typecheck
pnpm --filter @mu-cabin/muc-cli test
pnpm --filter @mu-cabin/muc-cli build仓库内的 AGENTS.md 与 docs/development.md 记录开发约定和验收证据;它们不属于安装包。Skill 源码随包发布,全局安装副本需另行安装。
pnpm --filter @mu-cabin/muc-cli clean 和 pack:offline 支持 Windows、macOS、Linux。MUC 的运行时依赖已内嵌,pack:offline 直接生成普通 npm tarball mu-cabin-muc-cli-<version>.tgz,目标机器可用 npm install -g --offline <tarball> 安装,无需另行捆绑依赖。
