1. 准备环境（.env 只放路径配置；凭据在启动后于设置页填写）

cp example.env .env # 按需修改 FSCHANNEL_REPO / FSCHANNEL_ENV_FILE

配置

注册行 feishu-bot（来自包内 cordis.patch.yml，作为 bundle 层自动叠加）：

字段	默认	说明
envFile	/.env	路径配置文件（FSCHANNEL_* 键）；不再承担凭据
appId / appSecret	凭据库	入口配置直接覆盖；设置页「连接凭据」保存到 DSH 凭据库
requireMention	true	群聊仅响应 @ 机器人；单成员群（1 用户 + 机器人）免 @
output	stream	stream=流式打字机卡片（失败回退普通消息）；plain=每步一条消息
modelCardTriggers	true	提到模型/effort 时自动弹出按钮卡片
queueAck	true	Agent 忙碌时回复排队位置提示
ackInbound	false	空闲时也回复「收到，处理中…」
reactInbound	true	收到消息时加表情反馈（👍→✅/☹️）
reactReceived / reactDone / reactError	THUMBSUP / DONE / SAD	各阶段表情（飞书标准 emoji_type，可自定义）
holdImages	true	暂存飞书图片，随下一条文字一起识别
holdHint	true	纯图片消息回「已收到 N 张图片…」提示
maxHeldImages	10	每个聊天暂存图片上限
maxHeldImageBytes	10 MiB	单张图片大小上限
holdTtlMs	0	暂存过期时间（毫秒，0=不过期）
imageDir	/.dsh-fschannel-images	暂存目录（须在会话工作区内）
hintUnbound	true	未绑定聊天回复引导提示
hintText	内置	自定义引导文案
bindingsFile	$DSH_HOME/feishu-bindings.json	绑定持久化路径

凭据解析优先级：插件配置 appId/appSecret > 凭据服务（shell 导出的环境变量 > DSH 凭据库 $DSH_HOME/.credentials.yaml > 项目 .env > ~/.dsh/.env）> 插件 envFile。推荐做法：在设置页「飞书机器人 → 连接凭据」填写 appId/appSecret，保存到凭据库（appId 仅显示掩码，secret 永不回显；.env 中不要再放凭据）。

路径配置（放 .env，不入库）：FSCHANNEL_REPO（插件仓库根目录，脚本/重启用）、FSCHANNEL_ENV_FILE（.env 自身路径，默认取工作目录）、FSCHANNEL_BINDINGS_FILE（绑定数据文件，默认 $DSH_HOME/feishu-bindings.json）。cordis.patch.yml 的 envFile 解析顺序：FSCHANNEL_ENV_FILE 环境变量（由 scripts/restart-web.ps1 从 .env 导出）→ /.env。

---

使用方式

绑定一个会话到飞书

1. 在 Web 界面新建会话（或打开已有会话）
2. 点击会话标题旁的「连接飞书」（待绑定状态），或：
   • 设置 → 飞书机器人 标签页：打开「新会话默认连接飞书」→ 之后每个新会话自动待绑定
   • 设置 → 飞书机器人 标签页：「新建会话并连接飞书」一键新建并待绑定
3. 在飞书里私聊机器人 / 群里 @ 机器人发一条消息 → 该聊天即绑定此会话
4. 聊天消息进入会话处理：回复流式呈现，Web 与飞书互通；会话头 chip 显示已连接（点击断开）

设置 → 飞书机器人 标签页的「绑定管理」中可管理：已绑定会话可「断开」；待绑定会话可「取消待绑定」（例如创建后未使用、不再需要的会话）。

飞书侧命令与卡片

输入	效果
「调整模型」「切换模型」「把 effort 调一下」等	弹出按钮卡片（模型 Pro/Flash + effort off/high/max 一键切换）
/model	弹出同一张卡片
/model list	列出模型目录
`/model use
/`	切换模型
/model effort	切换推理等级
/status	会话与机器人状态
/stop	停止当前回合
/help	命令清单

---

附录：飞书机器人申请与配置（参考流程）

以下流程参照飞书自建应用的完整配置路径，含两个已知的坑（个人版建不了应用、未发布就配长连接会报错）。控制台界面可能随版本微调。

步骤 0：确认账号能建自建应用

1. 浏览器打开 https://open.feishu.cn/ ，用你的飞书账号登录
2. 进入「开发者后台」，点「创建企业自建应用」
3. 如果被拦住（提示个人版不支持 / 没有企业）：回到飞书客户端 → 头像 → 设置 →「升级为团队」，免费创建一个只有你自己的团队，然后重来第 1 步

步骤 1：创建应用并拿凭证

