mirror of
https://github.com/WecomTeam/wecom-cli.git
synced 2026-09-14 18:23:19 +08:00
jasonhzhang
1f0e0b8fb4
- feat(service): discovery schema 新增 remote_doc（service/resource/method 就近覆盖），命中节点的 --doc/--help/--schema 改由远程端点渲染，未命中 回退本地渲染 - feat(service): ServiceInfo.alias 注册为 clap hidden alias，matches 归一化 为规范名；经别名调用时上报 method_alias 遥测，命名冲突 warn 并跳过 - refactor(transport): 请求载荷重构为可重放的 HttpRequestPayload 延迟工厂 （JSON Arc 零拷贝重放，multipart 每次重建表单重开文件），853004 重放 不再限于 JSON；信封包装收敛到 pipeline 入口单一组合点 - refactor(auth): AuthRequirement 拆分为 RequireAuth（前置门禁）与 SuppressAuth（抑制注入）双标记；鉴权引导端点预装配为 Endpoint 实例， 在凭据迁移与 853004 刷新间共享 - fix(error): wecom 层错误经 transport Other 边界往返时 downcast 还原 原始变体，保留 code/type 结构化渲染
62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 开发说明
|
||
|
||
这页面向仓库维护者和贡献者，记录源码结构、常用本地命令和打包边界。
|
||
|
||
## 仓库结构
|
||
|
||
本仓库为 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`（持有 token 即注入 Bearer token、`RequireAuth` 前置门禁 + 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 工具链。
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
# 全量检查 / 测试 / 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/`](e2e/FRAMEWORK.md)：
|
||
|
||
```bash
|
||
# 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()` 注册。
|