dsh-plugin-feishu-im

dsh-plugin-feishu-im

中文 | English

DeepSeek Harness 的飞书 IM 通道：在 DSH Web 的「设置 → 飞书 IM」里扫码创建一个专属飞书机器人， 把任务进展、审批请求、提问推到飞书，并在飞书里直接指挥 DSH。

它能做什么

安装

# 从 npm 安装（推荐）
plugin_manager install_bundle dsh-plugin-feishu-im

# 或者
npm i -g dsh-plugin-feishu-im

装好后进入 设置 → 飞书 IM。

做成服务（不需要 sudo）

设置页「部署方式」可以把 DSH 装成用户级 systemd 服务（~/.config/systemd/user/dsh.service，Restart=always）， 全程不需要 sudo —— 这对只能通过网页 / 飞书操作、没有终端可以输入密码的部署尤其重要。

• 设置页会先检测当前是否已经是服务模式（系统级 / 用户级），已托管时按钮禁用并显示是哪一种；
• Windows 下该选项直接禁用，并提示「当前仅支持 Linux（用户级 systemd）与 macOS（launchd）」；
• 未托管时会提示风险：进程退出或重启机器后不会自动拉起、关闭终端或注销会中断；
• 已经由系统级 dsh.service 托管时，插件会拒绝安装用户级服务，避免两个进程抢 3080；
• 「注销后仍运行」需要 root 一次性执行 loginctl enable-linger $USER（本机已开启）；
• 装好后的重启走 systemctl --user restart dsh.service，scripts/restart-dsh.py 会自动优先用它， 并仍按「忙碌检测 → 飞书预告 → 重启 → 新进程发完成通知」的流程执行。

连接飞书

扫码创建（推荐）

1. 点「生成连接二维码」，用飞书手机端扫码；
2. 按提示确认创建；
3. 页面自动拿到凭据、写入本机并校验机器人身份。

飞书这一侧用开放平台的设备码注册流程（accounts.feishu.cn/oauth/v1/app/registration， archetype=PersonalAgent），创建出来的应用已带消息权限，不需要手动勾选。这条接口不在飞书公开文档里， 可能随平台演进；失败时界面会退回到手动填写。

手动填写

已有应用时直接填 App ID / App Secret，但需要自己配置：

• 开启「机器人」能力
• 权限：im:message、im:message:send_as_bot、im:resource、im:chat
• 事件：im.message.receive_v1（长连接）
• 回调：card.action.trigger（回调配置页，不是事件配置页；同样用长连接）
• 发布一个应用版本（权限与回调不发布会不生效，点按钮会报 200340）

指挥与询问策略

审批与提问默认只走飞书：宿主不把同一条请求转给网页，所以在飞书答完就是最终结果，不会留下一个还在等你的网页提示。 打开「网页与飞书同时询问」会恢复并行：两边都弹，谁先回答用谁（飞书先答时，网页那条要等本轮结束才消失）。

飞书等待上限：1–120 分钟，或「永不超时」。超时后卡片失效（原地改写为「⏱ 已超时」），请求转回 DSH 网页。 这段时间里 DSH 网页不会弹原生的选择窗口——独占模式下请求只存在于飞书。

卡片状态

所有卡片终态都是原地改写，选项按钮不再保留：

改变过消息路由的卡片会在底部标明当前路由，例如「消息路由：已切回原来的会话，接下来的消息会照常发给 DSH。」

提问卡片

点选项直接作答，或点「✏️ 输入你的答案」后在下一条消息里写答案。

授权卡片

任务完成

会话列表与切换

/sessions [关键字]（别名 /history）发一张卡片：最多 10 个按钮，按钮上直接是会话标题 · 最后互动时间（如「修 CI · 2 小时前」），点按钮即切换；正文不再重复标题，只提示可以用 /sessions <关键字> 检索。也可以 /resume <编号|id|标题>。 切换后就地改写那张卡，只保留目标会话标题。列表会过滤子代理会话，并标出当前会话（←当前）。

模型也能用：内置工具 feishu_sessions（list / current / switch），在飞书发起的会话里可以直接说「切到第 3 个会话」。

会话建在哪

设置里的「飞书会话的位置」控制两件事：

• 工作文件夹：默认 ~/dsh-plugin-feishu-im，不存在会自动创建；
• 工作区名称：默认「飞书IM」，工作区列表里按这个名字分组；改名后下一次新建飞书对话时同步到已有工作区。

已经在用的对话不受影响；想搬到新目录，发 /new 开一个即可。

会话权限

每个飞书对话独立保存一个权限模式，切换后立即作用于它绑定的会话：

切换是两步：/permission（或 LLM 通过 feishu_permission 工具申请）先发一张带四种模式的卡片； 点其中一种后再弹确认卡片（显示「从 X → 到 Y」），点「确认修改」才真正生效，点「取消」则什么都不变。 超时未确认会原地改成「⏱ 已超时」，权限保持原样。

实现上：沙箱模式是会话级的 sandbox/mode 事件，审批策略用 approval.setPolicy，auto 模式交给宿主的 Auto Review（dsh-experimental-auto-review）逐次评估。设置页可以改新会话的默认模式，单聊用 /permission 覆盖。

安全模型

• App Secret 只存在 <DSH_HOME>/feishu-im/state.json，权限 0600，不回传浏览器、不写进 cordis.patch.yml；
• 设置页的接口是 DSH 的 exact Fetch 路由（/api/feishu-im/*），只有本机已认证的 owner 浏览器能访问；
• 飞书侧按 open_id 允许列表过滤，扫码授权的人自动进入列表；列表为空时接受第一个来消息的人并设为唯一使用者；
• 关闭「允许在飞书里指挥 DSH」后，飞书只收通知，不接指令；
• 危险操作仍走 DSH 的审批策略；卡片只是把同一次请求搬到手机上回答；
• 同一个飞书应用不要在别处同时开长连接（飞书会把事件随机投给其中一条）。

排障

打开宿主追踪（默认关闭，也可 touch <DSH_HOME>/feishu-im/trace.on 运行时打开）：

DSH_FEISHU_IM_TRACE=1 dsh web

日志在 <DSH_HOME>/feishu-im/host-probe.log：路由注册、长连接起停、turn 事件、通知发送、卡片点击。

开发

测试会写 fixture 状态，sessions-smoke / answers-smoke 在未设置 DSH_HOME 时会自己指到临时目录——不会碰你 ~/.dsh/feishu-im/state.json 里的真实凭据。手动跑其它会写状态的脚本时，请依然带上 DSH_HOME=$(mktemp -d)。

npm test              # tool-schema + inbound + answers + sessions + service + render
npm run test:render   # 真 React 渲染每个页面状态（需要 react/react-dom）
npm run test:live     # 真连飞书，回读卡片内容并断言三种终态
npm run test:timeout  # 真连飞书，走一遍超时转回

发布走 .github/workflows/release.yml：trusted publisher（OIDC） 自动发布并生成 provenance，不使用 NPM_TOKEN。 push 一个 v* tag 即可。

License

MIT