goodbuddy/UI-DESIGN.md

GoodBuddy 统一界面设计系统

1. 目的与适用范围

本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、任务中心、知识库、 智能心跳、运行记录，以及后续新增的一级页面。

设计系统解决两类问题：

1. 统一跨页面的视觉语言、信息层级和交互反馈。
2. 保留不同工作场景所需的布局差异，不强行把阅读、工作台、仪表盘和数据视图做成同一种页面。

所有新界面必须优先使用本文定义的语义令牌、页面壳层和共享组件。现有界面迁移时应保持功能与数据语义不变，不以视觉统一为理由隐藏范围、状态或风险。

2. 核心原则

2.1 一致的语义，不要求相同的布局

• 相同含义使用相同的颜色、间距、控件和文案结构。
• 不同任务使用明确命名的页面壳层，不再为单个页面随意设置宽度。
• 页签只用于同级页面导航，分段控件只用于当前视图内的单选切换，筛选控件只改变当前数据集合。

2.2 范围始终可见

知识、任务、自动化和活动记录可能属于全局或某个项目。当前范围必须在页面标题区或对象标题旁持续显示，不能只通过入口位置、默认筛选或颜色暗示。

2.3 主任务优先

• 每个页面只保留一个视觉上最突出的主操作。
• 页面标题、范围、说明、主操作和导航按固定层级排列。
• 次要设置、筛选和批量操作不得与主任务争夺注意力。

2.4 状态明确且可恢复

• 加载、空内容、无结果、失败、只读和权限不足是不同状态，必须分别呈现。
• 可撤销操作优先提供撤销，不可撤销操作必须在执行前说明影响范围。
• 不依赖颜色单独表达状态或风险。

2.5 默认支持浅色与深色主题

组件不得直接使用原始颜色值。主题差异只在令牌层定义，业务组件仅引用语义令牌。

两种主题必须保持相同的信息层级，但不要求机械地反转明暗。浅色主题以白色主内容画布、冰蓝灰侧栏和轻微着色的顶栏建立空间关系；深色主题使用深海军蓝与蓝灰表面逐层提亮，避免纯黑。蓝色承担主要选择和交互，青绿色主要承担成功与可用状态，二者不得混用语义。

3. 设计令牌

令牌以 CSS 自定义属性实现。:root 提供浅色值，[data-theme="dark"] 覆盖深色值。组件样式不得新增只服务于单个页面的颜色、阴影、圆角或间距常量。

3.1 颜色令牌

令牌	用途
--surface-canvas	应用和页面底色
--surface-raised	卡片、面板、输入框和弹窗
--surface-subtle	次级区域和控件底色
--surface-muted	进度轨道和更弱的分隔表面
--text-primary	标题与主要正文
--text-secondary	辅助正文
--text-muted	占位、时间和弱提示
--text-on-accent	强调色或危险色表面上的文字
--border-default	常规边框
--border-control	输入框、分段控件等必须清晰可辨的控件边界
--border-subtle	区块分隔线
--accent、--accent-hover	强调文字、图标和交互反馈
--accent-solid、--accent-solid-hover	主按钮等需要反白文字的强调背景
--accent-selected、--accent-subtle	选中边框、选中背景和信息强调
--success、--success-subtle	成功状态
--warning	警告状态
--danger、--danger-strong	危险文本和状态
--danger-solid	最终确认按钮等需要反白文字的危险背景
--danger-border、--danger-subtle	危险入口和失败状态背景

浅色与深色具体值只在 styles.css 的主题根节点维护。状态组件必须同时显示文字或图标，不能仅靠颜色区分。

表面与边框使用规则：

• 浅色主题的阅读、编辑和页面主内容使用白色或接近白色的 --surface-raised；主侧栏使用更深一阶的冰蓝灰 --surface-canvas，顶栏使用弱于侧栏的次级表面。相邻区域必须可辨，但不能形成高饱和色块。
• 深色主题从深海军蓝画布开始，以蓝灰表面逐层提亮。不同层级优先依靠表面亮度与语义边框区分，不使用纯黑底色或无边界的大面积同色区域。
• 浅色侧栏中，导航与最近会话、最近会话与账户区之间的结构分隔线使用 --border-default。列表行之间或卡片内部的弱分隔仍使用 --border-subtle，不得为了增强结构而给每一项加重边框。
• 控件边界、焦点环和选中边框必须达到至少 3:1 的非文本对比度；正文、状态色和弱文本分别遵守无障碍对比度要求。
• 业务组件不得通过主题条件分支写原始颜色；新增视觉层级时先确认能否复用现有表面、边框和状态令牌。

3.2 间距令牌

采用 4 像素基准：

令牌	值	典型用途
--space-0	0	显式取消间距
--space-1	4px	图标内部微调
--space-2	8px	紧凑控件、图标与文字
--space-3	12px	表单字段内部、紧凑列表
--space-4	16px	默认组件间距
--space-6	24px	区块间距、窄屏页面内边距

使用规则：

• 同一组件内部优先使用 8px、12px、16px。
• 同一区块内组件之间优先使用 16px 或 24px。
• 页面级区块之间优先使用 32px 或 40px。
• 不新增 14px、18px、22px 等非令牌间距。

3.3 字体令牌

界面英文和数字优先使用随客户端本地打包的 Inter Variable。简体中文优先使用平台原生 UI 字体：macOS 使用 PingFang SC，Windows 使用 Microsoft YaHei UI，以获得与系统渲染匹配的小字号 hinting；其他平台及缺失字形使用本地打包的 Noto Sans SC Variable。代码、标识符和原始日志使用等宽字体栈。字体不得通过运行时网络请求加载。

令牌	字号 / 行高	字重	用途
--font-caption	11px	时间、短标签和紧凑元数据
--font-body	13px	默认界面正文
--font-section-title	14px	卡片和区块标题
--font-page-title	24px	一级页面标题

使用规则：

• 业务组件通过 --font-family-ui 与字体尺寸令牌继承字体，不创建页面专属字体栈。
• 表单按钮、输入框、选择框和文本域必须继承界面字体，避免回退为原生控件字体。
• 连续阅读内容使用 14px，持久辅助信息不得小于 11px。
• 本地兜底字体资源必须随生产包交付，并同时包含 Inter 与 Noto Sans SC 的 OFL 许可证。
• 页面内不得通过同时放大字号、加粗和使用强调色制造多个同级主标题。

3.4 圆角、阴影与层级

令牌	值	用途
--radius-control	10px	输入框、按钮、菜单项
--radius-card	14px	卡片和面板
--shadow-card	主题定义	卡片和选中分段控件
--shadow-dialog	主题定义	对话框和浮层

整体使用适度圆角：控件和卡片保持清晰、克制的几何轮廓，不使用胶囊化的大圆角替代信息层级。普通卡片通过表面色和边框区分，不默认添加阴影；输入区等需要从内容流中明确浮起的持续操作面板可以使用克制的 --shadow-card。菜单和对话框使用对应层级阴影，阴影只表示真实的浮层关系。不允许页面自行创建高于 --z-dialog 的层级。

3.5 动效令牌

• --motion-fast: 120ms：悬停、按压、焦点反馈。
• --motion-normal: 180ms：菜单、折叠区域、轻量视图切换。
• --motion-slow: 240ms：对话框和抽屉。
• 默认缓动使用 ease-out，退出可使用 ease-in。
• 在 prefers-reduced-motion: reduce 下移除非必要位移和缩放，仅保留即时状态切换。

4. 页面壳层

所有一级页面使用 PageShell。壳层负责水平居中、最大宽度、响应式内边距、页面背景和滚动边界，业务页面不得再次设置独立的整体最大宽度。

变体	最大内容宽度	适用场景	页面映射
reading	820px	连续阅读、单列编辑、对话撰写	聊天正文与输入区
standard	960px	常规列表、设置与表单	最近对话、设置
dashboard	1040px	指标、卡片网格、宽表格与审计数据	智能心跳、活动记录
master-detail	可用空间内流式铺开	左侧选择、右侧编辑或预览	知识库

共同规则：

• 宽度计算统一为 min(100%, 变体最大宽度)。
• 页面左右内边距在常规桌面窗口为 32px，中等窗口为 24px，窄窗口为 16px。
• 页面顶部和底部内边距默认为 32px。
• master-detail 的左栏建议为 280px 至 360px，右栏占剩余空间。分隔线和滚动容器属于壳层，不由内容卡片模拟。
• 聊天输入区可以粘附在 reading 壳层底部，但消息内容和输入区必须共享同一阅读宽度。
• 宽表格可在 dashboard 内容区内部横向滚动，不得撑宽整个应用窗口。

5. 信息层级

一级页面按以下顺序组织：

