dsh-restart-module 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# dsh-restart — 会话内自重启 DSH
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 DSH 加一个模型可调用的工具 `dsh_restart`：任意会话（桌面 GUI / `dsh web` / QQ 机器人 / 其它终端）
+在写完文件、改完插件或配置之后，可以自己排一次重启让改动生效，不再需要外部 `restart-dsh-*.bat`。
+
+## 为什么不用 dshmarket 的一键重启
+
+市场插件（`dshmarket` 1.66.21）自带 self-restart，但在本机桌面版上结构不成立：
+
+1. `dshArgv()`（`dshmarket/src/dsh-cli.ts:468`）只在 `process.argv[1]` 匹配
+   `/[\\/](?:bin\.(?:js|ts)|dsh)$/` 时才重放原命令；桌面宿主的 argv[1] 是
+   `...\dsh-desktop-host\lib\index.js`，匹配不上 → 回退成裸 `dsh`，
+   重放出来的是 web CLI 而不是 `F:\dsh\DeepSeek Harness.exe`。
+2. 它的 helper 由宿主 `spawn(detached)` 出来，仍在宿主的 Job 里；宿主 500 ms 后
+   `process.kill(process.pid,'SIGTERM')` 自杀，Job 关闭会把 helper 一起带走 —— 没有活口重拉。
+
+所以本插件复用已经实测跑通的独立重启器 `F:\dsh\001X\restart-module`：
+
+```
+dsh_restart(schedule)
+  └─ node trigger-restart.mjs --delay N
+       ├─ 写 request.json
+       └─ WMI Win32_Process.Create('cmd.exe /c run-helper.cmd')   ← 脱离 DSH 进程树与 Job
+            └─ node dsh-restart-helper.mjs
+                 ├─ 等到 scheduledAt
+                 ├─ taskkill /F /T /IM "DeepSeek Harness.exe"
+                 ├─ 等 8 个进程与 127.0.0.1:19387 双双消失
+                 ├─ spawn F:\dsh\DeepSeek Harness.exe（清理 ELECTRON_RUN_AS_NODE / DSH_* 环境）
+                 └─ 轮询端口最多 120 s，失败重拉一次，写 logs\result.json
+```
+
+实测：杀进程到端口重新可访问 ≈ **2.1 s**，会话靠 `session/end-seed` 自动恢复，
+只丢失当时正在执行的那一次工具调用。
+
+## 工具
+
+单个工具 `dsh_restart`，用 `action` 区分三种操作：
+
+| action | 作用 | 常用参数 |
+| --- | --- | --- |
+| `schedule`（默认） | 排程一次重启 | `delay_sec`（5–3600，默认 60）、`note`、`dry_run`、`force`（默认 false，见守卫节）、`wake`（默认 true，见唤醒节）、`wake_note` |
+| `status` | 查上次结果 / 是否有待执行请求 / 最近一条插件日志 | — |
+| `cancel` | 杀掉等待中的 helper 并删 `request.json`；即使只删 `request.json`，helper 也会在 0.5 s 内自查作废、绝不杀进程（实测 03:59:12Z pid=32868 killed，App 未重启） | — |
+
+返回里带 `scheduledAt`（ISO UTC）、`helperPid`、`delaySec`；`dry_run: true` 只验证链路不杀进程。
+
+典型用法（agent 写完文件后）：
+
+```json
+{ "action": "schedule", "delay_sec": 30, "note": "装完插件让改动生效" }
+```
+
+## 忙时禁重启守卫
+
+「其他会话正在跑任务时不许重启」是默认行为，防止把别人的回合打断在半路。
+
+- **排程阶段**：`trigger-restart.mjs` 先探一次——`GET /dsh-market/status` 的 `runningAgents`，加上各会话
+  transcript（`session.v4.jsonl.zstd`）mtime 是否在 3 秒内被写过；除发起会话外还有活人就直接拒绝
+  （退出码 7，工具返回 `reason: "others-busy"`），不写 `request.json`、不启动 helper。
+- **到点阶段**：helper 在 kill 之前再等「连续 3 秒没有任何其他会话活动」，最长等 `quietWaitSec`
+  （默认 180 秒，排程时写进 `request.json`）；等不到就中止——**不杀进程**，写
+  `{ "ok": false, "reason": "others-busy", "busy": [...] }` 到 `result.json`，退出码 3。
+- **用户明确同意**（例如「现在就重启，别等了」）时传 `force: true`：两步都跳过，只在日志里记一行。
+  不带 `force` 的自动重启永远不会打断别的会话。
+- **判据实现**：`F:\dsh\001X\restart-module\busy-check.mjs`（只读，不写落盘）。可单独跑：
+  `node F:\dsh\001X\restart-module\busy-check.mjs --self session-xxxx --max-wait 0`（忙时退出码 3）。
+- **邮件告知/获准**那条通路暂未实现，等与 `dsh-crossterm` 互通插件配对后再接；`request.json` 里留了
+  `"notify": "pending-crossterm-integration"` 占位。
+
+## 重启后自动唤醒（wake）
+
+重启会打断当前回合；重启后桌面 App 会恢复上次会话，但不会自己继续——要等人输入。默认开启的 wake 补的就是这一步：
+
+- helper 在 kill 之前把 `{ sessionId, text, createdAt }` 写进 `F:\dsh\001X\restart-module\logs\wake.json`。
+- 新宿主起来、插件把工具挂到该会话时读这张卡（10 分钟内有效、`sessionId` 必须匹配），2.5 秒后调
+  `agent.followup({ content: [{ type: 'text', text }], source: { kind: 'user' } })` —— 这是一条普通用户消息，
+  会立刻唤醒会话继续干活；成功后 `plugin.log` 留一行 `wake: injected into <sessionId>`。
+- 默认文案：「DSH 已于 <时间> 完成重启，请继续刚才的工作；若上一回合被中断，先核查中断点再续。」
+  可用 `wake_note` 追加说明；不想唤醒传 `wake: false`（helper 日志记 `wake: skipped`）。
+- 卡片只有 10 分钟寿命：重启没发生（被 cancel、被守卫中止）时过期自动丢弃，不会误唤醒。
+- 与「邮件告知/获准」是两件事：wake 是重启后的自唤醒，不依赖 `dsh-crossterm`。
+- **实测（2026-10-18T03:46:40Z）**：`idle guard` 等满 3.019 s → 写卡 → kill 8 进程（0 s 消失）→ 新宿主 2.15 s 拉起 →
+  `03:46:46.483Z wake: injected into session-a3e9f80e-…`，即**杀进程到会话自动开工 ≈6.3 s**，`wake.json` 随后被消费删除。
+
+## 时间口径
+
+- 工具参数 `delay_sec` 是**相对秒数**，与服务器时区无关。
+- 日志与返回值里的 `scheduledAt` / `startedAt` / `finishedAt` 是 **ISO 8601 UTC**（结尾 `Z`），
+  本地时间 = UTC + 8（`15:54:09Z` = `23:54:09`）。
+- `plugin.log` / `helper-*.log` 用的是带 `Z` 的 UTC 时间戳。
+
+## 安装 / 卸载
+
+**npm 包名 `dsh-restart-module`**（0.2.0 起；`dsh-restart` 这个名字在 npm 上被别人占用了，
+与本插件无关）。本机开发源仍用 `link:` 安装，其他机器用包名安装。
+
+```bat
+:: 其他机器（npm）
+dsh plugin --profile desktop add dsh-restart-module
+dsh plugin --profile desktop remove dsh-restart-module
+
+:: 本机开发源（link:，改源码即生效）
+dsh plugin --profile desktop add link:F:\dsh\001X\dsh-restart
+```
+
+手工改 profile（等价）：在 `C:\Users\Administrator\.dsh\profiles\desktop\package.json` 的
+`dependencies` 加 `"dsh-restart-module": "link:F:/dsh/001X/dsh-restart"`，并把 `dsh-restart-module`
+加进 `dsh.profile.bundles`；再建 `node_modules\dsh-restart-module` → `F:\dsh\001X\dsh-restart` 的符号链接。
+改动插件源码后需要重启 DSH 才生效（可以用它自己的 `dsh_restart` 来重启）。
+
+## 配置
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `DSH_RESTART_MODULE_DIR` | `F:\dsh\001X\restart-module` | 重启器目录，需包含 `trigger-restart.mjs` |
+| `DSH_NODE_EXE` | 内置 runtime node | 调 trigger 用的 node，默认 `...\dsh-primary-runtime\dependencies\node\bin\node.exe` |
+
+## 日志
+
+| 文件 | 内容 |
+| --- | --- |
+| `restart-module\logs\plugin.log` | 插件侧：何时挂到哪个 agent、排程调用与错误 |
+| `restart-module\logs\helper-<时间>.log` | helper 侧：kill / 等端口 / 拉起 / 重试全过程 |
+| `restart-module\logs\helper-console.log` | `run-helper.cmd` 的 stdout/stderr |
+| `restart-module\logs\result.json` | 最近一次结果 `{ok, dryRun, startedAt, finishedAt, port, procs, logFile}` |
+| `restart-module\request.json` | 最近一次排程请求 `{delaySec, scheduledAt, note, ...}` |
+
+## 挂载方式（踩过的坑）
+
+- 用 **per-agent** 注册：`agent.ctx.effect(() => agent.ctx.tools.register(tool))`，不要全局注册。
+- 不要只看 `ctx.agents.roots()`：被 resume 的会话可能既不在 `roots()` 里，也等不到
+  `agent/created`，所以每 5 s 用「`ctx.sessions.list()` × `ctx.agents.get(id)`」补挂一次。
+- 验证工具是否真的进了模型，别用 `agent.ctx.tools.schemas(agent.ctx)`（它只回 global 层，
+  `term_*`、`qq_push` 都不在里面）。权威依据是会话日志里的 `request/header` 事件：
+  解帧后用 `F:\dsh\001X\restart-module\_tools-hist.cjs` 打印 tools 名单。
+
+## 已知限制
+
+- **唤醒注入必须带 `id` + `role`（0.1.1 起，重要）**：`agent.followup()` 的官方样例形状
+  `{ content, source }` 落盘后会缺 `id`，DSH 重放会话时判 `session event at seq N lacks an identified message`，
+  该会话直接打不开。现行写法：
+  `followup({ id: crypto.randomUUID(), role: 'user', content: [{type:'text',text}], source: {kind:'user'} })`。
+  0.1.0 曾在 `session-a3e9f80e` 上污染过 `seq 3508 / 3734`（由 crossterm 主维护会话修回），**别退回旧形状**。
+  0.1.1 已于 2026-10-18T04:20Z 由主维护会话用自身会话端到端验证：注入事件 `seq 3297` 带
+  `id=4bfbf697-…`、`role="user"`、`source={"kind":"user"}`，全机 `selfcheck.mjs` 30 会话 0 命中、exit 0。
+- `taskkill /F /T /IM "DeepSeek Harness.exe"` 会杀掉该镜像的**所有**实例（含测试 profile）。
+- 走 WMI 拉起，helper 可能延迟几秒到 ~20 s 才真正开始计时；`delay_sec` 是从 `createdAt` 起算，会兜底至少 3 s。
+- 15 分钟内已有 helper 在跑时 `--delay` 会被拒绝（退出码 3），用 `status` 看 `helper.pid`。
+- 非优雅退出：重启瞬间正在执行的那次工具调用会作废（回复本身若已落盘不受影响）。
+- 没有实现 dshmarket 那种「重启失败时的 recovery 页」；失败时看 `logs\result.json` 和 `helper-*.log`，或跑
+  `F:\dsh\001X\restart-module\revert-plugin-and-relaunch.cmd`。
+
+## 回滚
+
+```bat
+copy /y F:\dsh\001X\backups\profile-desktop\package.json.20261017-233708.bak C:\Users\Administrator\.dsh\profiles\desktop\package.json
+rmdir C:\Users\Administrator\.dsh\profiles\desktop\node_modules\dsh-restart
+taskkill /F /IM "DeepSeek Harness.exe" & timeout /t 4 >nul & start "" "F:\dsh\DeepSeek Harness.exe"
+```
+
+或直接跑 `F:\dsh\001X\restart-module\revert-plugin-and-relaunch.cmd`。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-restart-module —— 会话内自重启（排程杀掉并重拉 DSH 桌面进程）
+#
+# npm 安装：dsh plugin --profile desktop add dsh-restart-module
+# 本地源码装：dsh plugin --profile desktop add link:F:\dsh\001X\dsh-restart
+# 卸载：dsh plugin --profile desktop remove dsh-restart-module
+# 改动本插件源码后，需要重启 DSH 才生效（可用它自己的 dsh_restart 工具来重启）。
+- insert:
+    - id: dsh-restart-module
+      name: dsh-restart-module

