goodbuddy/UI-DESIGN.md

GoodBuddy 统一界面设计系统

1. 目的与适用范围

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

设计系统解决两类问题：

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

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

2. 核心原则

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

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

2.2 范围始终可见

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

2.3 主任务优先

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

2.4 状态明确且可恢复

• 加载、空内容、无结果、失败、只读和权限不足是不同状态，必须分别呈现。
• 可撤销操作优先提供撤销，不可撤销操作必须在执行前说明影响范围。
• 不依赖颜色单独表达状态或风险。
• 当前模型或 Runtime 及切换进度集中显示在会话输入区，顶栏不重复显示可用性标识。切换失败、自动状态检查失败或返回不可用时，通过应用通知说明原因；发送按钮保留关联的无障碍状态说明。

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

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

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

外观设置提供“透明磨砂特效”开关，默认开启，文字在左、共享 Switch 在右。新用户及缺少该字段的旧配置使用开启状态；已保存的开关选择保持不变。选择保存在应用设置中，保存成功后立即生效，重启后恢复。开启时，右侧内容框架顶栏的背景不透明度在浅色主题为 65%、深色主题为 70%，保留 18px 背景模糊与淡分隔线。聊天滚动视口向上延伸 58px，消息上滚时实际经过顶栏背后；不使用人工渐变充当背景。初始留白放在滚动内容中，包含顶栏高度和当前任务／待办条的实测高度，首条消息仍从这些控件下方开始。任务／待办条固定在顶栏下方并保持实色；展开的 Runtime 待办卡片使用两主题各自的 75% 不透明背景、18px 背景模糊和清晰的文字颜色。

已保存的开关状态同步到文档根节点，卸载时清理，使 body/top layer 中的待办卡片也能应用样式；其他菜单保持原有表面。输入区、右侧工作栏和非聊天页面保持原有位置，聊天加载态及无活动消息面板时不扩展视口。窗口拖拽和控制按钮保持原有行为；该效果不透出操作系统桌面。关闭后恢复顶栏下方的聊天布局，顶栏与待办卡片均恢复实色。tests/frosted-glass.electron.test.ts 使用真实 ChatHistoryPane 检查消息与顶栏的可见矩形交叠、初始留白、关闭恢复、浅深主题、跳底、历史加载锚点和会话切换。

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-solid-hover	最终确认按钮等需要反白文字的危险背景及悬停背景
--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 与字体尺寸令牌继承字体，不创建页面专属字体栈。
• 表单按钮、输入框、选择框和文本域必须继承界面字体，避免回退为原生控件字体。
• 文本表单复用 .field 下的共享输入规则；不适合增加字段包装层的独立输入或文本域使用 .field-control。文本输入规则排除 Checkbox 和 Radio，保留全局 :focus-visible 轮廓，不清除 Switch 焦点环。
• 连续阅读内容使用 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	指标、卡片网格、宽表格与审计数据	活动记录
supervisor	1440px	选择列表、图谱画布、来源详情三栏工作台	监督者（含智能心跳设置）
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：可选，需要常显的简短上下文，不重复标题或帮助内容。
• help：可选，补充用途和操作说明，通过标题同行的 InlineHelp 按需展开，规则见 6.14。
• 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 的按钮组语义，支持方向键切换。
• 不能用于多选筛选、页面导航或执行即时命令。
• 与 PageTabs 一样，共享控件根节点必须 flex: 0 0 auto，不能被同级长表单或滚动区域 压缩高度。横向空间不足时保留控件自身滚动，不把标签裁成一条窄缝。
• 控件宽度由内容决定，除移动窄屏外不默认等分整行。

6.3 筛选工具栏

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

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

6.4 ScopeBadge

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

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

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

6.5 EmptyState

EmptyState 统一包含：

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

必须区分：

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

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

6.6 危险操作

共享危险操作样式包含：

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

danger-solid 必须是全局共享类，不依赖页面祖先；通过 Portal 挂到 body 后仍须生效。 尺寸、圆角、字体、间距和禁用状态与 primary-button、secondary-button 共用规则， 键盘焦点沿用全局 button:focus-visible。背景及可用态悬停使用危险实心色令牌，文字使用 --text-on-accent；禁用时不触发悬停变色。

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

6.7 数据表格与活动列表

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

6.8 应用侧栏

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

• 浅色侧栏使用冰蓝灰表面，与白色主内容画布形成明确边界；深色侧栏使用比主画布略亮的蓝灰表面。
• 一级导航与最近会话之间、最近会话与底部账户区之间必须有可见结构分隔线。浅色主题使用 --border-default，深色主题可在可辨前提下使用 --border-subtle。
• 当前导航项和当前会话使用一致的淡蓝选中背景、强调色文字和中等字重，不额外描边或添加侧边标记；导航图标随选中状态使用强调色，悬停时保留选中状态。浅深主题遵循相同规则，强制颜色模式保留系统选中边框。
• 固定导航行高至少 36px、行间距 4px，图标统一为 16px；导航与会话区域之间、会话区域与底部入口之间的分隔线上下均各留 8px（--space-2）。普通待办和待处理建议数量使用中性色徽标，不使用危险红色；徽标高度不得改变导航行高。搜索框获得内部焦点时显示完整焦点环。
• 未选中项保持平整，不为每一行添加卡片边框或阴影。悬停反馈不得强于选中状态。
• 最近会话列表在精细指针设备上使用细原生滚动条，滑块使用 --border-control、轨道透明；强制颜色与粗指针设备保留系统默认。
• 会话区域使用 --surface-raised 与主导航区分，浅色为白底，深色为相邻的深蓝灰底。不显示“最近会话”标题，保留区域的无障碍名称，列表独立滚动。搜索与新对话共用主导航上方的一行，不在会话区域另设搜索头部；展开、关闭和键盘规则见会话搜索。搜索框使用透明背景、--border-control 边框与完整焦点环。
• 窗口高度不超过 600px 时，侧栏允许整体纵向滚动，会话区域至少保留 200px 高度，避免搜索框、列表与底部入口相互覆盖。
• 最近会话的顺序不随流式输出增量反复变化；置顶与新消息排序遵守 会话列表排序规则。
• 项目选择器顶行保留项目切换与新建按钮；项目设置统一从下拉列表对应行的管理按钮进入，关闭后焦点返回项目选择器。
• 项目选择器与下方默认的新建对话按钮等宽，两行右侧图标按钮均宽 36px，与左侧控件间距均为 8px；搜索展开时项目选择器宽度保持不变。
• 项目下拉列表通过 FloatingPortal 浮在侧栏与会话区上方，默认宽度 380px，不受侧栏裁剪；距窗口边缘至少 16px，窄窗口自动收窄，长列表内部滚动。浮层锚定项目选择按钮，窗口、滚动和尺寸变化后重新定位。
• 项目选择器使用固定双行单按钮，第一行显示项目名，第二行显示跨项目活动汇总或“暂无活动”；点击任一行打开统一菜单并默认预览当前项目，全部项目范围在菜单内切换。尺寸、焦点、项目计数与菜单遵守 项目活动汇总 UI 规则。 活动数量不改变项目菜单的稳定分组和顺序。
• 桌面停靠状态下，主侧栏宽度允许在 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。名称或副标题溢出品牌区时 单行截断，不能撑宽或挤压侧栏。
• 侧栏底部提供“应用 / Apps”和“设置 / Settings”两个横向等高 nav-item 按钮，均显示图标和文字，中间使用弱竖分隔线。“应用”带向下箭头，点击后向上展开轻量锚定菜单，无模态遮罩，只列已启用应用，不按打开历史或常驻状态筛选；点击行关闭菜单，知识库、智能心跳和魔法笔记在主内容区打开页面。本机推理监控从菜单、常驻入口或管理 Modal 打开时均使用独立 Modal，保留底层工作区。菜单底部“管理应用”使用 LayoutGrid 图标，打开既有整窗管理 Modal，标题仍为“应用中心 / Application Center”，共同应用设置沿用设置 Modal。 五个内置应用的管理列表、菜单和侧栏共用保存顺序，菜单按启用过滤，侧栏按启用且常驻过滤。知识库始终启用并常驻，可调整位置；管理 Modal 提供“打开”和排序，不提供启用、常驻开关或通用空设置，标签为“始终显示”（英文 Always shown）。监督者沿用智能心跳身份，可修改启用和常驻，执行边界见监督者逻辑。魔法笔记、本机推理监控同样可修改启用和常驻。设备共享在测试阶段默认关闭，标签为“可选”及启用状态，提供启用设置和排序，不提供常驻开关；启用后可从应用菜单及管理 Modal 在主内容区打开元数据页面，关闭时退出该页，规则见设备共享 UI。当前对话、运行记录和设置保持固定系统位置，不参与应用排序。 设置持久化后的事件同步各入口及工具配置写入；重开中心刷新期间锁定修改，新快照不被旧读取覆盖。文件、终端、浏览器和资源监控只通过右侧工作栏访问，不在左侧复制入口。 管理 Modal 始终使用紧凑单列横向列表，纵向对应保存顺序；左侧为图标、名称及简短用途，右侧为打开、可用的设置及上下移动操作，行间使用弱分隔线，不加卡片外框。窄窗口操作换行且不溢出，保留共享键盘焦点环。可选应用关闭时禁用“打开”。启用、常驻位于紧凑设置详情；五行均提供上下移动及拖动排序，不受启用或常驻影响，箭头按完整顺序判断边界。搜索时禁用拖动，箭头仍按完整顺序移动，不丢失未命中项。尺寸、返回与滚动重置规则见应用中心 UI 设计。已有稳定设置入口时，不在顶栏重复提供同一入口。
• 本机推理监控 Modal 复用整窗 Portal、背景隔离和焦点循环；停止、重启及释放使用其上方的紧凑影响确认。Escape 只关闭最上层，操作提交期间禁止关闭及重复提交；焦点恢复与尺寸见本机推理监控 UI 规则。

