你在电脑上复制一行地址。几秒之后，你想在使用移动流量的手机上粘贴它。这时，单纯确认两台设备能够互相探测 通还不够。同步还需要建立可信的数据会话，选择可用路径，把内容写入接收端的本地历史，并且让前台操作保持可用。Syzygy 把这些工作拆成几个可以观察的阶段：账号服务负责授权，设备交换历史元数据，传输层选择路径，调度器安排后台任务，接收端持久化结果，界面展示状态。
这种边界让一次同步的耗时有了可以检查的解释。网络 RTT 只是其中一段，不能代表整条同步链路。
从信任边界开始
Syzygy 以账号和本地节点作为起点。账号标识用户和设备成员关系，节点负责当前设备上的工作副本。配对会把另一个节点 加入可信集合。配对并不会让任何设备获得全部账号权限，服务端会在接受配对前检查角色和授权范围。 设备完成身份证明后，传输层才会承载加密帧。中继可以转发这些加密帧，但它不会读取剪贴板数据载荷。服务端 负责账号和配对决策，不会成为日常内容块传输的代理。你撤销一台手机的配对时，电脑上的本地历史仍然属于电脑。
撤销改变的是未来请求的授权关系。它不取决于两台设备上一次使用了局域网（LAN）、Tailscale 还是中继。
配对一台设备
在已经拥有历史内容的设备上打开设备页【Devices】，选择添加设备【Add device】。保持确认页面打开，再在另一台设备上打开配对页面。 两台设备都会显示可核对的身份信息。确认名称和身份后，为新设备设置一个你以后能认出的名称。接受前先查看同步模式。确认后，新节点 会先进行一次小型控制消息交换，交换成员关系和能力信息。接着，两台设备比较最近的历史元数据头。首次追赶不需要把所有 内容块一次复制完，接收端可以先显示等待中行。
你可以在项目归档仍在下载时完成配对。这个步骤把“建立信任”和“搬运大文件”分开了。
元数据头保存什么
一个元数据头会标识一条历史记录条目。它可以包含条目标识、创建时间、内容家族、标题、文件名和预览元数据。 它也可以包含标签名称、标签颜色和内容块大小。大文件的每个字节都不需要放进元数据头。接收端先把元数据头 写入本地读取视图，列表就可以排序和过滤。预览可以说明内容正在等待，标签编辑器也可以处理已经到达的元数据。 当你需要实际内容时，再按下下载。于是一个同步条目可以先出现图片或 PDF 的标题，之后再出现完整内容。
这两种状态不能混为一谈。条目已知说明元数据头到达，等待中说明本地还没有完整内容块。
实时和按需
实时模式适合小而新的内容。运行时会根据当前设备的预取策略判断哪些项目可以自动 本地化。在有效阈值以内的内容可以在后台准备。超过阈值的内容保留元数据头，直到你明确发起下载。按需模式把 内容块传输放在下载之后。手机使用计费流量时，大型设计导出和项目归档不会自动占满带宽。两种模式都允许元数据头 同步。它们也都允许更新标签、查看预览元数据和搜索已经到达的字段。
模式只控制自动本地化，不会把未完成的条目显示成就绪。等待中标记会一直保留到本地内容块 通过完整性检查。
大项目必须在后台运行
一个项目目录可能包含成千上万个文件。历史条目可能代表一个很大的集合，打开快捷面板【Quick Panel】不应该等待这个 集合。下载由传输后台任务持有，前台只读取共享运行时状态。回车键、复制和 打开等动作拥有自己的优先级，不会被无关的后台下载卡住。桌面端在有数据时显示已经接收的字节和当前速率。只有元数据头时显示 等待中，后台任务正在执行时显示同步中，本地持久化完成后才显示就绪。这种状态命名让操作变得安全。用户按下 回车键时，界面可以告诉他是“还需要下载”，还是“内容已经在本地可以复制”。
找到一条可用路径
传输层会从可用网络接口收集候选地址。候选可能来自本地网络、Tailscale 接口、公网地址、手动引导提示或中继 地址。候选地址只是选项，不等于当前会话。探测会检查对端设备 是否能在这条路径上回答，连接层会记录最后真正交换数据的本地和远端地址。诊断视图把不经过中继跳转的会话标记为直连。经过 中继转发加密帧的会话标记为中继。设备卡片还会展示已选择的远程地址、已选择的本地 地址和路径摘要。详细诊断会补充探测、握手、重试和传输时间。
局域网（LAN）、Tailscale 和中继
LAN 往往提供最小 RTT。探测成功后，运行时可以使用本地路径完成会话。Tailscale 可以在不同网络之间提供加密的 直连路径。地址看起来很远，并不能说明数据经过中继。手机运营商和家庭路由器都可能提供 NAT。两端同时处于 NAT 后，节点会尝试可用的穿透方式。如果直连交换失败，中继会提供另一条已认证的路径。后备 不需要重新配对，也不改变设备身份。
网络发生切换时，连接层会在使用新路径前进行验证。手机从 Wi-Fi 切到 5G 时，会话可能更换路径，但同步意图保持不变。
直连不等于本地
用户常把直连理解为同一 Wi-Fi。两个词描述的问题不同：局域网（LAN）描述接口或地址环境，直连描述会话最终采用的路径。 Tailscale 地址可以承载直连会话，公网地址也可以。中继在严格 NAT 环境下可能是最快的可用结果。 因此不要只看候选列表，也不要按 IP 地址前缀猜测路径。以已选择的路径和已选择的地址为准。 当你向支持人员反馈问题时，把这几个字段一起提供。它们比“我看到了一个 100.x 地址”更接近实际数据路径。
连接复用
每个条目都建立新连接，会反复支付发现和握手的成本。Syzygy 会保留健康的对端设备 连接，让多个操作共享它。第一次操作可能包含发现和握手时间。后续操作如果复用成功，就可以直接进入控制或内容块 阶段。连接池只保留健康会话。空闲或失败的会话会被移除，下一次任务可以创建替代连接。诊断视图会记录已复用 或新建的结果。重连不会被伪装成成功，失败尝试也会进入时间线。
这让一次慢同步有机会被拆解。你可以区分“每次都在重新握手”和“连接复用后仍然传输很慢”。
为什么 100 ms 探测会变成几秒同步
探测只测量一次很小的网络交换。同步还可能等待对端设备通告、候选路径探测、连接握手、队列、文件写入和读取视图刷新。 接收端写入大内容块时，磁盘耗时也会进入总耗时。事件流到达后，界面还需要在下一个事件循环中刷新可见行。 诊断时间线会分别展示队列等待、连接重试、内容块传输、接收端持久化和界面刷新。这样可以判断延迟来自网络还是本地工作。 总耗时是多个阶段的加总。把它直接当成 RTT，会让排障方向偏离真正原因。
一次同步的阶段
发送端创建同步意图，意图标识对端设备和条目。队列根据当前策略决定它什么时候可以执行。后台任务 获取新连接或复用已有连接，然后发送元数据头。接收端验证元数据头，把投影写入本地数据库。运行时根据 条目大小和策略决定是否请求内容块。允许传输时，接收端把数据块写入本地存储。完整内容通过校验后，接收端更新历史记录 投影。事件流通知桌面，桌面刷新可见行。
只有本地内容检查完成，条目才进入就绪。每个阶段都可以产生错误，每个错误都应该保留自己的状态。
调度器如何保护前台
全局同步调度器最多允许三个并发任务。单个对端设备同时只运行一个任务，避免一台设备独占整个队列。自动传输共享字节 预算，默认预算为 64 MiB。这个预算让手机在后台追赶时不会意外拉取全部历史。手动下载 表示更强的用户意图。队列会先持久化意图，再启动后台任务，重启后仍然能够继续。关闭快捷面板【Quick Panel】 不会误取消下载。再次打开面板时，界面读取同一份任务状态。
前台命令和后台传输各自拥有生命周期，这是大项目同步时保持可用的关键。
重试和超时
控制消息使用有界重试，当前等待序列是 0、250 和 900 毫秒。短暂丢包可以恢复，连续失败也不会让任务无限等待。 内容块连接使用五秒建连超时，最多尝试六次。每一次尝试都记录结果，调度器在预算耗尽后停止重试。任务会停在 等待中或失败，并给出可理解的原因。用户可以在条件改变后重新发起重试。 无限重试会掩盖坏路径，也会消耗移动流量。诊断中的重试数量可以和已选择的路径一起判断问题。
等待中条目可以做什么
你可以打开等待中行，查看内容家族、标题和预览元数据。你可以添加或删除标签，也可以把它移到回收站。你可以在需要时按 下载。你不能复制本地不存在的字节，操作菜单会显示这个前置条件。远程 HTML 中的图片尤其需要这条边界。浏览器可能已经显示远程图片，但系统剪贴板写入仍然需要本地已本地化图片。按回车键 不能绕过物化要求。界面会把缺少的资源状态展示出来，而不是注入不完整的剪贴板数据载荷。
手机流量和电量
手机与工作站的成本模型不同。按需可以把大型内容块放在明确的下载之后，元数据头交换仍然保持轻量。 设备可以先看到新的文字条目，不必先下载视频或归档。调度器限制并行任务，连接复用也减少重复握手。 用户可以在流量变化时停止手动下载。任务状态已经持久化，下一次可以从可恢复的位置继续。界面同时展示已选择的路径和 传输状态。用户知道数据正在走哪条路径，也知道当前是否正在写本地内容。
标签和删除状态
标签属于条目元数据，可以随着元数据头路径到达另一台设备。接收端保存标签名称和用户选择的颜色。标签 页面和条目标签片从同一份已保存颜色读取。等待中条目也可以完成标签更新，因为这一步不需要内容块。回收站 状态属于条目投影。恢复会产生可见的状态变化，永久删除会从本地历史记录和 搜索中移除条目。同步策略允许时，对端设备也会收到删除状态。内容块是否已经下载，不决定条目是否活跃。
慢同步怎么查
打开设备页【Devices】，找到对应对端设备卡片，先看路径摘要。确认已选择的路径是直连还是 中继，再复制已选择的远程和本地地址。打开详细网络诊断对话框，查看最近一次探测、连接复用、握手、队列等待、收发字节、确认、持久化和重试数量。 如果 RTT 稳定在 100 ms，而队列等待很长，问题更接近调度；若多次出现五秒建连超时，问题更接近候选路径或网络限制。 如果数据库已经有就绪内容，但界面晚几秒才更新，问题更接近读取视图或界面刷新。相同的总时长可能来自完全不同的阶段。
诊断信息的隐私
复制诊断摘要时，系统不会包含账号密钥和剪贴板正文。摘要可以包含对端设备关联标识、路径类别和计时字段。 原始模式可以显示 IP 地址，便于网络管理员比较 NAT 行为。分享前先确认接收者和用途，避免把地址发到公开渠道。 诊断信息会注明采集时间。支持人员可以用它对照重试、连接切换和最终状态。用户决定粘贴哪些内容进入工单。任何模式都不应该要求你附上 剪贴板文字或秘密令牌。
网络切换
下载进行时，手机可能离开 Wi-Fi。旧路径停止响应后，运行时会检测失败的交换。连接层验证新的候选路径，后台任务继续使用原来的 同步意图。队列不会因为路径切换创建重复条目。在替代路径启动期间，条目保持 同步中。诊断记录会展示切换，最终状态会落到就绪或失败。对端设备暂时离线时，任务仍然可以重试。只有 元数据头的条目仍然可用，等待内容的工作不会破坏已到达的元数据。
移除配对
在已配对设备列表选择目标设备，核对最后在线时间和身份后选择移除或 撤销。账号服务会记录这一变化。被移除的节点失去未来请求的授权。两台设备的本地历史不会因为撤销配对而自动删除。 如果你的目标是清理数据，请使用本地回收站和保留策略控件。如果目标是停止信任，请使用设备移除。 这两个动作解决不同问题。把它们混在一起，会让用户误以为撤销设备会清空自己的历史。
电脑到手机的工作流
先在设备页【Devices】配对手机，把手机设为按需。电脑复制一段短地址，等待手机出现对应的元数据头。打开等待中 行并点击下载。观察已选择的路径、已接收字节和传输速率。条目到达 就绪后打开预览，再按复制。电脑可以继续处理其他工作，手机也不会把电脑的全部历史拉下来。 这个流程把昂贵的步骤放在用户意图之后。用户先确认内容，再决定是否消耗流量。
设计文件的工作流
从设计工具复制 SVG 时，发送端会在可用的情况下保留语义源内容。接收端先得到元数据头，预览可以先展示图形状态。内容块 到达后，源内容视图仍然可以提供可编辑文字。需要视觉副本时使用已渲染图片，需要修改时使用源内容。 能力取决于本地内容表现。等待中元数据头不能提供尚未到达的源内容字节，点击下载 才能满足这个前置条件。任何编辑结果都会作为新的快照保存。原始条目保持独立，方便回到最初的设计内容。
远程图片的工作流
HTML 采集可能包含图片网址。元数据头可以先到达，预览在允许的情况下显示远程资源。系统剪贴板写入仍需要本地 已本地化图片。后台任务会校验网址协议、请求大小、响应大小和重定向边界。 下载完成并验证后，系统才会注入剪贴板。失败时保留原有剪贴板，不写入半截内容。 这让“页面能显示图片”和“设备能复制图片”成为两个可解释的状态。一个状态不再伪装成另一个状态。
配对成功但元数据头不到达
先确认两台节点都在运行，再查看对端设备最后在线时间。打开诊断，检查发现超时、连接复用和已选择路径的变化。 确认账号仍然列出两台设备，然后重试控制消息交换。如果路径仍不可用，再检查 VPN 或运营商 NAT。把摘要诊断提供给支持人员，不要为了复现问题而提交剪贴板正文。
元数据头到达但内容块一直等待中
先看同步模式和条目大小。按需需要手动下载，实时也可能因为大文件超过阈值而保留等待中。按一次下载，观察已排队、同步中和传输速率。 再检查字节预算、对端设备并发数和最终错误原因。元数据头到达并不证明内容块失败，等待中标记告诉你还缺哪个动作。
直连退回中继
以已选择路径为准，不要把候选列表当成实际结果。查看探测错误、接口变化、运营商 NAT 和 VPN 规则。 中继是有效的加密后备，RTT 可能更高，但不应该触发重新配对。只要中继能完成传输，信任关系仍然成立。 如果所有路径都失败，分享候选和重试时间线。网络管理员可以从失败发生的阶段开始排查。
下载期间回车键没反应
先确认选中的条目是否就绪。等待中条目需要下载，就绪条目则应该能够在另一个条目下载时复制。检查菜单显示的能力，再确认目标应用焦点权限。 快捷面板【Quick Panel】模式还需要确认系统剪贴板写入和粘贴注入的结果。前台命令应报告自己的错误，不应该等待无关的后台任务。若就绪 条目仍然被阻塞，请记录命令诊断事件。
常见问题
服务端会保存所有剪贴板内容块吗？
产品使用服务端处理账号和配对决策。日常可信设备同步由 P2P 传输承载，具体边界以你的部署和保留策略配置为准。
直连是否表示同一 Wi-Fi？
不是。直连描述会话路径，VPN 接口也可以跨网络承载直连会话。
等待中条目为什么有标签？
标签属于元数据头投影。设备可以在内容块到达前保存元数据。
可以强制所有条目自动下载吗？
请选择适合设备和网络的策略。等待中条目仍然提供手动下载，大型后台任务应该放在后台运行。
移除设备会删除它的本地历史吗？
不会。配对移除改变授权关系，回收站和保留策略才负责本地删除。
应该给支持人员什么？
发送复制出的诊断摘要、操作时间和最终状态。原始模式只有在适合分享时才附带，绝不要包含剪贴板文字或秘密令牌。
验证清单
配对两台设备，确认双方身份。复制短文本，确认元数据头到达，并确认手机可以复制就绪条目。复制大文件，确认策略要求时出现等待中。 点击下载，确认进度和速率会更新。把手机从 Wi-Fi 切换到移动数据，确认已选择路径可以变化。打开网络诊断，确认它对应当前操作。 比较第一次和后续操作的连接复用。把条目移到回收站，确认对端设备收到元数据状态，再恢复。
撤销已配对设备，确认未来请求进入授权错误。确认每台设备会保留自己的本地历史，直到你明确删除它。
多候选路径如何做决定
运行时会同时收集可用候选，而不是把一个地址失败后再等待很长时间。局域网地址通常延迟较低，VPN 或 Tailscale 地址可以跨越不同网络， 公网地址适合直接可达的设备，中继则为严格 NAT 提供最后的加密后备。探测阶段会记录响应时间、是否能完成握手，以及最近一次成功传输的时间。
选择器根据可达性、往返时间、失败次数和连接健康度给候选排序。它不会因为地址看起来像局域网就强行选用，也不会因为路径来自 VPN 就默认走中继。 最终结果写入诊断摘要，设备卡片展示已选择路径、远程地址和本地地址。候选列表说明“可以尝试什么”，已选择字段说明“这一次真正使用了什么”。
连接复用怎样降低等待
首次同步通常需要发现设备和完成握手。健康连接建立后，后续的元数据更新、标签修改和小文件复制可以复用同一会话，省去重复探测和握手。 连接池只保留最近成功、仍能响应控制消息的会话；空闲时间过长或连续失败的会话会被移除。移除连接不会删除同步意图，队列会在下一次执行时创建替代连接。
如果每次操作都显示新建连接，先检查设备是否频繁休眠、网络接口是否切换，以及连接是否被错误标记为不可复用。若连接已经复用但总耗时仍很高， 再查看队列、传输和磁盘阶段，不要把所有问题都归因于网络 RTT。
诊断摘要应该回答什么
一次有用的摘要至少包含操作时间、条目标识、内容大小、同步模式、候选数量、已选择路径、是否复用连接、队列等待、握手、已发送和已接收字节、 确认、持久化和最终状态。它不需要包含剪贴板正文、账号密钥或文件内容。需要分析 NAT 时，再由用户主动复制原始模式，并在分享前检查地址。
当你看到“平均延迟四秒”时，先把总时间拆开：如果队列等待占大头，调度器需要调整；如果握手和重试占大头，候选路径或连接池需要检查； 如果传输已经完成而持久化很慢，问题在本地磁盘或读取视图。阶段数据让支持人员能复现方向，也让用户不必上传工作内容。
回车键与后台下载互不阻塞
后台下载负责把等待中的内容变成本地完整内容，命令面板负责响应当前键盘意图。用户在下载项目目录时，仍然应该能够选中一个已经就绪的条目并按回车键复制。 如果选中的条目仍在等待，面板应明确显示“需要下载”，而不是无声地等待。远程 HTML 图片还需要先完成物化和完整性检查，失败时保留原剪贴板。
这条边界同时保护性能和安全。前台命令不会抢占后台传输的所有资源，后台任务也不会吞掉回车键、复制或打开动作。两条时间线在诊断中分开记录， 用户可以知道自己是在等待内容、等待网络，还是遇到了目标应用的焦点权限问题。
一个候选路径的实际判断
假设电脑和手机同时发现三条地址：同一局域网的地址往返时间为 2 毫秒，Tailscale 直连地址往返时间为 95 毫秒，中继地址往返时间为 280 毫秒。选择器不会只按地址名称决定结果，而会先验证控制消息是否能够完成，再结合最近失败次数、连接健康度和传输测量排序。
如果局域网地址只在发现阶段出现，实际握手无法完成，系统应把它标记为不可用，让 Tailscale 直连继续尝试。若直连建立后持续丢包，中继可以接管当前同步意图，任务不需要重新配对，也不应生成重复历史。设备卡片展示最终选择，诊断摘要保留未选候选的失败原因。
这个例子说明了为什么“能互相探测”不是同步完成的证明。探测、握手、传输和持久化各自有状态，只有把阶段拆开，用户才知道四秒延迟来自等待哪一步。
一次同步的状态如何变化
同步状态应该描述一条任务的生命周期，而不是把网络连接状态当成同步结果。发送端先保存同步意图，接收端先接受元数据头，再依据策略请求内容块。连接可以在中途切换，任务标识保持不变；内容写入磁盘并通过校验后，接收端才把条目标记为就绪。
stateDiagram-v2
[*] --> queued: 创建同步意图
queued --> connecting: 领取后台任务
connecting --> metadata: 控制消息成功
connecting --> retrying: 候选失败
retrying --> connecting: 仍有候选或重试次数
metadata --> waiting: 按需下载
metadata --> transferring: 自动下载或手动下载
transferring --> verifying: 收到内容块
verifying --> ready: 长度和指纹通过
verifying --> retrying: 内容不完整
retrying --> failed: 超过预算或重试上限
waiting --> transferring: 用户开始下载
ready --> [*]
failed --> [*]设备页可以把这些状态压缩成“等待中、同步中、已就绪、失败”四个用户可读的标签，同时在详细诊断中保留候选路径、连接复用、队列等待和写盘时间。用户看到“同步中”时，知道后台任务正在传输；看到“已就绪”时，才可以安全地复制完整内容。状态模型越诚实，回车键、复制和打开动作越不容易误触发。
如果移动设备在传输期间从 Wi-Fi 切换到运营商网络，连接层重新探测地址，调度器继续使用原来的同步意图。旧路径失败只会增加一次重试记录，不会创建重复历史。最终诊断应同时保留原路径和新路径，说明哪一次交换完成了数据传输，支持人员才能区分路径切换与内容写入变慢。
继续阅读
阅读剪贴板内容类型，了解元数据头如何描述内容家族。阅读预览、弹出窗口和命令面板，了解动作边界。阅读索引器和 OCR 搜索，了解下载后的图片如何进入搜索。阅读标签和回收站，把元数据与删除状态分开管理。当信任、路径、策略和进度都可见时，P2P 同步才容易使用，也容易排查。