JunguangJiang/dsh-lark-channel

dsh-lark · DeepSeek Harness 飞书 / Lark 插件

npm CI license

简体中文 | English

把你正在使用的 DeepSeek Harness 接进飞书。

直接在聊天里给 Agent 派任务、看执行过程、切换工作区和模型。遇到提问、计划确认或工具审批，也不用回到终端，直接在飞书里处理。需要时，还能把多个 Agent 放进同一个群里协作。

快速开始

npm i -g dsh-lark-channel
dsh-lark-channel start

终端会显示二维码。用飞书扫码完成应用创建，然后私聊机器人，或在群里 @ 它即可开始。

不想装到全局也可以直接跑，只是之后每条命令都要带 npx：

npx dsh-lark-channel@latest start

如果还没有安装 DeepSeek Harness，先运行：

npm i -g @deepseek-ai/dsh

无需公网服务器，也无需配置回调地址。

为什么值得装

- 不用守着终端：从飞书发起任务，随时查看进度和结果。
- 不只是聊天机器人：可以切换真实工作区和模型，执行 Harness 已有的命令与工具。
- 关键决定仍由你控制：模型提问、计划审阅和工具审批都会回到当前聊天，按钮或文字都能作答。
- 上下文不会混在一起：不同聊天、话题和工作区可以保留各自的会话。
- Agent 之间也能协作：一条命令添加更多机器人，让它们在群聊中通过 @ 交接回合，并用轮数上限防止无限对话。

可以这样开始

先看看当前状态和可用工作区：

/status
/ws
/cd my-project
/model

然后直接派一个任务：

检查这个项目为什么构建失败。先给我计划，需要操作时让我确认。

Agent 的执行过程会显示在飞书中；需要你参与时，会发送提问、计划或审批卡片。渠道自带文案会按每位读者的飞书语言显示中文或英文。

主要能力

| 能力 | 使用体验 |
|---|---|
| 持久会话 | 重启后可以恢复；后续消息继续当前上下文，/new 可以原地重开一个 |
| 多工作区 | /ws 查看、/cd 切换；回到原工作区时继续之前的任务 |
| 模型切换 | /model 打开模型选择卡片；切换后保留当前会话，也可随时恢复默认模型 |
| 原生执行过程 | 在飞书中查看推理、工具调用和结果，最终答案单独发送 |
| 人机协作卡片 | 单选、多选或文字回答问题；批准计划或提出修改意见；允许或拒绝工具调用 |
| 实时状态 | /status 展示工作区、模型和 session；可用时还显示上下文占用与累计 token，并支持刷新 |
| 会话隔离 | 可按聊天、话题或群成员划分独立 Agent 会话 |
| 多 Agent 协作 | 多个机器人拥有独立设置、凭据和 session，可以在同一个群里对话与交接任务 |
| 全局问答拦截 | 自动包装 ctx.userQuestions Provider，飞书会话的 ask() 走卡片，其他会话透传给 Web BFF |
| 斜杠命令 | 宿主自带的命令（/plan、/compact、/permission 等）直接进入 DSH 命令运行时 |
| 会话镜像 | GUI 会话通过 /lark 命令绑定到飞书群，用户消息、助手回复、计划审阅、命令执行和提问卡片均实时转发 |

常用命令

| 命令 | 用途 |
|---|---|
| /status | 查看并刷新工作区、模型和 session；可用时包含上下文与 token 状态 |
| /ws | 查看可用工作区 |
| /cd  | 切换工作区 |
| /model | 打开模型选择卡片 |
| /model use  | 直接切换模型 |
| /model reset | 恢复默认模型 |
| /new | 原地开一个新会话，清空上下文，工作区和模型保持不变 |
| /stop | 停止当前任务 |
| /help | 查看全部命令（含宿主提供的） |

日常运行

macOS 和采用 systemd 的 Linux 会使用用户级后台服务，关闭终端后仍可运行：

dsh-lark-channel status
dsh-lark-channel logs -f
dsh-lark-channel restart
dsh-lark-channel stop

用 npx 启动的话，这些命令同样要带 npx dsh-lark-channel@latest 前缀——工具会按你实际的启动方式打印提示，读到什么就能直接粘贴。

升级：

dsh-lark-channel upgrade

它会装上最新的 CLI 并在新版本上重启机器人。用 npx 的话不需要这一步，npx dsh-lark-channel@latest start 本来就是最新。有新版本时，start 和 status 会顺带提醒你一行。

连接异常时，插件会在限额和退避控制下自动重建 WebSocket，避免进程仍在但机器人已经静默离线。

添加更多 Agent

给第二个飞书应用添加一套独立的 Agent：

dsh-lark-channel add reviewer

命令会写入新实例、重启服务并显示二维码。扫码后，这个机器人拥有自己的设置、App Secret 和 session，不会与第一个机器人共享上下文。

把两个机器人加入同一个群后，它们可以通过 @ 把回合交给对方。例如，让一个 Agent 完成修改后 @ 另一个 Agent 复核，后者也可以 @ 回去要求调整。默认最多连续进行 6 个机器人轮次；任何人发言都会恢复额度。需要移除时：

dsh-lark-channel remove reviewer
移除会保留该实例的凭据和设置，之后用同一个名字重新添加即可恢复。

如果希望飞书和 dsh web 共用同一个 profile：

dsh plugin --profile web add dsh-lark-channel@latest
dsh web

权限与高级选项