6.9 助手工作栏

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

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

6.10 应用顶栏与全局操作

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

• 应用壳层在水平方向分为全高主侧栏和右侧内容框架。主侧栏从窗口顶部贯穿到底部，品牌区、 项目切换器、导航和账户区保持同一连续表面；不能用全宽标题栏把整条侧栏向下推移。
• 无边框窗口的紧凑标题栏只覆盖右侧内容框架，保留侧栏开关、当前会话标题、范围、Runtime 状态、主题开关和窗口控制，不得为了新增工作栏入口把这一整组控件下移。普通图标按钮使用 34px × 34px 点击区域。
• 发布说明 Modal 与其他应用级 Modal 一样使用整窗遮罩；遮罩必须覆盖主侧栏、右侧内容和 顶栏，不能保留一条未被遮罩的窗口控制色块。关闭操作由 Modal 自身提供。
• 整窗固定遮罩通过 createPortal(..., document.body) 挂载，避免页面层叠上下文影响； 保留 React Context、关闭与焦点管理，表单样式不得依赖已移出的页面祖先选择器。
• 共享锚定菜单 AnchoredMenu、同行帮助 InlineHelp 和应用通知共用 FloatingPortal 的非模态 popover="manual"，由浏览器 top layer 绘制，避免被 Modal 或滚动容器遮挡。菜单和帮助挂在触发按钮所属 Modal 内，通知跟随当前活动 Modal，无 Modal 时挂在 body；不能只提高 z-index 或解除背景的 inert。
• 原生浏览器 WebContentsView 不受网页 z-index 控制。应用级 Modal 打开时统一释放 浏览器 viewport；非模态对话框、菜单、同行帮助 tooltip、局部确认或应用通知与浏览器区域相交时也释放。 浮层关闭后只恢复当前活动实例的 viewport，不关闭、重建或刷新网页。接线与测试见 浏览器多实例技术设计。
• 遮罩必须 inset: 0 铺满整窗，并由 styles.css 中统一的遮罩选择器声明 -webkit-app-region: no-drag，否则 .brand 与 .topbar 的原生拖动区域会截获指针， 使遮罩上的控件无法悬停和点击。新增整窗遮罩时扩展该共享选择器，不要在各自规则里复制 no-drag，也不要用 inset: 38px 0 0 之类的偏移绕开标题栏。遮罩回归按 fixed/inset 声明发现，不能只按 backdrop 或 modal 类名后缀筛选；知识引用的 -dialog 同样适用。
• 当前会话存在 Task 时，Task 上下文栏位于标题栏下方并承载任务摘要与详情；没有 Task 时 整行隐藏。折叠状态保持为 46px 单行表面，与右侧工作栏标签栏等高，左右分隔线必须水平 对齐。该栏不重复放置新建入口。
• “新建任务”只位于工作栏“任务索引”标题后方；任务状态筛选占满工作栏可用宽度，四个选项 等分，不能保留内容宽度的短控件。
• Runtime 状态、同步状态等短标签使用 --font-caption，不得放大为正文标题。顶栏 Runtime 状态由状态点和 Runtime/模型名称紧凑表达：就绪使用绿色，连接中使用黄色，不可用使用灰色， 不再重复显示状态文字；完整状态详情继续通过可访问说明和工具提示提供。
• 浅色与深色切换属于持续可用的窗口级操作，直接显示太阳或月亮图标，并通过可访问名称说明将切换到的主题。选择必须持久化，切换不得改变布局。
• 顶栏只直接显示当前任务所需的高频操作。已有侧栏账户设置入口时，不再重复显示 Runtime/设置入口；使用帮助优先放在相关操作附近，而不是为单个帮助项创建“更多”菜单。
• 助手工作栏开关固定在顶栏 .topbar__actions 内、紧邻浅色/深色主题按钮之前；展开后该开关保持原位并 负责收起，不在工作栏标题区域增加第二个关闭入口。
• 只有存在至少两个无法由稳定入口承载的低频全局操作时才增加全局菜单，不为了容纳一个冗余入口而显示省略号按钮。
• 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。
• 使用全局菜单时，菜单项使用 --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 应用通知与就地反馈

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

• 右上角通知使用紧凑的中性表面、弱边框和轻阴影，最大宽度为 360px，窄窗口保留两侧各 16px。状态色仅用于图标，不铺满卡片；正文直接呈现，通用状态标题仅供屏幕阅读器读取。图标、正文与关闭按钮统一垂直居中，不使用各自的上下偏移。
• 异步操作成功、无需立即处理的信息，以及不属于某个字段的异步失败，使用应用级 success、info 或 error 通知。
• 成功和信息通知默认在约 2 秒后自动消失；错误通知保持可见，直到用户关闭或同一去重键的更新替换它。
• 通知出现不抢焦点；Modal 打开时，通知关闭按钮纳入当前 Modal 的 Tab 循环。聚焦通知时 Escape 返回原控件或当前 Modal 的可用控件，不关闭 Modal；关闭通知后同样恢复焦点。 打开、关闭或切换 Modal 不重建通知，不重置自动消失计时。
• 同一语义和文案的重复通知应去重。通知正文必须有长度上限，不包含凭据、私人内容或未脱敏的提供商响应。
• 字段校验、破坏性确认、操作进度、阻塞整个页面的状态，以及需要就地重试或修正的错误保留在相关控件附近。
• 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 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 靠右，说明放在标签下方；不因 JSX 中输入控件与文字的先后顺序改变视觉位置。窄窗口允许文字换行，开关保持固定尺寸。Checkbox 和 Radio 保留各自的选择布局。
• 异步切换期间禁用重复操作并保留原状态。失败时恢复或保留最后确认状态，通过应用通知或就地可恢复错误说明原因。
• 涉及联网、上传、电脑控制或其他外部影响的 Switch，附近必须持续说明数据去向、权限范围或风险，不能只靠设置名称表达影响。
• 自动化测试应按 switch 角色查询二元开关，按 checkbox 角色查询多选或确认项，防止视觉迁移后语义回退。

