wecom-cli输出与下载实战：--output、--output-dir与NDJSON分页的完整规则

wecom-cli输出与下载实战--output、--output-dir与NDJSON分页的完整规则【免费下载链接】wecom-cli企业微信开放平台命令行工具 — 让人类和 AI Agent 都能在终端中操作企业微信项目地址: https://gitcode.com/gh_mirrors/we/wecom-cliwecom-cli 是企业微信开放平台的命令行工具让人类和 AI Agent 都能在终端里操作消息、邮件、文档、微盘等业务。真正上手后最常被问到的其实是输出问题结果去了哪里文件落在哪个目录分页数据怎么接 本文用一份实战规则一次讲清--output、--output-dir与 NDJSON 分页三件套的行为边界帮你在脚本和 Agent 集成中精准拿到每一份结果。先搞懂三种输出形态wecom-cli 的命令形如wecom-cli service [resource...] method [flags]执行后输出分为四种形态先建立全局认知输出形态触发方式结果去向默认 JSON不加任何输出参数compact JSON 写入 stdout文件落盘--output/-o file响应体写入指定文件下载文件下载类方法 --output-dir dir文件落盘stdout 输出DownloadResultJSON分页 NDJSON--page-count nstdout 逐行输出每行一页 JSON完整参数表可参考官方文档docs/cli-reference.md。默认输出compact JSON 直接进 stdout不加任何参数时响应体以 compact JSON 打到 stdout这是为管道和 Agent 消费设计的默认行为wecom-cli message aibot sessions list三条约定值得记住stdout 只放数据日志与提示信息一律走 stderr不会污染你的 JSON 管道退出码0成功1运行时错误2用法错误错误也是 JSON失败时 stdout 输出结构化的{error: {...}}脚本可直接解析。--output把任意响应写入文件的唯一通道--output简写-o可以配合任意方法使用把响应体直接写入指定文件wecom-cli doc search --json {keywords:[周报],limit:10} --output result.json两个关键规则JSON 响应落盘只能走--output或 shell 重定向--output-dir对纯 JSON 响应不产生任何文件——它是为下载场景准备的写文件后 stdout 会输出一个DownloadResult摘要 JSON包含content_type、file_path、size方便脚本确认结果。这条JSON 响应 --output的组合被完整覆盖在测试用例中crates/wecom/test-e2e/cases/output/001-file/desc.md。--output-dir下载目录的三条硬规则--output-dir dir指定下载类方法文件的落盘目录默认是当前工作目录。它的行为有三条硬规则规则一只对产出文件的方法生效纯 JSON 方法带上--output-dir调用照常成功但目录下不会多出一个文件——语义对齐 curl 的--output-dir仅在产文件时生效。相关验证见 crates/wecom/test-e2e/cases/output/002-output-dir-non-download/desc.md。规则二目录形状会先被校验指向已存在的普通文件→ 直接报无效目录路径错误请求根本不发出指向多级不存在的目录如a/b/c→ 自动逐层创建文件正常落盘指向沙箱 roots 之外的路径→ 报目标路径超出可访问范围。校验逻辑位于 crates/wecom-fs/src/sandbox/mod.rs行为细节见 crates/wecom/test-e2e/cases/output/005-output-dir-shapes/desc.md。规则三dry-run 与真实执行同一道门--dry-run --output-dir dir时会先做同样的沙箱校验但不实际创建目录——预览和落盘共用一个门禁错误时机完全一致。门禁位置可在 crates/wecom/src/service/handler.rs 中查看。下载类方法文件 DownloadResult 双输出下载类方法如微盘文件下载的行为是双输出文件以Content-Disposition中的文件名落盘自动做安全清洗权限为0600stdout 输出DownloadResultJSON含content_type、file_path、size供脚本做后续处理。# 下载到指定目录文件名来自服务端响应头 wecom-cli disk files download --id file_id --output-dir ./downloads二进制分支的落盘实现在 crates/wecom/src/service/output.rs完整行为见 crates/wecom/test-e2e/cases/output/003-binary/desc.md。NDJSON 分页--page-count 的完整行为面对拉取全部数据场景用--page-count启用游标式自动分页wecom-cli hr dept list --page-count 3 --page-delay 100参数说明--page-count n最多拉取 n 页输出为 NDJSON每行一页独立合法 JSON--page-delay ms分页请求间隔毫秒数默认 100终止条件只有两个满足其一即停服务端返回has_more: false数据取完达到--page-count上限即使服务端还有数据。NDJSON 格式对脚本极其友好——while read或jq -c都能逐行消费无需等待全部数据到位。分页逻辑与游标提取在 crates/wecom/src/service/execute.rs两种终止条件的用例分别见 分页全量拉取 与 上限截断。输出与分页的组合--output 接住 NDJSON--output与--page-count可以叠加NDJSON 多行结果会整体写入--output指定的文件而不是刷屏到 stdout。适合先落盘、后离线分析的批处理流程# 分页拉取 10 页逐行 JSON 写入 pages.ndjson wecom-cli hr dept list --page-count 10 --output pages.ndjson常见疑问速查疑问答案JSON 结果能落到--output-dir吗不能JSON 落盘只能走--output或 shell 重定向下载默认落到哪里当前工作目录可用--output-dir覆盖分页拉不完会报错吗不会达到--page-count后静默停止dry-run 会创建输出目录吗不会只校验不物化文件权限是什么下载文件以0600落盘延伸阅读完整命令模型与运行时路径docs/cli-reference.md输出形态实现crates/wecom/src/service/output.rs、crates/wecom/src/service/execute.rs沙箱路径策略crates/wecom-fs/src/sandbox/mod.rs端到端用例索引crates/wecom/test-e2e/cases/output/、crates/wecom/test-e2e/cases/pagination/掌握--output写文件、--output-dir下载目录、--page-countNDJSON 分页这三条规则wecom-cli 的输出就再也没有意外——无论人工操作还是 Agent 自动化结果都落在你指定的位置。【免费下载链接】wecom-cli企业微信开放平台命令行工具 — 让人类和 AI Agent 都能在终端中操作企业微信项目地址: https://gitcode.com/gh_mirrors/we/wecom-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考