dsh-remote-feishu
Verified@cubeai/dsh-remote-feishu · v0.5.2 · Apache-2.0 · Web UI
飞书DSH客户端:1)用户(人)通过本插件提供UI访问远端智能体;2)本地DSH通过调用本插件提供工具访问远端智能体。支持的远端智能体包括且不限于:DSH、OpenClaw、WorkBuddy、Weknora等等。
Install
dsh plugin add @cubeai/dsh-remote-feishu Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Creators
Readme
dsh-remote-feishu
dsh-remote-feishu(界面名称「飞书DSH客户端」)是 DeepSeek Harness(简称 DSH)的一个插件:通过自建的飞书应用(机器人应用),把本地 DSH 和远端安装了 @cubeai/dsh-feishu-channels 插件的 DSH 连接起来。
它解决两类场景:
- 人通过 UI 访问远端 DSH:在本地 DSH Web / Windows / Mac 桌面版的「飞书DSH客户端」面板里,以你的飞书用户身份与远端 DSH 对话——发文字、图片、文件,查看远端回复、卡片和审批。
- 本地 DSH 智能体访问远端 DSH 智能体:本地智能体以你的飞书用户身份向远端智能体提交任务,取回远端回复的文本/图片/文件等结果,并把远端审批桥接到本地审批界面。
特别提示:本插件支持的远端智能体不限于 DSH:OpenClaw(龙虾)、WorkBuddy、Weknora 等智能体,只要集成了飞书接入通道,也能像 DSH 一样接入本插件;UI 对话和智能体互联均可支持。
具体形态与特性:
- 一个飞书应用(机器人应用)= 一个机器人 = 一个单聊(
chat_id) - 发送使用你的飞书用户身份(
user_access_token),读取历史使用机器人身份(tenant_access_token) - App Secret(应用密钥)、用户 Token、Refresh Token 都保存在 DSH Credential Vault
- UI 支持:文字、Markdown 表格、DSH 风格代码块、图片、文件、语音/视频(兼容模式)、卡片按钮、审批按钮、名称/会话设置
适用版本
| 组件 | 当前适用版本 | 说明 |
|---|---|---|
| DSH | v0.2.1-rc.2 |
本插件运行在 DSH Web / Windows 桌面版 / Mac 桌面版 |
| @cubeai/dsh-feishu-channels(远端) | 最新版 | 飞书频道专用,自动配置权限和重定向 URL |
| @cubeai/dsh-remote-feishu | 0.5.2 |
本插件 |
表中是当前验证版本,其他版本可能也可用。DSH 远端需要安装
@cubeai/dsh-feishu-channels插件;本插件的 Agent 工具依赖它的OnIt/DONE/ERRORreaction 判断远端这一轮是否结束。
目录
- 适用版本
- 安装
- 功能概览
- Agent 工具
- 工作原理
- 第一次使用:完整前置准备
- 日常使用
- 数据与安全
- 常见错误
- 已知限制
- 当前验证状态
- 开发
- 参考
安装
本插件是一个 DSH Cordis 插件 bundle,不需要单独构建。
方式 A:界面安装(推荐)
在 DSH 里的「插件 → 添加插件」界面中,输入下面的地址,系统会自动安装:
@cubeai/dsh-remote-feishu
或:
https://openi.pcl.ac.cn/dsh/dsh-remote-feishu.git
安装后刷新 DSH,左侧栏「自动化任务」下方会出现 飞书DSH客户端。
方式 B:命令行安装(适用于 web profile)
dsh plugin --profile web add https://openi.pcl.ac.cn/dsh/dsh-remote-feishu.git
或从 npm 安装:
dsh plugin --profile web add @cubeai/dsh-remote-feishu
更新 Client 后通常硬刷新页面即可;更新 Host 后需要重新加载插件或重启 DSH。状态目录默认是
$DSH_HOME/dsh-remote-feishu(通常是~/.dsh/dsh-remote-feishu)。
功能概览
界面
- 侧边栏「自动化任务」下方的 飞书DSH客户端 入口。
- 左侧机器人列表:显示机器人名称、最后消息、状态点;当前选中项有明显高亮。
- 右侧聊天页:消息区、附件区、审批区、输入框。
- 聊天页右上角只保留一个
⋯菜单,包含刷新、测试连接、重新授权、设置、删除机器人。 - 应用设置页支持修改名称、打开/重新绑定单聊、删除机器人。
消息
- 文字消息,Enter 发送;Shift+Enter 换行。
- Markdown:标题、列表、引用、链接、表格、行内代码、代码块。
- 代码块按 DSH Web 风格渲染:语言标签、语法高亮、复制按钮、自动换行、DSH 行距。
- 用户消息使用 DSH 的浅色气泡样式;助手消息左对齐。
- 轮询新消息、去重、日期分隔、未读提示、草稿保存、滚动到底部。
图片 / 文件 / 语音 / 视频
- 图片:原生飞书图片消息;气泡内缩略图,点击灯箱预览,可下载。
- 文件:原生飞书文件消息;文件卡片支持预览(浏览器能展示的 PDF/文本/图片等)和下载。
- 语音 / 视频:按文件消息发送,以兼容目标
@cubeai/dsh-feishu-channels;本插件按扩展名识别并显示音频/视频播放器。 - 添加附件:输入框左下角
+选择,或直接把图片/文件粘贴到输入框(截图粘贴亦可),也支持先发文字再发附件。 - 发送上限:图片 10MB,其他附件 30MB。
- 图片/文件/音视频资源由本插件 Host 代理读取,不把 Token 暴露给浏览器。
卡片与审批
- 卡片正文会提取为 Markdown;有效卡片里的按钮会显示在本插件中。
- 普通菜单按钮:点击发送对应序号。
- 审批卡:点击按钮发送 「批准」/「拒绝」;按钮显示在消息下方(没有底部常驻审批条);批准/拒绝后(包括在本地 DSH 审批里操作)会自动收起。
- 卡片显示「已失效」后远端会移除按钮,此时飞书客户端也无法点击,只能重新发起审批或
/menu。 - 原生
card.action.trigger回调由远端飞书频道插件处理;本插件的按钮仍是文字回退,不是飞书原生回调。
Agent 工具
本地 DSH 智能体可以通过三个 Host 工具,以用户身份向已配置的远端 DSH 发起会话,并把结果取回本地上下文。工具只增加 Host 侧能力,不改变现有聊天面板。
| 工具 | 作用 |
|---|---|
remote_feishu_list |
列出远端、能力描述、标签、绑定/授权状态、busy、最近一次调用结果 |
remote_feishu_ask |
向指定远端发送文本(可选图片/文件),等待这一轮结束或需要决策 |
remote_feishu_continue |
继续 pending / needs_approval / needs_answer 的请求 |
典型用法:
- “让远端智能体DSH-1 看一下这个报错,只回复原因。”
- “找擅长图像处理的那台远端智能体,分析一下这幅图像。”
- 模型自己判断需要远端算力/环境时,先
remote_feishu_list,再remote_feishu_ask。
工作方式:
- 用你的
user_access_token发消息,远端@cubeai/dsh-feishu-channels才会像普通用户消息一样处理。 - 发送后记录
message_id,轮询该消息上的OnIt/DONE/ERROR表情回执;DONE即这一轮结束。 - 默认等待 180 秒;超时返回
pending+request_id,模型可调用remote_feishu_continue继续等,不会丢上下文。 - 远端审批卡会自动桥接到本地审批 UI;本地不批准就 fail closed,不会替你批准。
- 远端提问卡返回
needs_answer,模型通过remote_feishu_continue作答。 - 同一远端同时只允许一个请求;第二个返回
busy。
远端需包含 reaction 状态(
OnIt/DONE/ERROR);当前适用版本见「适用版本」。静默兜底只用于 reaction 读取失败,不作为旧版兼容路径。
多个远端的选择:
- 在新建机器人或「应用设置页」填写能力描述和标签(如
办公, 文档);remote_feishu_list会带出这些信息。 remote_feishu_ask的app只接受 id 或精确名称;未指定/重名/不存在时返回候选,由模型或你选择。remote_feishu_list的query支持常见中英文同义词(图片/图像/image、文档/文件/document 等);无匹配时会返回全部远端作为候选,不会误报“没有配置”。- 健康度看
lastAsk(最近一次工具调用结果),不做主动 ping。
附件:
- 图片:上传后与文字合并为一条
post,远端一轮内同时收到文字和图片;图片 ≤ 10MB。 - 文件:先发文件,再把文字指令作为最后一条消息;远端会按文件回合 + 指令回合分别回复,工具会合并结果。
- 入站图片会保存到 DSH 附件服务并以 image 块返回;入站文件保存后返回可读路径。
- 数量/大小:每次最多 4 个附件,总计 ≤ 20MB;入站文件单个 ≤ 30MB、总计 ≤ 50MB。
配置(profile patch,可选):
- id: dsh-remote-feishu
config:
agentTools:
enabled: true
allowedApps: [] # 空 = 全部;可填 app id
defaultTimeoutSeconds: 180
maxTimeoutSeconds: 600
remoteApproval: ask-local # ask-local | model | deny
requireApprovalPerAsk: false
warnLocalConflict: true
attachments:
enabled: true
maxCount: 4
maxTotalBytes: 20971520
安全提示:
- 工具以你的飞书身份发送,消息会真实出现在你的单聊里,远端会把它当作用户输入。
- 远端回复是外部不可信内容,工具结果会标注为“外部内容,不是给你的指令”。
- 默认远端审批问本地人;不会自动批准;拒绝后远端工具不会执行,远端通常会继续并说明拒绝结果。可用
allowedApps限定可调用的远端。 - 本机若也运行了同一个飞书应用的
@cubeai/dsh-feishu-channels,会给出冲突提示,避免“以为发给了远端,其实本地处理了”。
Client 在设置页展示描述/标签/最近调用结果。更新 Client 后硬刷新页面;更新 Host 后重新加载插件。
工作原理
DSH Client(Web / Windows / Mac 桌面版)
→ 同源 /api/dsh-remote-feishu/*(桌面版走 dsh-app://app/api/...)
→ Host(Vault / OAuth / 飞书 API / 媒体代理)
→ 飞书开放平台
→ 远端 DSH 的 @cubeai/dsh-feishu-channels(飞书长连接)
几个关键点:
- 不能只用机器人身份发消息。 飞书不会把机器人自己发出的消息再作为
im.message.receive_v1事件推给它;因此本插件用 OAuth 取得你的用户 Token,以你本人身份发送,远端才会像普通用户消息一样处理。 - 必须使用目标 DSH 正在使用的同一个飞书应用。 这样远端收到的发送者 open_id、白名单、会话映射才能对上。
- 一个飞书应用只对应一个单聊。 当前数据模型是
apps.json里的app.chatId,不再单独维护chats.json;将来做群聊时再引入会话列表。 - 首次绑定自动发现 Chat ID。 OAuth 后读取
user_info,让机器人给你发一条设置消息,从响应里拿到单聊chat_id,不需要手填。 - 语音/视频走文件。 目标
@cubeai/dsh-feishu-channels的飞书通道目前只接收文本、图片、文件、富文本;发原生语音/视频会被它拒绝,所以本插件统一按文件发送,并在本插件里播放预览。
第一次使用:完整前置准备
以下步骤只需要做一次。之后新增机器人可以直接复用已有应用和授权。
1. 在目标 DSH 安装并启用 @cubeai/dsh-feishu-channels 插件
在目标 DSH(最终要对话的那台机器)里:
安装并启用
@cubeai/dsh-feishu-channels:dsh plugin --profile PROFILE add @cubeai/dsh-feishu-channels也可以从 OpenI 源码安装:
dsh plugin --profile PROFILE add https://openi.pcl.ac.cn/dsh/dsh-feishu-channels.git刷新 DSH,左侧边栏出现: 飞书频道。
2. 选择或创建飞书机器人
在远端 DSH 的 飞书频道 里:
- 方式 A:扫码创建(推荐):点「添加飞书账号」→ 填写频道名称 → 扫码。插件会创建 PersonalAgent 应用,并自动配置权限和重定向 URL。
- 方式 B:使用已有应用:已有飞书自建应用时,直接填 App ID / App Secret。
确认:
- 账号在飞书频道里已连接。
- 你在飞书里能找到机器人,并能正常单聊。
- 在飞书频道账号设置里可以查看/复制 App ID 和 App Secret。
- 本插件要填的必须是目标 DSH 的飞书频道正在使用的同一个飞书应用。
3. 飞书后台配置:通常不需要
通过扫码创建应用时,@cubeai/dsh-feishu-channels 会自动完成:
- 开通
im:message、im:message.send_as_user等必需权限; - 写入默认重定向 URL;
- 配置机器人能力和事件订阅。
所以一般不需要进入飞书开发者后台,也不需要手动发布权限。
唯一需要手动处理的常见情况:本地 DSH 部署在 CubeAI 智立方云平台。
插件自动写入的重定向 URL 中有一条以 https://www.cubeai.com 开头的占位地址,例如:
https://www.cubeai.com:6443/cubeaispace-dsh1-1234567890-dsh/api/dsh-remote-feishu/oauth/callback
CubeAI 上实际访问地址通常带有你自己的实例前缀。请到飞书开发者后台 → 目标应用 → 安全设置 → 重定向 URL,找到这条以 https://www.cubeai.com 开头的地址,把前缀替换为浏览器地址栏中实际看到的基址,保留后面的:
/api/dsh-remote-feishu/oauth/callback
例如实际访问地址是:
https://your-host:6443/cubeaispace-dsh2-1-35c331fc7c-dsh/
就改成:
https://your-host:6443/cubeaispace-dsh2-1-35c331fc7c-dsh/api/dsh-remote-feishu/oauth/callback
只修改这一条,不要删除其他自动写入的重定向 URL。飞书官方的安全配置说明中,重定向 URL 修改后立即生效,不需要重新发布版本;只有权限等配置变更才需要提交发布审核。
权限、事件订阅和重定向 URL 的自动配置由远端
@cubeai/dsh-feishu-channels完成;本地dsh-remote-feishu只负责 OAuth 和消息收发。
4. 在本插件里添加
- 打开 DSH(Web 或 Windows / Mac 桌面版),左侧栏「自动化任务」下方点 飞书DSH客户端。
- 点 + 添加飞书机器人。
- 选 新建应用(把飞书应用的 App ID / App Secret 填进来,可从远端通过扫码创建的飞书账号设置中找到,或者从飞书开发者后台找到):
- 飞书机器人名称(可选)
- App ID
- App Secret
- 保存并继续
- 在「授权并绑定单聊」页:
- 点 授权并绑定单聊;
- 用与机器人单聊的同一个飞书账号扫码/登录并同意;
- 授权成功后插件会自动让机器人给你发一条设置消息,并取得单聊
chat_id。
- 绑定成功后,左侧出现机器人,直接发消息即可。
关于设置消息:第一次绑定会由机器人给你发一条类似「飞书DSH客户端:已绑定…」的文本,只用于确定单聊 ID,可以忽略。远端飞书频道插件不会处理机器人自己发出的消息,因此不会触发任务。
日常使用
机器人列表
- 点击左侧机器人切换对话。
- 当前选中项有品牌色底、左侧色条和加粗名称。
- 列表显示机器人名称、最后一条消息、状态点和时间。
聊天页右上角 ⋯ 菜单
聊天页右上角只显示一个 ⋯ 按钮,点开后有:
- 刷新:重新拉取当前消息和授权状态。
- 测试连接:检查机器人凭据、授权和单聊绑定。
- 重新授权 / 授权飞书账号:重新走 OAuth。
- 设置:进入应用设置页。
- 删除机器人:删除本插件里的飞书应用记录、授权和本地 Secret;不会删除飞书应用,飞书侧聊天记录也不受影响。
点击菜单外或按 Esc 关闭;切换机器人时自动收起。
应用设置页
通过 ⋯ → 设置 进入:
- 修改名称:只影响本插件列表/标题,不修改飞书应用或机器人名称。
- 打开单聊:回到聊天页。
- 重新绑定单聊:重新让机器人发设置消息并刷新
chat_id。 - 重新授权、测试应用、删除机器人。
复用已有应用
- 点 + 添加飞书机器人 → 使用已有应用。
- 选择应用 → 继续。
- 已绑定直接打开单聊;未授权先授权;没有绑定则自动绑定。
- 不会重复保存 Secret,也不会重复授权。
数据与安全
~/.dsh/dsh-remote-feishu/apps.json:机器人显示名称、App ID、App Secret 的 Vault 引用、chatId、授权状态、时间戳;不含明文 Secret。- 旧版
bots.json/chats.json会自动合并进apps.json,并备份为*.migrated-*;原授权 Token 保留,不需要重新授权。 - App Secret、user_access_token、refresh_token 保存在 DSH Credential Vault。
debug.log:流程和错误码;不含 Secret、Token 或消息正文。- 管理 API 复用 DSH 的登录/跨站校验;变更请求额外要求
x-dsh-remote-feishu-client: 1头。 - OAuth 使用一次性随机
state(10 分钟有效),回调路径精确匹配。 - Client 只访问同源管理 API;图片/文件/音视频通过 Host 代理读取,Token 不下发浏览器。
- 资源代理只接受
image/file类型,限制附件大小,文件名做安全清洗。
状态文件示例
{
"version": 3,
"apps": [
{
"id": "app_xxx",
"name": "远端DSH-3",
"appId": "cli_xxx",
"appSecretRef": "dsh_remote_feishu_app_xxx_app_secret",
"userAccessTokenRef": "dsh_remote_feishu_app_xxx_user_access_token",
"refreshTokenRef": "dsh_remote_feishu_app_xxx_refresh_token",
"chatId": "oc_xxx",
"description": "部署在云端的 DSH 智能体,擅长图像分析",
"tags": ["cloud", "image"],
"lastAsk": {
"at": "2026-10-23T06:00:00.000Z",
"status": "done",
"durationMs": 12345,
"requestId": "req_xxx"
},
"auth": {
"authorized": true,
"expiresAt": "2026-10-23T06:00:00.000Z",
"scope": "im:message im:message.send_as_user offline_access",
"refreshable": true,
"warning": null,
"error": null
}
}
]
}
常见错误
| 错误 | 处理 |
|---|---|
20027 |
扫码时 OAuth 权限未自动开通或未生效。重新扫码创建,或检查飞书频道账号的权限配置 |
2000 / redirect_uri unmatch |
重定向 URL 与浏览器实际地址不一致。CubeAI 平台修改自动写入的 https://www.cubeai.com... 前缀;其他自定义地址确认实际回调已在飞书安全设置中 |
20010 |
你不在应用可用范围内 |
230027 |
机器人权限未生效;重新扫码创建,或检查飞书频道账号的权限配置 |
230013 |
用户不在机器人可用范围,或应用被禁用 |
99991677 |
用户授权过期;⋯ → 重新授权 |
99991679 |
授权缺少 im:message.send_as_user;重新授权 |
234006 |
附件超过飞书限制:图片 10MB,其他文件 30MB |
234004 / 234003 |
机器人不在会话,或资源不属于该消息 |
234043 |
该消息类型不支持读取资源 |
| 上传图片/文件报权限错误 | 检查远端飞书频道账号的权限配置;优先重新扫码创建,让插件重新应用所需权限 |
| 图片/文件预览失败 | 确认已登录 DSH、应用仍在单聊中;查 debug.log 中的资源错误 |
| 自动绑定失败 | 检查 user_info、机器人发消息权限、可用范围;或用设置页手动 Chat ID |
| 「这个应用已经添加过」 | 用「使用已有应用」,不要重复新建 |
401 |
当前 DSH Web 登录失效;重新打开 DSH 地址 |
已知限制
- 当前是 一个飞书应用 = 一个单聊。群聊、一个飞书应用多会话暂不实现。
- 飞书公开 API 不提供 p2p 会话列表,只能自动发现“机器人与当前授权用户”的单聊;群聊要手动 Chat ID。
- 只加载最近 50 条消息,暂无分页。
- 目标
@cubeai/dsh-feishu-channels的飞书通道只接收文本、图片、文件和富文本:- 语音/视频发送时按文件处理;
- 在飞书客户端里直接发的原生语音/视频,本插件能展示,但远端飞书频道插件当前会拒绝该消息类型。
- 消息会同时出现在正常飞书客户端的单聊里(传输层决定)。
- UI 目前为中文;插件元数据提供 zh/en。
- 浏览器能预览的文件类型有限;其他文件下载后查看。
- Agent 工具:同一远端同时只允许一个请求;远端审批仍有 5 分钟窗口;图片能否被远端理解取决于远端模型/图片管线。
当前验证状态
- P0:真实飞书 OAuth、用户身份发送、远端
@cubeai/dsh-feishu-channels回复、历史读取通过。 - 兼容:DSH
v0.2.1-rc.2+ 远端@cubeai/dsh-feishu-channels(不锁定版本)。 - 部署:Web 根路径、nginx 路径前缀、Windows 桌面版 OAuth 回调均已验证。
- 迁移:旧
bots.json/chats.json已合并为apps.json;应用授权和 chatId 均保留。 - 飞书应用与会话:新建、复用、重命名、重新绑定、自动发现 Chat ID 已实测。
- 媒体:图片/文件上传并发送已实机验证;图片灯箱、文件卡片已基本通过验收。
- 音视频:播放器与“按文件发送”逻辑已实现;真实语音/视频发送、播放与远端处理待验收。
- 代码块:DSH 风格高亮、复制、自动换行已实现。
- 卡片:审批按钮已可点击并映射为「批准/拒绝」;在插件或本地 DSH 里处理后,内联审批自动收起;原生回调由远端飞书频道插件提供,本插件当前使用文字回退。
- 界面:右上角
⋯菜单、内联审批、附件灯箱/播放器已实现。 - Agent 工具:
remote_feishu_list/ask/continue,文本、文件、图片、提问、超时继续、审批批准/拒绝、busy 锁、取消均已实机验证。
开发
lib/index.js:Host(状态、Vault、OAuth、聊天发现、消息、媒体上传/代理、卡片归一化、管理路由)。lib/agent-bridge.js:Agent 工具(list/ask/continue、状态机、锁、审批桥接、附件)与apps.jsonv3 迁移辅助。lib/client.js:Client(侧边栏入口、机器人列表、表单、设置页、聊天页、Markdown/代码块、附件/灯箱/播放器、内联审批、轮询)。package.json/cordis.patch.yml/locale//icon.svg:bundle 与展示资源。- 无构建步骤;
lib/index.js和lib/client.js直接作为插件产物。 - 修改 Client 后硬刷新页面;修改 Host 后重新加载插件。
- 调试日志:
~/.dsh/dsh-remote-feishu/debug.log。 - 设计文档:docs/dsh-remote-feishu-plan.md。
- Agent 工具方案与验证记录:docs/dsh-remote-feishu-agent-bridge-plan.md。