wecomdocs-cli

企业微信文档 CLI — 通过逆向 web API 读取和写入 doc.weixin.qq.com 上的表格，无需管理员 API 权限。

• 无需管理员权限 — 使用个人企业微信账号扫码登录即可
• 表格读写 — 支持读取、批量写入、版本历史对比
• 多种输出格式 — Markdown / CSV / TSV / JSON / Text
• 可编程调用 — 提供 Node.js API，方便集成到自动化脚本

安装

npm install -g wecomdocs-cli

或直接使用 npx：

npx wecomdocs-cli <command>

安装时会自动下载 Chromium（约 150 MB），用于登录和写入操作。

前置要求

• Node.js >= 18

快速开始

# 1. 登录（扫码）
wecomdocs-cli login

# 2. 浏览文档列表
wecomdocs-cli ls

# 3. 读取表格
wecomdocs-cli read <doc-id-or-url>

# 4. 写入单元格
wecomdocs-cli write <doc-id-or-url> --data "A1=hello,B2=world"

文档 ID 和完整 URL 均可使用，例如：

wecomdocs-cli read e3_AbCdEfG
wecomdocs-cli read "https://doc.weixin.qq.com/sheet/e3_AbCdEfG?scode=xxx"

命令参考

login / logout

wecomdocs-cli login          # 打开浏览器扫码登录
wecomdocs-cli logout         # 清除本地会话

登录凭据保存在 ~/.wecomdocs-cli/ 目录下。

ls — 列出文档

wecomdocs-cli ls             # 列出最近文档（默认 30 条）
wecomdocs-cli ls -n 50       # 指定数量

| 选项 | 说明 | |------|------| | -n, --limit <n> | 显示条数（默认 30） |

search — 搜索文档

wecomdocs-cli search <关键词>
wecomdocs-cli search "季度报表" -n 10

| 选项 | 说明 | |------|------| | -n, --limit <n> | 返回条数 |

read — 读取表格

wecomdocs-cli read <doc-id-or-url>                 # 读取表格（Markdown 格式）
wecomdocs-cli read <id> -f csv                     # 输出 CSV
wecomdocs-cli read <id> -f json                    # 输出 JSON
wecomdocs-cli read <id> -t "Sheet2"                # 指定标签页
wecomdocs-cli read <id> --all-tabs                 # 导出所有标签页
wecomdocs-cli read <id> --tabs                     # 仅列出标签页名称
wecomdocs-cli read <id> --fast                     # 快速模式（更快，合并单元格可能不准确）
wecomdocs-cli read <id> -s <scode>                 # 通过分享码访问
wecomdocs-cli read <id> --batch-size 20            # 设置并发批次大小
wecomdocs-cli read <id> --line-numbers             # 显示行号

| 选项 | 说明 | 默认值 | |------|------|--------| | -f, --format <format> | 输出格式: markdown, csv, tsv, json, text | markdown | | -t, --tab <name> | 指定标签页名称 | 第一个标签页 | | -s, --scode <code> | 分享码（用于访问他人分享的文档） | — | | --tabs | 仅列出所有标签页 | — | | --all-tabs | 导出所有标签页 | — | | --fast | 快速模式（混合获取策略） | — | | --batch-size <n> | 并发批次大小 | 10 | | --line-numbers | 显示行号 | — |

write — 写入表格

支持四种写入方式：

# 单个单元格
wecomdocs-cli write <id> -r 0 -c 0 -v "hello"

# 批量写入（内联）
wecomdocs-cli write <id> --data "A1=hello,B2=world"

# 从 CSV 文件读取
wecomdocs-cli write <id> --file changes.csv

# 从标准输入读取
echo "A1=hello" | wecomdocs-cli write <id> --stdin

# 预览模式（不实际写入）
wecomdocs-cli write <id> --data "A1=test" --dry-run

CSV 文件格式（每行一个单元格）：

A1=hello
B2=world
C3,some value

