mirror of
https://github.com/WecomTeam/wecom-cli.git
synced 2026-09-14 18:23:19 +08:00
jasonhzhang
b2dfa0f1cc
架构： - 单 crate 拆分为 Cargo workspace，按职责分为三个 crate - wecom：argv 调度、服务发现、schema 命令树、指令处理、沙箱 FS - wecom-cli：入口装配、鉴权、配置与日志 - wecom-transport：传输后端、信封、端点目录、长任务轮询 命令模型： - 调用格式改为 `<service> [resource...] <method> [flags]` - 服务目录与方法 schema 由服务端下发并本地缓存 - 请求体支持 schema 命名参数、`--json`、`--set` 三种组合方式 - 新增 `--doc` / `--schema` / `--dry-run` 文档、预览与调试能力 - 新增 `--page-count` 自动分页与 `--output` / `--output-dir` 落盘 - 新增 `+` 前缀本地 helper 与内建 `schema`、`cache` 命令 鉴权： - 命令收敛为 `auth init` / `auth show`，扫码为默认接入方式 - 凭据统一存放于 credentials.enc（AES-256-GCM，0600） - 密钥优先使用系统 keyring，不可用时回退本地密钥文件 - token 失效时静默换取新 token 并重放一次请求 - 旧版凭据文件在启动时自动迁移 输出与约定： - 错误以结构化 JSON 输出到 stdout，日志与提示一律走 stderr - 明确退出码 0 成功、1 运行时错误、2 用法错误 - `--version` 输出携带发行渠道、构建时间与 commit id - 新增按天滚动的 JSON Lines 日志目录与额外请求头注入 - 新增可选配置文件 config.json，环境变量优先级高于配置文件 - `--json` / `--set` 中的非法 JSON 自动修复并输出前后对照 - 文件落盘由 schema 指令与响应类型决定，默认写入临时目录 能力与 Skills： - 新增邮件、在线表格、智能文档、微盘、媒体等服务品类 - 文档能力增强：搜索、重命名、成员权限与加入规则管理 - 内置 Skills 扩充至 14 个，改为按需引用的分层结构 工程： - 引入 lefthook 管理 Git 钩子，pnpm 升级至 11 - 补齐 library-level 与 process-level 双层 e2e 框架 - 重写开发说明与 CLI 命令参考文档 BREAKING CHANGE: - 调用格式由 `<category> <method> '<json>'` 改为服务/资源/方法路径 - 接口名与参数整体更名，脚本需按 `--help` / `--doc` 逐个核对迁移 - 品类标识调整：`msg` → `message`，`schedule` → `calendar` - `wecom-cli init` 移除，改用 `wecom-cli auth init` - `auth show --auth-status` 改为 `auth show --status` - 错误输出由 stderr 文本改为 stdout 结构化 JSON - `WECOM_CLI_LOG_FILE` 移除，改用 `WECOM_CLI_LOG_DIR`（传目录） - 移除 MCP 传输后端与 JSON-RPC 模式 - 移除 service_base_url_override、access_token 等废弃配置 - 落盘规则改变：由 schema 指令与响应类型决定，可用 `--output` 覆盖
194 lines
7.4 KiB
Markdown
194 lines
7.4 KiB
Markdown
# CLI 命令参考
|
||
|
||
本文档描述 `wecom-cli` 的命令模型、参数约定、运行时路径、环境变量与错误格式。
|
||
|
||
## 命令模型
|
||
|
||
`wecom-cli` 的命令分为四类：
|
||
|
||
| 形态 | 说明 |
|
||
| --- | --- |
|
||
| `wecom-cli <service> [resource...] <method> [flags]` | 调用远程服务方法。`service` 由服务端 discovery 动态下发，方法可能带嵌套资源路径（如 `message aibot sessions list`） |
|
||
| `wecom-cli <service> +<helper> [flags]` | 本地 helper（`+` 前缀），由产品层注册 |
|
||
| `wecom-cli auth <init\|show>` | 授权管理（内建扩展命令） |
|
||
| `wecom-cli schema ...` / `wecom-cli cache ...` | 内建命令（隐藏在 `--help` 之外，见下文） |
|
||
|
||
说明：
|
||
|
||
- 服务目录与工具 schema 均在线获取，因此查看帮助与调用工具需要凭证与网络。
|
||
- 可用的 `service` 列表以 `wecom-cli --help` 实际输出为准。常见品类：`message`（消息）、`mail`（邮件）、`doc`（在线文档/文档管理）、`sheet`（在线表格）、`smartsheet`（智能表格）、`smartpage`（智能文档）、`calendar`（日程）、`meeting`（会议）、`todo`（待办）、`disk`（微盘）、`contact`（通讯录）、`media`（媒体文件）、`identity`（身份）。
|
||
|
||
## 配置凭证 `auth`
|
||
|
||
交互式配置企业微信机器人凭证，加密存储到本地（见「运行时路径」）。仅需执行一次：
|
||
|
||
```bash
|
||
# 配置凭证（交互式选择接入方式；非交互环境自动使用扫码接入）
|
||
wecom-cli auth init
|
||
|
||
# 查看授权状态
|
||
wecom-cli auth show
|
||
```
|
||
|
||
支持两种接入方式：
|
||
|
||
- **扫码接入（推荐）**：终端展示二维码，使用企业微信扫码创建绑定；扫码等待超时为 5 分钟
|
||
- **手动接入**：输入 Bot ID 和 Secret，获取方式[参考](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21677)
|
||
|
||
### `auth init` 参数
|
||
|
||
| 参数 | 说明 |
|
||
| --- | --- |
|
||
| `--noninteractive` | 跳过交互选择，直接使用扫码接入（CI/脚本/管道等非交互环境适用） |
|
||
| `--no-browser` | 扫码时不自动打开浏览器 |
|
||
| `--output-qrcode <PATH>` | 将二维码输出为 PNG 文件（仅支持当前目录下的路径，如 `qr.png`） |
|
||
| `--manual` | 跳过交互选择，手动输入 Bot ID 和 Secret（需要终端） |
|
||
|
||
### `auth show` 参数
|
||
|
||
默认输出人类可读的 `Status` 与 `Bot ID`。
|
||
|
||
| 参数 | 说明 |
|
||
| --- | --- |
|
||
| `--status` | 仅输出 `authorized` / `unauthorized` 单行，便于脚本判断 |
|
||
|
||
## 查看帮助 `--help`
|
||
|
||
支持获取各级命令的使用方式：
|
||
|
||
```bash
|
||
# 列出所有支持的命令和品类
|
||
wecom-cli --help
|
||
|
||
# 列出指定品类下的所有工具
|
||
wecom-cli <service> --help
|
||
|
||
# 列出指定工具所需的输入
|
||
wecom-cli <service> [resource...] <method> --help
|
||
```
|
||
|
||
此外，每个服务与方法都支持文档 flag：
|
||
|
||
- `wecom-cli <service> --schema` / `--doc`：输出服务 schema / 文档
|
||
- `wecom-cli <service> <method> --schema` / `--doc`：输出方法 schema / 文档（含 TS 类型声明）
|
||
|
||
`--version` 输出格式：`wecom-cli <version> (<distribution> <RFC 3339 构建时间> <git_commit_id>)`。
|
||
|
||
## 调用工具
|
||
|
||
通用格式：
|
||
|
||
```bash
|
||
wecom-cli <service> [resource...] <method> [--param value ...] [--json '<JSON>'] [flags]
|
||
```
|
||
|
||
请求体有三种给出方式，可组合：
|
||
|
||
| 方式 | 说明 |
|
||
| --- | --- |
|
||
| 命名参数 | 由方法 schema 生成的 clap 参数（如 `--id root`），类型与必填性以 `--help` 为准 |
|
||
| `--json '<JSON>'` | 直接给定完整请求体 JSON 字符串 |
|
||
| `--set path=value` | 深层路径覆盖，可重复（如 `--set extra.flag=true`）；非法 JSON 片段会自动修复 |
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 无参方法（含嵌套资源路径）
|
||
wecom-cli message aibot sessions list
|
||
|
||
# --json 给定请求体
|
||
wecom-cli doc search --json '{"keywords":["周报"],"limit":10}'
|
||
```
|
||
|
||
执行相关 flag（所有方法通用）：
|
||
|
||
| Flag | 说明 |
|
||
| --- | --- |
|
||
| `--dry-run` | 仅在本地校验并打印将发送的请求，不实际调用 |
|
||
| `--page-count <n>` | 启用游标式自动分页，最多拉取 n 页；输出为 NDJSON（每行一页） |
|
||
| `--page-delay <ms>` | 分页请求间隔毫秒数，默认 100 |
|
||
| `--output` / `-o <file>` | 将响应体写入文件 |
|
||
| `--output-dir <dir>` | 将响应与附件写入目录（分页时生成 `<method>.ndjson`） |
|
||
|
||
输出形态：
|
||
|
||
- 默认：compact JSON 输出到 stdout
|
||
- 写文件/下载：stdout 输出 `DownloadResult` JSON（含 `content_type`、`file_path`、`size`），文件以 `0600` 权限落盘
|
||
- 分页：NDJSON 多行输出
|
||
|
||
## 内建命令
|
||
|
||
以下命令隐藏在 `--help` 之外，面向调试与集成场景：
|
||
|
||
```bash
|
||
wecom-cli schema list # 列出所有服务及方法 schema
|
||
wecom-cli schema get <service.resource.method> # 获取指定方法 schema（点分隔路径）
|
||
wecom-cli cache status # 查看 discovery 缓存状态
|
||
wecom-cli cache clear # 清除所有 discovery 缓存
|
||
```
|
||
|
||
## 运行时路径
|
||
|
||
| 项目 | 默认位置 | 备注 |
|
||
| --- | --- | --- |
|
||
| 配置目录 | `~/.config/wecom` | 可由 `WECOM_CLI_CONFIG_DIR` 覆盖 |
|
||
| 凭据文件 | `<config_dir>/credentials.enc` | `auth init` 时创建；AES-256-GCM 加密（0600），bot 信息与 token 共存于同一文件 |
|
||
| 加密密钥 | 系统 keyring 或 `<config_dir>/.encryption_key` | 无系统 keyring 时的文件回退（0600） |
|
||
| discovery 缓存 | `<config_dir>/cache` | 服务目录与 schema 缓存，TTL 60 秒 |
|
||
| 临时目录 | `<system_tmp>/wecom` | 媒体下载、请求暂存等；可由 `WECOM_CLI_TMP_DIR` 或 `config.json` 的 `tmp_dir` 覆盖 |
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 作用 |
|
||
| --- | --- |
|
||
| `WECOM_CLI_CONFIG_DIR` | 覆盖默认配置目录 |
|
||
| `WECOM_CLI_TMP_DIR` | 覆盖临时目录根目录 |
|
||
| `WECOM_CLI_ADDITIONAL_HEADERS` | 额外请求头，值为 JSON object（`Record<string, string>`）；同时支持 `WECOM_CLI_ADDITIONAL_HEADERS_*` 后缀形式的多个变量，取值同为 JSON object |
|
||
| `WECOM_CLI_LOG_LEVEL` | 打开 stderr 文本日志并设置过滤级别（如 `debug`、`wecom=trace`；非法值回退 `warn`） |
|
||
| `WECOM_CLI_LOG_DIR` | 打开 JSON Lines 日志输出，按天写入 `<dir>/ww.log.<日期>`（UTC+8） |
|
||
|
||
## 配置文件 `config.json`
|
||
|
||
存放于 `<config_dir>/config.json`，全部字段可选：
|
||
|
||
```json
|
||
{
|
||
"headers": { "X-Custom": "value" },
|
||
"tmp_dir": "/tmp/wecom-custom"
|
||
}
|
||
```
|
||
|
||
| 字段 | 作用 |
|
||
| --- | --- |
|
||
| `headers` | 额外请求头（别名 `additional_headers`） |
|
||
| `tmp_dir` | 覆盖临时目录根目录 |
|
||
|
||
说明：
|
||
|
||
- 环境变量优先级高于配置文件。
|
||
- access token 不允许经 `config.json` 配置，仅来自 `credentials.enc`。
|
||
|
||
## 退出码与错误格式
|
||
|
||
| 退出码 | 含义 |
|
||
| --- | --- |
|
||
| `0` | 成功（含 `--help` / `--version`） |
|
||
| `1` | 运行时错误（网络、鉴权、IO、后台业务错误等） |
|
||
| `2` | 用法错误（参数缺失、未知命令等；后台返回用法类错误码时也会渲染当前命令 help） |
|
||
|
||
错误以结构化 JSON 输出到 stdout：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"type": "AuthError",
|
||
"code": 893201,
|
||
"message": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
- CLI 自身错误的 `code` 段：`893000–893099`（lib）、`893100–893199`（transport）、`893200–893299`（bin），`893999` 为共享兜底码。
|
||
- 后台业务错误（`errcode != 0`）直接透传后台响应体与原 `errcode`。
|
||
- 日志与提示信息一律走 stderr，不污染 stdout 的 JSON 输出。
|