飞书机器人桥接 zyfgood/dsh-feishu-bot

@zyfgood/dsh-feishu-bot

npm 包名：@zyfgood/dsh-feishu-bot（配置里插件行的 name: 也必须写这个名字）。
仓库目录名 / 历史文档里的 dsh-feishu-bot 指同一个插件。

DeepSeek Harness（DSH）插件：绑定飞书（Feishu / Lark）机器人并互动。

- 绑定：配置飞书自建应用的 appId / appSecret，通过官方 SDK @larksuiteoapi/node-sdk 的 WebSocket 长连接接入（无需公网回调地址），SDK 内置自动重连。
- 互动（入站）：用户给机器人发消息 → 机器人自动回复，三种模式：
- echo：回显原文（快速验证绑定是否打通）；
- llm：调用 DSH 的 ctx.llm 服务直接生成回复（自包含，带每会话短期记忆）；
- agent：把消息转交给 DSH agent 处理——指定 agentId 复用该会话，或自动为每个飞书会话创建一个专属 agent（标准模式 preset、持续复用上下文、具备全部 DSH 工具），agent 输出流式实时转发到飞书。
- 任务执行中提问：agent 正在跑任务时发消息，会用 steer 在下一个节点插入你的问题，agent 先回应（流式实时到达）再继续任务。
- 互动（出站）：注册 9 个模型可调用的 feishu_ 工具，让 DSH agent 主动与飞书互动（发消息、回复消息、发交互卡片、确认问答、查会话、查消息、查连接状态、推送目标群）。
- 确认问答：agent 调用 ask_user_question / feishu_ask_choice 需要你拍板时，问题以带按钮的交互卡片发到飞书（点按钮 / 回编号 / 回选项文字均可），回答后卡片定格为结果视图，agent 继续流式输出。
- 策略：群聊 @机器人 才回复、私聊开关、会话白名单、@所有人 响应开关，均由 SDK 的入站策略管道执行。

English Summary

@zyfgood/dsh-feishu-bot 把 Feishu / Lark 机器人接入 DeepSeek Harness（DSH）。在手机上用飞书就能和你的 DSH agent 对话——无需公网回调地址（官方 WebSocket 长连接，自动重连）。

功能

- 入站（用户 → agent）：三种回复模式——echo（验证绑定）、 llm（直接由模型回复，带每会话短期记忆）、agent（把消息交给 DSH agent；自动为每个会话创建专属会话，使用标准 preset 和完整 DSH 工具，回复流式实时 推送到飞书）。
- 任务执行中提问：任务进行中发的消息会在下一个步骤边界通过 steer 注入——agent 先回答（流式），再继续任务。
- 会话命令：/new（全新上下文，回复会预览下一个会话的 model/effort/permission/preset/workspace）、/model（查看或切换本会话的模型——/model list 会给每个模型编号，之后用 /model <n> 切换，和 /attach <n> 一样；对运行中的会话从下一步生效，按会话持久化）、/thinking（查看或切换本会话的推理强度——/thinking list 会给模型支持的档位编号， /thinking <level|n> 切换，/thinking reset 跟随默认值；从下一步生效，按会话持久化）、/sessions（列出会话）、/attach（接管已有的 GUI 会话——两边共享上下文）、/detach。
- 出站（agent → 飞书）：9 个模型可调用的工具（feishu_send_message、feishu_send_card、feishu_ask_choice、 feishu_reply_message、feishu_list_chats、feishu_get_messages、 feishu_get_chat_info、feishu_connection_status、feishu_push）。
- 交互式确认：agent 需要你拍板时（ask_user_question / feishu_ask_choice），会往会话发一张按钮卡片——点按钮，或回复选项编号/文字。回答之后（或卡片在超时后定格为结果视图，智能体的后续输出会流式写入一张新的打字机卡片。
- 策略：群聊仅在 @ 时回复、私聊开关、会话白名单、响应 @所有人 开关——全部走 SDK 入站策略管线。
- 配置：appId/appSecret 通过 env:VAR 传入（绝不使用明文），domain 取 feishu/lark，dmMode 取 open/allowlist/pair/disabled，群白名单、requireMention、智能体预设与工作区、命令开关。

安装

Git channel (repo root is the plugin)
dsh plugin --profile web add "github:zyfgood/dsh-feishu-bot#main&path:/"
npm channel (published package)
dsh plugin --profile web add @zyfgood/dsh-feishu-bot

