pi-web-ui 0.68.1 → 0.69.0

package/dist/server/index.js

@@ -16,7 +16,7 @@
  *   all share one conversation list per project.
  *   PI_CODING_AGENT_DIR  pi config dir (auth/models/skills) — passed to the SDK
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { createConnection } from "node:net";
@@ -36,6 +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 { 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 两种写法。
@@ -76,6 +79,31 @@ const ALLOW_ORIGINS = (process.env.PI_WEB_ALLOW_ORIGINS ?? "")
  *  Authorization: Bearer / X-PI-Token 头、?token= 查询参数或 pi_web_token cookie
  *  任一匹配即可；供 0.0.0.0 / 反代等暴露场景兜底，未设置则行为不变。 */
 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 对齐。
+ *
+ * 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).
@@ -164,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 });
 });
@@ -252,6 +284,63 @@ const USER_THEMES_DIR = join(DATA_DIR, "themes");
 app.get("/api/themes", (_req, res) => {
     res.json({ themes: listThemes(BUILTIN_THEMES_DIR, USER_THEMES_DIR) });
 });
+// 语言包：核心只随包发布中英，其余按需下载到 <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), defaultLocale: DEFAULT_LOCALE });
+});
+app.get("/api/locales/:code", (req, res) => {
+    const code = String(req.params.code ?? "");
+    if (!isKnownPack(code)) {
+        res.status(404).end("unknown locale");
+        return;
+    }
+    const pack = readPackFile(DATA_DIR, code);
+    if (!pack) {
+        res.status(404).end("locale not installed");
+        return;
+    }
+    res.setHeader("Cache-Control", "no-cache");
+    res.json(pack);
+});
+app.post("/api/locales/:code/install", async (req, res) => {
+    const code = String(req.params.code ?? "");
+    if (!isKnownPack(code)) {
+        res.status(400).json({ error: `unknown locale: ${code}` });
+        return;
+    }
+    try {
+        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) {
+        res.status(502).json({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
+app.delete("/api/locales/:code", (req, res) => {
+    const code = String(req.params.code ?? "");
+    if (!isKnownPack(code)) {
+        res.status(404).end("unknown locale");
+        return;
+    }
+    if (!removePack(DATA_DIR, code)) {
+        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.
 // Registered before the SPA catch-all below (otherwise it'd return index.html).
 app.get("/themes/:id.css", (req, res) => {
@@ -435,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"));
@@ -591,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);
@@ -702,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;
@@ -826,6 +932,8 @@ wss.on("connection", (ws) => {
                     terminalBash: msg.terminalBash,
                     terminalBashIdleMs: msg.terminalBashIdleMs,
                     editSoftEnabled: msg.editSoftEnabled,
+                    questionnaireEnabled: msg.questionnaireEnabled,
+                    goalModeEnabled: msg.goalModeEnabled,
                     thinkingWrap: msg.thinkingWrap,
                     toolsWrap: msg.toolsWrap,
                     visionBridgeEnabled: msg.visionBridgeEnabled,
@@ -848,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}`);
                 }
@@ -858,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}`);
                 }
@@ -871,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}`);
                 }
@@ -930,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;
@@ -963,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

@@ -0,0 +1,210 @@
+/**
+ * locales — downloadable language packs.
+ *
+ * Core ships zh/en only (see web/src/i18n.tsx). Every other language lives in
+ * `locales/<code>.json` in the git repo (NOT in the npm `files` whitelist, so
+ * packs never ship with the package) with shape:
+ *   { code, nativeName, version, strings: Record<string,string> }
+ *
+ * On demand the server downloads a pack from PI_WEB_LOCALE_BASE_URL
+ * (default: GitHub raw — version tag first, `main` as fallback) into
+ * <dataDir>/locales/<code>.json and serves it to the browser. Missing keys
+ * fall back to English client-side, so version skew between app and pack is
+ * tolerable. Manually dropped <dataDir>/locales/*.json files work too
+ * (offline installs) — the list is read from disk.
+ */
+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" },
+    { code: "es", nativeName: "Español" },
+    { code: "fr", nativeName: "Français" },
+    { code: "it", nativeName: "Italiano" },
+    { code: "ja", nativeName: "日本語" },
+    { code: "ko", nativeName: "한국어" },
+    { code: "pt", nativeName: "Português" },
+    { code: "ru", nativeName: "Русский" },
+];
+export function isKnownPack(code) {
+    return LOCALE_PACKS.some((p) => p.code === code);
+}
+export function packMeta(code) {
+    return LOCALE_PACKS.find((p) => p.code === code) ?? null;
+}
+export function packPath(dataDir, code) {
+    return join(dataDir, "locales", `${code}.json`);
+}
+/** Downloaded packs must look like this (extra fields ignored). */
+export function validatePack(data, code) {
+    if (!data || typeof data !== "object")
+        return { ok: false, error: "not an object" };
+    const d = data;
+    if (d["code"] !== code)
+        return { ok: false, error: `code mismatch (want ${code})` };
+    if (typeof d["nativeName"] !== "string" || !d["nativeName"].trim()) {
+        return { ok: false, error: "missing nativeName" };
+    }
+    if (!d["strings"] || typeof d["strings"] !== "object")
+        return { ok: false, error: "missing strings" };
+    const strings = {};
+    for (const [k, v] of Object.entries(d["strings"])) {
+        if (typeof v !== "string")
+            return { ok: false, error: `non-string value for ${k}` };
+        strings[k] = v;
+    }
+    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: {
+            code,
+            nativeName: d["nativeName"].trim(),
+            version: typeof d["version"] === "string" ? d["version"] : "unknown",
+            strings,
+            serverStrings,
+        },
+    };
+}
+/** Read an installed pack (null when missing / corrupt — corrupt files are ignored, not deleted). */
+export function readPackFile(dataDir, code) {
+    if (!isKnownPack(code))
+        return null;
+    const file = packPath(dataDir, code);
+    if (!existsSync(file))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(file, "utf8"));
+        const v = validatePack(data, code);
+        return v.ok ? v.pack : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function listPacks(dataDir) {
+    return LOCALE_PACKS.map((meta) => {
+        const installed = readPackFile(dataDir, meta.code);
+        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;
+    const file = packPath(dataDir, code);
+    if (!existsSync(file))
+        return false;
+    rmSync(file);
+    return true;
+}
+const MAX_PACK_BYTES = 4 * 1024 * 1024;
+/**
+ * Download a pack and persist it under <dataDir>/locales/<code>.json
+ * (atomic write via tmp + rename). Throws on network / validation errors.
+ */
+export async function installPack(dataDir, code, opts = {}) {
+    const meta = packMeta(code);
+    if (!meta)
+        throw new Error(`unknown locale: ${code}`);
+    const base = (opts.baseUrl ?? "https://raw.githubusercontent.com/xing-shuyin/pi-web-ui").replace(/\/+$/, "");
+    const urls = opts.version
+        ? [`${base}/v${opts.version}/locales/${code}.json`, `${base}/main/locales/${code}.json`]
+        : [`${base}/main/locales/${code}.json`];
+    const fetchFn = opts.fetchFn ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    let lastError = "";
+    for (const url of urls) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            const res = await fetchFn(url, { signal: ctrl.signal });
+            if (!res.ok) {
+                lastError = `HTTP ${res.status} for ${url}`;
+                continue;
+            }
+            const text = await res.text();
+            if (text.length > MAX_PACK_BYTES)
+                throw new Error(`pack too large (${text.length} bytes)`);
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`invalid JSON from ${url}`);
+            }
+            const v = validatePack(data, code);
+            if (!v.ok)
+                throw new Error(`invalid pack ${code}: ${v.error}`);
+            mkdirSync(join(dataDir, "locales"), { recursive: true });
+            const file = packPath(dataDir, code);
+            const tmp = `${file}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(v.pack));
+            renameSync(tmp, file);
+            return { code, nativeName: v.pack.nativeName, version: v.pack.version };
+        }
+        catch (e) {
+            lastError = e instanceof Error ? e.message : String(e);
+            // A validation error means the URL answered with wrong content —
+            // don't silently retry the fallback for it, surface it directly.
+            if (lastError.startsWith("invalid "))
+                throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    throw new Error(lastError || `download failed for ${code}`);
+}

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,