ai-dvps/comate/wecom-doc

<objective> 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. </objective>

<quick_start> Read a document or sheet:

wecom doc:get-doc-content --docid DOCID --type 2

Create a document:

wecom doc:create-doc --doc-type 3 --doc-name "Weekly Report"

Upload an image to a document:

wecom doc:upload-doc-image --docid DOCID --file-path "images/chart.png"

Get smartsheet metadata:

wecom doc:smartsheet-get-sheet --docid DOCID

Add a record to a smartsheet:

wecom doc:smartsheet-add-records --docid DOCID --sheet-id SHEET --records '[{"field_values":{"Field1":"Value1"}}]'

Export every smartsheet in a document to one .xlsx file:

wecom doc:smartsheet-export-excel --docid DOCID --output ./export.xlsx

If wecom is not in PATH, use npx wecom or ${WECOM_CLI_PATH}. </quick_start>

<workflow>

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 ``

1. 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-*)

1. 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.

1. 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.

1. 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.
2. 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).
3. 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.
4. 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.

1. Execute and report: Show the command and the outcome. If errcode is non-zero, surface errcode and errmsg to the user and retry once.

</workflow>

<examples> <example number="1"> <input>Read the content of document DOC123</input> <output>

wecom doc:get-doc-content --docid DOC123 --type 2

</output> </example>

<example number="2"> <input>Create a document called "Weekly Report"</input> <output>

wecom doc:create-doc --doc-type 3 --doc-name "Weekly Report"

Save the returned docid. </output> </example>

<example number="3"> <input>Set DOC123 content to "# Weekly Report\n\nAll done"</input> <output>

wecom doc:edit-doc-content --docid DOC123 --content "# Weekly Report\n\nAll done" --content-type 1

</output> </example>

<example number="4"> <input>Create a smartpage from docs/overview.md</input> <output>

wecom doc:smartpage-create --title "Overview" --page-filepath "docs/overview.md"

Save the returned docid. </output> </example>

<example number="5"> <input>Export the smartpage at https://doc.weixin.qq.com/smartpage/xxx as Markdown</input> <output> Start the export task:

wecom doc:smartpage-export-task --url "https://doc.weixin.qq.com/smartpage/xxx" --json '{"content_type":1}'

Poll for the result:

wecom doc:smartpage-get-export-result --json '{"task_id":"TASK_ID"}'

Repeat until task_done is true. </output> </example>

<example number="6"> <input>Upload an image to document DOC123</input> <output>

wecom doc:upload-doc-image --docid DOC123 --file-path "images/chart.png"

Save the returned url or media_id for use in document content. </output> </example>

<example number="7"> <input>Add a record to smartsheet DOC123 / sheet SHEET1</input> <output>

wecom doc:smartsheet-add-records --docid DOC123 --sheet-id SHEET1 --records '[{"field_values":{"Status":"Done","Owner":"Alice"}}]'

</output> </example>

<example number="8"> <input>Add a smartsheet record with an image file</input> <output>

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. </output> </example>

<example number="9"> <input>Export the smartsheet at https://doc.weixin.qq.com/smartsheet/DOC123 to Excel</input> <output>

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. </output> </example> </examples>

<anti_patterns> <pitfall name="mixing_url_categories"> Different URL categories map to different tools. Never mix them:

• /doc/*, /sheet/* → doc:get-doc-content
• /smartpage/* → doc:smartpage-export-task + doc:smartpage-get-export-result
• /smartsheet/* → doc:smartsheet-* tools

</pitfall>

<pitfall name="smartpage_mis trigger"> Only use smartpage_* tools when the user explicitly says 「智能文档」 or 「智能主页」. For all other "document" requests, use the standard WeCom doc tools. </pitfall>

<pitfall name="ignoring_async_polling"> 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. </pitfall>

<pitfall name="plus_prefix"> The legacy Rust CLI required +smartpage_create. The new TypeScript CLI uses wecom doc:smartpage-create without any + prefix. </pitfall>

<pitfall name="json_vs_data"> 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. </pitfall>

<pitfall name="export_excel_writes_a_file"> 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. </pitfall>

<pitfall name="quoting_json_flags"> Flags like --fields, --records, --data expect JSON strings. Always wrap the JSON in single quotes on the shell to avoid expansion issues:

wecom doc:smartsheet-add-fields --docid DOCID --sheet-id SHEET --fields '[{"title":"Name","type":1}]'

</pitfall>

<pitfall name="ignoring_exit_code"> 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. </pitfall> </anti_patterns>

<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>

Command taxonomy

Reference docs

• get-doc-content.md
• create-doc.md
• edit-doc-content.md
• smartpage-create.md
• smartpage-export.md
• upload-doc-image.md
• upload-doc-file.md
• smartsheet-get-sheet.md
• smartsheet-add-sheet.md
• smartsheet-update-sheet.md
• smartsheet-delete-sheet.md
• smartsheet-get-fields.md
• smartsheet-add-fields.md
• smartsheet-update-fields.md
• smartsheet-delete-fields.md
• smartsheet-get-records.md
• smartsheet-add-records.md
• smartsheet-update-records.md
• smartsheet-delete-records.md
• smartsheet-add-records-auto-file.md
• smartsheet-update-records-auto-file.md
• smartsheet-export-excel.md