SKILL.md
唯讀
名稱
lark-base
描述
飛書多維表格（Base）操作：建立表格、欄位、記錄、檢視、統計、公式/lookup、表單、儀表板、workflow、角色權限；遇到 Base/多維表格/bitable 或 /base/ 連結時使用。檔案匯入轉 lark-drive，驗證/授權轉 lark-shared。
版本
1.2.2
base
何時使用
使用本 skill：
- 使用者明確提到 Base / 多維表格 / bitable，或提供
/base/連結。 - 使用者要在 Base 內建立表格、修改表格、管理欄位、寫入記錄、查詢記錄、設定檢視。
- 使用者要在 Base 內設定公式欄位、lookup 欄位、跨表計算、衍生指標、篩選聚合、TopN、統計分析。
- 使用者要管理 Base 表單、儀表板、workflow、進階權限或角色。
- 使用者要把舊版 Base 聚合式命令或舊寫法遷移到目前的
lark-cli base +...shortcut。
不要使用本 skill：
- 僅進行驗證、初始化設定、切換身分、處理 scope 或權限授權復原，轉用
lark-shared。 - 將本機 Excel / CSV /
.base匯入成 Base，轉用lark-drive +import --type bitable。 - 一般性資料分析、欄位設計、公式討論，但缺乏 Base/多維表格上下文情境。
使用邊界
- Base 業務操作僅使用
lark-cli base +...shortcut，不使用舊版聚合式+table / +field / +record / +view / +history / +workspace。 - 本輪 Base 不依賴
lark-cli schema。SKILL 僅保留路由、風險和複雜 JSON/DSL；簡單命令由命令本身的參數、tips 和錯誤復原承接。 - 使用者要把 Excel / CSV /
.base匯入成 Base 時，先轉用lark-cli drive +import --type bitable，匯入完成後再回到 Base 命令。 - 使用者只提供 Base 名稱或關鍵字時，先用
lark-cli drive +search --query <keyword> --doc-types bitable定位資源。 - Base 命令必須先有
base_token或可解析出的 Base URL。沒有 token 時：使用者要新建就用+base-create；使用者給標題/關鍵字就搜尋lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user；若仍無法定位，則詢問使用者具體是哪一個 Base。 - 驗證、初始化、scope、身分切換、權限不足復原屬於
lark-shared；Base 文件僅保留會影響 Base 路徑選擇的權限規則。
快速路由
| 使用者目標 | 優先命令 | 何時參閱 reference |
|---|---|---|
| 查詢 Base 本體 | +base-get |
用傳回值確認 Base 名稱、owner、權限和可繼續操作的 token |
| 建立/複製 Base | +base-create / +base-copy |
新建時強烈推薦使用 --table-name + --fields 同時設定新 Base 中唯一一個初始資料表的 name 與 schema；寫入後回報新 Base 識別碼與 permission_grant |
| 檢視 Base 內資源目錄 | +base-block-list |
想先了解 Base 裡有哪些 table/docx/dashboard/workflow/folder 時優先使用；傳回 ID 關係與 fewshot 請參閱 --help |
| 管理 Base 內資源目錄 | +base-block-create/move/rename/delete |
建立或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；資源內容繼續使用對應命令 |
| 管理資料表 | +table-list/get/create/update/delete |
處理 table 的列出、詳細資料、建立、重命名和刪除 |
| 列出/查詢/刪除欄位 | +field-list/get/delete/search-options |
寫入前用 list/get 確認欄位型別、選項、ID；刪除前確認目標欄位 |
| 建立/更新欄位 | +field-create / +field-update |
必讀 lark-base-field-json.md；公式參閱 formula-field-guide.md；lookup 參閱 lookup-field-guide.md；命令細節參閱 lark-base-field-create.md / lark-base-field-update.md |
| 讀取記錄明細 | +record-get / +record-list / +record-search |
涉及篩選、排序、Top/Bottom N、聚合、多表關聯、全域結論時參閱 lark-base-data-analysis-sop.md |
| 寫入記錄 | +record-upsert / +record-batch-create / +record-batch-update |
必讀 lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md 和 lark-base-cell-value.md |
| 附件欄位 | +record-upload-attachment / +record-download-attachment / +record-remove-attachment |
附件不要偽造成普通 CellValue；上傳走本機檔案，下載/刪除按 file token 或欄位定位 |
| 刪除記錄 / 分享記錄連結 / 歷史 | +record-delete / +record-share-link-create / +record-history-list |
刪除前確認 record；分享連結最多 100 條；歷史參閱 lark-base-record-history-list.md，僅查詢單條記錄，不做全表稽核 |
| 管理檢視 | +view-* |
+view-set-filter 參閱 lark-base-view-set-filter.md；其餘設定先 get 現狀，再依傳回結構更新 |
| 一次性聚合統計 | +data-query |
必讀 lark-base-data-analysis-sop.md 和入口 lark-base-data-query-guide.md；完整 DSL 再參閱 lark-base-data-query.md |
| 公式欄位 | +field-create/update --json '{"type":"formula",...}' |
必讀 formula-field-guide.md，閱讀後再加入隱藏確認 flag --i-have-read-guide |
| Lookup 欄位 | +field-create/update --json '{"type":"lookup",...}' |
必讀 lookup-field-guide.md，閱讀後再加入隱藏確認 flag --i-have-read-guide |
| 表單提交 | +form-submit |
先參閱 lark-base-form-detail.md 取得題目、filter 與附件所需的 base_token；提交 JSON 參閱 lark-base-form-submit.md |
| 表單題目建立/更新 | +form-questions-create / +form-questions-update |
參閱 lark-base-form-questions-create.md / lark-base-form-questions-update.md |
| 其他表單管理 | +form-list/get/detail/create/update/delete / +form-questions-list/delete |
+form-detail 參閱 lark-base-form-detail.md；刪除前確認目標表單 |
| 儀表板與組件 | +dashboard-* / +dashboard-block-* |
提到圖表/看板/block 時先參閱 lark-base-dashboard.md；組件 data_config 參閱 dashboard-block-data-config.md；讀取圖表計算結果使用 +dashboard-block-get-data |
| Workflow | +workflow-* |
建立/更新或理解 steps 時參閱入口 lark-base-workflow-guide.md 和 steps JSON SSOT lark-base-workflow-schema.md；list/get/enable/disable 僅處理 workflow ID 與啟停狀態 |
| 進階權限與角色 | +advperm-* / +role-* |
角色操作先參閱入口 lark-base-role-guide.md；角色 create/update 或解讀完整設定再參閱權限 JSON SSOT role-config.md；系統角色不可刪除；關閉進階權限會影響自訂角色 |
Base 心智模型
- Base 曾用名為 Bitable；傳回欄位、錯誤訊息或舊文件裡的
bitable多為歷史相容，不代表應改走裸 API 或另一套命令。 +base-block-list是檢視 Base 內資源目錄的新入口：它會列出此 Base 直接管理的folder/table/docx/dashboard/workflow，適合先判斷 Base 裡有哪些內容，再決定使用 table、dashboard、workflow 或 docx 命令。base-block僅負責資源目錄管理，包含建立資源、移動到 folder、重命名與刪除；具體資源內容仍使用 table/dashboard/workflow 命令。- 新建 Base 時，強烈推薦一次性執行
lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'，同時設定新 Base 中唯一一個初始資料表的 name 與 schema；使用--fields前先參閱 lark-base-field-json.md 或複用+field-create的欄位 JSON 結構，切勿推測欄位屬性。 +base-create未傳入--table-name與--fields時，會建立一個預設 schema 的初始資料表。- 資料表、欄位、檢視、workflow、dashboard block 的名稱與 ID 必須來自真實傳回值，切勿憑使用者口述推測。
- 儲存欄位可寫入；系統欄位、
formula、lookup為唯讀；附件欄位請走專用 attachment 命令。 - 一次性原始記錄查詢優先使用
+record-list/+record-search的 filter/sort；聚合分析優先使用+data-query；需要長期顯示在表格中時，才新增formula/lookup欄位。 formula適合常規計算、條件判斷、文字/日期處理和長期衍生指標；lookup適合明確的跨表搜尋、篩選後取值或聚合引用。- 寫入、分析、公式、lookup、workflow、dashboard 前，先讀取真實結構：資料表、欄位、檢視、關聯表與 dashboard block 名稱皆以命令傳回值為準。
- 跨表情境必須讀取目標表結構；link 儲存格中的關聯
record_id僅為連接鍵，最終回答需回查並展示使用者可讀欄位。
身分與權限降級
- 預設顯式使用
--as user操作使用者資源；僅在使用者明確要求應用程式身分時，才直接使用--as bot。 - user 身分回報 scope/授權不足，或錯誤訊息包含
permission_violations/hint時，先轉用lark-shared進行使用者授權復原，切勿直接降級為 bot。 - user 身分回報資源層級無權限存取且無授權復原提示時，才可用
--as bot重試一次；bot 依然失敗則停止重試，並按權限錯誤處理。 91403或明確無法存取的錯誤切勿循環切換身分重試。+base-create/+base-copy若以 bot 身分執行，請留意傳回值中的permission_grant，並告知使用者是否能開啟新 Base。
查詢與統計規則
涉及查詢、統計或判斷結論時，先參閱 lark-base-data-analysis-sop.md，並遵守以下規則：
+record-list的預設頁、固定--limit和本機jq只能證明已讀取範圍內的事實，無法直接支援全域極值、全量計數、Top/Bottom N、異常識別或分組結論。- 能由 Base 表达的篩選、排序、投影、聚合、分組和限制，應在 Base 雲端查詢能力中執行；切勿先將原始記錄擷取至本機上下文再手動篩選排序。
has_more=true或等效分頁訊號表示目前結果非全量；除非使用者僅需要範例/前 N 條，否則不能基於該頁回答全域問題。- 多表查詢必須先確認關係欄位與連接鍵；link 儲存格裡的
record_id是關係鍵，並非使用者可讀的答案。 - 最終答案必須能追溯到真實資料表、真實欄位、查詢範圍、篩選/排序/聚合條件與必要的連接鍵。
- 一次性原始記錄查詢優先使用
+record-list/+record-search的 filter/sort；聚合分析優先使用+data-query；若要把結果長期顯示在表格中，才考慮新增formula/lookup欄位。 +data-query可傳回聚合結果或維度欄位列，但維度列會依欄位組合去重且不傳回record_id；需要逐條記錄、記錄定位或完整列級欄位時，再使用+record-list/+record-search/+record-get回查。
寫入前置規則
- 寫入記錄前先讀取欄位結構；僅寫入儲存欄位。系統欄位、附件欄位、
formula、lookup不得作為普通記錄的寫入目標。 - 附件上傳、下載、刪除請使用專用
+record-*-attachment命令。 - 寫入欄位前先參閱 lark-base-field-json.md；涉及
formula/lookup時必須參閱 formula-field-guide.md / lookup-field-guide.md。 - 資料表名稱、欄位名稱、檢視名稱、workflow 設定中的名稱必須來自真實傳回值；跨表情境還需讀取目標表結構。
- 刪除、角色更新、欄位更新等高風險操作遵循 CLI 的 confirmation gate；目標不明確時先用 get/list 消除歧義。
- 批次寫入單批最多 200 條；連續寫入同一表時請序列執行，遇到
1254291請短暫等待後重試。 +record-batch-update是「同值批次更新」：將同一份 patch 套用到全部record_id_list，切勿用它進行逐列不同值的對應更新。- select/multiselect 寫入未知選項可能會觸發平台新增選項；若非意圖新增，請先使用
+field-list或+field-search-options確認可選值。
表單與檢視細節
+form-submit前必須先執行+form-detail，讀取questions[].type、required、filter與附件情境需要的base_token；請勿填寫被 filter 隱藏的問題。- 表單附件請勿寫入
fields，應放在--json.attachments；提交附件時必須同時傳入表單所屬 Base 的--base-token。 +view-set-filter是唯一保留的 view reference；sort/group/card/timebar/visible-fields 這類設定先用對應 get 命令讀取現狀，保留未修改欄位，僅替換使用者要求變更的設定。- 檢視適合持久化、共用與 UI 複用；一次性篩選/排序可先用
+record-list/+record-search的 filter/sort 驗證結果，再視需要沉澱為持久檢視。
Token 與連結
| 輸入類型 | 含義 / 正確處理方式 |
|---|---|
/base/{token} |
普通 Base 連結；擷取 /base/ 後的 token 作為 --base-token |
/wiki/{token} |
Wiki 節點連結；先執行 wiki +node-get，當 data.obj_type=bitable 時使用 data.obj_token 作為 --base-token |
/base/{token}?table={id} |
table 參數用於定位 Base 內物件：tbl 開頭為資料表 --table-id；blk 開頭為 dashboard ID；wkf 開頭為 workflow ID |
/base/{token}?view={id} |
view 參數用於定位表檢視，擷取為 --view-id；通常還需要確認 table 參數或先查詢表結構 |
/share/base/form/{shareToken} |
表單分享連結；這是表單 share token，走 +form-detail / +form-submit --share-token <shareToken> |
/share/base/view/{shareToken} |
檢視分享連結；具有分享權限語義，暫不支援使用 CLI 直接存取，引導使用者在瀏覽器或飛書用戶端開啟 |
/share/base/dashboard/{shareToken} |
儀表板分享連結；具有分享權限語義，暫不支援使用 CLI 直接存取，引導使用者在瀏覽器或飛書用戶端開啟 |
/record/{shareToken} |
記錄分享連結；暫不支援使用 CLI 直接存取，引導使用者在瀏覽器或飛書用戶端開啟。若使用者想產生現有記錄的分享連結，使用 +record-share-link-create --base-token <base_token> --table-id <table_id> --record-ids <record_id> |
/base/workspace/{token} |
BaseApp / workspace 連結；暫不支援使用 CLI 直接存取 |
wiki +node-get 傳回非 bitable 時，不繼續使用 Base 命令：docx 轉用文件，sheet 轉用試算表，其他雲端空間物件轉用對應 skill 或 drive。
Dashboard / Workflow / Role
- Dashboard 的複雜之處在於 block 的
data_config，而非 list/get/create/delete 命令參數。建立或更新 block 前先參閱 dashboard-block-data-config.md，組件必須序列建立；+dashboard-arrange為伺服器端智慧版面配置，僅在使用者明確要求重排/美化時執行。+dashboard-block-get-data用於讀取圖表最終計算結果，不傳回 block 名稱、型別、版面配置或data_config；需要元資料請先使用+dashboard-block-get。 - Workflow 的複雜之處在於
steps結構。建立、更新或解讀完整 workflow 時請參閱入口 lark-base-workflow-guide.md 和 steps JSON SSOT lark-base-workflow-schema.md；enable/disable/list 僅需確認 workflow ID、目前啟停狀態與使用者意圖。 - Role 的複雜之處在於權限 JSON。角色操作先參閱入口 lark-base-role-guide.md；
+role-create僅支援自訂角色；+role-update為 delta merge；角色 create/update 或解讀完整設定時請參閱權限 JSON SSOT role-config.md。+role-delete僅適用於自訂角色，系統角色不可刪除；刪除角色與關閉進階權限前必須確認目標與影響。
常見復原
| 錯誤 / 現象 | 復原動作 |
|---|---|
param baseToken is invalid / base_token invalid |
檢查是否將 wiki token、workspace token 或完整 URL 誤當成 --base-token；依 Token 與連結 重新定位真實 Base token |
not found 且輸入來自 Wiki 連結 |
優先檢查是否將 wiki token 誤當成 base token，切勿立刻改走裸 API |
1254045 欄位名稱不存在 |
重新執行 +field-list，使用真實欄位名稱或欄位 ID；注意空格、大小寫和跨表欄位 |
1254015 欄位值型別不相符 |
先執行 +field-list，再按 lark-base-cell-value.md 建構 CellValue |
| 日期 / 人員 / 超連結欄位報格式錯誤 | 日期使用 YYYY-MM-DD HH:mm:ss；人員使用 [{ "id": "ou_xxx" }]；超連結使用 URL 或 markdown link 字串 |
| formula / lookup 建立失敗 | 先參閱 formula-field-guide.md / lookup-field-guide.md，再依指南重建請求 |
ignored_fields / READONLY |
移除唯讀欄位，僅寫入儲存欄位 |
1254104 |
批次超過 200，請分批呼叫 |
1254291 |
包含並行寫入衝突，請改為序列寫入並在批次間短暫等待 |
91403 |
無權限存取該 Base，按 lark-shared 權限流程處理，切勿盲目重試 |
保留 Reference
- lark-base-data-analysis-sop.md：查詢/統計/全域結論的選路 SOP
- lark-base-data-query-guide.md / [lark-base-data-qu...
