# 分阶段验证记录

## 阶段 1：阅读底板（2026-09-10）
- 使用官方 theme.overrideTokens，并显式依赖 theme、slots、timer。
- 移除编译类名透明背景、文字描边和全局透明代码块覆盖。
- 正文、次级文字在浅色/深色及背景图黑白极值下，对比度均 >= 4.5:1。
- node --check lib/client.js、node --test tests/theme.test.mjs（2/2）、git diff --check 通过。
- 本机 DSH 0.1.2-rc.1 实测：浅色/深色对话、内联代码和工具汇总可读；外观恢复“跟随系统”。
- 挂件遮挡留到阶段 2。

## 官方资料
- https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/slots.md
- https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-theme/README.md
- https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/web-styling.md
- https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md
- 兼容性以本机已安装包的类型声明为准；当前 master 的 rightbar 插槽尚不存在于本机版本。

## 阶段 2：装饰避让（2026-09-10）
- 三个自由浮动挂件合并为独立 248px 装饰栏，使用 shell.overlay 和 sidebar.footer.action 两个 additive 插槽。
- 通过稳定的 #root 挂载容器预留宽度；无宿主编译类名依赖；不替换原生对话或 details 插槽。
- 添加一键收起/显示，外观面板可直接展开；小人换装、翻转和背景选择保留，取消自由拖动。
- 实测 950px 窗口：rootRight = dockLeft = 702.4px，互不覆盖；隐藏后主区恢复 950.4px；无页面横向溢出。
- 实测小人互动、换装、外观展开及工具轨迹详情；参数/结果/计时区域未被装饰覆盖。
- node --check、3/3 单元测试、git diff --check 通过。
- 窄窗口自动收起留到阶段 3。

## 阶段 3：响应式收起（2026-09-10）
- 1280×720 及以上使用装饰栏；较小窗口自动收起，用户主动打开时使用原生 dialog。
- 原生 modal 负责焦点约束与背景交互隔离；Escape/收起关闭后返回侧栏装饰按钮；装饰内容独立滚动。
- 宽屏选择在尺寸变化中保留；移除遗留的宿主编译类名媒体查询，添加 reduced-motion 样式。
- 浏览器实测矩阵：
  - 1440×900：主区与装饰栏边界同为 1192px，侧栏展开后不重叠。
  - 1280×720：主区与装饰栏边界同为 1032px。
  - 1279×720：自动收起，主区恢复全宽。
  - 1440×600：自动收起，主区恢复全宽。
  - 390×844：装饰默认隐藏；弹窗保持在视口内；Escape 关闭并恢复焦点。
  - 以上尺寸均无 document 横向溢出。
- 已恢复原始约 950×858 视口，对话页仍可继续使用；浏览器 error 日志为空。
- npm run check、npm test（4/4）、git diff --check 通过；无需新依赖。
- 同步更新中英文使用说明及展示页文案。

## 范围
修复主题的阅读对比度、装饰遮挡和窄窗口挤占。DSH 原生的工具状态一致性、折叠摘要及轨迹导航逻辑不在主题插件中修改。

## 用户反馈修正 A：恢复背景（2026-09-10）
- 全页底色透明度由 0.96 降为 0.08，阅读底色只作用于可见的消息/工具内容。
- 使用 data-chat-flow-kind 等语义标记；折叠行无新增 padding 和背景，不生成空白条。
- 浏览器截图验证背景清晰可见，消息可读；5/5 单元测试和语法检查通过。
- 此修正替代阶段 1 的整页底板方案。