1. PageHeader
2. PageTabs，仅在存在同级子页面时出现
3. 页面级状态或重要提示
4. 筛选与批量操作工具栏
5. 主内容
6. 与主内容就近关联的分页或加载状态

一个页面只能有一个可见的一级标题。卡片标题不得重复页面标题。面包屑只在层级超过两级且返回关系无法通过侧栏或主从布局表达时使用。

5.1 PageHeader

PageHeader 统一接收以下内容：

• title：必填，简短名词或任务名称。
• description：可选，一行说明当前页面能做什么，不重复标题。
• scope：涉及范围的数据页面必填，使用 ScopeBadge。
• primaryAction：可选，页面唯一主操作。
• secondaryActions：可选，最多两个直接显示，其余进入更多菜单。
• status：可选，用于只读、同步中、连接异常等页面级状态。

布局规则：

• 标题和范围徽标在同一信息组中，范围不得放入更多菜单。
• 主操作位于标题区右侧，窄窗口下换行到标题下方并保持靠左。
• 不在内容卡片中再次渲染同名标题。
• 标题区默认不粘附。只有主内容长且页面级操作需要持续可用时才启用粘附。

6. 共享组件

6.1 PageTabs

用于同一一级页面内的同级内容面板，例如智能心跳的“运行概览”和“心跳计划”。

• 使用 tablist、tab 和 tabpanel 语义，当前项使用 aria-selected="true"。
• 一级页面之间的导航由应用主导航承担，不复用 PageTabs。
• 标签保持短名词，不显示句号，不用页签承载开关或过滤条件。
• 项目过多时优先重组信息架构，不把一级页签做成多行。
• PageTabs 可使用默认视觉或共享的 segmented 视觉变体。紧凑主从工作台中的 2 至 4 个同级面板可使用与模型设置一致的分段外观，但不得因此改用按钮组语义。
• 视觉变体不改变组件含义：分段外观的 PageTabs 仍使用页签语义、单一激活面板、游标焦点和方向键切换，不复制页面专属样式。
• 在独立滚动的 Flex 页面中，PageTabs 及其直接包装层必须保持 flex: 0 0 auto，不得被剩余内容压缩到零高度。新增页签容器时必须提供对应的 CSS 回归测试。

6.2 SegmentedControl

用于当前页面内互斥的视图或状态切换，例如“列表 / 网格”或少量单选状态。

• 选项数量为 2 至 4 个。
• 使用带 aria-pressed 的按钮组语义，支持方向键切换。
• 不能用于多选筛选、页面导航或执行即时命令。
• 控件宽度由内容决定，除移动窄屏外不默认等分整行。

6.3 筛选工具栏

筛选不创建第五种类似页签的视觉控件：

• 2 至 4 个互斥状态可使用 SegmentedControl。
• 多维条件使用统一尺寸的选择框、搜索框和复选菜单。
• 已生效条件以文字和值明确展示，并提供“清除筛选”。
• 无匹配结果使用“无结果”状态，不能显示为首次使用的空状态。
• 筛选条件改变数据范围时，结果数量或当前条件必须可见。

6.4 ScopeBadge

ScopeBadge 表达对象或页面数据的归属范围：

• 全局范围显示“全局”，并配合通用范围图标。
• 项目范围显示“项目：项目名称”，不得只显示项目名称。
• 未知或已失效范围显示“范围不可用”，并提供修复入口或只读说明。
• 徽标始终包含文字，不以颜色作为唯一差异。
• 可切换范围时，徽标作为范围选择器的触发器，并提供明确的展开状态和键盘操作。
• 不可切换范围时，徽标为只读状态，不显示下拉箭头。

创建新对象时必须在提交按钮附近再次显示目标范围。跨范围移动属于显式操作，需要说明原范围、目标范围和对关联数据的影响。

6.5 EmptyState

EmptyState 统一包含：

• 能说明状态的图标或简洁插图。
• 一句标题。
• 一至两句原因或下一步说明。
• 最多一个主操作和一个次操作。

必须区分：

状态	标题示例	操作原则
首次为空	“还没有知识条目”	提供创建或导入
筛选无结果	“没有符合条件的结果”	提供清除筛选
搜索无结果	“未找到相关内容”	建议修改关键词
加载失败	“内容加载失败”	提供重试并保留错误上下文
无权限或只读	“当前范围不可编辑”	说明原因和可行路径

空状态不得使用孤立的短句或仅显示图标。加载中不得先闪现空状态。

6.6 危险操作

共享危险操作样式包含：

• danger-ghost：列表行、菜单和工具栏中的删除入口。
• danger-solid：确认对话框中的最终危险操作。
• danger-zone：设置页中集中展示的高影响操作区域。

普通页面不得用实心红色按钮与主操作并列。危险入口必须使用具体动词和对象，例如“删除知识条目”，避免只写“确定”。

6.7 数据表格与活动列表

• 表头、单元格、空值、状态和行操作使用统一对齐规则。
• 文本默认左对齐，数值右对齐，状态与短标签可居中。
• 时间显示使用一致格式，并在需要时通过工具提示提供完整时间和时区。
• 行操作默认放在行末。高频安全操作可直接显示，低频或危险操作进入更多菜单。
• 活动记录必须保留操作者、动作、对象、范围、结果和时间等审计语义，不用纯图标代替关键字段。
• 表格密度可以选择“默认”或“紧凑”，但同一页面不得混用。

6.8 应用侧栏

主侧栏用于一级导航、最近会话和稳定的账户入口，必须通过表面、结构线和选中状态建立清楚但不过度装饰的层级。

• 浅色侧栏使用冰蓝灰表面，与白色主内容画布形成明确边界；深色侧栏使用比主画布略亮的蓝灰表面。
• 一级导航与最近会话之间、最近会话与底部账户区之间必须有可见结构分隔线。浅色主题使用 --border-default，深色主题可在可辨前提下使用 --border-subtle。
• 当前导航项和当前会话必须同时使用至少三种信号中的两种：强调背景、可见边框、图标或文字强调。浅色主题的当前项优先使用更完整的蓝色选中表面和较高字重。
• 未选中项保持平整，不为每一行添加卡片边框或阴影。悬停反馈不得强于选中状态。
• 桌面停靠状态下，主侧栏宽度允许在 220px 至 420px 范围内通过指针或键盘调整， 并记住用户选择；分隔条使用 separator 语义，支持方向键、Home 和 End。小于 900px 时继续使用固定宽度抽屉，不显示拖拽分隔条。
• 关联 Task 的 Conversation 在行最左侧显示独立展开按钮，父会话行不重复任务标签或数量； 展开后的每个 Task 子项左侧显示名称，模式、计划和共享状态标记收在右侧，与父会话的 更新时间位置一致；展开层级只到 Task，不展示 Job、Subjob 或 Run。
• 会话标题保持单行且不挤压更新时间。更新时间默认靠近行右侧；低频的更多操作按钮不常驻 占位，只在悬停会话行时替换右侧时间显示。键盘焦点进入会话行或操作菜单展开时，按钮仍 保持可见。标题实际溢出时，悬停会话行才在标题的固定裁切区域内平滑横向滑动以展示完整 名称；移开后快速复位。未溢出标题不产生位移动效，prefers-reduced-motion 下禁用滑动 并保留完整标题提示。
• 分支会话在侧栏标题前和聊天顶栏标题旁显示同一个横向分叉徽标；徽标通过可访问名称和 工具提示说明来源会话，不能只靠图形表达。分支不改成树状会话列表，也不挤压更新时间。
• 新建 Task 后可以首次自动展开所属 Conversation；用户手动折叠后保持其选择，后台状态变化 只更新状态提示，不强制展开或抢占焦点。
• Task 子项右侧复用任务中心的共享状态标记：运行中使用脉冲强调色，已完成使用带勾成功点， 失败或中断使用危险色，等待审批使用警告色，暂停或取消使用禁用色；非完成态旁边同时 显示本地化状态文字，已完成文案保留给辅助技术而不在紧凑元数据中重复显示，不能只靠 颜色或动效表达状态。
• 左上角品牌区允许用户在“外观”设置中定制品牌名称、中英文副标题和单个 Logo。定制只 影响该品牌区，不替换安装包名称、更新协议、Agent 标识或应用正文中的 GoodBuddy 产品 身份。副标题按当前界面语言显示，留空时隐藏且不保留空行。
• 品牌设置必须提供同布局预览、显式保存、默认 Logo 和整组恢复默认操作。自定义 Logo 仅 接受用户本机选择的 PNG、JPEG 或 WebP 内联数据，宽高不超过 4096 × 4096、总像素不 超过 1600 万且大小不超过 512 KB；不得读取远程 Logo URL。名称或副标题溢出品牌区时 单行截断，不能撑宽或挤压侧栏。
• 侧栏底部固定显示文件、终端、浏览器和资源监控四个系统工具图标，设置按钮独立靠右。工具 图标只负责打开或聚焦助手工作栏面板，不在侧栏复制工具内容。已有稳定设置入口时，不在顶栏 重复提供同一入口。

