飞书私聊助理 wanjiaju3108/dsh-feishu-assistant

dsh-feishu-assistant

飞书上的 AI 助手：在飞书里私聊机器人，就是跟你指定的那条 DSH 会话对话——助手的回答以卡片回到飞书，Markdown 正常渲染。不需要公网入口。

装

dsh plugin --profile web add dsh-feishu-assistant

装完重启 dsh web。

DSH 版本：当前 0.1.6 需要 DSH 0.1.7-rc.1 及以上。
还在 DSH 0.1.5 上的，装最后一个支持它的版本：

dsh plugin --profile web add dsh-feishu-assistant@0.1.4

装的时候如果收尾报 ERR_PNPM_IGNORED_BUILDS: protobufjs，插件其实没装上。
@larksuiteoapi/node-sdk 的依赖里有 protobufjs，它带 postinstall 脚本，pnpm 默认不跑；dsh 把 pnpm 的非零退出当成整体失败，于是没把插件登记进 profile。先放行再装一次：

~/.dsh/profiles//pnpm-workspace.yaml
allowBuilds:
protobufjs: true

做一个飞书AI助理（从零到能聊天）

第 1 步：飞书开放平台建应用

1. 到飞书开放平台 → 创建企业自建应用；
2. 「凭证与基础信息」里抄下 App ID 和 App Secret；
3. 「添加应用能力」里开启机器人；
4. 「权限管理」里加上四条权限：
- im:message.p2p_msg:readonly —— 接收私聊消息
- im:message:send_as_bot —— 以机器人身份发消息
- cardkit:card:write —— 回答卡片（建卡片实体、整块更新组件正文）。不加也能跑，只是回答退回"每段一张普通卡片"
- contact:contact:readonly —— 读通讯录，用来在审批卡片上把请求人显示成姓名。不加也能跑，卡片上会退回显示 open_id
5. 用上一条权限的话，还要把请求人放进应用的通讯录权限范围（开发配置 → 权限管理 → 数据权限）：contact/v3/users 只返回权限范围内的用户，范围外的照样取不到名字，接口会报 41050 no user authority
6. 「事件与回调」里把订阅方式设为长连接，然后添加：
- 事件 im.message.receive_v1（收到消息）
- 回调 card.action.trigger（审批卡片的按钮点击）
7. 「版本管理与发布」里创建版本并申请发布 —— 企业自建应用要管理员通过后才对用户生效。

第 2 步：DSH 里装上并配好

打开 设置 → 「飞书AI助理」，四项：

| 项 | 填什么 | 存哪 |
| App ID / App Secret | 第 1 步抄下来的 | $DSH_HOME/.credentials.yaml |
| 目标会话 | 见下面「选一条会话」 | $DSH_HOME/settings.yaml |
| 人设文件 | 上传一份本地 md/txt；不上传就等于这个模式没开 | $DSH_HOME/settings.yaml |
| 管理员 | 不手填，用配对码绑 | $DSH_HOME/settings.yaml |

凭据写入后不再回显；被环境变量或 .env 遮蔽时，页面上显示为只读。

必须把 DSH 权限设成「完全权限」：

飞书来的消息是无人值守执行的——你在手机上，应答不了 DSH 的权限审批。而 DSH 的审批是 fail-close 的：没有应答方就直接拒绝。权限不放开的后果是，飞书发来的请求一碰到写文件、跑命令就失败，而你在手机上只看到一句报错，不知道为什么。

两处都要设，缺一处都不行：

| 哪里 | 设成什么 | 管什么 |
| 设置 → 通用 → 权限 | 完全权限 | 以后新建会话的默认档位 |
| 在会话里打 /permission | 完全权限 | 当前这条会话的档位 |

顺序有讲究：先改通用设置、再建目标会话，新会话就直接是完全权限；要是会话已经建好了，改默认值不会回头生效，得进去用 /permission 补一次。

附带后果：开了完全权限，等于机器人能在这台机器上做任何事。所以「管理员」那一项别漏——它决定谁能跟机器人说话。

