飞书桥接 amlyczz/dsh-lark-link

🪶 dsh-lark-link

DeepSeek Harness × 飞书/Lark 双向桥接 — 把你的 DSH 智能体装进飞书，扫码 30 秒上线，随时随地对话

DeepSeek Harness × 飞书/Lark 双向桥接插件 —— 把你的 DSH 智能体装进飞书：扫码 30 秒上线、消息零丢失、卡片化交互、每个飞书会话独立智能体。手机上随时给智能体派任务、看结果、切模型切模式——不用守着终端。

🌟 为什么选 dsh-lark-link

- 零门槛：扫码即建飞书应用，不用手搓开放平台、不用配回调、不用公网服务器
- 零丢失：出站 Outbox + 入站 WAL 双持久化，进程崩溃 / 插件热更 / dsh 重启，消息和回答都补得回来
- 零学习成本：所有切换类命令都是单选卡片，点一下即生效；DSH 原生命令（/goal /compact …）直接用
- 真智能体：不是聊天机器人——bash/文件/子代理/工作流全套工具，飞书里跑完整 Harness
- 统一控制台：DSH 设置面板与插件详情页无缝复用专属控制台，四维监控、动态调控、无任何侧栏挤占

✨ 特性

| 能力 | 说明 |
| 🎨 官方品牌 Logo | 原创设计的 Feather-Nexus 矢量微标（assets/icon.svg / assets/logo.svg），原生注入设置面板与包导出，极高视觉辨识度 |
| 🎯 一键认证 | /lark setup 扫码创建飞书应用（自动订阅消息事件 + 群聊全量 + 表情权限 + 用户基本信息），30 秒上线，无需手搓开放平台；也支持 DSH_LARK_APP_ID/SECRET 手动通道 |
| 🧠 多模式智能体 | 标准 / PTC / 极简 / Cordis preset + 你在 GUI 自建的 preset，飞书发 /mode 出单选卡片即切（默认 PTC：一次执行多步工具调用，更快更省） |
| 🎛 权限分级 | 只读 / 工作区写 / Full access 三种权限，/permission 卡片即切；默认 Full access 全放行 |
| 🎨 卡片化命令 | /mode /permission /model 全部是单选按钮卡片——点一下即切换，不用记命令拼写；模型选择按供应商分组展示 |
| 💬 意图确认转发 | 模型提问（ask_user_question）→ 飞书意图确认卡片（选项按钮 + 下拉多选 + 自定义输入），答完模型继续，飞书里完成完整交互闭环 |
| 😊 表情回执 | 收到消息随机表情「已收到」；回复完成 / 命令完成打 DONE ✅（只使用飞书实测有效 emoji） |
| 💪 出站零丢失 | 持久 Outbox（JSONL + at-least-once + 幂等键 + 分航道并行 + 失败离队不阻塞 + 周期清理），kill 重启自动续投；桥命令回复同样走 Outbox |
| 📥 入站请求补发 | 智能体处理到一半插件/dsh 崩溃/重启，重启后自动重新触发这条用户消息（不再静默丢请求）——Inbound WAL 持久化 + 原子快照压实 + 启动对账 + 次数上限/时间窗防空转；支持 /lark replay 手动触发与 replay drop 丢弃 |
| 🛡 连接自愈 | probe 驱动受控重连 + QuotaGovernor 配额熔断（窗口过期自动解除、自动重连）+ 断连补偿；环境代理自动规避 |
| 🔒 四级脱敏与 UTF-8 守护 | 敏感密钥（Bearer/sk-/app_secret/t-token 等）全链路自动脱敏；UTF-8 字符字节预算有界截断，杜绝卡片越界报错与乱码 |
| 🔀 命令三级分流 | 桥特有命令桥处理；DSH 注册命令原生执行；/goal、未知 /xxx、普通消息原样注入智能体（无拦截无门禁）；skill 无前缀——直接描述任务，模型自动加载 |
| 📎 入站多媒体 | 飞书图片 → 视觉模型看图（attachment 存储）；文件 → 有界文本提取进提示词 |
| 📤 出站多媒体 | 模型经 lark_send_local_file 主动回传本地图片/文件（工作区白名单 + 大小校验 + 格式自动降级） |
| 🩺 一键诊断 | /doctor → ZIP 诊断包（含当前会话完整 DSH session log + 脱敏配置 + ISSUE.md），发回飞书，贴给 AI 即可定位 |
| ✍️ Markdown 渲染 | 回复自动检测 markdown → CardKit 卡片渲染（标题/列表/代码块/表格），纯文本走文本消息 |
| 🌊 可选流式输出 | /lark-config streaming.enabled=true 热开 CardKit schema 2.0 流式卡片，逐字打印（默认关，省流量） |
| 🎯 长任务目标驱动 | /goal <目标> 直接在飞书启动自主长任务闭环；支持 /goal pause（暂停）、/goal resume（继续）、/goal clear（清除）；纯文本自然对话交互 |
| 🔄 会话管理与恢复 | /new 当前工作区新起会话；/resume 极简卡片恢复历史会话（点选/序号/id 前缀，自动提取会话真实标题，彻底解决跨重启 live session 冲突）；/workspace <路径> 切换工作区；按会话完全独立持久化工作区/模型/模式 |
| 🖥 复用 DSH Web GUI | 彻底干掉侧边栏图标（零挤占变形），设置页（settings.section）与插件详情页（plugins.bundle.config）复用统一高保真管理控制台：包含 4 维监控卡片、一键扫码配置（QR 自动刷新）、实时运行时策略调整（免 @/预设/权限/补发开关）、常用命令速查与全功能 Web 操作接口 |
| 👥 访问控制 | allowlist 限定可对话的 open_id 白名单；groupPolicy 群聊触发策略（open / mention / keywords / reply）；denyList 命令前缀拒绝兜底 |
| 🔓 默认 Full access | 沙箱全访问 + 审批 never，零打扰 |

