LittleInk/dsh-feishu-bot

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

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

飞书用户 ──消息──> 飞书开放平台 ──长连接(WS)──> dsh-feishu-bot 插件 ──> 本机 DSH agent
飞书用户 ，飞书账号登录 → 开发者后台 → 创建企业自建应用。
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 中运行（在仓库根目录）：
powershell
git clone https://github.com/Little/dsh-feishu-bot.git
cd dsh-feishu-bot

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

可选参数：
powershell
.\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 件事：
bash
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）追加：
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 列表追加（只需本插件一行）：
yaml
- 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 或错误信息 |

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

排障

仓库内 scripts/check.mjs 一键健康检查（只读，不改任何配置）：
powershell
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/ 即可启用：
powershell
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