Syzygy 1.0.1：十二个提交，零个新功能

1.0.0 发布于 7 月 22 日。1.0.1 的版本号提交落在 8 月 11 日，中间隔着 12 个提交，没有一项是新功能，8 月 12 日更新分发配置后，这个补丁版本开始推送。补丁版本的意义在于回答一个问题：第一批真实使用暴露了什么。它的内容不值得写进营销页，值得写进这里。下面按症状、原因、修法记录每一处。

#窗口里其余的工作

十二个提交里有几件不构成「症状→修法」叙事、但让这个补丁更完整的事。服务端镜像的构建加入修订号跟踪，哪个镜像来自哪个提交从此可对账。窗口生命周期管理的文档补齐并同步了子模块补丁，测试配置与资源管理做了一轮收敛。仓库还新增了一份 Human-in-the-Loop 软件工程流程文档：这个窗口里的每处修复都先经过人的判断再由工具执行，文档把这套协作方式固定了下来。

#历史和回收站，一条保留策略

症状：剪贴板历史和回收站各自维护一条淘汰上限，历史默认 2000 条、回收站默认 100 条，两个数字来自两个独立常量、互不感知。用户配置里的历史值可以超出策略允许的范围，界面滑杆的最大值也是硬编码的，配置与 UI 各说各话。

修法是把两套数字合并成一条策略：引入一个权威硬上限（2000 条）和一个历史与回收站共享的默认值（100 条），另设 50 条的下限；淘汰策略改用共享常量，配置快照把超限的旧值钳制回上限。这次修改以后端、配置、UI 三层联动的方式落地：桌面组件替换硬编码常量为动态回退值，用配置给出的 max_items_limit 实施钳制，滑杆最大值改为读取该上限，配置层与界面层各自补了测试锁住「默认值生效」与「超限旧值被钳制」两个行为。这是一处标注了破坏性变更的调整：默认历史保留从 2000 条变为 100 条。理由写在 commit message 里也写在这里：剪贴板历史的定位是高频缓存，收藏和置顶才承担归档职责，回收站里被删除的内容也不应该比留下来的内容活得更久。

#置顶顺序成为一种数据

症状：置顶状态此前是一个布尔标记，只回答「钉没钉」，不回答「钉在第几位」。Pinlist 的顺序缺乏一个权威数据源，置顶上限也只是个写死的数字。

修法分三步。协议层面，SetHeaderPinned 布尔请求被替换为 MutateHeaderPinnedV1 变更请求，ClipHeaderV1 与 HistoryItemV1 结构体获得 pinned_position 字段，顺序成为随条目同步的数据，CLI 命令与 API 处理器同步迁移到新请求类型。策略层面，引入按订阅状态区分的剪贴板限额：免费档位置顶上限从 10 个调整为 5 个，订阅档位不设限制。配置层面，数字键快捷粘贴的修饰键组合开放为 quick_paste_pinned_modifiers 配置项，不再固定写死。对用户可见的效果是：Pinlist 的排列从此有一个可依赖的顺序来源，拖拽排序的结果不会在同步或重排后悄悄漂移。

#快捷面板的焦点与预览会话

两处与 Quick Panel 相关的修正，都指向同一种症状：面板的行为依赖一些没被明确管理的状态。焦点处理改为只在 macOS 与 Windows 上编译启用，不支持的平台不再保留注定无效的代码路径，这两个平台「呼出面板后键盘立即可用」的路径由此变成明确支持、有测试覆盖的行为。预览则修了一个状态不同步的问题：此前预览的开合状态由面板内各路由各自维护，在面板路由之间跳转后可能残留过期状态；现在预览生命周期由一个跨路由共享的会话对象统一跟踪（open、reset、transition），由工厂函数创建、以单例在各面板路由间共享，面板布局里的本地状态全部移除，新增测试专门验证路由切换后的共享预览行为。

#配对流程任务化，订阅会话自愈

配对模块从单一路径重构为任务化架构：接受、发起、展示三种操作各有独立的任务执行器（对应新的 PairShowTaskCommandV1 命令），正在等待的展示会话可以被新的会话顶替，不再互相纠缠。同一窗口里，订阅插件进入客户端依赖列表，订阅运行时补齐了会话自愈：重新认证的处理、会话续期状态管理、访问令牌校验、经认证的会话快照解析，登出与重置也有了明确的状态迁移；权益接口的账户快照相应增加了可选的会话续期字段；账户与激活页面把手动激活的说明统一为权益时长（例如「30 天」），结束日期仍同时显示，避免只看日期产生歧义。文件预览顺带获得了基于内容计划的 OCR 能力检测与源码语法高亮的测试覆盖。

#生产产物里的开发凭据

一个和终端用户无关但值得记录的清理：部署模板与容器构建里残留的开发用 mock 凭据（NEXT_PUBLIC_PORTAL_DEV_* 变量与 dev_auth_enabled 配置）被全部移除，并加入产物校验，防止 mock 凭据再次进入生产镜像，相关文档同步更新。服务端同时为应用商店审核准备了独立的引导账号环境变量，审核环境与生产环境从此走各自的账号通道。顺带一提，这扇窗口里还有一个加了一天就被撤掉的 API：「定位某条历史并返回其邻域窗口」的接口第二天就被移除，改用标准查询加游标。写在这里是想说明撤回也是发布流程的一部分。

#从 1.0.0 升级会看到什么

配置文件无需手改。旧的历史保留值若超出上限会被自动钳制，默认值的变化只影响未显式配置过保留条数的用户；免费档位的置顶上限收紧为 5 个；数字键快捷粘贴的修饰键组合在设置里可查可改。协议层的变更（置顶变更请求、共享保留策略）全部封装在客户端内部，用户看到的只是行为变化，不是迁移负担。

分发配置更新之后，1.0.1 走既有分发通道推送。用户侧能直接感知的变化大多很具体：从快捷面板的预览跳去别的页面再回来，预览的开合状态不再错乱；回收站与历史的清理节奏从此一致；配对界面里等待中的会话可以被新会话安全顶替。变化虽小，方向一致：在 1.0.0 的骨架上，把第一批用户踩到的毛刺逐个磨掉。

1.0.1 没有可写进营销材料的改动，这正是它该有的样子：稳定版本的第一个补丁，职责是把地基压实。下一个版本 1.1.0 重新回到了功能节奏：桌面端工作台、同步可视化与 Windows 热键重写。