wecomcli-smartsheet

企業微信智能表格管理

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

資源型技能，負責智能表格（/smartsheet/*，doc_type=10）的新建、結構（子表、欄位/列）與資料（記錄）管理。所有介面支援透過 docid 或 url 二選一定位文件。

呼叫方式

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

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

智能表格各介面的 docid/url 二選一傳入即可，以下範例以 docid 為主，URL 傳入方式以此類推。

回傳格式說明

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

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

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

特殊錯誤碼

errcode	errmsg	含義	處理方式
851002	incompatible doc type	文件品類與所呼叫的介面不匹配	確認目標 URL 為 /smartsheet/*；若不是，請跳轉到對應品類的 skill

介面路由表

硬規則：第二列是 references/xxx.md 連結的，命中這一行後先 read 對應 references 檔案，再建構命令。寫入/讀取記錄前，先用 smartsheet_get_sheet 拿到目標子表的 sheet_id，並用 smartsheet_get_fields 了解欄位類型。

使用者意圖	參考位置
從零新建智能表格（空白）	見下方「新建智能表格」
查詢文件中所有子表	見下方「查詢子表」
新增 / 改名 / 刪除子表	見下方「子表管理」
查詢子表欄位/列	見下方「查詢欄位」
新增欄位/列	references/smartsheet-field-types.md
改名 / 刪除欄位	見下方「欄位管理」
查詢子表記錄	references/smartsheet-get-records.md
新增記錄 / 更新記錄	references/smartsheet-cell-value-formats.md
刪除記錄	見下方「刪除記錄」

---

一、新建智能表格

新建智能表格

從零新建一篇企微智能表格（doc_type=10）：空白。建立成功後回傳 docid 和 url。

命令

wecom-cli doc create_doc '<JSON 參數>'

參數

參數	類型	必填	預設值	說明
doc_type	int	是	—	固定傳 10（智能表格）
doc_name	string	是	—	表格標題，最多 255 個字元，超過會被截斷

注意事項

• 新建智能表格文件預設已含一個子表，可透過 smartsheet_get_sheet 查詢其 sheet_id，僅需多個子表時才呼叫 smartsheet_add_sheet。
• docid 僅在建立時回傳，後續無法再取得，務必儲存。

---

二、智能表格結構管理

查詢子表

查詢文件中所有子表資訊，回傳 sheet_id、title、類型等。

# 透過 docid 查詢
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
# 透過 url 查詢
wecom-cli doc smartsheet_get_sheet '{"url": "https://doc.weixin.qq.com/smartsheet/xxx"}'

子表管理

新增子表 —— 新增空白子表。新子表不含檢視、記錄和欄位，需透過其他介面補充。

wecom-cli doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'

注意：新建智能表格文件預設已含一個子表，僅需多個子表時呼叫。

修改子表標題 —— 需提供 sheet_id 和新 title。

wecom-cli doc smartsheet_update_sheet '{"docid": "DOCID", "properties":{"sheet_id":"SHEET_ID", "title":"新子表"}}'

刪除子表 —— 永久刪除子表，操作不可逆。

wecom-cli doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'

查詢欄位

查詢子表的所有欄位資訊，回傳 field_id、field_title、field_type。

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

欄位管理

新增欄位 —— 向子表新增一個或多個欄位。單個子表最多 150 個欄位。

wecom-cli doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "任務名稱", "field_type": "FIELD_TYPE_TEXT"}]}'

在新增欄位前，請先參閱所有欄位類型和定義 欄位類型參考。

注意：如果是首次建立表並呼叫這個方法新增欄位的情況下，呼叫本介面前，你必須確認已完成以下操作，否則會多出一個無用的預設列：

1. 已呼叫 smartsheet_get_fields 查看子表現有欄位（新子表會自帶一個預設文字欄位）
2. 已呼叫 smartsheet_update_fields 將該預設欄位重新命名為你需要的第一個欄位名稱，然後在本介面中只傳入剩餘的欄位（不包含第一個欄位）。

更新欄位標題 —— 只能改名，不能改類型（field_type 必須傳原始類型）。field_title 不能更新為原值。

wecom-cli doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "新標題", "field_type": "FIELD_TYPE_TEXT"}]}'

刪除欄位 —— 刪除一列或多列欄位，操作不可逆。field_id 可透過 smartsheet_get_fields 取得。

wecom-cli doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'

---

三、智能表格資料管理

查詢記錄

查詢子表全部記錄。

# 透過 docid
wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'
# 或透過 URL
wecom-cli doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'

參見 API 詳情。

新增記錄（不帶圖片或檔案）

新增一行或多行記錄，單次建議 500 行內。

呼叫前必須先了解目標表的欄位類型（透過 smartsheet_get_fields），重點關注 field_type。對於單選/多選（Option）欄位，需注意匹配已有選項的 id。

wecom-cli doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任務名稱": [{"type": "text", "text": "完成需求文件"}], "優先級": [{"text": "高"}]}}]}'

各欄位類型的值格式參見 儲存格值格式參考。

新增記錄（帶圖片或檔案）

新增一行或多行記錄，單次建議 500 行內。與 smartsheet_add_records 不同之處在於，可支援本機路徑傳入圖片、檔案。對於需要新增帶圖片或檔案的記錄，請使用此介面。傳入後台後，後台將自動儲存並轉換為 image_url。

wecom-cli doc +smartsheet_add_records_auto_file '{"docid":"DOCID","sheet_id":"SHEETID","records":[{"values":{"圖片":[{"image_path":"/path/to/image.jpg"}],"檔案":[{"file_path":"/path/to/file.txt"}]}}]}'

更新記錄（不帶圖片或檔案）

更新一行或多行記錄，單次建議在 500 行內。需提供 record_id（透過 smartsheet_get_records 取得）。支援透過 key_type 指定 values 的 key 使用欄位標題或欄位 ID：

• CELL_VALUE_KEY_TYPE_FIELD_TITLE：key 為欄位標題
• CELL_VALUE_KEY_TYPE_FIELD_ID：key 為欄位 ID

wecom-cli doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"任務名稱": [{"type": "text", "text": "更新後的內容"}]}}]}'

注意：建立時間、最後編輯時間、建立人、最後編輯人欄位不可更新。

更新記錄（更新圖片或檔案欄位）

更新一行或多行記錄，單次建議在 500 行內。與 smartsheet_update_records 不同之處在於，可支援本機路徑傳入圖片、檔案。對於需要更新記錄中的圖片或檔案，請使用此介面。傳入後台後，後台將自動儲存並轉換為 image_url。

wecom-cli doc +smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"values":{"圖片":[{"image_path":"/path/to/image.jpg"}],"檔案":[{"file_path":"/path/to/file.txt"}]}}}]}'

刪除記錄

刪除一行或多行記錄，單次必須在 500 行內。操作不可逆。record_id 透過 smartsheet_get_records 取得。極速版智能表格不支援此介面。

wecom-cli doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'

---

典型工作流程

新建並搭建表結構

1. 新建智能表格 →

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

，儲存回傳的 docid。
2. 了解預設子表 → smartsheet_get_sheet 拿到預設子表的 sheet_id → smartsheet_get_fields 查看預設欄位。
3. 搭建列 → 先 smartsheet_update_fields 改預設欄位名，再 smartsheet_add_fields 補充其餘欄位。

智能表格結構操作

1. 了解表結構 →

wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'

→

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

2. 建立表結構 → smartsheet_add_sheet 新增子表 → smartsheet_add_fields 定義列
3. 修改表結構 → smartsheet_update_fields 改列名 / smartsheet_delete_fields 刪列

智能表格資料操作

1. 讀取資料 →

wecom-cli doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'

2. 寫入資料 → 先 smartsheet_get_fields 了解列類型 → 若涉及成員（USER）欄位，先透過 wecomcli-contact 的 get_userlist 查詢人員 userid → smartsheet_add_records 寫入
3. 更新資料 → 先 smartsheet_get_records 取得 record_id → 若涉及成員（USER）欄位，先透過 wecomcli-contact 的 get_userlist 查詢人員 userid → smartsheet_update_records 更新
4. 刪除資料 → 先 smartsheet_get_records 確認 record_id → smartsheet_delete_records 刪除

跨技能依賴

依賴技能	典型協作場景	資料流向
wecomcli-contact	成員（USER）類型欄位需填 user_id，不能直接用姓名	get_userlist 按姓名查到 userid → 本 skill 寫入
wecomcli-msg	使用者要求把智能表格連結發給某人/某群	本 skill 新建後回傳 url → wecomcli-msg 發送連結

注意：成員（USER）類型欄位需要填寫 user_id，不能直接使用姓名。必須先透過 wecomcli-contact 技能的 get_userlist 介面按姓名查找到對應的 userid 後再使用。