6.14 InlineHelp 同行帮助

页面、区块和字段的补充用途、格式及操作说明统一收进标题或标签旁的 InlineHelp 问号按钮。 PageHeader 与 SettingsSectionHeader 通过 help 接收这类内容；description 保留需要常显的上下文，两处不重复说明。描述缺省或为空时不渲染段落，不保留空行。 当前范围、状态、字段错误、操作进度、风险、费用和影响用户决策的限制仍就地可见。混合文案先拆分，再将补充说明移入帮助。

• 标题或标签与问号使用共享 inline-help-label 同行排列，不为帮助另占说明行；字段标签通过 htmlFor 关联控件，帮助按钮放在 label 外，避免点击帮助触发输入或开关。
• 悬停或键盘聚焦按钮时展开；指针可移入浮层阅读。点击（含 Enter、Space 激活）固定展开，再次点击关闭；未固定时，指针和焦点均离开后关闭。
• Escape、点击外部或焦点移到外部关闭帮助。Escape 优先关闭帮助，不同时关闭所属 Modal；展开和关闭不主动转移焦点，不建立焦点陷阱。
• 按钮提供与标题或标签对应的可访问名称、aria-expanded，展开时通过 aria-controls、aria-describedby 关联 role="tooltip" 内容。提供稳定帮助 ID 时，关闭状态保留同 ID 的隐藏说明，展开时由浮层替换，确保字段的 aria-describedby 始终有唯一目标。持久标签与必要提示不得依赖浮层。
• SSH 密码字段常显认证用途和验证成功后加密保存的说明；Main 处理及不写入命令行、日志、普通设置的细节收进同行帮助。应用常驻说明与关闭后果使用独立翻译键，关闭后果保持常显，不按标点拆分翻译文本。
• 浮层复用 FloatingPortal，遵循 6.10 的 Modal 归属规则。宽度最多 360px，四周保留 16px 视口边距；空间不足时翻转或调整位置，长内容在浮层内滚动，窗口及滚动变化后重新定位。
• 问号使用共享 28px × 28px 点击区域、焦点环与主题令牌。不得另做原生 title 长说明或页面专属帮助浮层。

6.15 表单 Modal

• 复用 styles.css 中的 custom-task-dialog__surface、custom-task-dialog__header、custom-task-dialog__content 和 custom-task-dialog__actions，与定制任务、SSH Host 等现有弹窗使用同一结构；不为单个业务另建 Modal 框架。
• 标题放在 header 左侧，右侧只放共享 icon-button 的 X 关闭按钮，使用本地化 aria-label 和工具提示。取消不放在标题下方或表单顶部。
• footer 使用共享操作区，按钮整体右对齐，次要取消在前、主要保存在后。放弃修改确认沿用同一操作区，继续编辑在前、危险操作在后。
• header、滚动 body、footer 是 surface 的三个直接子区域。沿用共享 Grid 的 auto minmax(0, 1fr) auto，只有 body 滚动，短窗口仍可见标题、关闭和提交操作；窄窗口沿用共享外边距、内边距和主题令牌。
• X、取消、Escape 和遮罩关闭共用业务关闭检查，不绕过未保存确认或提交锁定。确认中的 Escape 或 X 返回编辑；继续复用 activateModalFocus、trapTabFocus，保留背景隔离、初始焦点和关闭后的焦点恢复。保存失败保留草稿及可恢复错误。
• 从已有 Modal 打开的子 Modal 同样复用 --z-dialog 和 activateModalFocus，以较后挂载的 body Portal 绘制在父层上方，并隔离父层；不能只手动聚焦或使用旧的页面层级常量。子层关闭后恢复父层的隔离状态与触发按钮焦点，Escape 不继续关闭父层。

7. 交互状态

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

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

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

