# ax-feishu-bridge

> 在飞书/Lark 里聊天驱动本机 DeepSeek Harness：扫码建机器人，私聊/群/话题各自维护会话，流式卡片回复图片、文本、群策略。

## Metadata

- Author: [@AX1202](https://github.com/AX1202)
- Repo: <https://github.com/AX1202/ax-feishu-bridge.git>
- GitHub: [AX1202/ax-feishu-bridge](https://github.com/AX1202/ax-feishu-bridge)
- Stars: 34
- Language: TypeScript
- Topics: `chatbot`, `cordis`, `dsh`, `dsh-plugin`, `feishu`, `lark`, `pi-plugin`
- Forks: 18
- Open Issues: 6
- Last push: 2026-08-18T16:58:15.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:AX1202/ax-feishu-bridge
```

## Wiki

## 一句话定位
在飞书/Lark 里聊天就能驱动本机 DeepSeek Harness：扫个码建好机器人，私聊、群、群话题各自维护独立会话，机器人用流式卡片流式回复，支持图片、代码文件、群策略配置。

## 核心能力
- 通过终端扫码快速创建飞书/Lark 自建机器人，无需手填 App ID/Secret
- 私聊、群聊、群话题各自绑定独立的 DSH 会话，互不串扰
- 群聊支持两种触发策略：`open`（不 @ 也回）和 `mention`（仅 @ / 关键词 / 跟帖触发）
- 支持图片（png/jpg/webp/gif）和常见代码/文本附件输入，识别能力取决于所选模型
- 收到消息后立即显示"正在回复…"卡片，同一卡片内流式打字，可中途停止
- 在飞书内通过 `/new` `/resume` `/model` `/thinking` `/workspace` `/status` `/stop` `/config` 切换会话/模型/思考强度/工作区
- 解析飞书 interactive 告警卡片，回复/引用时把原消息一并带给模型

## 技术实现
- **语言**: TypeScript
- **关键依赖**: @larksuiteoapi/node-sdk（飞书官方 SDK）、@deepseek-ai/dsh-attachment-local（图片本地存储）、@deepseek-ai/cordis（DSH 宿主框架）
- **架构模式**: Cordis 插件注入；DSH 端通过 `cordis.patch.yml` 注册 `feishu-harness` 插件，宿主启动时调用 `apply(ctx)`，通过 `ctx.effect` 启停 WebSocket 传输；与 Pi 端通过 `@earendil-works/pi-coding-agent` 的扩展机制注入（同一 npm 包，两个适配器，配置完全独立）
- **入口文件**: DSH 入口 `src/adapters/harness/index.ts`，Pi 入口 `src/adapters/pi/index.ts`，公共逻辑在 `src/feishu/`

## 适用场景
你经常用飞书/Lark 办公，又想随时让本机 DSH 帮你处理代码、文档、调试任务。这个插件让你在不离开聊天窗口的前提下和 DSH 协作：私聊一对一连续对话、群里让机器人按策略接活、告警群把告警卡片丢给机器人让模型分析。比单独开终端交互更自然，也方便和同事共享同一个会话上下文。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+ | `peerDependencies` 声明 `dsh-agent`/`dsh-agent-presets`/`dsh-llm`/`dsh-session`/`dsh-session-query` 均为 `^0.1.0-rc.6` |
| Cordis | ^4.0.1 | `peerDependencies` 声明 `@deepseek-ai/cordis ^4.0.1` |
| Node | ^22.19.0 或 >=24.0.0 | `engines.node` 字段 |
| 平台 | 跨平台 | 源码中无 `os`/`cpu` 限制；仅 Pi 适配器在 Windows 上需要另行配置 Git Bash（DSH 适配器不受影响） |
| 原生模块 | 无 | 全部为纯 JS/TS 依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:AX1202/ax-feishu-bridge
```

## 配置项
DSH 端默认配置存在 `~/.dsh/feishu/config.harness.json`，首次启动未检测到配置时自动进入终端配置向导（推荐扫码，也可手填）。所有配置项也可以通过 `HARNESS_` 前缀的环境变量设置（环境变量 > config.json > 默认值）。

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `appId` / `appSecret` | 字符串 | 飞书/Lark 应用凭证 | 配置向导生成 |
| `domain` | `feishu` / `lark` | 应用所属区域（中国飞书 / 国际 Lark） | `feishu` |
| `groupPolicy` | `open` / `mention` | 群聊触发策略 | `open` |
| `groupKeywords` | 字符串数组 | 群聊关键词触发（逗号/分号分隔），命中后无需 @ | `[]` |
| `groupAlsoOnReply` | 布尔 | 回复机器人消息时也触发，无需 @ | `false` |
| `ignoreBotMessages` | 布尔 | 是否忽略其他机器人消息 | `true` |
| `cardActionMode` | `webhook` / `ws` | 卡片按钮回调通道 | `webhook` |
| `cardActionWebhookHost` | 字符串 | 卡片回调监听地址 | `0.0.0.0` |
| `cardActionWebhookPort` | 整数 | 卡片回调端口（DSH 默认 3002） | `3002` |
| `cardActionWebhookPath` | 字符串 | 卡片回调路径 | `/webhook/card` |
| `language` | `zh` / `en` | 提示语言 | `zh` |
| `reactEmoji` | 字符串 | 收到消息时的表情回应 | `Get` |
| `autoStart` | 布尔 | DSH 启动时是否自动连接飞书 | `true` |
| `parseInteractiveCards` | 布尔 | 是否把飞书告警卡片转成可读文字再给模型 | `true` |
| `includeQuotedMessage` | 布尔 | 回复/引用消息时是否带上原消息内容 | `true` |
| `quotedMessageMaxChars` | 整数 | 引用消息最多带入多少字符 | `8000` |
| `promptNotifySec` | 整数 | 长任务超过多少秒后在飞书发"仍在处理中"提示；`0` 关闭 | `180` |
| `promptTimeoutSec` | 整数 | 任务硬超时秒数；`0` 表示永不超时 | `0` |
| `sendMaxRetries` | 整数 | 飞书接口临时失败时的重试次数 | `2` |
| `streamingReply` | 布尔 | 是否启用 CardKit 单卡流式回复 | `true` |
| `streamPrintFrequencyMs` | 整数 | 流式逐字显示的刷新间隔（毫秒） | `50` |
| `streamPrintStep` | 整数 | 每次显示的字符数 | `1` |
| `streamPushIntervalMs` | 整数 | 向飞书推送最新正文的间隔（毫秒） | `120` |

热更新白名单（与机器人私聊发 `/config` 立即生效）：`groupPolicy` / `groupKeywords` / `groupAlsoOnReply` / `ignoreBotMessages` / `reactEmoji` / `language` / `streamingReply` / `streamPrintFrequencyMs` / `streamPrintStep` / `streamPushIntervalMs`。

## 常见问题

**Q: 为什么机器人没回复？**

A: 按顺序排查三件事：1) 飞书机器人是否已创建并配置好（`/feishu status` 可看 App ID 和连接状态）；2) 插件是否随 DSH 加载（默认 `autoStart=true`，关闭后下次启动才生效）；3) 群聊策略是否要求 `@` 机器人（`mention` 策略下没 @ 不会回）。

