# 安装与人工验收

这是待执行的验收清单，不代表已经完成实机验证。Web 与原生官方 Desktop 分开记录；Mock 预览、自动化测试和构建通过不能替代 Desktop 实测。

官方 Desktop 新旧包接管需单独验收：保留 `dsh-client-liang-intensity-skin`（包括本地链接），安装新版 scoped 包后点击使用，确认旧组合包撤下、新版选中且旧安装文件保留；旧版已停用时不重复切换。DSH `0.2.0-rc.2` 若要求重启，完整退出重开后确认新版实际运行。失败时核对旧选择恢复；存在未知冲突、额外组件、手工重复注册或无法确认的禁用覆盖时，应说明原因并保留保护。

## 1. 本地检查

在仓库根目录执行：

```bash
npm ci
npm run check
```

这些检查不会安装到真实 DSH profile。生命周期超时、丢失管理结果、目录替换中取消、恢复命令返回成功但入口仍缺失、SRI 不匹配等故障，用临时目录和模拟宿主测试；不要在正常使用的 profile 中删除锁文件、包文件或制造故障。

## 2. Web 浏览器验收

开发构建可从当前目录安装：

```bash
dsh plugin --profile web add "file:$PWD"
```

发布包则使用 `dsh-skin-market@<待验收版本>`。重启 `dsh web`，打开启动时给出的登录地址，再进入「设置 → 皮肤市场」。记录 DSH、市场版本、操作系统和当前 profile。

依次检查：

1. **浏览**：目录、真实截图、GitHub 地址与 Stars 正常；详情、搜索和列表滚动可用，其他设置页尺寸不被市场改变。提供「插件列表 → dsh-skin-market → 详情」入口的 Web 宿主也检查：市场随内容展开，由宿主详情页统一滚动；鼠标停在市场卡片、列表空白或市场外都能滚动同一页面，滚到列表末尾会追加下一批；缩小窗口后重复检查。
2. **安装**：选择一个测试皮肤。安装完成只表示包已经安装，启用状态以详情实际结果为准；日志、失败原因和取消按钮状态准确。
3. **使用与切换**：在可热应用的宿主点击「使用」并切换另一测试皮肤，确认目标实际运行、原普通皮肤停止且不弹重启提示。分别检查模块异步到达、加载中和加载失败：中间态不立即弹重启，加载完成后自动收起本次切换的推断提示，失败显示原因。宿主或浏览器确实无法应用时再提示重启。保留另一浏览器页面，确认一个页面已应用不会直接清除其他页面的待同步状态。
4. **常驻**：将一个适合叠加的测试插件设为常驻，切换普通皮肤后它保持运行；取消常驻与停用结果一致。旧皮肤仍运行、关联组件未应用或共享伴随插件状态不符时，不能仅凭目标外观变化就显示切换已生效。
5. **停用**：当前皮肤恢复默认外观或显示真实的待重启状态；包保持「已安装」。
6. **更新**：只有存在更高的已收录版本时执行。成功显示实际物化版本；刷新页面后待重启提示仍在，完成重启后再核对外观。相同版本不循环提示更新。
7. **卸载**：卸载测试皮肤后包与市场拥有的注册项被移除；常驻、伴随依赖和无关第三方插件按其所有权保留，不能被顺带删除。
8. **市场自更新与重启**：存在新版时更新本插件，核对实际版本和待重启提示。运行中的 Agent 或插件操作会阻止 Web 重启；状态未知时不能把新版本当作成功加载。

安装、更新或宿主明确要求重启后，再执行普通使用、切换、常驻与停用；原有重启提示必须保留。尤其更新后同包旧模块仍运行时，不得因模块显示 active 而清除新版的重启要求。

<details>
<summary><strong>展开 Web 登录与目录刷新检查</strong></summary>

