sugarforever/dsh-lark

DeepSeek Harness Lark / 飞书

@sugarforever/dsh-lark 是一个 DeepSeek Harness Host 插件。安装后，用户可以直接从飞书或 Lark 与 Harness Agent 对话，并继续使用 Harness 中配置的模型、工具、系统提示和会话存储。

插件使用飞书官方 @larksuiteoapi/node-sdk 的 Channel API，通过 WebSocket 长连接接收消息，不需要公网服务器、域名或 Webhook 回调地址。官方 SDK 负责连接、自动重连、消息去重、过期事件过滤、同一聊天的串行处理、消息格式转换和发送回复；插件负责把飞书会话映射到 Harness Session，再把消息交给 Agent。

功能

• 支持飞书中国版和国际版 Lark。
• 使用 WebSocket 长连接接收事件，无需公网回调地址。
• 回复会关联原始消息，并保留在原来的话题线程中。
• 可以通过白名单限制群聊和单聊用户。
• 可以沿用 Harness 默认模型，也可以为飞书渠道指定模型。

运行要求

• Node.js ^22.19.0 或 >=24.0.0。
• 已安装或能够通过 npx 运行 DeepSeek Harness 0.1.0-rc.6 或更高的 0.1.x 版本。
• 一个飞书或 Lark 自建应用。
• 应用已经启用机器人能力。
• 应用使用长连接接收事件，并订阅 im.message.receive_v1。

如果尚未运行过 Harness，可以先启动一次 Web Profile：

npx @deepseek-ai/dsh web

首次启动会创建 web Profile。默认目录是 ~/.dsh/profiles/web；如果设置了 DSH_HOME，则位于 $DSH_HOME/profiles/web。

创建飞书应用

以下名称在飞书中国版和国际版 Lark 控制台中可能略有区别，但配置内容相同。

创建自建应用

1. 打开飞书或 Lark 开发者后台。
2. 创建一个企业自建应用。
3. 填写应用名称、描述和图标。
4. 进入“凭证与基础信息”，记录 App ID 和 App Secret。

不要把 App Secret 直接写进仓库中的 YAML 文件。后续通过 Harness Settings 页面保存，或者通过启动环境变量传给插件。

启用机器人

1. 进入“添加应用能力”。
2. 添加“机器人”能力。
3. 设置机器人名称和头像。

添加权限

默认配置下，应用需要开通以下三个权限：

飞书控制台中显示的中文名称可能随平台版本略有调整，应以权限标识为准。添加 im.message.receive_v1 事件时，控制台通常也会提示补充前两个接收权限。

如果开发者后台支持批量导入权限，可以直接复制下面的配置：

{
  "scopes": {
    "tenant": [
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot"
    ],
    "user": []
  }
}

这组配置对应插件的默认行为：接收单聊消息、接收群聊中 @机器人的消息，以及以机器人身份发送回复。导入后仍需在事件订阅中添加 im.message.receive_v1，并发布新版本，权限和事件配置才会应用到已安装的机器人。

如果需要让机器人处理群聊中没有 @机器人的普通消息，还要额外开通：

im:message.group_msg 的权限范围更大，通常需要企业管理员审批。默认的 requireMention: true 不需要申请这个权限。

有些企业会直接批准范围更大的 im:message 权限，它也可以覆盖消息读取和发送场景，但本插件不要求使用这个宽泛权限。优先申请上表中的最小权限即可。