6.9 助手工作栏

助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime 自动增删入口。产品契约见 通用助手工作栏与执行空间 PRD， 动态 Tab、“+”和终端细节见 助手工作栏多终端页签 PRD。

• 升级后默认打开任务中心、工作区、浏览器和成果四个单实例应用，不根据当前页面或 Runtime 能力自动增删稳定应用目录入口。
• 资源监控作为本机单实例应用保留在能力目录，但不加入升级后的默认打开实例。面板只在可见 活动时采样，首期不持久化历史或提供后台负载告警。
• Tab 行只显示已打开实例，行末始终提供“+”普通按钮；点击后在内容区打开应用选择页。 “+”不使用 tab 语义，也不能因为终端或其他应用已经打开而消失。
• 应用注册表声明单实例或多实例。在工作栏“+”目录中，单实例重复选择时聚焦已有 Tab；终端 从首期开始支持多实例，每次选择创建独立 Tab 和 Shell Session。主侧栏系统工具快捷入口 可以聚焦当前执行空间中最近使用的终端，额外终端仍从“+”目录创建。
• Task Center 是 Task 的单例应用级索引，不使用“跟随 / 固定目标”多实例模式。每个 Task 只关联一条 Conversation，一条 Conversation 可以关联多个 Task；列表不得复制会话内容， 也不得把 Job/Run 提升为可导航 UI 对象。
• 各栏目读取当前会话或项目的对应内容；当前内容不可用时仍保留栏目入口并说明原因。
• 能力、连接和内容可以动态变化，栏目入口不能随之自动隐藏。不可用状态必须说明原因、影响和可执行入口。
• 用户可以主动排序或隐藏栏目，并可恢复默认布局；应用不能用用户偏好机制实现自动能力裁剪。
• 已打开实例保留 tablist、tab、tabpanel、方向键、Home、End 和焦点恢复语义。 实例过多时 Tab 区单行横向滚动，“+”保持可见，不换行或改成下拉框。
• 当前工作栏 Tab 必须同时使用连续内容表面、可见边框、顶部指示、图标或较高字重中的至少 两种信号；悬停反馈不得强于当前选中态。Tab 关闭按钮保留固定布局空间，默认仅在对应 Tab 悬停或 focus-within 时显示；无悬停或粗指针设备始终显示，键盘与辅助技术始终可访问。
• 工作栏 Tab、Tab 关闭按钮和“+”入口沿用共享控件圆角；终端面板外框及终端顶部工具栏按钮 使用直角，形成紧凑的停靠式终端界面。
• 选择“终端”后直接绑定当前项目，由项目执行空间自动决定本机或托管 SSH；不再显示第二层 目标选择器。终端面板内部不重复提供关闭会话按钮，关闭统一由 Tab 入口完成。
• 下一次请求使用的附件和知识库由会话输入区展示与管理，不在工作栏重复提供“上下文”栏目； 记忆功能实现前不展示占位内容，未来的记忆与历史执行上下文归入关联 Task 的任务中心详情。
• 徽标可以提示未解决意见、等待审批、失败或连接状态，但不能成为唯一状态信号，也不能无条件抢占当前栏目。
• 浏览器 Tab 的内容顶部固定使用一条紧凑工具栏，按“返回、刷新/停止加载、地址输入、 前往、交互、关闭浏览器”排列。“刷新”在当前页面加载时原位切换为“停止加载”； “关闭浏览器”必须使用明确文字和与页面导航控件清楚区分的危险操作视觉，不能继续标为 含义模糊的“停止浏览器”。地址输入显示浏览器权威提交 URL，但用户编辑期间保留本地草稿， 不被画面或状态刷新覆盖；提交裸域名时自动添加 http://，提交、失焦后的同步规则不得让 尚未提交的文字改变 Agent 看到的页面。
• 浏览器工具栏操作的是当前 Conversation 中 Agent 使用的同一隔离浏览器会话，用户导航会 有意改变 Agent 下一步看到的页面。创建中、Agent 操作中或已进入完整交互窗口时禁用其余 工具栏控件；仅当前导航仍在加载时保留“停止加载”，且该操作只中止页面加载，不关闭浏览器、 不释放 Runtime 上下文。没有会话的活动 Conversation 可以直接在地址栏输入 URL 并“前往” 创建会话，但必须复用 Agent 浏览器相同的 URL 策略与能力路径。
• 所有窗口宽度下均停靠在主工作区右侧并参与水平布局回流；展开时压缩主工作区，不能覆盖、 遮罩或隔离其内容。分栏计算排除最左侧主导航，主工作区与工作栏采用相同的 300px 最小宽度；拖动保存两者在可用分栏宽度中的比例，任一侧到达最小值后都不得继续侵占。 所有可容纳两侧最小值的尺寸均支持指针和键盘调整，并须保留全部栏目入口。
• 工作栏开关固定在窗口关闭按钮正下方，同一个按钮负责展开与收起并持续暴露状态；图标中的 箭头方向必须随当前动作切换，收起状态提示展开，展开状态提示收起。按钮保持普通图标按钮 视觉，不通过持续高亮表达展开状态。工作栏内部不再重复关闭按钮；当前会话没有 Task 时， 不得为了放置该开关而保留一条空上下文栏。
• 停靠工作栏不得获得对话框语义、焦点陷阱或背景遮罩。关闭后焦点返回同一个工作栏开关； 主工作区与工作栏在展开期间都保持可达。
• 对话消息流、输入区和输入区元信息必须在主工作区内部保留对称的左右安全边距。工作栏 分割线只能位于主工作区边界之外，不能覆盖、裁切或挤掉输入框边框、发送按钮或右侧边距。
• 终端、宽日志和大型成果可以由用户切换到底部停靠或独立窗口，应用不得因内容变化自动改变用户已选布局。

6.10 应用顶栏与全局操作

应用顶栏用于当前会话标题、范围、窗口级状态、侧栏开关和低频全局操作，不承担主要导航。 顶栏必须保持紧凑，不能与页面内容争夺注意力。

• 应用壳层在水平方向分为全高主侧栏和右侧内容框架。主侧栏从窗口顶部贯穿到底部，品牌区、 项目切换器、导航和账户区保持同一连续表面；不能用全宽标题栏把整条侧栏向下推移。
• 无边框窗口的紧凑标题栏只覆盖右侧内容框架，保留侧栏开关、当前会话标题、范围、Runtime 状态、主题开关和窗口控制，不得为了新增工作栏入口把这一整组控件下移。普通图标按钮使用 34px × 34px 点击区域。
• 发布说明 Modal 与其他应用级 Modal 一样使用整窗遮罩；遮罩必须覆盖主侧栏、右侧内容和 顶栏，不能保留一条未被遮罩的窗口控制色块。关闭操作由 Modal 自身提供。
• 当前会话存在 Task 时，Task 上下文栏位于标题栏下方并承载任务摘要与详情；没有 Task 时 整行隐藏。折叠状态保持为 46px 单行表面，与右侧工作栏标签栏等高，左右分隔线必须水平 对齐。该栏不重复放置新建入口。
• “新建任务”只位于工作栏“任务索引”标题后方；任务状态筛选占满工作栏可用宽度，四个选项 等分，不能保留内容宽度的短控件。
• Runtime 状态、同步状态等短标签使用 --font-caption，不得放大为正文标题。顶栏 Runtime 状态由状态点和 Runtime/模型名称紧凑表达：就绪使用绿色，连接中使用黄色，不可用使用灰色， 不再重复显示状态文字；完整状态详情继续通过可访问说明和工具提示提供。
• 浅色与深色切换属于持续可用的窗口级操作，直接显示太阳或月亮图标，并通过可访问名称说明将切换到的主题。选择必须持久化，切换不得改变布局。
• 顶栏只直接显示当前任务所需的高频操作。已有侧栏账户设置入口时，不再重复显示 Runtime/设置入口；使用帮助优先放在相关操作附近，而不是为单个帮助项创建“更多”菜单。
• 助手工作栏开关固定在上下文栏最右侧并与窗口关闭按钮纵向对齐；展开后该开关保持原位并 负责收起，不在工作栏标题区域增加第二个关闭入口。
• 只有存在至少两个无法由稳定入口承载的低频全局操作时才增加全局菜单，不为了容纳一个冗余入口而显示省略号按钮。
• 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。
• 使用全局菜单时，菜单项使用 --font-body、14px 图标和约 32px 单项高度；标签使用短名称。菜单保留 menu、menuitem 语义，支持上下方向键、Home、End 和 Escape，关闭后焦点返回触发按钮。

6.11 单选选择器

