飞书遥控 potterlee369-prog/dsh-feishu

dsh-feishu

DSH 宿主插件：用飞书控制本机 DSH。手机或电脑上的飞书客户端给机器人发 @dsh ，插件通过飞书长连接（WebSocket，无需公网 IP）收到消息，把指令作为用户消息投递给一个专属 DSH 会话执行完整 agent 流程（工具调用、读写工作区、权限审批都在本机 DSH 内完成），等 DSH 空闲后把最终回复发回同一个飞书会话——手机和 PC 双端同步可见。

手机飞书 / PC 飞书 ──► 飞书服务器 ──长连接──► dsh-feishu 插件（跑在 dsh web/headless 进程内） │ 创建/复用 DSH 会话（ctx.apiProxy.sessions） │ DSH Agent 执行（工具、工作区、权限） │ 飞书双端看到回复 ◄── im.message.create ──────────────┘

飞书后台要求（配置过一次即可）

1. 飞书开放平台 → 自建应用 → 开通机器人能力（建议机器人名就叫 dsh，群聊里 @ 它）。
2. 复制 App ID（cli_...）与 App Secret。
3. 权限管理添加（以应用身份开通）：
- im:message.p2p_msg:readonly（读取用户发给机器人的单聊消息）——私聊必须
- im:message.group_at_msg:readonly（读取群聊中 @ 机器人的消息）——群聊必须
- im:message:send_as_bot（以机器人身份发消息）
- 如果希望机器人读取群里所有消息（不 @ 也触发），再额外加 im:message.group_msg
4. 事件与回调：
- 订阅 接收消息 im.message.receive_v1
- 订阅方式选 “使用长连接接收事件”
5. 创建应用版本并发布（组织内可用即可，无需上架）。修改权限或事件后必须发新版，否则不会生效。

构建与安装

cd E:\dsh_custom\dsh-feishu
npm install # 首次
node build.mjs # 产出 lib/index.js + lib/index.d.ts
node smoke-test.mjs

安装到 web profile（link 方式，源码改动即时生效）
dsh plugin --profile web add "E:\dsh_custom\dsh-feishu"

配置 App ID / App Secret（推荐：设置页面）

重启 dsh web 后打开 设置 → 飞书，在页面上填写：

- App ID（cli_...）与 App Secret；
- 触发词、工作目录等可选项；
- 点 保存 —— 凭据变化会立即重连飞书长连接，无需再重启。

设置保存在本机 DSH 设置文档中（settings 服务），也可以在 cordis.patch.yml 里给 feishu 行写 appId/appSecret 作为底层默认值，页面保存的值会覆盖它：

- id: feishu
name: dsh-feishu
config:
appId: '' # 可留空，在 设置 → 飞书 里填 appSecret: '' trigger: '@dsh' cwd: E:\your\workspace # DSH 会话工作目录（留空 = 宿主默认）

App ID / Secret 也可以用环境变量 DSH_FEISHU_APP_ID、DSH_FEISHU_APP_SECRET；环境变量仅在配置值为空时兜底。

使用

| 场景 | 操作 |
| 单聊机器人 | 直接发消息即可（默认私聊免 @，例如发“帮我看看当前目录有哪些文件”） |
| 群聊 | 把机器人拉进群，发 @dsh 帮我写一个周报，只有 @ 它才触发 |
| 发图片（私聊） | 直接发图片，DSH 会调用本机 dsh-image-recognizer 识别后回复 |
| 发图片（群聊） | 在群里 @机器人 后发图片，机器人识别后回复 |
| 发文件（私聊） | 直接发送文件；文件会下载到 DSH 工作目录的 .feishu-inbox/，然后交给当前会话处理 |
| 发文件（群聊） | 在群里 @机器人 后发送文件；文件会下载到 .feishu-inbox/，然后交给当前会话处理 |
| 从 DSH 发文件回飞书 | 发送 /send ，例如 /send reports/final.pdf；成功后只发送文件附件，不额外发送确认文本 |
| 私聊也要 @ | 在设置页关闭“私聊免 @ 触发”，或把 p2pNoTrigger 配为 false |
| 全部消息触发 | 把 trigger 配成空字符串 '' |

内置命令（私聊直接发命令，群聊前缀 @dsh ）：

| 命令 | 作用 |
| /help | 显示帮助 |
| /status | 桥接状态（长连接、工作目录、会话数） |
| /new（/reset） | 为当前飞书会话开启新的 DSH 会话，清空上下文 |
| /send | 将 DSH 工作目录内的普通文件上传并发送到当前飞书会话（也支持 /发送 ），成功后不发送文字确认 |

每个飞书会话（chat_id）对应一个独立的 DSH 会话，历史上下文会跨消息保留；同一会话内消息按到达顺序串行执行，不会互相打断。

配置项

