前言¶
團隊的知識庫在飛書裏，常見的痛點是：Wiki 鏈接點進去還要跳一層纔是真實文檔；文檔正文、表格、多維表格（Bitable）各自結構不同，人工複製粘貼既慢又容易丟格式；寫腳本直接對接開放平臺又要自己處理 token 鑑權和分頁。
這個 Skill 的作用是讓 agent 直接按文檔或 token 取飛書內容，自動把 Wiki URL 解析成真實實體，並把結果轉成 Markdown，省掉自己寫對接代碼的功夫。
這是什麼¶
Feishu Doc 是一個基於通用 SKILL.md 格式的 Agent Skill，用來讀寫飛書（Lark）的 Wiki、文檔、表格和 Bitable。
它由 autogame-17 發佈，來源爲 clawhub，上游倉庫在 clawhub.ai/autogame-17/feishu-doc，當前版本 v1.2.7，許可證 MIT-0。SkillHub 上同步收錄了該 Skill，座標 @clawhub_autogame-17/feishu-doc，分類 office-efficiency。
它解決的問題是：給 agent 一個統一的入口讀飛書內容並轉成 Markdown，同時支持創建、覆蓋寫入和追加寫入文檔。
核心功能¶
下面是已從官方資料覈實的能力，按官方 SKILL.md 的分類列出。
讀取：從文檔、表格、Bitable 和 Wiki 獲取內容，自動把 Wiki URL 解析爲真實實體，並轉換爲 Markdown。
創建：創建新的空白文檔。
寫入：用 Markdown 覆蓋文檔已有內容。
追加：把 Markdown 內容追加到文檔末尾。
Block 級操作：列出、獲取、更新和刪除具體的 block，用於在文檔內部做局部修改。
注意，官方資料裏的寫入動作描述是「overwrite document content with Markdown」，也就是覆蓋寫，不是在光標處插入。需要保留原文時要先 read 出來再整體寫回。
前置依賴¶
這個 Skill 不能單獨使用，必須先裝 feishu-common。
官方說明：該 Skill 依賴 ../feishu-common/index.js 來完成 token 和 API 鑑權。也就是說鑑權邏輯不在 feishu-doc 自身，而是由配套的 common 包提供。漏裝這一步，後續 read/write 都會因爲沒有鑑權而失敗。
安裝順序上，先裝 feishu-common，再裝 feishu-doc。
安裝與啓用¶
官方給出的安裝命令走 OpenClaw/clawhub 生態的 CLI，命令如下。
openclaw skills install @autogame-17/feishu-doc
這條命令拉取 Skill 包到本地 skills 目錄，之後由 agent 運行時加載 SKILL.md。
官方資料中沒有分別給出 Cursor、Codex CLI、Claude Code 的安裝方式，也沒有說明這些工具是否需要額外配置。這一點按現狀說明，不做推斷。
配置¶
鑑權需要飛書開放平臺應用的 app_id 和 app_secret，有兩種提供方式，二選一。
在 Skill 根目錄創建 config.json：
{
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET"
}
或用環境變量：
export FEISHU_APP_ID="YOUR_APP_ID"
export FEISHU_APP_SECRET="YOUR_APP_SECRET"
配好之後，agent 或 CLI 調用時才能拿到有效的訪問憑證。app_id 和 app_secret 需替換爲實際值，官方資料未提供佔位符之外的示例值。
典型用法¶
官方資料給出了一組可復現的 CLI 調用，下面按動作分別列出。這些都是在 Skill 目錄下執行 node index.js。
讀取文檔內容：
node index.js --action read --token <doc_token>
創建空白文檔：
node index.js --action create --title "My Doc"
覆蓋寫入，--content 接收 Markdown 字符串：
node index.js --action write --token <doc_token> --content "# Title\nHello world"
追加寫入，適合分段補內容：
node index.js --action append --token <doc_token> --content "## Section 2\nMore text"
實際使用時把 <doc_token> 換成真實文檔的 token。創建動作返回的 doc_token 可以接在後續 write / append 裏，形成先建文檔再填內容的順序。
長文檔處理¶
官方資料專門說明了超過 LLM 輸出長度上限時的處理方式。默認單次輸出大約在 2000 到 4000 tokens，長文檔一次寫完會被截斷。
官方建議的做法是分塊追加：
1、先 create 拿到 doc_token。
2、把內容按邏輯章節切分，例如 Introduction、Chapter 1、Chapter 2。
3、逐塊調用 feishu_doc_append 順序追加。
官方明確提醒：文檔很長時不要試圖用一次 feishu_doc_write 寫完整篇，用 append 循環的方式更穩。
這個約束來自模型輸出長度，而不是飛書接口本身，所以內容越長，分塊策略越重要。
適用場景與注意¶
適合的場景：需要把飛書 Wiki、文檔、表格或 Bitable 的內容拉出來轉成 Markdown，再交給 agent 做總結、檢索或二次加工；需要在 agent 裏創建或更新飛書文檔。
需要注意的地方：
必須先裝 feishu-common，否則沒有鑑權。
必須配置 app_id 和 app_secret，否則請求會被拒絕。
write 是覆蓋寫，操作前先 read 確認內容，避免誤覆蓋。
長文檔要分塊 append，不要指望一次 write 完成。
官方安裝命令面向 OpenClaw/clawhub 生態，其他工具的安裝方式官方未說明。
小結¶
這個 Skill 的價值在於把飛書內容的讀取和 Markdown 轉換收斂成一個標準動作，Wiki URL 解析、鑑權依賴和分塊寫入這些細節由 Skill 內部處理，使用者只需要提供 token 和憑證。官方地址：https://api.skillhub.cn/zcwl/feishu-doc
