flycucu/dsh-icon-changer

【本插件代码由 DeepSeek Harness 生成】

dsh-icon-changer

更新日志

DeepSeek Harness 桌面端的应用图标更换器插件：把官方 exe 内嵌的图标换成你自己的 .ico，也能一键回退成官方默认。

宿主半区（lib/index.js，跑在 DSH 主进程里）通过 ctx.webServer 挂一组 API； 客户端半区（lib/client.js）往设置页注册一张卡片，所以不需要手输 URL。 两侧都不引入任何 npm 依赖。

为什么需要"退出后才换"

Windows 会锁住正在运行的可执行文件，而这个插件就跑在它要改的那个 exe 里。 所以 API 不会当场动手，而是：

1. 校验请求，把任务写进 state.json 与 pending-job.json
2. 用 WMI（Win32_Process.Create）拉起 worker —— 关键点：直接 spawn 的子进程会随应用被 job object 一起干掉，而 WMI 创建出来的进程挂在 wmiprvse.exe 名下，不受应用 job object 约束，能在应用退出后继续活着
3. worker（bin/apply-icon.ps1）轮询等待 exe 被释放
4. 备份 → 用 rcedit 改写图标 → 比对改前/改后/目标三者的图标指纹
5. 指纹没变且不等于目标图标才自动还原并报失败；成功则（可选）重新拉起应用（应用已在跑就不重复拉）
6. 刷新 shell 图标缓存：worker 立刻跑一次 ie4uinit.exe -show，并把 pendingExplorer 写进 state.json； 应用重启后宿主侧 reconcilePendingExplorer() 会调 bin/refresh-shell.ps1 做完整刷新： ie4uinit -show → 停 Explorer → 抢删 iconcache_16/32/48/256/wide/idx.db → 起 Explorer → 广播 SHCNE_ASSOCCHANGED

也就是说：改图标必然伴随一次应用重启，这是平台限制，不是偷懒。

任务卡住时怎么自愈（都是踩过的坑）

• 那个窗口是"只读且关不掉"的：Windows 控制台默认开着 QuickEdit，鼠标一拖选文字就会把里面的进程暂停（标题会多出 选择 前缀）。 本机真踩过：worker 冻在第一步、exe 没改写、队列永远挂着。 run-worker.ps1 现在启动做两件事：
  1. 输入模式整个清零（实测 0x01F7 → 0x0000）：鼠标点击/拖选、键盘、Ctrl+C 都不再交给进程 （ENABLE_PROCESSED_INPUT 关掉，误按也不会打断）；只动输入缓冲，输出与任务本身完全不受影响。
  2. 摘掉系统菜单里的"关闭"（GetSystemMenu + DeleteMenu(SC_CLOSE)，实测菜单项 10 → 9、 GetMenuState(SC_CLOSE) 返回"不存在"）：因此 × 与 Alt+F4 都点不动；最小化/最大化/移动保留（无害）。 真的需要中止时，用任务管理器结束那个 powershell.exe —— 这是刻意保留的唯一逃生口。 等应用退出的长等待型任务本来就用 -WindowStyle Hidden 无窗口运行。
• 下次启动自动接续：宿主会记下 worker 的 pid（workerPid）。若某次启动发现"队列还在、而那个 worker 已经没了"， reconcileStalledPending() 就把任务交给重试路径，用 -WindowStyle Hidden 在后台重跑（实测：任务被成功补完）。
• 两个 waiter 不会打架：任务里带 jobId（= 入队时间）。worker 拿到 exe 锁后先核对队列是否仍是自己那一版， 否则打印 SUPERSEDED 并什么都不改就退出；pendingExplorer 也由 worker 在真正改写成功后设置， 不再由宿主在"刚拉起 worker"时就提前置位（那会导致刷了缓存但图标还没换）。
• 队列里的 pending 显示为"上次任务没有跑完"时，可以点「取消排队」，或直接再点一次应用（新请求会覆盖它）。

只改 exe 而不刷缓存，图标文件是新的、shell 还在供旧位图（本机实测：exe 指纹、 三个快捷方式全对，桌面仍显示旧图标）。只重启 Explorer 也不够 —— 缓存库会活下来， 必须删库；而 AutoRestartShell=1 会在杀掉 Explorer 后约 1 秒把它拉回、重新锁住文件， 所以删库必须"杀+抢删"带重试（refresh-shell.ps1 已按此实现，实测 6/6 删除成功）。

