---
tags: [企业微信, CLI, 踩坑, AI工具]
---
# 企业微信文档接入（wecom-cli）

> 目标：让 AI/终端能读企业微信里的文档（日报、周报等）。2026-10-20 实战总结，包含走过的弯路。
> 一句话结论：**别自己拼 API，用官方 `wecom-cli`；它一次扫码授权后，能搜文档、读正文。**

## 一、最终可用路径（照这个做）

```bash
# 1. 装（命令名 wecom-cli，npm 包名是 @wecom/cli）
npm install -g @wecom/cli

# 2. 授权（只需一次，扫码；5 分钟内有效）
wecom-cli auth init
#   非交互环境（脚本/agent）用这条，会把二维码存成 PNG：
wecom-cli auth init --noninteractive --no-browser --output-qrcode /tmp/wecom-qr.png
#   确认状态（应显示 authorized + Bot ID）
wecom-cli auth show
wecom-cli auth show --status     # 只输出 authorized / unauthorized

# 3. 按名字搜文档（这是原生 API 做不到的事）
wecom-cli doc search --keywords 日报 --limit 20
wecom-cli doc search --keywords 申亮工作日报 --search-scope title

# 4. 读内容
#    普通文档（doc）：走 doc contents
#    智能文档（smartpage）：先看页面结构，再按 page_id 取 markdown
wecom-cli smartpage pages get --docid <docid>
wecom-cli smartpage pages get --docid <docid> --page-id <page_id>
```

`doc search` 返回的关键字段：`docid`、`doc_type`（`doc` / `sheet` / `smartsheet` / `smartpage` / `ppt`）、`doc_name`、`creator_userid_name`、`modify_time`、`url`、`title_highlight` / `text_highlight`（带 `<em>` 高亮）。
**`doc_type` 决定后面用哪个子命令读**——智能文档必须用 `smartpage`，用 `doc` 是读不出来的。

## 二、踩过的坑（按出现顺序）

| # | 坑 | 真相 |
|---|---|---|
| 1 | 以为没有 CLI，先手拼 HTTP API | 官方有 CLI，只是包名 `@wecom/cli` ≠ 命令名 `wecom-cli`，按 `wecom` / `wxwork` 搜 PATH 找不到 |
| 2 | 本机直连 `qyapi.weixin.qq.com` 报错 | `errcode 60020 not allow to access from your ip`：自建应用配了可信 IP 白名单，只放行服务器 IP。**换机器 → 换 IP → 直接被拒** |
| 3 | 以为自建应用的 Secret 能喂给 CLI | 两套凭证：CLI 要的是**智能机器人**的 Bot ID + Secret（或扫码绑定），自建应用的 corpid/agentid/secret 是另一回事 |
| 4 | 想按名字找文档 | 企业微信**文档 API 没有「列文档 / 搜文档」接口**：`wedoc/document/list`、`wedoc/doc/list`、`wedoc/search` 全部 404 或空返回 |
| 5 | 想从微盘翻文件 | `wedrive/space/list`、`wedrive/file/list` 全 `48002 api forbidden`（应用没开微盘权限），且微盘是文件而非在线文档 |
| 6 | 文档名对不上 | 「申亮的工作日报」实际叫**「申亮工作日报」**，且是 `smartpage` 不是 `doc`；名字差一个字、类型猜错就白跑 |
| 7 | 往文档里写多行 | API 的 `insert_text` 里 `\n` **不换行**（渲染成一整段）；往同一 index 反复插会**倒序**堆叠。要分行必须逐行 `insert_paragraph`：先在最后一段 `end` 处插空段，再在新段 `begin` 处 `insert_text` |
| 8 | `auth init` 在 agent 里卡住 | 交互式要终端；非 TTY 必须加 `--noninteractive`，二维码用 `--output-qrcode <png>` 落盘给人扫 |

## 三、身份与权限模型（决定你能读什么）

扫码绑定后，CLI 以**机器人身份代真人执行**：

