@mu-cabin/muc-cli 0.3.1 → 0.5.0

package/README.md

@@ -1,471 +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` resolves as **per-call `--os` → `defaultChatOs` in `~/.muc/config.json`
-→ built-in `iOS`**. Valid values: `Windows`, `OS X`, `Mac`, `iOS`, `Android`.
-Set the per-machine default once with `muc init --default-os <os>` (or the
-`MUC_DEFAULT_OS` env var, or the interactive prompt during `muc init`). Useful
-if your real device is an iPhone — flip the CLI default to `windows` so
-chat-channel commands park on the PC slot instead of kicking your phone.
-**`--os` / `defaultChatOs` 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, or run
-`muc init --default-os windows` to flip the per-machine default to the PC
-slot (which kicks the desktop instead of the phone).
+`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.1`
-`2026.04.29`
-- Add `defaultChatOs` to `~/.muc/config.json`: per-machine fallback for the chat-channel `--os` slot. Configure via `muc init --default-os <windows|osx|mac|ios|android>`, the `MUC_DEFAULT_OS` env var, or the interactive prompt during `muc init`. Resolution order: per-call `--os` → `defaultChatOs` → built-in `iOS`. Use this when your real device is on the Mobile slot (e.g. iPhone) so chat-channel commands park on PC instead of kicking your phone.
-
-#### `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 里加。