dsh-feishu-channel

把飞书变成 DSH 的遥控器 —— 双向对话、流式富卡片、一键审批、扫码即用。

Feishu/Lark IM channel for DeepSeek Harness：在飞书聊天里直接驱动你的 DSH agent——每个私聊、群聊或话题都有自己的 agent，回复以流式富卡片回到飞书，工具权限问题变成按钮决策。

English — Turn Feishu/Lark into a remote control for DeepSeek Harness: every chat (direct / group / topic) drives its own DSH agent, replies stream back as rich cards with live progress, tool approvals become one-tap buttons, images pass through whenever the bound model supports vision, and every turn reports its token cost with DeepSeek peak/off-peak pricing. Install in one command — see 快速开始.

为什么用它

快速开始

环境要求：DeepSeek Harness 的 dsh web（本插件在 0.1.2-alpha.2 主线上开发并实测，依赖宿主 agents / settings / commands / sessionController 等核心服务，标准 dsh web 组合自带）；Node ^22.19.0 || >=24。

① 安装（三选一，装进你的 web profile；命令即转发 pnpm，在 ~/.dsh/profiles/web 内执行）：

# 已发布版本（需要对应 tag 已推送到 GitHub）
dsh plugin --profile web add github:whoisjiahao/dsh-feishu-channel#v0.9.0

# 或：从 GitHub Releases 下载 tgz 后本地安装（无需网络解析 git 引用）
dsh plugin --profile web add ~/Downloads/dsh-feishu-channel-0.9.0.tgz

# 或：开发模式——链接本仓库，pnpm build 后热重载即可见
dsh plugin --profile web add file:/绝对路径/dsh-feishu-channel

安装排障（pnpm 门禁都是幂等占位行，改完重跑即安全）：

