飞书桥接增强版 AnFRuJ/dsh-lark-plus

🪶 dsh-lark-plus

DeepSeek Harness × 飞书/Lark 双向桥接私聊 / 群聊 · 卡片按钮 · 审批与提问回传 · 任务板 · goal · 定时任务外加：全程本机的语音转文字 + 网页端播放条

DeepSeek Harness × 飞书/Lark 双向桥接插件：把 DSH 智能体装进飞书——扫码建应用、30 秒上线，在飞书里对话、点卡片、回审批、跑任务、看任务板。在此基础上还带了一条全程本机的语音链路：飞书里按住说话，音频在本机由 SenseVoice 转成文字，并可直接在 DSH 网页端回放——音频不出本机、不调任何云端语音 API。

本仓库是 dsh-lark-link 的 fork（MIT，原作者及贡献者版权保留）。桥接部分沿用上游实现，语音链路为新增。详见文末归属与许可。

🌟 桥接能力（沿用上游）

- 零门槛：/lark setup 扫码即建飞书应用，不用手搓开放平台、不用配回调、不用公网服务器
- 零丢失：出站 Outbox + 入站 WAL 双持久化，进程崩溃 / 插件热更 / dsh 重启后消息与回答都补得回来
- 零学习成本：切换类命令都是单选卡片，点一下即生效；DSH 原生命令直接用
- 真 Agent：不是聊天机器人——bash / 文件 / 子代理 / 工作流全套工具，飞书里跑完整 Harness

✨ 特性

| 能力 | 说明 |
| 🎙 本地语音转写 | 飞书发语音 → 本机 SenseVoice 转文字（见上文）；音频原文件始终保留 |
| 🎯 一键认证 | /lark setup 扫码创建飞书应用（自动订阅消息事件 + 群聊全量 + 表情权限 + 用户基本信息），30 秒上线；也支持 DSH_LARK_APP_ID/SECRET 手动通道 |
| 🧠 多模式 Agent | 标准 / PTC / 极简 / Cordis preset + 你在 GUI 自建的 preset，飞书发 /mode 出单选卡片即切 |
| 🎛 权限分级 | 只读 / 工作区写 / Full access 三种权限，/permission 卡片即切 |
| 🎨 卡片化命令 | /mode /permission /model 全是单选按钮卡片——点一下即切换 |
| 💬 意图确认转发 | 模型提问（ask_user_question）→ 飞书意图确认卡片，答完模型继续 |
| 😊 表情回执 | 收到消息随机表情；回复完成 / 命令完成打 DONE ✅ |
| 💪 出站零丢失 | 持久 Outbox（JSONL + at-least-once + 幂等键 + 分航道并行 + 周期清理） |
| 🆕 入站请求补发 | Agent 处理到一半插件/dsh 崩溃，重启后自动重新触发该消息 |
| 🛡 连接自愈 | probe 驱动受控重连 + 配额熔断 + 断连补偿；环境代理自动规避 |
| 🔀 命令三级分流 | 桥特有命令桥处理；DSH 注册命令原生执行；其余原样注入 Agent |
| 📎 入站多媒体 | 飞书图片 → 视觉模型看图；文件 → 有界文本提取；语音 → 本地转写 |
| 📤 出站多媒体 | 模型经 lark_plus_send_local_file 主动回传本地图片/文件 |
| 🩺 一键诊断 | /doctor → ZIP 诊断包（含当前会话 session log + 脱敏配置） |
| ✍️ Markdown 渲染 | 回复自动检测 markdown → CardKit 卡片渲染，纯文本走文本消息 |
| 🌊 可选流式输出 | /lark-config streaming.enabled=true 热开流式卡片（默认关，省流量） |
| 🖥 复用 DSH Web GUI | 桥 Agent = 原生 DSH session，聊天/工具卡/设置全由 GUI 呈现 |
| 👥 访问控制 | allowlist 白名单；groupPolicy 群聊触发策略；denyList 命令前缀拒绝兜底 |

🚀 快速开始

前置：Node.js ≥ 24，已安装 DeepSeek Harness。语音功能另需 ffmpeg（见上文）。

安装（DSH 官方 bundle 机制，产物已随仓库提交，不执行构建脚本）：

从 npm 安装（推荐，已发布 0.1.0）
dsh plugin --profile <你的档> add dsh-lark-plus

从 GitHub 仓库安装（跟进尚未发版的提交用这条）
dsh plugin --profile <你的档> add github:AnFRuJ/dsh-lark-plus