共享控件的状态规则须在容器组合中生效：菜单通用按钮样式不能覆盖危险按钮，普通图标悬停不能覆盖危险图标或作用于禁用按钮，页签悬停保留当前选中态。深色主题通过令牌提供控件颜色，避免用页面祖先下的通用输入规则替换控件边框。验证时读取最终 computed style；共享令牌对比度与源码规则存在性检查不能代替容器内、body Portal 和伪状态回归。修复与验证记录见共享控件审查。

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 原文，不包含推理过程、工具日志或引用元数据。复制成功后，当前按钮显示使用 --success 的绿色对号，可访问名称和工具提示同步表示已复制，3 秒后恢复复制图标；重复复制成功重新 计时，不显示成功通知。失败仍通过应用错误通知反馈。流式回复完成前不显示复制入口。
• 默认开启“会话 HTML 渲染”时，已完成 Agent 回复中的完整 HTML 与 html / htm 代码块在原位置显示隔离静态预览；用户消息、推理过程和流式中的回复不得执行 HTML。 每个预览持续标注脚本和网络已禁用，并在标题右侧复用与 Mermaid 图表相同的图标按钮组： 源码按钮使用代码图标并暴露 aria-expanded，全屏按钮使用放大图标打开统一 Modal。 全屏预览遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape 关闭和焦点恢复规则， 并沿用同一套清理与 Sandbox/CSP 边界。关闭平台功能后必须显示 HTML 源码，不能隐藏内容 或保留旧预览。 Tab 和 Shift+Tab 必须能进入及离开 iframe；焦点在预览内部时 Escape 仍关闭当前全屏层并返回入口。空 sandbox 与禁脚本 CSP 保持不变，跨文档键盘接线见HTML 渲染技术设计。
• Mermaid 大图支持缩放和拖动；图形超过画布时，四个边缘都必须能通过滚动到达，不能因居中而裁掉顶部或左侧。 弹窗工具栏提供“导出 PNG”，保存完整图形，不受当前缩放和滚动位置影响；背景使用当前主题的画布底色。 导出按原图四周留出 16px，以 2 倍分辨率绘制，任一边最多 4096px。导出期间禁用重复点击，失败在按钮旁提示重试。
• 本地会话的更多操作提供“在新会话中继续”。创建前必须先持久化当前稳定消息；有活动运行 或待发送内容时不可创建。新会话复制聊天内容与当前 Runtime/知识检索选择，重置压缩状态， 使用新的会话和消息 ID，且不复制 Task、队列、运行、记忆或成果归属。
• 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
• 模型、专家角色、工作模式、OpenCode Agent、Continue 预设和 Runtime 快捷操作使用统一的上下文单选菜单，并保持菜单互斥、键盘可达和选中状态明确。
• Runtime 选择菜单必须反映当前执行空间的真实能力。托管 SSH 项目当前只支持 OpenCode，因此输入区只渲染已配置的 OpenCode 选项和管理入口，不显示直连模型、Continue 或 DeepSeek Harness 的不可用入口；旧会话保存的其他 Runtime 选择在项目激活时恢复为当前 OpenCode 配置。
• 输入区使用一个完整容器，主工具栏保留附件、语音、Runtime、工作模式、会话选项及停止/发送。知识范围、专家角色、OpenCode Agent、Continue 预设和 Runtime 快捷操作收纳在会话选项浮层中；Runtime 专属选择在浮层内按提供方分组，无可选功能时不保留空分组。输入框上方以简短摘要显示生效的专家、知识范围、检索方式和 Runtime 专属选择。
• 会话选项浮层与主行菜单互斥，内部复用上下文选择菜单；子菜单就地展开，浮层统一限制宽高并滚动。Escape 先关闭子菜单并恢复其触发按钮焦点，再关闭会话选项并恢复入口焦点；点击外部、焦点离开、切换会话或开始/结束回复时关闭浮层。
• 会话选项入口紧随录音键，使用无常驻边框的调节图标，保留可访问名称、悬停说明和展开态反馈；浮层在工具栏左侧展开，最大宽度为 300px，窄窗口不超过输入区。浮层内选择器使用整行轻量列表样式，避免重复的按钮边框；知识库行右侧显示展开箭头，展开时朝上。
• 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 过程中使用同一轻量折叠记录：不显示外层“工具执行”标题、计数、背景和边框，保留无障碍区域名称。记录纵向左对齐，头部按内容收宽且不超过消息宽度；展开箭头在左，工具名作为主标题，有额外信息的单行摘要弱化显示。右侧以绿色对勾显示成功完成，以图标显示运行和待执行状态，提供悬停文字和无障碍名称；失败和可恢复状态保留文字。仅重复工具名和执行状态的已知 Runtime 模板摘要在头部与详情中均隐藏；刷新重试、审批等额外提示保留。默认折叠，状态和输出更新不改变用户的展开选择；折叠时露出一行错误，展开详情使用消息可用宽度、浅背景和左侧细线，按错误、结果、独立折叠的输入参数阅读。详情保留原始文本，完整 JSON 输入可缩进显示，复制仍使用收到的原文，并通过应用通知反馈。详情工具栏只保留复制按钮，文本默认自动换行，长内容在固定最大高度内滚动，不提供换行切换和展开全部按钮。
• OpenCode 主会话和子 Agent 的工具记录均保留 Runtime 提供的操作标题作为摘要，显示文件路径、命令或操作描述；本地 SDK 标题去除首尾空白后最多保留 240 字符，没有标题时沿用工具名回退规则。主会话工具失败或中断时保留已收到的标题；远端 ACP 继续在记录名称中显示其提供的标题。
• 工具取消后保留“已取消”文字，避免与失败图标混淆。
• Continue、DeepSeek Harness 和直连模型的工具名后显示单行操作摘要，内容提取、长度与完成态保留规则见工具操作摘要。
• Agent 回复进行中不能禁用普通消息发送。新消息与到期 Scheduled Task 共用 Conversation 级待发送队列。队列位于 Composer 容器之外、与输入框等宽并保持独立间距；有待发送项时直接显示无标题栏的极简列表，空队列不保留占位。每项固定为一行，按进入顺序显示轻量来源图标和截断摘要；普通消息使用消息图标，Scheduled Task 统一使用淡出时钟图标。
• 待发送项默认在当前回复结束后顺序执行。每项提供明确的“立即中断并插入”（空闲时为“立即运行”）和删除操作；前者先取消当前 Conversation 的活动执行，再将所选项提升为下一项，不允许同一 Conversation 并发写入时间线。
• 队列区域向上增长并设置有界滚动高度，不提供展开、收起或冗余计数标题。宽容器中的操作采用弱化的行内样式，不渲染成强调卡片或胶囊；窄容器中保留来源、摘要和图标操作并隐藏冗长按钮文字。区域、来源和每个操作必须有可读无障碍名称。队列异步错误进入应用通知，不在 Composer 内复制通知样式。
• 支持上下文状态的 Runtime 在输入区下方复用同一紧凑用量条；文案必须区分“本次模型调用”和“压缩后对话估算”。手动压缩仅在当前 Runtime 明确支持且没有活动回复时显示，作为元信息区左下角的浮动次操作，不参与输入区高度计算；元信息区始终预留稳定高度，切换 Runtime 不得让输入框上下位移。元信息区与窗口底部只保留紧凑安全留白，不形成额外空白区。进行中禁用重复操作，结果通过应用通知反馈。
• 已选择的工作模式在触发按钮中只显示 Ask 或 Execute；完整中文含义和说明保留在菜单选项、可访问名称及输入区下方的模式说明中。
• 宽度大于 700px 时，主工具栏的添加内容、Runtime、模式、会话选项与发送保持同一行。窄输入区按容器宽度换行，保留发送及停止入口；选项浮层不得超出输入区宽度，不再常驻独立的 Runtime 专属功能行。
• 输入框原生支持 Ctrl+V：文本直接进入草稿，系统截图和从文件管理器复制的一个或多个支持文件加入本次消息附件。文件粘贴与上传按钮共用读取、解析进度和数量限制；读取期间阻止重复导入及发送，错误就地关联输入框和附件按钮。具体类型、大小及批次失败规则见聊天附件要求。默认工具栏不提供独立“读取剪贴板”“截取当前屏幕”和“选择应用窗口”入口。
• 空输入框使用三行原生占位文案：第一行为消息提示（生图模式保留图片描述提示），第二行为“Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴”，第三行为“Ctrl+N 新建对话 · 实际已注册快捷键 快捷唤起”。新建与粘贴快捷键按平台显示，macOS 使用 Command；全局快捷键不可用时省略该项。输入文字后占位提示自然隐藏，输入框下方不再重复全局快捷键，保留模式、安全边界和其他元信息。
• 输入操作提示不能替代表单的可访问名称，输入框始终保留持久的程序化标签。
• 草稿与消息中的附件操作使用紧凑图标按钮，并提供悬停和键盘焦点提示；文件名、解析状态与操作行的布局遵循附件操作规则。
• 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
• 消息流的滚动范围必须使用已渲染消息的真实高度。长会话可以按批次只挂载最近消息并由用户 加载更早内容，但不得用固定的消息占位高度替代实际布局，避免推理、工具列表或长正文被 排除在可滚动范围之外。

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 智能心跳

• 监督者入口使用 supervisor 壳层；智能心跳设置位于同一壳层内。
• 顶层页签为“工作回顾 / 故事线图谱 / 智能心跳 / 活动记录 / 设置”，使用一套共享 PageTabs，窄窗口单行横向滚动。页签下不重复同名标题，也不保留空标题容器；所选回顾使用“监督结果”标题，历史结果不得标为最新。
• 工作回顾只展示统一监督结果、历史选择和紧凑的新回顾控件；结果保留自身范围、覆盖区间和生成时间，图谱读取同一结果 ID。智能心跳集中展示心跳计划、监督建议和只读的历史心跳报告；活动记录只展示统一执行活动、进度和详情。每页保留所属数据的一处刷新入口，范围与时间选择仅作用于新回顾请求。详细布局与阅读规则见监督者 UI 设计。
• 监督者保留统一页面壳层；工作回顾与活动子面板铺满壳层可用内容宽度，与页签左右对齐。工具栏、历史导航、状态和结果共享宽度，不再增加子面板宽度上限。工作回顾按纵向排列，空态独占工具栏下方整行并水平居中。活动筛选按内容紧邻排列，阶段使用编号圆点和连接线，次要统计收进详情；具体布局见监督者 UI 设计。
• 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用 Checkbox，不能依靠进入页面时的当前项目推断。
• 状态卡片使用统一状态令牌，不只依赖颜色。
• 活动记录先显示运行状态、时间、范围及实际阶段，恢复操作紧邻进度。原始错误默认折叠，展开后在有界面板内滚动并可选择复制；配置归入次要详情。任务层级只展示可查询的记录，缺失阶段明确标注，不能用剩余来源为零推断发布成功。具体阶段与分页规则见监督者活动设计。
• 智能心跳的“心跳计划”卡片内直接排列状态说明、创建按钮和计划列表，不再嵌套第二层边框；仅保留一个创建按钮，说明文字按无计划、全部暂停、正常三种状态只显示一条。创建与编辑复用同一份表单及共享 Modal 焦点、背景隔离和遮罩样式；未保存关闭须确认，保存失败保留草稿，编辑暂停计划不恢复运行。“执行记录”进入按该计划 ID 筛选的活动页，活动页不重复显示心跳审计列表。
• 设置只展示模型超时与并发、分页、分批和单次响应容量，不含计划、报告、审计或嵌套页签，不显示整页全局徽标或独立刷新行。
• 监督者的设置、帮助、空态及错误文案不得向终端用户展示内部路线图、交付进度或设计与实现缺项；只说明当前行为、适用范围和可执行的下一步。不得因此夸大为提供商全局限流或完整语义识别；真实的运行失败、超时、暂停、来源失效及恢复操作必须保留。
• 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。
• 分区记忆协同与唤起条件尚未实现，不得显示占位入口或平行的记忆类型。

