DevFlow/docs/02-架构设计/专项设计/飞书直连接入-形态修正与问题记录-2026-10-05.md

飞书直连接入 — 形态修正设计与问题记录(2026-10-05)

产出:AI-Ops(飞书 bot,只做分析/设计/问题记录);实施:devflow agent。 背景:用户 10-05 在飞书群多轮拍板,推翻 df-im-gateway→u-relay 网关链路,定稿「桌面本地 WS 直连飞书开放平台」。

一、形态拍板(用户令,已定稿)

飞书开放平台 ←WS长连接(出站,免公网回调)→ devflow 桌面端(内置飞书渠道) ⇄ ai-chat agent

• 参照形态:u-claw feishu_channel.go(官方 SDK larksuite/oapi-sdk-go/v3 的 larkws.Client 出站长连接 + REST API 回复,单进程闭环零中间件)
• 旧网关链路(飞书→df-im-gateway→u-relay→df-tunnel→桌面端)在单机场景属绕行,推翻;原网关规划设计文档的 §十(云端多人演进预留)保留远期参考
• 代价已确认:「桌面端关机 bot 不活」用户接受(先例:AI-Ops 即本机常驻)

二、实施要点(交 devflow agent)

1. 复用现有资产,勿新建 df- 组件*(用户 10-05 明确):crates/df-im-gateway/src/feishu.rs(350 行,基于 larksuite-oapi-sdk-rs 0.3.12 channel 特性)的长连接内核可提炼,并入哪个现有 crate 由实施时定位(SDK 用法参考:公开 API LarkClient::ws_client(dispatcher) 直建,拿 WsClientControl 句柄做停机/诊断;AI-Ops 侧曾试建 df-feishu crate 已按要求撤销,其间验证过该路线可行:11 单测全过)
2. 消息链路:飞书 Inbound(文本/卡片动作)→ chat_id↔conversation_id 映射 → ai-chat 会话链路(GUI 同源)→ agent → 流式回飞书;先文本回复,卡片流式更新/审批卡放第二批次
3. Settings 契约:app_settings 单键 'feishu-config' = JSON {enabled, app_id, app_secret, whitelist[]}(snake_case,存法对齐 df-knowledge-config)
   • 注:AI-Ops 侧子代理已按此契约实现 Settings 面板于工作区(6 文件:FeishuPanel.vue 新增 + SettingsNav/searchIndex/Settings.vue/zh-en i18n 修改,vue-tsc 通过,未提交)。devflow agent 三选一:采纳 / 推翻重做 / 回退(git checkout 那 6 文件+删 FeishuPanel.vue)
4. 白名单:空=放行所有(与现 df-im-gateway main.rs 行为一致);open_id 按应用隔离,严禁从其他 bot 搬,须本应用实测获取(首启留空 → 用户发一条消息 → 日志取 open_id 回填)
5. 凭证:用户已在飞书开放平台建应用(10-05),经设置页录入;曾现「bot disabled」,接入验收前先在开放平台启用 bot

三、问题记录 ①:ai-chat 交互消息闪现即消(未结,待复现)

现象:用户 10-05 白天报告,ai-chat 对话页面消息闪现一下就消失,自述"又出现了"。

已锁机制:前端乐观气泡被回滚移除(useAiSend.ts:132/190/199 — IPC 失败即移除占位气泡)。实锤:10-05 00:12 换装重启后 ai_messages 零写入(Roaming/top.1216.devflow/devflow.db),白天发的消息后端一个没接住,闪现=回滚删除。

时间线:10-05 00:03-00:12 凌晨会话(agent 自主)按攒批纪律以工作区状态 bun tauri build 打 NSIS 包,DevFlowRedeploy 计划任务强杀换装;00:35 攒批分组提交(8e1e56b 等);运行中二进制=LOCALAPPDATA/devflow/devflow.exe(00:11 产,48MB)。

候选根因(按嫌疑序,未定):

1. 换装后 agent 后端没接活,发消息 IPC 失败(spawn 前)——零写入吻合
2. "无活跃对话"回滚路径(useAiSend.ts:190)——重启后活跃会话指针丢失
3. 会话级:仅大会议(seq 4989 级)复现 → 嫌疑落"上下文管理信息组织"批次改动

已排除:provider 配置完好(ai_providers 5 行);9-28 走查#5 队列误清已由 c10f0e4 修复(本次是同症状另一条路径);工作区现有改动与本问题无关(df-im-gateway/df-mcp/df-nodes/df-storage 等,系 devflow agent 在途工作)。

下一步(需现场):用户在 ai-chat 再发一条消息,同时记录三点:闪掉的是 user 气泡还是 assistant 占位;有无错误提示一闪而过;全部会话闪还是个别会话。前端 webview console(EBWebView CDP)是备选取证面。

四、问题记录 ②:seq=0 system 消息(次要,顺手修)

ai_messages 中发现 system 消息 seq=0 混于 seq=4951+ 序列(10-05 00:00:50,conv=84cb104c,内容为 assistant 风格"vision 技能已加载…")。seq 分配路径存在未走递增器的旁路,排序场景会被挤到队首。修复时一并核对 system 类消息的 seq 分配。