package/lib/index.js

@@ -0,0 +1,337 @@
+/**
+ * dsh-restart —— 在会话内把 DSH 自身重启一次（替代外部 restart-dsh-*.bat）。
+ *
+ * 重启链路（restart-module，已多次端到端实测）：
+ *   写 request.json → WMI Win32_Process.Create 起 cmd.exe（脱离 DSH 进程树与 Job）
+ *   → cmd 跑 run-helper.cmd → node dsh-restart-helper.mjs
+ *   → 等到 scheduledAt → taskkill /F /T /IM "DeepSeek Harness.exe"
+ *   → 等进程与 19387 端口双消失 → 重新拉起 F:\dsh\DeepSeek Harness.exe
+ *   → 轮询端口最多 120s，失败重拉一次。
+ * 实测：杀进程到端口可访问 ≈ 2.1s，会话靠 end-seed 自动恢复。
+ *
+ * 工具挂载（照 dsh-crossterm 的实战写法）：
+ *   - 每个 agent 的 scope 里注册（agent.ctx.tools.register），不用全局注册；
+ *   - 不能只认 ctx.agents.roots()：已存在的/被 resume 的会话不一定在 roots() 里，
+ *     也等不到 agent/created，所以每 5 秒用「会话列表 × 活着的 agent」补挂一次。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { execFile } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const MODULE_DIR = process.env.DSH_RESTART_MODULE_DIR || 'F:\\dsh\\001X\\restart-module'
+const TRIGGER = path.join(MODULE_DIR, 'trigger-restart.mjs')
+const LOG_DIR = path.join(MODULE_DIR, 'logs')
+const PID_FILE = path.join(LOG_DIR, 'helper.pid')
+const RESULT_FILE = path.join(LOG_DIR, 'result.json')
+const REQUEST_FILE = path.join(MODULE_DIR, 'request.json')
+const MARK_FILE = path.join(LOG_DIR, 'plugin.log')
+const DEFAULT_DELAY = 60
+
+function mark(line) {
+  try {
+    fs.mkdirSync(LOG_DIR, { recursive: true })
+    fs.appendFileSync(MARK_FILE, `[${new Date().toISOString()}] ${line}\n`)
+  } catch { /* 日志失败不影响功能 */ }
+}
+
+function textOf(value) {
+  return [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }]
+}
+
+function nodeExe() {
+  const explicit = process.env.DSH_NODE_EXE
+  if (explicit && fs.existsSync(explicit)) return explicit
+  const bundled = 'C:\\Users\\Administrator\\.dsh\\dsh-runtimes\\dsh-primary-runtime\\dependencies\\node\\bin\\node.exe'
+  if (fs.existsSync(bundled)) return bundled
+  return 'node'
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return null
+  }
+}
+
+function tail(file, lines = 6) {
+  try {
+    return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/).filter(Boolean).slice(-lines)
+  } catch {
+    return []
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function runTrigger(args) {
+  return new Promise((resolve) => {
+    const env = { ...process.env }
+    delete env.ELECTRON_RUN_AS_NODE
+    delete env.ELECTRON_NO_ATTACH_CONSOLE
+    execFile(nodeExe(), [TRIGGER, ...args], {
+      cwd: MODULE_DIR,
+      env,
+      timeout: 120000,
+      windowsHide: true,
+      encoding: 'utf8',
+    }, (err, stdout, stderr) => {
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: stdout || '', stderr: stderr || '' })
+    })
+  })
+}
+
+function scheduleArgs(args, selfSessionId) {
+  const asked = Number(args?.delay_sec)
+  const delay = Number.isFinite(asked) ? Math.min(3600, Math.max(5, Math.round(asked))) : DEFAULT_DELAY
+  const cli = ['--delay', String(delay)]
+  const note = typeof args?.note === 'string' ? args.note.trim() : ''
+  if (note) cli.push('--note', note)
+  if (args?.dry_run === true) cli.push('--dry-run')
+  if (args?.force === true) cli.push('--force')
+  if (selfSessionId) cli.push('--self-session', String(selfSessionId))
+  return { cli, delay }
+}
+
+async function execute(args, sessionId) {
+  const action = typeof args?.action === 'string' ? args.action : 'schedule'
+
+  if (action === 'status') {
+    const result = readJson(RESULT_FILE)
+    const request = readJson(REQUEST_FILE)
+    const pid = Number((readJson(PID_FILE) || {}).pid ?? NaN)
+    const alive = pidAlive(pid)
+    const schedAt = request && request.scheduledAt ? Date.parse(request.scheduledAt) : NaN
+    const finishedAt = result ? Date.parse(result.finishedAt || result.at || '') : NaN
+    const alreadyRan = Number.isFinite(schedAt) && Number.isFinite(finishedAt) && finishedAt >= schedAt
+    const pending = alive && !alreadyRan
+    const pendingText = pending
+      ? `待执行：${request.scheduledAt}（delay ${request.delaySec}s，helper pid ${pid}）`
+      : (alreadyRan ? `无待执行请求（${request.scheduledAt} 那次已执行完毕）` : '无待执行请求')
+    return {
+      ok: true,
+      action,
+      detail: [
+        alive ? `helper 在跑（pid ${pid}）` : '当前没有活着的 helper',
+        pendingText,
+        result ? `上次结果：ok=${result.ok} ${result.startedAt || result.at || ''} → ${result.finishedAt || ''} port=${result.port || '?'}${result.reason ? ` reason=${result.reason}` : ''}` : '还没有重启记录',
+      ].join('；'),
+      helper: { pid: pending ? pid : null, pendingRequest: pending ? request : null },
+      lastResult: result || null,
+      lastPluginLog: tail(MARK_FILE, 1)[0] || null,
+    }
+  }
+
+  if (action === 'cancel') {
+    let pid = Number((readJson(PID_FILE) || {}).pid ?? NaN)
+    if (!Number.isFinite(pid)) {
+      // helper 写的是纯文本 pid（不是 JSON），这里得按文本兜底
+      try { pid = Number(String(fs.readFileSync(PID_FILE, 'utf8')).trim()) } catch { /* ignore */ }
+    }
+    const alive = pidAlive(pid)
+    let killed = false
+    if (alive) {
+      try {
+        execFile('taskkill', ['/F', '/PID', String(pid)], { windowsHide: true }, () => {})
+        killed = true
+      } catch { /* ignore */ }
+    }
+    try { fs.rmSync(REQUEST_FILE, { force: true }) } catch { /* ignore */ }
+    if (alive) { try { fs.rmSync(PID_FILE, { force: true }) } catch { /* ignore */ } }
+    mark(`cancel: pid=${pid} alive=${alive} killed=${killed}`)
+    return {
+      ok: true,
+      action,
+      detail: killed ? `已取消：结束等待中的 helper（pid ${pid}）并删除请求文件` : '没有等待中的重启，已清理请求文件',
+      helperPid: alive ? pid : null,
+    }
+  }
+
+  if (action !== 'schedule') {
+    return { ok: false, action, detail: `未知 action "${action}"，只支持 schedule / status / cancel` }
+  }
+
+  const { cli, delay } = scheduleArgs(args, sessionId)
+  if (args?.wake === false) cli.push('--no-wake')
+  if (typeof args?.wake_note === 'string' && args.wake_note.trim()) cli.push('--wake-text', args.wake_note.trim())
+  const r = await runTrigger(cli)
+  mark(`schedule: code=${r.code} args=${JSON.stringify(cli)} stdout=${r.stdout.trim().slice(0, 400)}`)
+  if (r.code === 7) {
+    return {
+      ok: false,
+      action,
+      reason: 'others-busy',
+      detail: `${(r.stderr || r.stdout).trim().slice(0, 600)} 要么等它们结束（到点前会等 3 秒静默），要么由用户明确同意后加 force:true 重试。${sessionId ? '' : '（本会话 id 未知，保守拒绝）'}`,
+      stdout: r.stdout.trim(),
+      stderr: r.stderr.trim(),
+    }
+  }
+  if (r.code !== 0) {
+    return {
+      ok: false,
+      action,
+      detail: `排程失败（exit ${r.code}）：${(r.stderr || r.stdout).trim().slice(0, 600)}`,
+      stdout: r.stdout.trim(),
+      stderr: r.stderr.trim(),
+    }
+  }
+  const pidMatch = /spawned cmd pid=(\d+)/i.exec(r.stdout)
+  const atMatch = /scheduled at ([^\r\n]+)/i.exec(r.stdout)
+  return {
+    ok: true,
+    action,
+    delaySec: delay,
+    scheduledAt: atMatch ? atMatch[1].trim() : new Date(Date.now() + delay * 1000).toISOString(),
+    helperPid: pidMatch ? Number(pidMatch[1]) : null,
+    dryRun: args?.dry_run === true,
+    detail: args?.dry_run === true
+      ? `dry-run 已排程：${delay}s 后只做检查、不杀进程（详情见 ${RESULT_FILE}）`
+      : `已排程 ${delay}s 后重启 DSH。本会话届时被中断，重启后会自动恢复；本次回复会在此之前落盘。`,
+  }
+}
+
+function buildTool(agentId) {
+  return defineTool({
+    name: 'dsh_restart',
+    description:
+      '在会话内把 DSH 自身重启一次（替代外部 restart-dsh-*.bat）。适合改完插件/配置、写完文件后让改动生效：'
+      + 'schedule（默认）排程一次重启——先落盘当前回复，再由脱离进程树的独立 helper 杀掉宿主并重新拉起桌面 App，'
+      + '会话重启后自动恢复；status 查上次重启结果与是否有待执行请求；cancel 撤销还没触发的重启。'
+      + '注意：排程后本会话会被中断，delay_sec 至少 5 秒（默认 60），要给回复留出发送时间。'
+      + '守卫：默认禁止在其他会话正在跑任务时重启——排程会被拒（exit 7），helper 到点前也会等「连续 3 秒无其他会话活动」，超时则中止不杀进程。'
+      + '只有用户明确同意（例如「现在就重启」）时才传 force=true 跳过守卫。'
+      + '默认重启成功后会自动唤醒本会话（helper 先留 wake.json，重启后插件注入一条“继续工作”的用户消息），需要静默重启时传 wake=false。',
+    parameters: {
+      action: { type: 'string', enum: ['schedule', 'status', 'cancel'], description: 'schedule 排程重启（默认）；status 查状态；cancel 取消未触发的重启' },
+      delay_sec: { type: 'number', description: '排程模式下多少秒后重启，5–3600，默认 60。要给当前回复留出发送时间，别小于 15' },
+      note: { type: 'string', description: '写进 request.json 与日志的备注（例如“装完 dsh-restart 插件”）' },
+      dry_run: { type: 'boolean', description: '只验证链路，不杀进程（默认 false）' },
+      force: { type: 'boolean', description: '用户明确同意时置 true：即使其他会话在跑任务也立刻重启（默认 false）' },
+      wake: { type: 'boolean', description: '重启后是否自动唤醒本会话（默认 true）：helper 杀进程前留 wake.json，重启后插件注入一条“继续工作”的用户消息；置 false 关闭' },
+      wake_note: { type: 'string', description: '唤醒消息里附加的说明（可选，例如“继续写剩下的两节”）' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => textOf(value && value.detail ? value.detail : value),
+    },
+    async execute(args) {
+      try {
+        return await execute(args || {}, agentId)
+      } catch (e) {
+        mark('execute error: ' + ((e && e.stack) || String(e)))
+        return { ok: false, detail: 'dsh_restart 执行异常：' + ((e && e.message) || String(e)) }
+      }
+    },
+  })
+}
+
+// 重启后自动唤醒：helper 在杀进程前写 logs\wake.json，这里在 agent 挂载后把它注入成一条用户消息。
+const WAKE_FILE = path.join(LOG_DIR, 'wake.json')
+
+function takeWake(agentId) {
+  let raw = ''
+  try { raw = fs.readFileSync(WAKE_FILE, 'utf8').replace(/^\uFEFF/, '') } catch { return null }
+  let wake = null
+  try { wake = JSON.parse(raw) } catch { wake = null }
+  if (!wake) { try { fs.rmSync(WAKE_FILE, { force: true }) } catch { /* ignore */ } return null }
+  if (wake.sessionId && agentId && wake.sessionId !== agentId) return null
+  const age = Date.now() - Date.parse(wake.createdAt || '')
+  try { fs.rmSync(WAKE_FILE, { force: true }) } catch { /* ignore */ }
+  if (!Number.isFinite(age) || age > 10 * 60 * 1000) {
+    mark(`wake: stale (age=${Math.round(age / 1000)}s), dropped`)
+    return null
+  }
+  return wake
+}
+
+function wakeAgent(agent, wake) {
+  const target = typeof agent?.followup === 'function' ? agent : agent?.agent
+  if (!target || typeof target.followup !== 'function') {
+    mark(`wake: agent ${agent?.id} has no followup(); skipped`)
+    return
+  }
+  const timer = setTimeout(() => {
+    try {
+      // 必须带 id / role：DSH 重放会话时会校验「user/message 的 data 本身就是消息」，
+      // 缺 id 直接判 corrupt（Error: session event at seq N lacks an identified message）。
+      // 官方样例 followup({content, source}) 就是残缺形状，踩过一次（2026-10-18，a3e9f80e 会话被污染）。
+      target.followup({
+        id: crypto.randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: String(wake.text || '') }],
+        source: { kind: 'user' },
+      })
+      mark(`wake: injected into ${agent.id}`)
+    } catch (e) {
+      mark(`wake: inject failed on ${agent.id}: ${(e && e.message) || String(e)}`)
+    }
+  }, 2500)
+  if (timer && typeof timer.unref === 'function') timer.unref()
+}
+
+export default {
+  name: 'dsh-restart',
+  apply(root) {
+    root.inject(['agents'], (ctx) => {
+      const mounted = new Map()
+
+      const mount = (agent) => {
+        if (!agent || mounted.has(agent)) return
+        try {
+          const dispose = agent.ctx.effect(() => {
+            const disposers = []
+            try {
+              const maybe = agent.ctx.tools.register(buildTool(agent.id))
+              if (typeof maybe === 'function') disposers.push(maybe)
+            } catch (e) {
+              mark(`register throw on agent ${agent.id}: ${(e && e.message) || String(e)}`)
+            }
+            return () => {
+              for (const fn of disposers) {
+                try { fn() } catch { /* ignore */ }
+              }
+            }
+          }, 'dsh-restart: dsh_restart tool')
+          mounted.set(agent, dispose)
+          mark(`mounted on agent ${agent.id}`)
+          const wake = takeWake(agent.id)
+          if (wake) wakeAgent(agent, wake)
+        } catch (e) {
+          mark(`mount failed on agent ${agent && agent.id}: ${(e && e.message) || String(e)}`)
+        }
+      }
+
+      const reconcile = () => {
+        try {
+          let list = []
+          try { list = ctx.sessions?.list?.() || [] } catch { list = [] }
+          for (const s of list) {
+            try { const agent = ctx.agents?.get?.(s.id); if (agent) mount(agent) } catch { /* ignore */ }
+          }
+        } catch { /* ignore */ }
+        try { for (const agent of ctx.agents.roots()) mount(agent) } catch { /* ignore */ }
+      }
+
+      reconcile()
+      ctx.effect(() => {
+        const timer = setInterval(reconcile, 5000)
+        if (timer && typeof timer.unref === 'function') timer.unref()
+        return () => clearInterval(timer)
+      }, 'dsh-restart: 会话工具补挂')
+
+      ctx.on('agent/created', ({ agent }) => mount(agent))
+      ctx.on('agent/disposed', ({ agent }) => { mounted.delete(agent) })
+      mark('ready')
+    })
+  },
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "dsh-restart-module",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "会话内自重启：任何会话都能排程「杀掉本机 DSH 桌面进程并自动拉回」，替代 restart-dsh-*.bat",
+  "type": "module",
+  "main": "./lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*"
+  }
 }