然后创建自建飞书应用（开放平台步骤见下方中文章节：开启机器人能力、im:message 权限、订阅 im.message.receive_v1、长连接模式、发布版本），再重启 dsh web。日志出现 feishu: 长连接已就绪（机器人：<bot name>） 即表示绑定成功。

License: MIT.

目录

- 快速开始
- 一、飞书开放平台：创建并配置机器人
- 二、安装插件并加载
- 三、配置项
- 四、互动方式
- 五、常见问题

快速开始

1. 按第一节在飞书开放平台创建自建应用并发布版本；
2. 把插件装入 profile 并配置（见第二节，示例见 cordis.patch.example.yml）；
3. 重启 dsh web。

日志出现 feishu: 长连接已就绪（机器人：<你的机器人名>） 即绑定成功；在飞书里给机器人发消息即可指挥 agent 工作（群聊需 @机器人，私聊直接发），让 DSH agent 调用 feishu_connection_status 可随时查看连接状态。

飞书开放平台侧有一个关键开关：事件与回调 → 订阅方式 = 「使用长连接接收事件/回调」（长连接模式无需配置请求地址）。若当前是回调 URL 模式，请切换为长连接，否则消息事件不会推过来。

一、飞书开放平台：创建并配置机器人

以下步骤在 飞书开放平台（国际版 Lark）开发者后台完成，全程无需服务器公网地址。

1. 创建企业自建应用 「开发者后台」→「创建企业自建应用」，填写名称等信息。
2. 获取凭证 「凭证与基础信息」→ 复制 App ID（cli_xxx）与 App Secret。
3. 开启机器人能力 「添加应用能力」→ 勾选 机器人。
4. 添加权限（「权限管理」→ 开通以下权限，保存后需发布版本生效）：
| 权限 | 用途 |
| im:message:send_as_bot | 以机器人身份发送/回复消息 |
| im:message（含 p2p_msg / group_msg / group_at_msg 子权限） | 接收用户消息事件 |
| im:chat:readonly（可选） | 查询会话详情/列表 |
5. 订阅事件（「事件与回调」→「事件配置」→「添加事件」）：添加 接收消息 im.message.receive_v1。
使用长连接时不需要配置回调请求地址（Request URL 留空即可），事件会通过 WebSocket 长连接直接推给插件。
6. 发布版本（「版本管理与发布」→ 创建版本 → 申请发布/审核通过）。
自建应用只有发布后才能被用户搜到并使用。

二、安装插件并加载

插件以 Cordis 插件形式加载，通过 profile 的 cordis.patch.yml 插入配置行。

从 Git 仓库安装（推荐，一条命令安装并挂载）

安装前设置密钥环境变量（也可装后再设，重启前配置好即可）
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx

dsh plugin --profile web add "github:zyfgood/dsh-feishu-bot#main&path:/"
或 npm 渠道（npm 上已发布）：
dsh plugin --profile web add @zyfgood/dsh-feishu-bot

包内自带 cordis.patch.yml（dsh.bundle.patch），CLI 安装时自动挂载，无需手工编辑配置文件；默认 llm 模式，改 agent 模式等见「三、配置项」，在 profile 自己的 cordis.patch.yml 里按 id: feishu-bot 覆盖即可。
装完重启 dsh web 生效；下方是手工安装方式（适用于任何托管位置）。

DeepSeek Harness Desktop 用户：把上面的 --profile web 换成 --profile desktop 即可（桌面版的配置档名为 desktop），例如
dsh plugin --profile desktop add @zyfgood/dsh-feishu-bot。

2.1 把插件放进配置档目录并安装依赖

DSH 的配置档位于 Harness 家目录（$DSH_HOME，默认 ~/.dsh）下的 profiles/<name>/。
以 web 配置档为例：

方式 A —— 从 npm 安装（推荐，无需克隆仓库）

cd ~/.dsh/profiles/web
npm install @zyfgood/dsh-feishu-bot # 或 pnpm add @zyfgood/dsh-feishu-bot

npm 包里已包含编译好的 lib/（无需 npm run build）、cordis.patch.yml
（dsh.bundle.patch）与 cordis.patch.example.yml；运行期依赖 @larksuiteoapi/node-sdk 会随包自动安装，@deepseek-ai/ 由 DSH 运行时提供（在 package.json 里声明为 peerDependencies）。

方式 B —— 从本地目录 / Git 仓库安装

1) 把本插件目录复制到 profile 目录（或放到任意位置后用 file: 引用）
cp -r /path/to/dsh-feishu-bot ~/.dsh/profiles/web/dsh-feishu-bot

