前言¶
在 DeepSeek Harness（DSH）里跑 agent，若要把对话和工具结果推到飞书，常见做法是简单桥接：文本能发出去，但 Markdown 表格会变成竖线串，代码块容易被吞，标题层级也会塌成一段。入站若只靠轮询或短连接，任务执行中晚到的消息往往只能排队，体验和上下文连续性都差一截。
dsh-hermes-feishu 是社区维护的 DSH 客户端类插件（维护者 lishuaibing521），把出站渲染、入站 WebSocket 长连接、13 个飞书操作工具、Web 设置页、语音与媒体、以及模型故障转移链收进一个 bundle。下面按安装、配置和实际能力说明用法与约束。
这是什么¶
一句话：DeepSeek Harness 的飞书 / Lark 通道——出站支持图文卡片与原生表格组件，入站走长连接；附带 Web 配置界面与一组飞书 API 工具。
插件 manifest 依赖 dsh.bundle.patch，通过 dsh plugin add 识别为可安装 bundle。运行时依赖 @deepseek-ai/schemastery 与 @larksuiteoapi/node-sdk；渲染、消息路由、卡片构建与媒体处理在插件内自研，未引入第三方 Markdown 渲染库。许可证为 MIT（package.json 版本 1.0.0）。
出站与入站分别解决什么¶
出站按内容类型拆开发送，避免「全当纯文本」：
- 普通文本 → 飞书
text消息 - Markdown → Schema 2.0 交互卡片（
wide_screen_mode） - Markdown 表格 → 飞书原生
table组件（columns+rows），不是 markdown 字符串 ##及更深标题 → 转成粗体（飞书卡片不认多级标题）- 代码块 → 单独成行，降低被吞的概率
入站走 WebSocket 长连接。agent 正在执行任务时，新到的消息不会排队等待下一轮，而是插入当前这一轮继续执行。
核心功能¶
Web 设置页¶
安装后在 dsh「设置 → 插件配置」中可见六个分组：
- 飞书应用 — App ID / Secret、服务区域（飞书 vs Lark）
- Agent 与模型 — 主模型与备用模型链（两级联动下拉）
- 进度气泡 — 思考内容与工具调用的实时显示、工具预览截断长度
- 媒体 — 图片生成与识别的 provider / 模型
- 语音 — STT / TTS 的 provider、语言、音色、语速、音调、音量
- 联网搜索 — search provider、fetch provider
各 provider 运行时从已注册插件动态读取，只列出已配好的项；密钥仅在服务端读取，不下发前端。
13 个飞书工具¶
| 工具 | 作用 |
|---|---|
feishu_send_message |
主发送入口，按内容自动判定 text / 卡片 |
feishu_send_card |
强制发交互卡片（含表格渲染） |
feishu_send_file |
发文件，按扩展名路由（如 ogg→语音、mp4→视频） |
feishu_send_image |
发图片 |
feishu_send_voice |
文本合成语音气泡 |
feishu_reply |
回复某条消息 |
feishu_edit_message |
编辑已发消息（可用于进度更新） |
feishu_delete_message |
撤回消息 |
feishu_download |
下载消息中的图片 / 文件 |
feishu_transcribe |
语音转文字 |
feishu_bot_info |
查询机器人身份 |
feishu_render_preview |
只渲染不发送，调试卡片结构 |
feishu_parse_message |
归一化一条入站消息 |
可靠性与交互¶
- 模型故障转移：主模型失败时按备用链依次切换，走 dsh 原生
agent/requestwaterfall，不重建 agent、不重放消息。 - 审批兜底：工具需人工确认时发飞书卡片，用户点「允许 / 拒绝」；否则 dsh 会 fail-closed，任务可能无声失败。
- 进度气泡：思考与工具调用在同一条气泡里更新，减少刷屏；思考过程默认关闭（
thinkingEnabled默认false），需在「进度气泡」分组中开启。 - 会话持久化：会话映射落盘，dsh 重启后可接续上下文。
安装与启用¶
DSH 生态里是「一切皆插件」；社区目录页在 SkillHub，与 DeepSeek / 幻方无官方从属关系。安装前建议自行查看 GitHub 源码与 MIT 许可证——插件以当前 dsh 进程权限运行。
先做插件安装（官方 README 命令，需 --profile web）：
dsh plugin --profile web add github:lishuaibing521/dsh-hermes-feishu
装完重启 dsh web（将 <你的 dsh 目录> 换成本机路径）：
powershell -ExecutionPolicy Bypass -File <你的 dsh 目录>/start-dsh-hidden.ps1 -Target web
飞书开放平台侧需开启应用的机器人能力，以及在事件订阅里启用长连接模式。仅开出站能力时仍可用工具发消息，但收不到入站消息。
配置¶
凭据通过环境变量配置，写在 ~/.dsh/.env：
| 变量 | 说明 |
|---|---|
FEISHU_PLUGIN_APP_ID |
飞书应用 App ID |
FEISHU_PLUGIN_APP_SECRET |
飞书应用 App Secret |
FEISHU_PLUGIN_DOMAIN |
feishu（国内）或 lark（国际），默认 feishu |
FEISHU_PLUGIN_CHAT_ID |
默认发送目标（oc_ 群或 ou_ 用户） |
FEISHU_PLUGIN_BOT_NAME |
卡片标题中的机器人名 |
变量名不能使用 DSH_ 前缀——dsh 会把 DSH_* 视为仅可由启动环境设置的 bootstrap 变量，写入 .env 会导致启动失败。同类限制还包括 XDG_、DYLD_、BASH_FUNC_ 前缀，以及 PATH、HOME、NODE_OPTIONS、GIT_* 等具体名字。
多数设置在 Web 设置页保存后即时生效；App ID、Secret、域名等与长连接绑定的项修改后需重启 dsh web。
典型用法与自测¶
日常对话与 agent 输出会经通道自动路由到 text 或卡片；需要强制卡片或调试结构时，agent 可调用 feishu_send_card 或 feishu_render_preview。入站消息经长连接进入 DSH 后，由 feishu_parse_message 等工具配合会话映射处理。
仓库内测试脚本（README 原文）：
node test/run.mjs # 渲染 / 入站 / 路由 / 音频解析
node test/load.mjs # 插件加载与工具注册契约
node test/probe.mjs # 真机：token / 机器人身份 / 会话 / 渲染链路
node test/e2e.mjs # 端到端：构建 → 实发 → 读回 → 撤回
probe 与 e2e 会真实连接飞书，需先配好上述环境变量。
适用场景与注意¶
适合：已在 DSH web profile 上跑 agent、希望飞书作为双向通道（含表格与卡片质量、进度气泡、工具审批）的团队或个人。
务必留意的约束（来自 README「已知约束」）：
chat_id必须是机器人已在的会话，否则发送可能报230002。- 音频时长解析仅认 OGG/Opus；其他格式时长回 0。
- 语音识别与合成依赖独立 dsh 插件（如
dsh-baidu-stt/dsh-baidu-tts）；未安装时下拉为空，文字链路仍可用。 - 同一飞书应用同时只能有一条长连接；若其他工具已占用同一应用，此处无法连上。
结尾¶
经过上面的步骤，你可以在 DSH 里用一条长连接收飞书消息，并把 agent 输出按类型发到 text、卡片或原生表格，同时用 Web 页配模型链、语音与媒体 provider。目录与源码：
- 社区目录：https://www.skillhub.cn/plugins/lishuaibing521/dsh-hermes-feishu
- GitHub：https://github.com/lishuaibing521/dsh-hermes-feishu
