# 飞书直连接入 — 形态修正设计与问题记录(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 分配。