CodePilot/docs/handover/ui-governance.md

设计模式与组件一致性治理

完成时间：2026-03-12 | 涉及 92 个文件 | 净减 ~2,900 行

治理目标

在保留现有视觉语言的前提下，建立统一的组件分层规则、消灭跨层重复模式、拆分超大组件、通过 ESLint 静态约束防止退化。

分层架构

src/components/ui/          → 纯 primitives（Button, Input, Select, Dialog…）
src/components/patterns/    → 复用展示模式（SettingsCard, FieldRow, StatusBanner…），零副作用
src/components/{feature}/   → 组合 hooks + patterns + 业务状态
src/app/                    → 页面装配
src/hooks/                  → 数据获取、状态管理
src/lib/constants/          → 纯数据常量，不引用 UI 层

已完成的治理项

1. ESLint 治理规则 (eslint.config.mjs)

规则	级别	作用域	说明
禁止原生 HTML 控件	warn	业务组件 + app 层	<button/input/select/textarea> → 使用 ui/ 组件
禁止 Lucide 导入	error	src/**	统一使用 Phosphor，通过 ui/icon.tsx 入口
禁止直接引用 Phosphor	warn	业务组件 + hooks	应从 @/components/ui/icon 导入
组件文件行数上限 500	warn	src/components/**（排除 ui/、ai-elements/）	skipBlankLines + skipComments
Patterns 层隔离	error	src/components/patterns/**	禁止导入 @/hooks/* 和 @/lib/*（允许 @/lib/utils）
外部资料目录排除	—	资料/**	不参与主仓 lint

2. 图标统一 (src/components/ui/icon.tsx)

• 所有业务组件通过 @/components/ui/icon 统一入口导入 Phosphor 图标
• 目前导出 86+ 个图标 + ICON_SIZE 常量 + Icon/IconProps 类型
• types/index.ts 中的 IconComponent 类型与 Phosphor 解耦，使用泛型 SVG 签名
• 图标与命令数据分离：lib/constants/commands.ts（纯数据）+ lib/constants/command-icons.ts（图标映射），在 hooks/useSlashCommands.ts 中合并

3. 颜色 token 治理 (globals.css + lint:colors)

新增语义 token（light + dark）：

--status-success-{muted,foreground,border}   （原 green-*）
--status-warning-{muted,foreground,border}   （原 orange/yellow/amber-*）
--status-error-{muted,foreground,border}     （原 red-*）
--status-info-{muted,foreground,border}      （原 blue-*）

• Tailwind v4 通过 @theme inline 中的 --color-status-* 变量注册
• npm run lint:colors 检查 green/emerald/red/orange/yellow/amber/blue-{400-700} 用法
• 例外行标注 // lint-allow-raw-color（如 diff 语法高亮、终端提示符）

4. Patterns 层 (src/components/patterns/)

组件	用途
SettingsCard	统一的设置卡片容器（title + description + children）
FieldRow	设置项行布局（label + description + 右侧控件）
StatusBanner	success/warning/error/info 状态横幅
EmptyState	空状态占位（icon + title + description + action）
CommandList	斜杠命令列表弹窗

5. 超大组件拆分

组件	原始行数	当前行数	抽出的子模块
MessageInput	1,659	444	MessageInputParts, SlashCommandPopover, hooks: useChatCommands, usePopoverState, useSlashCommands, useCliToolsFetch, useCommandBadge, libs: message-input-logic, file-utils
ChatView	~850	419	useStreamSubscription, useAssistantTrigger
ProviderManager	1,081	~406	provider-presets, PresetConnectDialog, useProviderModels
AppShell	527	470	useUpdateChecker
AssistantWorkspaceSection	908	499	WorkspaceTabPanels, WorkspaceConfirmDialogs, WorkspaceStatusCards, workspace-types
ChatListPanel	677	484	SessionListItem, ProjectGroupHeader, chat-list-utils

6. 原生 HTML 控件迁移

38 个文件中 80 处原生 <button/input/textarea/select> 替换为 ui/Button、ui/Input、ui/Textarea、ui/Select。

7. Hook 依赖与死代码清理

• 修复 react-hooks/exhaustive-deps 和 react-hooks/set-state-in-effect 共 22 处
• 清除 unused imports/variables 共 7 处
• AppShell 中 5 个 set-state-in-effect 错误通过 lazy initializer、derived state、eslint-disable-next-line 组合解决

新增文件清单

组件

• src/components/patterns/CommandList.tsx
• src/components/chat/MessageInputParts.tsx
• src/components/chat/SlashCommandPopover.tsx（重构）
• src/components/layout/SessionListItem.tsx
• src/components/layout/ProjectGroupHeader.tsx
• src/components/layout/chat-list-utils.ts
• src/components/settings/provider-presets.tsx
• src/components/settings/PresetConnectDialog.tsx
• src/components/settings/WorkspaceTabPanels.tsx
• src/components/settings/WorkspaceConfirmDialogs.tsx
• src/components/settings/WorkspaceStatusCards.tsx
• src/components/settings/workspace-types.ts

Hooks

• src/hooks/useAssistantTrigger.ts
• src/hooks/useChatCommands.ts
• src/hooks/useCliToolsFetch.ts
• src/hooks/useCommandBadge.ts
• src/hooks/usePopoverState.ts
• src/hooks/useProviderModels.ts
• src/hooks/useSlashCommands.ts
• src/hooks/useStreamSubscription.ts
• src/hooks/useUpdateChecker.ts

Lib

• src/lib/constants/commands.ts
• src/lib/constants/command-icons.ts
• src/lib/file-utils.ts
• src/lib/message-input-logic.ts

当前 Lint 状态

• 治理涉及文件：0 errors, 0 warnings
• 全仓：0 errors, 80 warnings（均在未涉及的文件中：tests、api routes、lib、ai-elements）
• Typecheck：通过
• Unit tests：374 pass, 0 fail

已知遗留（不在本轮治理范围）

1. ai-elements 层：prompt-input.tsx（1,345L）仍含 30+ thin re-export wrappers；file-tree.tsx 有可访问性 warning
2. 全仓 80 warnings：主要是 tests 中的死代码、bridge adapters 中的 unused vars、stream-session-manager.ts 中的 unused imports
3. CodeBlock 两套并存：chat/CodeBlock.tsx（Prism）和 ai-elements/code-block.tsx（Shiki），计划统一为 Shiki
4. catch { // ignore } 模式：50+ 处静默错误，需逐步加 toast 或 console.warn

开发者须知

• 新建业务组件时，从 @/components/ui/icon 导入图标，不要直接引 @phosphor-icons/react
• 颜色使用语义 token（text-status-success-foreground），不用裸色值（text-green-500）
• 新 pattern 组件放 patterns/，不引 hooks/lib（除 @/lib/utils 的 cn()）
• 组件超过 500 行时考虑拆分
• 提交前运行 npm run test + npm run lint:colors