Skip to content

10-UI与诊断.md

Latest commit

 

History

History
184 lines (148 loc) · 18.3 KB

10-UI与诊断.md

File metadata and controls

184 lines (148 loc) · 18.3 KB
Raw
doc-id 10-ui-diagnostics
title UI 与诊断
status active
version 2.1.0
last-updated 2026-08-29
source-range 规格书 §2.4 第 3 条、§18、§18.1–§18.3、§22；v1.1 Agent 工作台与变更审阅；v1.2 多目标工作台；v1.3 品牌视觉、双语与逐目标编辑；v1.4 低密度 Agent 布局与入口层级；v1.5 源码快捷入口与开源传播；v1.6 深色原生选择控件；v1.7 工作区健康、显式同意与渐进增强选择器；v1.8 工具轮次活动与精确错误诊断；v1.9 直接运行、可选能力诊断与严格 CSP nonce 继承；v2.0 可拖拽浮动工作台与灵动岛入口；v2.1 持续 Shell 与真实状态动效目标
参考文献/依赖
03-public-api-models
05-runtime-lifecycle
06-source-resolution
07-dom-css-collection
08-code-prompt
09-local-protocol-security
12-testing-acceptance
15-risks-adr
16-ai-agent-execution
17-model-provider-credentials
21-floating-workbench-island
22-persistent-shell-motion-system

UI 与诊断

Shadow DOM

  • 工具 UI 使用 Shadow DOM，与业务 CSS 隔离。

UI marker 只在本文件定义：

export const UI_MARKER_ATTRIBUTE = "data-spotpatch-ui" as const;
  • host：<spotpatch-root data-spotpatch-ui>
  • mode：open，便于自身测试和可访问性检查。
  • 全部样式写入 Shadow Root。
  • 页面现有 script[nonce] 只有一个非空唯一值时，Runtime 将该值传播到全部 Shadow Root <style>；无 nonce 或值有歧义时不猜测、不放宽宿主 CSP。
  • 高亮层 pointer-events: none。
  • 工具栏层级使用统一常量，不散落魔法 z-index。

选择器必须引用 UI marker 排除工具节点 (见 doc-id:05-runtime-lifecycle)。该方案的架构决策见 ADR-004 (见 doc-id:15-risks-adr)。

组件最小集合

  • BrandMark：使用随插件打包的 SpotPatch 矢量标识；紫蓝青渐变只承担品牌识别，不依赖远程图片，也不重复朗读旁边的品牌文字。
  • Trigger：启用/停用选择模式。
  • HoverHighlight：选择模式下高亮当前候选，不代表已加入目标集。
  • SelectionHighlights：为全部已选目标显示持久编号边框，活动目标使用更强视觉层级。
  • TargetList：按选择顺序显示编号、组件/元素名、源码位置、采集状态、说明状态和逐项移除按钮。
  • TargetEditor：只在活动目标卡片内展开，直接编辑该目标自己的修改说明；折叠项仍显示是否已填写。
  • ContextWorkbench：选中后立即显示目标列表和活动目标编辑器，不经过二级“添加说明”流程。
  • ContextSummary：组件、文件、置信度、警告。
  • PreviewPanel：完整 Prompt 预览。
  • ProviderStatus：展示脱敏连接与工具能力状态。
  • WorkspaceHealth：展示本地 Git 可执行性、变更分类计数和阻断原因；本地修改纳入同意与 provider 数据传输同意必须是两个独立控件。
  • ModelSelector：使用原生 <select>，只选择可信配置登记的 provider/model profile；保留系统键盘、读屏和触控语义。
  • ExecutionModeSelector：服务端公开可信极速能力时，使用原生 <select> 提供“审阅 / 可信极速”并默认审阅；不能提供服务端未授权的模式。
  • AgentProgress：展示当前阶段、有界工具活动和取消入口。
  • DiffReview：展示文件列表、完整 Diff、检查结果和 Apply/Revert 门禁。
  • RepositoryLink：在品牌标题区提供官方 GitHub 仓库入口，不抢占任务主操作。
  • EditorStatus：显示打开中、成功或失败；状态变化通过 aria-live 宣告。
  • Actions：追加元素、复制、重新选择、打开活动目标源码、关闭。

状态流转由 Runtime 状态机唯一规定 (见 doc-id:05-runtime-lifecycle)，Prompt 内容和顺序由 Prompt 规范规定 (见 doc-id:08-code-prompt)。