| 选项 | 说明 | 默认值 | |------|------|--------| | -r, --row <n> | 行号（0-based，单个单元格模式） | — | | -c, --col <n> | 列号（0-based，单个单元格模式） | — | | -v, --value <text> | 写入值（单个单元格模式） | — | | -d, --data <pairs> | 批量写入，如 "A1=hello,B2=world" | — | | --file <path> | 从 CSV 文件读取写入数据 | — | | --stdin | 从标准输入读取写入数据 | — | | --dry-run | 预览模式，不实际写入 | — | | -t, --tab <name> | 指定标签页名称 | 第一个标签页 | | -s, --scode <code> | 分享码 | — | | -f, --format <fmt> | 输出格式: json, text | json |

history — 查看编辑历史

wecomdocs-cli history <doc-id>                           # 列出修改记录
wecomdocs-cli history <doc-id> -n 50                     # 显示 50 条
wecomdocs-cli history <doc-id> -p 2                      # 翻页
wecomdocs-cli history <doc-id> --rev 2957                # 查看指定版本快照
wecomdocs-cli history <doc-id> --diff 2940..2957         # 对比两个版本
wecomdocs-cli history <doc-id> --diff 2940..2957 -f json # JSON 格式输出

| 选项 | 说明 | 默认值 | |------|------|--------| | -n, --limit <n> | 显示最近 N 条记录 | 20 | | -p, --page <n> | 页码 | 1 | | -r, --rev <n> | 查看指定版本快照 | — | | --diff <range> | 对比两个版本（格式: rev1..rev2） | — | | -t, --tab <name> | 指定标签页名称 | — | | -s, --scode <code> | 分享码 | — | | -f, --format <format> | 输出格式: text, json, markdown | text |

编程接口 (API)

除了 CLI 使用外，wecomdocs-cli 也导出了 Node.js API，方便在脚本或其他项目中调用：

import { WecomClient, DocsApi, SheetsApi } from 'wecomdocs-cli/api';
import { SessionManager } from 'wecomdocs-cli/auth';

// 初始化客户端（自动加载已保存的 session）
const client = new WecomClient();

// 列出文档
const docsApi = new DocsApi(client);
const docs = await docsApi.list(30);

// 读取表格
const sheetsApi = new SheetsApi(client);
const data = await sheetsApi.readSheet('e3_xxx', '');

// 写入单元格
await sheetsApi.writeCell('e3_xxx', '', 0, 0, 'hello');

导出的类型：

| 导出路径 | 内容 | |----------|------| | wecomdocs-cli/api | WecomClient, DocsApi, SheetsApi, SheetTab, SheetData, AllTabsData, CellWrite | | wecomdocs-cli/auth | SessionManager |

工作原理

• 登录 — 通过 Playwright 打开浏览器让用户扫码，获取 session cookies
• 读取 — 使用逆向的 web API + protobuf 解码获取表格数据
• 写入 — 通过 Playwright 自动化浏览器操作模拟用户编辑（每个单元格约 1–2 秒）

注意事项

• 当前仅支持表格文档（文档 ID 以 e3_ 或 s3_ 开头），在线文档（w3_）暂不支持
• 写入操作需要 Chromium，读取操作仅需网络请求
• Session 过期后需重新执行 wecomdocs-cli login
• 从旧版 wecom-doc 升级时，~/.wecom-doc/ 目录下的会话会自动迁移到 ~/.wecomdocs-cli/

开发

git clone https://github.com/Hallalei/wecomdocs-cli.git
cd wecomdocs-cli
npm install
npx tsx src/index.ts <command>    # 开发模式运行
npm run build                     # 编译 TypeScript
npm test                          # 运行测试（59 个用例）

源码仓库开发环境下 npm install 不会自动安装 Chromium；需要写入功能时手动执行：

npx playwright install chromium

更多开发文档见 .docs/ 目录。

许可证

ISC