或本地目录（源码开发时）
dsh plugin --profile <你的档> add link:/path/to/dsh-lark-plus

装完在 DSH 输入框执行一次扫码上线：

/lark setup # 手机飞书扫码，自动创建应用并写入凭据 /lark start # 建立长连接 /lark status # 查看连接/会话/补发计数

之后在飞书里直接发文字、图片、文件，或按住说话发语音。

桌面版 DSH 的 desktop 档由 Electron 独占，CLI 会拒绝；那种情况请走 GUI 侧边栏「插件」页添加同一条地址。

🎙 附加能力：本地离线语音转文字（+ 网页端回放）

它是怎么工作的

飞书语音（OGG/Opus） ↓ 下载（本机 → 飞书 API，唯一的网络请求） ↓ 原文件落盘保留 ← 你随时能在飞书回听，agent 也能复读同一份文件 ↓ ffmpeg 转 16 kHz 单声道 WAV ↓ SenseVoice（sherpa-onnx，CPU 推理）文字 → 作为这条消息的正文交给智能体

- 引擎：SenseVoice（int8，中/英/日/韩/粤 + 自动标点），通过 sherpa-onnx-node 在本机 CPU 上跑。
- 音频去向：只有一次联网 —— 下载约 228 MB 的模型。下载不在插件装载时触发（安装 / 激活 / 启动永远秒级）：第一次收到语音消息、或在侧栏面板点「下载模型」、或调用 POST /dsh-voice-local/v1/model/download 时才开始。之后完全离线。
- 失败不丢消息：模型没下好、ffmpeg 缺失、解码失败时，音频照样落盘，正文留空并把原因写进日志。同一条语音永远不会因为转写失败而消失。
- 可关：配置里 voice.enabled: false 就只保留音频、不做转写。
- 可回放：DSH Web UI 里每条语音正文下面直接有一条播放条（宿主只读路由 GET /plugins/lark-plus/audio?name=…，支持 Range），不用回飞书重听；原始附件卡片会被隐藏，一屏只剩「文字 + 播放条」。

前置条件

| 依赖 | 说明 |
| ffmpeg | 必须。飞书语音是 OGG/Opus，模型只吃 16 kHz WAV。默认按 PATH 查找，也认 voice.ffmpegPath / DSH_VOICE_FFMPEG。 |
| 模型 | 装载时不会下载；首次需要转写时（或手动点「下载模型」/ 调 POST /dsh-voice-local/v1/model/download）才下到 $DSH_HOME/voice/sensevoice/（默认 ~/.dsh/voice/sensevoice/），与 dsh-voice-local 共用同一目录——装过那个插件、或已手动放置模型，都不会重复下载。可用 voice.sha256 / voice.modelSha256 / voice.tokensSha256 做完整性校验。 |

手动放置模型（内网 / 下载慢时）：解压官方归档，保证目录里有 model.int8.onnx 和 tokens.txt 即可：

mkdir -p ~/.dsh/voice/sensevoice
官方：https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/ sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17.tar.bz2
tar -xjf sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17.tar.bz2 \
--strip-components=1 -C ~/.dsh/voice/sensevoice

配置

cordis.patch.yml（profile 的 patch 层）
- id: lark-plus
config:
voice:
enabled: true
modelDir: '' # 空 = $DSH_HOME/voice/sensevoice ffmpegPath: '' # 空 = 自动探测 modelUrl: '' # 主下载源覆盖 mirrors: '' # 逗号分隔，优先于内置镜像（hf-mirror / ghfast） sha256: '' # 可选：模型归档 tar.bz2 的 SHA-256 modelSha256: '' # 可选：model.int8.onnx 的 SHA-256（直连文件源） tokensSha256: '' # 可选：tokens.txt 的 SHA-256 timeoutMs: 600000 # 可选：单次下载尝试上限（默认 10 分钟）；慢源失败即换下一个 ffmpegTimeoutMs: 60000

本地转写接口

语音链路把转写能力也开成了本机路由（可直接被其他工具复用；只服务本机）：

| 方法 | 路径 | 说明 |
| GET | /dsh-voice-local/v1/health | 引擎 / 模型 / ffmpeg / 下载状态 |
| GET | /dsh-voice-local/v1/model/status | 模型文件与下载进度 |
| POST | /dsh-voice-local/v1/model/download | 触发后台模型下载 |
| POST | /dsh-voice-local/v1/transcribe | body = 16 kHz 单声道 PCM16 WAV，返回 { ok, text } |

自测

npm run test:voice # 真实模型 + 真实 ffmpeg；资产缺失时自动 skip
npm run check # tsc --noEmit

