前言¶
DSH 的日常操作多在本地终端 TUI 或网页端完成。人不在电脑前时，常见做法是公网入口、HTTPS、反向代理或内网穿透，运维和证书成本都不低。dsh-feishu-cui 走另一条路：把飞书私聊当作操作界面（CUI），消息与卡片回调经飞书机器人出站长连接到达本机 dsh web 插件；执行仍在宿主里的 agent 完成，沙箱与审批策略仍由 DSH 决定。下面介绍它是什么、怎么装、飞书侧要配什么，以及日常怎么用。
这是什么¶
dsh-feishu-cui 是社区维护者 wanjiaju3108 发布的 DSH 客户端类插件（当前 package 版本 0.4.2，许可证 MIT）。结构上分两半：宿主侧 lib/ 随 dsh web 加载；浏览器侧设置页 lib/settings/client.js 挂在 DSH Web 界面「飞书CUI会话」分区。
它解决的核心问题是：免公网入口、免证书、免内网穿透的远程使用入口。机器人向飞书建长连接，不必开端口、改防火墙或自建中转；飞书私聊收回答、卡片做选择、自定义菜单做入口，不必单独写移动客户端。配对码一次性绑定 owner，机器人只服务绑定的那一个人。
与 TUI 相比，差别主要在交互：工作区、会话、模型、推理深度、权限、余额等多为卡片和菜单点击；私聊发话排进当前会话队列，回答回到该条消息上的卡片，并随状态从「排队中」「处理中」走到完成或失败。
核心功能¶
下列能力均来自插件 README 与仓库说明，安装前请自行核对源码与许可证。
远程对话与队列
- 私聊发文本 → 进入「当前会话」队列，不打断正在跑的一轮；回答以卡片形式 reply 到原消息，正文逐段更新，跑完收尾为「已完成」「已停止」或「处理失败」。
- 卡片仅展示助手消息里的 text 块；思考、工具调用与工具结果不上屏，完整过程在网页端查看。
- 「停止」打断当前轮（等同网页端停止生成）；「撤回」移除尚未开跑的排队项。正文超过约 30KB 时卡片提示到网页端查看。
菜单与设置（推荐八项子菜单，event_key 须与文档一致）
- 申请配对、工作区列表、会话列表（含新建）、会话重命名、模型、推理深度、权限、余额。
- Agent 反问（
ask_user_question，仅有选项的题）与工具审批在飞书弹卡；谁触发谁答。 - 网页端 / CLI 等处修改当前会话的模型、权限或会话名时，会向 owner 私聊推送「模型已修改」等通知卡。
连接与边界
- 存活看门狗：约 15 秒无回帧则重连；SDK 自动重连，断线期间飞书可能补推事件。
- 只服务 owner；非 owner 或未完成配对时，消息与菜单统一回复「CUI会话未匹配」。
- 仅私聊、仅文本；图片 / 文件 / 附件不支持。只认「飞书当前会话」上下文。
- 凭据引用名
FEISHU_CUI_APP_ID/FEISHU_CUI_APP_SECRET；勿与其他飞书插件共用同一自建应用（长连接集群模式会抢事件）。
安装与启用¶
前置：本机已安装 DSH，dsh 与 dsh plugin 可用；使用 web profile（设置页依赖 Web 服务器）。peer 依赖为 @deepseek-ai/dsh ≥ 0.1.7-rc.1（当前 0.2.x 插件线）；若仍在 DSH 0.1.5，需安装插件 @0.1.0。
在目标 profile 下执行官方安装命令：
dsh plugin --profile web add dsh-feishu-cui
装完后重启 dsh web（插件仅在启动时加载一次）。若安装收尾报 ERR_PNPM_IGNORED_BUILDS: protobufjs，说明 @larksuiteoapi/node-sdk 的 postinstall 被 pnpm 跳过、插件未登记进 profile。在对应 profile 的 pnpm-workspace.yaml 放行后再装一次：
# ~/.dsh/profiles/<profile>/pnpm-workspace.yaml
allowBuilds:
protobufjs: true
本地改插件源码时，可用 link: 指到仓库目录；同样需重启 dsh web。
飞书自建应用（摘要）
开发者后台为你的自建应用配置：
- 事件与回调订阅方式选 长连接。
- 事件：
im.message.receive_v1、application.bot.menu_v6；卡片回调：card.action.trigger。 - 权限至少：
im:message.p2p_msg:readonly、im:message:send_as_bot；设置页要显示绑定人姓名时，还需通讯录相关权限并把绑定人纳入通讯录数据权限范围（详见 README「飞书那边」）。 - 可用范围只勾自己。
- 机器人自定义菜单：子菜单选「推送事件」，
event_key与 README 表格一致（如model、sessions、pairing等）；父菜单仅作容器、不配事件。 - 创建版本并发布；菜单生效约需 5 分钟。
在 DSH Web 设置页「飞书CUI会话」填写 App ID / App Secret（保存后写入 $DSH_HOME/.credentials.yaml 并按新凭据重建长连接）。
典型用法¶
配对（一次性）
- 飞书菜单点「申请配对」，机器人下发输入框卡片。
- 打开 DSH 设置页「飞书CUI会话」，复制页面上的配对码（10 分钟有效、一次性；已绑定则无法再申请）。
- 将配对码填入卡片并确定，提交者成为 owner。换人需先在设置页「解绑」，再在飞书重新申请配对。
日常
- 在菜单「会话列表」选定或新建当前工作区下的会话；无当前会话时发消息会提示「还没有当前会话」。
- 私聊机器人发送任务描述；观察该条消息下的状态卡片。有排队中的回答卡时，无法通过卡片切换会话或工作区。
- 通过「模型」「推理深度」「权限」等菜单改当前会话设置；需要输入文字的只有配对码与会话重命名。
- 设置页点「刷新」查看长连接、绑定用户、在册配对码与凭据状态（页面不自动轮询）。
排查
| 症状 | 可能原因 |
|---|---|
| 发消息无反应 | 长连接未建立或飞书事件订阅未配全 |
| 菜单无反应且日志有「这个菜单项还没有去处」 | event_key 不一致或父菜单误配了事件 |
| 「CUI会话未匹配」 | 未配对或发送者不是 owner |
| 「只支持文本消息」 | 发送了非文本内容 |
更完整的日志与术语说明见 GitHub README。
适用场景与注意¶
适合谁：已在本地或内网跑 dsh web、希望用手机飞书私聊排队提问、切会话与模型、处理 agent 反问与工具审批，且不愿维护公网入口或穿透的 DSH 用户。插件分类为「客户端」，强调交互入口而非替换宿主执行面。
务必知晓：插件与当前 dsh web 进程同权运行 agent 与工具；安装前应阅读 仓库源码 与 MIT 许可证，并理解「仅 owner、仅私聊文本、会话级设置」等边界。DSH 社区插件目录（如 SkillHub 条目页）为独立生态站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-feishu-cui 把飞书私聊做成 DSH 的 CUI：长连接出站、卡片与菜单驱动常用操作，省掉公网与穿透运维。安装命令为 dsh plugin --profile web add dsh-feishu-cui，飞书侧配好长连接、事件、菜单与凭据并完成一次配对即可使用。
- 目录页：https://www.skillhub.cn/plugins/wanjiaju3108/dsh-feishu-cui
- GitHub：https://github.com/wanjiaju3108/dsh-feishu-cui