13.5 Task Center

• 保留现有助手工作栏入口，首期在窄栏内适度完善，不先扩张成新的独立一级页面。
• 只展示 Task；普通 Conversation、Job、Run、工具步骤、Subagent 和心跳事项不独立占行。
• 范围固定为当前项目，不提供全局或所有项目入口；切换会话不筛掉本项目其他会话的任务。
• 顶部紧凑显示当前会话消息总数和 Agent 累计回复时间，按每轮请求区间累加，包含轮内工具和 审批等待，不计轮间空闲。历史缺失显示不完整提示，远程缺少可靠证据时不虚构用时。
• 每项显示名称、关联 Conversation、所属项目、Ask/Execute、状态、最近进展、 最近真实活动时间、累计执行时间及需要关注信息。任务用时汇总历次执行请求，不按父任务生命周期计算。
• 点击列表项打开关联 Conversation 并定位该 Task，不显示第二份内容载体。
• 项目任务标题右侧依次为“+”新建和筛选图标；图标按钮提供可访问名称，筛选按钮提供展开状态。 状态筛选默认收起且为全部；展开后用共享 SegmentedControl 提供全部、进行中、暂停、已结束， 窄栏不足时单行滚动。收起保留条件，非全部时图标高亮并显示条件。状态归类遵循任务中心 PRD。
• 完整消息留在 Conversation；长错误、工具、审批和成果按 Task 关联到 Runtime、活动记录和 成果查看器，不撑高列表，也不显示 Job/Run 树。
• “新建定制任务”使用共享 Modal，默认立即执行和当前 Conversation，可选择本项目其他可用 Conversation 或新建会话，选择必须持续可见。内容必填，名称可选并从内容生成；定时提供单次、每日和每周。
• 定时消息创建 Modal 使用关联 Conversation 的 Runtime 与 Ask/Execute 模式，不再提供独立 模式开关。未运行计划的详情显示会话当前模式，已运行任务显示该次执行记录的模式； 不得用旧计划字段表示下一次执行权限。不支持工具时不得静默降级。

13.6 运行记录

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

13.7 魔法笔记

会话联动已接入：右侧提供可关闭的单实例笔记 Tab，通过工作栏“+ → 笔记”打开；左下角和聊天页头不再提供重复的“快速笔记”入口。助手消息和会话标题菜单可打开文字采集预览；保存记录在面板和完整工作区显示独立来源条。草稿由 App 保留，关闭、替换及禁用前确认。具体交互由魔法笔记会话联动界面设计维护。真实 Electron 验收已通过，全仓验证未全绿，见验证进度。下列规则描述独立工作区。