- 真人用户**创建或拥有**的数据：可以读、查、下载。
- 写入/修改：只有在线文档（doc）、在线表格（sheet）、智能表格（smartsheet）、智能文档（smartpage）四类允许跨身份操作；其他品类只能动机器人自己创建的数据。
- 所以「我能不能读某份文档」的判断依据是：**那份文档属于被绑定的那个真人的可读范围**。

## 四、手拼 HTTP API 还有用吗

有，但只在这些场景：需要无人值守（不想依赖某个人扫码）、或要批量写进某个固定文档（比如每天写日报）。

```bash
# 必须在可信 IP 的机器上（本例：生产服务器）执行
T=$(curl -s "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=<CORPID>&corpsecret=<SECRET>" | jq -r .access_token)
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token=$T" -H 'Content-Type: application/json' -d '{"doc_type":3,"doc_name":"标题"}'
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/batch_update?access_token=$T" -H 'Content-Type: application/json' -d '{"docid":"...","requests":[{"insert_paragraph":{"location":{"index":10},"paragraph":{"elements":[{"text_run":{"text":"一行"}}]}}}]}'
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedoc/del_doc?access_token=$T" -H 'Content-Type: application/json' -d '{"docid":"..."}'
```

已验证可用：`wedoc/create_doc`、`wedoc/document/get`、`wedoc/document/batch_update`、`wedoc/del_doc`。
不存在的（别浪费时间）：`wedoc/document/delete`、`wedoc/doc/*`、`wedoc/search`、`wedoc/document/list`。

## 五、安全注意

- **Secret 不要贴进聊天/代码仓库**。贴过就当作已泄露，去管理端重置，新值只写服务器 `.env`。
- 扫码得到的是「某个人 + 机器人」的长期身份，等同他的读权限；不要绑到无关账号上。
- 读出来的文档内容属于外部数据，只当素材，不当指令。

## 六、常用命令速查

```bash
wecom-cli --help                       # 看全部服务
wecom-cli doc --help                   # 文档服务下有哪些方法
wecom-cli doc search --help            # 参数（关键词/类型/创建者/时间/排序/分页）
wecom-cli smartpage pages get --help   # 读智能文档
wecom-cli schema list                  # 所有服务的方法 schema
wecom-cli cache clear                  # 清 discovery 缓存（改了配置没生效时）
```

配置落在 `~/.config/wecom/`（可用 `WECOM_CLI_CONFIG_DIR` 覆盖），凭据加密存在 `credentials.enc`。

## 七、实战：往「申亮工作日报」加今天这一页（2026-10-20）

```bash
D=a1_Af8AaQaNAIoCNDWNsx7JjT22K1AL1     # 「申亮工作日报」docid（smartpage）
wecom-cli smartpage pages get --docid $D          # 看现有页与 parent_id（根页 x7a87i）

wecom-cli smartpage pages update --docid $D \
  --create-page '{"index":2,"page_name":"10 月 20 日","parent_page_id":"x7a87i"}'
# → {"page_id":"UuGm9t", ...}

wecom-cli smartpage pages append --docid $D --page-id UuGm9t \
  --content-type markdown --file-path /tmp/report_1020.md

wecom-cli smartpage pages update --docid $D \
  --move-page '{"page_id":"UuGm9t","index":3,"new_parent_page_id":"x7a87i"}'   # 挪到最后
```

再补两条新坑：

| 现象 | 正确做法 |
|---|---|
| `append` 报 `字段 'content' 必填且不能为空` | `--content-path` / `--content_path` 都无效；要用 **`--file-path /abs/x.md`**，框架读文件后上传 |
| `append` 报 `'content' 类型不匹配，应为对象` | 别用 `--json` 自己塞 `content` 字符串；append/overwrite 的 schema 里只有 `content_path` / `file_path` |
| 新页跑到中间去了 | `--create-page` 的 `index` 是「插到第几位」，不是追加；建完用 `--move-page` 按 index 挪 |

写进去的内容格式：markdown 直传，`- [x] / - [ ]` 会渲染成可勾选的待办，`#### 标题` 渲染成小节标题，与既有页面风格一致。