imetn/dsh-lark-bridge

DeepSeek Harness Lark Bridge

CI
License: MIT
Node.js

一个面向 DeepSeek Harness 的安全、双向飞书/Lark 控制器。

你可以从私聊、群聊或话题发任务。Bridge 会把任务交给正确的 Harness Project 和 Session，用一张飞书原生卡片持续更新进度，并把审批、提问、文件、图片和控制操作送回同一段会话。

当前版本已针对 DeepSeek Harness 0.1.0-rc.6 验证。Harness 仍处于开发者预览阶段。

已支持

- 从飞书创建、继续、纠偏、停止、恢复和检查 Harness Session。
- 每个群可绑定独立的 Project、工作目录、模型路线、权限和卡片视图。
- 默认一个话题或线程对应一个隔离的 Session。
- 同一张卡片从运行中原位更新为完成、阻塞、取消或失败。
- 通过卡片允许一次工具调用，或回答 Agent 的结构化问题。
- 接收文字、图片和文件；Agent 可通过 lark_deliver 安全发送工作区文件。
- 每个 Project 或 Session 可选择精简、标准、开发者视图。
- 使用 WebSocket 长连接，无需部署公网 Webhook。

卡片只展示受长度限制、已脱敏的工具摘要，不会展示模型隐藏思维链。

快速开始

需要 Node.js 22+、pnpm、可用的 DeepSeek Harness 模型配置，以及已安装的 dsh CLI，或附近一份官方 Harness 源码。

进入希望机器人控制的 Project，运行：

pnpm dlx github:imetn/dsh-lark-bridge setup --project "$PWD"

向导会自动完成：

1. 打开飞书/Lark 官方页面，创建一个新的机器人应用。
2. 只申请 Bridge 用到的消息、附件、表情、事件和卡片回调能力。
3. 把 App Secret 写入 Harness 的本机私密凭据文件，不写进 Profile。
4. 安装插件，幂等写入 lark Profile，绑定授权用户并启动 Bridge。
5. 打开机器人；平台返回用户 Open ID 时，机器人会主动发送欢迎卡片。

字节租户请添加 --brand larkoffice，国际版 Lark 请添加 --brand lark：

pnpm dlx github:imetn/dsh-lark-bridge setup --project "$PWD" --brand larkoffice

自动流程固定使用 createOnly: true，不会选择或修改已有应用。

使用已有应用

已有应用不会被修改。命令只验证凭据并写入本机 Harness 配置：

printf '%s' "$LARK_APP_SECRET" | pnpm dlx github:imetn/dsh-lark-bridge setup \
--project "$PWD" \
--app-id cli_xxxxxxxxxxxxxxxx \
--app-secret-stdin

如果企业策略不允许一键创建，添加 --manual。向导会打开开发者后台，并提示输入 App ID 和隐藏的 App Secret。

手动创建应用时，请启用机器人能力，选择长连接，发布一个版本，并添加：

| 类型 | 必需配置 |
| --- | --- |
| 权限 | im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:send_as_bot、im:resource |
| 接收入站附件 | im:message:readonly |
| 消息事件 | im.message.receive_v1 |
| 卡片回调 | card.action.trigger |
| 用表情停止任务，可选 | im:message.reactions:read、im.message.reaction.created_v1 |

群聊只申请 @机器人 消息，不需要读取群内全部消息。

验收

在机器人私聊中发送：

/status

再发送一个小任务。回复卡片应展示 Project、结果、耗时，以及当前视图对应的信息。原始任务已经出现在飞书引用回复中，卡片内部不会重复展示。

随时可以检查本机接入状态：

pnpm dlx github:imetn/dsh-lark-bridge doctor

欢迎卡片中的按钮测试是可选项，不点击也能直接发送文字任务。

dsh --profile lark 只启动 Bridge，不会提供 HTTP 页面。http://127.0.0.1:3080 属于单独的 dsh web 命令。

Project、群聊与 Session

大多数团队可以直接采用这套映射：

| 飞书实体 | Harness 实体 | 用法 |
| --- | --- | --- |
| 机器人私聊 | 个人控制面 | 切换 Project，处理私密任务 |
| 一个群 | 一个 Project | 承载一个代码库或长期工作流 |
| 一个话题或线程 | 一个 Session | 把一个任务和它的后续交流放在一起 |

