sliverp/DeepSeek-harness-lark

DeepSeek Harness 飞书 / Lark 插件

基于飞书官方 @larksuiteoapi/node-sdk 的 DeepSeek Harness 长连接通道。无需公网 IP 或回调服务器，支持飞书中国版和国际版 Lark。

功能

- 官方 WebSocket 长连接与自动重连
- 单聊和群聊访问策略，群聊默认要求 @机器人
- 普通文字、富文本、图片和普通文件消息输入
- 图片下载后保存为 Harness 附件，并按模型能力启用多模态输入
- 普通文件下载到 Agent 工作目录下的 .dsh-lark/inbox/，可由标准文件工具读取
- 模型文字回复、生成图片上传和工作区文件回传
- 每个聊天独立、可恢复的 Harness 会话；/new 可保留旧记录并切换到空白会话
- 新建与恢复会话均挂载并记录 Harness Agent preset，默认使用 standard
- Harness 已注册斜命令直接执行，不会作为普通文字发送给模型
- 工具审批可在原飞书会话使用一次性的 /approve  或 /reject  决定
- /bot-ping、/bot-help、/bot-image-test、/bot-file-test、/bot-status、/bot-cancel
- App Secret 通过 Harness 凭据服务解析，不写入插件配置
- 未配置 App ID 或 App Secret 时保持休眠，单独安装插件不会阻塞 Harness Web

环境要求

- Node.js 22.19 或更高版本
- pnpm 10.33.4
- DeepSeek Harness 0.1.0-rc.7 或更高版本

安装

pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-lark

本地开发版本：

pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-lark

飞书开放平台配置

1. 在飞书开放平台创建企业自建应用并启用机器人能力。
2. 添加权限：im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:readonly、im:message:send_as_bot、im:resource。其中，用户发送的图片和文件必须通过“消息中的资源”接口下载，该接口需要 im:message:readonly。
3. 在「事件与回调」选择「使用长连接接收事件」，订阅 im.message.receive_v1（接收消息）。
4. 创建并发布应用版本，将机器人加入需要使用的聊天。
5. 把 App ID 写入 LARK_APP_ID，把 App Secret 保存为 Harness 凭据 LARK_APP_SECRET。

开发时可从环境变量注入：

export LARK_APP_ID='cli_your-app-id'
export LARK_APP_SECRET='your-app-secret'
pnpm dsh --profile web

长期运行时，建议把 App ID 放在 ~/.dsh/.env，并通过 Harness 凭据设置界面保存 App Secret。不要把真实凭据提交到 Git。

配置

安装包默认添加：

- id: lark-channel
name: deepseek-harness-lark
config:
appId: !!js process.env.LARK_APP_ID
appSecretRef: LARK_APP_SECRET
cwd: !!js process.env.DSH_LARK_CWD ?? process.cwd()

需要国际版 Lark、群聊白名单或其他策略时，可在配置中覆盖：

domain: lark
singlePolicy: allowlist
singleAllowFrom: [ou_xxx]
groupPolicy: allowlist
groupAllowChats: [oc_xxx]
groupRequireMention: true
imageInputMode: auto
maxInboundFiles: 10
maxInboundFileBytes: 52428800
maxInboundMessageFileBytes: 104857600
maxReplyFiles: 5
maxOutboundFileBytes: 31457280
approvalTimeoutMs: 240000
agentPreset: standard

访问策略可选 open、allowlist、disabled。生产环境建议使用白名单，并为 agent 配置最小文件和工具权限。

连接和鉴权在后台运行。缺少或错误的飞书凭据只会让该通道保持离线并记录日志，不会阻塞 Harness 启动。

用户发送的图片和普通文件会通过消息级资源接口，使用相匹配的 message_id 与资源 Key 下载；该接口需要 im:message:readonly（或范围更大的 im:message）。单独的 im:resource 权限仍用于机器人上传图片和文件。插件会把文件名收敛为安全的叶子文件名，以不覆盖已有路径的方式写入 /.dsh-lark/inbox/ 下每条消息独立的目录。默认最多接收 10 个文件、单文件 50 MiB、单条消息合计 100 MiB。模型只会收到保存路径，并通过正常文件工具读取；插件不会执行文件，也不会把文件内容悄悄塞进提示词。

模型需要主动回传工作区文件时，会在本回合最终可见回复中放置明确的 Markdown 文件链接。插件会解析真实路径，拒绝不存在的文件、目录、符号链接逃逸以及 session cwd 之外的任何目标，再通过飞书文件接口上传经过大小限制的字节。插件只检查最终 assistant 消息，中间工具输出不会触发文件发送。默认每次回复最多发送 5 个非空文件，单文件上限为 30 MiB。

Harness 请求工具审批时，插件会向原飞书会话发送绑定请求者的六位短码。回复 /approve  只允许该操作一次，回复 /reject  拒绝该操作。短码只能消费一次，不能跨会话使用；原回合等待期间会绕过普通消息容量限制。超时、取消、发送失败或服务退出都会按失败闭合。approvalTimeoutMs 必须小于 responseTimeoutMs。

agentPreset 是新会话和无 preset 旧记录的明确回退配置。修复工具调用链后，插件 session namespace 已从 lark-v1- 升级为 lark-v2-：旧 session 文件不会删除或改写，但插件不再续写可能已被 DSML 文本污染的 lark-v1-* 记录。Web 仍可查看这些旧记录。

验证

启动后向机器人发送：

/bot-ping
/bot-image-test
/bot-file-test
/new

前三个命令应分别返回 pong、蓝色图片和可下载的文本文件；/new 应确认已切换到空白会话。再发送普通文字、一张图片和一个 CSV 文件，并让机器人读取 CSV，以验证文件确实下载到了工作目录且可由工具访问。随后让机器人创建并发送一个 CSV，最终回复中应收到文件附件。最后请求一个需要审批的操作，并原样回复机器人给出的 /approve  或 /reject ；同一回合应继续或停止，网页不应接管这次审批。

开发

pnpm install
pnpm run check
pnpm pack

仓库使用 PNPM 10.33.4；插件运行时要求 Node.js >=22.19，不要求 PNPM 11。

协议与配置参考 larksuite/openclaw-lark；传输和媒体能力由飞书官方 Node SDK 提供。本项目使用 MIT 许可证。