2) 在 profile 的 package.json 中声明依赖并安装
cd ~/.dsh/profiles/web
若 profile 目录还没有 package.json，先创建（或直接执行下面的 pnpm add）
pnpm add ./dsh-feishu-bot

插件运行期还需要能解析 @deepseek-ai/ 与 @larksuiteoapi/node-sdk。
DSH 会通过配置档的 node_modules 与自身安装树自动解析 @deepseek-ai/； @larksuiteoapi/node-sdk 由本插件自带的 dependencies 提供。

2.2 在 cordis.patch.yml 中加载插件

编辑配置档的 cordis.patch.yml（web 配置档为 ~/.dsh/profiles/web/cordis.patch.yml），追加：

- id: feishu-bot
name: '@zyfgood/dsh-feishu-bot'
config:
appId: 'env:FEISHU_APP_ID'
appSecret: 'env:FEISHU_APP_SECRET'
mode: llm
provider: deepseek-official
model: deepseek-v4-flash
requireMention: true
tools: true

把 FEISHU_APP_ID / FEISHU_APP_SECRET 写入启动环境（如 .env、系统环境变量）， 不要在配置里明文写 App Secret（插件支持 env:VAR 形式从环境变量读取）。

2.3 启动并验证

dsh --profile web

- 日志出现 feishu: 长连接已就绪（机器人：xxx） 即绑定成功。
- 在飞书里给机器人发一条私聊消息，echo 模式会回显 收到：...。
- 让 DSH 智能体调用 feishu_connection_status 工具可随时查看连接状态。

三、配置项

| 配置项 | 类型 | 默认 | 说明 |
| appId | string，必填 | — | 飞书自建应用 App ID（cli_xxx），支持 env:VAR |
| appSecret | string，必填 | — | 飞书自建应用 App Secret，支持 env:VAR |
| domain | feishu \| lark | feishu | 开放平台域名（国际版选 lark） |
| loggerLevel | fatal~trace | info | SDK 日志级别 |
| dmMode | open \| allowlist \| pair \| disabled | open | 私聊策略：开放/白名单/仅双向/关闭 |
| dmAllowlist | string[] | [] | allowlist/pair 模式下的用户 open_id 白名单 |
| groupAllowlist | string[] | [] | 群聊 chat_id 白名单（空 = 不限群） |
| requireMention | boolean | true | 群聊中必须 @机器人 才回复 |
| respondToMentionAll | boolean | false | 是否响应 @所有人 |
| mode | echo \| llm \| agent | llm | 入站回复模式 |
| replyFormat | markdown \| text | markdown | 回复排版：markdown 富文本（代码块/表格/列表完整渲染，智能体流式以卡片呈现）或纯文本 |
| systemPrompt | string | 默认提示词 | llm 模式的系统提示词 |
| provider | string | — | 服务商路由（如 deepseek-official）。llm 模式直接使用；agent 模式自动创建会话时优先使用 |
| model | string | — | 模型 id（如 deepseek-v4-flash）。llm 模式直接使用；agent 模式自动创建会话时优先使用 |
| reasoningEffort | string | — | 默认思考模式档位（v0.9.0，adapter 声明的 reasoning effort id，如 off/low/high/max，DeepSeek 官方默认 high）。llm 模式随请求发送；agent 模式作为新会话默认档位，飞书里可用 /thinking 按会话覆盖。不配置时跟随模型默认档位；模型不支持时 DSH 会拒绝请求（UNSUPPORTED_REASONING_EFFORT），此时请留空 |
| maxHistory | number | 20 | llm 模式每会话保留的对话轮数（0 = 无记忆） |
| agentId | string | — | agent 模式：目标 DSH agent 会话 id（不配置则自动创建） |
| agentPreset | string | 跟随默认 | 自动创建会话使用的 agent preset（如 standard / liangshen）；不配置跟随 GUI 默认预设 |
| workspace | string | process.cwd() | agent 模式自动创建会话时的工作目录 |
| commands | boolean | true | 是否启用飞书会话管理命令（/new /sessions /attach /detach /cancel） |
| resetCommands | string[] | ['/new', '/reset'] | 重置上下文命令列表 |
| attachHistory | number | 5 | /attach 接手后发送最近几条对话历史（0 = 不发） |
| questionTimeoutMs | number | 600000 | 飞书侧确认问题等待回答的超时（ms，默认 10 分钟；超时自动取消该次询问，防止 agent 回合/会话队列被永久挂起） |
| persistSessions | boolean | true | 是否持久化 chat→会话映射：dsh web 重启后自动 resume 原 DSH 会话，延续对话上下文（映射存于 $DSH_HOME/feishu-bot/chat-sessions.json） |
| segmentChars | number | 8000 | 流式/卡片内容分段阈值（字符，1000~30000）：agent 输出（含大文件内容）超过该长度自动分多张卡片（多条消息）发送，按代码围栏/标题切，代码块不切断。原生打字机卡片固定以 min(segmentChars, 8000) 封顶（飞书卡片 JSON 30KB 硬限制，CJK 8000 字符 ≈ 24KB），超出部分切旧链路分段续传；CJK 内容建议 ≤ 8000，否则单卡可能触及 30KB 上限自动降级为纯文本 |
| eagerPlaceholder | boolean | true | 回合开始立即上屏「占位打字机卡片」（v0.6.7）：模型闷头执行工具、尚未产出首批文本时，用户先看到占位卡（带打字光标），首批文本到达后无缝续写同一张卡。解决「工具执行期完全静默、被误认为没有流式回复」的观感问题；关闭后回到旧行为（首批文本到达才创建卡片） |
| streamPlaceholder | string | 收到，正在处理… | 占位卡片文案（配合 eagerPlaceholder） |
| tools | boolean | true | 是否注册 feishu_ 模型工具 |
| pushChatId | string | — | 飞书目标群 chat_id（oc_ 开头）；配置后启用 feishu_push 工具（任务结果/定时推送直达该群） |

