一句话定位

在飞书/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 协作：私聊一对一连续对话、群里让机器人按策略接活、告警群把告警卡片丢给机器人让模型分析。比单独开终端交互更自然，也方便和同事共享同一个会话上下文。

前置依赖与兼容性

安装方式

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

配置项

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

热更新白名单（与机器人私聊发 /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），其他进程不启动连接。

支持 Deepseek Harness/Pi 接入 飞书/Lark 的消息桥接扩展：在熟悉的聊天界面里与本机 DSH/Pi 持续协作。

中文 · English

DSH、Pi飞书交流反馈群：https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=57dvecbb-95d3-4d01-b689-6ebc3d17c867

扩展有什么问题可以加群反馈。

我的媒体平台 关注我第一时间了解最新AI工具

全平台账号名称：AX阿煊

B站：https://space.bilibili.com/4489397

主要能力

• 通过扫码快速创建飞书/Lark 机器人，减少手动配置
• 支持私聊、群聊、群话题分别维护独立的 Pi 会话
• 支持群聊策略：
  • open：群里和话题里可直接回复，不需要 @，还需手动在飞书开发者后台开启机器人“获取群组中所有消息”的权限
  • mention：只有 @ 机器人、命中关键词或回复机器人消息时才会回复（后两项可选开启）
• 支持图片、代码文件和文本文件等附件输入；图片识别取决于当前模型是否支持图片
• 支持解析飞书 interactive 告警卡片；回复一条消息或卡片时，可把原内容一并带给 Pi
• 支持群聊关键词触发、回复机器人消息继续追问
• 支持在飞书内切换当前会话的模型、工作区、历史会话和思考强度
• 收到消息后立即显示“正在回复…”，后续答案在同一张卡片中流式输出；可停止，并会显示完成或失败状态
• 支持渲染显示 Markdown 格式内容
• Pi agent 关闭后，仍有后台常驻服务可以对话，pi agent无需前台运行。

---

快速开始

下面的快速开始先介绍 DeepSeek Harness（DSH），Pi 用户可直接跳到 Pi 快速开始。

DeepSeek Harness（DSH）

本扩展同时以 DeepSeek Harness 组合包（bundle）形式分发，飞书机器人的配置和聊天体验与 Pi 一致。

1. 安装

前提：本机已安装 dsh

从 npm 安装

dsh plugin --profile web add ax-feishu-bridge --ignore-scripts

2. 启动与首次配置

安装后重启dsh,如果没有检测到飞书机器人配置，会自动进入终端配置向导：推荐选择“扫码自动创建飞书助手”，按提示扫描终端里的二维码即可；如果你已经有现成的飞书/Lark 应用，也可以选择手动填写 App ID 和 App Secret。

配置完成后桥接会自动启动并连上飞书/Lark，之后每次启动 dsh 也会自动连接。

DSH 使用独立的配置文件 ~/.dsh/feishu/config.harness.json（存放在 dsh 自己的家目录下），与 Pi 的配置互不干扰，两边可以同时安装、共存。

3. 在飞书里互动

• 私聊：直接发消息
• 群聊：根据群聊策略决定是否需要 @ 机器人
• 话题：每个话题会独立对应一个会话

群聊策略设为open后，想要不@机器人就能回复任何群内消息，还需要到飞书开发者后台 - 对应机器人事件与回调 - 打开“获取群组中所有消息”或“获取群组中用户和机器人发送的消息”这两个任意一个权限。

/new、/resume、/model、/thinking、/stop、/workspace、/status、/config 等聊天内命令同样可用，完整列表见下文“飞书里怎么用”。

两点区别需要注意：

• DSH 的 /feishu 管理命令是精简版：提供 setup / status / autostart / debug / reset，没有 start / stop / restart——桥接随 dsh 自动启停，由配置里的 autoStart 控制。
• DSH 的环境变量前缀是 HARNESS_（例如 HARNESS_APP_ID），而不是 Pi 的 FEISHU_；卡片回调端口默认也不同——Pi 默认 3001，DSH 默认 3002，两边同时启用也不会冲突。

Pi

1. 安装

pi install npm:ax-feishu-bridge

也可以从 Git 安装：

pi install git:github.com/AX1202/ax-feishu-bridge

2. 初始化配置

在 Pi 里运行：

/feishu setup

推荐选择“扫码自动创建飞书助手”，按提示扫描终端里的二维码即可。

如果你已经有现成的飞书/Lark 应用，也可以选择手动填写 App ID 和 App Secret。

3. 启动桥接

/feishu start

如果开启了自动启动，Pi 会话启动时会自动连上飞书/Lark。

4. 开始聊天

在飞书/Lark 里打开机器人，直接发消息即可。

• 私聊：直接发消息
• 群聊：根据群聊策略决定是否需要 @ 机器人
• 话题：每个话题会独立对应一个 Pi 会话

群聊策略设为open后，想要不@机器人就能回复任何群内消息，还需要到飞书开发者后台 - 对应机器人事件与回调 - 打开“获取群组中所有消息”或“获取群组中用户和机器人发送的消息”这两个任意一个权限。

---

Windows 上运行 Pi Agent 飞书插件配置方法

解决方法

1. 先安装 Git for Windows

安装后一般会有这个文件：

