dsh-lark-bridge：飞书智能体桥接 DeepSeek Harness 插件

前言¶

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 的工具箱中，实现自动化办公流程。