飞书一体化通道tkwkeven/dsh-lark-all

dsh-lark-all — DeepSeek Harness 飞书 / Lark 一体化插件

基于飞书官方 @larksuiteoapi/node-sdk 的 DeepSeek Harness 长连接通道 + 进程重启恢复通知合并插件。使用官方 WebSocket 长连接接收事件，无需公网 IP、无需回调服务器，同时支持飞书中国版与国际版 Lark。

一个包、一次安装，同时提供两个插件入口：

| 入口 | 插件 ID | 作用 |
| --- | --- | --- |
| dsh-lark-all | lark-channel | 飞书/Lark 消息通道桥：收发消息、并行任务会话、流式卡片、媒体与云文档 |
| dsh-lark-all/ops | dsh-ops | 重启恢复通知：进程重启完成后向发起重启的聊天发送恢复提示 |

功能特性

通道与消息

- 官方 WebSocket 长连接 + 自动重连，无公网服务器
- 单聊 / 群聊访问策略（open / allowlist / disabled），群聊默认要求 @机器人
- 文字、富文本、图片消息输入；图片按模型能力启用多模态输入，超大「原图」自动降级为工作区文件并告知模型路径
- 文件 / 语音 / 视频入站：自动下载到 .lark-inbox/，文本类文件附带内容预览，模型读路径即可处理
- 飞书云文档（docx）分享入站：自动读取正文内容供模型回答
- 模型文字回复、生成图片上传发送
- 收到消息立即添加「进行中」表情（默认 Typing），完成后移除，可选添加完成表情
- 每个聊天独立、可恢复的 Harness 会话；消息路由决策写入 /.lark-routing.log 便于排查

并行任务会话（核心特性）

- 消息以 任务： 开头（或 ptc任务： / 标准任务： / 极简任务： / 创造任务： 指定 agent preset）创建独立、可持久化的 Harness 会话——相当于 Web 端新建对话
- 每个任务在各自的话题中运行，带实时流式交互卡片：蓝色「🧠 任务执行中」→ 完成绿色「✅ 任务完成」/ 失败红色「⚠️ 任务失败」，正文展示任务标题、模式与会话、状态、耗时、轮次步骤、最近工具、思考摘要（240 字）与任务清单（最多 3 项）
- 卡片更新按 1200ms 最小间隔节流，终态立即推送并冻结；同一聊天内多个任务并行执行（chatQueue: false 默认）
- 话题内继续发消息即继续该任务会话（自动归属，无需依赖 root_id/thread_id）；每轮生成一张新的「第 N 轮」卡片
- 超长报告按每页 3500 字符分页，避开代码块、尽量在标题处断页，每页以回复形式投递到任务话题内
- 恢复旧的严格串行行为：设置 chatQueue: true

出站媒体

| 方式 | 说明 |
| --- | --- |
| 斜杠命令 | /bot-send-file（文件 ≤30MB）、/bot-send-image（原图 ≤10MB）、/bot-send-voice（opus 语音）、/bot-send-video（mp4 视频）、/bot-send-doc（markdown 生成飞书云文档） |
| 模型回复标记 | 模型在回复中单独一行输出 [lark-file: 路径]、[lark-image: 路径]、[lark-voice: 路径]、[lark-video: 路径]、[lark-doc: 路径] 即可附带媒体（标记行不显示在回复中） |
| 大文件 | 超过 IM 上限且开启 driveLargeFiles 时，自动分片上传云空间并回复分享链接（≤200MB） |
| 安全边界 | 本地文件必须位于 outboundAllowedDirs（默认 cwd）内，realpath 校验防路径穿越；URL 由 SDK 内置 SSRF 防护兜底 |

进程重启与恢复通知（ops）

- 在主聊天发送配置的重启命令（默认 重启进程）即可安全重启 DSH 进程：写入重启标记 → 调度 detached 重启（优先 dsh-safe-restart.ps1 安全重启脚本，失败自动回滚配置；否则使用内置 detached helper）→ 延迟退出
- 进程恢复后，dsh-ops 检测到重启标记，向发起重启的聊天发送 ✅ DSH 进程已恢复，重启完成 通知并清除标记；通知失败保留标记下次重试

凭据安全

- App Secret 通过 Harness 凭据服务（credentialRef）解析，不写入插件配置；App ID 建议通过环境变量注入

安装

方式一：直接安装到 DSH profile

从 GitHub Releases 安装（发布后）
pnpm dsh plugin --profile web add https://github.com/tkwkeven/dsh-lark-all/releases/download/v1.0.0/dsh-lark-all-1.0.0.tgz

本地源码目录安装（开发）
pnpm dsh plugin --profile web add /absolute/path/to/dsh-lark-all

方式二：从源码构建安装

git clone https://github.com/tkwkeven/dsh-lark-all.git
cd dsh-lark-all
pnpm install
pnpm build        # 产出 dist/index.js（含 d.ts 与 source map）
pnpm pack         # 产出 dsh-lark-all-1.0.0.tgz