默认 groupSessionScope: thread 时，同一话题内的回复共享上下文，新话题会创建独立 Session。普通群的每条顶层消息也会获得自己的线程 Session。

Profile 只有一个可用 Project 时，Owner 第一次在群里 @机器人就会自动完成绑定。存在多个 Project 时，只需发送一次 @机器人 /bind 。

sender 会为每位群成员保留独立 Session；chat 让全群共享一个 Session，只有明确需要共享上下文时才使用。

卡片信息密度

卡片本身已经回复了原始任务，因此不会再重复任务正文。

| 视图 | 展示内容 |
| --- | --- |
| compact | 结果、耗时、关键操作 |
| standard | 精简视图 + Project、模型、近期工具名、工具次数和总 token |
| developer | 标准视图 + cwd、Session ID、已脱敏工具摘要与耗时、输入/输出/缓存 token |

通过 cardPreset 设置全局或 Project 默认值。当前 Session 可发送 /view compact|standard|developer，或点击完成卡片按钮切换。

控制命令

| 输入 | 行为 |
| --- | --- |
| 文字或附件 | 继续当前 Agent |
| /steer  | 在运行中补充或纠正最近一步 |
| /status | 查看连接、Project、模型、目录、Session 和待处理交互 |
| /stop | 取消当前任务 |
| /approve、/reject | 处理当前一次工具审批的文字兜底 |
| /new | 创建新 Session |
| /sessions、/resume  | 列出或恢复属于当前飞书来源的 Session |
| /projects、/project  | 在私聊中列出或选择 Project |
| /bind [project-id]、/unbind | 管理群聊的 Project 绑定 |
| /commands、/help | 查看 Harness 原生命令或 Bridge 帮助 |

卡片按钮也支持停止、新会话、状态、审批、视图切换和结构化提问。

多 Project 配置

向导会写入 ~/.dsh/profiles/lark/cordis.patch.yml。需要更多 Project 时，在这个文件中追加：

- id: dsh-lark-bridge
config:
appId: cli_xxxxxxxxxxxxxxxx
appSecretRef: DSH_LARK_APP_SECRET
brand: feishu
defaultProjectId: web
groupSessionScope: thread
projects:
- id: web
name: Web App
cwd: /absolute/path/to/web-app
workspaceRoot: /absolute/path/to/web-app
cardPreset: developer
- id: ios
name: iOS App
cwd: /absolute/path/to/ios-app
workspaceRoot: /absolute/path/to/ios-app
cardPreset: compact

每个 Project 还可以设置 chatIds、allowedOpenIds、provider、model 和 inboundDir。从飞书完成的群绑定保存在仅 Owner 可读的 Bridge 状态文件中；静态 chatIds 优先。

安全与文件

- Owner 通过官方授权身份绑定，或使用经过哈希保存、十分钟有效、只能使用一次的 /claim 配对码。
- 用户、群聊、Project 权限和卡片操作者都会在执行 Agent 操作前重新检查。
- 卡片、错误、工具摘要和溢出文件会统一脱敏。
- 入站附件使用 0700 目录和 0600 文件，文件名会被净化并添加随机后缀。
- 出站文件必须是 Project workspaceRoot 内的普通文件，符号链接逃逸会被拒绝。
- 入站事件会去重、拒绝过期消息，并按聊天串行处理。
- 审批按钮只授权当前一次操作。

完整信任模型见 SECURITY.md。

开发与发现

git clone https://github.com/imetn/dsh-lark-bridge.git
cd dsh-lark-bridge
pnpm install --frozen-lockfile
pnpm run check

仓库提交了已构建的 lib/，并打包飞书官方 SDK，所以从 Git 安装不需要现场构建。package.json 通过 dsh.bundle.patch 支持 Harness 自动激活，也包含官方发现关键词 dsh-plugin。

常见问题：

- 收不到消息：发布应用版本，选择长连接，检查消息事件和权限。
- 群聊无响应：把机器人加入群并 @它。只有一个 Project 时会自动绑定；多个 Project 需要 /bind 。
- 卡片按钮无响应：添加 card.action.trigger。文字任务、/approve、/reject 和直接文字回答仍可使用。
- 附件失败：添加 im:message:readonly，并检查文件大小限制。
- 127.0.0.1:3080 空白：运行 dsh web；Lark Profile 是 Bridge 进程，不是 Web UI。

许可证

MIT