模型、专家角色、工作模式、Runtime Agent、Runtime 预设和 Runtime 快捷操作属于同一输入上下文，其选择器必须共享结构、尺寸和菜单视觉，不能出现一个精细菜单与多个风格不一致的原生下拉框。

• 只有选项能由单行短标签充分区分、不需要补充来源、位置、状态或说明时，才使用原生 select。
• 当用户必须在选择前比较来源、范围、位置、连接状态或其他辅助信息时，使用与输入区选择器同类的自定义富信息单选菜单，不用 CSS 修饰原生 select 冒充富信息菜单。
• 触发按钮复用统一的模型选择按钮样式，保持相同高度、圆角、边框、展开指示和焦点状态。
• 菜单使用 menu 与 menuitemradio 语义，当前项同时显示选中标记和 aria-checked。选项可以包含一行简短说明，但标签和说明不得被截断到无法区分。
• 支持上、下方向键、Home、End、Enter 或 Space、Escape；打开后焦点进入当前项，关闭后返回触发按钮。
• 点击或聚焦菜单外部时关闭；同一输入区内的模型、专家和模式菜单互斥展开。
• 不可用选项保持可读并说明原因，键盘导航不得停留在不可选择项上。
• 当某个选项需要用户在其展开区域内完成路径选择、授权或其他前置操作时，不得因为前置条件 尚未完成而禁用该入口。选择入口只展开流程，验证成功前不提交实际值；不得自动采用第一个 候选。取消保持原值，验证错误在对应操作附近显示。
• 项目选择器属于富信息单选菜单。收起时保持当前项目名称紧凑可见；展开后每项至少显示项目名称，并按数据可用性补充目录、远程来源或其他能帮助辨认项目的信息。托管 SSH 项目在“远程项目”内按已保存 SSH Host 做一层轻量分组，Host 标题旁显示真实 Agent 连接状态；项目副标题只显示远端路径，不重复“托管 SSH”类型。
• 项目菜单区分“本地项目 / 远程项目 / 远程通道”，不把消息通道命名为远程项目。“远程项目（技术预览）”关闭时完整移除远程项目分组，而不是显示不可操作的残留选项；本地项目和远程通道继续可用。Agent 连接状态使用“未连接 / 连接中 / 就绪 / 异常”等文字标签，读取状态不得发起连接，且不能只依赖图标或颜色；新增项目来源时不得退回仅列名称的原生 select。

6.12 应用通知与就地反馈

应用级通知统一进入全局通知视口，页面不得自行复制通知卡片或在内容流中长期堆放短期消息。

• 异步操作成功、无需立即处理的信息，以及不属于某个字段的异步失败，使用应用级 success、info 或 error 通知。
• 成功和信息通知默认在约 4.5 秒后自动消失；错误通知保持可见，直到用户关闭或同一去重键的更新替换它。
• 同一语义和文案的重复通知应去重。通知正文必须有长度上限，不包含凭据、私人内容或未脱敏的提供商响应。
• 字段校验、破坏性确认、操作进度、阻塞整个页面的状态，以及需要就地重试或修正的错误保留在相关控件附近。
• 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 alert 和 assertive 实时区域，成功与信息使用 status 和 polite 实时区域。
• 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。

6.13 Switch 与 Checkbox

Switch 用于在两个持久状态之间立即切换，例如启用能力、开启索引、允许群消息或显示平台入口。Checkbox 用于独立多选、范围分配或执行前确认，例如选择多个 Runtime、选择知识库、清除已保存密钥。两者不得只因底层都使用 input[type="checkbox"] 而混用视觉或语义。

• 二元启停必须使用共享滑动开关视觉，当前实现复用 toggle-row，不得显示为原生方形 Checkbox。
• Switch 底层可以使用 input[type="checkbox"]，但必须声明 role="switch"，通过原生 checked 状态暴露开关状态，并具有持久、明确的可访问名称。
• Checkbox 保留原生 Checkbox 语义和方形勾选视觉，不得添加 role="switch"。多项分配、列表选择、确认声明和“保存时清除密钥”等一次性选择均属于 Checkbox。
• 不创建页面专属 Switch 样式。需要紧凑布局时仍复用同一轨道、滑块、焦点环、禁用状态和动效，只调整共享组件支持的布局变体。
• Switch 支持 Tab 聚焦和 Space 切换，键盘焦点至少显示 2px 高对比焦点环。可见标签应描述被控制的能力，不能只显示“开 / 关”。
• 异步切换期间禁用重复操作并保留原状态。失败时恢复或保留最后确认状态，通过应用通知或就地可恢复错误说明原因。
• 涉及联网、上传、电脑控制或其他外部影响的 Switch，附近必须持续说明数据去向、权限范围或风险，不能只靠设置名称表达影响。
• 自动化测试应按 switch 角色查询二元开关，按 checkbox 角色查询多选或确认项，防止视觉迁移后语义回退。

7. 交互状态

所有可交互组件必须实现：

• 默认：文本、边框和背景层级清晰。
• 悬停：提供轻量背景或边框反馈，不改变布局。
• 按下：反馈比悬停更强，持续时间使用 --motion-fast。
• 键盘焦点：显示至少 2px 的高对比焦点环，不被容器裁切。
• 选中：同时使用背景、边框、图标或字重中的至少两种信号。
• 禁用：降低强调度，同时保留可读标签，并通过说明或工具提示解释原因。
• 加载：防止重复提交，保留原按钮宽度并显示进行中标签。
• 错误：字段或局部操作错误就近显示可执行说明；非局部异步错误使用不会自动消失的应用级错误通知。

异步提交成功后更新内容并通过统一应用通知提供明确反馈。失败时保留用户输入和筛选上下文。

8. 范围与数据语义

8.1 页面范围

• 页面范围决定当前列表、搜索、创建和批量操作针对的数据集合。
• 页面标题区必须持续显示当前范围。
• 搜索框占位文案应反映范围，例如“搜索当前项目的知识”。
• 切换范围后清理不再有效的选择项，并明确提示数据集合已变化。

8.2 对象范围

• 详情页或主从布局的右侧面板显示所选对象自身的范围。
• 当页面范围与对象范围不一致时，必须显示解释，不得静默混合。
• 全局对象可被项目引用时，应分别表达“归属范围”和“当前引用关系”。

8.3 操作范围

批量操作、导入、删除、移动和自动化运行前，界面必须明确：

1. 将影响哪些对象。
2. 对象属于全局还是某个项目。
3. 操作是否可撤销。
4. 是否影响关联任务、知识引用或历史记录。

9. 破坏性操作政策

9.1 风险等级

等级	示例	要求
低	移除可立即恢复的筛选、取消未保存草稿	通常无需确认，必要时提供撤销
中	删除单个可恢复对象、停止正在运行的任务	显式确认或操作后撤销，说明直接影响
高	永久删除、批量删除、清空历史、删除被引用对象	必须使用确认对话框，说明范围、数量和不可逆性

9.2 确认对话框

• 标题包含具体动作和对象，例如“永久删除 12 条活动记录？”
• 正文说明范围、关联影响和恢复可能性。
• 取消按钮在前，危险按钮在后。初始焦点放在取消按钮。
• 最终按钮使用 danger-solid，标签重复具体动作。
• 仅对高影响且不可恢复的操作要求输入对象名称或确认短语，避免把摩擦用于所有删除。
• 提交期间锁定重复操作。失败后保持对话框打开并显示可处理的错误信息。

9.3 撤销与反馈

• 可恢复删除优先在操作后显示带“撤销”的持久通知。
• 撤销窗口结束前，不把操作描述为“永久删除”。
• 删除成功后更新列表、选中项和计数。主从布局中被删除对象的详情面板应回到明确的未选择状态。
• 审计记录不得因普通对象删除而被静默移除。

10. 深色主题

• 深色主题通过语义令牌替换实现，不在组件中使用主题条件分支选择原始颜色。
• 主画布使用深海军蓝，侧栏、顶栏、输入区和浮层使用逐级提亮的蓝灰表面；表面层级主要依靠亮度和边框区分，避免大面积纯黑与高亮白形成刺眼对比。
• 深色强调色使用明亮但不荧光的蓝色，成功状态使用青绿色。用户消息等大面积强调表面使用更深的实心蓝，确保反白文字舒适可读。
• 输入框、代码块、表格悬停、选中行、弹窗遮罩和滚动条必须分别检查深色值。
• 图片、图表和状态色在深色背景下保持可读。图表系列不能只靠色相区分，还应使用形状、线型或标签。
• 焦点环、危险文本和弱文本在两种主题下都满足对比度要求。
• 原生控件和滚动条声明正确的 color-scheme。
• 主题切换不得导致布局、边框宽度或字号变化。

11. 无障碍

11.1 键盘与焦点

