dsh-feishu-bot — 飞书机器人接入 DeepSeek Harness（一键安装）

把 DeepSeek Harness 接进飞书：在飞书里和本机 agent 对话，agent 的回复发回飞书。 使用飞书官方 SDK 的 WebSocket 长连接——无需公网 IP、无需端口映射、无需内网穿透。

飞书用户 ──消息──> 飞书开放平台 ──长连接(WS)──> dsh-feishu-bot 插件 ──> 本机 DSH agent
飞书用户 <──回复── 飞书开放平台 <──im/v1/messages── dsh-feishu-bot 插件 <── agent 输出

特性

• ✅ 每飞书会话一个独立 DSH agent，多轮上下文连续（映射持久化 $DSH_HOME/feishu-sessions.json）
• ✅ 断线自动重连（30 秒 watchdog）、token 自动刷新
• ✅ 私聊 / 群聊（@机器人）都支持
• ✅ 纯文本 + 富文本（post）消息都支持（自动提取文字内容；post 里粘贴的图片也会下载识别）
• ✅ 图片消息支持：自动下载到 $DSH_HOME/feishu-images/，并引导 agent 用识图脚本 （vision.js）识别内容后回复；文件/卡片/语音等暂忽略
• ✅ 提问闭环：agent 需要确认时会先把问题发到飞书，你直接回复答案即可（不会卡住）
• ✅ 可选 open_id 白名单
• ✅ 完整工具集：飞书会话自动挂载 agent preset（默认 standard，与 Web 会话一致）， 文件读写、Shell、Web 搜索、Skills、目标、计划模式、子代理、工作流、Todo 等全部可用

环境要求

依赖	说明
DeepSeek Harness (dsh)	已安装并至少启动过一次（生成 $DSH_HOME/profiles）
Node.js ≥ 22	自带 npm（用于自动安装飞书 SDK）
飞书开放平台应用	见下方第 1 步

---

一键安装（约 5 分钟）

第 1 步：飞书开放平台创建应用（一次性）

1. 打开 https://open.feishu.cn/，飞书账号登录 → 开发者后台 → 创建企业自建应用。

2. 应用详情 → 添加应用能力 → 机器人 → 启用。

3. 事件与回调 → 事件配置：

   • 订阅方式选 「使用 长连接 接收事件」。
   • 添加事件：接收消息 im.message.receive_v1（v2.0）。

4. 权限管理（应用身份，4 个全部开通，缺一不可）：

   权限标识	名称	必需原因
   im:message.p2p_msg:readonly	读取用户发给机器人的单聊消息	私聊收消息
   im:message	获取与发送单聊、群组消息	收发消息基础权限
   im:message.group_msg.include_bot:read	获取群组中用户和机器人发送的消息	群聊收消息
   im:message:send_as_bot	以应用的身份发消息	机器人回复

5. 版本管理与发布 → 创建版本 → 发布（⚠️ 改配置后必须发布新版本才生效）。

6. 应用 可用范围 包含你的账号。

7. 回到 凭证与基础信息，复制 App ID（cli_xxx）和 App Secret。

第 2 步：一键安装脚本（Windows）

克隆本仓库，在 PowerShell 中运行（在仓库根目录）：

git clone https://github.com/<你的账号>/dsh-feishu-bot.git
cd dsh-feishu-bot

.\install.ps1 -AppId "cli_xxxxxxxx" -AppSecret "xxxxxxxxxxxxxxxx"

可选参数：

.\install.ps1 -AppId "cli_xxx" -AppSecret "xxx" `
              -DshHome "C:\Users\you\.dsh" `   # 默认取 $env:DSH_HOME 或 ~/.dsh
              -Cwd     "D:\your\workspace"      # agent 初始工作目录（默认当前目录）

脚本自动完成：

[1/5] 复制插件到 $DSH_HOME\profiles\node_modules\dsh-feishu-bot
[2/5] npm 自动安装飞书 SDK 及全部依赖（插件私有目录，不污染顶层 node_modules）
[3/5] 注册插件行到 cordis.patch.yml（自动备份 .bak）
[4/5] 凭证写入 settings.yaml（自动备份 .bak）
[5/5] 运行健康检查脚本

第 3 步：重启并验证

1. 重启 dsh web：npx @deepseek-ai/dsh web（或关闭旧终端重开）。
2. 终端出现 [info]: [ '[ws]', 'ws client ready' ] = 长连接建立。
3. 飞书开放平台 → 事件与回调 → 订阅方式 → 重新验证 → 显示连接成功。
4. 飞书里私聊机器人发消息 → agent 回复，$DSH_HOME\feishu-sessions.json 生成。

---

非 Windows / 手动安装

Linux/macOS 或不想用脚本时，手动做脚本里的 5 件事：

# 1. 复制插件
mkdir -p "$DSH_HOME/profiles/node_modules"
cp -r dsh-feishu-bot "$DSH_HOME/profiles/node_modules/"

