Architecture: UIX 与 AgentX UI 的关系定位

[deepracticexc]

背景

经过与 Sean 的讨论，明确了 Lucid UI 在 Deepractice 生态中的定位。

架构关系

AgentX (产品/运行时)
  ↓ 使用
@agentxjs/ui (组件实现)
  ↓ 引用
Lucid UI (设计语言/规范)

• AgentX 定义了"需要什么组件"(Studio、MessagePane、UserMessage...)，这是产品需求驱动的
• Lucid UI 负责回答"这些组件长什么样、怎么交互"，是设计细节的 Source of Truth

Lucid UI 的职责

层面	AgentX UI 定义	Lucid UI 负责
颜色	Primary/Secondary/Accent	具体色值、渐变、状态变化规则
组件	MessageAvatar 存在	Avatar 的尺寸规格、边框样式、状态指示器设计
布局	三栏结构	响应式断点、间距比例、折叠动画
交互	消息有状态	Thinking 动画、Streaming 效果、Error 样式
移动端	需要适配	Bottom Tab Bar 规范、Action Sheet 设计原则

Lucid UI 输出物

1. Design Tokens - CSS Variables / Tailwind Config
2. 组件设计规范文档 - 每个组件的设计细节
3. 交互模式指南 - 动画、状态转换、响应式行为
4. 可选: Figma 设计稿

术语统一

颜色系统

Lucid UI 当前	AgentX UI 当前	统一后
Rational Blue	Primary (Blue)	Primary / Rational
Sentient Gold	Secondary (Amber)	Secondary / Sentient
-	Accent (Orange)	Accent

组件命名

Lucid UI 应采用 AgentX UI 的组件命名体系，确保一致性。

---

AgentX UI 组件清单

以下是 @agentxjs/ui 当前的完整组件结构，Lucid UI 需要为每个组件提供设计规范。

1. Studio 层 (完整工作台)

组件	描述	Lucid UI 需要定义
Studio	完整的聊天工作台	整体布局、响应式行为

2. Container 层 (业务容器)

组件	描述	Lucid UI 需要定义
AgentList	对话/智能体列表	列表项样式、选中状态、空状态
Chat	聊天界面	消息区布局、滚动行为
ChatHeader	聊天头部	标题样式、操作按钮布局
ToolCard	工具调用卡片	折叠/展开动画、状态指示

3. Pane 层 (纯UI面板)

组件	描述	Lucid UI 需要定义
NavBar	图标导航栏	图标尺寸、激活状态、hover效果
ListPane	通用列表面板	搜索框样式、列表间距
MessagePane	消息显示区域	消息间距、时间分割线
InputPane	输入区域	输入框样式、发送按钮
InputToolBar	输入工具栏	工具按钮样式、布局

4. Layout 层 (布局结构)

组件	描述	Lucid UI 需要定义
ActivityBar	活动栏	宽度、图标样式
Header	顶部栏	高度、阴影、内容布局
MainContent	主内容区	padding、最大宽度
Panel	面板容器	边框、圆角、阴影
RightSidebar	右侧边栏	宽度、折叠动画
Sidebar	侧边栏	宽度、背景色
StatusBar	状态栏	高度、内容样式

5. Element 层 (原子组件)

组件	描述	Lucid UI 需要定义
ActionBar	操作栏	按钮间距、分隔线
AgentLogo	智能体Logo	尺寸规格、圆角
AppHeader	应用头部	布局、品牌区域
Badge	徽章	尺寸、颜色变体
Button	按钮	尺寸变体、颜色变体、状态样式
EmojiPicker	表情选择器	面板布局、emoji尺寸
EmptyState	空状态	图标、文案样式
ImageAttachment	图片附件	预览尺寸、加载状态
Input	输入框	尺寸、边框、焦点状态
ListItem	列表项	高度、内边距、hover状态
LoadingState	加载状态	动画样式、文案
MessageAvatar	消息头像	尺寸、在线状态指示器
PageHeader	页面头部	标题样式、面包屑
Popover	弹出层	阴影、圆角、动画
ScrollArea	滚动区域	滚动条样式
SearchInput	搜索输入框	图标、清除按钮
TabNavigation	标签导航	标签样式、激活指示器
TimeAgo	时间显示	格式、颜色
TokenUsagePie	Token用量饼图	颜色、尺寸
Toast	提示消息	位置、动画、颜色变体

6. Message 层 (消息组件)

组件	描述	Lucid UI 需要定义
MessageRenderer	消息渲染器	消息间距
UserMessage	用户消息	气泡样式、对齐方式
AssistantMessage	AI助手消息	气泡样式、状态指示(thinking/streaming/complete)
ToolMessage	工具调用消息	代码块样式、折叠状态
ErrorMessage	错误消息	错误样式、重试按钮
UnknownMessage	未知消息	降级显示样式
MessageAvatar	消息头像	尺寸、位置
MessageContent	消息内容	Markdown渲染、代码高亮