• 所有交互均可通过键盘完成。
• 焦点顺序与视觉顺序一致，打开弹窗后焦点进入弹窗，关闭后返回触发元素。
• 页面导航链接按正常 Tab 顺序操作。同页签组和单选组使用方向键，菜单使用上下方向键和 Escape。
• 不给不可交互容器添加焦点，不用 div 模拟按钮而缺少按钮语义。

11.2 语义与标签

• 图标按钮必须有可访问名称，并在视觉上提供工具提示。
• 表单控件有持久标签，不能只使用占位文案。
• 状态变化使用适当的实时区域，但避免对频繁日志逐条播报。
• 错误信息与对应字段建立程序化关联。
• 表格使用正确的表头关系，复杂审计记录在窄屏下仍保持字段标签。

11.3 对比度与触控目标

• 正文与背景对比度至少为 4.5:1，大号文本至少为 3:1。
• 控件边界、焦点和关键图形对比度至少为 3:1。
• 常规交互目标建议至少 32px × 32px。紧凑表格可使用 28px 高度，但相邻目标之间必须有足够间隔。
• 文字缩放至 200% 时，核心操作、范围信息和错误提示不能被裁切。

12. 响应式与窗口规则

GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证任务连续性，不简单隐藏信息。

12.1 宽窗口，1200px 及以上

• 使用各 PageShell 的完整最大宽度。
• dashboard 可使用 3 至 4 列卡片。
• master-detail 保持双栏，详情区获得主要空间。

12.2 中等窗口，960px 至 1199px

• 页面左右内边距为 24px。
• 仪表盘降为 2 列。
• 主从布局缩小左栏，但不得低于 280px。
• 表格优先收起低优先级列到详情或行展开区，不隐藏范围、状态和时间。

12.3 窄窗口，720px 至 959px

• PageHeader 的操作区换行。
• master-detail 变为单面板导航。进入详情后提供明确返回列表的按钮。
• 仪表盘使用单列或 2 列，取决于卡片最小宽度。
• PageTabs 可单行横向滚动，不换成下拉菜单。
• 宽表格在自身容器内横向滚动，并固定关键标识列时确保键盘可达。

12.4 极窄窗口，小于 720px

• 页面左右内边距为 16px。
• 标题、范围徽标和操作纵向排列，但范围不得隐藏。
• 主操作可以占满可用宽度，次操作进入更多菜单。
• 分段控件可等分整行，筛选工具栏改为可展开区域。
• 聊天输入区保持可见，并考虑窗口安全边距。
• 对话框使用接近全宽的布局，仍保留 16px 外边距。

13. 页面应用规范

13.1 聊天

• 使用 reading 壳层，消息流与输入区共享宽度。
• 对话标题和当前项目范围位于 PageHeader 或对话上下文区，不在消息流中重复。
• 已结束且包含正文的助手回复在底部提供带可访问名称和工具提示的复制图标；复制 Markdown 原文，不包含推理过程、工具日志或引用元数据，结果通过应用通知反馈。流式回复完成前不显示 复制入口。
• 默认开启“会话 HTML 渲染”时，已完成 Agent 回复中的完整 HTML 与 html / htm 代码块在原位置显示隔离静态预览；用户消息、推理过程和流式中的回复不得执行 HTML。 每个预览持续标注脚本和网络已禁用，并在标题右侧复用与 Mermaid 图表相同的图标按钮组： 源码按钮使用代码图标并暴露 aria-expanded，全屏按钮使用放大图标打开统一 Modal。 全屏预览遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape 关闭和焦点恢复规则， 并沿用同一套清理与 Sandbox/CSP 边界。关闭平台功能后必须显示 HTML 源码，不能隐藏内容 或保留旧预览。
• 本地会话的更多操作提供“在新会话中继续”。创建前必须先持久化当前稳定消息；有活动运行 或待发送内容时不可创建。新会话复制聊天内容与当前 Runtime/知识检索选择，重置压缩状态， 使用新的会话和消息 ID，且不复制 Task、队列、运行、记忆或成果归属。
• 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
• 模型、专家角色、工作模式、OpenCode Agent、Continue 预设和 Runtime 快捷操作使用统一的上下文单选菜单，并保持菜单互斥、键盘可达和选中状态明确。
• Runtime 选择菜单必须反映当前执行空间的真实能力。托管 SSH 项目当前只支持 OpenCode，因此输入区只渲染已配置的 OpenCode 选项和管理入口，不显示直连模型、Continue 或 DeepSeek Harness 的不可用入口；旧会话保存的其他 Runtime 选择在项目激活时恢复为当前 OpenCode 配置。
• 输入区第一行工具栏只承载附件、语音、知识范围、专家角色、工作模式、Runtime 选择和发送等通用操作。OpenCode Agent、Continue 预设及 Runtime 快捷操作必须放入其下方独立的 Runtime 专属功能行，通过可见分组名称、顶部边界和差异化表面与通用操作分层；该行只承载对当前消息生效的高频选择，当前 Runtime 没有可选专属功能时不保留空行。
• OpenCode、Continue 和 DeepSeek Harness 后续的 Task 级委派与取消、后台执行进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止及原生会话监督统一进入应用级助手工作栏固定的“Runtime”栏目，不加入 Composer。栏目入口始终存在；只选择 Conversation 或 Task，并按 Task 聚合执行状态，不显示 Job/Run 树或独立操作菜单。内部可选区域按用户所选目标和 Runtime 的真实能力显示，不为未支持能力渲染空卡片或成排禁用按钮。切换跟随目标时必须清理上一归属的监督状态，固定目标则保持不变。
• 设置中心只管理持久 Runtime 配置、默认值和能力清单；右侧 Runtime 栏目管理用户当前跟随或固定目标的生命周期。两处不得复制同一实时操作，栏目中的高风险操作仍须就地确认并保留取消、权限、用量和活动审计。
• Runtime Prompt 快捷操作只把模板填入输入草稿，用户可以继续编辑；OpenCode Command 由 Runtime 原生 API 执行，输入框只承载可选参数，不以普通斜杠文本冒充执行。
• OpenCode 原生 Task 调用在本地项目和托管 SSH 项目中统一解析为子 Agent 状态卡，不显示为普通工具卡。状态卡持续显示 Agent 类型、任务说明、运行状态、完成输出或失败原因；身份徽标、Agent 名称和状态位于首层，任务说明作为主信息，Runtime 来源作为次级元数据，输出与错误在同一卡片内按需展开。父 Agent 的推理不冒充子 Agent 过程，必须与状态卡保持明确间距。状态不能只靠颜色表达。推理、子 Agent、工具和正文统一按事件首次出现顺序进入消息块；增量更新只更新原位置，Task 临时工具块重分类后必须原位替换，不能把子 Agent 卡统一提升到消息顶部。同一调用的增量事件按稳定调用 ID 更新，不能因 ACP 首帧尚无参数而永久保留重复工具卡或活动记录。一次请求内已观察到的子 Agent 均保留在消息与活动记录中；父请求取消、失败或意外中断时仍处于活动状态的卡片必须结算为对应终态，父请求成功结束但子 Agent 未报告终态时必须显示为失败而不是推断为完成。
• Agent 回复进行中锁定模型、专家角色、工作模式和 Runtime 定制选择器，并关闭已打开的上下文菜单；回复结束或停止后再恢复选择，避免界面状态与本次运行实际使用的上下文不一致。
• Agent 回复进行中不能禁用普通消息发送。新消息与到期 Scheduled Task 共用 Conversation 级待发送队列。队列位于 Composer 容器之外、与输入框等宽并保持独立间距；有待发送项时直接显示无标题栏的极简列表，空队列不保留占位。每项固定为一行，按进入顺序显示轻量来源图标和截断摘要；普通消息使用消息图标，Scheduled Task 统一使用淡出时钟图标。
• 待发送项默认在当前回复结束后顺序执行。每项提供明确的“立即中断并插入”（空闲时为“立即运行”）和删除操作；前者先取消当前 Conversation 的活动执行，再将所选项提升为下一项，不允许同一 Conversation 并发写入时间线。
• 队列区域向上增长并设置有界滚动高度，不提供展开、收起或冗余计数标题。宽容器中的操作采用弱化的行内样式，不渲染成强调卡片或胶囊；窄容器中保留来源、摘要和图标操作并隐藏冗长按钮文字。区域、来源和每个操作必须有可读无障碍名称。队列异步错误进入应用通知，不在 Composer 内复制通知样式。
• 支持上下文状态的 Runtime 在输入区下方复用同一紧凑用量条；文案必须区分“本次模型调用”和“压缩后对话估算”。手动压缩仅在当前 Runtime 明确支持且没有活动回复时显示，作为元信息区左下角的浮动次操作，不参与输入区高度计算；元信息区始终预留稳定高度，切换 Runtime 不得让输入框上下位移。元信息区与窗口底部只保留紧凑安全留白，不形成额外空白区。进行中禁用重复操作，结果通过应用通知反馈。
• 已选择的工作模式在触发按钮中只显示 Ask 或 Execute；完整中文含义和说明保留在菜单选项、可访问名称及输入区下方的模式说明中。
• 宽度大于 700px 时，通用工具栏内的添加内容、知识范围、专家、模式和 Runtime 选择保持同一行，Runtime 专属功能在自己的下一行横向排列。窄输入区中两行分别换行，专属选择器以至少 220px 的基准宽度换行而不是被挤压；不能把专属控件重新塞回通用工具栏。
• 输入框原生支持 Ctrl+V：文本直接进入草稿，图片转换为本次消息附件。文件选择由上传按钮承担，不再提供独立“读取剪贴板”按钮；默认工具栏也不提供“截取当前屏幕”和“选择应用窗口”入口，避免与系统粘贴、文件选择和后续工具执行重复。
• “Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴图片或文本”等输入操作提示放在空输入框内部，作为主占位文案的次级行；不得在输入框下方单独占用第二行。输入框下方只保留一行当前模式、安全边界或全局快捷键说明。
• 输入操作提示不能替代表单的可访问名称，输入框始终保留持久的程序化标签。
• 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
• 消息流的滚动范围必须使用已渲染消息的真实高度。长会话可以按批次只挂载最近消息并由用户 加载更早内容，但不得用固定的消息占位高度替代实际布局，避免推理、工具列表或长正文被 排除在可滚动范围之外。