**Q: 在群里发了消息机器人不理我，怎么破？**

A: 看策略：`mention` 必须 @ 机器人才回复（可叠加关键词触发或回复机器人消息继续追问）；`open` 策略下群里/话题里直接回，但要确认飞书开发者后台的"获取群组中所有消息"或"获取群组中用户和机器人发送的消息"权限已开启。

**Q: DSH 和 Pi 两边的飞书插件能一起装吗？**

A: 可以。配置分别存 `~/.dsh/feishu/config.harness.json` 和 `~/.pi/agent/feishu/config.pi.json`，互不影响；连接锁按 appId 区分，同 appId 多进程只会留一个持有者；卡片回调端口 Pi 用 3001、DSH 用 3002，开箱即用就错开。

**Q: 图片发给机器人能识别吗？**

A: 取决于两件事：1) 当前会话选中的模型是否支持图像输入；2) Harness 宿主是否提供图片附件服务。本插件在宿主未挂载时会自己注册本地存储到 `~/.dsh/attachments`（挂载失败时退化为仅文字）。仅支持 png/jpg/webp/gif。

**Q: `/workspace` 能用相对路径吗？**

A: 不能。源码显式校验：只接受绝对路径或 `~/` 开头的路径，相对路径会直接报错。

**Q: 长时间跑测试/构建会被判失败吗？**

A: 默认不会。`promptNotifySec=180` 时超过 180 秒在飞书里只发一条"仍在处理中"提示，回复卡片保持"回复中"，完成后正常送达结果；只有显式设置 `promptTimeoutSec>0` 才会硬超时并报失败。

**Q: 怎么重置配置但保留会话历史？**

A: 在 DSH 里运行 `/feishu reset confirm`——会删除 `config.harness.json` 等配置和会话映射，但不会删除任何会话历史内容；下次启动会重新进入配置向导。

## 上手难度
入门 — 安装后首次启动即进入配置向导，扫码完成；无任何必填参数或命令行操作即可在飞书里开始对话。

## 已知问题与限制
- DSH 平台限制：在空白全新会话里敲 `/feishu setup` 等命令不渲染命令记录，需要先在该会话里发一条普通消息再执行命令；`setup` 向导本身不受影响（问答与二维码仍在终端）。
- 图片输入依赖宿主附件服务：宿主未挂载时插件会自行挂载本地存储（存到 `~/.dsh/attachments`），挂载失败时图片输入将不可用并提示降级为仅文字。
- 图片格式仅支持 png/jpg/webp/gif，其他格式会被拒绝并提示。
- `/workspace` 仅支持绝对路径或 `~/` 开头路径，相对路径直接报错。
- 同 appId 的飞书机器人多进程并发启动时只有一个能拿到连接锁（`/feishu status` 会显示 `owned by another process`），其他进程不启动连接。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [ax-feishu-bridge](https://deepseek-plugin.org/plugins/AX1202/ax-feishu-bridge)
Wiki generated by AI (model: `MiniMax-M3`)