wms-cli

微秘书 (WMS) 平台命令行工具，专为 AI Agent（Claude Code / OpenClaw / Hermes / Codex）与人工运维双场景设计。

📖 完整使用指南（推荐新手）：GUIDE.md — 含准备工作、apiKey 获取、安装、8 个使用案例、AI Agent 接入、常见问题

📝 版本变更：CHANGELOG.md

安装

npm i -g @aibotk/wms-cli

在 AI Agent 平台启用

wms-cli 自带一份 SKILL（skill/SKILL.md + skill/references/*.md），让 AI Agent 能自动调用本 CLI。一行命令装到平台：

wms install-skill --platform all              # 装到所有检测到的平台
wms install-skill --platform claude           # 或只装到某一个
wms install-skill --platform claude --json    # 脚本友好输出

该命令把 skill/ 拷贝到各平台的 skills 目录；目录不存在的平台会被静默跳过。

| 平台 | 装到 | 如何让它生效 | |---|---|---| | Claude Code | ~/.claude/skills/wms/ | 新一轮对话自动加载（新版本无需重启）。触发：自然语言「用 wms 找好友 张三」或描述任务即可，Claude 根据 SKILL 的 description 自动匹配 | | Codex（OpenAI Codex CLI） | ~/.codex/skills/wms/ | 重启 codex CLI 会话。Codex 在启动时扫描 skills 目录 | | OpenClaw | ~/.openclaw/skills/wms/ | 重启 OpenClaw 会话 | | Hermes | ~/.hermes/skills/wms/ | 重启 Hermes 会话 |

验证 skill 已加载（以 Claude Code 为例）：

在新会话里问 Claude「你装了哪些 skill？」或「列一下你能用的 skill」，回答里应该包含：

wms: 微秘书 (WMS) CLI 工具。查询微信好友/群，按关键词模糊搜索...

或者直接给任务 ——「用 wms 找一下我的好友张三，给她发『你好』」—— Agent 会自动跑：

wms contact list --keyword 张三 --json    # 拿 wxid
wms send contact --to <wxid> --text "你好" --json

注意 bins 约束：SKILL 的 frontmatter 声明 requires.bins: ["wms"]，遵守这一字段的平台会先检查 wms 命令是否在 $PATH，所以必须先全局装 @aibotk/wms-cli，再装 skill。

快速开始

wms auth token <你的 apiKey>                         # 默认 https://api-bot.aibotk.com
wms auth whoami --json                                # 验证
wms contact list --keyword "张三" --json
wms send contact --to wxid_xxx --text "你好" --json

功能场景速查

| 场景 | 命令 | |---|---| | 查机器人信息 | wms auth whoami --json | | 查好友（关键词模糊） | wms contact list --keyword "张三" --json | | 查好友详情（按 wxid） | wms contact get --wxid <wxid> --json | | 查群（关键词模糊） | wms room list --keyword "运营" --json | | 查群详情 | wms room get --wxid <roomId> --json | | 给好友发文字 | wms send contact --to <wxid> --text "..." --json | | 给好友发图片 | wms send contact --to <wxid> --image <url> --json | | 给好友发卡片 | wms send contact --to <wxid> --card-url <u> --card-title <t> --card-desc <d> --card-thumb <th> --json | | 给群发消息 | wms send room --to <roomId> --text "..." --json | | 设群公告（@所有人） | wms send multi --target roomnotice --groups <roomId> --text "..." --json | | 批量多目标多消息 | wms send multi --target room --groups r1,r2 --messages-json '[...]' --json |

群公告说明：调用 /chat/multi 接口，target=roomnotice，messages 仅支持 type=1（文字）。机器人需为群主或管理员才能成功发送。

命令清单

| 命令 | 作用 | |---|---| | wms auth token <key> / logout / whoami | 凭证管理 | | wms auth list / wms auth use <name> | 多 profile 切换 | | wms contact list/get | 好友查询 | | wms room list/get | 群查询 | | wms send contact/room/multi | 发送消息 | | wms spec | 输出 OpenAPI YAML | | wms install-skill --platform <p> | 安装 SKILL 到 AI Agent 平台 |

完整 Agent 指南：skill/SKILL.md

多 apiKey / 多账号

支持任意多个 profile（每个 profile 一个 apiKey + host）。

# 同时配置两个账号
wms auth token <dev-key>  --profile-name dev
wms auth token <prod-key> --profile-name prod --host https://prod.example.com

# 查看所有 profile（apiKey 自动遮罩；✓ 标默认）
wms auth list
wms auth list --json

# 切换默认 profile（之后命令不用再带 --profile）
wms auth use prod
wms contact list --keyword "张三" --json     # 走 prod

# 单条命令临时切换，不影响默认
wms --profile dev contact list --keyword "张三" --json

# 删除某个 profile（删默认时自动指向剩余其一）
wms auth logout --profile-name dev

也支持环境变量临时覆盖，优先级 flag > 环境变量 > 配置文件：

WMS_API_KEY=<key> WMS_HOST=https://x.com wms contact list --json

全局选项

• --json AI Agent 必加
• --dry-run 打印请求不发送
• --profile <name> 多环境
• --host <url> 覆盖 baseURL
• --debug 打印请求/响应

退出码

| 码 | 含义 | |---|---| | 0 | 成功 | | 1 | api / validation | | 2 | auth | | 3 | network | | 4 | timeout | | 5 | vip_required |

开发

pnpm install
npm test               # 全部测试
npm run test:e2e       # 仅 e2e