13.2 最近对话

• 使用 standard 壳层和统一 PageHeader。
• 搜索、范围和时间筛选位于筛选工具栏。
• 行项目统一显示标题、范围、最近更新时间和必要状态。
• 侧栏最近会话的更新时间在当天显示本地时间，非当天显示本地日期；非当年记录必须同时显示年份。悬停时间信息时提供完整日期和时间。
• 侧栏中有关联 Task 的 Conversation 显示行首展开按钮，父行不显示任务标签或数量；展开后 最多直接显示 3 个 Task，“查看全部 N 个任务”打开该 Conversation 的完整任务区。
• Task 子项左侧显示名称，右侧显示本地化的 Ask/Execute、计划摘要和共享状态标记，与父会话 的更新时间位置一致；已完成使用带勾成功点，不重复显示完成文字。点击子项打开同一 Conversation 并定位 Task，不继续展开 Job/Run。
• 删除入口使用 danger-ghost，并按数据可恢复性执行确认或撤销策略。

13.3 知识库

• 使用 master-detail 壳层。
• 左侧负责范围、搜索、筛选和条目选择，右侧负责详情、编辑和预览。
• 两侧均只使用语义颜色令牌，禁止内联浅色背景或边框。
• 选中条目后持续显示对象范围。没有选中项与知识库为空必须使用不同状态。
• 窄窗口切换为单面板导航，不把双栏压缩到不可读。

13.4 智能心跳

• 使用 dashboard 壳层。
• 顶部先呈现运行状态、实际范围和主操作，再呈现指标、建议、历史与配置。
• 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用 Checkbox，不能依靠进入页面时的当前项目推断。
• 状态卡片使用统一状态令牌，不只依赖颜色。
• 保留“运行概览 / 待处理建议 / 报告与记录 / 心跳计划”四个同级页面。
• 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。
• 分区记忆协同与唤起条件尚未实现，不得显示占位入口或平行的记忆类型。

13.5 Task Center

• 保留现有助手工作栏入口，首期在窄栏内适度完善，不先扩张成新的独立一级页面。
• 只展示 Task；普通 Conversation、Job、Run、工具步骤、Subagent 和心跳事项不独立占行。
• 每项显示名称、关联 Conversation、Global 或 Project 范围、Ask/Execute、状态、最近进展、 最近真实活动时间及需要关注信息。
• 点击列表项打开关联 Conversation 并定位该 Task，不显示第二份内容载体。
• 需要关注、进行中、已暂停和已结束使用共享 SegmentedControl；窄栏不足时单行滚动。
• 完整消息留在 Conversation；长错误、工具、审批和成果按 Task 关联到 Runtime、活动记录和 成果查看器，不撑高列表，也不显示 Job/Run 树。
• “新建定制任务”使用共享 Modal，明确选择当前或新 Conversation。聊天入口默认当前 Conversation，Task Center 入口默认新 Conversation；选择必须持续可见。
• 创建 Modal 默认 Execute，并允许主动切换 Ask。Execute 持续显示实际 Runtime、Project、 工作目录、工具和审批摘要；不支持工具时不得静默降级。

13.6 运行记录

• 使用 dashboard 壳层，并通过 PageTabs 提供“任务与会话 / 活动时间线 / 用量统计”三个同级视图。
• 默认视图按“项目 → 任务或会话 → 活动详情”组织，项目范围持续可见，任务或会话详情可以折叠。
• 任务或会话的综合状态以最近一次顶层请求对应的最终 Agent 结果为准；最终结果尚未产生时使用该请求的当前状态。中间工具或子专家的失败、取消和中断保留在活动详情中，但不得覆盖最终成功状态。
• 活动时间线按项目分组、按任务或会话建立横向轨道，所有轨道共享同一执行顺序并按事件时间排列，以带身份名称的节点表达用户、主 Agent、子专家、工具、审批、状态和并行关系。节点内使用 U / G / S / T / A 拉丁字母简称，节点下显示完整身份或名称；选择节点后显示所属会话、不可变范围快照和完整详情。
• 用量统计与活动记录分离，支持按项目、会话和模型切换统计维度，宽表格在独立容器内横向滚动。
• 活动状态筛选使用 SegmentedControl，不与页面页签混合。清空历史遵循破坏性操作政策。

13.7 魔法笔记

• “笔记 / 待办”属于同一工作台内的同级内容面板，使用 PageTabs 的 segmented 视觉变体，与模型设置的分段控件保持同一外观。
• 页签切换保留 tablist、tab 和 tabpanel 语义；待办状态仍使用独立的 SegmentedControl，不得与内容页签合并。
• 笔记编辑器保留 Quill 原生列表快捷输入：输入 -、*、1.、[ ] 或 [x] 后按空格，分别转换为项目符号、编号或待办清单。快捷输入只生成现有 Delta 富文本，不引入 Markdown 源码模式、第二套持久化格式或第三方 Markdown 插件；编辑区附近持续提供简短提示。
• 左侧笔记与待办列表在双栏布局中允许在 180px 至 360px 范围内通过指针或键盘调整， 也可从页面标题区隐藏和恢复；宽度与显示状态均记住用户选择。分隔条保留 separator 语义及方向键、Home、End 操作，窄窗口堆叠布局不显示拖拽分隔条。
• 左侧笔记列表依次显示标题、最多两行内容预览，以及同一行的记录数和本地化更新时间。记录数靠左、更新时间靠右，窄宽度下均保持单行省略，不挤压标题或扩大列表栏。
• 左侧“魔法笔记”入口可显示未完成待办数量。数量为 0 时隐藏徽标，超过 99 时显示 99+，可访问名称仍说明精确数量；勾选、取消勾选以及 Agent / MCP 对笔记清单的写入都必须刷新数量。
• 未完成待办徽标的高度不得超过主导航图标；数量从 0 变为可见或再次隐藏时，主导航项行高和相邻菜单位置必须保持不变。
• 在待办面板勾选或取消勾选后，当前缓存中的源笔记正文必须立即同步对应清单状态，不得依赖离开工作区后重新加载。
• 当前记录草稿非空时，切换笔记、待办或内容面板必须先在编辑器旁就地确认；继续编辑时保留草稿并恢复编辑焦点，只有明确选择放弃后才切换。
• 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。
• 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。

13.8 设置中心

