pi-web-ui 0.68.2 → 0.69.0

package/dist/server/i18n.js

@@ -0,0 +1,157 @@
+/**
+ * i18n — server-side language negotiation (issue #91).
+ *
+ * Two tracks:
+ *  - Browser UI strings live in `locales/<code>.json` packs (`strings`).
+ *  - Server-authored strings the model relays to the user (tool return
+ *    values, prompt segments, guidance blocks) are keyed through THIS module.
+ *    zh/en stay inline at the call site (zero-cost, always available); every
+ *    OTHER language resolves through a per-language table that translators
+ *    ship inside the SAME pack file (`serverStrings` section — one download
+ *    covers UI + server). Missing key → English fallback, so partial
+ *    translations are safe and adding a language is just filling a table.
+ *
+ * Conventions for contributors:
+ *  - `pick(lang, zh, en, key?)` — key format `<module>.<slug>`, e.g.
+ *    `subagents.spawn.started`. Slugs derive from the English source text.
+ *    Keys must be globally unique (module prefix guarantees it).
+ *  - `getServerBlock(lang, key, zhLines, enLines)` — multi-line blocks
+ *    (guidance arrays, prompt sections); tables store one `\n`-joined string.
+ *  - `bilingual(en, zh)` — tool DEFINITIONS stay static en+zh (baked into the
+ *    session at creation; the model works fine with English definitions
+ *    under any UI language). No keys needed.
+ *  - Template DATA (subagent_templates content, user overrides) stays zh/en
+ *    fields — it is user-editable config, not code copy.
+ *
+ * Pure functions + a tiny in-memory registry (no node imports) — unit-tested.
+ * Tables are loaded from `<dataDir>/locales/*.json` at startup (see
+ * loadServerStringsFromDir + index.ts hooks); tests register synthetic tables.
+ */
+/**
+ * Normalize a UI locale code to a server language code.
+ * "zh-CN"/"zh_TW" → "zh"; "pt-BR" → "pt"; "en-US" → "en"; "" → "en".
+ */
+export function resolveServerLang(locale) {
+    if (typeof locale !== "string")
+        return "en";
+    const code = locale.trim().toLowerCase();
+    if (!code)
+        return "en";
+    const m = code.match(/^([a-z]{2,3})(?:[-_].*)?$/);
+    return m?.[1] ?? "en";
+}
+/** True when the server language is Chinese. */
+export function isZh(lang) {
+    return lang === "zh";
+}
+/* ------------------------------------------------------------------ */
+/* translator tables                                                   */
+/* ------------------------------------------------------------------ */
+const serverTables = new Map();
+/** Normalize a table code the same way locales resolve ("PT-br" → "pt"). */
+function tableCode(code) {
+    return resolveServerLang(code);
+}
+/** Register (or replace) a translator table, e.g. from a pack's
+ *  `serverStrings` section. Empty tables are ignored. */
+export function registerServerStrings(code, table) {
+    const entries = Object.entries(table ?? {}).filter(([k, v]) => typeof k === "string" && k.length > 0 && typeof v === "string");
+    if (entries.length === 0)
+        return;
+    serverTables.set(tableCode(code), Object.fromEntries(entries));
+}
+/** Drop a translator table (pack removed). */
+export function unregisterServerStrings(code) {
+    serverTables.delete(tableCode(code));
+}
+/** Visible for tests / diagnostics. */
+export function registeredServerLangs() {
+    return [...serverTables.keys()].sort();
+}
+/** Look up one key for a non-Chinese language (undefined = fall back). */
+export function getServerString(lang, key) {
+    if (isZh(lang) || !key)
+        return undefined;
+    const v = serverTables.get(tableCode(lang))?.[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Pick the zh/en variant of a user-visible or model-facing string, with
+ * translator-table override for other languages:
+ *   pick(lang, "当前没有子代理。", "No subagents running.", "subagents.list.empty")
+ * zh → inline Chinese; other → table hit or inline English.
+ *
+ * Interpolated strings pass `vars` (5th arg). Table values use `{expr}`
+ * slots where `expr` is the EXACT text inside the call site's `${...}`
+ * (translators copy it verbatim; complex sub-expressions should be hoisted
+ * to a named const at the call site first):
+ *   pick(lang, `剩${n}个`, `${n} left`, "k.items.left", { n })
+ *   → table: `"残り{n}件"`. Slots missing from `vars` stay literal.
+ */
+export function pick(lang, zh, en, key, vars) {
+    if (isZh(lang))
+        return zh;
+    if (key) {
+        const hit = getServerString(lang, key);
+        if (hit !== undefined)
+            return formatTable(hit, vars);
+    }
+    return en;
+}
+/** Fill `{name}` slots from vars (unknown slots stay literal so a stale
+ *  table never eats text silently; null/undefined render as empty). */
+export function formatTable(template, vars) {
+    if (!vars)
+        return template;
+    let out = template;
+    for (const [k, v] of Object.entries(vars)) {
+        out = out.split(`{${k}}`).join(v === undefined || v === null ? "" : String(v));
+    }
+    return out;
+}
+/**
+ * Multi-line variant for guidance blocks / prompt sections. Tables store one
+ * `\n`-joined string per key; zh/en stay inline arrays at the call site:
+ *   getServerBlock(lang, "markers.todo.guidance", TODO_GUIDANCE_ZH, TODO_GUIDANCE_EN)
+ */
+export function getServerBlock(lang, key, zhLines, enLines) {
+    if (isZh(lang))
+        return zhLines;
+    const hit = getServerString(lang, key);
+    if (hit !== undefined)
+        return hit.split("\n");
+    return enLines;
+}
+/**
+ * Join English-first bilingual copy for tool *definitions* (baked into the
+ * session at creation, so they cannot be lang-switched without rebuilding
+ * the runtime — inline both instead). English leads per the English-default
+ * policy; the Chinese half keeps zh-UI behavior identical to before.
+ */
+export function bilingual(en, zh) {
+    if (!en)
+        return zh;
+    if (!zh)
+        return en;
+    if (en === zh)
+        return en;
+    return `${en}\n${zh}`;
+}
+/** Pull a translator table out of a parsed pack file (null = none usable). */
+export function extractServerStrings(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    if (typeof d.code !== "string" || !d.code)
+        return null;
+    if (!d.serverStrings || typeof d.serverStrings !== "object")
+        return null;
+    const table = {};
+    for (const [k, v] of Object.entries(d.serverStrings)) {
+        if (typeof k === "string" && k.length > 0 && typeof v === "string" && v.length > 0)
+            table[k] = v;
+    }
+    if (Object.keys(table).length === 0)
+        return null;
+    return { code: d.code, table };
+}

package/dist/server/index.js

@@ -36,7 +36,9 @@ import { startControlServer } from "./control-socket.js";
 import { scheduleUploadCleanup } from "./uploads.js";
 import { ensureWindowsBash, windowsBashDir } from "./ensure-bash.js";
 import { listThemes, resolveThemeFile } from "./themes.js";
-import { installPack, isKnownPack, listPacks, readPackFile, removePack } from "./locales.js";
+import { isManaged, managedRefusal } from "./managed.js";
+import { parseTabs, tabsRefusal } from "./tabs.js";
+import { installPack, isKnownPack, listPacks, loadServerStrings, readPackFile, removePack, unloadServerStrings, } from "./locales.js";
 import { PluginManager, resolvePluginClientFile, } from "./plugins.js";
 import { McpBridge } from "./mcp-bridge.js";
 /** 从 CLI 参数中取 flag 值：支持 --flag value 与 --flag=value 两种写法。
@@ -79,17 +81,29 @@ const ALLOW_ORIGINS = (process.env.PI_WEB_ALLOW_ORIGINS ?? "")
 const AUTH_TOKEN = process.env.PI_WEB_TOKEN?.trim() ?? "";
 /** 语言包下载根（语言包仓库的 raw 文件地址；版本 tag 优先、main 兜底，见 locales.ts）。 */
 const LOCALE_BASE_URL = process.env.PI_WEB_LOCALE_BASE_URL?.trim() || "https://raw.githubusercontent.com/xing-shuyin/pi-web-ui";
-/** 本包版本 —— 下载语言包时优先取同版本 tag，保证 key 对齐。 */
-const APP_VERSION = (() => {
-    try {
-        // 注意：此处不能用下面的 pkgRoot 常量（TDZ）——直接调函数声明（已提升）。
-        const pkg = JSON.parse(readFileSync(join(resolvePkgRoot(), "package.json"), "utf8"));
-        return pkg.version ?? "";
-    }
-    catch {
-        return "";
+/**
+ * 本包版本 —— 下载语言包时优先取同版本 tag，保证 key 对齐。
+ *
+ * Read on first use, not here. `resolvePkgRoot()` is hoisted, but it reads
+ * `here`, which is a `const` declared further down: calling it at module-init
+ * time throws on the temporal dead zone, the catch swallows it, and the
+ * version was silently "" — so the language packs never used the version tag
+ * and always fell back to `main`. Reading it lazily costs one branch and
+ * gives the real number.
+ */
+let appVersionCache = null;
+function appVersion() {
+    if (appVersionCache === null) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(resolvePkgRoot(), "package.json"), "utf8"));
+            appVersionCache = pkg.version ?? "";
+        }
+        catch {
+            appVersionCache = "";
+        }
     }
-})();
+    return appVersionCache;
+}
 // Root of the SDK default per-project session dirs — chat transcripts live in
 // <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
 // honors PI_CODING_AGENT_DIR).