📖 完整文档

⌨️ 命令

DSH 侧（GUI 或终端）

/lark setup 扫码一键建应用（或 DSH_LARK_APP_ID/SECRET 手动通道） /lark start|stop|restart|status 桥接生命周期与全链路健康 /lark uninstall-clean 清除凭据与状态目录

飞书侧（卡片化单选，无需记忆拼写）

| 类别 | 命令 | 行为 |
| 选择类 | /mode /permission /model | 单选按钮卡片，点选即切换（动态感知自建 preset 与提供商） |
| 目标类 | /goal [目标\|pause\|resume\|clear] | 启动长任务自主执行 / 暂停 / 恢复 / 清除当前目标 |
| 状态类 | /status /sessions /help | 全链路健康（含 Outbox/补发计数）/ 会话列表 / 帮助卡片 |
| 会话类 | /new /resume [序号\|id] /stop /workspace <路径> | 新会话 / 极简恢复历史会话 / 停当前任务 / 切工作区 |
| 诊断 | /doctor | ZIP 诊断包（session log + 配置 + ISSUE.md） |
| 热改 | /lark-config key=value | 热改配置（如 groupPolicy=open、agentPreset=standard、streaming.enabled=true） |
| DSH 命令 | /compact 等 | 原生执行，结果回飞书 |
| 多媒体 | 发图片/文件 | 图片→视觉模型；文件→文本提取 |
| 意图确认 | 模型提问 | 自动转飞书意图确认卡片，选项或输入作答 |

命令无拦截、无门禁：一切 / 消息要么桥处理，要么原样交 DSH——绝不静默丢弃。skill 无前缀，直接说任务即可。

⚙️ 常用配置（/lark-config 热改，立即生效并持久化）

| 配置键 | 默认 | 说明 |
| groupPolicy | open | 群聊触发策略：open（免 @ 全触发）/ mention / keywords / reply |
| groupKeywords | ["lark","bot"] | keywords 模式下的触发词 |
| agentPreset | ptc | Agent preset（shipped：standard/ptc/minimal/cordis，或 GUI 自建 id；历史别名 code 会自动映射为 ptc） |
| permissionMode | danger-full-access | 权限：read-only / workspace-write / danger-full-access |
| streaming.enabled | false | CardKit 流式卡片（开=逐字打印） |
| reactions.enabled | true | 表情回执 |
| allowlist | [] | open_id 白名单，空 = 所有人可对话 |
| denyList | [] | 命令前缀拒绝兜底 |
| workspaceRoot | | 桥会话工作区根目录（空 = process.cwd()） |
| attachments.retentionHours | 168 | 入站图片/文件的保留时长（小时，默认 7 天；0 = 永久保留）。默认存系统临时目录，到期自动清扫 |
| attachments.dir | | 入站媒体根目录覆盖（空 = 系统 tmpdir；重启生效） |

凭据（appId/appSecret）存放在 DSH credentials 服务，不进配置文件；/lark setup 扫码自动写入。

🩺 遇到问题？

1. 飞书发 /doctor，得到 ZIP 诊断包（完整 session log + 脱敏配置 + ISSUE.md 模板）
2. 把诊断包贴给任意 AI（或在 GitHub Issue 中发出来），即可快速定位
3. /status 可随时看连接 / Outbox / 补发 / 会话全链路健康

🛠 开发者

npm run dev:link # 链接本地 DSH checkout（类型检查/测试需要）
npm run check # tsc --noEmit
npm test # 264 项单元 + 集成测试
npm run build # tsdown → dist/（宿主 ESM + client bundle）
npm pack # 产出可分发 tarball

架构：桥 = Cordis 插件（dsh.bundle 格式），分层清晰：

host（SDK 适配/认证）→ inbound（传输/群触发/断连补偿/Inbound WAL）→ application（命令路由/消息编排/诊断）→ outbound（Outbox/事件转发/卡片）→ sessions（每会话 Agent 管理）。

CI（GitHub Actions）：push/PR 自动跑类型检查 + 264 项测试 + 构建；发布 npm 走 tag release 的 Publish workflow。

📄 许可

MIT — 自由使用、修改、分发。

本项目为社区插件，与 DeepSeek、飞书或 Lark 无隶属关系。

DeepSeek Harness × 飞书/Lark 桥接 —— 把 DSH 智能体装进飞书。扫个二维码，30 秒上线，随时随地开聊。还有完全本地的语音转写，以及 Web GUI 里的播放条。

🌟 为什么选 dsh-lark-plus

