feat: add verified user flow visualization

[hifizz]

目标

为 ThreadChat 增加类似 Mermaid 的用户流程图能力：用户只需自然语言提出“画个用户流程图”，主模型调用 generate_visualization，由独立低成本模型生成结构化 FlowSpec，经过确定性校验与有限 repair 后持久化为 data-visualization message part，并在前端以交互式流程图渲染。

OpenSpec

本需求以以下 OpenSpec change 为权威跟踪与验收来源：

• openspec/changes/add-user-flow-visualization/.openspec.yaml
• proposal.md
• design.md
• specs/user-flow-visualization/spec.md
• tasks.md

原设计文档 docs/plans/2026-09-14-user-flow-visualization.md 仅作为讨论摘要；冲突时以 OpenSpec 为准。

已实现

领域 IR 与校验

• 新增版本化 FlowSpec / FlowNode / FlowEdge / FlowGroup。
• FlowSpec 是 ThreadChat 自有稳定领域 IR，只描述图的业务语义。
• 使用严格 Zod schema 拒绝 position、style、handle、React Flow / Dagre / ELK 等 renderer-specific 字段进入持久化数据。
• deterministic Graph Verify 覆盖重复 node/edge、未知端点、重复边、自环、group 引用等错误。

专用低成本模型生成

• 新增 generate_visualization Tool。
• 默认使用 private-relay-gpt-5.6-luna，可通过 VISUALIZATION_MODEL_ID 覆盖，与用户当前聊天模型解耦。
• 使用 AI SDK structured output 生成 FlowSpec。
• verify 失败时将当前 spec + structured errors 交给同一模型 repair。
• 总 attempts 上限为 3，失败不会产生成功的 data-visualization part。
• 记录 model id、耗时、first-pass、repair 次数、usage。

Message 持久化

• 新增 typed data-visualization assistant part。
• authoritative message snapshot 只保留 FlowSpec；内部 tool-generate_visualization payload 不作为最终业务数据持久化。
• 不新增 visualization 表，不保存 SVG/HTML/React Flow graph。

可替换 Renderer

• 新增 FlowRendererAdapter<TGraph> 边界。
• V1 使用项目已有的 @dagrejs/dagre 做 layout、@xyflow/react 做 renderer，不新增图形依赖。
• position、node type、styles、zIndex、layout options 全部只存在 Adapter/Renderer 层。
• 契约测试使用第二个 mock adapter 验证同一 FlowSpec 可以替换 renderer，而不修改 Tool、持久化 schema 和领域 Verify。

前端

• 新增 VisualizationBlock / FlowCanvas / node / edge / group renderer。
• 支持 LR/TB 流程、group、图表/源码切换、Fit、Zoom Out、Zoom In、Reset。
• 可视化 Tool 的内部 input/output 不在普通 assistant UI 中重复展示。

验证

新增路径限定的 Visualization CI，保护该功能的类型和 renderer-independent 契约：

• ✅ pnpm typecheck
• ✅ node --import tsx e2e/thread-chat/user-flow-visualization.test.mjs
• ✅ pnpm exec openspec validate add-user-flow-visualization --strict
• ✅ 仓库 OpenSpec workflow (validate --all --strict)

当前仍未声称完成：

• 桌面 / 移动端真实 UI 验收；
• 完整 production build：当前 Vercel preview 在进入 Next.js/TypeScript build 前就被既有数据库 migration 步骤阻断，因此不能把该失败归因于本功能；
• Render Verify / Semantic Verify / 小型模型 evaluation set（按 OpenSpec 属于后续项）。

仓库现有 Agent Evals workflow 当前仍有与本功能无关的 search-abort.test.mjs 失败；Visualization 自己的 typecheck + contract CI 已单独通过。

分支

• Head: feat/user-flow-visualization
• Base: main
• 与 PR feat: 支持 Markdown Artifact 划选开 Thread #143 无依赖

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
thread-chatbot	Error		Sep 18, 2026 11:49am UTC

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 9ec9b233-d006-4f36-963d-9451e0d5c702

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}