3.1 新会话的模型、思考模式与权限如何确定（agent 模式）

/new 后下一条消息自动新建会话时，模型按以下顺序解析（resolveAgentModel）：

1. /model 命令设置的覆盖（本飞书会话维度，存于 $DSH_HOME/feishu-bot/model-overrides.json，重启后仍生效，最高优先级）；
2. 插件配置 provider + model（cordis.patch.yml）；
3. 缺失时回退 GUI 默认模型 ctx.agentDefaultModel（settings.yaml 的 agent-default-model 分节，即 GUI 选择的默认模型，热更新生效）。

思考模式（reasoning effort，v0.9.0）在同一覆盖链上解析，模型档位由 provider adapter 声明（DeepSeek 官方：off/low/high/max，默认 high；部分模型不支持档位）：

1. /thinking 命令设置的覆盖（与 /model 覆盖共用同一条持久化记录，只写 reasoningEffort 字段，最高优先级）；
2. 插件配置 reasoningEffort（模型未走命令覆盖时生效）；
3. 模型回退 GUI 默认模型时，沿用 GUI 默认模型自带的档位；
4. 都没有 → 跟随模型默认档位（不向请求传 effort，由 DSH 物化模型自身的 defaultEffort）。

/model <provider>/<模型id> 切换的是第 1 层覆盖：经 ctx.llm 校验模型可用后写入，对活跃会话从下一个 step 生效（与 GUI 切模型同一机制： installModelSelection 每 step 实时读取，运行中任务当前 step 不受影响），之后新建/恢复的会话也沿用；/model reset 清除覆盖回到第 2/3 层。
/model list 为每个模型标注连续编号并按会话记忆，之后 /model <编号> 即可切换（与 /attach <编号> 同一交互模式，编号以最近一次列表为准）。
/attach 接手或 agentId 配置的 GUI 会话不适用（模型在 GUI 会话内切换）。

/thinking <档位|编号> 同样经 ctx.llm 校验后写入覆盖（档位列表用 /thinking list 查看，带编号与默认/当前标注）；切换同样从下一个 step 生效（effort-only 变化不会插入 model changed 通知）。切模型时的协同：已有档位覆盖而新模型不支持该档位时，/model 会自动清除档位并在回复中提示（避免下一条请求被 UNSUPPORTED_REASONING_EFFORT 拒绝）；新模型支持时档位原样保留。

权限与预设跟随 DSH 全局设置，插件不单独覆盖：权限预设取 ctx.permissionPresets 默认值（settings.yaml permission.defaultPreset，如 danger-full-access = sandbox 全开 + 免审批），agent 预设取 agentPreset 配置或 GUI 默认预设。

/new 的回复（v0.6.9 起）会附上这些参数的预览，无需翻配置即可确认。

四、互动方式

4.1 入站：用户 → 机器人

