dsh-notify-windows 0.7.8 → 0.8.0-beta.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)。
 
+## [Unreleased]
+
+### 新增
+
+- **多语言 toast 文案（`locale` / `messages`）**：新增内置语言包 `zh`（默认，**保持现有文案不变**）、
+  `en`、`ru`，并由 `locale` 选择；任意一条文案都可用 `messages` 按 key 覆盖，覆盖优先于语言包。
+  占位符（`{turn}` / `{tool}` / `{reason}` / `{version}` / `{code}`）由事件数据代入：未知占位符
+  **原样保留**而非清空，非字符串覆盖值被忽略，未知 `locale` 回退默认语言包——写错不会产生空正文或
+  `[object Object]`。默认值不变，故本次改动对既有安装零影响（升级后文案与行为完全一致）。
+- 审批（`approval`）与提问（`ask-user`）路径的日志行补充 `title` 与 `body` 字段，与既有的
+  `notify` 行对齐，便于排查「实际发出去的文案是什么」。新增字段为**增量**，不破坏既有日志消费方。
+
+### 测试
+
+- `test/probe.test.mjs` 新增 5 个用例（共 20/20 通过）：
+  - `resolveMessages`：各语言包**键集合一致**、每条文案非空、`{turn}` / `{tool}` / `{reason}` /
+    `{version}` / `{code}` 占位符**逐项齐备**（漏一个即变红）、未知 `locale` 回退默认包、
+    `messages` 覆盖优先于语言包、非字符串覆盖被忽略、`messages` 非对象不崩；
+  - 端到端 `locale=en` / `locale=ru`：完成回合正文与轮次后缀（`Task completed (turn 1)` /
+    `Задача завершена (раунд 1)`）；
+  - 端到端 `messages` 覆盖：未覆盖的键仍用所选语言包；
+  - 端到端 approval / ask 的标题与正文，含 `approvalGeneric` 与 `askFallback` 两条兜底文案。
+
+### 修复
+
+- `resolveMessages` 的 locale 查找改用 `Object.hasOwn`：`locale` 若恰为 `Object.prototype` 成员名
+  （`constructor` / `toString` / `__proto__` / `hasOwnProperty` / `valueOf`），裸索引会取到函数、
+  展开成空包，正文渲染成字面量 `undefined` —— 与「未知 locale 回退默认包」的承诺不符。
+  现在与其它未知 locale 一样回退 `zh`。
+
 ## [0.7.8] - 2026-09-29
 
 ### 兼容性

package/README.en.md