• ERR_PNPM_IGNORED_BUILDS（protobufjs）：依赖链 feishu-channel → @larksuite/channel → protobufjs（Lark 协议层），插件侧移不掉。pnpm 会在 profile 的 pnpm-workspace.yaml 写入 protobufjs: null 占位行，把 null 改为 true 重跑即可；其 postinstall 只做本地版本提示，放行风险可控。
• ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED（git 安装）：0.9.0 起不再发生——插件已把 prepare 改为 prepublishOnly（lib/ 随 git 提交，git 安装无需构建）。仅安装 ≤0.8.0 旧版会遇到，解法同上（占位行改 true）或改用 tgz 安装。
• 新版依赖刚发布被拒（minimumReleaseAge 门禁）：pnpm 可能拒绝解析刚发布的 @deepseek-ai/* 版本。等几天后重跑，或在 profile 的 pnpm-workspace.yaml 加 minimumReleaseAgeExclude 条目。

② 重启 dsh web，启动日志出现二维码：

feishu-channel: 请用飞书扫码创建应用…

③ 扫码：用飞书 App 扫描二维码，确认创建应用——凭据自动保存，下次启动直连，无需再扫。

④ 开聊：在飞书里给机器人发第一条消息（群聊记得 @ 它）。

已有企业应用凭据？直接写在 profile 的 cordis.patch.yml：

- insert:
    - id: feishu-channel
      name: dsh-feishu-channel
      config:
        appId: cli_xxx
        appSecret: xxx

或用环境变量管理凭据：运行 node scripts/register-lark-app.mjs 走官方扫码注册，把产出的 FEISHU_APP_ID / FEISHU_APP_SECRET 填入 patch 的 appId: !!js process.env.FEISHU_APP_ID（!!js，不是 !js）。

🤖 你是 AI agent？跳到 Agent 安装指引——每步带命令与完成标志，可直接执行。

Agent 安装指引（机器可执行）

目标读者：AI agent 与自动化脚本。按序执行，每步给出完成标志；任一步失败即停，不要自行变通。以下 $PROFILE 默认 web。

步骤 0 · 前置检查

node -v   # 必须满足 ^22.19.0 || >=24.0.0
test -f ~/.dsh/profiles/$PROFILE/package.json && echo profile-ok

步骤 1 · 安装包体（二选一）

# A. 本地 tgz（从 Releases 资产下载，或仓库内 pnpm pack 产出；不触发任何构建门禁）
dsh plugin --profile $PROFILE add /绝对路径/dsh-feishu-channel-0.9.0.tgz
# B. 发布版（要求 GitHub 存在 v0.9.0 tag；未发布则用 A）
dsh plugin --profile $PROFILE add github:whoisjiahao/dsh-feishu-channel#v0.9.0

完成标志：~/.dsh/profiles/$PROFILE/package.json 的 dependencies 出现 "dsh-feishu-channel"。

步骤 2 · 装配确认（三处，缺一不可）

1. package.json → dsh.profile.bundles 数组包含 "dsh-feishu-channel"（没有就手动加一行）；
2. 凭据二选一：~/.dsh/settings.yaml 的 feishu-channel: 段（appId/appSecret），或 profile cordis.patch.yml 的 insert 行（模板见上文快速开始）；两者都缺 → 首次启动进入扫码流程，也算合法路径；
3. node -e "console.log(require('$HOME/.dsh/profiles/$PROFILE/node_modules/dsh-feishu-channel/package.json').version)" 输出预期版本。

步骤 3 · 重启并验证

重启 dsh web 后，日志必须出现授权声明行：

feishu-channel: direct messages: anyone the app is visible to (narrow with senderAllowlist); groups: ...

冒烟测试：在飞书向机器人发送任意消息 → 收到流式卡片（加载 → 完成/失败三态之一）即成功。

回滚

dsh plugin --profile $PROFILE remove dsh-feishu-channel
# 并从 package.json 的 dsh.profile.bundles 数组移除 "dsh-feishu-channel"，然后重启。

界面预览

以下均为真实飞书客户端截图，敏感路径已遮盖。

回复卡片

结论优先呈现，支持表格、编号列表与默认收起的分析过程。

命令执行

同一张卡片从处理中原地更新为完成态，并保留清晰、可核对的执行时间线。

执行中	已完成

命令控制

命令中心与会话设置均使用原生交互控件，无需记忆参数或离开聊天窗口。

命令中心	模型设置

常用配置

命令

直接发送裸命令会打开交互卡：有固定选项的命令显示下拉框，需要参数的命令显示输入框，无参数动作显示确认按钮。显式参数仍可直接执行，例如 /feedback 卡片体验很好。

其余 /xxx 来自当前 DSH 的宿主命令运行时，并按宿主描述自动进入同一套交互流程。/permission 的选项直接读取当前会话投影；切换到 danger-full-access 前必须再次确认。

安全

本插件让飞书消息驱动一个有文件读写和 shell 权限的 agent——它就是你的遥控器。默认拒绝一切收窄之外的流量：

• 生产部署务必设置 senderAllowlist / groupAllowlist / approvers，把遥控器交给该交的人
• 审批卡片展示工具名、将执行的命令与模型说明；所有动态文本先限长，命令和说明中的 token / secret / password / api-key 等先自动脱敏
• 点击必须同时匹配动作、原卡片、所在聊天、当前会话与允许的操作人；旧命令卡自动失效，同名 callId 在不同会话之间不会串用参数
• 拒绝入站保持静默：不向未授权者暴露边界事实
• 卸载即净：transport 断开、自有 agent 全部 dispose、挂起审批全部结算为 cancelled
• ask_user_question / exit_plan_mode 默认禁用：它们把提问弹到 ctx.userQuestions 的唯一注册方（通常是 dsh web 图形界面），飞书用户看不到也答不了，只会挂起到超时；禁用后模型会直接在聊天里用文字提问、用文字给计划。若你的部署以别处作答，可从 denyTools 移除

开发

pnpm install
pnpm gates        # typecheck + test + build + pack 冒烟 + 版本一致性（发布前必跑）
pnpm build        # tsc + tsdown，lib/ 提交进 git

组件组合测试将完整插件经 apply 挂到可控 transport 与 host 测试替身（tests/harness.ts），覆盖入站会话阶梯、授权拒绝、命令卡片、审批卡片全生命周期、富卡片渲染与失败重试、图片附加、斜杠面板同步、卸载清理与扫码注册流程。真实飞书客户端验收仍是发布前的独立步骤。

架构与设计决策见 docs/DESIGN.md。

局限

• 配置只在启动时读取一次（patch 层与 settings 层都生效，后者优先），修改需重启
• chat agent 存活到插件卸载，无空闲驱逐
• 停机期间到达的消息不会重放（transport 无游标）
• 图片按当前模型能力决定是否透传，与 dsh web 图形界面同一门禁语义：会话模型声明支持图片输入即透传（无需任何配置）；模型不支持时机器人明确告知"当前模型不支持图片输入"，可 /model 切换视觉模型后重发；模型信息未知时放行、由路由做最终裁决。文件和音频以 SDK 标准化文本透传给模型
• 模型询问类工具（ask_user_question / exit_plan_mode）被禁用而非以卡片作答

License

MIT