- llm 模式（默认）：用户发消息 → 插件用 ctx.llm 生成回复并引用回复该消息。每个会话（chat_id）维护短期记忆（maxHistory 轮）。
- agent 模式：把消息作为 user 消息 followup 给 DSH agent 会话，agent 的输出（assistant/chunk）流式实时转发到飞书：首选原生卡片流式（cardkit 打字机效果，只传增量，不再每次刷新把全文重传/重渲染）；卡片流式不可用时自动降级为「先发一条消息，随后持续编辑更新（约 400ms 聚合一次）」的旧链路，最终定型为完整回复。两种用法：
- 自动创建（推荐，不配置 agentId）：每个飞书会话首次消息时自动创建一个专属 DSH agent（标准模式：挂载 agentPreset（默认 standard），与 GUI 新建会话一致；工作目录 = workspace，默认 process.cwd()），后续消息复用同一会话（上下文持续），agent 具备全部 DSH 工具能力，插件卸载时自动销毁；
- 复用指定会话（配置 agentId）：

- id: feishu-bot
name: '@zyfgood/dsh-feishu-bot'
config:
appId: 'env:FEISHU_APP_ID'
appSecret: 'env:FEISHU_APP_SECRET'
mode: agent
agentId: main

其中 agentId 是 ctx.agents 中存在的会话 id（例如 profile 里 agent-spine 配置创建的 main，或 GUI 中当前会话的 id）。
- echo 模式：回显原文，适合先验证绑定是否打通。

4.2 任务执行中提问（agent 模式）

当 agent 正在执行任务（例如 GUI 里跑一个长任务、或上一轮回复还在进行）时，你在飞书发消息：

- 插件改用 agent.steer() 把问题插入下一个 step 边界——agent 会在任务的下一个节点先回应你的问题，再继续任务（不会打断/丢弃任务）；
- 回应同样流式实时转发到飞书，遇到 agent 下一次工具调用即收尾定型；
- 若 agent 直接完成任务而没有再回应，则以 idle 收尾。
- 长任务期间你的消息会先收到「📥 已收到」即时确认，不再石沉大海。

说明：如果 agent 卡在单个长工具调用内（如长时间 bash 命令），问题要等该工具返回后才能被读到——这是单 agent 模型的固有限制。

4.3 交互确认卡片（agent 调用 ask_user_question 时）

agent 在飞书会话里调用 ask_user_question（需要你确认/选择）时，问题不再只出现在 Web 界面：插件会向该飞书会话发送一张带按钮的交互卡片（每个选项一个按钮）+ 编号提示，你可以：

- 点按钮直接选择；
- 或回复编号（如 1、2,3；多选问题用逗号分隔）或回复选项原文；
- 或回复 /cancel 取消该次询问（agent 继续执行、不等待）。

回答/超时/取消后，问题卡片会定格为结果视图（「✅ 已选择：xx」/「⏰ 等待超时」等，v0.8.0），按钮不再出现；回答后的续写会开一张新的打字机卡片继续流式输出——发起问答时当前打字机卡片已被优雅收尾（去光标、定格），等待你选择的那几分钟不再消耗飞书 cardkit 流式卡片约 10 分钟的服务端寿命，彻底消除「选择后原卡冻结、闪现空卡」的断流观感（2026-09-03 修复）。

超时（questionTimeoutMs，默认 10 分钟）未回答会自动取消该次询问，agent 回合必然结束——不会出现「问题只出现在 Web、飞书侧永久挂起、机器人从此不再回复」。（/attach 接手的 GUI 会话不受影响，确认仍走 Web 界面。）

4.4 飞书会话管理命令（agent 模式，commands 默认开启）

在飞书里直接给机器人发命令（群聊需 @机器人），无需改配置、无需重启：

