wecomcli-doc

企業微信文件管理

wecom-cli 是企業微信提供的命令列程式，所有操作透過執行 wecom-cli 命令完成。

管理企業微信文件和智能文件（原名智能主頁）的建立、讀取和編輯。文件介面支援透過 docid 或 url 二選一定位文件。

⚠️ 重要觸發規則：只有當使用者明確提到「智能文件」或「智能主頁」時，才使用智能文件相關介面（smartpage_* 系列）。其他所有涉及「文件」的場景（如"建立文件"、"寫個文件"、"幫我建個文件"等），一律使用企微文件介面（create_doc / get_doc_content / edit_doc_content）。

URL 品類識別與介面路由

企業微信文件有四種品類，URL 格式不同，讀取內容所用的介面也不同，切勿混用。其中表格（線上表格）與智能表格是兩類不同品類，請透過 URL 嚴格區分：

URL 模式	品類	讀取內容介面
https://doc.weixin.qq.com/doc/*	文件（doc_type=3）	get_doc_content
https://doc.weixin.qq.com/sheet/*	表格 / 線上表格	get_doc_content
https://doc.weixin.qq.com/smartsheet/*	智能表格（doc_type=10）	參閱 wecomcli-smartsheet skill
https://doc.weixin.qq.com/smartpage/*	智能文件（原名智能主頁）	smartpage_export_task → smartpage_get_export_result

判斷規則：