飞书开放平台配置

1. 在飞书开放平台创建企业自建应用，启用「机器人」能力。
2. 添加权限：
- 必选：im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:send_as_bot、im:resource
- 「进行中表情」：im:message.reactions:write_only
- 可选：docx:document（云文档收发）、drive:drive（大文件上传云空间）
3. 在「事件与回调」选择「使用长连接接收事件」，订阅 im.message.receive_v1（接收消息）。
4. 创建并发布应用版本，把机器人加入需要使用的聊天。
5. 配置凭据（二选一）：

开发时环境变量注入
export LARK_APP_ID='cli_your-app-id'
export LARK_APP_SECRET='your-app-secret'
pnpm dsh --profile web

长期运行推荐：App ID 放 ~/.dsh/.env，App Secret 通过 Harness 凭据设置界面保存（引用名 LARK_APP_SECRET）

⚠️ 不要把真实凭据提交到 Git。

DSH 配置

插件包自带 cordis.patch.yml，安装后自动插入两行：

- insert:
- id: lark-channel
name: dsh-lark-all
config:
appId: !!js process.env.LARK_APP_ID
appSecretRef: LARK_APP_SECRET
cwd: !!js process.env.DSH_LARK_CWD ?? process.cwd()
responseTimeoutMs: 21600000
- id: dsh-ops
name: dsh-lark-all/ops
config:
appId: !!js process.env.LARK_APP_ID
appSecretRef: LARK_APP_SECRET
cwd: !!js process.env.DSH_LARK_CWD ?? process.cwd()

在 profile 自己的 cordis.patch.yml（最后应用的一层）中覆盖配置：

- id: lark-channel
config:
appId: cli_your-app-id        # 建议保留环境变量方式
singlePolicy: allowlist
singleAllowFrom: [ou_xxx]
groupPolicy: allowlist
groupAllowChats: [oc_xxx]
taskReasoningEffort: max      # 任务会话固定的推理强度
restartExitDelayMs: 2000      # 重启时退出延迟（配合 relaunch helper）

完整配置项

访问策略与输入

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| domain | feishu | feishu（中国版）或 lark（国际版） |
| singlePolicy / groupPolicy | open | open / allowlist / disabled |
| singleAllowFrom / groupAllowChats | [] | 白名单（ou_ / oc_） |
| groupRequireMention | true | 群聊要求 @机器人 |
| respondToMentionAll | false | 响应 @所有人 |
| imageInputMode | auto | auto / always / never |
| replyInThread | false | 回复是否进话题 |

超时与回复

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| responseTimeoutMs | 300000 | 单轮回复上限（合并版默认 6 小时） |
| mediaDownloadTimeoutMs | 30000 | 媒体下载超时 |
| sendTimeoutMs | 30000 | 发送超时 |
| sendRetries | 2 | 发送重试次数 |
| maxReplyChars | 20000 | 单条回复上限 |
| maxReplyImages | 4 | 单条回复图片上限 |

入站媒体

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| inboundFiles | true | 接收文件到 inbox |
| inboundMedia | true | 接收语音/视频到 inbox |
| inboundDir | '' | 自定义 inbox 目录（空用 /.lark-inbox） |
| inboundResourceLimitBytes | 104857600 | 入站资源上限（飞书 100MB） |
| inboundTextPreviewChars | 6000 | 文本类文件预览长度 |

出站媒体

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| outboundMedia | true | 出站媒体总开关（命令 + 标记） |
| outboundAllowedDirs | [] | 允许的出站本地目录（空默认 [cwd]） |
| maxOutboundFileBytes | 31457280 | 文件上限（30MB） |
| maxOutboundAudioBytes | 31457280 | 语音上限 |
| maxOutboundVideoBytes | 31457280 | 视频上限 |
| maxOutboundImageBytes | 10485760 | 图片上限（10MB） |
| driveLargeFiles | false | 超限文件改传云空间并回复链接 |
| maxDriveFileBytes | 209715200 | 云空间上传上限（200MB） |
| sendFileMarkers | true | 解析模型回复 [lark-: 路径] 标记 |
| docxInbound | true | 读取 docx 分享内容 |
| docxOutbound | true | 允许 /bot-send-doc 与 [lark-doc:] |

任务会话

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| taskSessions | true | 任务会话总开关 |
| taskPresets | {} | 额外前缀 → agent preset 映射 |
| taskDefaultPreset | code | 裸 任务： 前缀使用的 preset |
| taskReasoningEffort | max | 新建任务会话固定的推理强度（模型不支持时会按路由自动收敛） |
| reportIdentity | wdsh | 任务报告前缀中的身份标识 |
| taskCounterFile | '' | 每日任务计数器路径 |
| chatQueue | false | 关闭（默认）→ 任务并行；true → 同聊天严格串行 |

