Manage WeCom documents, smartpages, uploads, and smartsheets via the wecom CLI. Use when the user wants to read, create, edit, export, upload to, or manage WeCom docs, sheets, or smartpages, or when a doc.weixin.qq.com URL is mentioned.
Manage WeCom documents, smartpages, uploads, and smartsheets via the wecom CLI. Use when the user wants to read, create, edit, export, upload to, or manage WeCom docs, sheets, or smartpages, or when a doc.weixin.qq.com URL is mentioned.
Manage WeCom documents, smartpages (formerly "智能主页" / "智能文档"), uploads, and smartsheets through the `wecom doc:*` subcommands. Help the agent route URLs to the correct tool family, build oclif flag commands, and poll async export/read tasks to completion.
If wecom is not in PATH, use npx wecom or ${WECOM_CLI_PATH}.
</quick_start>
1. **Verify CLI version**: Before any operation, check the installed CLI version:
```bash
wecom --version
```
Expected: `1.2.0` or higher. If lower, advise the user to update:
```bash
npm install -g @webank/wecom@latest
```
If `wecom` is not found, check `npx wecom --version` or `${WECOM_CLI_PATH} --version`.
If the CLI is not installed at all, advise installation:
```bash
npm install -g @webank/wecom
```
2. **Identify the URL category** before reading or modifying anything:
- `/doc/*` or `/sheet/*` → use `wecom doc:get-doc-content`
- `/smartpage/*` → use `wecom doc:smartpage-export-task` + `wecom doc:smartpage-get-export-result`
- `/smartsheet/*` → use the smartsheet tools (`wecom doc:smartsheet-*`)
3. **Decide the tool family**:
- **Smartpages**: Only when the user explicitly uses the terms 「智能文档」 (smart document) or 「智能主页」 (smart homepage).
- **Smartsheets**: When the URL is `/smartsheet/*` or the user asks about smart tables/records/fields.
- **Uploads**: When the user wants to attach an image or file to a document or smartsheet record.
- **Standard docs**: All other "document" scenarios use `doc:get-doc-content`, `doc:create-doc`, or `doc:edit-doc-content`.
4. **Build the command**:
- Prefer typed flags (`--docid`, `--url`, `--type`, etc.).
- When passing complex JSON or fields not covered by flags, use `--json '{"key":"value"}'` to override.
- The smartsheet auto-file helpers (`smartsheet-add-records-auto-file` and `smartsheet-update-records-auto-file`) use `--data` instead of `--json` because oclif reserves `--json` as a built-in boolean flag.
5. **Create smartpages**: When explicitly requested, use `doc:smartpage-create` with a local Markdown file path or `--json` for multi-page input. Save the returned docid.
6. **Handle uploads**: For images/files attached directly to a doc, use `doc:upload-doc-image` or `doc:upload-doc-file`. For records that include image/file fields, prefer the auto-file helpers (`doc:smartsheet-add-records-auto-file`, `doc:smartsheet-update-records-auto-file`).
7. **Export smartsheets to Excel**: To save a whole smartsheet document as a workbook, use `doc:smartsheet-export-excel --docid DOCID --output PATH.xlsx`. It exports every sheet (tab) into one `.xlsx` file. This command writes a binary file locally — it does **not** take `--json` and prints the output path, not JSON. Pass `--force` to overwrite an existing file.
8. **Handle async polling**: `get-doc-content`, `smartpage-export-task`, and `smartpage-get-export-result` are async:
- First call returns a `task_id`.
- If `task_done` is `false`, call again with the `task_id` until `task_done` is `true`.
9. **Execute and report**: Show the command and the outcome. If `errcode` is non-zero, surface `errcode` and `errmsg` to the user and retry once.
Read the content of document DOC123
```bash
wecom doc:get-doc-content --docid DOC123 --type 2
```
Create a document called "Weekly Report"
```bash
wecom doc:create-doc --doc-type 3 --doc-name "Weekly Report"
```
Save the returned docid.
Set DOC123 content to "# Weekly Report\n\nAll done"
```bash
wecom doc:edit-doc-content --docid DOC123 --content "# Weekly Report\n\nAll done" --content-type 1
```
Create a smartpage from docs/overview.md
```bash
wecom doc:smartpage-create --title "Overview" --page-filepath "docs/overview.md"
```
Save the returned docid.
Export the smartpage at https://doc.weixin.qq.com/smartpage/xxx as Markdown
Start the export task:
```bash
wecom doc:smartpage-export-task --url "https://doc.weixin.qq.com/smartpage/xxx" --json '{"content_type":1}'
```
Upload an image to document DOC123
```bash
wecom doc:upload-doc-image --docid DOC123 --file-path "images/chart.png"
```
Save the returned `url` or `media_id` for use in document content.
Add a record to smartsheet DOC123 / sheet SHEET1
```bash
wecom doc:smartsheet-add-records --docid DOC123 --sheet-id SHEET1 --records '[{"field_values":{"Status":"Done","Owner":"Alice"}}]'
```
Add a smartsheet record with an image file
```bash
wecom doc:smartsheet-add-records-auto-file --docid DOC123 --sheet-id SHEET1 --data '{"records":[{"field_values":{"Photo":"images/photo.png"}}]}'
```
The server resolves `image_path`/`file_path` fields to WeCom media IDs.
Export the smartsheet at https://doc.weixin.qq.com/smartsheet/DOC123 to Excel
```bash
wecom doc:smartsheet-export-excel --docid DOC123 --output ./DOC123.xlsx
```
Every sheet in the document is written as a worksheet in the `.xlsx`. The command prints the absolute output path. Add `--force` to overwrite an existing file.
<anti_patterns>
Different URL categories map to different tools. Never mix them:
Only use `smartpage_*` tools when the user explicitly says 「智能文档」 or 「智能主页」. For all other "document" requests, use the standard WeCom doc tools.
`get-doc-content` and `smartpage-export-task` return a `task_id` on the first call. You must poll with that `task_id` until `task_done` is true before the content is available.
The legacy Rust CLI required `+smartpage_create`. The new TypeScript CLI uses `wecom doc:smartpage-create` without any `+` prefix.
Most commands accept `--json` to override the request body. The smartsheet auto-file helpers (`smartsheet-add-records-auto-file` and `smartsheet-update-records-auto-file`) use `--data` instead because oclif reserves `--json` as a built-in boolean flag. Passing `--json` to those commands will fail.
`smartsheet-export-excel` is the only smartsheet command that writes a **binary file** instead of printing JSON. It requires `--output` (a `.xlsx` path) and does **not** accept `--json`. If the file exists, it prompts in a TTY or exits `1` non-interactively unless `--force` is passed. Report the printed output path, not a JSON body.
Flags like `--fields`, `--records`, `--data` expect JSON strings. Always wrap the JSON in single quotes on the shell to avoid expansion issues:
```bash
wecom doc:smartsheet-add-fields --docid DOCID --sheet-id SHEET --fields '[{"title":"Name","type":1}]'
```
The wecom CLI returns specific exit codes:
- `0`: Success
- `1`: Invalid arguments or context file error
- `2`: No WeCom bot context found
- `3`: HTTP request failed
- `4`: Network error
Report the actual exit code and meaning to the user.
<success_criteria>
URL category is correctly routed to the appropriate doc:* tool
Smartpage tools are only used when explicitly triggered
Smartsheet tools are used for /smartsheet/* URLs and smart-table operations
Uploads are handled via doc:upload-doc-image, doc:upload-doc-file, or auto-file helpers as appropriate
Smartsheet-to-Excel exports use doc:smartsheet-export-excel with --output (and --force when overwriting), reporting the written file path
Async tasks are polled until task_done is true
Complex parameters are passed correctly via --json (or --data for auto-file helpers)
The executed CLI command is shown in the response
Error codes and messages are reported clearly
</success_criteria>