排查入口只有一个：$DSH_HOME/icon-changer/helper.log。宿主侧以 [host] 前缀、 启动器以 [wmi-spawn] 前缀、worker 以自己的时间戳写入，任何一环失败都能在这里看到。

安装

装法就是"放到磁盘上 + 挂进 profile"，仓库里没有安装脚本。先把代码取到本地：

git clone https://github.com/flycucu/dsh-icon-changer.git "$env:USERPROFILE\.dsh\plugin-src\dsh-icon-changer"

然后两处链接：

1. 把插件目录挂进 profile：mklink /J "%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-icon-changer" "<插件目录>"
2. 在 %USERPROFILE%\.dsh\profiles\desktop\package.json 里加依赖 "dsh-icon-changer": "link:<插件目录>"， 并把 dsh-icon-changer 加进 dsh.profile.bundles（宿主半边靠这一条进 Loader，客户端半边靠它被 roster 扫到）

改完 package.json 要重启 DeepSeek Harness；客户端半边只在启动扫描时进入启动图， 不重启不会出现设置卡片。改动前先备份 package.json（它属于启动关键配置）。

卸载：从 dsh.profile.bundles 与依赖里删掉，再删 junction。

用法（设置页，推荐）

打开 设置 → 应用图标：

• 选图标：内置图标（assets/whalemaid.ico → 显示为「鲸鱼娘（预置）」，assets/original.ico → 显示为「原版」） 与已上传的图标并排显示，点一下选中；文案见宿主 BUNDLED_LABELS，改文案要重启应用才生效
• 上传 .ico：宿主要求合法的 ICONDIR 头，不是 ico 会被拒（not-an-ico）； 上传的图标可以配一个 <名字>-tray.ico 伴生文件（放 $DSH_HOME/icon-changer/icons/），托盘会优先用它
• 应用选中图标并重启：排队后应用自动退出、worker 改写、再自动拉起
• 回退官方图标：从首次更换时留下的备份还原
• 删除：只有未使用的外部上传图标右上角才有 ×（悬停显示）。内置/原版没有 ×， 正在使用中的那个也没有；宿主侧同样拒绝（in-use / builtin-readonly），旧页面绕不过去

每张卡片固定留出"类型词条"与"当前使用"两行的高度：上传的图标没有词条，但用等高空位占住， 免得它那张卡片比别的矮、整行看着变形。

卡片顶部常驻 「当前图标」，并且默认停在应用当前真正穿着的那个图标上 （宿主把 state.applied.icon 反查成图标 id 作为 appliedId 返回；用户手动点过别的图标后不再覆盖他的选择）， 对应那张卡片还会挂一个绿色 当前使用 角标。卡片同时显示目标 exe 路径、排队中的任务、上次执行结果。

更换时弹出的那个 PowerShell 窗口：会依次显示 正在更换图标，请勿关闭此窗口 → 正在等待应用退出… → 正在写入新图标… → 图标已写入，正在重新启动应用… → 已完成，本窗口即将自动关闭，然后进程退出、窗口自己关掉（关掉窗口 = 杀掉任务，所以别手动关）。 等待用户自己退出应用的那类任务（restart:false / 启动补做）可能等很久，会用 -WindowStyle Hidden 静默运行，不弹窗。

用法（独立页面，备用）

http://127.0.0.1:<端口>/icon-changer（端口就是 Web GUI 那个，把路径换掉）。 页面上的按钮和设置卡片一一对应，UI 出问题时可以走这条。

HTTP API

图标 id 形如 builtin:whalemaid.ico 或 user:my_icon.ico。 所有写操作都过同源校验（Origin 与 Host 不一致直接 403）。

数据与回滚

手工回滚（插件用不了时的兜底）：