- 使用无宿主会话的浏览器窗口访问市场状态、日志及操作 API，支持宿主登录的版本应拒绝未登录请求；正常登录后恢复使用。
- 宿主明确声明的可信地址可以浏览和安装；其他地址/Origin 被拒绝。通过代理转发的请求不能触发 Web 重启。
- 保持市场打开，5 分钟检查或重新聚焦后，远程目录更新能够出现；详情、弹窗和滚动位置保持。这里检查目录刷新，不需要重新安装市场。
- 断网时保留最近有效目录；首次无浏览器缓存时显示骨架屏。长列表分批追加，搜索覆盖全部条目。

</details>

### 2.1 Web 本地来源替换

- 在隔离 Web profile 中分别安装同一仓库的本地 `.tgz`、链接和目录包，确认完整构件能显示「替换为市场版本」。包名或仓库不同、入口缺失、存在 loader 冲突、含伴随插件或缺少已核验 npm 来源时不提供入口。普通更新说明本地来源限制，并指向页面提供的替换入口或原安装方式，不回显本地路径。
- 确认窗显示实际安装版本与市场版本；市场版本较旧时明确提示降级。取消后不发起下载或写入，确认后使用已核验的精确 npm 版本和完整性记录。原 GitHub 同版本「换用 npm」行为保持。
- 确认前后分别修改本地来源、已安装代码、锁文件和市场目标；陈旧确认均被拒绝，提示刷新详情并重新确认。下载或排队期间来源变化同样停止，不能覆盖新的安装。
- 分别检查当前使用、常驻和停用状态：成功后保留原有选择与无关插件；原本地目录及 `.tgz` 文件未被删除或修改。有待确认风险时保留停用，按使用前确认流程处理；确需重启时再核对真实运行结果。
- 用隔离故障检查下载失败、构件不符和写入后失败；失败恢复原来源、构件与选择，恢复未完成显示实际原因。官方 Desktop 不显示此换源入口，不用 Web 结果代替 Desktop 验收。

## 3. 原生官方 Desktop 独立验收

在实际桌面应用中，通过「插件 → 添加插件」安装待验收的 `dsh-skin-market@<版本>`。记录“关于 DeepSeek Harness”显示的应用版本；系统终端中另一份 npm dsh 的版本不作为 Desktop 证据。

按当前宿主实际提供的能力完成以下检查；`0.2.1-rc.1` 已核对官方 macOS 安装包中的接口与清单结构，自动化覆盖不能代替原生应用操作验收：

1. 市场识别为官方 Desktop，显示实际可用的管理按钮；缺少方法、比 `0.2.1-rc.1` 旧且尚未核验的版本仅在受影响的按钮处说明原因，不显示维护记录的常驻横幅。`0.2.1-rc.1` 及更新版本不得仅因版本号未写入名单就被误判为不支持管理；已启用和停用的皮肤按真实清单分别显示运行与已安装状态，不得批量显示“官方 pluginManager 未提供可用的插件清单”。真实加载失败与待重启要求仍须保留。
2. 在市场点击「安装」安装一个 `desktop: managed` 测试皮肤。确认操作由当前 Desktop 插件管理器完成，进度与实际安装结果一致，Web profile 未被修改。所有已核验且启停接口可用的官方宿主（包括 `0.2.0-rc.2` 与 `0.2.1-alpha.3`）都默认继续一键使用：先完成安装，再合并所需的使用前确认，确认后停用原先的普通皮肤、启用目标，保留目录中的常驻皮肤与无关插件。取消确认后包仍已安装，不启用目标。安装结果 `applied` 不能单独作为代码已加载的证据。
3. 使用、切换、常驻、取消常驻、停用和卸载分别核对真实外观、包状态与无关插件保留情况。安装返回 `restart-required` 后，确认使用仍继续保存停旧、启目标，切换结束才弹一次「请手动重启 Desktop App」；后续的 `applied` 不得清除安装留下的待重启状态。点击“知道了”、取消或关闭弹窗后，同一次提醒不再显示横幅，仍可从卡片的待重启入口重新查看；聚焦刷新、轮询及重新进入市场不得重复提醒。新的重启事项仍须提醒。无需重启时不弹重启窗。`overridden` 或真正的启用失败必须显示实际原因并恢复旧选择，不能显示为已经启用。
4. 存在新版时验证皮肤更新与市场自更新。皮肤更新通常保留原有启用及常驻选择；新版有待确认的兼容性或构件风险时，显示已安装并保持停用，使用或常驻确认后再启用。`0.2.1-alpha.3` 可热重载的更新按真实结果显示生效；`restart-required` 保留 `restartReason` 并提示手动重启，刷新页面不丢失待重启状态。未开启热重载时，启停选择保存后一次手动重启应用，再核对实际加载；市场不提供调用私有 Electron API 的重启按钮。
5. 取消安装后，以管理器最终结果为准：已经应用的操作不改标为取消。连接中断且支持结果恢复的版本核对原 request；无法确认时保持“等待宿主确认”，不重复安装或开始另一个 profile 写操作。
6. 需要构建授权时，只批准管理器返回的精确待构建项；旧版本不显示尚未支持的 registry 或 `saveExact` 功能。旧服务的 caret 依赖必须与锁文件实际解析和可用 SRI 一致；没有 SRI 时只记录元数据/入口检查。
7. 已确认使用的目标需重启时，完全退出 Desktop 并重新打开，确认直接加载目标皮肤，旧普通皮肤保持停用、常驻项保留，无需再手动开关皮肤。macOS 使用 `⌘Q`；关闭窗口可能只是隐藏窗口，不等于完全退出。旧版目标行导入失败但经独立核验完整启停选择已保存时，显示待重启而非撤销已保存的目标；其他导入或初始化失败仍显示失败并回滚。`0.2.1-alpha.1` 起的运行时包解析刷新与真实加载结果分别记录。

