harness-lark

Lark/飞书渠道插件，为 DeepSeek Harness 提供飞书通信能力。通信部分参考 openclaw-lark（MIT, ByteDance Ltd.），适配 dsh 的 Cordis 插件体系。

English | 中文 | 📖 安装文档（GitHub Pages）

> 用 Docker 一键部署（自带插件的 deepseek-harness-lark 镜像）或手动安装插件，见安装文档。

功能

架构

• 会话模型：每个飞书会话（chat_id）映射一个持久的 dsh agent（ctx.agents.resume 优先，失败则 create），上下文跨消息、跨重启保留。
• 通信层：@larksuiteoapi/node-sdk 的 WSClient 长连接 + EventDispatcher 路由（参考 openclaw-lark 的 monitor.ts / lark-client.ts）。
• 回复通路：飞书消息 → agent.followup()；assistant/chunk（reasoning-delta / text-delta）→ 流式卡片；turn/end → 完成卡片并换表情。
• 话题群：topicSeparateSession 开启时话题消息按 thread 独立建 session，回复挂对应话题线程下。
• 工具注册：所有飞书能力以 dsh 工具（ctx.tools.register + defineTool）暴露给模型。

斜杠命令

群聊中命令可带 @机器人 前缀（如 @机器人 /status），插件会自动剥离提及前缀。

安装

前置条件

• Node.js ≥ 22（含 pnpm）
• 已安装 DeepSeek Harness（dsh CLI，可通过 npx @deepseek-ai/dsh web 或从源码运行）
• 飞书开放平台应用（凭据：appId、appSecret；推荐开启长连接模式，无需公网回调地址）
• 飞书开放平台后台：事件订阅 → 订阅方式选择「使用长连接接收事件」，并订阅 im.message.receive_v1 事件

一条命令安装（推荐）

harness-lark 已发布到 npm。插件声明了 dsh.bundle.patch，dsh plugin 安装后会自动把 插件的 cordis.patch.yml 作为 bundle 层应用——无需再手动编辑任何配置，凭据直接读环境变量：

# 1. 设置凭据
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=your_secret

# 2. 安装到 web profile（同时自动应用插件的 cordis.patch.yml）
dsh plugin --profile web add harness-lark

# 3. 启动
dsh --profile web

可选：用仓库提供的一键脚本（安装 + 启动，等价于上面三条命令）：

export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=your_secret
bash scripts/install-dsh.sh web harness-lark

> 用本地源码构建后安装：bash scripts/install-dsh.sh web /path/to/harness-lark > （先在仓库目录执行 pnpm install && pnpm run build）

> 想覆盖插件默认配置（如禁用群聊）时，在 profile 的 $DSH_HOME/profiles/web/cordis.patch.yml > 中按 id: lark 覆盖对应字段即可（见下方配置示例）。

方式二：手动 patch 安装（从源码）

git clone https://github.com/huoxue1/harness-lark.git
cd harness-lark
pnpm install && pnpm run build
dsh plugin --profile web add file:/path/to/harness-lark

或直接在 profile 的 cordis.patch.yml（$DSH_HOME/profiles/<name>/cordis.patch.yml）中加入：

- insert:
    - id: lark
      name: 'harness-lark'
      config:
        appId: !!js process.env.FEISHU_APP_ID
        appSecret: !!js process.env.FEISHU_APP_SECRET
        brand: feishu        # feishu | lark
        connectionMode: websocket
        dmPolicy: open       # open | pairing | allowlist | disabled
        groupPolicy: disabled
        requireMentionInGroups: true
        replyMode: streaming # auto | static | streaming

> 群聊允许 + 流式回复：groupPolicy: open、requireMentionInGroups: false、replyMode: streaming。

方式三：Docker 部署

参见仓库内 Dockerfile / docker-compose.yml（dsh 侧镜像），插件通过 COPY plugins/harness-lark 打进镜像，entrypoint 首次启动时用 dsh plugin --profile web add 装入 profile。

配置