🚀 快速开始

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

安装（官方 dsh plugin 机制，无侵入）——包以官方 bundle 格式分发（package.json 的 dsh.bundle + cordis.patch.yml），安装后自动并入 profile 的 dsh.profile.bundles 层：

1. 安装插件（npm 官方包，装预构建产物，无需构建许可）：
dsh plugin --profile web add dsh-lark-link@latest --ignore-scripts

升级：
dsh plugin --profile web update dsh-lark-link --latest --ignore-scripts
#
或本地 tarball（先在源码目录 npm pack 生成，离线/内网友好）：
dsh plugin --profile web add ./dsh-lark-link-<version>.tgz --ignore-scripts
#
或 GitHub 源码（需 prepare 构建 + allowBuilds 许可）：
dsh plugin --profile web add github:amlyczz/dsh-lark-link

--ignore-scripts：飞书 SDK 的传递依赖 protobufjs 带一个可忽略的 postinstall，pnpm 11 安全策略会拦截并返回非零退出码；加此参数跳过（protobufjs 不执行 postinstall 完全可用）。若你的 pnpm 已全局放行，可不加。

--profile web：指定安装到哪个 profile（web / tui / headless）。dsh plugin 是 pnpm 的转发命令，用法为 dsh plugin --profile <name> <pnpm 参数>。想让飞书和 GUI 共用 web profile 就保持 web。

每次发布后：更新到最新版

不要依赖 @latest：它读的是镜像返回的 dist-tags.latest 标签——npmmirror 等镜像的标签缓存可能没刷新（版本元数据已同步、tag 还指着旧版），pnpm 看到「已装版本 == tag」就报 Already up to date，哪怕新版早就发布了。tag 是镜像说了算，版本号是你说了算。

1. 绕过标签，直接看官方源的真实版本列表：
npm view dsh-lark-link versions --registry https://registry.npmjs.org

2. 显式版本号安装（最可靠，不依赖镜像标签）：
dsh plugin --profile web add dsh-lark-link@<新版本号> --ignore-scripts

3. 或强制官方源再走 @latest：
dsh plugin --profile web add dsh-lark-link@latest --ignore-scripts --registry https://registry.npmjs.org

再遇 Already up to date 但怀疑有新版：先 dsh plugin --profile web outdated 看它认为的版本——outdated 都显示旧版，基本就是镜像标签没刷新，用上面的显式版本号绕开。装完重启 dsh web 生效。

2. 启动 DSH Web GUI
dsh web

