harness-lark

Lark/飞书（Feishu）渠道插件，为 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）。注意 SDK v1.65+ 需要显式 start({ eventDispatcher })（旧版构造时自动连接），且事件为 schema 2.0 格式（message.message_type 而非 msg_type）——harness-lark 两者均已适配。
• 回复通路：飞书消息 → agent.followup()；assistant/chunk（reasoning-delta / text-delta）→ 流式卡片；turn/end → 完成卡片并换表情。
• 模型切换：/model 通过 installModelSelection 的 ModelSelectionRef 运行时改写，下一轮生效。
• 工具注册：所有飞书能力以 dsh 工具（ctx.tools.register + defineTool）暴露给模型。

斜杠命令

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

安装

前置条件

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

一键安装（推荐）

插件已发布到 npm（harness-lark），一条命令完成安装 + 配置 + 启动：

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

# 2. 一键：安装插件到 web profile，生成配置，启动 dsh
bash scripts/install-dsh.sh web harness-lark

脚本做的事：

1. dsh plugin --profile web add harness-lark —— 安装插件（npm 包）
2. 生成 $DSH_HOME/profiles/web/cordis.patch.yml（网关配置，已存在则跳过）
3. dsh --profile web 启动

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

手动方式

# npm 发布后（或本地 bundle）
dsh plugin --profile web add harness-lark
# 然后手动编辑 $DSH_HOME/profiles/web/cordis.patch.yml（见下方配置示例）
dsh --profile web

方式三：手动 patch 安装

在 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。

配置

工具清单

用户数据类工具（云文档 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。通信与卡片设计参考 openclaw-lark（MIT, ByteDance Ltd.）。