用预览、弹出窗口和命令面板（Command + K）完成键盘优先的剪贴板工作流

高效的剪贴板工作流包含三个时刻：找到条目、确认内容、把内容送到目标位置。

这三个时刻之间的距离，决定历史记录是否真正有用。Syzygy 把预览当作决策面，把命令面板当作导航面，把弹出窗口当作聚焦窗口。

每个界面只负责一件事。它们共享同一份内容计划，不会复制彼此的业务规则。

#一分钟完成一次操作

macOS 按 Command + K，Windows 或 Linux 按 Ctrl + K，然后输入页面名称或命令。

输入 > 进入命令模式。用方向键移动，按 Enter 打开选中的目标。

当前选中的剪贴板条目保持不变。内容需要确认时打开预览，预览需要更多空间时打开弹出窗口，完成判断后返回列表。

这条路径减少了常见操作中的上下文切换。它也让内容在粘贴前有机会先说明自己是什么。

#预览为什么需要合同

预览不能只根据文件名猜内容。同一个 .html 包装层里可能装着 Markdown、源代码或 SVG。

也可能装着 Figma 标记、位图和可见文字。Syzygy 会根据内容证据选择文档家族。

有文本表现时，计划包含文字表现；同时说明渲染方式、布局和可用能力。

预览层读取这份计划，检查已经加载的数据载荷，再输出预览描述信息。卡片使用描述信息。

检查面板和弹出窗口也使用这份描述信息。任何界面都不会重新维护 MIME 表，也不会因为有按钮就创造能力。

任何界面都不会用传输层包装层替换语义源内容。

#用户能看到的渲染器

普通文字以可读文本打开。Markdown 按 Markdown 打开。源代码使用语法高亮。SVG 以图形打开。

数据载荷带有源文本时，SVG 源内容仍然可用。Excalidraw 以画布打开，Excalidraw JSON 仍然可以用于源内容操作。Figma 剪贴板源内容保留自己的标记。

二进制 Figma 文件以视觉文件打开。位图以图片打开。PDF 以文档打开。Office 文件以文档打开。

归档文件（Archive）以列表打开。富 HTML 通过安全 HTML 界面打开。混合 HTML 显示能够证明的文字和媒体。集合先打开文件网格。

未知二进制使用安全占位符。列表保持一致，渲染器随数据载荷改变。

#卡片、检查面板和弹出窗口

卡片为列表提供紧凑预览，检查面板为一个条目提供更多空间，弹出窗口为一个条目提供聚焦窗口。条目身份保持不变。

内容计划和操作能力保持不变，改变的只有布局。一个共享预览层负责内容展示。

模态层负责对话框外壳。弹出窗口会校验选中条目的身份并加载当前快照。

它加载内容，并报告超时、无效快照或本地化错误。

弹出窗口不会把错误静默变成空白预览。关闭路径保持可用，键盘焦点会返回调用方。

#命令面板（Command + K）从意图开始

命令面板包含页面入口、分组入口和命令入口。每个入口都有稳定身份。

每个入口有标签、描述和别名。搜索会比较翻译后的标签。

它会比较描述和别名。查询不区分大小写，查询两侧的空白不改变结果。

空查询返回完整列表。命令模式会缩小同一列表，列表保持键盘可达，选中行保持可见。

Enter 执行选中入口，Escape 关闭面板。页面负责后续导航，面板负责表达意图。

#上一次入口放在第一项

面板只记住上一次成功执行的真实入口，并在下次打开时把它放在第一项。这个入口可能是一个页面、一个分组或一个动作， 显示文字会随着当前语言更新，但它仍然指向同一个可执行目标。用户不需要重新输入完整名称，也不会看到一个无法点击的“幽灵命令”。

记忆保存在当前设备的本地界面状态中，不会加入剪贴板历史，也不会同步到其他设备。面板打开时会检查入口是否仍然存在、当前账号是否有权限、 以及所需内容是否已经在本地。如果检查失败，面板回到普通列表，用户仍然可以搜索其他入口。浏览器禁止本地存储时，面板仍然可以正常执行命令， 只是不会显示最近入口。