- 零配置门槛：扫码建应用 —— 不用折腾开放平台，不用回调 URL，不用公网服务器
- 零消息丢失：持久化 Outbox（出站）+ Inbound WAL —— 崩溃、热重载、dsh 重启都能恢复
- 零学习成本：每个开关都是一张单选卡片；原生 DSH 命令（/goal /compact …）直接可用
- 真正的智能体：完整工具链（bash / 文件 / 子代理 / 工作流），从飞书里驱动

✨ 功能

| 能力 | 说明 |
| 🎯 一键授权 | /lark setup 扫码创建飞书应用（自动订阅消息事件 + 群聊全量 + 表情回复）。30 秒完成接入；也支持手动配置 DSH_LARK_APP_ID/SECRET 通道 |
| 🧠 多模式智能体 | Standard / Code / Minimal / Cordis 预设 + 你在 GUI 里自定义的预设；/mode 弹出单选卡片 —— 点一下就切换（默认 Code：一次调用多步工具） |
| 🎛 权限分级 | 只读 / 工作区可写 / 完全访问；/permission 卡片即时切换（默认完全访问） |
| 🎨 卡片式命令 | /mode /permission /model 全是单选按钮卡片 —— 点一下就行，不用打字；模型按服务商分组 |
| 💬 意图确认 | 模型提问（ask_user_question）会变成飞书意图确认卡片（选项按钮 + 多选下拉 + 自定义文本）；你答完，智能体继续跑 |
| 😊 表情回执 | 收到消息随机回一个「收到」表情；任务完成回 DONE ✅（只用飞书验证过的 emoji） |
| 💪 出站零丢失 | 持久化 Outbox（JSONL + 至少一次投递 + 幂等 + 分通道并行 + 失败隔离 + 定期清理），进程被杀或重启后继续；桥接命令的回复也走 Outbox |
| 🆕 入站请求重放 | 如果智能体挂掉 / 插件重载 / dsh 重启发生在回合中途，被打断的用户消息会在启动时自动重新触发（不再有请求被悄悄丢掉）—— 持久化 Inbound WAL + 启动对账 + 尝试次数/时间上限；/status 显示待重放数量 |
| 🛡 连接自愈 | 探测驱动的受控重连 + QuotaGovernor 熔断（配额窗口过后自动解封并重连）+ 漏消息补偿；自动避开代理环境变量 |
| 🔀 三层命令路由 | 桥接命令 → 桥接；DSH 命令 → 原生；/goal、未知的 /xxx、纯文本 → 原样注入（不设门槛）。技能不需要前缀 —— 直接描述任务就行 |
| 📎 入站媒体 | 飞书图片 → 视觉模型（以附件形式传入）；文件 → 有长度上限的文本提取 |
| 📤 出站媒体 | 模型通过 lark_plus_send_local_file 发送本地文件/图片（工作区白名单 + 大小/格式校验） |
| 🩺 一键诊断 | /doctor → ZIP 包（完整 DSH 会话日志 + 脱敏配置 + ISSUE.md）发回聊天 |
| ✍️ Markdown 渲染 | 回复自动渲染成 CardKit 卡片（标题/列表/代码/表格）；纯文本保持纯文本 |
| 🌊 可选流式输出 | /lark-config streaming.enabled=true 热启用 CardKit schema 2.0 流式卡片（默认关闭，省流量） |
| 🆕 目标驱动长任务 | /goal <objective> 直接从飞书启动自主长任务循环；/goal pause / resume / clear 用自然对话管理执行 |
| 🆕 会话管理 | /new 开新会话；/resume 干净恢复历史会话（按钮/索引/id 前缀，解析真实标题，修复跨重启会话冲突）；/workspace <path> 切换；按会话隔离配置 |
| 🖥 复用 DSH Web GUI | 桥接智能体就是原生 DSH 会话；对话按工作区自动分组；Web 面板显示实时 Outbox/replay 计数器 |
| 👥 访问控制 | allowlist 限制入站到指定 open_id；groupPolicy（open / mention / keywords / reply）；denyList 按命令前缀拒绝 |
| 🔓 默认完全访问 | 沙箱完全访问 + 从不询问审批 |

🚀 快速开始

前置条件：Node.js ≥ 24，且已安装 DeepSeek Harness（npm i -g @deepseek-ai/dsh）。

dsh plugin --profile web add dsh-lark-plus@latest --ignore-scripts
dsh web
/lark setup # scan QR (30s)
/lark start

打开飞书，找到你的机器人，随便发点什么——收到表情回执 + 完整回复 = 端到端打通。群聊无需 @ 提及。