3. 在 GUI 的输入框（或终端 CLI）执行： /lark setup # 扫码创建飞书应用（30 秒，面板显示二维码） /lark start # 启动桥接

然后飞书搜索你的机器人，发任意消息——收到表情回执 + 完整回复即端到端连通。群聊免 @，直接说话即可。

⌨️ 命令

DSH 侧（GUI 或终端）

/lark setup 扫码一键建应用（或 DSH_LARK_APP_ID/SECRET 手动通道） /lark start|stop|restart|status 桥接生命周期与全链路健康 /lark replay 手动补发入站请求；replay list 查看 WAL、replay drop <id> 丢弃、replay auto on|off 切换启动自动补发 /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 × Feishu/Lark bridge — 把 DSH 智能体放进飞书。扫码 30 秒上线，随时随地聊天。

🌟 为什么选 dsh-lark-link

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

✨ 功能

| 能力 | 说明 |
| 🎯 一键授权 | /lark setup 扫码即可创建飞书应用（自动订阅消息事件 + 群组全量 + 表情回应）。30 秒完成接入；也支持手动配置 DSH_LARK_APP_ID/SECRET 通道 |
| 🧠 多模式智能体 | 标准 / 代码 / 极简 / Cordis 预设 + 你的自定义 GUI 预设；/mode 弹出单选卡片——点一下即切换（默认代码模式：一次调用完成多步工具） |
| 🎛 权限分级 | 只读 / 工作区可写 / 完全访问；/permission 卡片即时切换（默认完全访问） |
| 🎨 卡片式命令 | /mode /permission /model 全是单选按钮卡片——点选即可，无需打字；模型按服务商分组 |
| 💬 意图确认 | 模型提问（ask_user_question）以飞书意图确认卡片送达（选项按钮 + 多选下拉 + 自定义文本）；你回答后智能体继续执行 |
| 😊 表情回执 | 收到消息时随机回一个「收到」表情；任务完成时回 DONE ✅（仅使用飞书校验通过的表情） |
| 💪 出站零丢失 | 持久化 Outbox（JSONL + 至少一次投递 + 幂等 + 按通道并行 + 失败隔离 + 定期清理），进程被杀或重启后继续发送；桥接命令的回复同样走 Outbox |
| 🆕 入站请求重放 | 智能体崩溃 / 插件重载 / dsh 在回合进行中重启时，被打断的用户消息会在启动后自动重新触发（不再静默丢请求）——持久化 Inbound WAL + 启动对账 + 尝试次数/时间上限；/status 显示待重放数量。关闭方式：/lark-config replay.auto=false（或 DSH_LARK_AUTO_REPLAY=0），之后用 /lark replay 手动触发；过期或次数耗尽的记录会标记为失败，可用 replay drop 丢弃 |
| 🛡 连接自愈 | 探针驱动的受控重连 + QuotaGovernor 熔断器（配额窗口结束后自动解除并重连）+ 漏消息补偿；自动规避代理环境变量 |
| 🔀 三层命令路由 | 桥接命令 → 桥接层；DSH 命令 → 原生；/goal、未知 /xxx、纯文本 → 原样注入（不设拦截）。技能无需前缀——直接描述任务即可 |
| 📎 入站媒体 | 飞书图片 → 视觉模型（以附件形式传入）；文件 → 有长度上限的文本提取 |
| 📤 出站媒体 | 模型通过 lark_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-link@latest --ignore-scripts
dsh web
/lark setup # scan QR (30s)
/lark start

打开飞书，找到你的机器人，随便发条消息——收到表情回执 + 完整回复，说明端到端跑通了。群聊无需 @ 提及。

安装变体：本地 tarball（npm pack，然后 dsh plugin --profile web add ./dsh-lark-link-<version>.tgz --ignore-scripts）或 GitHub 源码（github:amlyczz/dsh-lark-link，需要构建审批）。升级用 dsh plugin --profile web update dsh-lark-link --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-link versions --registry https://registry.npmjs.org

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

3. Or force the official registry with @latest:
dsh plugin --profile web add dsh-lark-link@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 标签触发的 Publish 工作流。

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

📄 许可证

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

这是社区插件，与 DeepSeek、飞书或 Lark 无隶属关系。