C:\Program Files\Git\bin\bash.exe

这个就是 Windows 上给 Pi 使用的 Bash 环境。

---

2. 配置 Pi 的 settings.json

打开：

C:\Users\你的用户名\.pi\agent\settings.json

在大括号里加这一行：

"shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"

注意：如果你原来文件里还有其他配置，不要删掉，只加这一行即可。

这个配置主要是告诉 Pi 主程序 使用哪个 Bash。

---

3. 把 Git Bash 加到 Windows PATH

有些插件会直接调用：

bash

它不一定读取 Pi 的 shellPath 配置，所以还需要把 Git Bash 加到系统 PATH。

在 PowerShell 里执行：

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Program Files\Git\bin",
  "User"
)

---

4. 重启 PowerShell

执行完上面的命令后，要关闭 PowerShell，再重新打开。

然后验证：

where.exe bash

如果输出：

C:\Program Files\Git\bin\bash.exe

说明修复成功。

---

5. 再运行 Pi

pi

---

总结

最稳的配置是两个都做：

settings.json 配置 shellPath
+
Windows PATH 加入 C:\Program Files\Git\bin

前者给 Pi 主程序用，后者给插件或子进程直接调用 bash 用。

---

飞书里怎么用

发送给机器人的常用命令：

---

Pi 里怎么管理

---

DSH 里怎么管理

在 DSH 的 web 输入框或终端里输入（依赖宿主 DSH 的命令能力；宿主未提供时会静默跳过，不影响桥接本身）：

与 Pi 的区别：DSH 不提供 /feishu start | stop | restart——桥接随 dsh 自动启停，setup / reset 之后把插件重启 dsh，新配置即可生效。

注意（DSH 平台限制）：命令结果以可折叠的命令节点显示在对话流里，但空白的全新会话不渲染命令记录——如果敲了命令没看到任何反应，先在该会话里发一条普通消息，再执行命令即可。setup 不受影响（问答与二维码在终端）。

---

配置

配置默认保存在：

~/.pi/agent/feishu/config.json

也可以通过环境变量配置：

config.json 字段

除了上面的环境变量，也可以在 config.json 里设置（优先级：环境变量 > config.json > 默认值）：

注意：长时间任务（例如跑测试、构建、批量处理）默认不会再被报为“任务失败”——到达 promptNotifySec 后只会在飞书里提示“任务仍在处理中”，回复卡片保持“回复中”，完成后正常送达结果。只有显式设置 promptTimeoutSec 后才会硬超时。修改后请执行 /feishu restart 生效。

运行时配置

以下桥接设置可以在与机器人的私聊里用 /config 立即修改，无需重启，并保存到各自平台数据目录下的 runtime-overrides.json（Pi 为 ~/.pi/agent/feishu/，DSH 为 ~/.dsh/feishu/）：

/config
/config groupKeywords 报警,告警
/config groupAlsoOnReply true
/config streamingReply false
/config clear groupKeywords
/config clear all

可热更新的范围仅包括 groupPolicy、groupKeywords、groupAlsoOnReply、ignoreBotMessages、reactEmoji、language 以及流式展示参数；应用凭证、引用消息展开和连接方式不能通过聊天修改。

---

会保存哪些文件

连接锁选址：机器上装有 Pi（存在 ~/.pi/agent 目录）时沿用 ~/.pi/agent/locks.json，保证两边能协商同一个机器人的连接；纯 DSH 环境则使用 ~/.dsh/locks.json。

---

常见说明

• 图片能不能被识别，取决于当前选中的模型是否支持图片输入。
• 图片、文本/代码文件输入是已有能力；interactive 卡片解析和回复消息上下文展开是新版补充的能力。
• 对一条消息或卡片点“回复”后，Pi 会看到原消息内容和你的新问题；这不是把原消息再次发送到群里。
• /feishu reset 只会清掉配置和映射，不会删除会话历史。
• 从 TUI、CLI 或其他渠道创建的任务，不会主动发到飞书。
• /workspace 当前只支持绝对路径，或 ~/ 开头的路径。
• /resume 默认先显示当前项目的最近历史会话，也可以在卡片里切到“全部会话”并翻页浏览。
• 卡片按钮现在优先走 webhook 回包模式；如果你还想临时沿用旧的 WS 更新方式，可以把 FEISHU_CARD_ACTION_MODE 设成 ws。
• 卡片回调默认监听 0.0.0.0:3001/webhook/card（Pi）/ 0.0.0.0:3002/webhook/card（DSH），需要在飞书开发者后台把交互卡片回调地址指到一个外部可访问的 URL。

---

常见问题

为什么机器人没回复？

先看三件事：

• 飞书机器人是否已经创建并配置好
• /feishu start 是否已经运行
• 群聊策略是否要求 @ 机器人

为什么我在群里发了消息，机器人没有理我？

如果你把群聊策略设成了 mention，就需要 @ 机器人后它才会回复。
open模式下：群里和话题里可直接回复，不需要 @，但还需手动在飞书开发者后台开启机器人“获取群组中所有消息”权限才能生效。

还没有实现后台服务开机自启动功能，目前需要电脑开机后手动启动一次 Pi agent 才能正常工作。启动后，Pi agent 无需前台运行，关闭后，仍可以在飞书/Lark 里对话。