Skip to content

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 连接起来。

它解决两类场景:

  1. 人通过 UI 访问远端 DSH:在本地 DSH Web / Windows / Mac 桌面版的「飞书DSH客户端」面板里,以你的飞书用户身份与远端 DSH 对话——发文字、图片、文件,查看远端回复、卡片和审批。
  2. 本地 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 / ERROR reaction 判断远端这一轮是否结束。

目录

  • 适用版本
  • 安装
  • 功能概览
  • 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。

工作方式:

  1. 用你的 user_access_token 发消息,远端 @cubeai/dsh-feishu-channels 才会像普通用户消息一样处理。
  2. 发送后记录 message_id,轮询该消息上的 OnIt / DONE / ERROR 表情回执;DONE 即这一轮结束。
  3. 默认等待 180 秒;超时返回 pending + request_id,模型可调用 remote_feishu_continue 继续等,不会丢上下文。
  4. 远端审批卡会自动桥接到本地审批 UI;本地不批准就 fail closed,不会替你批准。
  5. 远端提问卡返回 needs_answer,模型通过 remote_feishu_continue 作答。
  6. 同一远端同时只允许一个请求;第二个返回 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(飞书长连接)

几个关键点:

  1. 不能只用机器人身份发消息。 飞书不会把机器人自己发出的消息再作为 im.message.receive_v1 事件推给它;因此本插件用 OAuth 取得你的用户 Token,以你本人身份发送,远端才会像普通用户消息一样处理。
  2. 必须使用目标 DSH 正在使用的同一个飞书应用。 这样远端收到的发送者 open_id、白名单、会话映射才能对上。
  3. 一个飞书应用只对应一个单聊。 当前数据模型是 apps.json 里的 app.chatId,不再单独维护 chats.json;将来做群聊时再引入会话列表。
  4. 首次绑定自动发现 Chat ID。 OAuth 后读取 user_info,让机器人给你发一条设置消息,从响应里拿到单聊 chat_id,不需要手填。
  5. 语音/视频走文件。 目标 @cubeai/dsh-feishu-channels 的飞书通道目前只接收文本、图片、文件、富文本;发原生语音/视频会被它拒绝,所以本插件统一按文件发送,并在本插件里播放预览。

第一次使用:完整前置准备

以下步骤只需要做一次。之后新增机器人可以直接复用已有应用和授权。

1. 在目标 DSH 安装并启用 @cubeai/dsh-feishu-channels 插件

在目标 DSH(最终要对话的那台机器)里:

  1. 安装并启用 @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
    
  2. 刷新 DSH,左侧边栏出现: 飞书频道。

2. 选择或创建飞书机器人

在远端 DSH 的 飞书频道 里:

  • 方式 A:扫码创建(推荐):点「添加飞书账号」→ 填写频道名称 → 扫码。插件会创建 PersonalAgent 应用,并自动配置权限和重定向 URL。
  • 方式 B:使用已有应用:已有飞书自建应用时,直接填 App ID / App Secret。

确认:

  1. 账号在飞书频道里已连接。
  2. 你在飞书里能找到机器人,并能正常单聊。
  3. 在飞书频道账号设置里可以查看/复制 App ID 和 App Secret。
  4. 本插件要填的必须是目标 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. 在本插件里添加

  1. 打开 DSH(Web 或 Windows / Mac 桌面版),左侧栏「自动化任务」下方点 飞书DSH客户端。
  2. 点 + 添加飞书机器人。
  3. 选 新建应用(把飞书应用的 App ID / App Secret 填进来,可从远端通过扫码创建的飞书账号设置中找到,或者从飞书开发者后台找到):
    • 飞书机器人名称(可选)
    • App ID
    • App Secret
    • 保存并继续
  4. 在「授权并绑定单聊」页:
    • 点 授权并绑定单聊;
    • 用与机器人单聊的同一个飞书账号扫码/登录并同意;
    • 授权成功后插件会自动让机器人给你发一条设置消息,并取得单聊 chat_id。
  5. 绑定成功后,左侧出现机器人,直接发消息即可。

关于设置消息:第一次绑定会由机器人给你发一条类似「飞书DSH客户端:已绑定…」的文本,只用于确定单聊 ID,可以忽略。远端飞书频道插件不会处理机器人自己发出的消息,因此不会触发任务。


日常使用

机器人列表

  • 点击左侧机器人切换对话。
  • 当前选中项有品牌色底、左侧色条和加粗名称。
  • 列表显示机器人名称、最后一条消息、状态点和时间。

聊天页右上角 ⋯ 菜单

聊天页右上角只显示一个 ⋯ 按钮,点开后有:

  • 刷新:重新拉取当前消息和授权状态。
  • 测试连接:检查机器人凭据、授权和单聊绑定。
  • 重新授权 / 授权飞书账号:重新走 OAuth。
  • 设置:进入应用设置页。
  • 删除机器人:删除本插件里的飞书应用记录、授权和本地 Secret;不会删除飞书应用,飞书侧聊天记录也不受影响。

点击菜单外或按 Esc 关闭;切换机器人时自动收起。

应用设置页

通过 ⋯ → 设置 进入:

  • 修改名称:只影响本插件列表/标题,不修改飞书应用或机器人名称。
  • 打开单聊:回到聊天页。
  • 重新绑定单聊:重新让机器人发设置消息并刷新 chat_id。
  • 重新授权、测试应用、删除机器人。

复用已有应用

  1. 点 + 添加飞书机器人 → 使用已有应用。
  2. 选择应用 → 继续。
  3. 已绑定直接打开单聊;未授权先授权;没有绑定则自动绑定。
  4. 不会重复保存 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.json v3 迁移辅助。
  • 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。

参考