• 未打开笔记详情时，笔记列表与待办使用页头普通按钮切换。按钮显示目标“切换到待办”或“切换到笔记”及对应图标，按内容宽度显示，不拉伸；笔记的新建入口位于左侧列表标题行，待办页的新建入口位于页头。窄窗口操作组可换行到标题下方，保留控件高度。
• 切换按钮不使用页签语义，切换后焦点回到同一个按钮；内容 section 持续提供当前列表的 aria-label。切换沿用草稿保护入口，待办状态仍使用独立的 SegmentedControl。
• 文字记录编辑器保留 Quill 原生列表快捷输入：输入 -、*、1.、[ ] 或 [x] 后按空格，分别转换为项目符号、编号或待办清单。快捷输入只生成现有 Delta 富文本，不引入 Markdown 源码模式、第二套文字记录持久化格式或第三方 Markdown 插件；新建文字记录的操作提示收进类型选择旁的 InlineHelp。
• 新记录可选择“文字 / 画布”；已保存画布提供分页阅读和“展开编辑画布”。画布使用 PeopleLib 的 Fabric 分页批注与 Quill 跨页正文，支持纸张模板、增删页、笔迹、高亮、整对象橡皮、选择及移动缩放旋转、浮动文字、图片和 PDF 底版。画布有固定页面边界；已保存记录、待办来源和编辑态默认容纳完整当前页及工具栏，高度随当前页实际显示尺寸变化，纵向由外层笔记流滚动。多页仍属于一条记录，通过页码翻页；窄窗口工具栏换行，纸张仅在自身视口内横向滚动，不撑宽外层页面。
• 画布通过“保存记录 / 保存修改”手动持久化，离开或切换记录类型前沿用未保存草稿确认。撤销/重做作用于当前批注页或 Quill 正文模式，增删页和 PDF 导入不属于全局撤销历史。删除非空批注页或 PDF 页需要在五秒内再次点击确认。
• 画布编辑与只读工具栏均提供缩小、当前百分比、放大和“适应宽度”。默认 100%，范围 25%–300%；加减每次调整 25 个百分点，点击百分比还原 100%。画布区域内 Ctrl/Command + 滚轮连续缩放，普通滚轮和 Shift 横滚保持原有方向与边界传递。适应宽度按实际视口计算，窗口或分栏调整后自动更新；翻页保留固定比例或适应宽度策略。缩放仅影响显示，整页高度与横向滚动范围随之变化，不新增内层纵向滚动，也不改变正文分页、保存内容、导出尺寸或未保存状态。控件沿用画布的主题、焦点环与提示，窄屏整组换行，适应宽度通过 aria-pressed 和选中样式表达状态。
• “导入 PDF”保留页面并提取原生文字供搜索与 AI 使用，扫描页不自动 OCR。“导出 PDF”将底版、正文和批注逐页合成为栅格 PDF，不保留可搜索文字层；当前 UI 无 PNG 下载按钮，页面 PNG 捕获仅作为程序接口提供。
• 画布新建与编辑态不显示常驻分析提示。操作放在编辑区右上角：新建与类型选择同排，顺序为“分析画布草稿、保存记录”；编辑放在记录头部，顺序为“分析画布草稿、取消、保存修改”。保存为最右侧主按钮，窄屏允许换行；底部不重复操作，新建不增加取消按钮。immediate 仍通过按钮手动分析，不随笔画自动请求；after-save-auto 在手动保存后分析。设置读取或页面捕获失败不阻断保存，保存成功后通过应用通知说明自动分析失败，可稍后重新分析；模型分析失败也不回滚已保存内容。
• 魔法笔记设置提供“发送画布页数”单选框，复用设置表单 .field 控件样式，范围 1～8，默认 1。标题同行的问号使用 InlineHelp，下拉框通过稳定的帮助 ID 关联展开的说明，交互遵循 6.14。说明包含当前页序前 N 页、不足时发送全部页、数量指单个画布页数而非记录数，以及完整保存与导出不受影响。修改后沿用设置保存反馈，下次分析生效。
• 草稿、已保存画布记录及来源为画布的待办，按默认模型的 supportsImageInput 使用所选前 N 页图像与文字，或只发送同一范围文字并标注“仅文字分析（未使用画布图像）”。所选页只有视觉内容的记录/草稿遇到文字模型时提示切换支持图像输入的默认模型，不声称已理解笔迹或布局。待办分析同时保留任务标题、说明和所选来源画布页的上下文。
• 画布文字评论在提取的 plainText 不变时保留；图像评论随画布内容或布局变化失效，在保存后自动评论模式下重新分析。草稿内容变化清除旧草稿分析，评论区显示实际使用的输入模式。存储和判定细节见画布技术设计。
• 总览是全宽的“全部笔记”页，以自适应卡片网格（最小 260px）显示全部笔记，不显示右侧空白详情，也不自动打开第一篇；卡片显示标题、短日期、两行预览和记录数。打开笔记后切为左侧紧凑列表与右侧详情，页头右上角显示带文字的“返回总览”，点击回到全部笔记页并恢复搜索、滚动位置与卡片焦点；“切换到待办”只在总览显示。列表按紧凑两行行项显示：第一行为标题与短日期（今天显示时间，其余显示月/日，完整时间在工具提示中），第二行为单行预览；记录数只提供给读屏。行项无边框、透明底色，悬停为次级底色，选中为淡蓝底色加左侧 3px 强调标记；“更多”按钮悬停或聚焦时覆盖在日期位置。保留搜索、置顶菜单和当前选中状态。打开笔记只更新右侧详情；列表独立滚动，切换保留搜索和列表位置，并在工作区挂载期间记住各篇笔记的阅读位置。明确定位某条记录时优先跳到该记录。
• 笔记列表默认展开、宽 280px，支持拖动分隔线在 240–420px 内调宽，方向键每次调整 16px，Home/End 跳到边界；桌面端详情页提供列表显隐开关，记住宽度和展开偏好。工作区宽度不超过 900px 时切换显示列表与详情，返回恢复列表位置和入口焦点，不覆盖桌面偏好。新建成功后打开新笔记；切换、新建和删除当前笔记都保护未保存的正文与标题。
• 待办页是独立任务视图：搜索任务标题、说明或来源笔记，搜索框右侧同一工具栏放置“全部 / 未完成 / 已完成”筛选，显示匹配数与总数；任务按来源笔记分组。列表独立滚动，页头、搜索和筛选保持可见，窄屏工具栏空间不足时换行。直接勾选完成或恢复未完成，不自动选择任务；状态变化后按当前筛选更新列表。
• 待办内容容器宽于 700px 时，任务列表稳定在左侧，右侧显示当前任务说明、来源记录和 AI 评论；未选择时右侧提示选择任务。点击任务只更新右侧，不改变列表宽度、行位置或滚动位置，再次点击取消选择。AI 不增加第三栏。容器不超过 700px 时，按需详情替换同一内容区域，并提供“返回待办列表”；列表保持挂载，返回恢复滚动和任务行焦点，不将列表与详情上下堆叠。任务按钮提供 aria-expanded 和 aria-controls。
• 待办左右栏分割线支持拖拽，并记住列表宽度；键盘左右方向键每次调整 16px，Home/End 调整至边界。列表默认 320px、最小 240px，详情至少保留 300px；窄屏隐藏分割线，临时缩窄窗口不覆盖已保存宽度。每个来源笔记标题可独立收起或展开待办列表，保留标题与数量，通过 aria-expanded 和 aria-controls 表明状态；收起不清除右侧当前详情。
• 待办 AI 评论保留方向选择、流式输出、重新分析和已有结果；来源加载失败通过应用通知提示，并提供就地重试。从待办打开原笔记后，“返回待办”恢复任务选择、搜索、筛选和列表滚动；宽屏焦点返回任务行，窄屏返回待办详情中的返回按钮。
• 笔记详情主区按新到旧连续展示全部记录。打开笔记即在标题下、历史记录上显示空白输入区，保留文字/画布类型选择和保存操作，标题栏与索引均不提供“新增记录”按钮。新增保存成功后重建空白输入区，保留所选类型；自动分析结束也不转入旧记录编辑。旧记录通过显式编辑入口修改，保存使用同一 ID 和返回的修订号。点击索引或当前笔记内的 AI 来源只按 entry ID 滚动定位，不卸载编辑器、不清草稿、不询问离开。空白输入区离开不提示，返回总览、打开其他笔记或改为编辑另一条记录时仍保护未保存修改。
• 打开笔记后页面一级标题仍为“魔法笔记”；笔记标题只在记录流顶部出现一次，使用 22px 的可编辑大标题，悬停显示下划线，聚焦显示强调色下划线，保留失焦保存、Enter 与 Escape。标题上方为吸顶的细工具栏，依次放置收起笔记列表、记录索引、条数与更新时间、AI 评论开关，均为带工具提示和可访问名称的图标按钮。记录流左右留白 24px（窄于 600px 时 12px），正文最大宽度 880px 并居中；吸顶工具栏不受此限制，始终铺满记录流宽度，AI 开关贴在右边缘，底部分隔线横贯整栏。
• 桌面笔记详情的列表标题行、正文工具栏与 AI 评论方向标签行顶部对齐，首行统一使用 40px 控件高度并垂直居中；AI 区域不叠加面板和表单的顶部留白。
• 文字记录的新建与编辑区域铺满卡片内沿，格式工具栏紧接头部，输入区域紧接工具栏；编辑器外层不再增加内边距或圆角。正文保留编辑器内部的文字留白，底部操作栏独立保留内边距与顶部分隔线；画布仍保留 12px 内容间距。
• 新建记录输入区空闲时收成一行虚线提示框，隐藏类型切换、格式工具栏和保存栏；聚焦、已有草稿、选择画布或出现校验错误时展开，初始约四行并随内容增高。保存成功或切换笔记后恢复为一行。此规则不作用于旧记录编辑器。
• 已保存记录的 AI 分析、编辑、删除为 28px 图标按钮，精细指针设备上悬停或键盘聚焦记录时才显示；删除悬停时使用危险色，确认条保持原样。粗指针设备始终显示。笔记内部列表、记录流、AI 区域和文字编辑区在精细指针设备上使用细原生滚动条，轨道透明；强制颜色与粗指针设备保留系统默认。说明、摘要和输入提示使用 --font-body 与 --text-secondary，时间和短标签保留 --font-caption。
• 左侧记录索引默认收起，只在用户展开后记住展开状态；展开宽度默认 168px，可拖动右边界在 140–320px 内调整栏宽，缩略图随列宽等比适配。开关位于笔记工具栏，提供 aria-controls、展开状态和动作提示；收起后完全移除索引列、分隔条、间隙、边框及轨道，不占宽度，隐藏内容不可聚焦。右侧 AI 评论独立显示、滚动和收起，不与索引共享页签。每条记录一个导航项：画布显示真实首页缩略图及总页数，文字显示摘要，两者均显示类型和时间。两侧分别记住桌面展开状态和宽度，共用原有布局偏好；宽布局分隔条共用样式及 separator 语义，方向键每次调整 16px，Home、End 跳到当前上下限。两侧宽度按可用空间协调限制，为主区保留至少 300px，窗口缩小时不覆盖保存的偏好。内容容器不超过 800px 时索引默认隐藏，由同一标题栏按钮开闭标题栏下方固定 168px 的抽屉，不显示调宽分隔条；标题栏自身保留控件高度，不保留轨道。选择记录或按 Escape 后关闭，Escape 将焦点返回开关。AI 移至底部，高度不超过可用布局的 40% 且最多 280px，不显示分隔条。 AI 评论默认不占列：当前笔记已有评论、正在分析或存在草稿评论时自动展开；用户对该笔记手动收起后保持收起，直到发起新的分析。无评论时手动展开即视为固定，固定状态跨笔记和重启保留，再次收起即取消固定。AI 评论的唯一显隐入口位于笔记工具栏右端，使用紧凑面板图标按钮；展开时应用共享选中样式，图标随显示或隐藏动作切换，并提供对应的工具提示、可访问名称、aria-expanded 和 aria-controls。评论面板内部不再显示重复的“AI 评论”标题或隐藏按钮行，保留区域的可访问名称、评论方向选择及各记录的分析操作。
• 笔记详情的内部记录索引使用透明底色，与主内容表面连续，仅保留细调宽分隔线。每条索引记录保留 1px 的 --border-subtle 淡边框，不加卡片底色或阴影，悬停使用轻微次级底色；选中记录使用淡蓝背景和左侧 3px 蓝色内侧标记，悬停时保留选中态。缩略图保留纸张边界，键盘焦点环与强制颜色模式选中边框保持可见。窄屏抽屉使用不透明的主内容表面，避免下层正文透出；深色主题沿用语义令牌。
• 笔记详情的标题、正文和记录流不再包裹额外的大外框，记录流容器只保留上述左右留白；缩略图列表顶部与正文区顶部对齐，左边界与索引栏左边界对齐，仅在右侧和底部保留 8px 留白，键盘焦点环向内绘制以避免滚动容器裁切。每条已保存记录使用一层 1px 的 --border-subtle 淡边框和 --radius-control 圆角，保留透明底色与记录间留白，不加阴影或头部下划线。记录编辑时保留输入区边框、页面安全边距及 AI 区域分隔。此规则仅作用于笔记详情，笔记列表与待办保持独立布局。
• 画布新建、编辑和只读态统一保留 12px 内容间距；详情中已保存画布去掉预览外框和工具栏底色、下划线，保留灰色画布衬底与白色纸张，编辑态保留编辑器边框。记录头部操作按内容宽度排列，空间不足时自然换行。文字新建的保存区与编辑器属于同一卡片，空白编辑区使用最小高度，不随容器百分比高度拉长。文字工具栏图标、菜单和原生滚动条须跟随主题。
• 标签使用中性胶囊样式（--surface-subtle 底色、--border-subtle 边框、--font-caption），不使用颜色区分。总览搜索框下方是标签筛选行：“全部”加各标签和对应篇数，均为 aria-pressed 切换按钮；可以多选，多选时只显示同时带有全部所选标签的笔记。选中时使用 --accent-subtle 底色和强调色边框。卡片最多显示 3 个标签，其余合并为“+N”。打开笔记后，左侧列表不显示筛选行，只显示“已筛选：A · B”提示条和清除按钮。
• 笔记标题下方是标签编辑行：已有标签后带 × 移除按钮，末尾是虚线“+ 标签”按钮。点击后展开组合框，按输入内容过滤已有标签，也可以新建。方向键切换选项，Enter、逗号或中文逗号确认，Escape 关闭并把焦点还给“+ 标签”。达到 10 个时，“+ 标签”禁用并说明上限。
• 列表标题行右侧只放“管理标签”，不再放 + 新建按钮。“新建笔记”统一放在页头右上角，是主按钮，始终位于“切换到待办 / 切换到笔记”或“返回总览”的右侧。打开笔记时点击，桌面端展开左侧列表并显示标题输入，窄屏先回到列表。“管理标签”在总览显示图标加文字，打开笔记后只显示图标。点击后打开共享 custom-task-dialog 对话框，按使用篇数列出标签，每行提供重命名和删除图标按钮。重命名在行内编辑；新名称与已有标签相同时，提示保存后会合并。删除在行内二次确认，并说明涉及的篇数。Escape 依次退出行内编辑或确认，最后关闭对话框。
• 整篇笔记的置顶、取消置顶和删除放在列表行的“更多”菜单，打开详情时仍可操作，标题编辑区不重复提供入口。按钮在悬停、键盘聚焦或菜单展开时显示，触屏设备常显；菜单沿用会话列表样式，通过 Portal 避免滚动区域裁切，支持方向键、Home、End 和 Escape。删除在菜单内二次确认并说明笔记标题及全部记录；删除当前笔记还须处理未保存草稿，删除其他笔记保留当前内容与草稿。打开菜单不切换笔记。
• 左侧“魔法笔记”入口可显示未完成待办数量。数量为 0 时隐藏徽标，超过 99 时显示 99+，可访问名称仍说明精确数量；勾选、取消勾选以及 Agent / MCP 对笔记清单的写入都必须刷新数量。
• 未完成待办徽标的高度不得超过主导航图标；数量从 0 变为可见或再次隐藏时，主导航项行高和相邻菜单位置必须保持不变。
• 在待办面板勾选或取消勾选后，当前缓存中的源笔记正文必须立即同步对应清单状态，不得依赖离开工作区后重新加载。
• Agent / MCP 或其他入口成功写入笔记后，已打开的工作台自动更新笔记列表、当前详情、待办及来源记录，不增加刷新按钮。保留仍存在的笔记与待办选择、搜索和筛选，以及未保存的标题、输入区和记录编辑草稿；普通后台刷新不重建编辑器。
• 外部删除当前笔记时，无草稿则返回总览；有草稿则保留编辑区并提示先复制草稿。外部删除正在编辑的记录时，同样保留该编辑器并明确提示记录已删除；保存失败不得清空草稿。
• 当前记录草稿非空或标题尚未保存时，返回总览必须先就地确认；编辑另一条记录等会丢弃正文草稿的操作沿用同一保护。继续编辑时保留草稿并恢复编辑焦点，只有明确选择放弃后才切换。
• 文字和画布记录保存修改成功后退出编辑状态，显示已保存正文；后续自动评论成功或失败均不重新打开编辑器。再次修改须点击编辑入口，以该修订的编辑器初始化内容作为修改比较基线。编辑器归一化不算用户修改，后续输入、画布变更和保存失败仍保留离开保护；同修订的后台刷新不替换已建立的基线。
• 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。
• 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。