7. Typography 层 (排版组件)

组件	描述	Lucid UI 需要定义
DiffViewer	Diff查看器	行高亮颜色、行号样式
JSONRenderer	JSON渲染器	语法高亮、折叠样式
MarkdownText	Markdown文本	标题、列表、代码块样式

---

下一步行动

1. 统一颜色系统命名
2. 为每个 Element 层组件编写设计规范
3. 定义 Message 组件的状态和动画
4. 提取 Design Tokens 为独立包
5. 更新 Demo 站点组件命名与 AgentX UI 对齐

---

相关资源

• AgentX Repository
• @agentxjs/ui Package
• [AgentX UI Storybook](运行 pnpm storybook 查看)

---

负责人: @deepracticexc (宝哥)

[deepracticexc]

补充: 完整待办事项梳理

基于上面的架构分析,以下是具体的执行清单。

---

一、Design Tokens 统一 🔴

颜色系统对齐

当前差异:

定义位置	Primary	Secondary
Lucid UI	#3B82F6 (blue-500)	#D4A012
AgentX UI	#0284c7 (blue-600)	#f59e0b (amber-500)

待办:

• 统一颜色值 (建议以 AgentX 为准)
• 统一命名: primary/secondary 为语义名, rational/sentient 为别名
• 定义完整语义 Token: background, foreground, muted, card, popover, border, ring, success, warning, error

---

二、Demo 站点分类重构 🟡

调整为与 AgentX UI 一致:

Foundation (Design Tokens)
├── Colors / Typography / Spacing / Responsive

Element (原子组件)
├── Button / Badge / Input / Avatar / Toast / SearchInput / ActionBar...

Message (消息组件)
├── UserMessage / AssistantMessage / ToolMessage / ErrorMessage

Pane (面板组件)
├── ListPane / MessagePane / InputPane / NavBar

Layout (布局组件)
├── AppShell / Header / Sidebar / Panel

Mobile (移动端)
├── BottomTabBar / ActionSheet

---

三、核心组件规范 🔴

Message 组件 (用户感知最强)

AssistantMessage 状态:

状态	显示	样式
queued	"Queue..."	text-muted-foreground + 动画点
thinking	"Thinking..."	text-muted-foreground + 动画点
responding	流式文本	正常文本 + 闪烁光标
success	完整消息	正常文本

消息布局:

• 用户消息: 右对齐, primary 背景
• AI 消息: 左对齐, muted 背景
• 间距: py-2, gap-3
• 最大宽度: max-w-[80%]

Element 组件

需要为以下组件编写规范:

• Button (变体/尺寸/状态)
• Badge
• Input / SearchInput
• Avatar / MessageAvatar (尺寸/角色区分/状态指示器)
• Toast (位置/变体/动画)
• EmptyState / LoadingState
• ActionBar / TabNavigation

---

四、执行计划

Phase 1: 颜色统一 + Demo 分类重构 + Message 规范
Phase 2: Element 组件规范完善
Phase 3: Layout/Typography/Mobile 规范 + @lucidui/tokens 发布

---

负责人: @deepracticexc (宝哥)

[deepracticexc]

更新：架构决策已记录

基于今天的战略讨论，已创建以下 ADR 文档：

• ADR-0001: 企业级 UI 基础设施定位
• ADR-0002: UI 协议选择延迟决策

关键决策：

1. Lucid-UI 定位为 企业级 UI 基础设施（非"组织级"）
2. UI 协议（A2UI vs MCP Apps）延迟 3-6 个月决策
3. 架构预留协议适配层

此 issue 中描述的架构关系仍然有效，README 已更新反映新定位。

[deepracticexc]

🔄 2024-12-22 更新

项目重命名

• Lucid-UI → UIX (AI-to-UI Protocol)

新架构关系

AgentX (产品/运行时)
  ↓ 使用
@agentxjs/ui (组件实现)
  ↓ 引用
UIX (设计语言/协议)
  ├── @uix/core        - Lucid IR 类型定义
  ├── @uix/tokens      - Design Tokens
  ├── @uix/react       - React 基础组件
  ├── @uix/agent       - AI Agent 组件
  ├── @uix/stream      - 流式渲染 (Streamdown)
  └── @uix/adapter-vercel - Vercel AI SDK 适配器

待更新内容

原 issue 中的组件清单需要与新包结构对齐：

• packages/agent 现在包含：MessageList, ToolResult, SourceBlock, ThinkingBlock
• packages/stream 现在使用 Vercel Streamdown

术语更新

旧术语	新术语
Lucid UI	UIX
Lucid IR	@uix/core
lucid-tokens	@uix/tokens