重启

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| restartCommand | 重启进程 | 主聊天中触发的重启命令 |
| restartMarkerFile | '' | 重启标记路径（ops 消费） |
| restartLaunch | dsh web | 重启后启动的命令行 |
| restartLogFile | '' | 重启后进程日志 |
| restartExitDelayMs | 4000 | 调度重启后退出延迟 |

其他

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| progressReaction | true | 收到消息先添加进行中表情 |
| progressEmoji | Typing | 进行中表情（Typing/THUMBSUP/THINKING/GLANCE/Fire…） |
| doneEmoji | '' | 完成表情（如 CheckMark；空 = 关闭） |
| maxInFlightMessages | 8 | 并行处理上限 |
| systemPrompt | 内置 | 通道系统提示词覆盖 |

使用方法

1. 基础命令（发给机器人）

| 命令 | 说明 |
| --- | --- |
| /bot-ping | 连通性检查，返回 pong |
| /bot-help | 查看命令帮助 |
| /bot-image-test | 发送蓝色测试图片，检查图片链路 |
| /bot-status | 查看连接状态 |
| /bot-cancel | 取消当前生成 |

2. 普通聊天

直接发文字、图片、文件、语音、视频或云文档分享即可。普通消息进入该聊天的常驻 Harness 会话，与 Web 端同一套模型配置。

3. 并行任务会话

任务：帮我调研一下开源社区的 Cordis 插件生态
ptc任务：写一个 PowerShell 脚本批量重命名文件
标准任务：总结这篇文档的要点
极简任务：翻译这段话
创造任务：设计一个产品原型方案

- 每条任务消息创建独立会话并在话题中运行，带实时流式卡片
- 任务还在运行时，继续发 任务：… 即可并行处理
- 在任务消息的话题（或回复任务消息的回复链）里继续发消息 = 继续该任务会话，每轮一张新的「第 N 轮」卡片
- 任务完成后，报告以回复形式投递到话题内；超长报告自动分页

4. 发送媒体

/bot-send-file C:\path\to\demo.txt
/bot-send-image C:\path\to\photo.png
/bot-send-voice C:\path\to\audio.opus
/bot-send-video C:\path\to\clip.mp4
/bot-send-doc C:\path\to\report.md

也可以让模型在回复中直接输出标记（独立一行）：

[lark-file: C:\path\to\demo.txt]
[lark-image: C:\path\to\photo.png]
[lark-doc: C:\path\to\report.md]

超过 IM 上限的文件在开启 driveLargeFiles 后自动上传云空间并回复分享链接。

5. 接收媒体

- 文件：下载到 /.lark-inbox/-/，文本类文件附带内容预览，可直接问文件内容相关问题
- 语音/视频：下载到 inbox 并告知时长与路径
- 原图：超过附件限制的图片自动降级为 inbox 文件并告知路径
- 云文档：docx 分享自动读取正文；sheet/bitable 识别名称与链接

6. 重启进程

在主聊天发送 重启进程（可配置 restartCommand）。机器人回复确认后调度安全重启，约 10~60 秒后恢复；dsh-ops 会向该聊天发送恢复通知。

7. 验证链路

/bot-ping        → pong
/bot-image-test  → 文字 + 蓝色图片

再发普通文字和一张图片验证模型与入站附件链路；发 demo.txt 后 /bot-send-file C:\绝对\路径\demo.txt 验证文件出站；向机器人发送一个文件或语音验证入站下载。

安全建议

- 生产环境使用白名单策略（singlePolicy / groupPolicy: allowlist），并为 agent 配置最小文件和工具权限
- App Secret 只存 Harness 凭据服务，App ID 走环境变量，绝不写进配置或提交 Git
- 出站媒体目录用 outboundAllowedDirs 收窄；不要在允许目录里放敏感文件
- 群聊保持 groupRequireMention: true 防止误触发

开发

pnpm install
pnpm check      # tsc --noEmit + esbuild 打包校验
pnpm build      # 产出 dist/index.js（esbuild 打包，@deepseek-ai/ 保持 external）
pnpm pack       # 产出 .tgz

源码结构：

src/
├── index.ts          # 插件入口（name/inject/Config/apply）
├── bridge.ts         # 通道桥：连接、消息路由、命令、重启调度
├── conversations.ts  # 会话管理：普通会话 + 并行任务会话 + 卡片流
├── card.ts           # 流式交互卡片状态机与渲染
├── inbound.ts        # 入站内容解析（文本/图片/文件/语音/视频）
├── media.ts          # 出站媒体构造与发送
├── docx.ts           # 飞书云文档读写
├── drive.ts          # 云空间大文件分片上传
├── config.ts         # 配置 schema（schemastery）
└── util.ts           # 工具函数
ops.js                # 重启恢复通知（直接执行的纯 JS 入口）

致谢与许可

协议与配置行为参考 larksuite/openclaw-lark；通道桥核心源自 sliverp/DeepSeek-harness-lark（MIT）。本项目在二者基础上合并增强，使用 MIT 许可证；打包产物中的第三方软件见 THIRD_PARTY_NOTICES.md。