- 飞书应用的可用范围决定谁能找到机器人；senderAllowlist、groupAllowlist 和 approvers 可以进一步收窄权限。
- workspaceRoots 可以限制聊天中允许切换到的目录。
- sessionScope 支持 chat、chat-thread 和 chat-sender 三种会话粒度。
- instance 用于命名额外的机器人实例；第一个机器人保持未命名，以兼容已有设置和会话。
- botPeers 可以限制允许对话的机器人，botHops 控制连续机器人轮次，默认是 6。
- 群聊默认只应答 @ 机器人的消息（requireMention）；开启 mentionFreeFollowUp 后，已绑定会话的话题（topic）内追问无需再 @。
- 会改变状态的卡片绑定原聊天，转发到其他聊天后不能操作原会话。
- 部署提供 credentials 服务时，扫码得到的 App Secret 会存入其中；旧版本写在 settings 中的 secret 会在下次启动时自动迁移。
- 图片附件默认关闭；只有确认当前模型支持视觉时，才应开启 attachImages。
- 配置在启动时读取，修改后需要重启服务。

架构：UserQuestions Wrapper Provider

插件在 bridge 初始化后安装一个 Wrapper Provider 到 ctx.userQuestions 服务上：

1. 时序：外部 bundle 插件加载晚于 @deepseek-ai/dsh-host-apiproxy（Web BFF），后者在 ApiProxyService 构造时即注册了唯一的 Provider。因此本插件无法"抢先注册"。
2. 策略：bridge 初始化后直接替换 service.provider 字段（运行时普通属性，非 JS #private），装入一个路由层：
- 请求的 agent.session.id 在 bySession Map 中查得到 → 该 session 绑定了飞书聊天 → 用 ChatQuestions 发交互卡片等待回答。
- 查不到 → 透传给原始 Web BFF Provider（original.ask(request)）。
3. 卸载：fiber 销毁时恢复原始 Provider，不留副作用。

效果：任何通过 ctx.userQuestions.ask() 发起的问答（包括 mirror 会话、未来新增的调用方）都会自动路由到飞书卡片，无需每个 agent 单独配置 shadow tool。已有的 per-agent tool shadowing 仍然保留，作为同一 session 内的快路径。

会话镜像覆盖面

/lark 命令将 GUI 会话绑定到飞书群后，以下交互实时转发：

| 事件类型 | 转发内容 | 控制开关 |
|---|---|---|
| user/message | 直接人类输入，镜像注入的消息不回显 | 始终开启 |
| assistant/message | 每轮最终助手回复（卡片形式，长文自动分块） | 始终开启 |
| tool/call | 工具调用一行活动通知 | verbose 开关 |
| tool/call（ask_user_question） | 提问信息卡 | 始终开启 |
| turn/end 错误 | 错误卡片 | 始终开启 |
| command/run | 斜杠命令调用通知（⚡ /name args） | verbose 开关 |
| command/done | 斜杠命令结果通知（✅/❌ /name result） | verbose 开关 |
| question/requested | 通过 SSE mux 订阅：通用问题渲染为按钮/下拉卡片 | 始终开启 |
| question/requested（plan-review） | 计划审阅专用卡片：标题、详情摘要、URL 可点击、批准/继续规划按钮 | 始终开启 |

命令事件与工具调用共用 verbose 开关：/lark verbose on 开启后两者同时可见。设计理由：命令是用户发起的轻量操作，与工具调用同属过程信息，独立开关会增加配置复杂度而收益有限。

question/requested 帧由宿主的 apiproxy 广播到所有 mux 订阅者，包含完整的 AskUserQuestionItem（含 intent、detail、options）。MirrorQuestionBridge 订阅 WebSocket 并为绑定会话渲染交互卡：
- 通用问题：按钮（≤6 个选项）或下拉（≤100 个选项）
- plan-review 意图：专用紫色卡片，摘要、URL 提取、批准/继续按钮
- /lead 模型选择弹窗等：走通用问题路径，选项渲染为按钮或下拉

镜像聊天支持触发短语桥接：triggerPhrases 配置一张自然语言→斜杠命令的映射表，绑定会话的入站消息精确匹配短语时执行映射的命令（trimmed、case-insensitive），不命中则走正常注入。verbose 模式下会推送映射提示。

与 plan-board / lark-watch 的资源分界

本插件与 plan-board（/lark-watch 命令）共享同一飞书应用，资源边界如下：

| 资源 | 归属 | 说明 |
|---|---|---|
| 事件长连接（WebSocket） | dsh-lark-channel 独占 | 飞书每 app 仅允许一条长连接；本插件在 port.connect() 时建立并维护。外部插件不得自行开启第二条——平台会踢掉先到者。 |
| IM 消息收发 | dsh-lark-channel | 所有聊天消息通过本插件的长连接接收、通过其 port.send() 发送。plan-board 的文档协同结果经宿主命令通道返回，无需直接收发 IM。 |
| 文档批注读写 | plan-board | /lark-watch 通过飞书 OpenAPI 读写文档评论，不依赖长连接。 |
| 应用 API 配额 | 共享 | 两个插件的 API 调用均计入同一 app 的速率限额。高频操作时注意配额余量。 |
实际协作：用户在 GUI 执行 /lark-watch process，或在镜像聊天里用触发短语（如“开始处理”→/lark-watch process）触发处理。触发短语通过 triggerPhrases 配置。

环境要求

- Node.js ^22.19.0 || >=24
- DeepSeek Harness 0.1.0-rc.6 或更新版本
- 飞书或 Lark 租户

原生思考过程需要飞书 PC 7.70、移动端 7.74 或更新版本；旧客户端可以使用 output: 'stream'。

开发

pnpm install
pnpm test
pnpm build

License

BSD-3-Clause

本项目是非官方社区插件，与 DeepSeek、飞书或 Lark 不存在隶属、授权或背书关系。