只有成功完成的入口才会更新记忆。用户按下回车后如果页面加载失败、内容仍在等待下载或动作被权限拒绝，原来的最近入口保持不变，避免一次失败操作污染下一次启动。

#快捷键不是操作权限

面板可以展示页面和动作入口，真正能做什么仍由能力计划决定。运行时仍会检查本地内容。

运行时仍会检查服务提供方配置、功能开关和平台剪贴板。Enter 不能绕过这些检查。

界面会报告缺少的前置条件。它不会在后端完成前假装成功。大项目下载时，这条边界很重要，下载可以在后台执行。

本地条目仍然可以复制，本地文件仍然可以外部打开，命令面板仍保持响应。

#预览中的远程图片

Markdown 使用标准图片语法。

![远程产品图片](https://your-domain.example/assets/product-image.jpg)

HTML 使用图片元素。

<img src="https://your-domain.example/assets/product-image.jpg" alt="远程产品图片">

网页内容渲染器可以展示这两种形式。图片链接是展示资源，不是剪贴板写入，也不是文件下载命令。

它不能证明完整图片字节已在本地。剪贴板 HTML 图片物化使用另一条后端边界，会规范化网址并校验协议。

它会限制重定向和响应大小，报告物化失败，并且不会注入半成品条目。

两条链路应保持分离。

#弹出窗口的焦点和键盘行为

打开弹出窗口会把焦点移动到对话框。对话框有标签和关闭控件，Escape 会关闭它。

背景层在调用方允许时可以关闭它。焦点返回触发弹出窗口的控件，预览不会把焦点困在不可达的子节点。 长文本在自己的内容区域滚动。

外壳不会滚动整个桌面窗口。弹出窗口会报告加载中、超时或错误。

每种状态都有可读文字。每种状态都有恢复路径。

#真实流程：检查一段代码

从浏览器复制代码片段。按 Command + K，搜索复制的条目并按 Enter。

阅读语法高亮源内容，打开弹出窗口，切换到源内容视图并复制准确的代码。

按 Escape 关闭弹出窗口，返回目标应用并粘贴源内容。预览可以避免把富 HTML 包装层粘贴到目标应用。

#真实流程：检查 SVG

从设计工具复制 SVG。打开命令面板，选中条目并确认图形预览。

打开源内容视图，检查标记；源内容能力存在时执行文本操作，复制源内容或渲染图。

选择保持明确。位图预览不会隐藏 SVG 源内容。

#真实流程：同步中的等待中文件

对端设备发送历史记录元数据头。元数据头显示标题和文件家族，内容块（blob）还不在本地。

预览显示等待中状态。用户选择下载，内容块（blob）传输在后台执行，历史事件更新读取视图。

预览解析器看到本地内容，渲染器变为可用，用户按 Enter，操作使用已本地化源内容。

前台面板没有等待整个项目。

#命令面板排查

#面板没有打开

检查平台快捷键、其他应用是否消费键盘事件、应用事件处理，以及网页视图是否拥有焦点。

检查当前窗口状态。快捷键不可用时，页面仍应提供可见入口。

#上一次入口消失

确认面板仍能读取本地界面记忆，并检查最近入口是否已经被移除或权限发生变化。无效记忆应回退到普通列表。

#Enter 打开错误目标

检查选中行标识和最近入口是否指向真实目标，确认导航使用当前选中行。

确认异步加载期间条目没有变化。

#弹出窗口空白

检查弹出窗口的选中条目、当前快照、本地化状态和渲染器描述信息。

检查弹出窗口报告的错误状态。错误状态比空白页面更有用。

#图片能显示但不能复制

图片可能仍然是远程资源。Markdown 渲染器只负责展示，剪贴板动作需要本地渲染图片。执行显式本地化。

资源通过协议和大小校验后再重试。

#预览排查

#Markdown 变成普通文本

检查内容家族、Markdown 渲染器、数据载荷是否完整，以及保留源内容的 HTML 包装层是否被识别。

预览解析器应该消费语义文本。

#源内容视图显示语法范围

语法范围属于 HTML 传输层。先提取语义源内容。独立 SVG 需要提取完整元素，Figma 标记需要归一化成同一种源内容形式。

没有语义源内容时才使用原始 HTML。

#集合选错文件

检查条目出现位置和内容哈希值，不能只按文件名定位成员，因为两个文件可能同名。

#常见问题

#命令面板（Command + K）会替代剪贴板列表吗？

不会。它提供从意图到目标的快捷路径。列表仍然负责选择具体条目。

#弹出窗口会复制一个新的条目吗？

不会。它使用当前快照的投影，历史记录条目仍然是唯一来源。

#弹出窗口可以强制打开等待中条目吗？

它可以显示等待中状态，但不能凭空创造缺少的字节，必须先完成下载或本地化。

#最近项记忆会同步到其他设备吗？

记忆使用本地界面状态，属于当前网页视图配置，不是剪贴板历史数据。

#最近项会变成新的命令吗？

不会。它保留真实入口的引用，不会创造第二条命令。

#图片链接为什么走另一条链路？

网页只需要展示网址，剪贴板写入需要本地字节和平台操作。两者的安全和生命周期不同。

#预览会下载所有远程图片吗？

网页可能让浏览器加载图片网址，剪贴板本地化需要显式后端操作。两种动作都应该让用户看得见。

#大项目同步时可以打开条目吗？

条目具备所需本地内容时可以。后台传输不应阻塞无关命令。

#预览类型来自扩展名吗？

类型由领域计划拥有。扩展名只是识别信号之一。

#为什么卡片和弹出窗口要分开？

卡片服务快速扫描，弹出窗口服务聚焦检查，两者消费同一个预览描述。

#用户应该能够验证的行为

每个主要页面都能用同一快捷键打开面板。上一次成功入口会在下次打开时出现在第一项。卡片与弹出窗口中的预览家族保持一致，Escape 会关闭当前覆盖层。

焦点会返回打开覆盖层的控件。等待中内容会显示状态，而不是空白界面。远程图片展示和剪贴板本地化保持为两项操作。

#新增预览功能的测试矩阵

测试纯文本、Markdown、源代码和 SVG 源内容。

测试带位图预览的 SVG、Excalidraw JSON、Figma 源内容标记和二进制 Figma。

测试位图、PDF、集合和等待中元数据头。

测试无效快照、渲染器超时、Escape 和焦点返回。

测试无效的最近入口记录、禁止存储的网页视图、远程图片网址和物化失败。

每个案例都应该得到清晰可读的状态。

#选择动作前看清内容状态

预览页顶部应先告诉你内容家族和本地状态，再列出动作。一个已经下载的 SVG 可以复制源内容或复制渲染图；一个只有元数据的 SVG 只能查看摘要并等待下载。 一个远程图片可以在网页中显示，但还没有经过剪贴板物化，因此“查看”和“复制”会呈现不同的状态。把这些信息放在动作旁边，比在失败后弹出模糊的错误更省时间。

用户在命令面板中选择的是意图，页面随后负责完成具体动作。选择“打开预览”只负责显示内容，选择“复制”才会触发平台剪贴板写入，选择“编辑”则需要完整的文字表现。 动作失败时，面板不应把失败入口记录为最近项；只有页面确认完成后，最近项才更新。这样，下一次按下快捷键时，第一项仍然是可靠的工作入口。

#远程图片的两种生命周期

网页渲染器可以让浏览器直接读取 HTTP 或 HTTPS 图片，浏览器负责缓存和显示。系统剪贴板需要另一条生命周期：后端先解码 HTML 实体，规范化网址，检查协议和重定向， 限制响应大小，再把完整图片保存到本地。两条生命周期互不共享成功状态，浏览器显示图片不代表剪贴板已经拥有图片字节。

当物化失败时，系统保留原来的剪贴板内容，不写入半截文件。用户可以稍后重试，或复制图片网址。这个结果看似保守，却能避免目标应用收到无法打开的伪图片。

#低干扰的焦点管理

打开弹出窗口后，焦点进入标题、关闭按钮和内容区域。用户可以用 Tab 在控件之间移动，长文本只在内容区域滚动；关闭窗口后，焦点回到打开它的按钮。 如果调用方已经失去焦点，窗口会在关闭前保存当前选中条目，重新打开时仍然回到同一条目。错误、超时和等待下载都使用可读文字，不依赖颜色或动画传达状态。

屏幕阅读器应能读出条目名称、内容家族、本地状态和当前动作。颜色预览需要文字替代，键盘操作需要可见焦点。弹出窗口的尺寸变化不应让按钮跑出可视区域， 移动设备窄屏时，操作菜单可以折叠，但复制、下载和关闭仍应保持可达。

#一个适合支持反馈的记录格式

遇到预览问题时，记录内容家族、来源（本地或远程）、是否已经下载、使用的入口、弹出窗口状态和最终错误。可以这样描述：“远程 HTTPS 图片在预览中可见， 点击复制后物化失败，原剪贴板保持不变”。这比“图片不能复制”包含更多可复现信息，也不会泄露图片正文。

对于命令面板问题，记录平台、快捷键、输入词语、选中入口是否为最近项、页面是否打开以及焦点最终位置。不要复制本地界面记忆或内部状态名称；支持人员需要的是用户可见的行为。

#最后一次完整走查

从一个纯文本条目开始，使用命令面板搜索、预览、复制，再打开弹出窗口并返回。接着重复 SVG、Markdown、PDF 和远程图片；每次都确认预览家族和动作能力保持一致。 在同步大文件的同时，打开面板选择已就绪条目，确认回车键不等待后台下载。清除本地界面记忆后重新打开面板，确认普通列表仍然可用；让最近入口失效，确认面板自动回退。

这套走查覆盖了日常使用、键盘访问、异步下载和远程资源四个边界。预览、弹出窗口和命令面板因此成为同一条清晰的工作流，而不是三个互相猜测状态的页面。

#前台动作和后台下载必须分开

大型项目同步时，下载任务可能持续数分钟。用户此时仍然需要打开命令面板、复制一段已经就绪的文字，或者关闭当前弹出窗口。把下载和前台动作放进同一个等待链，会让一次无关的回车操作继承网络超时；把它们分成两条任务线，前台就可以读取共享状态并立即执行自己有前置条件的动作。

sequenceDiagram
  participant U as 用户
  participant P as 命令面板
  participant F as 前台动作
  participant D as 后台下载
  participant S as 共享状态
  U->>P: 搜索并按回车
  P->>F: 提交已选入口
  F->>S: 检查内容是否就绪
  S-->>F: 返回可复制或需下载
  F-->>U: 执行动作或说明前置条件
  D->>S: 更新已接收字节和速率
  S-->>P: 刷新等待中状态

命令面板只记录成功完成的入口。用户选中一个仍在等待的项目并按回车时，面板可以打开该条目的状态页，但不能把这次失败记录成“上一次命令”。下载完成后，用户再次执行复制，系统才把动作视为成功。这个规则既保护最近入口记忆，也避免下一次打开面板时第一项继续指向一个无法执行的目标。

这条分工还能让诊断信息更准确。网络阶段记录连接建立、选中路径和传输字节，命令面板记录搜索、选中入口和最终动作，两者在同一时间线上通过条目标识关联。支持人员因此能够区分“下载没有完成”和“下载完成但复制注入失败”，而不需要用户重复描述一段模糊的等待过程。

#继续阅读

依赖渲染器前先读剪贴板内容类型。构建搜索快捷方式前先读索引器和 OCR 搜索。增加编辑命令前先读文本工作台和翻译。命令面板缩短意图到操作的路径，预览让你在操作前确认内容，弹出窗口提供空间，但不创造第二套产品。