| 字段 | 类型 | 默认 | 说明 | |---|---|---|---| | appId | string | — | 飞书应用 ID（缺省时仅注册工具、不启动网关） | | appSecret | string | — | 飞书应用密钥（缺省时仅注册工具、不启动网关） | | encryptKey | string | — | 事件加密密钥（长连接模式可留空） | | verificationToken | string | — | 事件验证令牌（长连接模式可留空） | | brand | feishu \| lark | feishu | 平台品牌 | | connectionMode | websocket \| webhook | websocket | 事件接收模式 | | provider | string | — | 创建的 agent 使用的 provider（缺省走默认） | | model | string | — | 创建的 agent 使用的模型 | | replyMode | auto \| static \| streaming | auto | 回复模式（auto 走静态文本） | | dmPolicy | open \| pairing \| allowlist \| disabled | open | 私聊策略 | | groupPolicy | open \| allowlist \| disabled | disabled | 群聊策略 | | allowlist | string[] | — | open_id 白名单 | | requireMentionInGroups | boolean | true | 群聊中是否需要 @机器人 | | topicSeparateSession | boolean | false | 话题群消息按 thread 独立建 session（每个话题一个上下文） | | dedupTtlMs | number | 12h | 消息去重窗口 | | agents | array | — | 多 agent 配置（见下）：每个 agent 一个 chat 路由分区 |

多 Agent 配置（agents）

支持多个 agent（可共享同一个飞书应用的 appId/appSecret），按 chat 路由：

- id: lark
  config:
    agents:
      - id: agent-a
        appId: cli_xxx            # 可与其他 agent 共享同一 appId/secret
        appSecret: secret
        cwd: /work/a              # 该 agent 会话的默认工作目录
        agentsMd: |               # 写入 <cwd>/AGENTS.md，作为该 agent 的指令
          # agent-a 的专属指令
        chats: [oc_111, p2p]      # 限定该 agent 服务的 chat：oc_ 精确 id 或 p2p/group 标签
        default: true             # 默认 agent：未匹配其他 agent 的 chat 走它
      - id: agent-b
        appId: cli_xxx            # 共享同一应用
        appSecret: secret
        cwd: /work/b
        agentsMd: "..."
        chats: [oc_222, group]    # 只服务该群组

• chats：oc_... 精确 chat_id 或 p2p/group 类型标签；缺省 = 服务全部（仅限单 agent 组）。
• default: true：未匹配的 chat 路由到此 agent；未标记时取组内第一个。
• 同一 appId 的 agent 共享一条 WebSocket 连接，消息按 chat 路由到各自 bridge（独立 cwd/AGENTS.md/session）。
• 也可在 Web 设置界面（dsh settings 的 harness-lark namespace）编辑 agents，重启后生效。
• 旧的顶层 appId/appSecret（或 FEISHU_APP_ID/FEISHU_APP_SECRET 环境变量）仍兼容，作为单 agent 配置。

工具清单

> 用户数据类工具（云文档 feishu_create_doc/fetch_doc/update_doc，以及多维表格、电子表格、日历、任务系列工具）在用户执行 /feishu auth 授权后，以该用户的身份调用飞书 API；未授权时回退为机器人身份。Wiki/Drive/IM 类工具始终以机器人身份调用。

开发

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run test        # vitest
pnpm run build       # tsdown -> lib/

目录结构

src/
  index.ts                 # 插件入口（name/inject/Config/apply）
  core/                    # 配置 schema、LarkClient、类型、去重、OAuth、token store
  channel/                 # WebSocket 网关 + 事件处理
  messaging/inbound/       # 消息解析、@提及、去重
  messaging/outbound/      # 文本/卡片/媒体发送
  agent/bridge.ts          # per-chat 持久 agent 桥接
  card/                    # 交互卡片构建 + 流式控制器
  tools/                   # 文档/Wiki/Drive、Base/表格/日历/任务、OAuth 工具
tests/                     # vitest 单测

安全说明

与 OpenClaw 插件相同，此插件在授权范围内以机器人身份调用飞书 API，存在模型幻觉、提示注入等固有风险。建议仅作为私聊助手使用，不要加入群聊或允许他人交互；保持默认安全配置（groupPolicy: disabled、requireMentionInGroups: true）。

许可证

[MIT](LICENSE)。通信与卡片设计参考 openclaw-lark（MIT, ByteDance Ltd.）。