dsh-autorestart 0.6.2 → 0.8.0

package/locale/zh.json

@@ -1,48 +1,99 @@
 {
-  "meta": {
-    "title": "Autorestart — 重启续接",
-    "description": "让 Agent 的工作跨 DSH 重启不中断：持久检查点、启动时重新武装目标或注入续接消息，以及 Agent 可自行请求的“空闲即重启”。"
-  },
-  "backupChoice": {
-    "title": "重启前自动备份：要不要把已安装的插件也一起备份？",
-    "body": "每次重启前会快照当前配置，万一重启后起不来就能自动回退。",
-    "withPlugins": "配置 + 已安装插件",
-    "withPluginsHint": "多约 3 秒、约 117 MB；插件把启动搞坏时也能回退。",
-    "configOnly": "只备份配置",
-    "configOnlyHint": "瞬间完成、约 66 KB；插件问题无法回退，需要手动重装。",
-    "footnote": "以后可在 设置 → 自动重启与关机 修改",
-    "pickPrimary": "用这个",
-    "pickSecondary": "只备份配置",
-    "recommended": "推荐",
-    "dismissAria": "关闭这个一次性提示"
-  },
-  "settings": {
-    "nav": "自动重启与关机",
-    "groups": {
-      "restart": "重启相关设置",
-      "shutdown": "关机相关设置"
-    },
-    "seconds": {
-      "label": "关机倒数秒数",
-      "immediate": "不倒数（立即关机）",
-      "value": "{n} 秒",
-      "hint": "所有会话收工后，屏幕上会显示这段倒数（可点「不关了」取消），数完才关机；想要更多落盘时间就把倒数调大。"
-    },
-    "restartGrace": {
-      "label": "重启前等待",
-      "immediate": "不等（立即重启）",
-      "value": "{n} 秒",
-      "hint": "重启没有倒数环节，会话一收工就会立刻重启；如果你装了“会话结束后才写”的记忆/总结类插件，把这里调大（默认 0 秒）。"
-    },
-    "backup": {
-      "label": "重启前备份",
-      "hint": "每次重启前先快照一次当前配置；万一重启后起不来，能自动回退。"
-    },
-    "backupPlugins": {
-      "label": "备份包含已安装插件",
-      "hint": "关闭后只备份 DSH 自身状态，不含 profile 里的插件目录。"
-    },
-    "error": "没能保存设置：{message}"
+  "label": "待重启",
+  "busyPrefix": " · 等待 ",
+  "busySuffix": " 个任务结束",
+  "idle": " · 空闲后自动重启",
+  "goalActive": " · 被某个自动续跑的 goal 占着",
+  "goalExhausted": " · 某个任务的 goal 轮次额度已用完，无法续跑",
+  "settling": " · 还在等这段安静期",
+  "parkedGoals": " · 已停泊 {n} 个 goal，重启后自动继续",
+  "parkButton": "停泊并重启",
+  "parkButtonAria": "停泊该会话的 goal，并立即请求重启",
+  "parkBusy": "停泊中…",
+  "parkError": "停泊失败：{message}",
+  "tooltip": "等待其他会话空闲后自动重启；重启后会自动继续本会话进度",
+  "tooltipBusy": "等待其他任务结束（计数含“排队但还没开始”的任务）后自动重启；重启后本会话会自动继续进度",
+  "tooltipWithError": "等待其他会话空闲后自动重启；重启后本会话会自动继续进度。{message}",
+  "dotAria": "待重启",
+  "panelHeading": "待重启",
+  "panelStateBusy": "等待其他会话空闲后重启",
+  "panelStateIdle": "等待空闲窗口后重启",
+  "panelStateGoalActive": "等待其他会话停泊它自动续跑的 goal",
+  "panelStateGoalExhausted": "等待其他会话的 goal（轮次额度已用完）",
+  "panelBlockedTitle": "占用会话：{title}",
+  "panelBlockedGeneric": "有一个任务正在运行",
+  "panelBlockedSession": "会话「{label}」正在运行",
+  "panelBlockedSubagent": "{name}正在运行",
+  "panelBlockedSubagentGeneric": "有一个子智能体正在运行",
+  "panelBlockedSubagentGroup": "会话「{label}」的 {n} 个子智能体正在运行",
+  "panelBlockedSubagentGroupGeneric": "有 {n} 个子智能体正在运行",
+  "panelBlockedRestartPending": "等这次重启完成后再关机",
+  "panelGoalActiveLine": "占用会话「{title}」：goal 正在自动续跑（goal-active）",
+  "panelGoalExhaustedLine": "占用会话「{title}」：goal 轮次额度已用完，无法继续（goal-exhausted）",
+  "panelParkedTitle": "已停泊的 goal（重启后自动继续）：",
+  "panelParkedGoal": "会话 {session} · {goal}",
+  "panelWaiting": "已等待 {duration}",
+  "panelResume": "重启后本会话会自动继续进度",
+  "longWaitPill": " · 已等 {duration} · {n} 项任务在跑",
+  "longWaitTooltip": "已等 {duration}。在跑：{blockers}",
+  "blockerGeneric": "有会话",
+  "blockerJoin": "、",
+  "blockerGroupSubagents": "{label}（{n} 个子智能体）",
+  "blockerGroupSubagentsGeneric": "{n} 个子智能体",
+  "blockerMore": "…等 {n} 项",
+  "blockersTitleLine": "占用会话：{blockers}",
+  "durationSeconds": "{n} 秒",
+  "durationMinutes": "{n} 分 {m} 秒",
+  "durationHours": "{n} 小时 {m} 分",
+  "durationMinutesShort": "{n} 分钟",
+  "durationHoursShort": "{n} 小时",
+  "durationHoursMinutesShort": "{n} 小时 {m} 分",
+  "cancelPanelTasks": "这次重启还在等 {n} 个任务结束",
+  "cancelPanelOthers": "还有 {n} 个会话也在等这次重启",
+  "cancelPanelOthersAfter": "还剩 {n} 个会话在等",
+  "cancelPanelAria": "待重启详情",
+  "cancelButton": "取消我的这次重启",
+  "cancelButtonAria": "取消我的这次重启",
+  "cancelConfirmTitle": "取消你的这次重启？",
+  "cancelConfirmOnlyMe": "取消后这次重启就不会发生了。",
+  "cancelConfirmOthers": "还有 {n} 个会话也在等这次重启——取消只影响你自己，他们仍会重启。",
+  "cancelConfirmUnknown": "当前会话未知，无法只撤自己。",
+  "cancelConfirmButton": "确认取消",
+  "cancelConfirmButtonAria": "确认取消这次重启",
+  "cancelDismissButton": "再想想",
+  "cancelDismissButtonAria": "算了，不取消",
+  "cancelFailed": "没能取消这次重启。",
+  "cancelFailedWith": "没能取消这次重启：{message}",
+  "cancelNotRequester": "这个会话没有请求这次重启，所以什么都没取消。",
+  "cancelNothingPending": "现在没有待重启的请求。",
+  "cancelUnknownSession": "当前会话未知，无法只撤自己。",
+  "cancelNoRoute": "找不到取消接口（宿主版本太旧）。",
+  "backupChoiceTitle": "重启前自动备份：要不要把已安装的插件也一起备份？",
+  "backupChoiceBody": "每次重启前会快照当前配置，万一重启后起不来就能自动回退。",
+  "backupChoiceWithPlugins": "配置 + 已安装插件",
+  "backupChoiceWithPluginsHint": "多约 3 秒、约 117 MB；插件把启动搞坏时也能回退。",
+  "backupChoiceConfigOnly": "只备份配置",
+  "backupChoiceConfigOnlyHint": "瞬间完成、约 66 KB；插件问题无法回退，需要手动重装。",
+  "backupChoiceFootnote": "以后可在 设置 → 自动重启与关机 修改",
+  "backupChoicePickPrimary": "用这个",
+  "backupChoicePickSecondary": "只备份配置",
+  "backupChoiceRecommended": "推荐",
+  "backupChoiceDismissAria": "关闭这个一次性提示",
+  "backupChoiceError": "保存失败：{message}",
+  "supervisor": {
+    "title": "让 DSH 自己把自己拉起来？",
+    "body": "现在这个 DSH 托管实例是手动/外部启动的——它挂了不会自己回来。我可以给你装一个自带的守护：登录时自动启动，进程掉了自动拉起，启动失败自动回滚上次快照。守护不会碰你的会话数据，只做「拉起 + 看住 + 回滚」三件事。",
+    "changes": "会改什么：新增 <stateDir>/supervisor/（守护脚本 + 配置 + 日志 + 锁）；Windows 注册一条登录自启记录（计划任务 dsh-autorestart-web），Linux 注册一个 systemd 用户服务。不改：会话数据、模型配置、已装插件。",
+    "rights": "需要什么权限：Windows 不需要管理员（用「登录时运行」；若该机策略禁止普通用户建计划任务，会自动降级到「启动文件夹」，同样不需要）；Linux 需要能写自己的家目录（systemctl --user，普通用户即可）。",
+    "uninstall": "怎么卸：设置页「开机自启 → 卸载」一键；或手动 schtasks /Delete /TN \"dsh-autorestart-web\" /F（Linux：systemctl --user disable --now dsh-autorestart-web.service && rm ~/.config/systemd/user/dsh-autorestart-web.service），两者都要再删掉 <stateDir>/supervisor/ 目录。",
+    "install": "帮我装（推荐）",
+    "installHint": "会写一个守护脚本到 <stateDir>/supervisor/，并在 Windows 注册一条登录自启记录 / Linux 注册一个 systemd 用户服务。不需要管理员。之后宿主进程退出，守护会在几秒内拉起它；起不来会自动回滚到重启前的快照。随时可以在设置里一键卸载。",
+    "keep": "保持我现在的启动方式",
+    "keepHint": "什么都不改。你现在用什么启动就继续用什么。代价：宿主进程退出后不会自动回来——重启功能会退化成「只能在有外部守护时生效」。",
+    "later": "以后再说",
+    "laterHint": "这张卡片不再出现。你可以随时在「设置 → 自动重启与关机 → 开机自启」里手动装。",
+    "error": "操作失败：{message}",
+    "busy": "正在处理…"
   },
   "sleep": {
     "button": {
@@ -61,26 +112,26 @@
     },
     "countdown": {
       "caption": {
-        "20": "鲸鱼娘开始收网了",
-        "19": "备份已经替你打包好",
-        "18": "没说完的话，再讲一句",
-        "17": "大家都在慢慢安静下来",
-        "16": "最后再巡一圈房间",
-        "15": "海面开始变暗了",
-        "14": "灯一盏一盏熄了",
-        "13": "房间已经安静下来",
-        "12": "还有一小会儿",
-        "11": "再看一眼屏幕吧",
-        "10": "鲸鱼娘在数最后几秒",
-        "9": "灯已经关了一半",
-        "8": "声音越来越小",
-        "7": "马上就到道别的时候了",
-        "6": "最后一口海水",
-        "5": "晚风越来越轻",
-        "4": "说声晚安吧",
-        "3": "真的只剩三秒啦",
-        "2": "还来得及说声再见",
         "1": "晚安 🌙",
+        "2": "还来得及说声再见",
+        "3": "真的只剩三秒啦",
+        "4": "说声晚安吧",
+        "5": "晚风越来越轻",
+        "6": "最后一口海水",
+        "7": "马上就到道别的时候了",
+        "8": "声音越来越小",
+        "9": "灯已经关了一半",
+        "10": "鲸鱼娘在数最后几秒",
+        "11": "再看一眼屏幕吧",
+        "12": "还有一小会儿",
+        "13": "房间已经安静下来",
+        "14": "灯一盏一盏熄了",
+        "15": "海面开始变暗了",
+        "16": "最后再巡一圈房间",
+        "17": "大家都在慢慢安静下来",
+        "18": "没说完的话，再讲一句",
+        "19": "备份已经替你打包好",
+        "20": "鲸鱼娘开始收网了",
         "default": "晚安 🌙"
       },
       "remaining": "还剩 {n} 秒",
@@ -117,11 +168,170 @@
       "error": "保存失败：{message}"
     }
   },
+  "nav": "自动重启与关机",
+  "settings": {
+    "groups": {
+      "restart": "重启相关设置",
+      "shutdown": "关机相关设置",
+      "supervisor": "开机自启",
+      "report": "报告问题",
+      "rescue": "出事了怎么办"
+    },
+    "seconds": {
+      "label": "关机倒数秒数",
+      "immediate": "不倒数（立即关机）",
+      "value": "{n} 秒",
+      "hint": "所有会话收工后，屏幕上会显示这段倒数（可点「不关了」取消），数完才关机；想要更多落盘时间就把倒数调大。"
+    },
+    "restartGrace": {
+      "label": "重启前等待",
+      "hint": "重启没有倒数环节，会话一收工就会立刻重启；如果你装了“会话结束后才写”的记忆/总结类插件，把这里调大（默认 0 秒）。",
+      "value": "{n} 秒",
+      "immediate": "不等（立即重启）"
+    },
+    "backup": {
+      "label": "重启前备份",
+      "hint": "每次重启前先快照一次当前配置；万一重启后起不来，能自动回退。",
+      "list": "现在备份了什么",
+      "count": "当前 {n} 份",
+      "keep": "最多保留 {n} 份，超出自动删最旧的那份。",
+      "empty": "还没有备份；每次重启前会自动生成一份。",
+      "path": "存放路径",
+      "copyPath": "复制路径",
+      "copied": "路径已复制",
+      "copyFailed": "复制失败，请手动选中上面的路径",
+      "withPlugins": "含已装插件",
+      "withoutPlugins": "只有配置"
+    },
+    "backupPlugins": {
+      "label": "备份包含已安装插件",
+      "hint": "关闭后只备份 DSH 自身状态，不含 profile 里的插件目录。"
+    },
+    "supervisor": {
+      "status": "当前由",
+      "installed": "插件守护",
+      "external": "你自己的方式",
+      "unknown": "未知",
+      "off": "关闭",
+      "capable": "重启能力",
+      "capableYes": "可用：宿主退出后会自动回来",
+      "capableNo": "不可用：宿主退出后不会自动回来",
+      "install": "装上守护",
+      "uninstall": "卸载守护",
+      "hint": "守护是一个独立进程：登录时自动启动，宿主进程掉了自动拉起，启动失败自动回滚上次快照。不需要管理员。",
+      "noInstallDesktop": "桌面版自带重启，这里不用装守护。",
+      "noInstallExternal": "已经有别的守护在管这个宿主：再装一个会两个一起拉起、抢同一个端口，所以这里不提供安装。",
+      "noInstallUnknown": "宿主没说清是谁在拉起它，所以这里不提供安装。",
+      "access": "当前访问链接",
+      "accessHint": "重启后 token 会变，链接也会变。这个链接一直是最新的。",
+      "pending": "卸载没有完成，请手动执行：{commands}",
+      "reason": "说明",
+      "command": "重启命令",
+      "derive": "推导重启命令",
+      "apply": "就用这条命令",
+      "revert": "撤销",
+      "noCommand": "推不出可重放的重启命令",
+      "plan": "干跑预览",
+      "reason.ok": "可以用这条命令重新拉起这个 DSH。",
+      "reason.desktop-app": "桌面版自带重启，不用管这条命令。",
+      "reason.not-a-web-host": "这个 DSH 不是网页型宿主，没有端口也没有监听器。",
+      "reason.argv-unavailable": "读不回启动命令行（它是被一个特殊方式拉起来的），所以不猜。",
+      "reason.external-supervisor": "已经有别的守护在管这个进程：装第二个会抢端口。改为「优雅退出，让它拉起我」。",
+      "reason.container-no-init": "这台机器没有开机自启机制（容器），所以不承诺自动拉起。",
+      "reason.port-not-fixable": "端口每次都变，浏览器会被踢出去；得先把端口固定下来。",
+      "reason.supervised": "插件自己的守护在管这个进程，重启直接交给它。",
+      "status.external": "我记下的启动方式：由你的脚本拉起（重启交给它，我不插手）",
+      "status.bareWritten": "我记下的启动方式：按你确认过的那条命令重启",
+      "status.bareUnknown": "我还不知道怎么把你拉起来",
+      "status.unknown": "我看不出你是怎么启动的（我不猜，也不会自己乱拉）",
+      "status.selfSupervised": "我记下的启动方式：插件自己的守护在管（重启交给它）",
+      "status.container": "这里没有\"登录时自启\"这回事：由编排器负责",
+      "redetect": "重新检测",
+      "deriveHelp": "帮我看看怎么重启",
+      "technical": "技术细节",
+      "technicalHint": "以下是插件实际会执行的命令",
+      "previous": "撤销后会还原成",
+      "app": "桌面版自带重启",
+      "startup": "启动方式",
+      "startup.bare": "手动启动（没人管它）",
+      "startup.external": "由别的守护在管",
+      "startup.container": "容器里（由编排器管）",
+      "startup.desktop": "桌面版自带重启",
+      "startup.selfSupervised": "插件自己的守护在管",
+      "startup.unknown": "认不出是谁拉起它的",
+      "autostart": "开机自启怎么做"
+    },
+    "report": {
+      "label": "遇到问题了？",
+      "github": "复制诊断信息并去 GitHub 提问题",
+      "hint": "诊断信息里没有你的访问令牌，也没有任何密钥；把它贴进 issue，我们就能看出问题出在哪。",
+      "email": "没有 GitHub 账号？发邮件到 {email}",
+      "copy": "复制诊断信息",
+      "copyFailed": "复制失败，请手动复制这段",
+      "issueTitle": "重启 / 开机自启相关的问题",
+      "issueBody": "请把刚才复制的诊断信息粘贴到下面。\n\n## 发生了什么\n\n\n## 期望什么\n\n\n## 怎么复现\n"
+    },
+    "rescue": {
+      "hint": "DSH 打不开的时候，用下面这两个脚本救自己（都不用 DSH 跑起来）。",
+      "restoreProfile": "回到上一次好状态",
+      "emergencyDisable": "只把这个插件摘掉",
+      "path": "路径",
+      "copyPath": "复制路径",
+      "copied": "路径已复制",
+      "copyFailed": "复制失败，请手动选中上面的路径",
+      "reveal": "打开所在文件夹",
+      "which": "怎么选：整个环境坏了（改了配置、装了别的插件、升级崩了）→ 用「回到上一次好状态」；只怀疑这个插件 → 用「只把这个插件摘掉」。",
+      "warning": "重要：这两个脚本是在 DSH 打不开的时候用的。DSH 正开着的时候用「回到上一次好状态」，会把你现在正在用的配置覆盖掉。",
+      "shortcut": "在桌面放一个快捷方式",
+      "shortcutDone": "已在桌面",
+      "noDesktop": "这台机器上没有桌面目录，所以放不了快捷方式（脚本的路径在上面，可以手动复制过去）。",
+      "shortcutFailed": "快捷方式没放成：{message}",
+      "revealFailed": "文件夹没打开：{message}",
+      "rollbackOk": "自动回滚：可用（重启后起不来会自动回到上一个好状态）",
+      "rollbackBlocked": "自动回滚：**不可用** —— 这台电脑不允许创建计划任务。**会丢失：重启后 DSH 起不来时不会自动恢复**；出问题时请双击「出事了怎么办」里的还原脚本。",
+      "rollbackUnknown": "自动回滚：还不知道（这台机器的能力还没检查过）",
+      "watchdogTier": "看门狗的触发方式：{tier}",
+      "watchdogLast": "上一次看门狗的结果：{result}",
+      "tierScheduledTask": "Windows 计划任务",
+      "tierSystemdRun": "systemd 定时器",
+      "tierDetachedProcess": "自建后台进程",
+      "tierNone": "（这台机器没有可用机制）"
+    },
+    "error": "没能保存设置：{message}",
+    "autostartKind": {
+      "other": "其他方式",
+      "windows-task": "Windows 计划任务",
+      "windows-startup": "Windows 启动文件夹",
+      "systemd-user": "systemd 用户服务",
+      "systemd-system": "systemd 系统服务",
+      "wsl-systemd": "WSL 里的 systemd",
+      "wsl-no-systemd": "WSL（没有 systemd）",
+      "container": "容器",
+      "desktop": "桌面版自带重启",
+      "unknown": "认不出",
+      "pm2": "pm2（进程守护工具）"
+    },
+    "startupWhy": {
+      "desktop": "这个进程就是桌面客户端本体，它自己会重启自己",
+      "bare": "它是被人在终端里手动起的，没人管它",
+      "external": "它是由另一个守护进程拉起来的",
+      "container": "它跑在容器里，由编排器负责",
+      "unknown": "看不出它是怎么被拉起来的",
+      "self-supervised": "它由本插件自己的守护在管"
+    }
+  },
+  "meta": {
+    "title": "dsh-autorestart — 重启不断线",
+    "description": "让 DeepSeek Harness 重启后接着干活：落盘的检查点、启动时重新武装 goal 或给一条续接提示，以及一次等人闲下来的优雅重启。"
+  },
+  "text": {
+    "missing": "（这条文案还没写）"
+  },
   "announcement": {
     "title": "新功能：收工关机",
     "line1": "左侧栏最底部多了一个 🌙「收工关机」按钮。",
     "line2": "点一下 → 所有会话收工后倒数 {n} 秒关机。",
-    "line2Generic": "点一下 → 所有会话收工后倒数几秒关机。",
+    "line2.generic": "点一下 → 所有会话收工后倒数几秒关机。",
     "line3": "想改行为，去「设置 → 自动重启与关机」。",
     "disabled": "按钮目前关闭，可在设置里打开。",
     "button": "知道了",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "DeepSeek Harness plugin: restart without losing work. Waits until every conversation is idle, restarts the host, then automatically resumes the interrupted sessions. AI-generated, not human-reviewed: use with caution.",
   "license": "MIT",
@@ -31,6 +31,9 @@
     "index.js",
     "client.js",
     "lib/**/*.js",
+    "supervisor/supervisor.js",
+    "scripts/*.ps1",
+    "scripts/*.cmd",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
@@ -46,7 +49,9 @@
     "client": {
       "platform": "web",
       "immediately": true,
-      "inject": ["@deepseek-ai/dsh-client-ui-conversation"]
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
     },
     "compatibility": {
       "dshReleases": {

package/screenshots.json

@@ -1,5 +1,7 @@
-[
-  "assets/screenshot-1.png",
-  "assets/screenshot-2.png",
-  "assets/screenshot-3.png"
+[
+    "assets/screenshot-1.png",
+    "assets/screenshot-2.png",
+    "assets/screenshot-3.png",
+    "assets/screenshot-4.png",
+    "assets/screenshot-5.png"
 ]

package/scripts/README.md

@@ -0,0 +1,65 @@
+# 自救包（scripts）
+
+DSH 起不来的时候，这个文件夹里的东西**不用 DSH 自己**就能救自己。
+
+## 按平台挑文件（**别拿错平台的**）
+
+| 你的机器 | 还原 profile | 摘掉本插件 |
+|---|---|---|
+| **Windows**（桌面客户端 / Windows 上的 `dsh web`） | 双击 `restore-profile.cmd` | 双击 `emergency-disable.cmd` |
+| **Linux / WSL / macOS**（托管端） | `sh scripts/restore-profile.sh` | `sh scripts/emergency-disable.sh` |
+
+Linux/WSL 的机器上**没有** `.cmd` 文件，Windows 的机器上**没有** `.sh` —— 设置页的
+「出事了怎么办」只显示**这台机器上真有的**那两个路径，不会给你一条走不通的死路。
+每个平台到底有什么能力，看 [平台能力矩阵](../docs/platform-matrix.md)。
+
+- **双击哪个**：DSH 起不来（插件升级把 profile 弄坏了）→ 还原；只是想把本插件摘掉 → 摘插件。
+- **找不到它们？**：设置页里有一组「出事了怎么办」，上面写着这两个脚本的**绝对路径**（可以一键复制、可以一键打开所在文件夹；Windows 上还能放一个桌面快捷方式）—— DSH 真打不开、连 README 都打不开的时候，那一栏就是给你指路的。
+- **它会做什么**：`restore-profile.cmd` / `restore-profile.sh` 把最新的那份快照（`<stateDir>/backups/` 里带 manifest 的）放回 profile —— 先把现在的 profile 整份挪到 `<profile>.broken-<时间戳>`，再复制快照里的配置和插件树，最后回读校验（package.json 能解析、`dsh.profile.bundles` 有内容、插件版本号读得到）；校验不过就如实报错，并告诉你原来那份还在哪个目录。**它不会替你重启 DSH**（重启由你自己来，免得"救一次挂一次"）。
+- **会留下什么**：一个 `<profile>.broken-<yyyyMMdd-HHmmss>` 目录（出事之前的那份 profile 原封不动地留着，确认没问题后可以自己删掉），加上最后一行"已还原到 …… 现在可以重新打开 DSH"的结论。
+
+## 两条硬规矩（有意收紧，不是 bug）
+
+- **目标 profile 目录必须已经存在**：还原器把快照放回一个**已经存在**的 profile，**不会凭空新建**一个 profile（也不会替你建 `profiles` 目录）。路径写错的时候，宁可报错，也不留一个空壳 profile 在那儿。
+- **插件版本号的校验看配置说话**：profile 的 `dsh.profile.bundles` 里**没有** `dsh-autorestart` → 这一项**跳过**；**声明了**、但 `node_modules/dsh-autorestart` 不在 → **必须失败**（配置说一套、磁盘是另一套，这是真坏，不能放过）。
+
+## 演练（不碰你正在用的 profile）
+
+| 平台 | 命令 |
+|---|---|
+| Windows | `powershell -NoProfile -ExecutionPolicy Bypass -File .\drill-rescue.ps1` |
+| Linux / WSL | `sh scripts/drill-rescue.sh` |
+
+两个演练是**同一套断言**（Windows 的 `.ps1` 与 POSIX 的 `.sh`）：在临时目录里造一个假 profile → 故意把 `package.json` 写坏、删掉插件目录 → 调还原脚本救回来 → 断言（能解析、插件版本读得到、`broken-*` 目录存在、非 profile 目录被拒绝、目标目录不存在时被拒绝、"配置说装了却没装"时必须失败、**还原脚本的输出里真的有中文**）→ 清理临时目录。全绿时退出码是 0。
+
+演练的目录纪律（**并发跑也互不干扰**）：每次跑用一个带完整 GUID 的**唯一**目录，目录由本次演练自己创建（已存在就报错退出），目录里放一个独占的锁文件 `.lock`；清理**只删自己那一个绝对路径**，**绝不按前缀/通配符扫临时目录** —— 那会踩到同时在跑的另一个演练。成功、断言不过、抛错中断，走的都是同一个 `finally`，一定会清理；清理不干净就把残留路径打印出来。
+
+`restore-profile.ps1` 的参数：`-DryRun`（只打印将要做什么）、`-Snapshot <目录>`（指定某一份快照）、`-ProfileDir <路径>`（演练用的隔离目录）、`-StateDir <路径>`（插件状态目录，默认 `<DSH_HOME>/storages/dsh-autorestart`）。
+`restore-profile.sh` 的参数：`--dry-run`、`--snapshot <目录>`、`--profile <路径>`、`--state-dir <路径>`。`DSH_HOME` 可以用环境变量覆盖，但目标 profile 目录必须已经在那儿。
+
+> 编码规矩（为什么脚本是英文的）：这台机器只有 Windows PowerShell 5.1，它按 ANSI 读**不带 BOM 的 UTF-8** —— 脚本里只要有一个中文字符，整份文件就变乱码、直接 ParserError，脚本连第一步都走不到。POSIX 那边同理（`/bin/sh` 也按字节读，而且中文注释会让不同的 shell 表现不一致）。这个坑一天之内踩了三次，所以现在是**根治**而不是"记得加 BOM"：**所有 `.ps1` / `.sh` / `.cmd` / `.mjs` 必须是纯 ASCII（所有字节 < 128、不带 BOM）**。面向用户的中文全部放在**一个文件**里：`scripts/rescue-strings.zh.json`（UTF-8、**不带 BOM**，带 BOM 会让 `JSON.parse` 直接失败），脚本运行时读它；读不到或读坏了，脚本会用**英文兜底**继续跑，并明确打印一行英文说明（不会崩成乱码）。
+>
+> **以后要改文案，改 `rescue-strings.zh.json`，不要往脚本里塞中文。** 键名是语义化的（`restore.title`、`restore.brokenKept`、`drill.passed`、`emergency.failed` …），值里可以用 `{0}`、`{1}` 这类占位符。这条规矩由 `test/scripts-encoding.test.mjs` 天天盯着：它会扫目录（不是写死文件名）、断言每个 `.ps1` / `.sh` / `.mjs` 都是纯 ASCII、断言 `.sh` 以 `#!/bin/sh` 开头并开着 `set -eu`、断言 JSON 无 BOM 且能被 `JSON.parse`、断言每个脚本里用到的键在 JSON 里都存在、断言 `.cmd` 调的是 `powershell.exe` 而不是 `pwsh`。
+
+## 写 POSIX 脚本时踩过的三个坑（别再踩一次）
+
+这三个都是**真跑出来的**（不是猜的），症状和原因都写在这儿：
+
+1. **`/bin/sh`（dash）会数单引号里的括号。**
+   一段 `$( ... )` 里如果有一段**单引号包起来的英文兜底文案**，而那个文案里有一个
+   没配平的 `)`，整份脚本会直接语法报错（`Syntax error: ")" unexpected` / `expecting ")"`），
+   **而且报错的位置在后面很远的地方**，很难看出是哪一行害的。
+   → **兜底文案里不要出现括号**。要写就写成 `-` 或 `:`。
+2. **双引号包起来的 sed 表达式会被 shell 吃掉转义。**
+   `sed -n "s/.*\"$key\".../\1/p"` 里的 `\"` 会被 shell 先处理掉，表达式在引号那里被截断，
+   sed 报 `unterminated 's' command`（而且报错只给 char N，看不出是引号的问题）。
+   → **sed 表达式要么全单引号，要么用 `'...'"$var"'...'` 的拼接写法**。
+3. **文案 JSON 是嵌套的**（`restore.title` 是一条路径，不是文件里的键）。
+   用一条平铺的 sed 去找 `"restore.title"` 永远找不到 → 脚本会静悄悄地退回英文，
+   **功能全对、只是没有中文**，特别难发现。
+   → **按路径取值**：用 node 读 JSON（`process.argv[2].split(".")` 一层层取），
+   顺便把 `{0}`/`{1}` 的占位符替换也交给 node —— 中文是 UTF-8，**按字节的 sed 会把它弄坏**。
+
+这三个坑的共同点：**症状离原因很远**（语法错在后面、或者干脆不报错只是少了中文），
+所以每个脚本都尽量把"取值"和"拼字符串"这两件事交给 node，只在 node 不在时才退回
+那一小段 ASCII 兜底逻辑。