上下文工作台定位与交互

  • 灵动岛入口默认位于右下角安全区域；用户可以拖拽灵动岛或展开工作台的标题栏改变位置。位置、拖拽、吸附和会话恢复的唯一详细规范见 (见 doc-id:21-floating-workbench-island)。该部分 Runtime 实现与单元校验已完成，真实 Chromium 视觉验证仍是发布前 Gate。
  • 当前 Trigger、Planner 与 Execution Island 已收敛为同一个 fixed Shell 内的互斥 Scene；“Pill → Capturing → Planner → Receiving → Handoff → Running → Result”只消费真实状态。Execution Island 复用现有 SpotPatch Logo，以 62px Compact 为默认形态，右侧保持“状态点 + 状态文字 + 真实计时 + 详情入口”，并由独立 GSAP Motion bundle 编排连续 Morph、文字切换和一次性 1px 品牌光扫。代码与自动化 Gate 已完成，真实 Chromium 视觉/性能验收仍待补；详细边界见 (见 doc-id:22-persistent-shell-motion-system)。
  • 选中元素后，工作台保持用户浮动锚点并向可用视口空间展开，不再读取活动目标矩形决定面板位置，也不显示指向选区的三角锚点。
  • HoverHighlight 和 SelectionHighlights 继续跟随元素滚动、ResizeObserver 与 DOM 几何变化；它们只表达元素关联，不能反向修改浮动工作台位置。
  • 工作台宽度和高度必须受当前视口约束；内容超出时只滚动工作台正文，标题、主操作与关闭入口保持可用。
  • 工作台显示期间，紧凑灵动岛必须从可见与可访问树中退出，由同一浮动表面呈现工作台；收起、选择或追加选择时再投影对应入口状态，不能保留两个重叠的可操作主入口。
  • 选中元素后立即展开并聚焦该目标的说明输入框。每个目标拥有独立草稿；点击另一目标只切换活动编辑器，不复制、拼接或覆盖说明。Preview/Run 在任一目标说明为空、整组说明超过公共总字符上限或上下文尚未满足要求时保持禁用；无需 Add note、Save note 或等价中间确认。
  • Add element 进入追加选择态并暂时隐藏工作台，但保留每个已有目标的草稿、编号和持久高亮；新目标以空说明加入并成为活动项。Reselect 明确表示清空全部目标重新开始，两者不能共用模糊文案。
  • 关闭入口只隐藏工作台，不得删除已经采集的目标或逐目标说明；再次打开恢复原活动项。页面导航后，已卸载目标不再显示几何高亮，但目标卡、页面来源、说明和 Preview/Run 能力继续保留；用户可在新页面通过 Add element 追加目标。
  • TargetList 必须同时显示“当前数量 / 配置上限”“已填写数量”和“整组说明字符数 / 总上限”；总字符超限必须显示文字和错误色，并保持 Preview/Run 禁用。重复选择不得生成第二项，达到目标上限时保留原集合并通过 aria-live 说明原因。删除一项只删除该项目标与说明，不影响其余草稿。
  • 多个目标分散在页面时，切换、追加或移除活动目标都不能改变工作台位置。所有持久高亮 pointer-events: none，不能遮挡后续选择。
  • 诊断信息必须完整保留，但视觉层级低于目标说明与主操作；源码位置和上下文就绪状态应在工作台首屏可见，完整诊断默认折叠，展开后在受限高度区域滚动查看。
  • 每个具有 source marker 的目标行都提供可读的源码快捷按钮，按钮名称必须包含稳定目标序号；底部按钮继续打开活动目标。点击目标按钮时同时激活该目标并复用同一打开流程。没有 marker 的目标只显示不可用状态，不猜测路径。
  • 打开源码是独立的只读导航能力：Agent 运行、审阅或 Apply 后均不得仅因编辑区锁定而禁用。Apply 后 UI 释放旧 DOM 高亮，但保留 source marker；打开失败必须显示可见、双语、可操作的错误，不能只有屏幕阅读器提示或控制台日志。
  • Preview prompt 和 Copy prompt 是各自状态的唯一主操作；打开编辑器、重新选择和返回编辑属于次级操作。
  • AI 未启用时，Preview prompt 保持主操作。AI 已启用且上下文、传输同意和工作区健康门禁满足时，Run AI 可以直接启动真实隔离会话，不以预先 capability probe 作为启用条件；显式探测通过后可强化其主操作层级。Preview prompt 始终作为明确可用的本地回退，不能被隐藏。
  • Provider、Model 与 Execution Mode 继续使用语义化原生 <select>。支持 customizable select 的 Chromium 使用 appearance: base-select 与 ::picker(select)：弹层从字段下缘留出小间距展开，圆角、深色表面、选中态和箭头旋转与面板一致，并用 :popover-open、@starting-style 完成克制的展开/收回过渡；不支持时以深色 color-scheme 和原生 option 配色渐进降级。两种路径都必须保留键盘、触控、读屏、焦点环、禁用态和可访问名称；不得复制一套自制下拉状态机或把 option 替换为不可访问的普通 div。可信极速选项只在服务端能力为 trusted-auto 时出现，并始终默认选择 review。
  • Agent 配置区同时显示 provider capability 与本地 workspace health。“检查运行环境”并行刷新两者；真正运行前必须再次刷新。健康检查中、未检查、blocked 或尚未取得对应模式同意时 Run 保持禁用。review/auto 的 consent-required 使用独立本地修改复选框；trusted-auto 只显示一次完整的可信极速模式会话授权，并以同一授权覆盖有界本地修改纳入与跳过项目检查。blocked 文案必须映射稳定错误码，明确区分非仓库、Git 操作中、冲突、未跟踪项不受支持、规模超限和并发冲突。
  • 必须尊重 prefers-reduced-motion，核心反馈不能依赖动画完成。

