前言¶
DeepSeek Harness (DSH) 的理念是「一切皆插件」，通過擴展工具讓智能體具備外部交互能力。在辦公場景中，飛書（Lark）生態擁有大量文檔、表格和智能體，但 AI 編程助手通常無法直接訪問這些內容，往往需要人工複製粘貼。
dsh-lark-bridge 插件將飛書開放平臺的能力轉化爲 DSH 可調用的工具。它解決了智能體無法直接讀取文檔、操作多維表格或觸發飛書智能體的問題，使 DSH 代理能夠作爲飛書機器人或服務端接口進行工作。
核心功能¶
該插件主要提供以下能力：
- 憑證解析與自動刷新：通過
tenant_access_token處理身份驗證，支持從環境變量或憑證域解析，無需手動維護 Token。 - 出站消息工具：支持向用戶、羣組發送文本或卡片消息。
- 文檔讀取：提供純文本和結構化塊級內容的讀取能力。
- 多維表格（Bitable）讀寫：支持列表、創建、更新、批量創建記錄。
- 智能體調用：通過消息觸發飛書機器人或智能體。
- 私有聊天入站（Phase 2）：建立長連接接收飛書私聊消息，由 DSH 代理在本地處理並回復。
安裝與啓用¶
安裝插件需要執行以下命令。請將 <your-user> 替換爲你的 GitHub 用戶名。
dsh plugin --profile web add github:<your-user>/dsh-lark-bridge
安裝後，需在配置文件中啓用該 Bundle。DSH 默認讀取 dsh.profile.bundles 列表。
配置說明¶
在插件的配置中，建議優先使用環境變量來存儲密鑰，避免將密鑰直接寫入配置文件。
| 配置項 | 默認值 | 說明 |
|---|---|---|
appIdEnv |
FEISHU_APP_ID |
飛書 App ID 的環境變量名，用於憑證解析。 |
appSecretEnv |
FEISHU_APP_SECRET |
飛書 App Secret 的環境變量名，用於憑證解析。 |
baseURL |
https://open.feishu.cn/open-apis |
飛書開放平臺 API 的基礎地址。 |
timeoutMs |
30000 |
每個工具調用的超時時間。 |
enableSendMessage |
true |
是否註冊發送消息工具。 |
enableReadDoc |
true |
是否註冊文檔讀取工具。 |
enableBitable |
true |
是否註冊多維表格讀寫工具。 |
enableCallAgent |
false |
是否註冊智能體調用工具（默認禁用）。 |
enableInbound |
false |
是否啓用飛書長連接入站功能。 |
示例配置片段：
- id: lark-bridge
name: dsh-lark-bridge
config:
appIdEnv: FEISHU_APP_ID
appSecretEnv: FEISHU_APP_SECRET
baseURL: https://open.feishu.cn/open-apis
enableInbound: true
首次運行與憑證設置¶
首次啓動時，Web UI 會彈出一個對話框，引導用戶輸入飛書 App ID 和 App Secret。這些值通過憑證域（credentials domain）存儲，而不會出現在配置響應中。你也可以通過設置環境變量 FEISHU_APP_ID 和 FEISHU_APP_SECRET 來跳過 UI 輸入。
工具列表¶
插件註冊的工具如下（僅列舉已啓用項）：
feishu_send_message：發送文本或卡片消息。feishu_read_doc：獲取文檔的純文本內容。feishu_list_doc_blocks：獲取文檔的結構化塊級內容（帶標題前綴）。feishu_list_bitable_tables：列出多維表格應用中的所有表。feishu_bitable_list_records：查詢多維表格中的記錄（支持過濾和排序）。feishu_bitable_create_record：創建單條記錄。feishu_bitable_update_record：更新單條記錄（覆蓋式）。feishu_bitable_batch_create_records：批量創建記錄。feishu_call_agent：觸發飛書機器人或智能體（間接調用，通過消息觸發）。feishu_aily_start_skill：直接啓動 Aily（飛書智能夥伴）技能。
私有聊天入站（Phase 2）設置¶
若要啓用入站功能，需在 cordis.patch.yml 中設置 enableInbound: true。
飛書端配置¶
- 使用與出站相同的 App ID / Secret（一個應用即可）。
- 授予應用權限：
im:message、im:message:send_as_bot、im:message.p2p_msg。 - 開啓事件訂閱：長連接接收事件及
im.message.receive_v1。 - 必須先啓動
dsh web，然後再在飛書開放平臺保存長連接設置。 - 注意：同一 App 只能有一個長連接，不要運行多個 WS 客戶端。
工作流¶
enableInbound: true 開啓後，插件會建立飛書長連接（im.message.receive_v1），僅處理私聊（P2P）消息。消息流轉邏輯爲：
飛書 P2P 消息 → 長連接接收 → 創建/恢復 Agent 會話 → Agent 執行回覆 → 通過 IM API 回覆。
注意事項與限制¶
- 私聊限制：入站功能目前僅支持私聊，暫不支持羣組。
- 回覆非流式：入站回覆會等待完整的 Agent 執行完畢後再發送文本。
- 間接調用：
feishu_call_agent是間接調用，因爲飛書沒有直接的服務器端運行 API，需通過發送消息觸發機器人。 - 長連接獨佔：同一 App 只能有一個長連接，避免衝突。
- 安全機制：
appId和appSecret具有安全角色（role('secret')），不會出現在describe()響應中。
總結¶
dsh-lark-bridge 是連接 DeepSeek Harness 與飛書生態的橋樑。通過它，開發者可以將飛書文檔、表格和智能體能力直接注入到 DSH 的工具箱中，實現自動化辦公流程。
