前言¶

DeepSeek Harness（DSH）把模型、工具、系統提示和會話存儲收攏在一個 Host 裏，日常開發多在 Web 客戶端或終端裏操作。團隊溝通卻常在飛書或 Lark 上完成——如果要讓同事在聊天窗口裏直接問 Agent，常見做法是自建 Bot 服務、配公網 Webhook，再把消息轉發到後端。鏈路長、部署門檻高，內網或本地開發環境往往還要額外打通回調地址。

@sugarforever/dsh-lark 是社區維護的 DSH Host 插件，由 sugarforever 發佈，在 SkillHub 歸類爲「模型推理」。它用飛書官方 @larksuiteoapi/node-sdk 的 Channel API，通過 WebSocket 長連接收消息，把飛書會話映射到 Harness Session，再交給已配置的 Agent 處理。安裝後，用戶可在飛書單聊、羣聊或話題裏對話，並沿用 Harness 裏的模型、工具與 Preset，無需單獨搭公網回調服務。

這是什麼¶

@sugarforever/dsh-lark（npm 包名，當前版本 0.2.2，MIT 許可證）是 DeepSeek Harness 的飛書 / Lark 渠道插件。插件負責會話映射與消息轉發；連接管理、自動重連、消息去重、格式轉換和回覆發送由官方 SDK 處理。

與「自建中間服務 + Webhook」相比，長連接模式下插件主動連飛書，本地電腦、內網機器或無公網入口的環境均可運行。

核心功能¶

以下能力均來自項目 README 與 package.json 說明：

• 支持飛書中國版（domain: feishu）和國際版 Lark（domain: lark）。
• WebSocket 長連接接收 im.message.receive_v1 事件，不需要公網服務器、域名或 Webhook 地址。
• 單聊與普通羣聊按聊天覆用 Harness Session；話題羣按 chat_id + thread_id 使用獨立 Session。
• 回覆關聯原始消息，並保留在對應話題線程中。
• 羣聊默認需 @機器人（requireMention: true）；單聊默認開放（dmMode: open）。
• 可通過 groupAllowlist、dmAllowlist 限制羣聊與單聊用戶；單聊也可設爲 disabled。
• 可沿用 Harness 默認模型，或通過 provider、model 爲飛書渠道單獨指定。
• 會話標識經 SHA-256 處理，原始 chat_id 不會寫入 Session ID。
• Harness 內部錯誤不會直接把堆棧發給飛書用戶，可配置 errorMessage。
• 支持在 Settings 頁面配置，或通過 profile patch、環境變量部署；憑據與 App Secret 分離存儲。

運行要求¶

開始安裝前，確認環境滿足 README 列出的條件：

• Node.js ^22.19.0 或 >=24.0.0。
• 已安裝或能通過 npx 運行 DeepSeek Harness 0.1.0-rc.6 或更高的 0.1.x 版本。
• 一個已啓用機器人能力、訂閱 im.message.receive_v1、並選擇「長連接接收事件」的飛書或 Lark 自建應用。

若尚未運行過 Harness，可先啓動 Web Profile 以創建默認配置目錄：

npx @deepseek-ai/dsh web

首次啓動會創建 web Profile，默認位於 ~/.dsh/profiles/web；若設置了 DSH_HOME，則在 $DSH_HOME/profiles/web。

創建飛書應用¶

下面介紹在飛書或 Lark 開發者後臺需要完成的配置。中國版與國際版控制檯名稱可能略有差異，權限標識以文檔爲準。

記錄憑證¶

1. 創建企業自建應用，填寫名稱、描述和圖標。
2. 在「憑證與基礎信息」中記錄 App ID 和 App Secret。

不要把 App Secret 寫進倉庫裏的 YAML。後續通過 Harness Settings 頁面保存，或用環境變量傳入。

啓用機器人與權限¶

1. 在「添加應用能力」中添加「機器人」，設置名稱和頭像。
2. 開通以下權限（默認行爲所需的最小集合）：

若後臺支持批量導入，可使用 README 提供的 scopes JSON；導入後仍需在事件訂閱中添加 im.message.receive_v1 併發布新版本。

若要將 requireMention 設爲 false、處理羣內未 @ 的消息，還需額外申請 im:message.group_msg，通常需企業管理員審批。

配置長連接事件¶

1. 進入「事件與回調」或「事件訂閱」。
2. 選擇「使用長連接接收事件」，不填寫 Webhook 地址。
3. 添加事件 im.message.receive_v1 並保存。
4. 創建應用版本，發佈或安裝到測試企業，在飛書中找到機器人發起單聊或拉入羣聊。

安裝與啓用¶

從 npm 安裝到 Harness Web Profile：

npx @deepseek-ai/dsh plugin --profile web add @sugarforever/dsh-lark