| 命令 | 作用 |
| /new 或 /reset | 开始新会话：完全重置本飞书会话——销毁专属 agent（即便当前正 /attach 接手它）、清除接手绑定与持久映射，下一条消息自动新建（上下文清空）；v0.6.9 起回复附带新会话参数预览（模型及来源、思考模式及来源、权限预设 sandbox/approval、agent 预设、工作目录） |
| /model | 查看/切换本飞书会话的模型（v0.7.0）：/model 看状态（含思考模式行）· /model list 列可用模型（带编号） · /model <编号> 数字切换（参照 /attach，如 /model 3） · /model <provider>/<模型id> 精确切换 · /model <模型id> 唯一匹配（歧义时列候选） · /model reset 恢复默认。切换对活跃会话自下一个 step 生效（运行中任务不撕裂），并持久化跨重启（model-overrides.json）；仅影响本飞书会话 |
| /thinking | 查看/切换本飞书会话的思考模式（v0.9.0）：/thinking 看状态（模型/生效档位/来源） · /thinking list 列当前模型支持的档位（带编号，标注默认/当前） · /thinking <档位> 如 /thinking max 切换 · /thinking <编号> 数字切换 · /thinking reset 恢复默认。切换对活跃会话自下一个 step 生效并持久化；与 /model 切模型自动协同（不支持的档位自动清除并提示） |
| /sessions | 列出当前活跃的 DSH agent 会话（编号 + 标题 + 模型 + 工作目录） |
| /attach <编号或会话id> | 接手 GUI 中某个既有会话：此后该飞书会话直接驱动它（两边共享上下文，GUI 可见） |
| /detach | 解除接手（回复会如实说明下一条消息的去向，优先级与路由一致：配置 agentId → 本会话专属会话（若有）→ 持久映射 → 自动新建，并附 /new 指引） |
| /cancel | 取消当前待确认问题（agent 继续执行） |

示例：想在飞书里继续 GUI 中某个会话 → 先发 /sessions，看到类似：

当前活跃会话（2 个）： 💬 1. 帮我重构登录模块
id=session-gui-777 · deepseek-v4-pro · /workspace/projA
🤖飞书 2. 飞书会话 · DSHProjects
id=feishu-oc_xxx-1234abcd · deepseek-v4-flash · /workspace

用 /attach <编号或会话id> 接手（编号见上），/detach 解除。

再发 /attach 1（按编号）或 /attach session-gui-777（按 id）即可接手；想清空上下文重新开始 → 发 /new。

说明：/new 只销毁插件自动创建的专属会话；/attach 接手的 GUI 会话不会被销毁（用 /detach 解除）。命令可通过 commands: false 关闭，重置命令可通过 resetCommands 自定义（默认 ['/new', '/reset']）。

自动创建的飞书会话会自动归入 workspace 配置的工作区（如 DSHProjects），不会出现在「未分组」里；会话标题由 DSH 的 session-title 服务生成，未生成前显示「飞书会话 · <目录名>」。

重启延续（persistSessions，默认开启）：插件把 chat→会话 映射持久化到 $DSH_HOME/feishu-bot/chat-sessions.json。dsh web 重启/插件重载后，你在飞书发的下一条消息会自动 resume 原 DSH 会话（同一 id、同一上下文），不会再被当成新用户另起炉灶。/new 会清除该映射。

4.5 出站：DSH agent → 飞书（模型工具）

| 工具 | 用途 |
| feishu_send_message | 向会话/用户发送文本或 markdown，可引用某条消息回复 |
| feishu_send_card | 向会话/用户发送任意交互卡片（卡片 JSON 2.0，可带按钮等元素） |
| feishu_ask_choice | 发送带按钮的确认卡片并等待用户点击（或回复编号/选项文字）；超时可配，返回 timeout=true |
| feishu_reply_message | 按 message_id 回复某条消息（无需知道会话 id） |
| feishu_list_chats | 列出机器人可访问的会话 |
| feishu_get_messages | 拉取某会话最近消息（了解上下文） |
| feishu_get_chat_info | 查询会话详情 |
| feishu_connection_status | 查询长连接状态与机器人身份（诊断用） |
| feishu_push | 把结果一键推送到配置的目标群（需 pushChatId；适合任务汇报、定时任务推送） |

feishu_send_message 的 target 支持 chat_id（oc_ 开头）或用户 open_id（ou_ 开头）， SDK 按前缀自动推断接收方类型。按钮卡片（feishu_ask_choice / 确认卡片）需要开放平台已订阅卡片交互回调（长连接模式下在「事件与回调 → 事件订阅」勾选 card.action.trigger），点击事件才会推送到插件。

五、常见问题

- 安装报 ERR_PNPM_IGNORED_BUILDS（protobufjs）：pnpm 10/11 默认拦截依赖构建脚本， @larksuiteoapi/node-sdk 的传递依赖 protobufjs 需要放行。在 profile 的 pnpm-workspace.yaml 加入：

allowBuilds:
protobufjs: true