@@ -178,6 +192,10 @@ if (AUTH_TOKEN) {
 }
 /** 引擎选择：PI_WEB_ENGINE=pi|dsh（默认 pi）。重启生效。 */
 const ENGINE = process.env.PI_WEB_ENGINE === "dsh" ? "dsh" : "pi";
+/** PI_WEB_MANAGED=1: this instance is updated by whoever deploys it. */
+const MANAGED = isManaged();
+/** PI_WEB_TABS: the tabs this instance offers. null = all of them, as before. */
+const TABS = parseTabs();
 app.get("/api/health", (_req, res) => {
     res.json({ ok: true, piVersion: VERSION, cwd: CWD, pid: process.pid, engine: ENGINE });
 });
@@ -268,8 +286,17 @@ app.get("/api/themes", (_req, res) => {
 });
 // 语言包：核心只随包发布中英，其余按需下载到 <dataDir>/locales/<code>.json。
 // 手工放进去的同名 JSON 也会被识别（离线安装）。PI_WEB_TOKEN 鉴权自动覆盖。
+/**
+ * PI_WEB_LOCALE — the language a first visit falls back to.
+ *
+ * It is a fallback, not an override: an explicit choice, and then the
+ * browser's own languages, come first (web/src/pick-locale.ts). It rides on
+ * /api/locales because the client already asks for that at boot, so naming a
+ * default costs no extra request.
+ */
+const DEFAULT_LOCALE = (process.env.PI_WEB_LOCALE ?? "").trim().toLowerCase() || null;
 app.get("/api/locales", (_req, res) => {
-    res.json({ packs: listPacks(DATA_DIR) });
+    res.json({ packs: listPacks(DATA_DIR), defaultLocale: DEFAULT_LOCALE });
 });
 app.get("/api/locales/:code", (req, res) => {
     const code = String(req.params.code ?? "");
@@ -292,7 +319,9 @@ app.post("/api/locales/:code/install", async (req, res) => {
         return;
     }
     try {
-        const meta = await installPack(DATA_DIR, code, { baseUrl: LOCALE_BASE_URL, version: APP_VERSION });
+        const meta = await installPack(DATA_DIR, code, { baseUrl: LOCALE_BASE_URL, version: appVersion() });
+        // 新包可能自带 serverStrings（issue #91 v2）——重扫注册，无表则跳过。
+        loadServerStrings(DATA_DIR);
         res.json({ ok: true, ...meta });
     }
     catch (e) {
@@ -309,6 +338,7 @@ app.delete("/api/locales/:code", (req, res) => {
         res.status(404).end("locale not installed");
         return;
     }
+    unloadServerStrings(code);
     res.json({ ok: true });
 });
 // Serve a theme's full CSS file so the frontend can swap the whole stylesheet.
@@ -494,6 +524,9 @@ const service = ENGINE === "dsh"
     : new AgentService(CWD, 
     // Per-client persisted UI state: last-used workspace + recent projects.
     join(DATA_DIR, "client-state.json"));
+// Server-string tables (issue #91 v2): packs' `serverStrings` sections feed
+// pick() lookup for non-zh/en UI languages (missing key → English fallback).
+loadServerStrings(DATA_DIR);
 // Optional UI plugins (<dataDir>/plugins/<id>/): scanned on every client
 // attach so freshly dropped plugins appear without a server restart.
 const pluginMgr = new PluginManager(DATA_DIR, CWD, join(pkgRoot, "plugins", "catalog.json"));
@@ -650,6 +683,15 @@ wss.on("connection", (ws) => {
             pending.push(msg);
             return;
         }
+        // Managed instances do not install software on themselves, and tabs this
+        // instance does not offer stay closed. Both refusals live here, on the
+        // server, because hiding them in the client would still leave the message
+        // reachable to anything that can open the socket. See managed.ts / tabs.ts.
+        const refusal = managedRefusal(msg.type, MANAGED) ?? tabsRefusal(msg.type, TABS);
+        if (refusal) {
+            send({ type: "notice", level: "error", text: refusal });
+            return;
+        }
         switch (msg.type) {
             case "prompt":
                 void cs.prompt(msg.text, msg.attachments, msg.queue);
@@ -761,6 +803,11 @@ wss.on("connection", (ws) => {
             case "set_cwd":
                 void cs.setCwd(msg.path);
                 break;
+            case "set_locale":
+                // UI language report — per-client persist + lang-aware prompt
+                // refresh (streaming-safe). Engine-agnostic via DispatchSession.
+                void service.setLocale(clientId, msg.locale);
+                break;
             case "complete_path":
                 void cs.completePath(msg.path);
                 break;
@@ -886,6 +933,7 @@ wss.on("connection", (ws) => {
                     terminalBashIdleMs: msg.terminalBashIdleMs,
                     editSoftEnabled: msg.editSoftEnabled,
                     questionnaireEnabled: msg.questionnaireEnabled,
+                    goalModeEnabled: msg.goalModeEnabled,
                     thinkingWrap: msg.thinkingWrap,
                     toolsWrap: msg.toolsWrap,
                     visionBridgeEnabled: msg.visionBridgeEnabled,
@@ -908,7 +956,7 @@ wss.on("connection", (ws) => {
                 pluginMgr.handleMessage(msg.pluginId, msg.payload, clientId ?? undefined);
                 break;
             case "plugin_settings": {
-                const r = pluginMgr.savePluginSettings(msg.pluginId, msg.values ?? {});
+                const r = pluginMgr.savePluginSettings(msg.pluginId, msg.values ?? {}, () => cs?.getLang() ?? "en");
                 if (r.error) {
                     cs?.emitNotice("error", `插件设置保存失败：${r.error}`, `Failed to save plugin settings: ${r.error}`);
                 }
@@ -918,10 +966,10 @@ wss.on("connection", (ws) => {
                 break;
             }
             case "plugins_reload":
-                void pluginMgr.reload().then(() => pluginMgr.pushToAll());
+                void pluginMgr.reload(() => cs?.getLang() ?? "en").then(() => pluginMgr.pushToAll());
                 break;
             case "plugin_catalog_add": {
-                const r = pluginMgr.addCatalogEntry(msg.entry ?? {});
+                const r = pluginMgr.addCatalogEntry(msg.entry ?? {}, () => cs?.getLang() ?? "en");
                 if (r.error) {
                     cs?.emitNotice("error", `添加到插件列表失败：${r.error}`, `Failed to add to plugin list: ${r.error}`);
                 }
@@ -931,7 +979,7 @@ wss.on("connection", (ws) => {
                 break;
             }
             case "plugin_catalog_remove": {
-                const r = pluginMgr.removeCatalogEntry(msg.id);
+                const r = pluginMgr.removeCatalogEntry(msg.id, () => cs?.getLang() ?? "en");
                 if (r.error) {
                     cs?.emitNotice("error", `从插件列表移除失败：${r.error}`, `Failed to remove from plugin list: ${r.error}`);
                 }
@@ -990,11 +1038,17 @@ wss.on("connection", (ws) => {
                     serverVersion: VERSION,
                     protocolVersion: PROTOCOL_VERSION,
                     engine: ENGINE,
+                    // This package's own version. `serverVersion` is the pi SDK's,
+                    // and the client used to learn ours from the update check —
+                    // which a managed instance never runs.
+                    appVersion: appVersion(),
+                    managed: MANAGED,
+                    tabs: TABS ? [...TABS] : undefined,
                 });
                 // Plugin catalog: re-scan + activate new dirs on every attach so
                 // freshly dropped plugins show up without a server restart.
                 pluginMgr
-                    .ensureLoaded()
+                    .ensureLoaded(() => service.get(cid)?.getLang() ?? "en")
                     .then((plugins) => {
                     if (closed)
                         return;
@@ -1023,6 +1077,10 @@ wss.on("connection", (ws) => {
                     // 会重连，重连又失败会陷入循环。至少把状态推下去。
                     cs.flushSnapshot();
                 });
+                // hello may carry the UI locale — persist it before replaying
+                // anything queued during startup (issue #91).
+                if (msg.locale)
+                    void service.setLocale(cid, msg.locale);
                 // Replay anything that arrived while the session was starting.
                 const queued = pending;
                 pending = [];

package/dist/server/locales.js

@@ -13,8 +13,9 @@
  * tolerable. Manually dropped <dataDir>/locales/*.json files work too
  * (offline installs) — the list is read from disk.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractServerStrings, registerServerStrings, unregisterServerStrings, } from "./i18n.js";
 /** Packs available for download (alphabetical by code). */
 export const LOCALE_PACKS = [
     { code: "de", nativeName: "Deutsch" },
@@ -55,6 +56,23 @@ export function validatePack(data, code) {
     }
     if (Object.keys(strings).length === 0)
         return { ok: false, error: "empty strings" };
+    // Optional translator table for server-authored strings (issue #91 v2).
+    // Non-string values are rejected (same strictness as `strings`).
+    let serverStrings;
+    if (d["serverStrings"] !== undefined) {
+        if (!d["serverStrings"] || typeof d["serverStrings"] !== "object" || Array.isArray(d["serverStrings"])) {
+            return { ok: false, error: "invalid serverStrings" };
+        }
+        serverStrings = {};
+        for (const [k, v] of Object.entries(d["serverStrings"])) {
+            if (typeof v !== "string")
+                return { ok: false, error: `non-string server value for ${k}` };
+            if (v.length > 0)
+                serverStrings[k] = v;
+        }
+        if (Object.keys(serverStrings).length === 0)
+            serverStrings = undefined;
+    }
     return {
         ok: true,
         pack: {
@@ -62,6 +80,7 @@ export function validatePack(data, code) {
             nativeName: d["nativeName"].trim(),
             version: typeof d["version"] === "string" ? d["version"] : "unknown",
             strings,
+            serverStrings,
         },
     };
 }
@@ -87,6 +106,41 @@ export function listPacks(dataDir) {
         return { ...meta, installed: installed !== null, version: installed?.version ?? null };
     });
 }
+/**
+ * Server-string tables (issue #91 v2): scan `<dataDir>/locales/*.json` pack
+ * files and register each pack's `serverStrings` section for pick() lookup.
+ * Called once at startup and after every pack install/remove. Files that are
+ * missing/corrupt/have no table are skipped (best-effort, never throws).
+ * Returns the language codes that actually contributed a table.
+ */
+export function loadServerStrings(dataDir) {
+    const loaded = [];
+    let files = [];
+    try {
+        files = readdirSync(join(dataDir, "locales")).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return loaded;
+    }
+    for (const file of files) {
+        try {
+            const data = JSON.parse(readFileSync(join(dataDir, "locales", file), "utf8"));
+            const extracted = extractServerStrings(data);
+            if (extracted) {
+                registerServerStrings(extracted.code, extracted.table);
+                loaded.push(extracted.code);
+            }
+        }
+        catch {
+            // corrupt pack — UI serving already ignores it; skip here too
+        }
+    }
+    return loaded;
+}
+/** Drop one language's server-string table (pack removed). */
+export function unloadServerStrings(code) {
+    unregisterServerStrings(code);
+}
 export function removePack(dataDir, code) {
     if (!isKnownPack(code))
         return false;

package/dist/server/managed.js

@@ -0,0 +1,61 @@
+/**
+ * managed — instances whose updates come from outside.
+ *
+ * pi-web-ui can update itself: the top bar shows an updates badge and a panel
+ * whose buttons run `npm i -g pi-web-ui@latest` in a visible terminal and
+ * restart the server. The plugin market installs plugins from the network the
+ * same way. On a developer's laptop both are conveniences.
+ *
+ * Behind a deploy pipeline they are not. A Docker image, a distribution
+ * package, or a release script that also checks the reverse proxy, the service
+ * unit and the environment variables a new version needs — for all of those,
+ * an in-app self-update leaves the machine in a state nothing describes, until
+ * the next real deploy silently undoes it. `PI_WEB_MANAGED=1` says "this
+ * instance is managed from outside": the update paths refuse, and the client
+ * stops offering them.
+ *
+ * Two rules kept this small:
+ *
+ * - **The server refuses, the client only hides.** Hiding a button while the
+ *   socket still accepts the message is hiding, not disabling: anything that
+ *   can open the WebSocket can still send it.
+ * - **Nothing else changes.** Chatting, plugins already installed, git,
+ *   terminal, settings are untouched — this switch is about who installs
+ *   software on the machine, not about what the interface can do.
+ */
+/** The client messages that install or replace software on the machine. */
+export const MANAGED_MESSAGES = [
+    /** Update check behind the top-bar badge. */
+    "check_update",
+    /** "Re-check all" in the UPDATE panel (app + components). */
+    "check_updates_all",
+    /** Installs the pi agent itself. */
+    "install_pi_agent",
+    /** Plugin market: fetches and installs a plugin from the network. */
+    "plugin_catalog_add",
+];
+/**
+ * Whether this instance is managed from outside.
+ *
+ * Accepts the spellings people actually put in a systemd unit or a
+ * docker-compose file; anything else — including an empty variable — means no,
+ * so the default stays exactly what it is today.
+ */
+export function isManaged(env = process.env) {
+    const v = (env.PI_WEB_MANAGED ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+/**
+ * The reason to send back, or null when the message may proceed.
+ *
+ * Returning the text rather than a boolean keeps the caller a single line and
+ * puts the explanation next to the rule it comes from — the user gets a
+ * sentence, not a silently dropped message.
+ */
+export function managedRefusal(type, managed) {
+    if (!managed)
+        return null;
+    if (!MANAGED_MESSAGES.includes(type))
+        return null;
+    return "This instance is managed: updates and plugin installs are handled by whoever deploys it (PI_WEB_MANAGED=1).";
+}

package/dist/server/marker-service.js

@@ -1,9 +1,10 @@
 /**
  * marker-service.ts — 标记服务（内置版 pi-marker-tools）。
  */
+import { pick } from "./i18n.js";
 import { ensureMarkersRegistered, parseMarkers, getMarker, allMarkers, collectGuidance, listMarkerNames, } from "./markers/index.js";
 import { loadStateFromBranch, appendSnapshot } from "./markers/store.js";
-import { TODO_NAMESPACE, initTodoState, describeTodos } from "./markers/builtins/todo.js";
+import { TODO_NAMESPACE, initTodoState } from "./markers/builtins/todo.js";
 ensureMarkersRegistered();
 const DEFAULT_MARKERS = {
     markersEnabled: true,
@@ -32,18 +33,26 @@ export class MarkerService {
             return false;
         return !this.settings.disabledMarkers.includes(name);
     }
+    /** 当前服务端语言（英文默认，未接线前保持原有英文行为）。 */
+    lang() {
+        return this.host.lang?.() ?? "en";
+    }
     buildGuidance() {
         if (!this.settings.markersEnabled)
             return "";
         const disabled = new Set(this.settings.disabledMarkers);
-        const lines = collectGuidance(disabled);
+        const lines = collectGuidance(disabled, this.lang());
         if (lines.length === 0)
             return "";
-        return ("\n\n────────── 内联标记工具（重要）──────────\n" +
+        return pick(this.lang(), "\n\n────────── 内联标记工具（重要）──────────\n" +
             "状态类操作（任务、标记位、通知）请直接写在回答正文里，采用内联标记语法，而不要调用对应工具。\n" +
             "插件会替你执行并把标记从展示文本中移除，不会中断你的回答。\n\n" +
             lines.join("\n") +
-            "\n──────────\n");
+            "\n──────────\n", "\n\n────────── Inline marker tools (important) ──────────\n" +
+            "Write status operations (tasks, marker bits, notifications) directly in your reply text using inline marker syntax — do not call a tool for them.\n" +
+            "The plugin executes them and strips the markers from the displayed text without interrupting your reply.\n\n" +
+            lines.join("\n") +
+            "\n──────────\n", "markers.service.guidance.frame");
     }
     setEnabled(enabled) {
         this.settings.markersEnabled = !!enabled;
@@ -164,10 +173,14 @@ export class MarkerService {
             };
             let result;
             try {
-                result = await marker.apply(token, ctx, state);
+                result = await marker.apply(token, ctx, state, this.lang());
             }
             catch (e) {
-                result = { applied: false, error: `执行异常: ${e?.message ?? String(e)}` };
+                const errMsg = e?.message ?? String(e);
+                result = {
+                    applied: false,
+                    error: pick(this.lang(), `执行异常: ${errMsg}`, `Execution failed: ${errMsg}`, "markers.service.execution.failed", { errMsg: errMsg }),
+                };
             }
             if (result.applied) {
                 // todo 落库；notify/conv 即时生效（通知已发 / 对话已重命名），无需快照。
@@ -234,7 +247,7 @@ export class MarkerService {
         const st = this.getState(conversationId, TODO_NAMESPACE, initTodoState);
         const visible = st.tasks.filter((t) => includeDeleted || t.status !== "deleted");
         if (visible.length === 0)
-            return "No todos";
+            return pick(this.lang(), "[todo] （空）", "[todo] (empty)", "markers.service.describe.empty");
         return visible.map((t) => `[${t.status}] #${t.id}: ${t.subject}`).join("\n");
     }
     getRawState(conversationId, namespace) {

package/dist/server/markers/builtins/notify.js

@@ -1,19 +1,32 @@
 /**
  * builtins/notify.ts — 纯提醒标记。
  */
+import { getServerBlock, pick } from "../../i18n.js";
+const NOTIFY_GUIDANCE_ZH = [
+    "- [[notify:<级别>:<内容>]] 仅向用户显示一个非打断性提醒，不会进入正文。级别为 info|warning|success|error。",
+];
+const NOTIFY_GUIDANCE_EN = [
+    "- [[notify:<level>:<message>]] shows a non-interruptive notice to the user only; it never enters the reply text. Levels: info|warning|success|error.",
+];
+/** 语言感知的 notify guidance（issue #91）：en 用英译、zh 用中文，默认英文。 */
+export function getNotifyGuidance(lang = "en") {
+    return getServerBlock(lang, "markers.notify.guidance", NOTIFY_GUIDANCE_ZH, NOTIFY_GUIDANCE_EN);
+}
 export const notifyMarker = {
     name: "notify",
-    guidance: [
-        "- [[notify:<级别>:<内容>]] 仅向用户显示一个非打断性提醒，不会进入正文。级别为 info|warning|success|error。",
-    ],
-    async apply(token, ctx) {
+    guidance: NOTIFY_GUIDANCE_ZH,
+    getGuidance: getNotifyGuidance,
+    async apply(token, ctx, _state, lang = "en") {
         const level = token.op || token.kwargs["level"] || "info";
         const text = token.kwargs["text"] || token.args.join(" ") || "";
         if (!text)
-            return { applied: false, error: "notify 需要内容" };
+            return {
+                applied: false,
+                error: pick(lang, "notify 需要内容", "notify requires a message", "markers.notify.requires.message"),
+            };
         const safe = (level === "warning" || level === "error" ? level : "info");
         ctx.notify(text, safe);
-        return { applied: true, feedback: "notified" };
+        return { applied: true, feedback: pick(lang, "已发送提醒", "notified", "markers.notify.notified") };
     },
     overlay: undefined,
     init: () => undefined,