8. 从「插件列表 → dsh-skin-market → 详情」打开市场，市场随内容展开，由宿主详情页统一滚动；鼠标停在卡片、列表空白或市场外都能滚动同一页面。滚到列表末尾继续加载下一批皮肤，搜索和皮肤详情弹窗正常；缩小窗口后重复检查。保留「设置 → 皮肤市场」入口的宿主也检查原有列表滚动。

9. 选择兼容范围不包含当前 DSH 版本或存在 SRI 风险的测试皮肤：安装、更新不弹可选风险确认；使用与常驻前将首次使用提醒、兼容性和构件风险合并在一个弹窗。取消或关闭不发起启用，包仍已安装；安装并使用在安装完成后确认一次。构件及核验目标未变时不重复确认已接受的构件风险，变化后重新确认。若官方管理器拒绝插件自身依赖，显示真实失败，不能将风险确认当成宿主兼容豁免。

10. 选择无 npm 包、已通过安装审查且不需额外构建或伴随插件处理的 GitHub 根包及子目录包，确认直接显示「安装」。安装和更新保留完整 commit 与 `&path:`，实际包名、版本、入口及锁文件仓库/commit/子目录均与目录一致；更新不因后来出现 npm 包而自动换源。

11. 选择需构建、伴随插件或未通过安装审查的目标，直接点击「安装」，确认打开应用原弹窗、目标已固定填写，尚未提交安装；中间不弹市场安装面板。已有安装或检查中的任务不被重置，已有其他非空草稿不被覆盖。入口失败时仅显示错误；「其他安装方式」中的原有提示词、包名输入及复制控件保持原样，没有第二个安装按钮。两处市场入口及快速重复点击均不得覆盖原任务。

12. 从市场打开虎鲸链路等原生安装目标：仅安装后返回，市场及时显示已安装；原生继续启用后，返回市场按原有确认流程完成互斥切换，保留常驻项。关闭确认时不重试；确认前离开再返回时不丢失待处理动作。原生安装失败、启用拒绝、修改目标或其他包操作不能触发市场切换。官方组件已运行但界面模块未加载时显示待重启，实际界面加载后才显示正在使用。原生页自行保存的选择在重启、刷新目录和市场切换失败回退后均保留；更新保留实际启用状态。