安装变体：本地 tarball（npm pack，然后 dsh plugin --profile web add ./dsh-lark-plus-<version>.tgz --ignore-scripts）或 GitHub 源码（github:amlyczz/dsh-lark-plus，需要构建审批）。升级用 dsh plugin --profile web update dsh-lark-plus --latest --ignore-scripts。

每次发版后如何更新

别依赖 @latest：它解析的是镜像的 dist-tags.latest 标签——npmmirror 类镜像可能给出过期标签（版本元数据已同步，标签仍指向旧版本），于是 pnpm 看到 Already up to date，哪怕新版本已经存在。标签是镜像说的；版本号是你说的。

1. See the real version list, bypassing tags:
npm view dsh-lark-plus versions --registry https://registry.npmjs.org

2. Install by explicit version (most reliable):
dsh plugin --profile web add dsh-lark-plus@<new-version> --ignore-scripts

3. Or force the official registry with @latest:
dsh plugin --profile web add dsh-lark-plus@latest --ignore-scripts --registry https://registry.npmjs.org

怀疑 Already up to date 有问题？先跑 dsh plugin --profile web outdated——如果它也显示旧版本，说明镜像标签过期了；改用显式版本号。安装后重启 dsh web。

⌨️ 命令（飞书侧）

- 选择器（单选卡片）：/mode /permission /model
- 目标：/goal [objective|pause|resume|clear]（自主任务 / 暂停 / 恢复 / 清除）
- 状态：/status /sessions /help
- 会话：/new /resume [index|id] /stop /workspace <path>
- 诊断：/doctor（打包会话日志的 ZIP）
- 热重载：/lark-config key=value
- DSH 命令原生执行：/compact …
- 媒体：向机器人发送图片 / 文件
- 意图确认自动以卡片形式送达

⚙️ 配置（/lark-config，热重载并持久化）

| 键 | 默认值 | 含义 |
| groupPolicy | open | 群触发方式：open / mention / keywords / reply |
| agentPreset | ptc | 智能体预设（standard/ptc/minimal/cordis 或自定义；旧别名 code 映射到 ptc） |
| permissionMode | danger-full-access | read-only / workspace-write / danger-full-access |
| streaming.enabled | false | CardKit 流式卡片 |
| reactions.enabled | true | 表情回执 |
| allowlist | [] | open_id 白名单（留空 = 所有人） |
| denyList | [] | 按命令前缀拒绝 |
| workspaceRoot | | 桥接会话的工作区根目录 |
| attachments.retentionHours | 168 | 入站图片 / 文件的保留时长（小时，默认 7 天；0 = 永久保留）。存放在操作系统临时目录下，按时间清理 |
| attachments.dir | | 入站媒体根目录覆盖（留空 = 操作系统临时目录；重载后生效） |

凭据（appId/appSecret）存放在 DSH 凭据服务中，绝不写入配置文件。

🩺 故障排查

在飞书里发送 /doctor —— 你会收到一个 ZIP，里面有完整会话日志、脱敏后的配置，以及 ISSUE.md 模板。把它交给任意 AI（或开一个 GitHub Issue）。/status 显示实时连接 / Outbox / 重放健康状况。

🛠 开发

npm run dev:link && npm run check && npm test && npm run build

264 个单元 + 集成测试。GitHub Actions CI 在每次 push/PR 时运行类型检查 + 测试 + 构建；npm 发布走 release-tagged 的 Publish 工作流。

架构（Cordis 插件，dsh.bundle 格式）： host（SDK 适配 / 鉴权）→ inbound（传输 / 群策略 / 补偿 / Inbound WAL）→ application（命令路由 / 编排 / 诊断）→ outbound（Outbox / 事件转发 / 卡片）→ sessions（按会话管理智能体）。

📄 许可

MIT —— 可自由使用、修改和分发。

这是社区插件，与 DeepSeek、飞书或 Lark 均无关联。

归属与许可

- 本项目基于 dsh-lark-link（MIT License，Copyright (c) 2026 dsh-lark-link contributors）二次开发，保留了原项目的全部版权与许可声明（见 LICENSE）。
- 新增部分：本地离线语音转写链路（src/voice/、消息链路的 audio 分支、本机转写路由）以及相应的测试。
- 语音引擎 SenseVoice 与运行时 sherpa-onnx 由各自作者以 Apache-2.0 许可发布；模型文件不随本仓库分发，首次使用时从官方发布页下载。
- 本仓库以 MIT License 发布，见 LICENSE。