@@ -72,6 +72,8 @@ in `$DSH_HOME/profiles/web/cordis.patch.yml` (hot-applied by the running host
 | --- | --- | --- |
 | `enabled` | `true` | master switch |
 | `reasons` | `[completed, error, max-tokens]` | turn-end reasons to notify (`aborted` / `interrupted` / `blocked` also available) |
+| `locale` | `zh` | built-in message pack for the toast text: `zh` / `en` / `ru` |
+| `messages` | `{}` | per-key wording overrides applied on top of `locale` (see Localization) |
 | `includeSubagents` | `false` | also notify subagent sessions |
 | `notifyOnStart` | `false` | toast when the plugin loads |
 | `notifyOnApproval` | `true` | toast on `approval/asked` (skipped under policy `never`) |
@@ -87,6 +89,42 @@ in `$DSH_HOME/profiles/web/cordis.patch.yml` (hot-applied by the running host
 | `preferExisting` | `true` | when true, launcher prefers focusing an open DSH window; when false, just open the URL in the default browser |
 | `webUrl` | `''` | override the auto-discovered base URL (e.g. `http://192.168.1.5:4000`); leave empty to auto-discover (defaults to `http://127.0.0.1:3080`) |
 
+## 🌐 Localization
+
+Toast wording comes from a built-in message pack selected by `locale`. The default is `zh`, so an
+existing install sees no change after upgrading; `en` and `ru` ship as complete packs. Any single
+string can be overridden per install through `messages`, which wins over the selected pack:
+
+```yaml
+- id: dsh-notify
+  name: dsh-notify-windows
+  config:
+    locale: ru
+    messages:
+      approvalTitle: ' · Требуется одобрение'
+      turnSuffix: ' — попытка {turn}'
+```
+
+| Key | Used for |
+| --- | --- |
+| `completed` / `error` / `max-tokens` / `aborted` / `interrupted` / `blocked` | the turn/end reason line (looked up by `reason.kind`) |
+| `turnEnded` | fallback when a reason has no entry in the pack |
+| `turnSuffix` | turn number appended to the reason line — `{turn}` |
+| `approvalTitle` | title suffix of an approval toast |
+| `approvalToolWithReason` / `approvalTool` / `approvalGeneric` | approval body — `{tool}`, `{reason}` |
+| `askTitle` | title suffix of a question toast |
+| `askFallback` | question body when no question text could be extracted |
+| `activated` | the `notifyOnStart` toast — `{version}` |
+| `warnSpawnFailed` / `warnToastFailed` / `warnExitCode` / `warnChannelUnavailable` | DSH log wording — `{code}`; the `dsh-notify:` tag itself is never translated, so logs stay greppable across locales |
+
+`{placeholder}` tokens are substituted from the event data. An unknown placeholder is left verbatim
+rather than blanked, and a non-string override is ignored — a typo can therefore never produce an
+empty or `[object Object]` toast. An unknown `locale` falls back to the default pack.
+
+The `approval` and `ask-user` log entries now carry `title` and `body` alongside the existing
+metadata (matching what the `notify` entry already did), so `%TEMP%\dsh-notify\notify.log` shows
+the text that was actually sent.
+
 ## 🔔 Triggers
 
 | Scenario | Session event | Sample toast |

package/README.md

@@ -74,6 +74,8 @@ dsh plugin --profile web remove dsh-notify-windows
 | --- | --- | --- |
 | `enabled` | `true` | 总开关 |
 | `reasons` | `[completed, error, max-tokens]` | 需要提醒的回合结束原因（可选 `aborted` / `interrupted` / `blocked`） |
+| `locale` | `zh` | toast 文案的内置语言包：`zh` / `en` / `ru` |
+| `messages` | `{}` | 按 key 覆盖文案，优先级高于 `locale`（见「多语言」） |
 | `includeSubagents` | `false` | 是否也提醒子代理会话 |
 | `notifyOnStart` | `false` | 插件加载时发一条「已激活」通知 |
 | `notifyOnApproval` | `true` | 审批请求提醒（策略 `never` 时自动跳过） |
@@ -89,6 +91,39 @@ dsh plugin --profile web remove dsh-notify-windows
 | `preferExisting` | `true` | true 走 launcher 优先聚焦已开 DSH 窗口；false 直接用默认浏览器打开 URL |
 | `webUrl` | `''` | 覆盖自动发现的基地址（如 `http://192.168.1.5:4000`），留空自动发现（默认 `http://127.0.0.1:3080`） |
 
+## 🌐 多语言
+
+toast 文案取自内置语言包，由 `locale` 选择。默认 `zh`，因此已有安装升级后文案完全不变；
+`en` 与 `ru` 为完整语言包。任何一条文案都可以用 `messages` 按 key 覆盖，覆盖优先于语言包：
+
+```yaml
+- id: dsh-notify
+  name: dsh-notify-windows
+  config:
+    locale: ru
+    messages:
+      approvalTitle: ' · Требуется одобрение'
+      turnSuffix: ' — попытка {turn}'
+```
+
+| key | 用途 |
+| --- | --- |
+| `completed` / `error` / `max-tokens` / `aborted` / `interrupted` / `blocked` | 回合结束原因行（按 `reason.kind` 查表） |
+| `turnEnded` | 原因在语言包中没有对应条目时的兜底文案 |
+| `turnSuffix` | 追加在原因行后的轮次后缀 —— `{turn}` |
+| `approvalTitle` | 审批通知的标题后缀 |
+| `approvalToolWithReason` / `approvalTool` / `approvalGeneric` | 审批正文 —— `{tool}` / `{reason}` |
+| `askTitle` | 提问通知的标题后缀 |
+| `askFallback` | 提取不到问题文本时的提问正文 |
+| `activated` | `notifyOnStart` 的「已激活」通知 —— `{version}` |
+| `warnSpawnFailed` / `warnToastFailed` / `warnExitCode` / `warnChannelUnavailable` | DSH 日志文案 —— `{code}`；`dsh-notify:` 前缀不翻译，保证跨语言可 grep |
+
+说明：`{占位符}` 由事件数据代入；未知占位符**原样保留**（不会被清空），非字符串的覆盖值会被忽略，
+因此写错不会产生空正文或 `[object Object]`；未知 `locale` 回退默认语言包。
+
+审批 / 提问路径的日志行新增 `title` 与 `body` 字段（与 `notify` 行一致），
+`%TEMP%\dsh-notify\notify.log` 因此能直接看到实际发出的文案。
+
 ## 🔔 触发场景
 
 | 场景 | 会话事件 | 通知示例 |

package/lib/index.js

@@ -15,6 +15,11 @@
 // Goal rounds (/goal auto-continuation) are quiet by default: only the final
 // round that completes or blocks the goal produces a toast.
 //
+// Wording is localizable: `locale` selects a built-in message pack (MESSAGES —
+// "zh" by default, "en" and "ru" also ship) and `messages` overrides individual
+// strings on top of it. The default pack keeps the original text, so an install
+// that sets neither key behaves exactly as before.
+//
 // Zero runtime dependencies: notifications go through the toast sender
 // script (./notify.ps1) executed by Windows PowerShell 5.1, whose .NET
 // Framework runtime supports the WinRT toast API.
@@ -54,15 +59,128 @@ const WSL_POWERSHELL = "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershel
 const resolvePowerShell = () => (existsSync(WSL_POWERSHELL) ? WSL_POWERSHELL : "powershell.exe");
 const POWERSHELL = resolvePowerShell();
 
-const REASON_TEXT = {
-  completed: "任务已完成",
-  error: "任务出错",
-  "max-tokens": "输出达到 token 上限",
-  aborted: "任务已取消",
-  interrupted: "任务中断",
-  blocked: "任务未开始",
+/**
+ * Built-in toast message packs.
+ *
+ * The keys serve two purposes at once. The turn/end reason kinds (`completed`,
+ * `error`, `max-tokens`, `aborted`, `interrupted`, `blocked`) are looked up
+ * directly by `reason.kind`, so every pack must carry one entry per reason;
+ * the remaining keys hold the surrounding toast and log wording.
+ *
+ * `zh` is the original wording and stays the default, so an existing install
+ * sees no change after upgrading. `en` and `ru` are complete packs. Any pack
+ * can be partially overridden per install through the `messages` config.
+ * `{placeholder}` tokens are substituted by `format()`.
+ */
+export const MESSAGES = {
+  zh: {
+    // turn/end reason kinds
+    completed: "任务已完成",
+    error: "任务出错",
+    "max-tokens": "输出达到 token 上限",
+    aborted: "任务已取消",
+    interrupted: "任务中断",
+    blocked: "任务未开始",
+    // turn/end wording
+    turnEnded: "任务已结束",
+    turnSuffix: "（第 {turn} 轮）",
+    // approval/asked wording
+    approvalTitle: " · 需要审批",
+    approvalToolWithReason: "工具 {tool}：{reason}",
+    approvalTool: "工具 {tool}",
+    approvalGeneric: "有一项操作等待你的批准",
+    // ask_user_question wording
+    askTitle: " · 需要回答",
+    askFallback: "Agent 正在等待你的确认",
+    // activation toast
+    activated: "任务完成提醒已激活（v{version}）",
+    // logger messages (the "dsh-notify:" tag stays untranslated, so logs
+    // remain greppable across locales)
+    warnSpawnFailed: "启动通知进程失败",
+    warnToastFailed: "通知进程未成功显示 toast",
+    warnExitCode: "（退出码 {code}）",
+    warnChannelUnavailable: "通知通道不可用（powershell.exe 或 notify.ps1 缺失），桌面通知将不会发送",
+  },
+  en: {
+    completed: "Task completed",
+    error: "Task errored",
+    "max-tokens": "Output reached the token cap",
+    aborted: "Task cancelled",
+    interrupted: "Task interrupted",
+    blocked: "Task not started",
+    turnEnded: "Task ended",
+    turnSuffix: " (turn {turn})",
+    approvalTitle: " · Needs approval",
+    approvalToolWithReason: "tool {tool}: {reason}",
+    approvalTool: "tool {tool}",
+    approvalGeneric: "An operation is waiting for your approval",
+    askTitle: " · Needs your answer",
+    askFallback: "The agent is waiting for your confirmation",
+    activated: "Task-completion reminders activated (v{version})",
+    warnSpawnFailed: "failed to start the notification process",
+    warnToastFailed: "the notification process did not show a toast",
+    warnExitCode: " (exit code {code})",
+    warnChannelUnavailable: "notification channel unavailable (powershell.exe or notify.ps1 missing); desktop toasts will not be sent",
+  },
+  ru: {
+    completed: "Задача завершена",
+    error: "Ошибка в задаче",
+    "max-tokens": "Достигнут лимит токенов",
+    aborted: "Задача отменена",
+    interrupted: "Задача прервана",
+    blocked: "Задача не начата",
+    turnEnded: "Задача завершена",
+    turnSuffix: " (раунд {turn})",
+    approvalTitle: " · Требуется одобрение",
+    approvalToolWithReason: "Инструмент {tool}: {reason}",
+    approvalTool: "Инструмент {tool}",
+    approvalGeneric: "Одна операция ожидает вашего одобрения",
+    askTitle: " · Требуется ответ",
+    askFallback: "Агент ждёт вашего подтверждения",
+    activated: "Напоминания о задачах активированы (v{version})",
+    warnSpawnFailed: "не удалось запустить процесс уведомления",
+    warnToastFailed: "не удалось показать тост",
+    warnExitCode: " (код выхода {code})",
+    warnChannelUnavailable: "канал уведомлений недоступен (нет powershell.exe или notify.ps1); тосты отправляться не будут",
+  },
 };
 
+/**
+ * Substitute `{name}` tokens with `params.name`. An unknown token is left
+ * verbatim rather than blanked, so a typo in an override stays visible in the
+ * toast instead of silently dropping text.
+ */
+function format(template, params) {
+  if (typeof template !== "string") return "";
+  return template.replace(/\{(\w+)\}/g, (match, key) =>
+    Object.prototype.hasOwnProperty.call(params, key) ? String(params[key]) : match,
+  );
+}
+
+/**
+ * Resolve the effective message pack: the selected locale (an unknown locale
+ * falls back to the default pack rather than leaving the toast empty), then
+ * the install's own `messages` overrides on top.
+ *
+ * A non-string override is ignored: it could only ever produce "[object
+ * Object]" in a toast, and silently dropping it is better than leaking it.
+ */
+export function resolveMessages(config = {}) {
+  // An unknown locale falls back to the default pack. `Object.hasOwn` (not a
+  // bare index) is required: a locale naming an Object.prototype member
+  // ("constructor", "toString", "__proto__", …) would otherwise resolve to a
+  // function, spread into an empty pack, and render a literal "undefined" body.
+  const base = Object.hasOwn(MESSAGES, config.locale) ? MESSAGES[config.locale] : MESSAGES.zh;
+  const resolved = { ...base };
+  const overrides = config.messages;
+  if (overrides && typeof overrides === "object") {
+    for (const [key, value] of Object.entries(overrides)) {
+      if (typeof value === "string") resolved[key] = value;
+    }
+  }
+  return resolved;
+}
+
 export const name = "dsh-notify-windows";
 
 function truncate(text, max) {
@@ -195,6 +313,8 @@ export const apply = (ctx, config = {}) => {
   const cfg = {
     enabled: true,
     reasons: ["completed", "error", "max-tokens"],
+    locale: "zh", // built-in pack: "zh" (default) | "en" | "ru"
+    messages: {}, // per-key overrides applied on top of the locale pack
     includeSubagents: false,
     notifyOnStart: false,
     notifyOnApproval: true,
@@ -213,6 +333,7 @@ export const apply = (ctx, config = {}) => {
     ...config,
   };
   const reasons = new Set(cfg.reasons);
+  const t = resolveMessages(cfg);
   const logPath = join(tmpdir(), "dsh-notify", "notify.log");
 
   const log = (entry) => {
@@ -284,7 +405,7 @@ export const apply = (ctx, config = {}) => {
     child.stderr?.on("data", (chunk) => { stderr += chunk; });
     child.on("error", (error) => {
       log({ event: "error", message: String(error?.message ?? error) });
-      ctx.logger?.warn?.("dsh-notify: 启动通知进程失败", error);
+      ctx.logger?.warn?.("dsh-notify: " + t.warnSpawnFailed, error);
     });
     child.on("exit", (code) => {
       const shown = /toast shown/.test(stdout);
@@ -296,7 +417,7 @@ export const apply = (ctx, config = {}) => {
           stdout: stdout.slice(0, 500),
           stderr: stderr.slice(0, 500),
         });
-        ctx.logger?.warn?.("dsh-notify: 通知进程未成功显示 toast" + (code !== null ? "（退出码 " + code + "）" : ""));
+        ctx.logger?.warn?.("dsh-notify: " + t.warnToastFailed + (code !== null ? format(t.warnExitCode, { code }) : ""));
       }
     });
   };
@@ -354,8 +475,8 @@ export const apply = (ctx, config = {}) => {
       }
 
       const title = titleFor(session) || cfg.appName;
-      let body = REASON_TEXT[reason.kind] ?? "任务已结束";
-      if (Number.isInteger(event.data.turn)) body += "（第 " + event.data.turn + " 轮）";
+      let body = t[reason.kind] ?? t.turnEnded;
+      if (Number.isInteger(event.data.turn)) body += format(t.turnSuffix, { turn: event.data.turn });
       if (cfg.excerpt && window.lastAssistantText) {
         body += "\n" + truncate(window.lastAssistantText, cfg.excerptMaxChars);
       }
@@ -380,10 +501,11 @@ export const apply = (ctx, config = {}) => {
       const data = event.data ?? {};
       const body = typeof data.toolName === "string"
         ? (typeof data.reason === "string" && data.reason.length > 0
-          ? "工具 " + data.toolName + "：" + truncate(data.reason, 100)
-          : "工具 " + data.toolName)
-        : "有一项操作等待你的批准";
-      sendToast(cfg.appName + " · 需要审批", body, { sessionId: session?.id });
+          ? format(t.approvalToolWithReason, { tool: data.toolName, reason: truncate(data.reason, 100) })
+          : format(t.approvalTool, { tool: data.toolName }))
+        : t.approvalGeneric;
+      const title = cfg.appName + t.approvalTitle;
+      sendToast(title, body, { sessionId: session?.id });
       const url = cfg.openOnClick && session?.id ? conversationUrl(session?.id) : undefined;
       log({
         event: "approval",
@@ -391,6 +513,8 @@ export const apply = (ctx, config = {}) => {
         id: data.id,
         toolName: data.toolName,
         reason: data.reason,
+        title,
+        body,
         ...(url ? { url } : {}),
       });
       return;
@@ -405,12 +529,16 @@ export const apply = (ctx, config = {}) => {
         question = extractQuestionFromCode(data.arguments);
       }
       if (question !== undefined || data.name === "ask_user_question") {
-        sendToast(cfg.appName + " · 需要回答", question ? truncate(question, 100) : "Agent 正在等待你的确认", { sessionId: session?.id });
+        const body = question ? truncate(question, 100) : t.askFallback;
+        const title = cfg.appName + t.askTitle;
+        sendToast(title, body, { sessionId: session?.id });
         const url = cfg.openOnClick && session?.id ? conversationUrl(session?.id) : undefined;
         log({
           event: "ask-user",
           sessionId: session?.id,
           question: question ?? null,
+          title,
+          body,
           ...(url ? { url } : {}),
         });
       }
@@ -433,10 +561,10 @@ export const apply = (ctx, config = {}) => {
     sessionId: null,
   });
   if (cfg.enabled && !channelOk) {
-    ctx.logger?.warn?.("dsh-notify: 通知通道不可用（powershell.exe 或 notify.ps1 缺失），桌面通知将不会发送");
+    ctx.logger?.warn?.("dsh-notify: " + t.warnChannelUnavailable);
   }
   if (cfg.enabled && cfg.notifyOnStart) {
     // Activation toast has no session: leave non-clickable (legacy behavior).
-    sendToast(cfg.appName, "任务完成提醒已激活（v" + VERSION + "）");
+    sendToast(cfg.appName, format(t.activated, { version: VERSION }));
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-notify-windows",
-  "version": "0.7.8",
-  "description": "DeepSeek Harness (DSH) 插件：任务完成 / 等待审批 / 等待回答时发送 Windows 系统桌面通知",
+  "version": "0.8.0-beta.0",
+  "description": "DeepSeek Harness (DSH) \u63d2\u4ef6\uff1a\u4efb\u52a1\u5b8c\u6210 / \u7b49\u5f85\u5ba1\u6279 / \u7b49\u5f85\u56de\u7b54\u65f6\u53d1\u9001 Windows \u7cfb\u7edf\u684c\u9762\u901a\u77e5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SeverusZh/dsh-notify-windows.git"