# 2. 安装 SDK（插件私有目录，不污染顶层）
cd "$DSH_HOME/profiles/node_modules/dsh-feishu-bot"
npm install @larksuiteoapi/node-sdk@1.73.0 --no-save --no-audit --legacy-peer-deps

# 3. 注册 cordis.patch.yml（追加到 - insert: 列表）
# 4. 写 settings.yaml（见下）
# 5. 重启 dsh web

settings.yaml（$DSH_HOME/settings.yaml）追加：

feishu-bot:
  appId: cli_xxxxxxxxxxxx
  appSecret: xxxxxxxxxxxxxxxxxxxx
  # allowedOpenIds:          # 可选白名单；留空=允许所有用户
  #   - ou_xxxxxxxx
  cwd: /path/to/workspace    # 可选；agent 初始工作目录
  # preset: standard         # 可选；agent 预设（决定可用工具集），留空=部署默认

关于工具：飞书会话默认挂载部署默认的 agent preset（standard，完整编码 agent 工具集： 文件系统、Shell、Web 搜索、Skills、目标、计划模式、子代理、工作流等，与 Web 会话一致）。 如需换成其他预设（如 minimal、code、cordis 或自定义 preset），在 feishu-bot.preset 指定其 id。注意：不挂载任何 preset 的会话，agent 将没有任何可用工具。

cordis.patch.yml（$DSH_HOME/profiles/web/cordis.patch.yml）的 insert 列表追加（只需本插件一行）：

- insert:
    - id: feishu-bot
      name: 'dsh-feishu-bot'

⚠️ 示例中不要加入其他插件的行（如 dsh-llm-vision-bridge——那是部署特有的自定义插件， 没有安装它却注册会直接启动失败）。你部署里已有的插件行保持原样即可。

---

常见问题

症状	原因	处理
启动报 exists and is not a symlink	SDK 依赖被复制进顶层 node_modules	只删报错点名的包；确认依赖装在插件私有目录
Cannot find package 'dsh-feishu-bot'	插件没装好	重跑 install.ps1
飞书后台「连接失败」	dsh 没在跑 / 长连接未启用	确认 ws client ready；后台订阅方式选长连接
私聊收不到消息	改配置后未发布新版本	版本管理与发布 → 创建版本 → 发布
群聊无响应	未 @机器人	@ 机器人并把它拉进群
回复「处理消息时出错」	agent 侧问题	看 feishu-diag.log 或错误信息

插件运行诊断日志：<workspace>/.dsh/feishu-diag.log（记录凭证读取、SDK 初始化、长连接、事件接收每一步）。

排障

仓库内 scripts/check.mjs 一键健康检查（只读，不改任何配置）：

node scripts/check.mjs

输出全部 ✅ = 就绪；有 ❌ = 按提示修复后重跑。

项目结构

dsh-feishu-bot/
├── install.ps1          # Windows 一键安装
├── package.json         # 插件清单
├── lib/index.js         # 插件源码（host 侧 Cordis 插件）
├── scripts/check.mjs    # 健康检查脚本
├── skill/               # dsh-feishu-skill（给 agent 的接入/排障指引）
│   ├── SKILL.md         #   skill 本体：接入步骤、硬约束、故障排查
│   └── check.mjs        #   健康检查（与 scripts/ 同源）
└── README.md

附带 Skill（可选）

skill/ 目录是 DSH 的 skill（agent 操作手册），与插件（可运行代码）互补：

• 插件（lib/index.js + install.ps1）= 实际干活的机器，装上即通。
• skill（skill/SKILL.md）= 操作手册，让 agent 遇到飞书任务时按规范步骤执行、 避开已知的坑（settings 注册的 onChange 陷阱、顶层 node_modules 符号链接约束等）。

把 skill/ 复制到 DSH 工作区的 .dsh/skills/dsh-feishu-skill/ 即可启用：

Copy-Item -Recurse "skill" "$env:USERPROFILE\.dsh\skills\dsh-feishu-skill"   # 或放到你的项目 .dsh/skills 下

启用后，agent 处理飞书接入/排障任务时会自动加载该 skill 的指引。

原理简述

• 传输层：飞书官方 SDK @larksuiteoapi/node-sdk 的 WSClient + EventDispatcher， 长连接是二进制 protobuf 帧协议，由 SDK 封装（不要手写）。
• 插件形态：host 侧 Cordis 插件，cordis.patch.yml 注册。
• 依赖布局：SDK 及依赖闭包装在插件私有 node_modules/，顶层 profiles/node_modules 只保留 dsh 管理的符号链接（registry 包绝不以真实目录放入顶层）。
• agent 驱动：参照 headless runner 模式——agents.create/resume + followup + whenIdle。
• 多会话：私聊按 open_id、群聊按 chat_id 映射独立 DSH session，持久化、可恢复。

License

MIT