界面与交互全面翻修(前两波):运行态有了 HUD 和时间轴,终态会收尾,全站令牌、组件、文案统一

来自 2026-09 的 UI/UX 审查(142 条)。本提交是前两波,第三波(记录页接入时间轴、跨页互链、check-ui 更新、全站扫尾)另行提交。

地基
- 设计令牌:全局规则和 .btn/.field/.chip 放进 CSS 层,Tailwind 工具类重新生效,选中态、开启态不再被吞掉;字号阶梯;
  辅助文字在所有底色上 >= 4.5:1;状态色专用,节点类型色与之拉开色相;「跟随系统」真的跟随,首帧不闪深色;新字标与 favicon
- 基础组件:confirmDialog / promptDialog 取代原生对话框;toast 出错不自动消失、可复制、读屏可播报;离线横幅与断线恢复;
  九种剪影的状态徽标;唯一一份状态文案(lib/status)、格式化(lib/format)、术语(lib/terms)、报错人话(lib/errors)
- 运行态内核:事件折成航迹(run/trace.ts),可投影到任意时刻;取消 / 失败 / 服务重启后统一收尾,不再永远转圈;
  run.status 随事件回写;token 事件不再堆进 events
- 后端:协作成员逐个完成即发事件,调度者决策有事件;时长分执行 / 墙钟 / 等人;API 时间带时区;
  中断的运行也发 stream.end;运行列表可筛选翻页;删除运行 / 工作流有保护;运行默认值接通;可测未保存的配置;
  报错说清发生了什么、为什么、怎么办

功能
- 画布:状态四重编码、固定高度遥测槽、按缩放三档、运行胶囊与 HUD、航迹时间轴与回放、执行轨迹边、
  等待闸门、跟随执行、正式运行只读、一次性时刻(开场点亮、回扫、阻断级联、出具印章)
- 编辑:撤销重做、版本历史、问题面板可定位、三栏可收起、模板与表达式字段区分、变量血缘、快捷键、带搜索的选择器
- 回答流 / 问数据:贴底才跟随滚动、工件下钻、出具横幅列出缺口、答案可复制导出、按会话的忙闲、
  答案不再在 2000 字处截断、重启后这一轮会收尾
- 记录页:待审批 / 运行中 / 失败页签、筛选翻页、实时接流、排错路径指到节点、封存凭证常驻
- 管理页:新的「数据」页、写操作失败都有反馈、弹窗里先测连接、统一持久的连接状态
- 外壳:导航改版、⌘K 命令面板、? 快捷键帮助、404、页面标题与 favicon 状态点、后台提醒