## 用户反馈修正 B：恢复浮动与小人常驻（2026-09-10，当前方案）
- 取消独立装饰栏、预留列宽、侧栏开关和装饰弹窗；恢复原有浮动组件与小人的拖动/单击/双击/长按功能。
- <1100px 宽或 <640px 高只隐藏卡片和签名，小人保持同一组件实例并始终显示；小人宽度在 120–220px 之间适配。
- 小人拖动/缩放时限制在视口内；设置面板改为视口内定位，避免原来的向右越界。
- 实测：1440×900 三项均显示，root宽度=1440；1100×800 显示三项；1099×800 卡片/签名隐藏，小人保留。
- 390×844 实测小人可见且在视口内，无页面横向溢出，Enter互动成功，菜单键打开的设置面板完全在视口内。
- 实测拖动后还原位置；已恢复默认浏览器视口；浏览器 error 日志为空。
- npm run check、npm test（4/4）、git diff --check 通过。
- 此方案替代原阶段 2/3 的侧栏和整组隐藏设计。

## 对话区现代化（2026-09-10）
- 对话记录：助手消息使用 20px 圆角、轻描边/阴影和 18×22px 留白；用户气泡采用不对称圆角；工具摘要保持紧凑并可展开。
- 提交区域：24px 圆角浮动输入框、浅/深色独立底色、聚焦光圈、36px 发送按钮和统一工具栏圆角；尊重减少动态效果设置。
- 使用宿主 data-* 和可访问性标记定位，无生成类名依赖；保留宿主输入、发送和菜单逻辑。
- 实际浏览器测试：多行输入后点击发送，收到“多行输入与发送正常”；提交后输入清空，空消息发送按钮禁用。
- 已验证工具过程展开/收起、模型菜单展开/关闭，以及浅色与深色外观；结束后恢复跟随系统。
- 390×844：输入框在视口内，document.scrollWidth=390，小人仍显示；结束后恢复默认视口。
- 最终计算样式：消息圆角20px、输入框圆角24px；语法检查、4/4单元测试及git diff --check通过。
- 已同步本机 DSH 安装副本。

## 小人选择框跟随修复（2026-09-10）
- 移除屏幕右下角固定坐标；选择框按小人位置展开，左侧空间不足时换到右侧，并限制在视口内。
- 浏览器验证：右侧小人菜单在左侧，相隔约8px、底部对齐；拖到左侧后菜单切换右侧。
- 菜单打开时继续拖动，小人和菜单同步移动；390×844下菜单边界为left78/right378/top12/bottom472，无越界。
- 通过键盘菜单键触发同一选择框逻辑；长按触发处理未变。恢复默认视口并刷新还原测试拖动位置。
- npm run check、npm test（4/4）、git diff --check通过；同步本机安装副本。

## Mobamas 默认关闭（2026-09-18）
- 初始化显示偏好改为 showMobamas=false，可在小人长按菜单中手动开启。
- 更新现有组件测试，验证默认隐藏、手动开启及窗口缩放后保留开启偏好。
- npm run check、npm test（4/4）、git diff --check通过；同步本机安装副本。

## Windows 桌宠（2026-10-05）

- 本地分支 `desktop`，插件版本 `1.2.0-desktop.1`；宿主为本机 DSH Desktop `0.2.0-rc.2`，助手运行时为 Electron `44.5.1`，Windows x64。
- 桌宠使用独立透明置顶窗口，监听所有主会话的本轮结束、异常、中止、提问和审批。每条新提示只执行一次原有单击翻转动作，无声音；提问和审批气泡保留到请求解决。点击气泡通过宿主的会话导航接口定位。
- 页面小人仅在桌宠握手就绪后隐藏；保留背景、签名及 Mobamas 偏好。桌宠故障时恢复页面小人。
- Host 与桌宠采用带随机握手凭据的 Windows 命名管道。停用插件时关闭自有进程，管道断开或父进程结束时桌宠退出。预览使用独立偏好目录，不改正式桌宠位置和去重记录。
- 对照本机已安装的 Connection、Session Projection 与 Cordis 实现确认事件及公开接口。RPC 使用 `connection.register(ctx, ...)` 保留消费插件的上下文；回归覆盖提供者 getter 捕获上下文导致的 `webServer` 注入错误。
- Windows 打包保留经 SHA256 核验的官方 Electron 可执行文件，避免本机 PE 资源改写后的启动失败；安装副本的 `app.asar` 内容与桌宠源码一致。