然后重新执行安装命令即可。
- feishu: 连接长连接失败（code 10003 invalid param）：appId/appSecret 无效，或应用未发布版本。检查凭证与「版本管理与发布」状态。
- 群聊里机器人不回复：确认已开启机器人能力、已订阅 im.message.receive_v1、已发布版本，且群聊中消息是 @机器人 发送的（requireMention: true）。
- 权限错误（permission denied）：在开放平台补充 im:message:send_as_bot / im:message 等权限后需重新发布版本。
- 私聊不可用：dmMode 默认 open；若设为 disabled 则机器人不响应私聊。
- agent 模式无回复：确认 agentId 对应会话在 ctx.agents 中处于活跃状态；若 agent 只调用工具而未输出文本，插件不会发送空消息。
- 对话一轮就断 / 机器人不再回复：旧版本在 agent 调用 ask_user_question（需你确认）时，问题只出现在 Web 界面，飞书侧答不了，agent 回合永久挂起导致该会话队列被堵死。升级到 v0.6.0 后问题会以交互卡片发到飞书（点按钮/回编号//cancel），
- 另有超时兜底；若仍怀疑卡住，可在飞书发 /new 重置会话。
- 重启后飞书对话上下文丢失：v0.6.0 起默认持久化 chat→会话映射并自动恢复；确认 persistSessions 未被关闭、$DSH_HOME/feishu-bot/chat-sessions.json 可写。
- 长文件/长代码不分段：v0.6.1 起默认按 8000 字符（segmentChars 可调）自动分段，按代码围栏/标题切分、代码块不切断，每段一条卡片消息；若觉得粒度不合适，调小（如 4000）或调大（如 12000）后重启生效。
- 流式回复到一定长度就停止：v0.6.2 及更早版本中，原生打字机卡片超过单卡上限后由 SDK 自动切卡，但「全量刷新 + 切卡」组合会在内容含超长单行（超长 URL / minified 代码 / 大段数据）时在 SDK 内部静默失败，回复停在约 8000 字符处不再更新，且无任何报错。v0.6.3 起原生卡片只承载
min(segmentChars, 8000) 的安全头部，超出即钉住当前卡片、尾部自动切
普通卡片链路分段续传（内容完整不丢）；若仍遇到回复中途停止，查看 dsh 日志中 feishu: 与 [stream] 相关告警，或在飞书发 /new 重置会话。
- 卡片按钮点击无响应：开放平台需已订阅卡片交互回调（长连接模式下在「事件与回调 → 事件订阅」勾选 card.action.trigger）并重新发布版本。
- 机器人会话不在工作区列表显示：会话被你在 GUI「归档管理」里归档后，机器人 resume/复用同一会话继续对话时，归档会话在工作区树中被隐藏（只在归档区可见），看起来像「机器人会话不显示」。v0.6.5 起会话被机器人激活（发消息驱动 / /attach 接手 / 长任务中 steer）时自动取消归档，立即恢复在工作区显示；也可在 GUI 归档管理里手动「恢复」。另：/new 在无活跃会话时也会清除持久化映射，确保下一条消息真正新建会话而非 resume 旧上下文。
- 确认问题（选项卡片）不出现、任务停滞：问题卡片曾连踩两个飞书卡片校验——① v0.6.3 及更早显式 update_multi: false 被拒（230099/300302， v0.6.4 已移除）；② 按钮包在 tag: 'action' 容器里，卡片 JSON V2 不再支持（230099/200861「unsupported tag action」，v0.6.6 起改为 button 直接平铺在 body.elements，已实测发送成功）。v0.6.4 起卡片万一发送失败也会必发一条含完整选项清单的文本提示（回复编号/选项文字即可回答），确认流程不会静默停滞；v0.6.6 起按钮卡片可正常渲染，点击经 cardAction 回流。
- 感觉「没有流式回复，最终完成才一次性回复」：先区分两种情况—— ① 流式链路故障（罕见，看 dsh 日志 feishu: / [stream] 告警）；② 模型行为差异：模型拿到任务后先闷头执行工具（可能几分钟完全不输出可见文本），全部文本集中在结尾几秒产出——流式卡在末尾才出现并快速打完，观感上就是「等了很久、最后一次性回复」（2026-09-02 晚实测：工具期 119 秒零文本，文本 9 秒内打完，流式链路本身全程正常）。v0.6.7 起 eagerPlaceholder（默认开）在回合开始就上屏「收到，正在处理…」占位打字机卡，工具执行期不再静默，首批文本到达后无缝续写同一张卡；回合内被 steer 接管或整轮无文本输出时占位卡会以中性提示收尾，不会悬挂打字光标。
- 确认问答点击选项后「断流」（原卡冻结、闪现空卡）：v0.8.0 之前的机制缺陷（2026-09-03 事故：等待 243 秒后点击）——回合开始即开启的原生打字机卡片在等待回答期间持续空转，而飞书 cardkit 流式卡片服务端约 10 分钟自动关闭（200850）、插件 8 分钟钉头上限只在下一批文本到达时才检查；回答后的续写到达时原卡早已被服务端关闭，只能切旧链路：光标消失、原卡定格、闪现一张空卡、续写落到新消息。v0.8.0 起发起问答时即优雅收尾当前打字机卡（去光标定格、等待期不再消耗流式寿命），回答后开新的打字机卡续流，且切链路尾部为空时不再发送空卡；同时问题卡片在回答/超时/取消后定格为结果视图（「✅ 已选择：xx」等，按钮不再出现）。
- 重启 / /detach 后机器人接着旧会话继续，而不是新会话：这是 persistSessions（默认开）的设计行为——chat→会话映射落盘，dsh web 重启、GUI 重开、/attach 再 /detach 都不会清除该映射，下一条消息会自动 resume 映射会话（延续上下文）；另外重启后 GUI 把曾经打开的会话恢复为活跃状态时，插件直接复用该活跃会话（若正是映射目标，效果相同）。要开全新会话请发 /new。v0.6.8 起 /detach、/attach （接手目标与映射不同时）、/sessions（含空列表场景）都会如实说明「下一条消息将恢复哪个会话 / 是否新建」，不再出现「以为 /detach 后是新会话、实际 resume 了旧会话」的误会（2026-09-02 晚实际发生： /attach 1 → /detach → 下一条消息 resume 了白天的会话）。
- /attach 接手本会话自己的专属会话后 /new 不生效：v0.8.3 之前的机制缺陷（2026-09-04 事故：/attach 5 → /new → 下一条消息仍复用旧会话 feishu-\-99cbcf39）——/attach 允许选中列表里任意会话，包括本飞书会话自己的专属会话，此时 state.bound 与 state.auto 指向同一 agent；而 /new 的接手分支只清了 bound 与持久映射，残留的 auto 复用路径让下一条消息继续落入旧会话，回复却承诺「下一条消息将自动创建新会话」。
v0.8.3 起 /new 在任何分支都做完全重置（销毁专属 agent + 清空 stateByChat/chatByAgent/持久映射），承诺永远为真；/detach 的去向说明也补上了「本会话专属会话」这一档（优先级与路由一致）。
- 思考模式切换无效 / 报 UNSUPPORTED_REASONING_EFFORT：思考档位因模型而异（由服务商适配器声明，DeepSeek 官方为 off/low/high/max，部分模型无档位），先 /thinking list 查看当前模型支持的档位再切换；llm 模式没有命令入口，请改插件配置 reasoningEffort；/attach 接手或 agentId 配置的 GUI 会话请在 GUI 会话内切换。切换对活跃会话自下一个 step 生效——运行中的当前 step 仍用旧档位，属预期行为（与 GUI 切换同机制，不打断任务）。