视觉系统

工作台采用“专业开发工具”而非通用 AI 聊天框风格：哑光深色表面、清楚的信息层级、有限的品牌色和克制阴影。禁止扫描线、装饰网格、大面积霓虹发光、无语义渐变文字或为了“科技感”牺牲可读性的效果。业务页面只被高亮层覆盖，不能被工具背景或滤镜改色。

GitHub 入口使用文字加识别图形的克制次级样式，桌面显示 GitHub，窄视口可只保留具备可访问名称的图形。链接固定新窗口打开并使用 rel="noopener noreferrer"，不带追踪查询、重定向或第三方脚本；推广目标是让已获得价值的开发者自然发现文档、Issue 与 Star，而不是打断修改流程。官方 URL 由公共常量定义 (见 doc-id:03-public-api-models)。

基础设计令牌在 Shadow Root 的 :host CSS custom properties 中集中声明，组件样式只引用这些令牌；颜色、圆角和主阴影不得在 Agent 面板、目标卡片等子模块重新维护另一套值。规范令牌包括：

令牌族 用途
--spotpatch-bg* 面板、抬升表面和输入区背景
--spotpatch-border* 常规与弱分隔线
--spotpatch-text* 主文本、辅助文本和技术元数据
--spotpatch-accent* 品牌主色、活动目标和焦点；青色只用于定位关联
`--spotpatch-success warning
--spotpatch-radius-*、--spotpatch-shadow-panel 面板/卡片圆角和唯一主阴影

尺寸与密度硬约束：

  • 桌面工作台最大宽度以当前实现的 460px 作为首轮视觉验证基线，最大高度以当前实现的 620px 为基线并受动态可视视口约束；最终值只在浮动工作台集中布局令牌中校准。Agent provider/model 在全部视口保持单列以降低信息密度；窄视口切换为受限底部布局并保留安全边距。
  • 主标题不小于 24px；目标组件名不小于 15px；目标说明与 provider/model 控件不小于 14px；说明性正文与 Agent 摘要不小于 13px；只有路径、计数、工具活动等技术元数据可使用 11–12px 等宽字体。
  • 活动目标说明区最小高度 116px，卡片间距不小于 10px；provider/model 控件高度不小于 44px，底部操作按钮高度不小于 40px。
  • 目标标题、完成进度、总字符预算和目标数不得挤在同一行；标题/数量与进度/预算分两层呈现。完整诊断与 Agent 细节按需展开或在正文区滚动，不能把主操作推出视口。
  • 动画只允许由集中 motion token 控制的颜色、边框、轻微位移和浮动表面展开反馈；完整持续 Shell 与 Agent 动效按 (见 doc-id:22-persistent-shell-motion-system) 执行，具体时长与曲线在完整 playground 验证后收敛，不能散落到组件。prefers-reduced-motion 下移除非必要过渡。

界面语言

  • Runtime 内置类型完备的 en-US 与 zh-CN 消息表，固定 UI 文案、可访问名称、错误码和状态名必须从当前消息表读取；组件中禁止散落双语条件表达式或硬编码固定文案。
  • 初始语言使用公共 locale 配置及 auto 解析规则 (见 doc-id:03-public-api-models)。工作台标题栏始终提供显式语言切换，不要求刷新页面。
  • 语言切换必须同步更新标题、按钮、目标状态、字符预算、provider 同意说明、Agent 固定状态、错误码和 Prompt 固定标题；不得清空目标、逐目标草稿、当前 provider/model、同意状态、Job 或 Diff。
  • 组件名、相对路径、代码、CSS、用户逐目标说明、provider/model label、check label 与服务端自由文本属于项目或协议数据，不做猜测翻译。错误码和公共枚举状态使用本地消息表翻译，避免切换语言后保留旧语言缓存。
  • Runtime 不依赖也不修改宿主 i18n、localStorage 或业务语言状态；全部样式和语言行为仍在 Shadow DOM 边界内。

Agent 工作台

  • 页面 UI 不提供 URL 或 Key 输入框；只显示可信配置中的 provider/model label。真实 provider 模型名、Base URL 和环境变量名不得通过 tooltip、DOM attribute 或诊断详情暴露 (见 doc-id:17-model-provider-credentials)。
  • 首次向一个 provider profile 发送项目内容前，必须展示远程传输说明和中转站信任提示，并取得当前 Vite 会话内的显式同意；拒绝后继续提供本地 Prompt。
  • 运行按钮旁必须显示当前模型；任一目标说明输入框中的 Mod+Enter 等价于一次明确运行，不得在输入、选择、切换活动目标、切换语言或模型切换时自动发起请求。
  • 运行态依次呈现准备隔离环境、分析、工具调用、验证和生成审阅结果。工具活动只展示工具名、相对路径或 check label 和脱敏状态，不滚动暴露整段源码或命令环境。活动身份使用 turn + toolCallId，中转站跨轮复用原始 ID 时必须保留每一轮记录，不能覆盖之前的成功或失败状态。
  • 运行中提供明确 Cancel；取消后保留已脱敏诊断，不把部分 worktree 变更描述为已应用。
  • review 模式必须先展示修改文件、增删行、完整可滚动 Diff 和每项 required check。Apply 在状态、基线或检查不满足时禁用，并显示具体原因。
  • auto 模式必须持续显示醒目标识；一旦门禁不足则降级到 review，不用弹窗诱导用户跳过检查。
  • trusted-auto 必须显示“可信极速模式”而不是含糊的“自动”标识；用户必须先在页面主动选择该模式，授权文案再明确列出远程传输、当前本地修改、跳过项目检查、直接应用、文件删除和配置变更。用户未勾选时不能创建 Job；勾选后不再显示第二个脏工作区确认或 Apply 按钮，服务端写回成功后直接进入可 Revert 状态。切回 review 必须立即恢复带项目检查的审阅流程且清除不适用的可信同意。
  • Apply 成功后展示“已写入本地文件”和 Revert；Revert 因后续文件变化被拒绝时，明确提示冲突，不声称已经撤销。
  • provider、模型、工具循环、检查和变更应用是不同状态来源；UI 只根据服务端公共状态渲染，不能依据自然语言消息推断状态。
  • 工具参数 Schema 错误与同轮调用 ID 冲突必须显示不同的双语建议；不得再显示同时包含两个猜测根因的合并文案。UI 可以显示工具名和轮次，不显示原始工具参数、provider chunk 或源码正文。

Agent 行为与审阅门禁由 Agent 规范定义 (见 doc-id:16-ai-agent-execution)，公共 Job 类型见数据模型 (见 doc-id:03-public-api-models)，endpoint 和脱敏规则见本地协议 (见 doc-id:09-local-protocol-security)。

可访问性

  • 所有按钮有可读名称。
  • 每个目标切换和移除按钮的可访问名称必须包含稳定目标序号；TargetList 使用独立的区域名称，填写数量、总字符超限和失败状态不能只靠颜色表达。
  • 面板使用 role="dialog" 和标题关联。
  • 打开面板后保存先前焦点，将焦点置于活动目标说明输入框；切换活动目标、从预览返回或追加选择完成后聚焦对应目标，关闭时恢复先前焦点。
  • Escape 有确定行为。
  • 状态反馈使用 aria-live="polite"。
  • 不能仅用颜色表示置信度和错误状态。

日志与诊断

统一日志命名空间：

[spotpatch:vite]
[spotpatch:transform]
[spotpatch:server]
[spotpatch:runtime]
[spotpatch:react]
[spotpatch:agent]
[spotpatch:provider]

默认只输出：

  • 启动成功和快捷键
  • 不支持版本
  • 影响功能的降级
  • 安全拒绝的摘要

debug 模式增加转换耗时、选中解析路径、CSS 警告、Job 阶段、非敏感 request ID、provider 状态类别和检查退出状态，但仍不记录 token、Key、Base URL、真实 provider 模型名、源码正文、Prompt、Diff、工具参数、命令输出、表单值和绝对用户数据。

debug 选项由公共配置定义 (见 doc-id:03-public-api-models)，安全字段与日志边界以安全规范为准 (见 doc-id:09-local-protocol-security)。

诊断面板应显示：

  • SpotPatch 版本
  • React/Vite 版本
  • React Adapter 是否可用
  • 当前定位来源
  • CSS 采集 warning
  • API 连接状态
  • AI 是否启用及 capability 状态
  • 当前 provider/model label、Job 状态和 request ID（如有）

来源与置信度文案必须采用源码解析规范 (见 doc-id:06-source-resolution)，CSS warning 来自采集规范 (见 doc-id:07-dom-css-collection)。无障碍与 UI 行为由 E2E 验证 (见 doc-id:12-testing-acceptance)。