前言¶
在 DSH 裏讓 Agent 讀企業飛書裏的雲文檔、表格或羣消息，常見做法是走 bash 調用 lark-cli。DSH 的 bash 在 workspace-write 沙箱裏執行，而 lark-cli 刷新用戶令牌需要寫本機憑據庫，沙箱會拒絕這次寫入，用戶身份調用往往時通時不通。自己寫一層飛書 OpenAPI 又意味着維護憑據與 scope，和「用已有 CLI 登錄態」不是同一條路。
下面介紹社區插件 transsioner-link（npm 包名 transsioner-cli）。它在宿主進程裏直接 spawn lark-cli，複用系統裏唯一那份憑據，把雲文檔、電子表格、多維表格、畫板、評論、妙記以及羣列表與羣消息等能力登記成 DSH 只讀工具；倉庫不含任何憑據，每人用自己的賬號授權。
這是什麼¶
Transsioner-CLI · 飛書連接器 由維護者 canadaeee 發佈，分類爲聯網工具。定位可以概括成：不重新實現飛書 API，不保存憑據，不緩存正文——每次調用都是實時讀取，可見範圍等於你此刻在飛書裏的權限。
倉庫名是 transsioner-link，DSH 按 npm 包名 transsioner-cli 登記 bundle，兩者不衝突。當前 package.json 版本爲 1.3.1，要求 Node >=20、DSH >=0.2.1-rc.3，許可證 MIT。
核心功能¶
插件只註冊讀命令，不提供發消息、改文檔、刪文件等寫操作。主要工具如下（典型入參見 README 工具表）：
| 工具 | 用途 |
|---|---|
feishu_status |
連接自檢：lark-cli 位置、應用、user/bot 狀態、已授權 scope |
feishu_setup |
配置檢查；未配好時給出步驟 |
feishu_search |
按關鍵詞搜雲文檔/知識庫/表格 |
feishu_doc_read |
讀文檔正文（docx、舊版 doc、wiki 節點） |
feishu_sheet_read |
工作表清單或指定區間 CSV |
feishu_bitable_read |
多維表格的數據表與記錄 |
feishu_chat_list |
我所在的羣（可關鍵詞搜索） |
feishu_chat_history |
某個會話的消息記錄 |
feishu_message_search |
跨會話搜消息 |
feishu_whiteboard_read |
讀文檔/畫板裏的節點文字 |
feishu_doc_comments |
文檔、表格、畫板的評論與回覆 |
feishu_minutes_read |
妙記的總結、待辦、章節、關鍵詞 |
約定要點：鏈接與 token 通用；長文檔可先 scope:"outline" 看結構再局部讀；單次返回默認約 3 萬字符，超出會截斷並提示如何繼續。讀文檔側優先使用 lark-cli 的 im-markdown 格式，並在必要時做 DocxXML 本地降級。
憑據與前置條件¶
本倉庫不包含任何憑據、令牌或真實文檔地址。憑據只存在本機 lark-cli 的庫裏（Linux：~/.config/lark-cli/；macOS、Windows 路徑見 README 表格）。第一次使用需用自己的飛書賬號授權：
lark-cli auth status
lark-cli auth login
lark-cli auth login --profile larktest # 需要與日常憑據隔離時
除安裝 lark-cli 並完成授權外，企業自建應用需開通 README「前置條件」中列出的 scope（文檔、表格、多維表格、羣、搜索、知識庫等）。缺權限時可用 feishu_status 逐項覈對，補 scope 後重新 lark-cli auth login。
安裝與啓用¶
DSH 生態裏插件可通過社區目錄頁添加；安裝方式以倉庫 README 爲準，任選其一。
① 在 DSH 插件頁填倉庫地址（推薦）
插件頁 → 添加插件 → 粘貼：
https://github.com/canadaeee/transsioner-link
DSH 會用 pnpm 把倉庫克隆到當前 profile 並登記成 bundle，裝完需重啓生效。固定版本可在地址後加 #v1.1.1 等形式（README 示例）。
② Release 中的 tgz（國內拉 GitHub 不穩時）
https://github.com/canadaeee/transsioner-link/releases/latest/download/transsioner-cli.tgz
③ 本地目錄（自改代碼時）
插件頁 → 添加插件 → 填本目錄絕對路徑；改完代碼重啓即生效。
配置項¶
在 cordis.patch.yml 對應行可調整（節選）：
| 字段 | 默認 | 說明 |
|---|---|---|
larkBin |
自動查找 | PATH 中沒有 lark-cli 時填絕對路徑 |
profile |
當前 profile | 多套飛書應用時指定 |
identity |
user |
user 以你的身份讀；bot 僅機器人可見內容 |
timeoutMs |
60000 |
單次調用超時 |
maxChars |
30000 |
返回給模型的字符上限 |
enableChat |
true |
設爲 false 只保留文檔類工具 |
appId |
空 | 可選；引導文案中的 App ID，源碼不內置 |
homeDir |
空 | 排障用；正常不要設，易造成令牌副本 |
典型用法¶
Agent 在會話裏通過上述工具名調用即可；入參爲 JSON 對象。README 中的示例形態如下。
搜索雲文檔：
{ "query": "週報" }
讀 docx（先看大綱再分段）：
{ "url": "https://…/docx/xxx", "scope": "outline" }
讀表格區間：
{ "url": "…/sheets/xxx", "sheet": "Sheet1", "range": "A1:F30" }
讀羣歷史：
{ "chat": "產品週會", "limit": 20 }
跨會話搜消息（消息搜索不返回羣名，需羣名時可先 feishu_chat_list）：
{ "query": "上線時間", "start": "2026-10-01T00:00:00+08:00" }
類型與 URL 不匹配時，工具會明確提示應改用哪個讀命令。
適用場景與注意¶
適合誰： 已在本地用 lark-cli 登錄企業飛書、希望 DSH Agent 只讀查閱文檔/表格/妙記/羣消息，又不想在沙箱裏反覆撞令牌刷新問題的開發者或團隊。
設計取捨： 這些工具不受 workspace 文件沙箱約束，否則無法穩定複用 lark-cli 憑據庫。插件因此 strictly 只讀；安裝前應查看源碼與 MIT 許可證，只裝信任來源的 bundle。
已知限制（README 摘要）： 舊版 /docs/ 文檔無標題層級與範圍讀取；圖片、內嵌畫板/表格等多爲佔位符；羣消息附件不自動下載；接口頻控時需稍後重試。
社區插件目錄 skillhub.cn 上的 transsioner-link 頁 與 GitHub 倉庫相互獨立引用，目錄站點與 DeepSeek / 幻方無官方從屬關係。
結尾¶
transsioner-link 把本機已登錄的 lark-cli 接成 DSH 只讀工具集，憑據留在 lark-cli，插件側零存儲、零寫接口。若你的 Agent 工作流依賴飛書內的結構化信息，可先完成 lark-cli auth login 與 scope 開通，再在 DSH 中按 README 添加倉庫或 tgz。
- 目錄頁：https://www.skillhub.cn/plugins/canadaeee/transsioner-link
- 源碼與文檔：https://github.com/canadaeee/transsioner-link