选一条会话：

1. 在 Web UI 里新建一条会话；
2. 随便发一句话让它落盘 —— 有日志的会话才会出现在「目标会话」下拉里；
3. 到 设置 → 「飞书AI助理」→「目标会话」，选中它。

建议专开一条会话给飞书用，别跟自己写代码的会话共用：飞书来的消息会进同一条会话历史。

绑管理员：点「生成配对码」，把 8 位口令私聊发给机器人，发送者即被设为管理员。口令 8 位、10 分钟有效、用一次即废。

第 3 步：验证

在飞书里私聊机器人发一句话。管理员的消息直接进队列；回答以卡片回。设置页「状态」区能看到长连接、目标会话、人设三块的状态。

人设文件

「飞书AI助理模式」这个能力跟插件一起装，但人设内容不由插件提供：上传一份本地 md/txt 就行。

- 上传后内容是插件自己配置里的一份副本（$DSH_HOME/settings.yaml 的 feishu-assistant.persona），插件不会动你的原文件
- 上限 64 KB；空文件或超限，设置页直接拒绝
- 内容为空时飞书消息不处理（管理员收到一句指路，其他人静默丢弃，审批卡片也不发）
- 内容会盖掉该会话原本的个人设定
- 上传后不用重启、也不用新建会话：下一条飞书消息就是新人设
- 代价：上传之后再改原文件，插件不会跟过来，要重新上传一次

写什么随意。典型内容是助手的身份、语气，以及"正文直接用 Markdown"这类格式约定。

行为

飞书私聊文本 ├─ 配对码 → 把发送者设为管理员，回执 ├─ 人设内容为空 → 管理员收到指路；其他人静默丢弃 ├─ 管理员 → 直接进请求队列 └─ 其他人 → 发审批卡片给管理员；同意后进请求队列，拒绝则回执（待审批最多 20 条、30 分钟过期，作废时回消息告知）

- 请求队列串行：先进先出，前一条整轮 turn/end 结束才注入下一条
- 重复投递只答一次：飞书长连接是“至少一次”投递，断线重连可能把同一条消息再送一遍；按 message_id 去重（lru-cache，记最近 200 条），重投只记一条日志
- 注入前等目标会话空下来：目标会话是共享的，DSH 界面里那一轮可能正在跑。飞书这条会先挂在队列里，等会话真空下来（当前轮跑完、没有排队输入，靠 agent.whenIdle()）再注入——这样它就是下一轮，“这一轮跑完了”的判定必然落在自己身上，不会和界面里的轮次交错。等待期间请求人已经在卡片上看到「正在处理」
- 回写粒度是 step：插件只消费已提交的 assistant/message，所以每产出一条就更新一次那张卡片（上面那条）；退回普通卡片时才是每段发一条、超过 3000 字按换行分片。DSH 另有 token 级的 agent/assistant-stream（网页界面用它逐字渲染），插件没有接
- 回答走一张卡片，整块替换：文本消息不渲染 Markdown，所以回答用卡片回；而且一条回答只用一张卡——先发一张写着「正在处理」的卡，之后每段把 markdown 组件整块换掉（cardkit.cardElement.update），客户端立刻显示。不用卡片流式接口：那是给逐字生成准备的，客户端会按打字机慢慢打，一段几百字要打好几秒，收尾还会把没打完的一次性刷出来（“打几个字突然整段蹦出”）。正文超过卡片上限（30 KB）会自动翻页再接一张卡
- 卡片开不出来就退回普通卡片：没 cardkit:card:write 权限或接口失败时，退回“每段一张普通卡片”的老行为；卡片中途失败会把没上屏的内容补发成普通消息，不丢内容
- 回写重试：单条失败重试 3 次（500ms / 1000ms 退避）
- 直发有回执：管理员私聊发来的请求先回一句「正在处理」再跑，长回答期间不会让你以为它死了（审批通过的请求人由审批流程回同一句）
- 没产出会说明：这一轮结束时一个字都没产出（例如跑到一半出错）就回一条失败文案，不再静默；管理员还会看到具体失败原因
- 不是飞书发起的轮次也推给你：目标会话是共享的——你可能在 DSH 界面上继续问同一件事。插件按「这一轮里有没有自己注入的那条消息」认领轮次：不是它发起的，就把回答以卡片主动私聊推给管理员，而不是静默丢掉（也没有可回复的飞书消息，所以用主动私聊）
- 会话主动打开：启动、换目标会话、收到消息时都会 sessionController.resolveAgent() 把会话拉起来
- 会话失效有反馈：目标会话打不开（例如被删掉）时，设置页「状态」区会出现红色的「会话错误」并写明原因；同一条失败还会主动私聊告知管理员一次，恢复后再坏会重新告知。确认打不开之后的后续消息不再白开一张卡片（直接回一句报错）；请求照常入队，会话恢复后照常处理——那一轮回答先以普通卡片回来，下一轮恢复成回答卡片
- 人设有状态：设置页「状态」区显示「飞书AI助理模式 已导入 （N / 65536 字节）」，没上传则显示未启用
- 助手反问会提示：助手调用提问工具（ask_user_question）时会往飞书回一条提示——那个问题只在 DSH 界面上等人回答，飞书看不到也答不了；提示里会建议用人设禁止它提问、改用回答正文
- 审批人校验：卡片回调校验点击人的 open_id / user_id / union_id，非管理员点不了