• URL 路徑以 /doc/* 開頭 → 文件 → 用 get_doc_content
• URL 路徑以 /smartsheet/* 開頭 → 智能表格 → 使用 wecomcli-smartsheet skill
• URL 路徑以 /sheet/* 開頭 → 表格（線上表格） → 用 get_doc_content
• URL 路徑以 /smartpage/* 開頭 → 智能文件（原名智能主頁） → 用 smartpage_export_task

⚠️ 表格 ≠ 智能表格：二者是不同品類（/sheet/ vs /smartsheet/），但讀取內容都使用同一個 get_doc_content 介面。僅在寫入/管理結構時才需要區分（智能表格的結構與記錄管理見 wecomcli-smartsheet skill；普通表格本 skill 僅支援讀取）。

呼叫方式

透過 wecom-cli 呼叫，品類為 doc：

wecom-cli doc <tool_name> '<json_params>'

回傳格式說明

所有介面回傳 JSON 物件，包含以下公共欄位：

欄位	類型	說明
errcode	integer	回傳碼，0 表示成功，非 0 表示失敗
errmsg	string	錯誤資訊，成功時為 "ok"

當 errcode 不為 0 時，說明介面呼叫失敗，可重試 1 次；若仍失敗，將 errcode 和 errmsg 展示給使用者。

特殊錯誤碼

errcode	errmsg	含義	處理方式
851002	incompatible doc type	文件品類與所呼叫的介面不匹配	根據文件 URL 重新確認品類（參見上方「URL 品類識別與介面路由」表），然後使用該品類對應的正確介面重試

---

文件

get_doc_content

取得文件 / 表格（線上表格） / 智能表格的完整內容資料，統一以 Markdown 格式回傳。採用非同步輪詢機制：首次呼叫無需傳 task_id，介面回傳 task_id；若 task_done 為 false，需攜帶該 task_id 再次呼叫，直到 task_done 為 true 時回傳完整內容。

適用 URL：/doc/*、/sheet/*。/smartsheet/*（智能表格）不適用，請改用 wecomcli-smartsheet skill；/smartpage/*（智能文件）不適用，請改用 smartpage_export_task。

• 首次呼叫（不傳 task_id）：

wecom-cli doc get_doc_content '{"docid": "DOCID", "type": 2}'

• 輪詢（攜帶上次回傳的 task_id）：

wecom-cli doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'

• 透過 URL 讀取文件：

wecom-cli doc get_doc_content '{"url": "https://doc.weixin.qq.com/doc/xxx", "type": 2}'

• 透過 URL 讀取表格（線上表格）：

wecom-cli doc get_doc_content '{"url": "https://doc.weixin.qq.com/sheet/xxx", "type": 2}'

⚠️ 智能表格（/smartsheet/*）不適用此介面，請使用 wecomcli-smartsheet skill 進行操作。

參見 API 詳情。

create_doc

新建文件（doc_type=3）或智能表格（doc_type=10）。建立成功回傳 url 和 docid。

• 建立文件：

wecom-cli doc create_doc '{"doc_type": 3, "doc_name": "項目週報"}'

• 建立智能表格：

wecom-cli doc create_doc '{"doc_type": 10, "doc_name": "項目任務表"}'

注意：

• docid 僅在建立時回傳，需妥善保存
• 智能表格（doc_type=10）的詳細管理功能（子表、欄位、資料記錄等）已遷移到 wecomcli-smartsheet skill，請使用該 skill 進行進階操作
• 普通表格（線上表格，URL 含 /sheet/）本 skill 僅支援讀取（透過 get_doc_content），不支援建立

參見 API 詳情。

edit_doc_content

用 Markdown 內容覆寫文件正文。content_type 固定為 1（Markdown）。

wecom-cli doc edit_doc_content '{"docid": "DOCID", "content": "# 標題\n\n正文內容", "content_type": 1}'

參見 API 詳情。

---

智能文件（原名智能主頁）

適用品類：智能文件（使用者說「智能文件」或「智能主頁」時觸發）
適用 URL：/smartpage/*

⚠️ 只有當使用者明確指定「智能文件」或「智能主頁」時，才使用以下介面。其他「文件」場景請使用上方的企微文件介面。

適用場景：

1. 將本地 Markdown 檔案建立為智能文件
2. 非同步匯出智能文件內容為 Markdown

smartpage_create

建立智能文件（原名智能主頁），支援傳入標題和多個子頁面。每個子頁面可指定標題、內容類型和本地檔案路徑。建立成功回傳 docid 和 url。

⚠️ 特殊語法：此命令必須使用 +smartpage_create（帶 + 前綴），加號不可省略；該 + 僅適用於此命令，不要泛化到其他 doc 子命令。

wecom-cli doc +smartpage_create '{"title": "項目概覽", "pages": [{"page_title": "需求文件", "content_type": 1, "page_filepath": "/path/to/requirements.md"}]}'

注意：

• content_type 必須與檔案實際內容匹配：.md 檔案或包含 Markdown 語法的內容必須傳 1（Markdown），僅純文字才傳 0。絕大多數場景應傳 1
• docid 僅在建立時回傳，需妥善保存
• 每個子頁面的 Markdown 檔案大小不得超過 10MB，超過會導致建立失敗。如果檔案過大，需先拆分為多個子頁面再建立

參見 API 詳情。

smartpage_export_task

發起智能文件內容匯出任務（非同步）。傳入 docid（或 url）和 content_type，回傳 task_id。這是非同步匯出的第一步，需配合 smartpage_get_export_result 輪詢取得匯出結果。

• 透過 docid：

wecom-cli doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'

• 或透過 URL：

wecom-cli doc smartpage_export_task '{"url": "https://doc.weixin.qq.com/smartpage/xxx", "content_type": 1}'

參見 API 詳情。

smartpage_get_export_result

查詢智能文件匯出任務進度。傳入 task_id 進行輪詢，當 task_done 為 true 時回傳 content（匯出的完整文件內容）。

wecom-cli doc smartpage_get_export_result '{"task_id": "TASK_ID"}'

當 task_done 為 true 時，content 欄位即為匯出的 Markdown 內容。

參見 API 詳情。

典型工作流程

關鍵提示：讀取內容前先看 URL 判斷品類。/doc/、/sheet/ → get_doc_content；/smartsheet/ → wecomcli-smartsheet skill；/smartpage/ → smartpage_export_task。只有使用者明確提到「智能文件」或「智能主頁」時才走 smartpage 流程，其他文件場景一律使用企微文件介面。

文件 / 表格讀取與文件編輯

1. 讀取文件 / 表格 →

wecom-cli doc get_doc_content '{"docid": "DOCID", "type": 2}'

或透過 URL（/doc/*、/sheet/* 適用）：

wecom-cli doc get_doc_content '{"url": "https://doc.weixin.qq.com/sheet/xxx", "type": 2}'

若 task_done 為 false 則攜帶 task_id 繼續輪詢

智能表格（/smartsheet/*）請使用 wecomcli-smartsheet skill

2. 建立新文件 →

wecom-cli doc create_doc '{"doc_type": 3, "doc_name": "文件名"}'

，保存回傳的 docid
3. 編輯文件 → 先 get_doc_content 了解目前內容，再 edit_doc_content 覆寫

智能文件操作

1. 建立智能文件（僅當使用者明確要求「智能文件」或「智能主頁」時） →

wecom-cli doc +smartpage_create '{"title": "標題", "pages": [{"page_title": "子頁面", "content_type": 1, "page_filepath": "/path/to/file.md"}]}'

，保存回傳的 docid
2. 取得智能文件內容（URL 含 /smartpage/，非同步兩步）：

• 第一步：發起匯出任務 →

wecom-cli doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'

，取得 task_id

• 第二步：輪詢匯出結果 →

wecom-cli doc smartpage_get_export_result '{"task_id": "TASK_ID"}'

，若 task_done 為 false 則繼續輪詢，直到 task_done 為 true，回傳的 content 欄位即為 Markdown 內容