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 + build

License

MIT