配置项

设置页改的都会即时生效（applies: 'live'），不需要重启。

补丁层也可以给初始值：

- id: feishu-assistant
name: dsh-feishu-assistant
config:
sessionId: ''
managerId: ''
persona: ''

怎么验证

npm test # 等价于 node test/all.mjs

六个用例、79 条断言，全部用假飞书 SDK 跑真实的 apply()（不打真接口、不需要凭据）：

| 用例 | 覆盖 |
| outbound-check | 出站返回值语义：卡片成功 / 被拒退回文本 / 没有收件人不发 |
| answer-card-check | 回答卡片：整块替换、翻页、失败补发、收尾不多调接口 |
| plugin-routing-check | 轮次归属：飞书请求回原消息、外部轮次走私聊、反问提示 |
| idle-hold-check | 注入前等会话空闲：忙时不注入、被插队继续等、前提被破坏时告警 |
| broken-session-check | 会话打不开：第一次闪一下、之后不再白开卡片、修好后恢复 |
| inbound-dedupe-check | 重复投递只答一次 |

测试放在 test/，不随 npm 包发布（package.json 的 files 只有 lib 和 cordis.patch.yml）。

已知边界

- 只处理私聊文本消息：群聊、图片、文件、富文本、语音一律忽略
- 目标会话必须能被本进程 resume；被另一个进程占着时会失败（DSH 会话是单进程独占的）
- 待审批缓存是内存态，DSH 重启即丢
- 回答卡片用的是卡片 JSON 2.0，要求飞书客户端 7.20 及以上：低于 7.20 时卡片正文会显示成“升级提示”占位图
- 目标会话忙着（界面里那一轮正在跑）时，飞书请求要等它跑完才开始；等待时间等于那一轮的时长。等待期间请求人的卡片显示「正在处理」
- 回答卡片是普通卡片（非流式），没有「生成中」状态，生成期间也能转发
- 每段正文是整块替换、不是逐字流式：答案会在每个 step 结束时成段出现（这是有意的，见上）
- 没有发送者限流；没有 / 命令

依赖的 DSH 服务

agents、settings、credentials、webServer 列在 inject 里，缺一个插件就不会加载。
四个都是官方包（@deepseek-ai/dsh-agent / dsh-settings / dsh-credentials / dsh-host-webserver）。前三个随 dsh-base 走，任何 profile 都有；webServer 只有 dsh-web-app 提供，所以：

这个插件只能在 web profile 里用。 装进 acp、headless、sdk 之类的 profile 时，因为 webServer 不存在，插件会静默不加载——不报错，就是没反应。安装时 --profile web 不要省。

更新日志

见 CHANGELOG.md。