前言¶

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