• 全页设置使用固定标题区、左侧分类导航和独立滚动的内容区。右上角关闭按钮是离开设置中心的稳定入口。
• 左侧分类导航在宽屏使用 220px，中等窗口使用 196px，窄窗口转为横向滚动；纵向滚动条仅在内容溢出时占用右侧空间，不在左侧创建镜像预留，选项与左侧可见边界保持默认内距。分类标题使用正文级字号，分类说明使用辅助字号；右侧内容区在可用空间内流式伸缩，最大宽度使用 standard 壳层的 960px，不得以页面专属较窄宽度压缩表单。
• 全页设置标题区与双栏内容使用共享 --page-gutter，标题、分类导航和内容区在同一页面边距基线上；标题继续使用标准 PageHeader 的底部分隔线与下内距。固定标题和双独立滚动区域不改变这些一级页面壳层规则；模态设置保留自身外框与标题边界。
• 设置中心不显示全局操作页脚，避免重复关闭入口和没有功能意义的整宽分隔线。
• 所有分类使用共享的 SettingsCategoryHeader 呈现分类标题、说明、错误与操作，不得在内容卡片内复制分类标题或创建页面专属操作栏。左侧分类名称与说明来自同一份分类定义，新增分类时不得分别维护导航和内容标题。
• 当前分类存在“保存”或“测试”等未提交配置操作时，统一放在分类页头右侧；主保存操作在最右侧，测试等次操作排列在其左侧。
• 自动生效、仅执行即时命令或自行管理编辑流程的分类不显示全局保存操作。窄窗口下操作区可以换行，但保存入口必须保持清晰可见。
• 智能心跳的单条配置不在设置中心重复管理。设置中心如需呈现平台级说明，只提供 “打开智能心跳”导航，不复制创建、暂停、恢复或删除表单。
• 保存或测试成功统一进入应用通知视口，并按全局规则自动消失，不在分类页头或内容卡片中保留持久成功文案。加载、保存和测试错误显示在分类页头下方，并保留可处理的上下文。
• “模型连接”的认证字段按“认证方式 → API Key → 凭据状态”排列；只有选择 API Key 时显示输入框。已保存的 API Key 属于该连接，修改模型服务地址或临时选择“无需认证”不得自动清除，也不得要求重新输入；仅由明确的“清除凭据”或“删除连接”操作移除。
• “保存并测试模型”必须在保存后发送一次有界的真实模型请求。文本连接校验本次随机测试文本，图像连接校验实际返回的内联图片；仅收到成功 HTTP 状态、模型列表或健康检查响应不算测试成功。界面持续说明该操作可能产生少量服务商用量费用，成功反馈明确写为“真实生成测试通过”。
• 所有显式保存的设置草稿都参与离开保护：关闭、切换分类、主侧栏或工作区导航及托盘导航不得静默丢弃，统一通过设置中心的就地确认提供继续编辑与明确放弃入口，保存失败后保留输入。“平台功能 / 通用设置”承载全局快捷唤起的共享 Switch、可访问 accelerator 录制输入、恢复默认、保存及注册、停用或冲突状态，不新增分类或页签；注册或持久化失败时保留上一组可用快捷键和当前草稿，保存或停用成功后同步更新输入区的快捷键提示。
• “平台功能 / 通用设置”同时提供默认开启的“在会话中渲染 HTML”持久 Switch。说明必须 明确该能力只生成禁用脚本、联网、表单提交和窗口操作的静态预览；保存成功后当前会话立即 更新，保存失败时保留最后确认状态。
• “平台功能”使用共享 PageTabs 区分“通用设置”“远程项目（技术预览）”和“魔法笔记”，默认进入通用设置。“远程项目”页将持久 Switch 与用户数据目录中的 Linux x64、Linux arm64、macOS arm64 Agent 包清单分成独立卡片；每张卡片与下载进度按平台和架构区分，不能把两个 arm64 目标合并。清单延迟到首次打开该页签时由 Main 完整校验，并读取所选更新源的小型签名目录，显示本地版本、在线最新兼容版本以及“有更新”“已是最新”“未下载”“校验失败”。打开页签或刷新不得自动下载 .gbagent；只有用户点击带目标版本的下载/更新按钮后才传输包。签名目录不可用时继续显示并允许导出已验证本地包，提供就地重试错误；清单不混入 Host 已安装状态、缓存路径或敏感签名细节。下载和导入期间保留上下文进度，成功进入全局通知视口。“魔法笔记”页提供默认开启的“显示未完成待办数量”持久 Switch，关闭后只隐藏左侧数量徽标，不改变待办数据或魔法笔记入口。全局模型下载源使用 fieldset、持久 legend 与整行可点击的原生 Radio 卡片；选中状态同时依靠 Radio、边框和背景表达，读取失败时不得用默认值伪装为已保存选择。
• “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、原生单选下拉框和用途说明放在同一行，并复用设置表单的统一控件样式；关闭启动检查后仍可选择更新源，手动检查继续使用当前选择。选项显示“GitHub（默认）”和中性的“镜像节点”。该选择同时控制手动检查、启动时检查、下载页和 Agent 包在线下载，不显示底层服务商名称。
• “关于与更新”在版本信息之后提供应用内反馈卡片。反馈对话框使用原生字段、明确隐私说明和一张可选截图；另提供默认关闭的原生 Checkbox，让用户主动附加最近桌面诊断摘要。Checkbox 附近必须持续说明摘要只含时间、组件、阶段、稳定错误码、错误类型和固定短消息，不含对话、Prompt、凭据、文件内容、路径、Provider 原始响应或远端 Agent 日志。勾选时为诊断摘要预留描述字符预算，超长草稿必须保留并显示字段错误，不得静默截断。失败时保留草稿、勾选状态和请求编号并提供就地重试，成功时在对话框内保留可复制编号而不重复发送全局通知；对话框遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape、焦点恢复和窄窗口布局。
• Agent Runtime 分类页头的“保存设置”同时保存 Runtime 基础配置与 Runtime 原生定制，不在原生定制卡片内提供第二个保存入口。原生定制存在未保存更改时持续显示状态和撤销入口；切换设置分类或 Runtime 不丢弃草稿，关闭设置中心前必须先保存或撤销。
• Agent Runtime 页面在低层程序与配置覆盖之外提供“能力与默认配置”区域。能力清单使用共享 PageTabs，按 Agents、Tools、Commands、Skills、MCP、Rules、Prompts、Resources、LSP、Formatters 和上下文 11 类单行滚动展示，一次只呈现当前分类的 tabpanel；清单只显示 Runtime 自有能力，不混入 GoodBuddy 分配的 Skills、临时 MCP 或 Continue 预设。Tools 必须独立于 Commands、LSP 和 Formatters，显示工具类型、来源及 Ask/Execute 可用性；清单状态必须区分完整、部分、不可用、仅连接和不支持，不能用进程连通性冒充清单可读。
• “能力与默认配置”只显示一个模块标题，刷新入口位于该标题右侧，能力状态压缩为一行并排在默认 Agent 或 Continue 预设编辑器之前；不得再复制“Runtime 原生能力”等同义标题、说明或状态结论。刷新只更新能力快照，不覆盖未保存的原生定制草稿。
• OpenCode 的默认 Agent 使用原生下拉选择；Continue 预设编辑器允许管理名称、说明、启用的 Rules 以及 Prompt 名称、说明和正文，并可展开查看原生 Rules 与启用预设 Rules 的最终合并顺序。持久启停仍使用共享 Switch，添加与删除使用明确按钮和可访问名称。
• MCP 设置按“内置 MCP / 直连模型 / 自定义 MCP / 电脑控制”四个同级 PageTabs 组织。联网搜索保留在直连模型；内置浏览器归入内置 MCP，提供持久启停和 Runtime 分配，并明确说明其操作 GoodBuddy 隔离浏览器、不控制客户端已安装的浏览器，开启后可由已分配 Runtime 的 Execute 直接使用，不逐次询问。该开关只控制 Agent 工具访问，关闭时不得禁用浏览器工作栏中的用户手动导航、返回、刷新、停止加载、交互或关闭操作。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 MCP 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。
• MCP Server 测试结果在同一展开卡片中分组显示 Tools、Prompts 和 Resources 的支持状态、数量与有界元数据；Prompt 参数标明必填项，Resource 只显示 URI、名称、类型和说明，不读取或渲染 Resource 内容。

13.9 文档解析设置