开发与构建

npm install # 安装依赖；@deepseek-ai/* 已钉在 0.2.0-rc.2 作为类型检查用 devDependencies
npm run build # tsc 构建到 lib/
npm test # 冒烟测试（mock 上下文跑通核心链路，无需真实飞书凭证）

运行期的 @deepseek-ai/ 由 DSH 提供（声明为 peerDependencies），devDependencies 里钉的同一批包只用于离线类型检查。

DSH 版本兼容：本包在 DSH 0.2.0-rc.2（DeepSeek Harness Desktop 0.2.0-rc.2）上验证通过，engines.dsh 与 @deepseek-ai/dsh- peer 范围均声明为 =0.2.0-rc.2 <0.3.0-0。DSH 安装期会用它做兼容性预检（不满足直接拒绝安装），换到其它 DSH 版本时请按实际验证结果调整该范围。

仓库中的 lib/ 为已构建产物（开箱即用）；修改 src/ 后运行 npm run build 重新生成。

源码结构：

- src/index.ts — 插件入口（Config 校验、服务注册、生命周期）
- src/service.ts — FeishuService（ctx.feishu：长连接 + 消息 API）
- src/inbound.ts — 入站消息路由（echo / llm / agent）+ 会话管理命令 + 会话恢复
- src/questions.ts — 飞书侧确认问答（交互卡片 + 按钮点击 + 文本回答 + 超时兜底）
- src/persistence.ts — chat→会话映射落盘（重启后 resume 恢复上下文）
- src/tools.ts — 模型可调用的 feishu_* 工具
- tests/smoke.mjs — 冒烟测试（npm test）
- cordis.patch.example.yml — 配置档补丁配置示例

License

MIT