Copy-Item "$env:USERPROFILE\.dsh\icon-changer\backup\DeepSeek Harness.exe.orig" `
          "<你的安装目录>\DeepSeek Harness.exe" -Force

备份是在首次更换之前做的，所以它始终是官方原版，多次换图标也不会被覆盖成中间态。

结构

icon-changer/
  package.json          # dsh.bundle.patch 指向 cordis.patch.yml；dsh.client 声明浏览器半边
  cordis.patch.yml      # 往 profile 插一行宿主插件
  lib/index.js          # 宿主半区：路由、状态、任务落盘、用 WMI 拉起 worker
  lib/client.js         # 客户端半区：设置页卡片（__ModuleLoader__ + React，无构建步骤）
  lib/ui.html           # 独立管理页面（备用，原生 JS）
  bin/wmi-spawn.ps1     # 启动器：读命令行文件 → Win32_Process.Create（逃出应用 job object）
  bin/run-worker.ps1    # bootstrap：读 pending-job.json → 调 apply-icon.ps1
  bin/apply-icon.ps1    # worker：等待解锁 → rcedit → 校验 → 记状态 → 可选重启
  bin/refresh-shell.ps1 # 刷 shell 图标缓存：ie4uinit → 杀 Explorer → 抢删 iconcache → 起 Explorer → 广播
  bin/console-messages.ps1 # 给 worker 窗口取中文提示（dot-source 共用）
  bin/messages.txt      # 中文提示文案（UTF-8 数据文件；脚本本体保持 ASCII-only，避免 PS 5.1 无 BOM 乱码）
  tools/rcedit-x64.exe  # rcedit 2.0.0（Electron 官方维护的 PE 资源编辑工具）
  assets/whalemaid.ico  # 内置图标
  _test_plugin.mjs      # 自测：mock cordis 上下文，真跑 /apply 全链路

自测（用一份改名的 node.exe 副本当"应用 exe"，DSH_HOME 指向临时目录， 所以只会改那份副本；别传 restart:true，那条路会 taskkill 真的应用）：

$t = "$env:TEMP\ic-test"; New-Item -ItemType Directory -Force $t | Out-Null
Copy-Item (Get-Command node).Source "$t\DeepSeek Harness.exe"
$env:DSH_HOME = "$t\home"
& "$t\DeepSeek Harness.exe" .\_test_plugin.mjs
Get-Content "$t\home\icon-changer\helper.log"   # 等几秒，看 RESULT ok=True

# 第二阶段：证明宿主能把 worker 写的 state 读回来（BOM 回归守卫）
& "$t\DeepSeek Harness.exe" .\_test_plugin.mjs --status-only

只做语法检查：npm run check。

安全与信任模型

• 所有路由挂在 ctx.webServer 上、只监听 127.0.0.1，不带 Web GUI 的 token：本机任何进程都能调 /apply。 跨源浏览器页面会被 sameOrigin() 挡掉（Origin 与 Host 不一致 → 403），所以拦住的是网页，不是本机程序。 换句话说：同用户、同机器即受信，与"能改本机 exe 的桌面插件"这一前提一致。若你的机器上有不受信的本机程序，请自行取舍。
• 上传走 ICONDIR 头校验 + 4 MiB 上限 + 文件名净化（basename + 非 \w 压成 _），预览/删除都只认数据目录里的图标 id， 不接受任意路径。
• 删内置/原版或正在使用中的图标会被宿主拒绝（builtin-readonly / in-use），即使绕过界面直接调接口也一样。
• 改写 exe 会破坏该文件的代码签名（若有），Windows SmartScreen 可能提示；官方 exe 备份在首次更换前就留下了， 可随时整字节还原。

许可

本插件为 MIT（见 LICENSE）。随仓库分发的第三方组件与内置图标说明见 THIRD_PARTY_NOTICES.md：tools/rcedit-x64.exe 来自 electron/rcedit（MIT, Copyright (c) 2013 GitHub, Inc.）； assets/whalemaid*.ico 为作者自有美术资源，assets/original*.ico 是官方原版应用图标（仅为方便回退而收录）。

已知限制

• 只在 Windows 上工作（依赖 WMI、PowerShell 5.1、PE 资源改写与 shell 缓存机制）。
• 只在桌面端工作：若 DSH 是以 npx dsh web 跑的（process.execPath 是 node.exe），/apply 返回 not-desktop-app。
• 改图标必然伴随一次应用重启：运行中的 exe 被系统锁住，这是平台限制（流程见上文）。
• 应用升级（重装/覆盖安装）会换回官方 exe，重新应用一次即可。
• 独立页 lib/ui.html 只做"看状态 + 换图标/回退 + 看日志"，删除图标请走设置页卡片。