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` 覆盖
2.8 KiB
2.8 KiB
开发说明
这页面向仓库维护者和贡献者，记录源码结构、常用本地命令和打包边界。
仓库结构
本仓库为 Cargo workspace，Rust 核心拆为三个 crate：
| 路径 | 说明 |
|---|---|
crates/wecom/ |
核心库（lib）：Client/ClientBuilder、discovery 服务发现与缓存、schema 指令（x-wecom-*）、builtins（媒体上传/下载）、HelperRegistry、端点目录（EndpointKey/EndpointCatalog）、网关扁平信封（PayloadStringReq/NestedRes） |
crates/wecom-cli/ |
二进制（bin）：main.rs 组装 Client 并 run；auth 鉴权体系（bot 凭据/扫码/签名引导/凭据加密）；WecomBackend（按 need_auth 动态注入 Bearer token + 853004 静默刷新）；config/env/logging；auth 命令经扩展命令点挂载 |
crates/wecom-transport/ |
传输层：TransportBackend trait、reqwest HTTP 后端、长任务轮询、请求/响应信封 trait（RequestEnvelope/ResponseEnvelope）、端点目录泛型机制（EndpointCatalog<K>/CatalogKey） |
bin/wecom.js |
npm 入口脚本，负责定位并执行当前平台的二进制 |
packages/* |
各平台的 npm 二进制包 |
skills/* |
Agent Skills 及其补充参考资料 |
docs/ |
持续维护的使用与开发文档 |
README.md |
项目首页 |
调用链路（lib 内）：
请求前: collect_directives → process_media_upload / multipart（x-wecom-* 指令）
调用: transport.invoke（Envelope 双轴解析 + taskid 触发 poll_long_task 轮询）
响应后: collect_directives → process_file_save → 输出路由
本地开发
仓库的 Rust crate 使用 edition = "2024"，开发时建议使用较新的 stable Rust 工具链。
常用命令：
# 全量检查 / 测试 / lint
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
# 构建并运行
cargo run -p wecom-cli -- --help
端到端测试
各 crate 的 e2e 套件统一放在各自 <crate>/test-e2e/ 下（run.rs 编译入口 + helpers/ + cases/<group>/<NNN>-<slug>/{desc.md,test.rs}），规范与生成手册见 e2e/：
# library-level 套件（crates/wecom）
cargo test -p wecom --test e2e
# process-level 套件（crates/wecom-cli，需 custom-endpoint feature）
cargo test -p wecom-cli --test e2e --features custom-endpoint
说明：
- 根包名为
@wecom/cli，实际可执行入口是bin/wecom.js。 - 平台二进制通过
optionalDependencies分发，位于packages/*。 pnpm-workspace.yaml当前只管理packages/*工作区。- 扩展命令（如
auth）经ClientBuilder::command()挂载，无需改动main.rs与 lib 调度层；产品 helper 经ClientBuilder::helper()注册。