| 验证层级 | 结果 | 证据与范围 |
| --- | --- | --- |
| 静态检查与自动测试 | PASS | `npm run check`、`npm test`（44/44）、`git diff --check`；覆盖事件去重、待答恢复、导航确认、偏好同步、透明区域判定、进程生命周期、安装备份及回滚。 |
| 本机实际 Cordis 服务集成 | PASS | 使用本机提取的 Connection、Projection 与 WebServer 实现，验证消费上下文注册、路由和卸载清理；未调用模型。 |
| 打包助手与合成状态 | PASS | 实际 Windows 助手启动并握手；提问只报一次，解决后显示完成提示，偏好往返与正常退出通过。 |
| 正式 DSH 插件启动 | PASS | 完整退出并重新启动 DSH 后，正式安装目录的桌宠进程及窗口出现，页面小人隐藏，背景和签名保留。 |
| DSH 最小化 | PASS | 主窗口最小化后，独立桌宠仍显示于桌面；恢复主窗口正常。 |
| 插件停用 | PASS | 在正式 DSH 插件面板停用后，桌宠窗口和所有 `Yukimi Desktop.exe` 进程退出。 |
| 插件重新启用 | PASS | 重新启用后自动创建一个桌宠窗口，页面小人隐藏，背景和签名恢复；结束时插件保持启用。 |
| DSH 前台时的可见性 | INCONCLUSIVE | 透明窗口捕获在 DSH 前台时未显示小人，最小化后可见；已询问用户确认实际屏幕效果，不能据此断言已通过前台置顶显示。 |
| 真实模型任务与气泡导航 | NOT RUN | 未在用户会话中发送新的模型任务；真实任务结束、提问、审批到气泡，以及鼠标点击气泡定位会话的完整链路尚未实测。对应状态与导航逻辑已通过自动测试。 |

- 本机原插件备份：`C:\Users\admin\.dsh\yukimi-desktop\backups\2026-10-05T10-03-41-495Z-c5c744e9`；按 README 中的 `desktop:sync -- --restore-backup` 流程回滚。

## 背景清晰度修正（2026-10-06）

- 根据用户澄清，完整回滚上一轮整体配色提亮：恢复背景、阅读区、输入框、代码区、侧栏和文字的原始颜色，移除浅色背景叠层。
- Windows 宿主将侧栏底色同时铺到整个 shell frame（深色透明度 97%），导致背景图几乎被盖住。只将包含直属 `data-shell-overlay` 的 Windows frame 背景设为透明；侧栏及标题栏仍使用宿主独立的原底色，消息阅读底板与输入框保持原样。
- 使用宿主语义标记 `[data-windows-titlebar] div:has(> [data-shell-overlay])`，不依赖生成类名；与调整前客户端备份相比，最终客户端仅新增这条 CSS 及其说明注释。
- `npm run check`、主题测试（4/4）、`git diff --check` 通过；正式安装客户端已同步，实际 DSH 截图确认背景图清晰显示，侧栏、消息阅读底板与输入框保留原配色。

## Windows 会话顶部导航整合（2026-10-06）

- 将用户指出的会话标题与“对话 / 轨迹”两条独立深色底板整合为一块半透明圆角导航区，统一边距、轻描边与选中标签底色，让背景图在导航区四周自然露出。
- 只作用于 Windows 中含会话标签的原生 header，保留宿主拖动标记、标题布局、菜单及标签逻辑；浅色和深色模式分别设置底色，沿用现有文字与主题配色。
- 实际 DSH 验证“对话 / 轨迹”往返切换正常，“更多操作”菜单完整显示下载日志和反馈项目。最终不使用 `backdrop-filter`，避免改变原生菜单的包含块而导致裁切。
- `npm run check`、主题测试（4/4）、`git diff --check` 通过；现有对比度用例覆盖新增导航底色，浅色和深色模式的主次文字均满足 4.5:1。
- 已同步正式安装客户端。Git 分支 `desktop` 的调整前基线为 `a0a2561`，本次导航样式单独提交，便于对照与回滚。