| 键 | 默认 | 说明 |
| appId | '' | 飞书 App ID；空则读 DSH_FEISHU_APP_ID |
| appSecret | '' | 飞书 App Secret；空则读 DSH_FEISHU_APP_SECRET |
| trigger | '@dsh' | 群聊（及关闭免 @ 时的私聊）触发前缀；'' = 每条文本消息都触发 |
| p2pNoTrigger | true | 私聊免 @：单聊机器人直接发消息即触发 |
| cwd | '' | 飞书消息创建的 DSH 会话工作目录；空 = 宿主默认 |
| agentPreset | '' | 可选 agent preset id |
| ack | true | DSH 执行前先回复“收到，DSH 处理中…” |
| replyChunkSize | 1800 | 长回复按字符预算分段（段落边界处切开） |
| timeoutMs | 600000 | 等 DSH 空闲的上限；超时回复“仍在处理中” |

工作原理

- 插件依赖宿主服务：apiProxy、agents、sessions（在 inject 中声明）。
- 收到触发消息后调用 ctx.apiProxy.sessions.create({ sessionId, cwd }) —— 与 Web 输入框相同的会话创建路径，sessionId 固定为 feishu-，重启后同 id 恢复既有会话。
- 每个飞书会话首次使用前读取宿主 host.describe 的默认 provider/model；若历史请求头仍记录旧路由，则调用 session.selectModel 同步到当前默认模型，再提交消息。
- 然后 ctx.apiProxy.sessions.prompt({ mode: 'queue', content }) 把消息投进 DSH agent 的收件箱；文字消息传 { type: 'text' }，图片消息会先下载飞书图片并传 { type: 'image', mediaType, data }，由本机 dsh-image-recognizer 识别后交给 DSH。
- 通用文件消息会通过 messageResource 下载到该会话工作目录的 .feishu-inbox/，再以包含相对路径的文字提示投递给 DSH；这避免把通用文件伪装成当前宿主只支持的图片附件。
- agent.whenIdle() 等待本轮全部活动（含工具调用与后续轮次）结束，再从会话事件流中取出最后一个 assistant/message 的文本块，经 client.im.message.create 发回飞书。
- /send 只允许读取当前 DSH 工作目录内的普通文件，单文件按飞书机器人接口限制不超过 30 MB；飞书消息资源下载按接口限制不超过 100 MB。
- 飞书长连接由官方 @larksuiteoapi/node-sdk 的 WSClient 维护，自动重连；插件卸载时关闭连接。

排查

| 现象 | 处理 |
| 设置页没有“飞书”栏目 | 确认已运行 dsh plugin --profile web add，并重启 dsh web 后刷新页面 |
| 启动日志提示 appId/appSecret not configured | 打开 设置 → 飞书 填写并保存，或设置环境变量后重启 |
| 设置页显示“设置服务不可用” | 宿主未挂载 settings 服务；改在 cordis.patch.yml 配置 |
| 日志出现 invalid appId | App ID 必须是 cli_ + 16 位十六进制格式 |
| 长连接一直 not ready / onError | 确认事件订阅方式选了“长连接”，App Secret 正确，机器没断网（长连接由本机主动连出，不需要公网） |
| 长连接已 ready 但完全收不到飞书事件 | 重点检查：im.message.receive_v1 是否已订阅；是否开通 im:message.p2p_msg:readonly（私聊）/ im:message.group_at_msg:readonly（群聊 @）；应用版本是否已发布。只加 im:message 或只改配置不发布，都会出现这种“连接正常但没事件”的情况 |
| 飞书收到消息但机器人不回复 | 检查 im.message.receive_v1 订阅、im:message.p2p_msg:readonly/im:message.group_at_msg:readonly/im:message:send_as_bot 权限、应用版本是否已发布；群聊里机器人要被拉进群 |
| 文件收到了但 DSH 找不到 | 检查提示中的 .feishu-inbox/，该路径相对于当前 DSH 工作目录；文件消息在群聊中必须 @ 机器人 |
| 文件发送失败 | /send 只接受当前 DSH 工作目录内的普通文件，且单文件不能超过 30 MB；确认机器人仍在会话中并拥有 im:message:send_as_bot |
| 回复“无法创建 DSH 会话: session-conflict” | 同一 feishu- 会话曾在别的 cwd 下创建过；改 cwd 或发 /new 换会话 |
| 发送失败 code ... | 机器人未加入群、或应用可用范围不含该用户；看日志中的飞书错误码 |

开发循环

cd E:\dsh_custom\dsh-feishu
node build.mjs # 修改 src/index.ts 或 src/client 后重新构建
node smoke-test.mjs # 宿主半侧冒烟（mock 宿主，不联网）
node client-smoke.mjs # 客户端 bundle 工厂形态
重启 dsh web 生效