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.p2p_msg:readonly	获取用户发给机器人的单聊消息	接收用户与机器人的单聊消息	是
im:message.group_at_msg:readonly	获取群组中 @机器人的消息	接收群聊中明确 @机器人的消息	是
im:message:send_as_bot	以应用的身份发消息	让机器人回复单聊、群聊和话题消息	是

飞书控制台中显示的中文名称可能随平台版本略有调整，应以权限标识为准。添加 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: false 接收群内全部消息	仅关闭 @限制时需要

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

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

权限变更可能需要企业管理员审批。测试时如果机器人能够加入聊天，但收不到消息或不能回复，先检查权限是否仍处于待审批状态。

配置长连接事件

1. 进入“事件与回调”或“事件订阅”。
2. 在事件接收方式中选择“使用长连接接收事件”。
3. 不要填写 Webhook 请求地址。
4. 添加事件 im.message.receive_v1。
5. 保存配置。

长连接模式由插件主动连接飞书，因此本地电脑、内网服务器和没有公网入口的开发环境都可以运行。

发布并安装应用

1. 创建应用版本。
2. 提交审核或发布到测试范围。
3. 将应用安装到当前企业或测试企业。
4. 在飞书中找到机器人并发起单聊，或者把机器人加入测试群。

只修改后台配置但没有发布新版本时，事件和权限通常不会在正式应用中生效。

安装插件

从 npm 安装到 Harness Web Profile：

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

Harness 的 Agent、Session、Settings 等服务由 Profile Bundle 在运行时提供。 插件将这些包声明为 optional peer，以适配 DSH 的 Bundle 加载机制；它不会在 Profile 中重复安装另一套 Harness。从 0.2.3 起兼容 0.1.0-rc.7、 0.1.2-rc.1 及稳定的 0.1.x 版本，并通过 CI 持续验证最新发布的 Harness 版本，因此升级到后续 RC 通常不需要重新发布插件。

查看已经安装的插件：

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

开发本项目时，也可以安装本地目录：

git clone https://github.com/sugarforever/dsh-lark.git
cd dsh-lark
npm install
npm test
npm run typecheck
npm run build
npx @deepseek-ai/dsh plugin --profile web add "$PWD"

插件安装后保持启用，但在 App ID 和 App Secret 尚未配置时不会建立飞书连接。这样安装完成后就能直接配置，而不必编辑 profile patch。

启动 Harness

启动 Web Profile：

npx @deepseek-ai/dsh web

…