Desktop 自带命令从 `0.2.0-rc.2` 起是另一个**离线维护入口**：先打开一次应用初始化 profile，再完全退出，才能使用它管理 Desktop 插件。应用运行中的市场仍使用 `pluginManager`；npm 安装的 dsh 不修改 Desktop profile。第三方桌面壳另做验收，不能用其 `desktopProfiles`/`desktopPnpm` 结果替代官方 Desktop 结果，也不自动迁移其配置。

### 3.1 安装、更新与重启场景矩阵

以下是验收要求，不代表已经逐项通过。每项分别记录自动化结果、原生操作结果、完整退出后的结果；三个证据不能互相替代。

必须分开核对四层状态：包已安装、bundle 已选中、组件有效启用、实际外观已应用。官方插件页的总开关开启，不代表「包含的组件」也开启；市场不得仅凭包版本或 bundle 选择报告使用成功。

| 场景 | 操作完成时应核对 | 提示与重开后的结果 |
| --- | --- | --- |
| 新安装或修复安装 | 先完成安装，再进行所需的使用前确认；确认后停旧、启目标，常驻项保留 | 取消后保留已安装包且不启用；确需重启才提示 |
| 使用已安装皮肤 | 完成所需确认后停用旧普通皮肤；目标 bundle 与主组件均有效启用 | 使用前提醒合并确认；已生效不弹重启窗，明确待重启则弹 |
| 目标 bundle 开启、主组件关闭 | 通过官方组件 API 修正已确认目标行，重新核对有效状态 | 不能把组件关闭显示成待重启，不能要求用户再手动打开组件 |
| 再次使用当前目标 | 不制造额外启停、重复安装或新的重启要求 | 已生效保持使用中；已有待办仅保留对应提醒 |
| 常驻与取消常驻 | 常驻前合并确认叠加与当前风险；保存选择，保留主皮肤及其他常驻项 | 仅明确需要重启时弹重启窗；重开后选择与实际组件一致 |
| 停用当前皮肤 | 目标不再有效启用，无关插件保留 | 即时停用不弹；外观仍待退出清理则准确提示 |
| 更新正在使用或常驻的皮肤 | 核对实际安装版本、启用选择及有效组件；待确认风险版本先停用 | 无待确认风险时保留原选择；再次使用或常驻时合并确认，确需重启则提示 |
| 更新未启用皮肤 | 核对版本但保持停用，不切换当前皮肤 | 不声称重启后将使用此皮肤；宿主明确要求重启时说明更新原因 |
| 卸载启用或未启用皮肤 | 核对包移除及当前选择；不影响其他常驻项 | 未启用皮肤不误报外观待办；仍需重启的卸载提醒应跨页面刷新保留 |
| 市场内按钮自更新 | 核对下载构件、包版本和当前加载的代码，分清已更新与已加载 | 市场提醒不混入皮肤提醒；按真实加载结果提示及清除 |
| 官方插件页更新市场 | 更新不经过市场内按钮，仍需核对加载版本与组件 | 不能依赖市场更新器闭包里的旧标记判断是否生效 |
| 官方返回 applied，但组件关闭或未运行 | 根据有效组件状态区分覆盖、加载中、未加载或失败 | 不把 applied 当作外观已应用，也不从无 fiber 直接推断必须再重启 |
| 加载失败、被覆盖、取消或结果未知 | 保存实际原因；按事务结果恢复或保留已确认选择 | 失败不报成功，未知不重复写入；不能用重启提醒掩盖错误 |
| 安装、更新或启停仍未完成 | 暂停冲突写入，保持进度可见 | 提示等待完成，不能此时引导退出中断安装 |
| 关闭弹窗、稍后、聚焦、刷新或市场页面重挂载 | 从宿主状态恢复同一待办，不重新执行安装和启停 | 同一待办不反复弹窗；横幅及详情入口可查看 |
| 待办完成、目标改选或目标卸载 | 以最新宿主状态为准，清理对应旧通知 | 旧皮肤或市场的横幅、弹窗不得残留或串到另一个目标 |
| 仅关窗口或刷新页面 | 核对宿主进程是否仍为同一次运行 | 不当作已完成重启，也不清除尚未应用的真实待办 |
| 完整退出并重新打开，目标已运行 | 核对目标有效启用、实际外观、旧普通皮肤关闭、常驻保留 | 清除已完成的重启标记、卡片待重启、横幅和弹窗，无需再点使用 |
| 完整退出后目标组件仍关闭、缺失或失败 | 显示具体未生效原因；启动中与失败分别核对 | 不再一律显示待重启，不让用户无限重复重启 |

