@4t145/lark-connector

Readme

# dsh-lark-connector

一个面向 DeepSeek Harness（DSH）的飞书连接器插件。

它把飞书机器人接入 DSH：飞书私聊或群聊中的消息可以进入独立的 DSH 会话，由 Agent 处理后再回复到原飞书消息。同时提供 Web 设置页，用于管理飞书凭据、连接状态以及新建飞书会话的默认配置。

## 功能特性

- 飞书 WebSocket 长连接：使用飞书官方 Node SDK 接收实时消息，不需要额外部署 Webhook 服务。
- 私聊与群聊支持：私聊消息直接响应；群聊仅响应明确 @ 机器人的文本消息。
- 识图能力：自动下载私聊图片消息与富文本 post 中的图片，持久化到 DSH 附件存储后随消息转发给 Agent，供具备视觉能力的模型识图；群聊中的富文本需要 @ 机器人。
- 会话隔离：每个飞书 chat 映射到独立的 DSH session；同一 chat 内按 FIFO 顺序处理，不同 chat 可以并发处理。
- 会话恢复与归档替换：使用 DSH session persistence 保存历史；归档后的 chat 会自动创建新的可见 session。
- 原生 DSH 会话标题：使用飞书聊天标题作为 DSH session 标题，并在消息中标注发送者信息。
- Workspace 归属：可将飞书会话归入指定 DSH workspace；未配置时使用宿主默认目录。
- 新会话默认配置：在 Web 设置页选择 Agent preset、Provider/Model 和 Workspace，应用于之后创建的飞书 session。
- 可靠回复：Agent 完成后将最终文本回复到原消息；超长文本自动分段，消息 ID 有界去重，避免长连接重放造成重复处理。
- 凭据管理：通过 DSH credentials 服务保存 App ID、App Secret、品牌和 lark-cli 路径，也支持环境变量和 .env 来源。
- lark-cli 集成：自动同步应用凭据到 lark-cli，并提供 lark_setup、lark_status 工具检查 CLI、官方 Skills 与连接状态。
- 中英文 Web 界面：设置页面文案跟随 DSH 当前语言。

## 安装

插件以 `@4t145/lark-connector` 名称发布在 npm。发布后可以直接把 npm 包安装到 DSH profile；也可以克隆源码本地安装：

```sh
npm install
npm run build
dsh plugin --profile web add /path/to/dsh-lark-connector
```

插件 bundle 安装后，重启 DSH Web Host。插件注册名为 lark-connector。

## 飞书应用配置

在飞书开放平台创建应用并启用机器人能力，然后：

1. 开通接收和发送消息所需的权限。
2. 在事件订阅中选择“使用长连接接收事件”。
3. 订阅 im.message.receive_v1。
4. 将机器人加入需要响应的群聊。

## Web 设置

![配置界面预览](docs/preview.png)

打开 DSH 设置中的“飞书连接器”页面，可以配置：

- App ID
- App Secret
- Brand（feishu 或 lark）
- lark-cli 路径
- 飞书会话 Workspace
- 新建飞书会话使用的 Agent preset
- 新建飞书会话使用的模型 Provider 和 Model
- 处理期间是否添加 THINKING 表情，并在完成后移除
- 是否使用交互卡片流式更新回复
- 是否在卡片中展示可折叠思维过程
- 是否在卡片时间线中展示工具调用和结果

卡片展示默认参考 lark-acp：思考和工具调用会合并到同一张 Feishu Card，并在生成期间持续更新。若卡片接口不可用，会自动回退为普通文本回复。

图片支持 PNG / JPEG / WebP / GIF：下载后的图片写入 DSH 附件存储，并以 image content block 随用户消息进入会话，DSH 会话界面里也能看到原图。超出单条消息附件数量上限的图片会被忽略；下载失败或格式不支持时降级为纯文本，转发内容中会附带说明。

保存的默认配置只影响之后新建的飞书 session，不会修改已经存在的 session。

## 环境变量

凭据引用如下：

| 引用            | 作用                                        |
| --------------- | ------------------------------------------- |
| LARK_APP_ID     | 飞书应用 App ID                             |
| LARK_APP_SECRET | 飞书应用密钥                                |
| LARK_BRAND      | 品牌，通常为 feishu                         |
| LARK_CLI_PATH   | lark-cli 可执行文件路径；留空时从 PATH 查找 |

例如：

```sh
export LARK_APP_ID=cli_xxx
export LARK_APP_SECRET=your-app-secret
export LARK_BRAND=feishu
npx @deepseek-ai/dsh web --port 8080
```

环境变量来源通常是只读的，优先级高于 Web 页面中保存的同名凭据。

## lark-cli 与官方 Skills

插件提供两个 DSH 工具：

- lark_setup：检查 lark-cli 和官方 Agent Skills；可选择执行官方安装器。
- lark_status：查看应用配置、CLI 版本和连接状态；可选择联网验证凭据。

也可以手动安装：

```sh
npx @larksuite/cli@latest install
```

## 本地开发

```sh
npm install
npm run check
npm run build
```

测试覆盖消息去重、chat/session ID、消息路由和 lark-cli 配置同步等核心逻辑。

## 项目结构

- src/plugin.ts：DSH 插件生命周期、凭据同步和工具注册。
- src/message/：飞书长连接、消息过滤、会话路由和 Agent 回复。
- src/lark-cli/：lark-cli 探测、安装和凭据同步。
- src/client/：DSH Web 设置页和 Typert 客户端 RPC。
- src/typert.host.ts：Host 端 RPC manifest。
- cordis.patch.yml：bundle 安装时使用的 Cordis 插件入口配置。

## 发布

本包通过 GitHub Actions 使用 npm Trusted Publishing（OIDC）发布，不需要长期保存的 NPM_TOKEN：

- .github/workflows/ci.yml：push 到 main 和 PR 时运行 typecheck、lint、格式检查、测试与构建。
- .github/workflows/npm-publish.yml：push `v*` tag（或手动触发）时，在检查与构建通过后执行 `npm publish --provenance --access public`。

npm 包设置中的 Trusted Publisher 需要填写：

- Repository：`4t145/dsh-lark-connector`
- Workflow filename：`npm-publish.yml`
- Environment：留空

首个版本需要先用已登录的 npm 账号手动发布一次以创建包条目，然后配置 Trusted Publisher，之后的版本由 tag 自动发布。

## 许可证

MIT