dsh-lark
English | 中文
极简的 DeepSeek Harness 飞书网关插件：在飞书里 @机器人 或私聊，就能驱动你机器上的 dsh Agent 干活，回复自动送回原会话。一个话题 = 一个 Agent 会话。
灵感来源于 botmux——把飞书接到各家 AI coding CLI 的先行者。dsh-lark 借鉴了它「话题即会话、@ 即派活」的交互，把这套体验以原生插件的形式带进 DeepSeek Harness。
设计目标只有三个：好用、架构干净、轻量。核心源码 4 个文件、约 600 行，没有卡片流水线、没有配对码、没有多项目路由——只保留"和飞书通信"这件事最核心的部分。
功能
- 飞书长连接：WebSocket 收消息，不需要公网回调地址，本机就能跑
- 会话映射：私聊一人一会话；话题内按话题隔离、普通群按群共享会话（也可配置按发送人）；从不主动创建话题——你在哪说，它就在哪回；会话持久化，重启后自动接上
- 图片输入：飞书发图直接进入模型（原生多模态，需模型支持）
- 文件送出：Agent 可用内置
lark_deliver工具把工作目录里的文件 / 图片发回飞书（严格限制在工作目录内） - 单卡片交互：一条任务 = 一张卡片，原地更新到底——状态（执行中→完成/停止/出错）、执行步骤实况（每次工具调用一行）、回复正文全在卡内，底部按钮直达 dsh Web；从不撤回任何消息，超长回复才追加一条全文消息
- 工具审批：Agent 要执行敏感操作时，飞书里弹出带「允许一次 / 拒绝」按钮的审批卡片，点一下即可（也支持
/approve//reject命令，dsh Web 面板同时可用，谁先处理谁生效） - 默认安全：open_id 白名单默认开启；陌生人会收到一次自己的 open_id，复制给部署者加白即可
安装（一条命令）
dsh plugin --profile web add "github:keepview/dsh-lark"构建产物直接在仓库里（lib/），装完即用，无需本地构建。
配置
1. 创建飞书自建应用
在 飞书开放平台 创建企业自建应用：
1. 添加机器人能力（应用能力 → 机器人） 2. 开通权限（权限管理）： - im:message（接收与发送消息） - im:message:send_as_bot（以机器人身份发消息） - im:resource（下载消息中的图片） 3. 事件订阅：订阅方式选择「使用长连接接收事件」，添加事件 im.message.receive_v1（接收消息） 4. 回调配置：「事件与回调 → 回调配置」同样选择「使用长连接」（审批卡片的按钮点击走这里，不配按钮无响应） 5. 发布版本，拿到 App ID 和 App Secret
2. 提供凭证
推荐用环境变量（也可写进 dsh profile 配置）：
export DSH_LARK_APP_ID=cli_xxx
export DSH_LARK_APP_SECRET=xxx
export DSH_LARK_ALLOWED_OPEN_IDS=ou_xxx # 你的 open_id；首次不知道就先发一条消息，机器人会告诉你
cd your-project
npx @deepseek-ai/dsh web> 没配凭证时插件会待机并打印提示，不影响 dsh 本体启动；凭证错误导致连接失败同样只报错不拖垮 dsh。
3. 开聊
- 私聊：直接给机器人发消息
- 群聊：把机器人拉进群，@机器人 发任务；话题群里每个话题是独立会话
配置项
| 配置 | 环境变量 | 默认 | 说明 |
|---|---|---|---|
appId | DSH_LARK_APP_ID | — | 飞书应用 App ID（必填） |
appSecret | DSH_LARK_APP_SECRET | — | 飞书应用 App Secret（必填） |
brand | — | feishu | feishu 或 lark（国际版） |
cwd | DSH_LARK_CWD | 启动目录 | Agent 工作目录 |
provider / model | — | dsh 默认模型 | 覆盖模型选择 |
requireMention | — | true | 群聊是否必须 @机器人 |
groupSessionScope | — | thread | 群会话隔离粒度：thread / chat / sender |
allowedOpenIds | DSH_LARK_ALLOWED_OPEN_IDS | [] | 用户白名单（逗号分隔） |
allowAllUsers | DSH_LARK_ALLOW_ALL_USERS | false | 放开所有用户（慎用） |
agentPreset | — | 部署默认 | Agent 预设 id，决定 agent 拥有的工具集（bash、web_search 等） |
approvals | — | true | 工具审批转发到飞书 |
autoApprove | DSH_LARK_AUTO_APPROVE | false | 全自动允许所有审批（完全信任，慎用） |
imageInput | — | true | 图片原生进入模型 |
sessionCard | — | true | 每条任务发一张可更新的状态卡片 |
webUrl | DSH_LARK_WEB_URL | http://127.0.0.1:3080 | 卡片按钮打开的 dsh Web 地址 |
maxReplyChars | — | 30000 | 单次回复最大字符数 |
命令
| 命令 | 说明 |
|---|---|
| 直接发消息 | 交给当前 Agent 处理 |
/steer <内容> | 任务运行中补充或纠正 |
/stop | 停止当前任务 |
/new | 开一个全新会话 |
/sessions | 列出当前对话的历史会话 |
/resume <id> | 恢复历史会话 |
/approve / /reject | 处理工具审批 |
/status | 连接与会话状态 |
/help | 帮助 |
其他 /命令 会透传给 Harness 原生命令系统。
架构
src/
index.ts Cordis 插件入口（30 行）：注入服务、生命周期
config.ts 配置 Schema + 环境变量合并（100 行）
sessions.ts 会话键 / 会话 ID / 小工具（70 行）
gateway.ts 飞书通道 ↔ Agent 双向桥（400 行）- 飞书协议层完全交给官方
@larksuiteoapi/node-sdk（长连接、重连、去重、限流、markdown 转换），本插件不重复造轮子 - Agent 层完全走 dsh 公开 API（
ctx.agents/session/event/followup），不碰内部实现 - 打包产物零运行时依赖（Lark SDK 已内联），
@deepseek-ai/*全部 external 由 dsh 提供
和同类插件的取舍
| dsh-lark（本插件） | dsh-lark-bridge | dsh-im-hub | |
|---|---|---|---|
| 定位 | 极简单目录网关 | 全功能控制台 | 多平台网关 |
| 交互 | 纯文字 + 命令 | 交互卡片 / 进度卡片 | 卡片 |
| 多项目路由 | ❌（一个实例一个目录） | ✅ | ✅ |
| 平台 | 飞书 | 飞书 | 飞书 / 企微 / Telegram |
| 核心代码量 | ~600 行 | ~3000 行 | 更大 |
需要进度卡片、多项目绑定、配对码等完整功能时，请用 dsh-lark-bridge；只想要"飞书 ↔ Agent 跑通、代码一眼能读完"，用本插件。
安全说明
- 默认拒绝所有未加白用户；
allowAllUsers意味着任何能找到机器人的人都能在你机器上驱动 Agent，开启前想清楚 lark_deliver只能发送 Agent 工作目录内的文件（SDK 层allowedFileDirs+ 插件层双重校验）- 审批转发只是转发 dsh 的审批请求，审批策略本身由你的 dsh profile 决定
- dsh 目前处于 developer preview，其本身的沙箱边界（全盘可读、出网不限）请自行评估部署环境
开发
pnpm install
pnpm run check # typecheck + test + buildLicense
MIT