## Windows 桌宠全屏拖动（2026-10-06）

- 根因：原边界函数限制整个 360×600 透明载体，小人固定在其底部居中，只能在屏幕的一部分坐标内移动。
- 改为独立保存小人的屏幕位置，按 170×170 小人边界适配完整 `display.bounds`。载体围绕小人重新布局，气泡和设置按上下剩余空间展开，空间不足时分置或收缩滚动；边缘位置不再受透明留白限制。
- 拖动按鼠标所在显示器计算，兼容负坐标副屏；保留按下时的原始位置，并在开始、松开时立即采样，避免短拖在 32ms 定时器采样之间结束而不移动。沿用 Electron DIP 坐标，不额外乘缩放比例。参考：[Electron screen API](https://www.electronjs.org/docs/latest/api/screen)。
- 本地位置文件升级为版本 2，新增 `petPosition`；旧版 `bounds` 自动换算为原小人位置，保留服装、背景和已提醒标识。
- `npm run check`、`npm test`（55/55）、`git diff --check` 通过；新增 11 项回归覆盖四角四边、内部位置、负坐标及垂直屏、拔屏恢复、小屏缩放、旧坐标迁移、完整屏幕边界、DIP 与连续拖动锚点。
- 实际 Windows 打包预览验证：鼠标短拖从 `(20,20)` 到主屏左上边缘，保存位置为 `(0,0)`；等待气泡改向下方展示，菜单键可展开设置，提醒与设置分开排列。其他边角和不同 DPI 的跨屏结果来自自动测试，未全部执行真实鼠标验证。
- 本轮只更新辅助程序，正式插件停用后同步，重新启用即可创建新进程；本轮未修改 Host 入口，未重启 DSH。安装备份：`C:\Users\admin\.dsh\yukimi-desktop\backups\2026-10-06T02-52-10-906Z-49f23565`，同时保存 `preferences.before.json` 供旧坐标文件恢复。

## Windows 桌宠服装预加载（2026-10-06）

- 启动后后台预加载 13 套服装共 52 张小人图片，优先当前服装及下一套，最多并行 4 张；同一 URL 只加载一次并保留解码后的 Image。只预加载小人，不增加大幅背景卡面的下载。
- 双击换装、单击动作及衣柜选择均先等待图片下载和解码；旧图保持显示到替换图片就绪。失败或 12 秒超时保留原服装，后续可重试；序号与服装基准保护防止迟到回调覆盖新的本地选择或 Host 状态。参考：[HTMLImageElement.decode()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decode)。
- `npm run check`、`npm test`（69/69）及 `git diff --check` 通过。新增 6 项缓存测试及 8 项实际 renderer 行为回归，覆盖解码等待、有界并行、优先级、去重、失败/超时重试、首次双击与异步选择竞争；延迟下载及解码使用可控 FakeImage / 缓存模拟，不代表真实冷网络耗时。
- Windows 打包预览成功加载新增模块，实际鼠标双击从第 8 套切到第 9 套，换装前后图片均可见，独立预览偏好记录由 `cardIndex:7` 更新为 `8`。未逐帧采样真实网络换装过程；首次慢加载无空白由上述 renderer 回归验证。
- 已在正式 DSH 插件面板停用主题，确认自有桌宠进程退出后同步完整副本；安装 `app.asar` 与本地打包文件及最新源码逐项一致。本次仅更新辅助程序，无需重启 DSH Host。安装备份：`C:\Users\admin\.dsh\yukimi-desktop\backups\2026-10-06T03-37-11-128Z-83c6d7ec`，另存 `preferences.before.json`。
- 重新启用后正式安装目录出现一个新桌宠窗口，renderer 的互动按钮已加载，保存的正式偏好与备份完全一致。透明窗口截图仍包含被覆盖的其他应用内容，不能凭该截图确认正式桌宠的屏幕可见性；实际换装验证使用上面的独立预览窗口。

## Windows 消息提醒置顶（2026-10-06）

- 原实现只在启动时设置 `floating`，没有在新提醒出现时提升窗口顺序。本次按 NoticeQueue 当前可见气泡管理层级：出现提醒立即设置 `pop-up-menu` 并调用 `moveTop()`；气泡保留期间复用原状态计时器，约每秒维护一次。询问与审批一直保持较高层级，完成提示结束后恢复 `floating`。
- 新气泡绕过维护节流，恢复中的旧等待气泡也会提升；Host 已确认但仍在显示的完成气泡不会提前降层。隐藏或丢失置顶状态时立即恢复，隐藏恢复使用 `showInactive()`，不调用 `focus()` 或 `show()`。置顶维护不增加提醒动作、声音或气泡重放。
- 对照本地 Electron `44.5.1` 类型及 [官方窗口文档](https://www.electronjs.org/docs/latest/api/base-window#winsetalwaysontopflag-level-relativelevel)：Windows 的 `pop-up-menu` 层级位于任务栏上方，`moveTop()` 改变窗口顺序而不要求焦点。
- `npm run check`、`npm test`（78/78）、`git diff --check` 通过；新增 9 项使用实际 NoticeQueue 的回归，覆盖完成退场、持续等待、排队、已投递重放、维护节流、新消息立即提升、隐藏恢复、丢失置顶、时钟回退与窗口销毁。测试窗口替身禁止抢焦点调用；未测量实际前台窗口焦点。
- 实际 Windows 打包预览：小人设于 DSH 窗口范围内，合成询问气泡和小人均显示在 DSH 内容上方，长时间等待仍可见；未向真实会话发送模型消息。切回 DSH 的额外验证被用户输入保护阻止，没有继续使用旧窗口状态。Windows 安全桌面、独占全屏及其他持续自我置顶程序不在本次实测范围。
- 正式插件停用后同步完整副本，安装 `app.asar` 与本地包以及 `main.cjs`、`logic.js` 源码一致；本次未改 Host 入口，无需重启 DSH。安装备份：`C:\Users\admin\.dsh\yukimi-desktop\backups\2026-10-06T07-34-06-244Z-02a2a9d3`，同时保留 `preferences.before.json`。
- 重新启用后正式目录的新桌宠窗口出现，插件保持启用；原服装、背景及小人位置与备份一致。真实会话的新提醒置顶链路未额外触发，窗口遮挡验证使用上述合成预览。

## 重启后主题开关与持久安装修复（2026-10-12）

- 现场宿主仍为 DSH Desktop `0.2.0-rc.2`。包总开关已开启，但详情显示内部 `yukimi-theme` 已关闭；profile 的覆盖补丁为 `disabled: true`。官方总开关调用 `setBundleEnabled()`，只增删 bundle；内部开关调用 `setPluginEnabled()`，两者独立。重复切换总开关不会清除内部停用状态。
- 使用本机官方 `applyEntryPatches` / `composeEntries` 原实现验证四个配置组合：包开、包关、包再开及内部启用，四项断言通过。该证据依赖本机宿主，不进入便携 `npm test`；没有复制或修改宿主实现。实际 UI 打开内部条目后主题立即恢复，包总开关关闭后主题正常卸载；修复通过官方 UI 写入 `disabled: false`。
- 同时发现安装副本已退回 `1.1.0`，Host 入口为空且无桌宠目录，profile 依赖仍锁定 GitHub 默认分支的 `94b6edf`。此前 `desktop:sync` 只覆盖安装文件，包管理重装仍会恢复旧依赖；没有证据断言仅重启本身必然触发重装。
- 新增 `desktop:install`，从白名单 staging 生成完整 `.tgz`，包含 Electron 运行时并验证 npm 清单及流式 tar 文件头；按 SHA256 固定保存归档，再由 Desktop 自带 CLI 更新依赖。禁止覆盖不同内容的已存在归档，不走命令 shell，不改 Harness 程序文件。版本升为 `1.2.0-desktop.2`；README 解释两层开关及临时同步的限制。
- `npm run check`、`npm test`（89/89）及 `git diff --check` 通过；11 项安装回归覆盖运行时缺失、发行白名单、归档遗漏、损坏压缩、打包失败、固定归档复用/拒绝覆盖、仅打包模式、Windows 参数、非官方启动器、安装失败和符号链接。实际完整归档与 Desktop 官方 CLI 安装已成功，安装后 32 项必需文件和源码、`app.asar` 一致。
- 正式依赖已改为 `$DSH_HOME/yukimi-desktop/packages/dsh-yukimi-theme-1.2.0-desktop.2-d80b5db3b7a6a30e1095d3ddbdef1d12aaf315dd3104b1aee3010365834ff37d.tgz`。安装前正常退出 DSH，备份原插件及 profile 的包声明、锁文件、覆盖补丁与正式偏好到 `C:\Users\admin\.dsh\yukimi-desktop\backups\2026-10-12T03-58-14-668Z-managed-install`。归档需要保留，供后续包管理恢复完整桌宠版。
- 安装后启用主题，正常退出应用及 Host，再重新启动；版本仍为 `1.2.0-desktop.2`，完整归档依赖与启用状态保留，独立桌宠窗口自动出现，页面只显示背景和签名。重启后关闭包总开关，所有桌宠进程退出，页面恢复宿主原界面。服装、背景、显示偏好及屏幕位置与安装前备份一致；其余 profile 依赖来源保持原样。
- 重启后的包总开关再次开启，背景及签名恢复并新建一个正式桌宠窗口，页面小人隐藏。结束时主题保持启用并返回原会话；未发送模型消息或改变其他插件开关。

## 聊天光晕、历史透底与输入遮挡（2026-10-13）

- 按用户指定的 3 → 2 → 1 顺序实施。输入卡片聚焦改为独立的蓝紫描边、薄内圈和柔和外光晕，保留键盘按钮焦点标识及减少动态效果设置。
- 历史底板深色透明度由 90% 调为 80%，浅色为 86%，减轻边框；仅历史区域的代码底板改为深色 88% / 浅色 90%。标题、侧栏及全局代码配色保留。对比度回归覆盖历史正文、代码及输入卡片，浅色和深色均在纯黑、纯白背景极值上验证主/次文字至少 4.5:1；未降低语法高亮文字本身的透明度。
- 重叠来自输入卡片的半透明背景透出滚动正文。输入卡片改为不透明底色，仅覆盖卡片自身；保留宿主 sticky 布局、36px dock 渐变、已有 ResizeObserver 高度占位和菜单层级，没有增加固定底部间距或裁切上弹菜单。
- 实际 DSH Desktop 中检查原会话：历史正文和代码区透出更多插画，空输入框与多行自动换行草稿中无历史文字穿透；滚动后遮挡仍有效，清空草稿后高度恢复。`/` 指令菜单和 `@` 文件菜单向上完整展开，“对话 / 轨迹”切换正常。测试草稿未发送，检查后恢复为空。浅色模式仅做自动对比度验证，未做原生窗口目视验证。
- 版本为 `1.2.0-desktop.3`；通过完整归档和官方 Desktop CLI 持久安装，保留前一版插件、profile 元数据与正式偏好备份。此次仅改页面样式，Host 与桌宠逻辑未改。
- 正常退出应用和 Host 后安装，再重新启动：主题自动启用，背景透底与输入遮挡保持，独立桌宠窗口出现；安装目录 32 个必需文件与源码一致，profile 指向完整 `.3` 归档。
- `npm run check`、`npm test`（89/89）、`git diff --check` 通过。实机验证未向模型发送消息。