• 设置中心新增独立的“文档解析”分类，统一管理聊天附件、知识库导入以及后续文档审阅场景使用的提取、转换和 OCR 策略。OCR 不作为普通对话模型出现在“模型连接”中。
• 分类页头说明文档解析的跨场景作用，右侧依次显示“测试解析”和“保存设置”；保存位于最右侧。测试必须选择真实文件并执行实际解析，不能只检查模型文件或接口连通性。
• 页面首先显示原生解析、文档转换和 OCR 的运行状态，并明确当前可处理格式、回退能力与不可用原因。部分能力未配置时使用“部分可用”状态，不得把原生文本解析一并标记为失败。
• “使用场景”分别配置聊天附件和知识库导入。普通用户选择“自动解析”“快速文本”“完整索引”等预设；阈值、并发和超时放入默认折叠的高级设置。
• 本地 OCR 的全平台基线使用同一组 PP-OCRv6 ONNX 模型和 ONNX Runtime WebAssembly，在 Windows、macOS、Linux 的 x64 与 arm64 上保持相同功能。原生 ONNX、WebGPU、DirectML、CoreML 或 CUDA 只能作为可选加速，失败时必须回退到 WASM CPU。
• OCR 模型管理与语音模型保持一致：应用不内置权重，用户可按需从 ModelScope 下载，也可在联网设备导出 ZIP 并在离线或内网设备直接导入。语音和 OCR 模型的下载、取消、ZIP 导入、ZIP 导出、删除与打开受管目录使用同一交互语义；ZIP 操作不得隐式切换当前模型或保存解析设置。
• OCR 模型卡片必须持续显示来源、语言、运行时、体积、安装状态和许可。“打开 ModelScope”直接位于卡片右上角，不再使用“模型详情与手动导入”折叠区。窄窗口下仓库操作换行到模型摘要下方，仍须保持可访问名称和键盘操作。
• PP-OCRv6 提供三个已实现档位：Tiny 约 6 MiB，适合低资源设备；Small 约 30 MiB，官方支持 50 种语言并作为推荐档位；Medium 约 132 MiB，官方支持 50 种语言、质量更高但速度较慢，界面必须提示其更高的内存占用和延迟。
• 本地模型按受管目录和固定清单加载。ModelScope 下载地址必须固定不可变 revision、字节数和 SHA-256；下载先进入临时目录，全部校验成功后再原子安装。识别时不得从网络或可变分支临时加载模型。
• 模型 ZIP 使用版本化的 goodbuddy-model.json 清单，声明模型类型、内置目录 ID、文件角色、大小与 SHA-256。导出前重新校验已安装文件；导入时限制压缩包大小、条目数、单文件和总展开大小，拒绝路径穿越、重复、未知、缺失或嵌套条目，并以应用内置目录重新校验后原子安装。ZIP 内的自声明信息不能扩大受信任模型集合。
• PDF 先读取文本层。仅当页面无有效文本、乱码比例过高或用户选择“始终 OCR”时渲染该页并识别；不得因为单页需要 OCR 而丢弃其他页面已经提取的可靠文本。
• DOCX、XLSX、PPTX 优先保留段落、单元格、公式、备注等原生语义。转换为 PDF 用于补充版面、页码、图表和图片理解，不作为唯一中间格式。
• DOC、XLS、PPT 等旧格式通过受控转换 Provider 生成新式 Office 文档和 PDF。转换子进程必须禁用宏和网络，限制输入、输出、内存、超时与临时目录，并在关闭或取消时清理。
• OCR 来源使用“本地模型 / 远程服务”互斥选择。选择本地后显示模型下载、模型下拉选择和本地运行参数；选择远程后显示 MinerU、PaddleOCR-VL 等服务连接配置。未实现的远程服务入口保持可读但禁用，不再增加与来源选择重复的“隐私与云端处理”授权区。
• 用户配置并保存远程 OCR 服务即表示选择该处理路径，不再逐场景重复询问。界面仍须明确显示当前服务名称、处理范围和远程属性，API 密钥只保存在主进程加密设置中，未选中远程服务时不得上传文档。
• 解析结果使用统一文档结构，至少保留文档标题、来源格式、页码或工作表定位、正文块、置信度、处理方式和警告。聊天附件对结果做有界截断，知识库使用完整结果分块和索引。
• 测试结果显示文件类型、页数、实际工作流、提取字数、OCR 页数、耗时和警告。测试文件不得自动进入聊天上下文或知识库。

14. 文案规则

• 使用简体中文，动词直接、对象明确。
• 页面标题使用名词，例如“知识库”“智能心跳”“活动记录”。
• 按钮使用“动词 + 对象”，例如“新建任务”“导入知识”“停止运行”。
• 状态文案描述事实，例如“正在同步”“上次运行失败”，不使用含糊的“异常”。
• 错误提示包含发生了什么、用户可以做什么。保留必要的错误上下文，但不得暴露凭据、授权头、私人文档或未脱敏的提供商响应。
• 同一概念固定使用一个名称，不交替使用“项目空间”“工作区”“范围”等近义词。产品内统一使用“范围”表达全局与项目归属。

15. 迁移检查清单

15.1 基础层

• 建立浅色与深色语义颜色令牌，移除业务组件中的原始颜色值。
• 建立白色浅色主画布、冰蓝灰侧栏与深海军蓝深色表面的稳定层级。
• 建立间距、字体、圆角、阴影、层级和动效令牌。
• 为主题切换、减少动态效果和原生控件设置全局规则。
• 建立组件交互状态和焦点环基线。
• 验证浅色侧栏结构分隔线与导航、会话选中状态清晰可辨。

15.2 页面壳层与层级

• 实现 PageShell 的 reading、standard、dashboard、master-detail 变体。
• 按页面映射替换 820px、900px、1040px 和全宽等分散宽度声明。
• 每个一级页面只保留一个 PageHeader 和一个一级标题。
• 移除内容卡片中与页面标题重复的标题。

15.3 共享组件

• 实现并迁移 PageHeader。
• 使用 PageTabs 统一同级页面导航。
• 使用 SegmentedControl 统一少量互斥视图和状态切换。
• 需要分段外观的同级面板使用 PageTabs 的共享 segmented 变体，不复制控件样式。
• 建立统一筛选工具栏，移除以页签样式伪装的筛选。
• 二元启停统一使用共享 Switch 视觉与 role="switch"，多选、范围分配和确认项保留 Checkbox。
• 将短期成功、信息和非局部异步错误接入应用通知视口，移除页面专属通知横幅。
• 实现 ScopeBadge 并覆盖全局、项目、失效和可切换状态。
• 实现 EmptyState 的首次为空、无结果、失败和只读变体。
• 实现 danger-ghost、danger-solid 和 danger-zone。
• 统一模型、专家角色和工作模式的单选菜单结构、视觉与键盘行为。

15.4 页面迁移

• 聊天迁移到 reading，统一消息流与输入区宽度。
• 将输入快捷键与附件提示置于空输入框内部，输入区下方保持单行说明。
• 最近对话迁移到 standard，统一搜索、范围、时间和删除行为。
• 知识库迁移到 master-detail，清除内联浅色样式并补齐窄窗口单面板流程。
• 智能心跳使用 dashboard，保留概览、建议、轨迹和计划，并在计划中支持 Global / 多 Project 范围。
• 在现有工作栏中完善任务中心，统一范围、状态、最近进展和筛选，不新建平行任务平台。
• 活动记录迁移到 dashboard，统一导航、筛选和表格行为。
• 设置中心使用共享分类定义与 SettingsCategoryHeader，将保存与测试操作统一放到分类页头右侧，并把成功反馈接入应用通知。
• 文档解析设置统一聊天附件与知识库的解析预设、OCR 状态、转换状态、隐私限制和真实文件测试。

15.5 验收

• 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
• 在大于等于 1200px、960px、720px 和小于 720px 的窗口宽度检查布局。
• 仅使用键盘完成导航、筛选、创建、编辑、确认和取消。
• 验证焦点恢复、可访问名称、表单错误关联和实时状态播报。
• 验证页面范围、对象范围和操作范围在关键流程中始终可见。
• 验证删除、批量操作、停止运行和清空历史符合风险等级策略。
• 验证加载中、首次为空、筛选无结果、搜索无结果、失败和只读状态不会互相混用。
• 在 Windows、macOS、Linux 的 x64 与 arm64 上执行真实本地 OCR，并验证 WASM CPU 回退、取消、超时和离线运行。
• 在联网设备导出语音与 OCR 模型 ZIP，在离线设备导入后执行真实推理；验证错误模型 ID、篡改文件、路径穿越、未知条目和压缩炸弹均被拒绝。

16. 完成标准

一个页面只有在满足以下条件时才视为完成迁移：

1. 使用明确的 PageShell 变体，没有页面专属整体宽度。
2. 使用统一标题层级、共享导航和筛选控件。
3. 所有颜色、间距、字体、圆角和阴影来自令牌。
4. 全局或项目范围在浏览、创建、编辑和危险操作中均可见。
5. 浅色、深色、键盘和各窗口宽度下均可完成核心任务。
6. 空状态、错误状态和危险操作符合本文规则。

17. 一级页面加载性能

• 首次启动只可在低优先级空闲时预加载轻量一级页面；Knowledge、Magic Notes、 Settings、Activity 等较重页面应在对应导航控件获得指针意图或键盘焦点时预加载。
• 点击、快捷键和程序化导航不能依赖预加载完成，必须保留页面级 Suspense 加载 状态、错误边界和 KeepAlive 行为。
• Workspace 与 Conversation 的 KeepAlive 缓存必须在每次访问时立即执行容量上限 与 LRU 保护规则；定时清理只负责过期与数据失效兜底，不能作为容量门禁。
• 页面内大型可选视图应使用局部加载边界。知识图谱画布加载失败时，只替换画布 区域并提供可访问的重试操作，不得替换整个 Knowledge 页面或丢失其余页面状态。
• 加载状态使用 role="status"、aria-live="polite" 与 aria-busy="true"； 局部加载失败使用 role="alert"，并保留明确的恢复操作。