npm - @mu-cabin/muc-cli - Versions diffs - 0.3.0 → 0.5.0 - Mend

@mu-cabin/muc-cli 0.3.0 → 0.5.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.

Files changed (13) hide show

package/README.md +262 -393
package/dist/muc.mjs +14170 -2900
package/dist/templates/code-handler/bin/prep-repo +386 -0
package/dist/templates/code-handler/setup-notes.md +63 -0
package/dist/templates/code-handler/system-prompt.md +153 -0
package/dist/templates/code-handler/template.json +15 -0
package/dist/templates/general-chat/setup-notes.md +64 -0
package/dist/templates/general-chat/system-prompt.md +44 -0
package/dist/templates/general-chat/template.json +12 -0
package/dist/templates/image-generator/setup-notes.md +64 -0
package/dist/templates/image-generator/system-prompt.md +74 -0
package/dist/templates/image-generator/template.json +14 -0
package/package.json +12 -10

package/README.md CHANGED Viewed

@@ -1,459 +1,328 @@
-# muc-cli
+# MUC-cli
-Terminal client for 东航 MUC IM (the `com.meicloud.im.dh` desktop app, also
-called MUC.app). Drives the same REST surface the desktop talks to, plus the
-binary chat protocol on raw TCP 8101 for sending messages, withdrawing, and
-syncing sessions.
+**muc-cli** 把 MUC IM（com.meicloud.im.dh）搬进终端。在 shell 里登录、找人、列群、读历史、收发消息和文件，不用打开桌面端 GUI。它同时附带**MUC Skill**，让你直接对 agent 说"把这个报告发给 张三"，Skill 会自动选命令、解析返回值。
-REST commands always coexist with the running desktop and phone — the server
-allows concurrent `accessToken`s. Chat-channel commands share online slots
-with real devices; see [Coexistence](#coexistence) below before sending.
+---
-## What it is
+## 快速安装（复制给 Agent）
-A single command (`muc`) packaging:
+把下面这段话发给 Agent, 它会帮你完成全部安装：
-- **Send** — 1:1 and group text, files, images, and voice clips. Add and
-  remove emoticon reactions on existing messages.
-- **Read** — server-side chat history, profile lookups, group lists, sticker
-  packs, directory search (people, departments, apps, service numbers), and
-  long-lived `listen` tail of inbound messages with sender/keyword filters.
-- **Manage** — login / token refresh, withdraw a message, clear a session,
-  download a chat-attached file, wait for a human emoticon reaction before
-  proceeding (`wait-react`).
-- **Self-describe** — every command has a `--json` mode emitting a stable
-  envelope; `muc manifest --json` returns the full command graph + per-command
-  output JSON Schema for agent / script consumers.
+```
+帮我安装 muc-cli 和 MUC Skill：
+1. 运行 `npm install -g @mu-cabin/muc-cli` 安装 CLI
+2. 运行 `npx skills add <everything-cli 仓库地址>/packages/muc/skills -y -g` 注册 Skill（全局安装到所有 agent）
+3. 运行下面这条 `muc init` 一次性写入租户配置（值见你的 MUC 部署管理员）：
+   muc init --no-interactive \
+     --app-key <APP_KEY> \
+     --app-id <APP_ID> \
+     --sign-secret-rest '<SIGN_SECRET_REST>' \
+     --sign-secret-secure '<SIGN_SECRET_SECURE>'
+4. 运行 `muc login --account <UID大写,如 ALICE> --password '<密码>'` 登录
+5. 运行 `muc whoami` 确认登录成功
+```
+---
+## MUC 租户配置
+CLI 不把租户密钥编进发布包；首次安装后必须用 `muc init` 把这四个值写入
+`~/.muc/config.json`（权限 0600）。**这些值因部署而异——向你的 MUC 管理员索取，
+不要外发。**
+| 字段 | 值 |
+|---|---|
+| `APP_KEY`            | `<APP_KEY>`（8 位小写 hex） |
+| `APP_ID`             | `<APP_ID>`（24 位小写 hex） |
+| `SIGN_SECRET_REST`   | `<SIGN_SECRET_REST>` |
+| `SIGN_SECRET_SECURE` | `<SIGN_SECRET_SECURE>` |
+| `PWD_DES_KEY`        | 留空（自动用 `APP_KEY`） |
+主机/端口（向管理员索取你的部署地址，CLI 内置默认仅适用于特定租户）：
+| 字段 | 示例 |
+|---|---|
+| `restHost` | `https://muc.example.com/` |
+| `ssoHost`  | `https://store.example.com/` |
+| `imHost` / `imPort`     | `muc.example.com` / `8101` |
+| `fileHost` / `filePort` | `muc.example.com` / `6101` |
-## Install
+一行式（非交互，CI/Agent 友好）：
 ```bash
-npm i -g @mu-cabin/muc-cli
-muc --version
+muc init --no-interactive \
+  --app-key <APP_KEY> \
+  --app-id <APP_ID> \
+  --sign-secret-rest '<SIGN_SECRET_REST>' \
+  --sign-secret-secure '<SIGN_SECRET_SECURE>'
 ```
-Requirements: **Node ≥ 18**. macOS, Linux, and Windows are all supported.
-DES-CBC password encryption is `crypto-js` (pure JS) — no
-`--openssl-legacy-provider` flag needed.
-`~/.muc/credentials.json` and `~/.muc/config.json` are written with mode
-`600` and the parent dir with mode `700`. POSIX honors that; on Windows the
-modes are silently ignored — protect the files with NTFS ACLs if you're on a
-shared host.
+或交互式：
-## First-time setup
+```bash
+muc init   # 逐项提示，密钥手输，主机/端口按回车采用默认
+```
-Before you can `login`, run `muc init` to seed the tenant configuration. The
-CLI is generic across MUC deployments — your MUC admin provides the
-tenant-specific values.
+校验：
 ```bash
-muc init       # interactive: walks through APP_KEY, APP_ID, signing secrets, hosts
+muc init --check --json   # exit 0=ok, 6=missing, 7=invalid
+muc init --show           # 仅显示打码后的指纹（不会回显原值）
 ```
-What `muc init` collects:
+> 这些值是租户级密钥，**绝不要复制到 npm 包、Skill 包或任何公开渠道**。向你的
+> MUC 部署管理员索取，并只通过私有渠道传递。
-| Field | Source | Notes |
-|---|---|---|
-| `appKey` | admin | 8 hex chars |
-| `appId` | admin | 24 hex chars |
-| `signSecretRest` | admin | secret for the regular-API signing scheme |
-| `signSecretSecure` | admin | secret for the `/contacts/secure/...` signing scheme |
-| `pwdDesKey` | admin (optional) | DES-CBC key for password encryption; defaults to `appKey` |
-| `restHost` | default `https://muc.ceair.com/` | press enter to accept |
-| `ssoHost` | default `https://store.ceair.com/` | reserved (advanced) |
-| `imHost` / `imPort` | default `muc.ceair.com` / `8101` | TCP chat channel |
-| `fileHost` / `filePort` | default `muc.ceair.com` / `6101` | TCP file channel |
+---
-Built-in defaults are provided **for hosts and ports only** — never for
-`appKey`, `appId`, or signing secrets.
+## 安装 CLI
-### Non-interactive (CI, scripts)
+环境: Node ≥ 18
-You can supply values via flags or env vars:
+```bash
+npm install -g @mu-cabin/muc-cli
+muc --version
+```
-Get the four secrets from your MUC admin first; the snippets below use
-placeholder names — substitute the real values your admin gives you.
+### 首次配置（一次性）
+CLI 没有内置可用的租户密钥，必须先用 `muc init` 写入。值见上面 "MUC 租户配置" 表：
 ```bash
-# Flag form
 muc init --no-interactive \
-  --app-key            "$APP_KEY" \
-  --app-id             "$APP_ID" \
-  --sign-secret-rest   "$SIGN_SECRET_REST" \
-  --sign-secret-secure "$SIGN_SECRET_SECURE" \
-  --json
-# Env-var form
-MUC_APP_KEY="$APP_KEY" \
-MUC_APP_ID="$APP_ID" \
-MUC_SIGN_SECRET_REST="$SIGN_SECRET_REST" \
-MUC_SIGN_SECRET_SECURE="$SIGN_SECRET_SECURE" \
-muc init --no-interactive
+  --app-key <APP_KEY> \
+  --app-id <APP_ID> \
+  --sign-secret-rest '<SIGN_SECRET_REST>' \
+  --sign-secret-secure '<SIGN_SECRET_SECURE>'
+muc init --check   # 应输出 ok
 ```
-Environment variables: `MUC_APP_KEY`, `MUC_APP_ID`, `MUC_SIGN_SECRET_REST`,
-`MUC_SIGN_SECRET_SECURE`, `MUC_PWD_DES_KEY`, `MUC_REST_HOST`, `MUC_SSO_HOST`,
-`MUC_IM_HOST`, `MUC_IM_PORT`, `MUC_FILE_HOST`, `MUC_FILE_PORT`.
+### 首次登录
-> **Env-var leakage warning.** Values exported into the environment are
-> visible to other processes on the same machine via `/proc/<pid>/environ`
-> on Linux, and they land in shell history if you don't prefix the command
-> with a space (and `HISTCONTROL=ignorespace` is set). For production setups
-> prefer the **interactive** prompt or **flag-based** invocation — you can
-> protect the flag values with secret-manager retrieval that never touches
-> the env.
+```bash
+muc login --account ALICE --password '<你的密码>'
+muc whoami
+```
-### Inspect, repair, reset
+登录成功后凭证写入 `~/.muc/credentials.json`（权限 600），有效期约 7 天；`tokenPwd`（30 天）可用于静默续登：
 ```bash
-muc init --check          # validate; exit 0 ok, 6 missing, 7 invalid
-muc init --check --json   # same, machine-readable
-muc init --show           # print config (secrets always redacted)
-muc init --show --json    # JSON envelope — secrets are also redacted here
-                          # (read ~/.muc/config.json directly for raw values)
-muc init --reset --yes    # delete ~/.muc/config.json
+muc login --token-pwd   # 无需密码，直接续登
 ```
-Resolution order per field: CLI flag → env var → existing saved value → built-in
-default (hosts/ports only) → interactive prompt (TTY) → fail.
+---
+## 安装并使用 Agent Code Skill
-## Login
+Skill 注册之后，你可以直接用自然语言驱动 `muc`，不用记命令格式。
-`muc login` is **non-interactive on the credential side** — it never prompts
-for a password. Pass it via flag, stdin, env var, or `--token-pwd` (reuse
-the saved tokenPwd).
+### 安装 Skill
 ```bash
-# Plaintext flag (avoid; lands in shell history)
-muc login --account WANGLULU8 --password '…'
+npx skills add <everything-cli 仓库地址>/packages/muc/skills -y -g
+```
+注册后 Agent Code 会自动识别 muc 相关请求并调用对应命令。
-# Safer: read password from stdin, no flag value
-printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
+### 对 Agent 说什么
-# Reuse saved tokenPwd (no password needed; ~30 day TTL)
-muc login --token-pwd
+以下这些说法都会触发 muc-cli Skill：
-# Env-var form
-MUC_ACCOUNT=WANGLULU8 MUC_PASSWORD='…' muc login
+```
+"把今天的周报发给 张三"
+"拉一下 王五 本周的聊天记录"
+"列一下我在 MUC 的群"
+"帮我搜一下 MUC 上叫 李四 的人"
+"IT 值班群发个通知：今晚 22:00 有计划性维护"
+"把 muc 上刚才发的消息撤回"
+"下载一下 <mid> 这条消息里的附件"
 ```
-- `account` is your MUC uid (uppercase ASCII, e.g. `WANGLULU8`); falls back
-  to `$MUC_ACCOUNT` or the previously-saved uid if `--account` is omitted.
-- One of `--password` / `--password-stdin` / `--token-pwd` / `$MUC_PASSWORD`
-  is required — running `muc login` with no creds fails fast with
-  `AUTH_REQUIRED` (exit 3).
-- The password is encrypted client-side (DES-CBC) before being sent — same
-  scheme the desktop client uses.
-- A successful login saves to `~/.muc/credentials.json` (mode `600`):
-  `accessToken` (≈7 day TTL) and `tokenPwd` (≈30 day TTL, used for silent
-  re-login with `--token-pwd`).
-- A stable per-CLI device id is generated at `~/.muc/device-id` on first
-  run. It is intentionally **different** from the desktop's machine-id so
-  REST sessions stay independent.
-## Output contract
-- **Default:** human-readable plain text on stdout, errors on stderr in the
-  form `error: <msg>` / `hint: <hint>` / `code: <code> (exit <n>)`.
-- **`--json`** (anywhere on the command line): every command emits a single
-  stable JSON envelope on stdout — `{ok:true, schema_version:1, data}` or
-  `{ok:false, schema_version:1, code, msg, hint?}` — and stderr stays
-  silent. Agents and scripts should always pass `--json`.
-- **Exit codes** are typed and identical in both modes: `0` success, `1`
-  internal bug, `2` usage, `3` auth required / expired, `4` not found, `5`
-  remote / network error, `6` config missing, `7` config invalid.
-- `--help` / `--version` are human escape hatches and bypass the JSON
-  envelope by design. The canonical agent surface is `muc manifest --json`.
-## Commands
-### Setup
-| Command | What it does |
-|---|---|
-| `muc init` | Seed / inspect / reset tenant config (`~/.muc/config.json`). Run before `login`. See [First-time setup](#first-time-setup). |
+### Skill 的行为规则
-### REST commands (no impact on the desktop app)
+- **首次 TCP 命令前**：Skill 会弹 `AskUserQuestion` 提示槽位风险，等你确认后再执行。
+- **不确定发给谁**：先用 `muc search` 缩小候选名单，通过 `AskUserQuestion` 让你选，不会猜。
+- **非自身目标**：必须经过你显式确认，不会偷偷给真实联系人发消息。
+- **token 过期**：自动用 `--token-pwd` 静默续登，续登失败才要求你手动 `muc login`。
-| Command | What it does |
-|---|---|
-| `muc login` | Authenticate, persist `accessToken` + `tokenPwd`. |
-| `muc whoami` | Show the saved profile + token freshness. Local only — does not read tenant config. |
-| `muc search <keyword>` | Org / employee directory search (12 results max, server-side). |
-| `muc search-dept <keyword>` | Department directory search (with employee count + path). |
-| `muc search-app <keyword>` | Search the user's MUC widgets/apps drawer. |
-| `muc search-sno <keyword>` | Search service-numbers (服务号); shows `★` for already-subscribed. |
-| `muc whois <UID>` | Employee info + ext info (`secureApi`). Renders `cn / id / mail / departmentName / positionName / empStatusText`. `--no-ext` skips the slower `getExtInfo` call. |
-| `muc groups` | Starred groups (flat list keyed by `team_id`) + department groups (keyed by `groupId / deptName`). |
-| `muc emoticons` | Sticker packages installed on your account. |
-| `muc history --peer UID \| --team TEAM_ID \| --to-self` | Server-side chat history via the roaming-messages endpoint. Stateless: each call fetches from the server. Default window: 30 days, 50 messages newest-first. |
-| `muc download --file-key <key> [--out <path>]` | Download a chat-attached file from the V5 file server (TCP 6101). **Read-only** — opens a fresh per-request session, no chat login, doesn't kick anyone. Pass `--mid <mid>` instead of `--file-key` plus `--peer/--team/--to-self` to look the file up via roaming history. Verifies md5 on completion. |
-| `muc react --mid <MID> --sticker-id <id> [target]` | Add an emoticon reaction to an existing message. **Visible.** Defaults to `--to-self`; non-self chats need `--yes-not-self`. By default assumes the original message was sent by the current user; pass `--src-sender-id <UID>` (and `--src-sender-app <appkey>`) to react to someone else's message. |
-| `muc reactions --mid <MID>` | List all emoticon reactions on a single message. Read-only. |
-| `muc unreact --emoticon-id <id> [target]` | Revoke one of your own reactions (id from `muc react` or `muc reactions`). |
-| `muc manifest` | Print the full command graph + per-command output JSON Schema. Pair with `--json` for agents. |
-`history` flags: scope with one of `--peer UID`, `--team TEAM_ID`,
-`--sid <UID1|UID2 or teamId>`, or `--to-self`. `--limit N` (default 50),
-`--days N` (window from now, default 30), `--before <ts|ISO>` to fetch
-older than a moment, `--sub-type N` to filter to one type (e.g. `1` text,
-`7` file, `8` image), `--desc` for newest-first (default: oldest at top).
-The fetched `timestamp` is normalized to ms.
+### Agent 场景示例
+MUC Skill 的价值在于嵌入更大的 agent 工作流——先让 agent 完成主任务，再用 MUC 传递结果或读取上下文。
+**跑测试 → 失败通知值班群**
+> 帮我跑一下单测，如果有失败把结果发到 IT 值班群
+Agent 跑完测试、整理失败摘要，再通过 MUC 推送到群里。MUC 是"结果出口"。
+**Code Review → 通知作者**
+> 帮我 review 这个 PR，review 完把结论发给作者
+Agent 分析 diff、生成意见，从 git log 拿到作者，搜出对应 MUC 账号后发消息。
+**读群聊上下文 → 代为回复**
+> IT 值班群今天在讨论什么？帮我接着回复，说为什么要用 Redis 而不是本地缓存
+Agent 拉取今日群消息，理解讨论脉络，起草回复并等你确认后发出。MUC 历史是**输入上下文**。
+**分析日志 → 发文件给同事**
+> 帮我分析 logs/access.log，生成访问量报告发给 王五
+Agent 统计 PV/UV、Top 路径、错误率，写成报告文件，搜出收件人后 `muc send-file` 发出。
+**读 MUC 需求 → 生成代码骨架**
+> 看看 王五 昨天发给我的需求，整理成 TODO 并创建对应的函数骨架
+Agent 拉取消息、提取功能点、在项目里生成文件，最后用 MUC 回复确认。MUC 历史是**任务来源**。
+**定时周报（配合 `/schedule`）**
+> /schedule 每周五 17:00 帮我把本周 git 提交整理成周报发给上级
+Agent 定时触发，跑 `git log`、整理自然语言周报、确认收件人、发送。
+---
+## cli 命令速查
+### 查人 / 查组织
 ```bash
-muc history --peer YANWENYU --limit 100
-muc history --to-self --days 7
-muc history --team 9009876543210000 --before 2026-04-20 --json | jq .
+muc search 李四              # 关键字搜员工
+muc search-dept "信息技术部"  # 按部门搜（含员工数 + 层级路径）
+muc search-app "审批"        # 搜应用/小程序
+muc whois BOB               # 单人完整档案
+muc groups                  # 我的星标群 + 部门群
+muc search-team "值班" --enrich     # 查已加入群（TCP）
+muc team-members 9009876543210000 --profiles  # 查群成员 + 部门/岗位（TCP + REST）
 ```
-### Chat-channel commands (TCP 8101) — see [Coexistence](#coexistence)
+### 聊天历史
-| Command | What it does |
-|---|---|
-| `muc tcp-ping [--wait N] [--debug]` | TCP connect + NEGOTIATE only. Smoke test, no login frame, **zero** kick risk. |
-| `muc sync [--os OS]` | After chat-login, run `syncDone` / `syncSession` / `syncWithdraws`. Read-only. |
-| `muc search-team <keyword> [--enrich]` | Search groups you belong to via the chat channel; `--enrich` follows up with `team/get_team` per id to print names + member counts. |
-| `muc send (--to-self \| --peer UID \| --team TEAM_ID) <text> [--yes-not-self]` | Send a plain-text message. **Visible to the recipient.** |
-| `muc send-file <file> [target] [--yes-not-self]` | Upload a file (TCP 6101) and broadcast as `MESSAGE_CHAT_FILE` (subType=7). Returns persistent `fileKey` + `mid`. **Visible.** Uses both 6101 (upload) and 8101 (broadcast) — costs the chosen `--os` slot for the broadcast. |
-| `muc send-image <file> [target] [--width N --height N]` | Same as `send-file` but as `MESSAGE_CHAT_IMAGE` (subType=8). Width/height auto-probed from PNG/JPEG/GIF/BMP headers; pass `--width/--height` to override. |
-| `muc send-voice <file> --duration <ms> [target]` | Same as `send-file` but as `MESSAGE_CHAT_AUDIO` (subType=9). `--duration <ms>` is required (the desktop renders the bubble's clip length from this metadata, not from the file). |
-| `muc withdraw --mid <MID> [target]` | Recall a sent message. Original gets replaced server-side with "您撤回了一条消息". Target flag must match the original message's chat. |
-| `muc clear-session [target]` | Delete a session from your client-side history (syncs to all your devices). **Doesn't delete server-side history** — `history` still returns the messages. |
-| `muc wait-react --mid <MID> [--from-uid UID] [--sticker-id ID] [--timeout 300]` | Block until someone reacts with an emoticon to `--mid`, then exit. Useful as a "human-in-the-loop approval" gate after `muc send`. Exits with `TIMEOUT` (exit 5) if no matching reaction arrives within `--timeout` seconds. |
-| `muc listen [--from-uid UID] [--team TEAM] [--peer UID] [--contains TEXT] [--regex …] [--at-me] [--max N]` | Long-lived TCP tap that emits one **NDJSON line per matching inbound message** (in `--json` mode each line is the standard envelope; in human mode it's a one-line summary). Supports repeatable filters (OR semantics within each kind, AND across kinds), `--at-me` to restrict to group messages where another user @-mentions you (implies excluding self), `--include-self` to include your own sends, `--include-reactions` to also surface type=3 sub=300/301 frames, `--max N` to exit after N matches. Stop with `^C`. |
-`--os` defaults to `iOS`. Valid values: `Windows`, `OS X`, `Mac`, `iOS`,
-`Android`. **`--os` does not provide coexistence — read the section below
-before using any chat-channel command if you have a real device logged in.**
-Sending to anyone other than yourself requires the explicit `--yes-not-self`
-flag — a guard against accidentally messaging real humans during testing.
-**Message tail (signature)**: by default `muc send` appends a short tail to
-the text it sends (e.g. `"\n—— 来自王璐璐的muc-cli"`) so recipients can
-tell automated traffic from a typed message. The check is idempotent —
-if your text already ends with the resolved tail, it is not appended a
-second time. Customise it with the
-`messageTail` field in `~/.muc/config.json` — set to a non-empty string to
-override, or to `""` to disable entirely. You can also use
-`muc init --message-tail "<custom>"` / `muc init --no-message-tail` to
-write the value, and per-call flags `muc send --tail "<one-off>"` /
-`muc send --no-tail` to override on a single send. Only `muc send`
-(plain-text) is affected; `send-file` / `send-image` / `send-voice` are
-not.
+```bash
+muc history --peer WANGWU --days 7 --limit 200
+muc history --team 9009876543210000 --days 30 --json | jq '.data.messages[]'
+muc history --to-self --days 1
+```
+### 发消息
+```bash
+muc send --to-self "hello from CLI"                           # 发给自己（安全测试）
+muc send --peer BOB "明天上午有空吗？" --yes-not-self
+muc send --team 9009876543210000 "值班通知" --yes-not-self
+```
+### 发文件 / 图片 / 语音
+```bash
+muc send-file ./dist/release.dmg --peer QA_LEAD --yes-not-self
+muc send-image ~/Desktop/screenshot.png --to-self              # 自动探测宽高
+muc send-voice ./recording.amr --duration 3500 --to-self       # duration 单位 ms
+```
+### 下载 / 撤回
 ```bash
-muc tcp-ping --wait 8                         # safe protocol smoke test
-muc send "hello from the CLI"                 # to-self (default)
-muc send --peer ZHANG_W2 "ping" --yes-not-self
-muc send --team 9009876543210000 "team message" --yes-not-self
-muc send-file ./report.pdf --to-self                                  # self test
-muc send-image ./screenshot.png --peer ZHANG_W2 --yes-not-self        # auto width/height
-muc send-voice ./clip.amr --duration 3500 --to-self                   # 3.5 s clip
-muc download --file-key /chat/m/WANGLULU8/.../<md5> --out ./got.bin   # by explicit key
-muc download --mid 69ef1ae07e5462c465c05e00 --to-self                 # look up body via roaming
-muc download --mid <MID> --peer YANWENYU --out ./inbox/                # save into a directory
+muc download --mid <mid> --to-self --out ./got.bin   # 通过消息 ID 下载附件
+muc withdraw --mid <mid> --to-self                   # 撤回自己发出的消息
 ```
-`download` is the only file-channel command that **doesn't** open a chat
-session — it speaks only port 6101 (and a one-time bucket lookup on first
-call). Run it from any environment without disturbing your desktop or phone.
+> 任何命令加 `--json` 输出稳定的机器可读信封：成功 `{ok:true, data}` / 失败 `{ok:false, code, msg}`。
+> 退出码：`0` 成功 / `2` 用法错误 / `3` 鉴权 / `4` 未找到 / `5` 远端或网络 / `1` 内部错误。
+---
-## Coexistence
+## 和桌面端 / 手机端共存
-**REST commands always coexist** with a running desktop and phone — the
-server allows concurrent `accessToken`s. `whoami`, `search`, `search-dept`,
-`search-app`, `search-sno`, `history`, `whois`, `groups`, `emoticons`, and
-`download` are REST-only (or 6101-only, in `download`'s case) and safe to
-run anytime.
+REST 命令（`search`、`history`、`whois`、`groups` 等）**永远可以共存**，与桌面端、手机端同时在线互不影响。
-**Chat-channel commands** (`sync`, `search-team`, `send`, `send-file`,
-`send-image`, `send-voice`, `withdraw`, `clear-session`) open a TCP-8101
-session and share a per-user **two-slot** model with real devices:
+聊天通道命令（`send*`、`withdraw`、`sync`、`search-team`、`team-members`）受 MUC **单点登录**规则约束：每个账号在 **PC 端**和**移动端**各只允许**一个**在线设备，同一端登第二个会把第一个挤下线（和"在另一台 Mac 上登 MUC 就把当前这台顶掉"是一回事）。CLI 通过 `--os` 决定自己算哪一端：
-| Slot | `--os` values |
+| 算作哪端 | 对应的 `--os` 取值 |
 |---|---|
-| PC | `Windows`, `"OS X"`, `Mac` |
-| Mobile | `iOS` (default), `Android` |
+| PC 端 | `Windows` / `OS X` / `Mac`（Mac 桌面端登录时上报的是 `OS X`） |
+| 移动端 | `iOS`（CLI 默认）/ `Android` |
-A second login in the same slot kicks the previous client off the realtime
-channel — the IM panel goes offline, but tokens stay valid (reopen to
-recover). The Mac desktop signs in as `"OS X"` (PC slot); the iPhone signs
-in as `iOS` (Mobile slot).
+> ⚠️ **默认发送消息会使移动端下线，谨慎使用。** CLI 默认 `--os iOS`，算"移动端"。
+> 只要跑了 `send` / `withdraw` 等聊天通道命令，**正在登录 MUC 的 iPhone 会被立刻挤下线**
+> （`accessToken` 不失效，但要重新打开 App 才能继续收实时消息）。
+>
+> - 测试或跑通流程时，先用 `muc send --to-self ...` 发给自己。
+> - 真要 `--peer` / `--team` 发出去之前，确认**没人在等 iPhone 上 MUC 的实时消息**。
+> - 如果手机 MUC 必须保持在线，**整段流程改用 REST 命令**（`history`、`search`、`groups`…），别碰聊天通道。
+> - **不要**显式传 `--os Windows / OS X / Mac`——那会把 Mac 桌面端 MUC 也顶下去。
-The CLI defaults to `--os iOS` so it coexists with a Mac desktop. If your
-iPhone is also signed in, both slots are taken and any TCP command will
-kick one of them — fall back to REST-only commands.
+`muc tcp-ping` 只做 TCP 连接和 NEGOTIATE，**不发登录帧**，不占任何在线名额，纯连通性测试，可以随时跑。
-`tcp-ping` only does TCP connect + NEGOTIATE (no `auth/login`), so it can't
-kick anything. Run it first to confirm the wire protocol is happy on your
-network.
+---
-If you do get kicked, reopen the desktop's IM panel or relaunch the mobile
-app to recover — tokens stay valid.
+## 开发者指南
-## Examples
+### 从源码运行
 ```bash
-$ printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
-uid: WANGLULU8
-empId: 5394483846707200
-name: 王璐璐
-accessToken: TV5l…u9kQ (redacted; use --json for raw)
-accessTokenExpireAt: 1745678340000
-tokenPwdRefreshed: true
-tokenPwdExpireAt: 1748097540000
-$ muc whoami
-uid: WANGLULU8
-empId: 5394483846707200
-name: 王璐璐
-deviceId: 8e413b4141…
-deviceName: WANGLULU8-mbp.local (muc-cli)
-accessToken: TV5l…u9kQ (redacted; use --json for raw)
-accessTokenExpireAt: 1745678340000
-tokenPwdSet: true
-tokenPwdExpireAt: 1748097540000
-savedAt: 1745073540000
-credentialsPath: ~/.muc/credentials.json
-$ muc search 张
-ZHANG_W2       张伟      飞行部 / 机长室
-ZHANGSAN03     张三      地面服务部
-…
-$ muc whois ZHANG_W2
-uid        ZHANG_W2
-name       张伟
-empId      4892173049281024
-mobile     1380013…
-email      zhang.wei@ceair.com
-dept       飞行部 / 机长室
-title      机长
-$ muc groups
-starred:
-  [常用] (3)
-    9001234567890123     IT 值班群
-    9001234567890124     运行联络
-    9001234567890125     部门通知
-dept groups: 1
-  9009876543210000     飞行部 / 机长室
-$ muc emoticons
-1001             默认表情包  (32)
-1042             航空主题     (18)
+git clone <repo> everything-cli && cd everything-cli
+pnpm install                       # 工作区依赖装在仓库根
+cd packages/muc
+pnpm run typecheck                 # tsc --noEmit，必须先过
+./bin/muc <command>                # 直接走 tsx 跑 src/，零构建
 ```
-## Files & paths
-| Path | Purpose | Mode |
-|---|---|---|
-| `~/.muc/config.json` | tenant config: APP_KEY, APP_ID, signing secrets, hosts/ports | 600 |
-| `~/.muc/credentials.json` | accessToken, tokenPwd, profile | 600 |
-| `~/.muc/device-id` | stable per-CLI deviceId (sha256 hex) | 600 |
-Both files share the `~/.muc/` parent (mode 700). The CLI creates them on
-first use; you should never need to edit them by hand.
-## Changelog
-#### `0.3.0`
-`2026.04.29`
-- Add `muc react` / `muc unreact` / `muc reactions` to add, revoke, and list emoticon reactions on existing messages
-- Add `muc wait-react` to block until a human reacts to a given mid; useful as a "human-in-the-loop approval" gate after `muc send`
-- Add `muc listen`, a long-lived TCP tap with sender / chat / keyword / `--at-me` filters, one NDJSON line per match
-- Exit code `5` now also covers `TIMEOUT` and `KICKED`
-#### `0.2.2`
-`2026.04.28`
-- `muc send` plain-text now appends an idempotent signature tail by default; override via `--tail` / `--no-tail`, `muc init --message-tail`, or `messageTail` in `~/.muc/config.json`
-#### `0.2.1`
-`2026.04.28`
-- Skills unified across macOS / Linux / Windows
-- On Windows, file mode `600` is silently ignored — use NTFS ACLs on shared hosts to protect `~/.muc/`
-#### `0.2.0`
-`2026.04.27`
-- Add `muc init`: extract `appKey` / `appId` / signing secrets out of source code, write to `~/.muc/config.json` (mode 600)
-- Companion subcommands: `muc init --check` / `--show` / `--reset`
-- License changed to MIT; package published to npm with public access
-## What it can't do (yet)
-- **Richtext messages** (`subType=11`, mixed text + image + @-mention in one
-  bubble). The image segments share the file-channel upload path so the
-  bulk of the work is already there; just needs a body-builder + a
-  `send-rich` command.
-- **Forwarded / merged messages** (`subType=26`).
-- **SSO / scan-to-login.** REST username+password works; the SSO flow is
-  not wired up.
-- **Image thumbnails.** The upload step asks the server to make `tn1`/`tn5`
-  thumbs, but `muc download` only fetches the original `fileKey`.
-- **End-to-end-encrypted file content.** Not active on the default tenant
-  and the CLI doesn't implement it.
-## Troubleshooting
-- `code: CONFIG_MISSING` (exit 6) — `~/.muc/config.json` is absent. Run
-  `muc init` to create it. The CLI cannot guess your tenant's signing
-  secrets.
-- `code: CONFIG_INVALID` (exit 7) — the file exists but failed schema
-  validation (corruption, manual edit gone wrong, or a stale schema after
-  upgrade). Run `muc init` to repair it; `--reset --yes` to start clean.
-- `login failed: code=…` — sign or DES is wrong. Double-check the signing
-  secrets and `appKey` / `appId` you supplied to `muc init` against the
-  values your MUC admin provided. `muc init --show` (secrets redacted) lets
-  you confirm what's currently saved; `muc init` (interactive) lets you
-  re-enter the values.
-- `error: not logged in` (exit 3, code `AUTH_REQUIRED`) — the saved
-  credentials file is missing or unreadable. Check `~/.muc/credentials.json`
-  and re-run `muc login`.
-- `code: AUTH_EXPIRED` (exit 3) — accessToken or tokenPwd was rejected by
-  the server. Re-run `muc login --token-pwd` (or full `muc login` if
-  `tokenPwd` is also stale).
-- `EPROTO` / TLS errors — corporate proxy or VPN intercepting traffic.
-  `muc-cli` does not pin certificates, so adding the proxy CA to your Node
-  trust store should suffice (`NODE_EXTRA_CA_CERTS=/path/to/ca.pem`).
-- A TCP send kicks your desktop off the IM panel — the CLI's `--os` value
-  collided with the desktop's slot. See [Coexistence](#coexistence) above:
-  default `--os iOS` only risks the Mobile slot (your iPhone), not the
-  desktop. If both desktop and phone are online, drop to REST-only
-  commands.
-### Exit-code summary
-| Exit | Code |
-|---|---|
-| 0 | success |
-| 1 | INTERNAL |
-| 2 | USAGE |
-| 3 | AUTH_REQUIRED, AUTH_EXPIRED |
-| 4 | NOT_FOUND |
-| 5 | REMOTE_ERROR, NETWORK, TIMEOUT, KICKED |
-| 6 | CONFIG_MISSING |
-| 7 | CONFIG_INVALID |
-## Security
-- Both files in `~/.muc/` are written with mode `600`. **Don't** check them
-  into git or copy them to shared machines.
-- **Don't share `~/.muc/config.json`** — it contains your tenant's signing
-  secrets (`signSecretRest`, `signSecretSecure`, `pwdDesKey`, `appKey`).
-  Anyone with these can impersonate API calls against your MUC tenant.
-- `MUC_PASSWORD` ends up in shell history; prefer `--password-stdin` or
-  `--token-pwd` for refreshes.
-- **Prefer interactive `muc init` over env vars.** Environment variables
-  leak through shell history and `/proc/<pid>/environ` to other processes
-  on the same machine. Use the interactive prompt or one-shot flags pulled
-  from a secret manager rather than persistent `MUC_*` exports.
-- TCP login over 8101 registers a device session in one of two slots per
-  user (PC or Mobile). A second login in the same slot kicks the first.
-  Default `--os iOS` keeps the CLI on the Mobile slot; only your iPhone is
-  ever at risk.
-- `tcp-ping` is the only chat-channel command that cannot kick anything —
-  use it as a network smoke-test before trying TCP sends.
+### 仓库结构
+```
+packages/muc/                  （everything-cli 工作区中的一个包）
+├── src/index.ts                命令分发器
+├── src/commands/*.ts           每个子命令一个文件
+├── src/lib/                    协议层：wire.ts / chat.ts / sign.ts / …
+├── src/assistant/              auto-reply 守护进程 + 各 backend
+├── skills/                     muc-* Agent Skills（muc-message / muc-chat / muc-shared / …）
+├── scripts/build.mjs           esbuild 打包脚本（→ dist/muc.mjs）
+├── bin/muc                     tsx 入口（零构建直接跑 src/）
+├── README.md                   本文件
+└── REFERENCE.md                完整命令 / 协议参考
+```
+> 协议研究文档与抓包脚本保留在内部源码研究仓库，未随本包导入；下文"协议抓包 /
+> 改动后测试 / 协议层参考"小节中对它们的引用均指内部仓库。
+### 协议抓包：通过 Surge.app
+不用切系统代理、不用安装额外 CA —— Surge.app 已在本机运行即可。
+**一次性配置**：在 Surge UI 里把你的 MUC 主机（如 `*.example.com`）加进 MITM hostname，打开 MITM + Capture + HTTP API。
+```bash
+# 抓 60 秒的 muc HTTP/S 流量，输出 NDJSON
+python3 surge_capture.py --key <surge-http-api-key> --process MUC --duration 60 > flows.ndjson
+# 聚合成 API 地图（人读）
+python3 analyze_api.py flows.ndjson
+# 机器读
+python3 analyze_api.py flows.ndjson --json
+# 只看某个主机
+python3 analyze_api.py flows.ndjson --host muc.example.com
+```
+> 如果 Surge 配置了 `http-api-tls = true`，用 `https://127.0.0.1:6171` + 关闭 SSL 验证访问，或直接去掉该配置项。
+### 改动后测试流程
+1. `pnpm run typecheck`（在 `packages/muc` 下）— 先过类型检查。
+2. 按内部 `TEST_CASES.md` 从头到尾跑一遍（§1 REST 读 + §2 `tcp-ping` 无条件跑；Mac 桌面 + iPhone 同时在线时跳过 §3 §4）。
+3. 任何一项失败：把 `--json` 原始信封贴给用户，停下来，不要"修一修再跑"。
+### 协议层参考（内部文档）
+- `HANDOFF.md` — 当前状态、已验证里程碑、常量（hosts / 密钥 / transport AES key）、关键算法的踩坑笔记。
+- `MUC_API.md` — REST 端点全图（`/muc /imm /msm /contacts /mam /...`）+ TCP 8101 帧规范 + 6101 文件通道。
+- `API_CLIENT.md` — 从解包客户端摘出的全量 API 目录，找 CLI 还没封装的端点去这里翻。
+### 红线
+- **绝不入库** `accessToken`、`tokenPwd`、明文密码、`clientSecret`、`pfxPass`、`bsSecretKey`、`encrypt_key`，以及租户密钥（`APP_KEY` / `sign secrets`）。
+- **CLI 默认会顶掉同账号的 iPhone 端 MUC**（默认 `--os iOS`，单点登录规则）；显式传 PC 类 `--os` 会顶 Mac 桌面端；桌面 + 手机都需要保持在线时，整段流程退到 REST 命令。
+- **CLI 发的消息所有参与方都可见。** 非自身目标必须带 `--yes-not-self`，先用 `--to-self` 测。
+- **不要擅自改 Surge 配置文件**（`~/Library/Application Support/Surge/Profiles/*.conf`）。要加 MITM hostname 让用户在 Surge UI 里加。