13.8 设置中心

• 设置中心以整窗遮罩上的大 Modal 打开，保留底层工作区、会话草稿和助手工作栏，不切换一级页面。固定标题区和右上角关闭按钮，左侧分类与右侧内容各自滚动。关闭后返回原工作区并恢复入口焦点。
• 新建项目与项目设置弹窗固定标题、关闭按钮和底部操作区，仅表单内容滚动；滚动条不进入标题区，关闭按钮保留至少 40 × 40px 的点击区域。
• 项目弹窗通过 Portal 挂载到 document.body，避免侧栏内的弹窗与主窗口标题栏拖动区域重叠时，Electron 截获关闭按钮的鼠标输入。
• Modal 最大尺寸为 1200px × 900px，常规外边距为 24px；窗口宽度不超过 1020px 或高度不超过 720px 时接近全屏，保留 16px 外边距。左侧分类宽度依次为 220px、180px（宽度不超过 1020px）、120px（不超过 720px）；窄窗口仍保留左右布局，长分类名称可换行。内容区在可用空间内伸缩，最大宽度为 960px。
• 设置 Modal 通过 Portal 挂载到 document.body，复用共享背景隔离与焦点恢复机制。打开后聚焦关闭按钮，Tab 在弹窗内循环；Escape 先交由嵌套弹窗处理，设置自身的 Escape 与关闭按钮共用未保存确认，确认出现后再按 Escape 返回编辑。点击遮罩不关闭；保存、测试和清理数据期间禁止关闭。每次打开重新挂载设置，模型和消息通道等直达入口使用本次指定分类，普通入口默认打开 Agent Runtime。
• 设置中心不显示全局操作页脚，避免重复关闭入口和没有功能意义的整宽分隔线。
• 所有分类使用共享的 SettingsCategoryHeader 呈现分类标题、说明、错误与操作，不得在内容卡片内复制分类标题或创建页面专属操作栏。左侧分类名称与右侧标题来自同一份分类定义，新增分类时不得分别维护导航和内容标题。
• 左侧按“常规 / 模型与执行 / 功能与扩展 / 系统”分组，顺序与键盘导航一致。分类按钮最小高度 40px，只显示名称；分类说明集中在右侧页头，外层标题不再重复功能简介。组名使用辅助字号，普通项使用正文和中等字重，选中项使用强调底色与加粗文字。
• 设置区块使用共享圆角、间距和表面令牌；标题为 --font-section-title，持久说明至少为 --font-caption。嵌套设置区块以顶部细分隔线和留白组织，不叠加卡片背景与四周边框。“能力与工具”的上级页签使用默认 PageTabs 外观，与 MCP 内部的分段页签区分。
• 当前分类存在“保存”或“测试”等未提交配置操作时，统一放在分类页头右侧；主保存操作在最右侧，测试等次操作排列在其左侧。
• 自动生效、仅执行即时命令或自行管理编辑流程的分类不显示全局保存操作。窄窗口下操作区可以换行，但保存入口必须保持清晰可见。
• 智能心跳的单条配置不在设置中心重复管理。设置中心如需呈现平台级说明，只提供 “打开智能心跳”导航，不复制创建、暂停、恢复或删除表单。
• 保存或测试成功统一进入应用通知视口，并按全局规则自动消失，不在分类页头或内容卡片中保留持久成功文案。加载、保存和测试错误显示在分类页头下方，并保留可处理的上下文。
• “模型连接”的认证字段按“认证方式 → API Key → 凭据状态”排列；只有选择 API Key 时显示输入框。已保存的 API Key 属于该连接，修改模型服务地址或临时选择“无需认证”不得自动清除，也不得要求重新输入；仅由明确的“清除凭据”或“删除连接”操作移除。
• “模型连接”页头在保存操作下方，将模型类型页签与全局模型下载源入口放在同一行；当前来源文字与“模型下载源”次按钮整体右对齐，窄窗口保持同行，空间不足时导航行可横向滚动。按钮打开挂载到 document.body 的 Portal 弹窗，复用共享 Modal 焦点管理；弹窗内使用 fieldset、持久 legend 与整行可点击的原生 Radio 卡片，选中状态同时依靠 Radio、边框和背景表达。Radio 只修改草稿，点击“确认”才保存；取消或关闭不改变已保存来源。读取失败提供重试并禁用确认，不以默认值伪装已保存选择；保存失败保留草稿并允许确认重试，保存期间禁止重复提交和关闭。向量、语音和 OCR 的更换下载源入口直接打开模型连接页的同一弹窗，跨分类时沿用未保存修改保护。详细规则见模型下载源设计。
• 设置中的连接列表与详情共用 .model-connection-manager，按容器可用宽度响应：不超过 640px 时上下排列，列表内部滚动高度最多 180px；更宽时恢复左右排列。LLM、向量连接和角色编辑复用此规则，不以整窗宽度代替表单宽度。接口协议的中英文当前值须完整可读。回归范围见窄容器布局修复记录。
• “保存并测试模型”必须在保存后发送一次有界的真实模型请求。文本连接校验本次随机测试文本，图像连接校验实际返回的内联图片；仅收到成功 HTTP 状态、模型列表或健康检查响应不算测试成功。界面持续说明该操作可能产生少量服务商用量费用，成功反馈明确写为“真实生成测试通过”。
• 所有显式保存的设置草稿都参与离开保护：关闭、切换分类、主侧栏或工作区导航及托盘导航不得静默丢弃，统一通过设置中心的就地确认提供继续编辑与明确放弃入口，保存失败后保留输入。“平台功能 / 通用设置”承载全局快捷唤起的共享 Switch、可访问 accelerator 录制输入、恢复默认、保存及注册、停用或冲突状态，不新增分类或页签；注册或持久化失败时保留上一组可用快捷键和当前草稿，保存或停用成功后同步更新输入区的快捷键提示。
• “平台功能 / 通用设置”同时提供默认开启的“在会话中渲染 HTML”持久 Switch。说明必须 明确该能力只生成禁用脚本、联网、表单提交和窗口操作的静态预览；保存成功后当前会话立即 更新，保存失败时保留最后确认状态。
• 通用设置按快捷唤起、会话与通知、工作目录分组，复用现有卡片。“桌面通知”为默认开启的持久 Switch，保存后立即控制窗口未聚焦时的任务完成、失败和取消系统通知，关闭不影响应用内通知。旧配置缺少该字段时默认开启，明确关闭后重启仍保持关闭；保存失败保留最后确认状态并显示应用内错误通知。
• “平台功能”使用共享 PageTabs 区分“通用设置”和“远程项目”，默认进入通用设置。“远程项目”页将持久 Switch 与用户数据目录中的 Linux x64、Linux arm64、macOS arm64 Agent 包清单分成独立卡片；每张卡片与下载进度按平台和架构区分，不能把两个 arm64 目标合并。清单延迟到首次打开该页签时由 Main 完整校验，并读取所选更新源的小型签名目录，显示本地版本、在线最新兼容版本以及“有更新”“已是最新”“未下载”“校验失败”。打开页签或刷新不得自动下载 .gbagent；只有用户点击带目标版本的下载/更新按钮后才传输包。签名目录不可用时继续显示并允许导出已验证本地包，提供就地重试错误；清单不混入 Host 已安装状态、缓存路径或敏感签名细节。下载和导入期间保留上下文进度，成功进入全局通知视口。
• “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、同行帮助和原生单选下拉框放在同一行，用途说明收进 InlineHelp，并复用设置表单的统一控件样式；关闭启动检查后仍可选择更新源，手动检查继续使用当前选择。选项显示“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，添加与删除使用明确按钮和可访问名称。
• 魔法笔记设置统一从应用中心对应行进入；笔记页和全局设置不再提供重复入口。“显示未完成待办数量”持久 Switch 只控制左侧数量徽标，不改变待办数据。旧入口开关绑定业务启用值，迁为“启用应用”并保留原值，常驻使用独立配置。默认开启仅适用于未配置布尔值，只有独立显隐偏好才映射到常驻。此迁移规则见应用导航 PRD。
• 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 内容。
• 内置 MCP 中的“图片生成与编辑”是自动管理例外：该行始终可见，标记“内置 · 自动管理”，不提供独立启停、分配保存、移除或凭据编辑。直连 Model、OpenCode、Continue、DeepSeek Harness 的分配只由已保存图片模型的“允许 AI 在会话中调用”设置推导；至少一个开启则全部勾选，没有开启模型则全部取消。使用禁用的原生 Checkbox、Runtime 标签及关联说明，保留可聚焦的“前往图片模型设置”导航；远程适用范围通过 GoodBuddy Agent 说明持续可见。Ask、离线、无工具能力或调用错误不改变勾选。图片模型默认关闭会话调用；默认生图模型独立于普通默认连接，关闭或删除后保留失效选择并提示改选，不自动回退。

