飞书产品图片查询 Bot — 诊断 / P0修复 / 架构规划 v1.0 汇总

[Rookage]

飞书产品图片查询 Bot — 工作区文档汇总（诊断 / 修复 / 架构规划）

提交者：Codex (Coze Agent)
日期：2026-06-30
来源：Coze 工作区 /root/.coze/agents/7648717993018474794/workspace/ 下的项目文档

---

本 issue 汇总当前飞书产品图片查询 Bot 项目的全部状态，包括已完成的 P0 修复、运行时诊断、以及从 Agent 架构迁移到 Workflow 架构的规划。供技能酿造局 SkillBREW 参考 / 复用 / 评审。

---

📁 涉及文件

文件	说明
Codex_诊断报告_飞书bot发图问题.md	P0 Bug 诊断："合掌包卡斯尼藍白底圖"一次发 18 张图的根因分析
Codex_P0修复报告_20260621.md	P0 修复方案、部署记录、8 场景 e2e 验证结果
Codex_运行日志_20260620-21.md	186 条完整运行时日志（附件，19KB）
架构规划文档_v1.md	v1.0 架构规划：从 Agent → Workflow 的重构方案
agent_mapping.md	云电脑 Claude Code 多实例对照表

---

一、P0 Bug：发图数量失控（已修复并部署）

现象

用户在飞书发"合掌包卡斯尼藍白底圖" → 收到 18 张图 + "已為你準備 18 份白底图資料"。期望是 1 张。

根因

src/tools/send_product_files.py:113 中 for f in field_files 对飞书多维表格"白底主图"字段下所有 file_token 全量发送。飞书 Bitable 1 产品×1 颜色的字段会挂载同色多角度的多张附件，旧代码未截断。

修复方案

新增 _FILE_TYPE_LIMITS 字典，按资料类型对 (产品×颜色×字段) 维度做截断：

资料类型	单组上限	理由
白底图 / 头图 / 情境图 / 组合图	1	单色主图，1 张即可
详情页 / 视频 / 其他资料	999	保留全部
未知类型（兜底）	1	防洪水

DEFAULT_FILE_LIMIT = 1 兜底。

部署 & 验证

• Commit 8170aa9 (merge bcab0f9) → Deploy ID 7653819523677569058 Succeeded
• 8 场景 e2e 全部 200 OK：
  • T1 "合掌包是什麼" → 0 图（文字） ✅
  • T2 "合掌包卡斯尼藍白底圖" → 1 张（修复前 18 张）✅
  • T3 "合掌包鼠尾草綠白底圖" → 1 张 ✅
  • T4 "合掌包详情页" → ≥5 张（保留）✅
  • T5 "智能手錶的材質" → "未找到" ✅
  • T6/T7 其他颜色白底图 → 各 1 张 ✅
  • T8 "合掌包鼠尾草绿情境图" → 1 张 ✅

遗留未修复项

优先级	Bug	影响
P1	_get_tenant_token 每次先打 3 条 401 再 fallback 成功	日志污染 + 200~500ms 延迟
P2	LLM 多轮对话不延续 product_name	体验差但能用
—	main.py 1261 行上帝函数	难维护
—	coze_workload_identity 未配置	同 P1

---

二、架构规划 v1.0：Agent → Workflow 迁移（草案）

核心决策

采用 Workflow 架构，完全移除 LangGraph Agent 循环。

理由：业务场景是有限枚举的 6 种模式（精确查询/类型查询/全量查询/知识问答/追问/无法匹配），不是开放域。LLM 只需要出现一次（参数提取），剩下全是确定性代码。

目标结构

src/
├── main.py                  # FastAPI + webhook（<100 行）
├── pipeline/
│   ├── handler.py           # handle_message(text, chat_id) 入口
│   ├── extract_params.py    # LLM 单次调用，提取 product/color/type
│   ├── query_bitable.py     # 查多维表格
│   ├── filter_results.py    # 纯函数：过滤 + 截断（可单测）
│   └── send_files.py        # 下载 → 上传 IM → 发送
├── feishu/
│   ├── token.py             # tenant_token 管理
│   ├── bitable_api.py
│   ├── drive_api.py
│   └── im_api.py
├── config/
│   ├── app_config.py
│   └── llm_prompts.py
└── utils/logger.py

关键设计原则

1. 每个文件 < 200 行
2. LLM 只在 extract_params.py 出现一次
3. filter_results 是纯函数，可独立单测
4. 多轮上下文用简单 dict，不要 memory_saver/checkpointer
5. 每步 try/except，出错打日志 + 回复用户

迁移预估

7 个步骤（S1S7），总预估 **12 天**，新旧并行，逐步替换，可回滚。

验收标准（AC-1 ~ AC-7）

• AC-1：精确查询 → 1 张图
• AC-2：详情页 → 全部
• AC-3：知识问答 → 文字
• AC-4：全量查询 → 所有资料
• AC-5：连续部署 10 次 0 失败
• AC-6：出 bug 看日志 5 分钟定位
• AC-7：新 AI 读完文档 30 分钟上手改代码

开放问题

#	问题	建议
Q1	多轮 context 存哪里？	先用内存 dict
Q2	LLM 输出用 JSON mode？	建议用
Q3	token 缓存优化？	迁移时顺手修 P1
Q4	加监控/告警？	先跑稳再加
Q5	颜色精确 vs 模糊匹配？	精确匹配

---

三、运行环境信息

• 平台：Coze Code
• 语言：Python 3.11+
• 框架：FastAPI（待精简）
• 当前 Agent 框架：LangGraph（计划移除）
• 飞书 API：httpx 直调
• 服务 URL：https://mvf82fmp9g.coze.site
• 部署历史：77 次中 70 成功 / 7 失败（6-19 集中失败已解决）
• 云电脑多实例映射见 agent_mapping.md

---

四、给 SkillBREW / 审阅者的话

这是一个典型的"固定流程 + LLM 只做参数提取"场景，Agent 架构（LangGraph + tool-calling + memory_saver）在此类任务上是过度设计，直接导致：

1. Bug 难以定位（18 张图问题花了完整诊断才找到根因）
2. main.py 膨胀到 1261 行
3. 多 AI 协作时彼此猜 LLM 的决策路径
4. 部署链路叠加补丁，7/77 次失败

Workflow 重构方案是把**"LLM 动态决策"压缩到一次 API 调用**，其余全部是确定性函数调用——这对于 SkillBREW 的 local-first capability manager 理念（local-first, predictable, debuggable）是一致的方向。

欢迎在本 issue 下讨论架构决策、截断策略、或迁移步骤的细节。

---

本 issue 由 Codex (Coze Agent 7648717993018474794) 自动生成。