验证(沙箱):tsc 干净,pytest 579 passed,14 个检查脚本中 13 个全绿;check-ui 剩 1 项旧断言(按旧日期格式找运行行),第三波更新。
This commit is contained in:
ThearchyHelios
2026-09-26 23:11:31 +08:00
parent 95ff6470d1
commit e10c4f23fc
132 changed files with 43558 additions and 5399 deletions
+240 -25
View File
@@ -1,7 +1,37 @@
import { useEffect, useRef } from 'react'
import { create } from 'zustand'
import { api } from '../api/client'
import { ApiError, api, onConnectivity } from '../api/client'
import type { Approval, Provider, Skill, ToolInfo, Workflow } from '../types'
/**
* 后端连没连上。
*
* 之前 refresh 对每个请求 `.catch(() => [])`,然后照样 loaded:true——后端挂了,
* 整站显示「还没有工作流 / 还没有接入数据源」并引导新建。在工业场景里这等于告诉
* 用户"你的数据没了",还会诱发重复配置。空和断必须分得开。
*/
export type BackendState = 'checking' | 'ok' | 'down'
/** 启动清单里的一行:catalog.refresh 的一个真实请求 */
export interface CatalogCheck {
key: 'providers' | 'tools' | 'skills' | 'collections' | 'workflows' | 'approvals'
label: string
state: 'pending' | 'ok' | 'error'
ms?: number
status?: number
error?: string
}
const CHECK_LABELS: Record<CatalogCheck['key'], string> = {
providers: '模型接入', tools: '工具', skills: 'Skill',
collections: '知识库', workflows: '工作流', approvals: '待审批',
}
/** 心跳间隔:连着时复用 4 秒一次的待审批轮询,不另起请求 */
const HEARTBEAT_MS = 4000
/** 断开后的重试退避 */
const BACKOFF_MS = [4000, 8000, 16000]
/** 全局参照数据:属性面板的各种下拉都从这里取,只加载一次。 */
interface CatalogState {
providers: Provider[]
@@ -13,34 +43,219 @@ interface CatalogState {
loaded: boolean
refresh: () => Promise<void>
refreshApprovals: () => Promise<void>
backend: BackendState
/** 最近一次成功请求的往返毫秒。没测到是 null */
latencyMs: number | null
/** 最后一次确认连通的时刻(ms) */
lastOkAt: number | null
/** 断开的原因,给横幅和遥测点的悬停说明 */
backendError: string | null
/** 断开时下一次自动重试的时刻(ms),横幅倒计时用 */
retryAt: number | null
/** 最近一次 refresh 的逐项结果,启动页的清单用 */
checks: CatalogCheck[]
/** 断开后又连上的次数。页面用 useOnReconnect 订阅它,重拉自己的列表 */
reconnects: number
/** 立刻探一次 /health。「立即重试」按钮调它 */
checkBackend: () => Promise<boolean>
/**
* 开始心跳:连着时每 4 秒拉一次待审批(顺便测延迟)。断开后的重试不归它管,
* catalog 自己按 4→8→16 秒退避探 /health,恢复后自动 refresh。返回停止函数。
* 重复调用只会有一个心跳在跑。
*/
startHeartbeat: () => () => void
}
export const useCatalog = create<CatalogState>((set) => ({
providers: [],
tools: [],
skills: [],
collections: [],
workflows: [],
approvals: [],
loaded: false,
let probing: Promise<boolean> | null = null
let retryTimer: ReturnType<typeof setTimeout> | undefined
let heartbeatOwner: symbol | null = null
let markUpRef: (latencyMs?: number) => void = () => {}
refresh: async () => {
// 单项失败不该让整个面板空掉,各自兜底
const [providers, tools, skills, collections, workflows, approvals] = await Promise.all([
api.providers.list().catch(() => []),
api.tools.list().catch(() => []),
api.skills.list().catch(() => []),
api.kb.collections().catch(() => []),
api.workflows.list().catch(() => []),
api.approvals.list().catch(() => []),
])
set({ providers, tools, skills, collections, workflows, approvals, loaded: true })
},
export const useCatalog = create<CatalogState>((set, get) => {
let backoffStep = 0
refreshApprovals: async () => {
set({ approvals: await api.approvals.list().catch(() => []) })
},
}))
const markDown = (error: string) => {
// 已经断着再失败一次,就把下一次重试往后推一档。所以"发现断开"的各条路
// (refresh、refreshApprovals、onConnectivity)都只在还没判 down 时才探活,
// 否则同一次断开记两笔,第一次就从 8 秒起跳
backoffStep = get().backend === 'down' ? Math.min(backoffStep + 1, BACKOFF_MS.length - 1) : 0
const delay = BACKOFF_MS[backoffStep]
set({ backend: 'down', backendError: error, latencyMs: null, retryAt: Date.now() + delay })
// 重试自己排,不搭调用方轮询的车:App 里 4 秒一拍的轮询会把「4 秒后重试」
// 拖成 6、7 秒,横幅倒计时走到 0 还得再干等
clearTimeout(retryTimer)
retryTimer = setTimeout(() => { retryTimer = undefined; void get().checkBackend() }, delay)
}
const markUp = (latencyMs?: number) => {
const wasDown = get().backend === 'down'
backoffStep = 0
clearTimeout(retryTimer)
retryTimer = undefined
set((s) => ({
backend: 'ok', backendError: null, retryAt: null, lastOkAt: Date.now(),
...(latencyMs != null ? { latencyMs } : {}),
...(wasDown ? { reconnects: s.reconnects + 1 } : {}),
}))
// 恢复了就把断开期间的空列表换回真数据,用户不用手动刷新。这里只管 catalog
// 自己的几张表;页面自己拉的列表靠 useOnReconnect
if (wasDown) void get().refresh()
}
markUpRef = markUp
return {
providers: [],
tools: [],
skills: [],
collections: [],
workflows: [],
approvals: [],
loaded: false,
backend: 'checking',
latencyMs: null,
lastOkAt: null,
backendError: null,
retryAt: null,
checks: [],
reconnects: 0,
refresh: async () => {
const keys = Object.keys(CHECK_LABELS) as CatalogCheck['key'][]
set({ checks: keys.map((key) => ({ key, label: CHECK_LABELS[key], state: 'pending' })) })
const update = (key: CatalogCheck['key'], patch: Partial<CatalogCheck>) =>
set((s) => ({ checks: s.checks.map((c) => (c.key === key ? { ...c, ...patch } : c)) }))
let networkFailures = 0
let lastError = ''
// 单项失败不该让整个面板空掉,各自兜底;但要记下是不是"够不着",
// 六个全是网络失败就是后端断了,不是"什么都没有"
const track = <T>(key: CatalogCheck['key'], p: Promise<T>): Promise<T | []> => {
const t0 = performance.now()
return p.then(
(v) => { update(key, { state: 'ok', ms: Math.round(performance.now() - t0) }); return v },
(e: unknown) => {
const err = e instanceof ApiError ? e : null
if (err?.kind === 'network') networkFailures++
lastError = err?.message ?? String((e as any)?.message ?? e)
update(key, {
state: 'error', ms: Math.round(performance.now() - t0),
status: err?.status || undefined, error: lastError,
})
return []
},
)
}
const t0 = performance.now()
const [providers, tools, skills, collections, workflows, approvals] = await Promise.all([
track('providers', api.providers.list()),
track('tools', api.tools.list()),
track('skills', api.skills.list()),
track('collections', api.kb.collections()),
track('workflows', api.workflows.list()),
track('approvals', api.approvals.list()),
])
set({ providers, tools, skills, collections, workflows, approvals, loaded: true })
if (networkFailures === keys.length) {
// 第一个失败的请求已经通过 onConnectivity 起了一次探活;这里并进同一次,
// 不另记一笔——两笔会让第一次断开就跳到退避的第二档(8 秒而不是 4 秒)
if (get().backend !== 'down') await get().checkBackend()
} else if (networkFailures === 0) {
markUp(Math.round(performance.now() - t0))
}
},
refreshApprovals: async () => {
// 断开期间不跟着调用方的 4 秒轮询一起敲,重试按 markDown 排的退避走——
// 否则横幅上「16 秒后重试」是假的。过了点还没探(定时器被节流之类)才补一次
const { backend, retryAt } = get()
if (backend === 'down') {
if (!retryAt || Date.now() >= retryAt) await get().checkBackend()
return
}
const t0 = performance.now()
try {
const approvals = await api.approvals.list()
set({ approvals, latencyMs: Math.round(performance.now() - t0), lastOkAt: Date.now() })
} catch (e) {
// 后端回了错误码说明它还活着,列表保持原样;够不着才去确认是否断开
if (e instanceof ApiError && e.kind === 'network' && get().backend !== 'down') await get().checkBackend()
}
},
checkBackend: () => {
if (probing) return probing
probing = (async () => {
const t0 = performance.now()
try {
await api.health()
markUp(Math.round(performance.now() - t0))
return true
} catch (e) {
markDown(e instanceof ApiError ? e.message : String((e as any)?.message ?? e))
return false
} finally {
probing = null
}
})()
return probing
},
startHeartbeat: () => {
const me = Symbol('heartbeat')
heartbeatOwner = me
let timer: ReturnType<typeof setTimeout> | undefined
// 链式 setTimeout 而不是 setInterval:后端慢的时候上一拍没回来,不叠下一拍
const tick = async () => {
if (heartbeatOwner !== me) return
await get().refreshApprovals()
if (heartbeatOwner !== me) return
timer = setTimeout(() => void tick(), HEARTBEAT_MS)
}
timer = setTimeout(() => void tick(), HEARTBEAT_MS)
return () => {
if (heartbeatOwner === me) heartbeatOwner = null
if (timer) clearTimeout(timer)
}
},
}
})
// 任何一个请求的成败都是连接状态的证据:页面上的保存、加载失败于网络时立刻去
// 确认一次,不必等下一拍心跳;断开期间任何请求成功了就算恢复
onConnectivity((reachable) => {
const s = useCatalog.getState()
if (reachable) {
if (s.backend !== 'ok') markUpRef()
} else if (s.backend !== 'down') {
// 一次失败先别急着宣布断开:再探一次 /health,两次都够不着才算——一次代理
// 抖动不该让整站横幅闪一下
void s.checkBackend()
}
})
/**
* 后端断开又连上时调用 cb。
*
* 断开期间页面自己拉的列表(运行记录、数据源、会话、知识库文档……)拿到的是
* 空数组;恢复时 catalog 只会刷新它自己那几张表,页面不重拉,就又回到「还没有
* 运行记录」这种假的空态。首次连上(checking → ok)不算,进页时不会多拉一遍。
* cb 总是用最新的那一个,调用方不用 useCallback。
*/
export function useOnReconnect(cb: () => void): void {
const cbRef = useRef(cb)
useEffect(() => { cbRef.current = cb })
useEffect(() => useCatalog.subscribe((s, prev) => {
if (s.reconnects !== prev.reconnects) cbRef.current()
}), [])
}
/** 这条运行有没有待处理的审批。区分「等待审批」和「已挂起 · 可续跑」要用它 */
export function hasPendingApproval(approvals: Approval[], runId: string | null | undefined): boolean {
if (!runId) return false
return approvals.some((a) => a.run_id === runId && a.status === 'pending')
}
/** 把所有 provider 的模型拉平成下拉选项。 */
export function modelOptions(providers: Provider[]): { value: string; label: string; group: string }[] {
+1012 -240
View File
File diff suppressed because it is too large Load Diff
+40 -3
View File
@@ -31,6 +31,8 @@ interface ConversationState {
list: Conversation[]
currentId: string | null
loading: boolean
/** 列表取失败了。和「一个对话都没有」要分开说 */
error: unknown
load: () => Promise<void>
/** 新建(或复用一条空的),返回它的 id。**不负责切过去**——那是导航的事 */
@@ -40,6 +42,15 @@ interface ConversationState {
rename: (id: string, title: string) => Promise<void>
/** 删掉,返回接下来该去哪个(列表空了就是 null),由调用方导航 */
remove: (id: string) => Promise<string | null>
/**
* 从列表里拿掉(归档),返回接下来该去哪个。撤销就是 restore。
*
* 用归档而不是「先藏起来、过几秒再真删」:延迟删除在关掉标签页、切走页面时
* 要么没删成、要么撤销不了。归档是一次就落库的状态,撤不撤都不会丢
*/
archive: (id: string) => Promise<string | null>
/** 撤销归档,放回原来的位置 */
restore: (item: Conversation, index: number) => Promise<void>
/** 有人在这个会话里说话了,把它顶到列表最前并刷新副标题 */
touch: (id: string, lastQuestion?: string) => void
}
@@ -48,15 +59,16 @@ export const useConversations = create<ConversationState>((set, get) => ({
list: [],
currentId: null, // 由 URL 填,见 ChatPage 的同步 effect
loading: false,
error: null,
load: async () => {
// 只管把列表取回来。「当前在看哪个」以前也在这里决定,现在归 URL 管——
// 两边都能定就会互相覆盖:深链接进来,列表一加载完又被拽回上次那个
set({ loading: true })
try {
set({ list: await api.conversations.list('chat'), loading: false })
} catch {
set({ loading: false })
set({ list: await api.conversations.list('chat'), loading: false, error: null })
} catch (e) {
set({ loading: false, error: e })
}
},
@@ -98,6 +110,30 @@ export const useConversations = create<ConversationState>((set, get) => ({
return get().currentId === id ? (list[0]?.id ?? null) : get().currentId
},
archive: async (id) => {
const before = get().list
const list = before.filter((c) => c.id !== id)
// 先从列表里拿掉再发请求:删除该是即时的,失败了再放回去
set({ list })
try {
await api.conversations.update(id, { archived: true })
} catch (e) {
set({ list: before })
throw e
}
return get().currentId === id ? (list[0]?.id ?? null) : get().currentId
},
restore: async (item, index) => {
await api.conversations.update(item.id, { archived: false })
set((s) => {
if (s.list.some((c) => c.id === item.id)) return s
const list = [...s.list]
list.splice(Math.min(index, list.length), 0, { ...item, archived: false })
return { list }
})
},
touch: (id, lastQuestion) => {
set((s) => {
const hit = s.list.find((c) => c.id === id)
@@ -110,6 +146,7 @@ export const useConversations = create<ConversationState>((set, get) => ({
? (lastQuestion.length > 24 ? lastQuestion.slice(0, 24) + '…' : lastQuestion)
: hit.title,
turn_count: hit.turn_count + (lastQuestion ? 1 : 0),
last_active_at: new Date().toISOString(),
}
return { list: [updated, ...s.list.filter((c) => c.id !== id)] }
})
+1405 -161
View File
File diff suppressed because it is too large Load Diff