查看已安裝插件：

npx @deepseek-ai/dsh plugin --profile web list

插件安裝後保持啓用；在 App ID 與 App Secret 未配置前不會建立飛書連接，便於先裝插件再在 UI 裏填憑據。

啓動 Harness：

npx @deepseek-ai/dsh web

打開 Settings，選擇 飛書與 Lark，配置 App ID、App Secret、域名（feishu 或 lark）、訪問策略和 Agent 參數。Provider 與 Model 來自 Harness 模型目錄；留空則跟隨 Harness 默認配置。

保存後，普通參數寫入 $DSH_HOME/settings.yaml 的 lark-channel 段；App Secret 通過 Harness Credentials 存入 $DSH_HOME/.credentials.yaml，不會在 Host 回顯到瀏覽器。配置或憑據變更後，插件會關閉舊 WebSocket 並重建 channel，一般無需重啓 Harness。

容器或 CI 場景可用環境變量傳入 Secret（默認引用名 DSH_LARK_APP_SECRET，啓動時凍結，修改後需重啓進程）：

export DSH_LARK_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npx @deepseek-ai/dsh web

也可在 profile patch 中提供基礎配置（勿重複 insert 同名 lark-channel 實例）：

- id: lark-channel
  config:
    appId: cli_xxxxxxxxxxxxxxxx
    appSecretRef: DSH_LARK_APP_SECRET
    domain: feishu

連接成功時，終端會出現 dsh-lark: WebSocket connected；網絡中斷時 SDK 會嘗試重連並輸出相應日誌。

典型用法¶

單聊驗證¶

1. 在飛書中打開機器人，發送普通文本消息。
2. 等待 Harness 完成當前 Agent turn。
3. 機器人回覆該 turn 最後生成的 assistant 文本；同一單聊後續消息複用同一 Session，可保留前文。

羣聊驗證¶

1. 將機器人加入羣聊。
2. 使用 @機器人 加問題發送。
3. 機器人回覆觸發它的那條消息。默認忽略未 @ 的羣消息。

話題羣¶

話題內消息使用獨立 Session，不同話題不共享記錄；回覆留在原話題線程中。

訪問控制示例¶

只允許指定羣使用：

requireMention: true
groupAllowlist:
  - oc_group_one
  - oc_group_two

只允許指定用戶單聊：

dmMode: allowlist
dmAllowlist:
  - ou_user_one
  - ou_user_two

完全關閉單聊：

dmMode: disabled

固定工作區與 Preset¶

若希望機器人始終操作某個項目目錄，可顯式配置：

workspace: /absolute/path/to/workspace
agentPreset: coding

未配置 workspace 時使用 Harness Workspace 列表中的第一個；未配置 agentPreset 時使用 Harness 當前默認 Preset。provider 與 model 建議同時設置，否則跟隨 Harness 默認模型。

完整配置項可參考 README 中的 lark-channel 示例，包括 errorMessage（Agent 失敗時返回給用戶的文本，最長 500 字符）等字段。

適用場景與注意¶

適合誰

• 已在用 DSH 管理 Agent、模型與工具，希望團隊在飛書 / Lark 裏直接對話同一套配置的團隊。
• 無法或不想維護公網 Webhook、但可以在本機或內網長期運行 DSH 進程的環境。
• 需要按羣、按用戶做白名單，或爲飛書渠道單獨指定模型與 coding Preset 的場景。

使用前請注意

• 插件以當前 DSH 進程的用戶權限運行，Agent 能訪問的工作區與工具能力取決於該進程配置；安裝前應閱讀 源碼 與 MIT 許可證，確認符合組織安全要求。
• App Secret 不要提交到版本庫；優先用 Settings 或 DSH_LARK_APP_SECRET 管理憑據。
• 權限變更可能需要企業管理員審批；機器人能進羣但收不到消息時，先檢查權限與事件訂閱是否已發佈生效。
• SkillHub 是獨立的 DSH 插件社區目錄，與 DeepSeek / 幻方無官方從屬關係；插件由社區維護，GitHub 當前約 24 stars、6 forks。
• 兼容 Harness 0.1.0-rc.6 起的 0.1.x；大版本升級時留意 README 與 CHANGELOG 中的 Session 版本說明。

結尾¶

經過上面的步驟，@sugarforever/dsh-lark 把飛書聊天窗口接到 Harness 的 Session 與 Agent 上：長連接免公網回調，會話與話題映射清晰，配置可走 UI 也可走 patch 與環境變量。若你已在用 DSH 做智能體開發，這個插件提供了一條相對直接的 IM 接入路徑。

• 目錄頁：https://www.skillhub.cn/plugins/sugarforever/dsh-lark
• GitHub：https://github.com/sugarforever/dsh-lark