imetn/dsh-lark-bridge

English | 中文

一个面向 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 <project-id>。

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 <id>	列出或恢复属于当前飞书来源的 Session
/projects、/project <id>	在私聊中列出或选择 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 <id>。
• 卡片按钮无响应：添加 card.action.trigger。文字任务、/approve、/reject 和直接文字回答仍可使用。
• 附件失败：添加 im:message:readonly，并检查文件大小限制。
• 127.0.0.1:3080 空白：运行 dsh web；Lark Profile 是 Bridge 进程，不是 Web UI。

许可证

MIT