1. 创建企业自建应用，名字随便（如 dsh-bot），传个头像
2. 左侧「凭证与基础信息」→ 记下 App ID（cli_ 开头）和 App Secret（Secret 首次不可见，点「重置」或「查看」获取完整值）
3. 保存到设置页：启动 dsh web 后，打开设置 →「飞书机器人」→「连接凭据」，填入 App ID 与 App Secret（保存到 DSH 凭据库，appId 仅显示掩码，secret 永不回显）。

   历史版本曾放在 .env（FEISHU_APP_ID=... / FEISHU_APP_SECRET=...）；v0.1.5.1 起 .env 不再承担凭据，凭据一律走设置页/凭据库。

步骤 2：开通权限

左侧「权限管理」→ 逐个搜索并开通以下 6 个权限：

权限标识	用途
im:message	接收用户发给机器人的单聊消息
im:message:send_as_bot	以应用身份发消息（回复、卡片）
im:message.group_at_msg:readonly	接收群组中 @ 机器人的消息
im:chat	获取群信息（绑定后显示群名）
im:chat.members:bot_access	获取群成员信息（单成员群免 @ 判定、绑定后显示群名）
cardkit:card:write	发送/更新交互卡片（流式卡片、模型设置卡片）

步骤 2.5：限定可用范围（安全边界，必做）

左侧「版本管理与发布」→ 创建版本时的「可用范围」→ 只勾选你自己这一个成员，不要选「全部成员」。这是防止别人拿到你会话控制权的唯一屏障。

步骤 3：开启机器人能力

左侧「应用能力」→ 添加「机器人」能力。没有这一步，私聊发消息不会触发任何事件。

步骤 4：发布应用（必须在配置长连接之前做）

1. 左侧「版本管理与发布」→「创建版本」→ 填写版本号与更新说明 →「申请发布」
2. 因为你是这个团队的管理员，去管理后台自己审批通过

⚠️ 已知的坑：没有已发布版本时，事件订阅页保存长连接配置会报「应用未建立长连接」。先发布，再配长连接。

步骤 5：配置事件订阅（长连接）

左侧「事件与回调」：

1. 「事件配置」→ 订阅方式选「使用长连接接收事件」—— 本插件用长连接，不需要公网回调地址
2. 记下 Encrypt Key 和 Verification Token（长连接方式一般用不到，先记下备用）
3. 「添加事件」→ 勾选 im.message.receive_v1（接收消息）
4. 「回调配置」→ 添加 card.action.trigger（卡片按钮回调，模型设置卡片点击依赖它）
5. 保存

保存长连接配置时若报错，通常是本地桥接还没起来：先把 dsh web 跑起来（本插件随 dsh web 启动长连接），再回来保存。

验证

1. 发布生效后，在飞书里搜索应用名，私聊机器人；或把机器人拉进群（群里 @ 机器人）
2. 给机器人发一条消息：未绑定聊天会回引导提示 → 说明事件订阅与权限已通
3. 回到本插件的流程绑定会话，即可收发消息

常见问题

• 收不到消息：检查权限（步骤 2）是否已随版本发布、事件订阅方式是否选的「长连接」、是否订阅了 im.message.receive_v1。
• 发不出消息：确认已开通 im:message:send_as_bot 且版本已发布。
• 群里不响应：需 @ 机器人（requireMention 默认开启），并开通 im:message.group_at_msg:readonly。
• 卡片不显示 / 点击没反应：确认已开通 cardkit:card:write 并配置了 card.action.trigger 回调。
• 保存长连接配置报「应用未建立长连接」：先完成步骤 4（发布应用），再回来配置。
• 创建应用被拦住：按步骤 0 把个人账号升级为团队。
• 连接失败：核对 App Secret 是否完整复制（避免多余空格/换行）。

步骤 4：发布应用（必须在配置长连接之前做）

1. 左侧「版本管理与发布」→「创建版本」→ 填写版本号与更新说明 →「申请发布」
2. 因为你是这个团队的管理员，去管理后台自己审批通过

⚠️ 已知的坑：没有已发布版本时，事件订阅页保存长连接配置会报「应用未建立长连接」。先发布，再配长连接。

步骤 5：配置事件订阅（长连接）

左侧「事件与回调」：

1. 「事件配置」→ 订阅方式选「使用长连接接收事件」—— 本插件用长连接，不需要公网回调地址
2. 记下 Encrypt Key 和 Verification Token（长连接方式一般用不到，先记下备用）
3. 「添加事件」→ 勾选 im.message.receive_v1（接收消息）
4. 「回调配置」→ 添加 card.action.trigger（卡片按钮回调，模型设置卡片点击依赖它）
5. 保存

保存长连接配置时若报错，通常是本地桥接还没起来：先把 dsh web 跑起来（本插件随 dsh web 启动长连接），再回来保存。