原生最短验收顺序：记录 Desktop 与市场版本、当前皮肤和常驻项 → 操作目标 → 核对官方插件页总开关及「包含的组件」 → 核对弹窗与实际外观 → 关闭弹窗并刷新市场 → 完全退出再打开一次 → 再核对组件、外观和所有提醒是否一致。更新按钮分别验证「皮肤更新」「市场内自更新」「官方插件页更新」，不可用其中一条代替另两条。

市场自更新后，继续安装另一个皮肤并更新一个已安装皮肤，不能只以市场版本变化判定整条链路通过。若官方包管理器返回 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`，应显示被阻止的具体包与版本，保留前面的网络警告为诊断，不能误报为网络故障。分别记录管理器失败结果与实际物化包状态。

核对精确版本例外：同名多条规则在包操作前合并，保留原有版本、其他包、注释和全局年龄策略；操作失败后若新增重复规则，修复后只重试一次。没有重复规则时不得自动重复失败请求。未知结果、取消或超时不得自动重试。明确的新包保护失败若已物化新版本、仅回滚清单和锁文件，在本次修复了报错所指包的重复例外后，允许同一精确目标重试一次并完整验证构件；修复无关规则不足以这样重试，第二次失败必须停止。其他失败须确认原构件已恢复才自动重试。

核对“允许此版本并继续”：只有官方确认的新包保护失败且能解析精确包名和版本时才出现；按钮显示的版本必须来自报错，可能与当前皮肤或市场不同。点击后在写入锁内核对失败上下文、当前目标和精确版本，再添加这一版本并重试。取消、陈旧操作、目标 release 或构件元数据变化、未知结果均不得借旧批准写入例外；不能给包的所有未来版本放行，也不能设置 `minimumReleaseAge=0`。明确的新包保护失败即使已物化新版文件、只回滚清单和锁文件，也应保留该精确批准按钮，点击后继续同一冻结目标并完整校验。真正未知事务、取消/超时及其他未确认恢复不得提供此按钮。

市场自更新不根据 npm 发布时间硬锁 24 小时，也不凭刚安装新版就推测皮肤操作受限。核对官方插件页或其他入口更新后的实际加载版本与重启状态；这些入口的首次安装不受市场预处理控制，需保留外部处理提示和等待保护期的后备方法。未发布版本在本机验收时使用完整包，不能以 Web 测试或源码替换冒充 Desktop 验收。

测试夹具必须允许 bundle 选择与组件 disabled 状态独立变化；不得在选择 bundle 时自动把组件标记为运行。模拟更换 PID 只能验证标记生命周期，不能替代真实 Desktop 退出、启动和组件加载验收。

## 4. 故障结果与验收记录

配置覆盖修复与排查入口另行核对：

- 在隔离 home/profile 中对同一测试组件设置相反开关，确认弹窗指出实际受影响组件；切换旧皮肤停用失败时，不能误指向新皮肤。
- 启停前只读预检本次切换涉及的全部覆盖；版本不一致、首次使用、构件风险和共享修改合并在一个确认窗。只有点击“解除覆盖并使用”等按钮才备份并修改，再后台走正常官方管理；取消或只打开弹窗不写配置。旧皮肤被强制开启且新皮肤被禁用时，同时展示两项目标，一次原子写入和一份备份，不连续弹出两次修复确认。
- 确认前后重新核对配置、选择与安装包；变化后更新同一确认流程并等待再次点击。已接受且未变化的兼容性与构件授权随本次操作保留，重试不重复弹出使用确认。未能预检的失败仍保留原诊断修复入口，并将所需使用风险合并在该窗口。
- 核对无关字段、注释、其他皮肤和权限保留，备份只在本地且权限为 0600；确认后的文件或安装构件已变化时拒绝旧方案。复杂 YAML、别名、动态标签、启动覆盖和软链接不提供自动修复。
- 明确失败时只恢复本次配置改动；有并发改动则不覆盖。宿主结果未知时保留备份和等待状态，不自动重试或假称已恢复。真正的宿主重启要求继续保留。
- 普通环境失败显示针对性的排查提示词；剪贴板不可用或日志导出失败时，说明缺失并提供可选择的文本。404、缺文件和模块缺失不预先归咎作者；宿主保护与登录来源检查不提供绕过提示词。

这些隔离测试不能替代官方 Desktop 实际安装完整包后的确认、启用、失败恢复和重启验收。不要为测试而修改正在日常使用的 home 配置。

自动化故障用例应覆盖：

- loader 操作 10 秒未完成后进入等待，读状态仍可用，新的 profile 写入被隔离；迟到的成功/失败被核对，没有第二次启停。
- Web 更新或取消后的恢复只执行一次、有独立 60 秒预算；版本、来源或声明入口未恢复时明确失败。官方 Desktop 只核对管理器处理后的实际构件与冻结状态，不额外恢复文件或重装。
- 管理器的 `applied`、`restart-required`、`overridden`、`failed`、`cancelled` 与未知结果不相互混淆；保留 `0.2.1-alpha.3` 返回的 `restartReason`。安装已应用与插件代码已加载分开判断；旧 Desktop 的待重启状态刷新后仍有效，但不禁止保存启停选择。
- 旧 Desktop 首次安装仅由市场推断需要重启时，使用/常驻后核对唯一主组件的启用与运行状态，并确认安装来源、版本及代码与首次安装构件一致，已生效即清除弹窗和横幅；异步加载完成后刷新同样清除。宿主明确要求重启、更新、修复及来源不明的旧记录保留；其他皮肤的重启记录不复制到当前目标。清单读取超时保留原记录，并释放操作队列，迟到结果不能清除后续操作的新重启要求。
- 默认安装链路不会因旧宿主版本或安装返回 `restart-required` 而遗漏后续使用流程；取消使用确认不启用，切换失败保留可恢复的旧选择和已安装包，不误报使用成功。更新有待确认风险时先停用，其他情况保留原选择，未知结果不继续写入。
- 普通进度只保留横幅；批准、可重试失败、结果待确认和重启等关键节点及时弹窗，同一结果去重，多个提示不叠层。关闭后保留横幅状态与日志，批准、失败和重启提示可重新打开；等待结束后显示真实结果。
- 过期/损坏锁文件与静默脚本超时分别提示，不能因误判网络错误而重试或重新解析其他插件。

每次人工验收记录：市场版本、宿主版本、平台/profile、测试皮肤、每一步结果及必要的截图/市场诊断日志。未执行、不能执行和失败分别写明；浏览器检查通过不写成“原生 Desktop 已验证”。

## 5. Web 回滚与清理

页面因皮肤冲突而无法操作时，先停止对应 DSH Web 进程，再运行：

```bash
~/.dsh/profiles/web/node_modules/.bin/dsh-skin-market-reset --profile web
```

重新启动后确认市场管理的皮肤已停用、默认外观恢复，安装包和无关插件保留。官方 Desktop 的恢复使用应用自身插件管理器，不运行上面的 Web 急救命令。

需要移除测试安装的市场时，先处理此次测试安装的皮肤，再在 Web profile 执行：

```bash
dsh plugin --profile web remove dsh-skin-market
```

官方 Desktop 在应用插件页移除。市场不会替用户删除其他插件或迁移第三方桌面壳的配置。

- 通知已读回归：皮肤安装/更新/启停失败、市场更新失败、新包授权、构件确认及构建授权点击知道了、取消或关闭后，同一通知不再显示横幅；刷新、轮询和重新进入市场仍保持已读。等待结果提示确认后隐藏横幅，但后台写锁与操作状态仍保留；同一操作后来转为失败时必须再次提示。新操作失败和新的重启事项均须正常提示。