13.9 文档解析设置

现有本地解析与本轮 HTTP 扩展的实现边界见文档处理进度。 跨场景入口、附件菜单、共享预览及选图返回规则由文档处理 UI 设计维护； 当前接线与存储行为见生产实现说明。文档解析属于全局设置，不新增应用中心成员；本机推理监控只管理本地服务。

• 设置中心新增独立的“文档解析”分类，统一管理聊天附件、知识库导入以及后续文档审阅场景使用的提取、转换和 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 来源使用“本地模型 / 远程服务”互斥选择，远程为 HTTP PaddleOCR-VL；MinerU 不在本轮范围。来源切换保留两套配置，未保存时禁止测试。来源配置、保存和测试规则见文档解析设置设计，不另加逐文件授权区。
• 用户配置并保存远程 OCR 服务即表示选择该处理路径，不再逐场景重复询问。界面仍须明确显示当前服务名称、处理范围和远程属性，API 密钥只保存在主进程加密设置中，未选中远程服务时不得上传文档。
• 解析结果使用统一文档结构，保留文档标题、来源格式、页码或工作表定位、正文块、处理方式和警告；置信度仅在解析器提供时显示，缺失不补造。聊天文档附件保留完整解析文本，超过暂存容量时报错；知识库使用完整结果分块和索引，具体要求见文档处理 PRD。普通图片默认走图片输入，显式 OCR、原图保存和文档选图遵循该功能的规划规则。
• 测试结果显示文件类型、页数、实际工作流、提取字数、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，清除内联浅色样式并补齐窄窗口单面板流程。
• 监督者使用 supervisor，工作回顾读取统一监督结果；智能心跳包含 Global / 多 Project 心跳计划、监督建议与历史心跳报告；活动记录显示统一执行，设置只保留算法参数。
• 在现有工作栏中完善任务中心，统一范围、状态、最近进展和筛选，不新建平行任务平台。
• 活动记录迁移到 dashboard，统一导航、筛选和表格行为。
• 设置中心使用共享分类定义与 SettingsCategoryHeader，将保存与测试操作统一放到分类页头右侧，并把成功反馈接入应用通知。
• 文档解析设置统一聊天附件与知识库的解析预设、OCR 状态、转换状态、隐私限制和真实文件测试。

15.5 验收

执行与取证方法见 Electron UI 自动化测试规范，包括真实 Portal、原生键盘、计算样式与 PNG 审阅；视觉 fixture 与完整生产 App 的结果须分别标注。

• 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
• 在大于等于 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"，并保留明确的恢复操作。