pi-web-ui 0.96.1 → 0.98.0

package/dist/server/index.js

@@ -16,6 +16,9 @@
  *   all share one conversation list per project.
  *   PI_CODING_AGENT_DIR  pi config dir (auth/models/skills) — passed to the SDK
  */
+// MUST be imported before the SDK is loaded so on-disk patches apply cleanly.
+import "./patch-remote-catalog.js";
+import "./patch-turn-end-boundary.js";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import { createServer, request as proxyRequest } from "node:http";
@@ -53,7 +56,7 @@ import { syncPluginCatalog } from "./plugin-catalog-sync.js";
 import { McpBridge } from "./mcp-bridge.js";
 import { createMcpHotReload } from "./mcp-hot-reload.js";
 import { createHostMetricsSampler } from "./host-metrics.js";
-import { SchedulerStore } from "./scheduler-tasks.js";
+import { SchedulerStore, SchedulerValidationError } from "./scheduler-tasks.js";
 import { initHttpProxy } from "./http-proxy.js";
 import { globalLspPool } from "./lsp-tool.js";
 import { buildPiWebTokenCookie, decodeCookieToken, isTlsRequest } from "./auth-cookie.js";
@@ -86,6 +89,13 @@ function cliFlag(name) {
     return undefined;
 }
 const PORT = Number(cliFlag("--port") ?? process.env.PI_WEB_PORT ?? 8787);
+// #506：直启路径与 bin 层对齐做端口校验——`--port abc` / `PI_WEB_PORT=abc` 之前会
+// listen(NaN) 被 Node 当 0 绑到随机端口，且日志打印 http://localhost:NaN。
+if (!Number.isInteger(PORT) || PORT <= 0 || PORT > 65535) {
+    console.error(`无效端口: ${cliFlag("--port") ?? process.env.PI_WEB_PORT} (--port / PI_WEB_PORT)`);
+    console.error(`Invalid port: ${cliFlag("--port") ?? process.env.PI_WEB_PORT} (--port / PI_WEB_PORT)`);
+    process.exit(1);
+}
 const CWD = resolve(cliFlag("--cwd") ?? process.env.PI_WEB_CWD ?? process.cwd());
 const DATA_DIR = resolve(cliFlag("--data-dir") ?? process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"));
 // The data dir is where the control socket, client state, plugins, themes and
@@ -973,6 +983,8 @@ httpServer.on("upgrade", (req, socket, head) => {
 // closing sockets, sleep/wake, network partitions). Also broadcasts lightweight
 // server host metrics (CPU and memory usage) sampled every ~2s.
 const HEARTBEAT_INTERVAL_MS = 2_000;
+/** 全局广播与心跳推送背压阈值（256KB）：socket 积压时丢弃广播消息，防用户态无界堆积（issue #460）。 */
+const BROADCAST_BACKPRESSURE_MAX_BYTES = 262_144;
 const sampleHostMetrics = createHostMetricsSampler();
 const heartbeatTimer = setInterval(() => {
     let message = { type: "heartbeat" };
@@ -985,8 +997,40 @@ const heartbeatTimer = setInterval(() => {
     if (wss.clients.size > 0) {
         const payload = JSON.stringify(message);
         for (const ws of wss.clients) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(payload);
+            if (ws.readyState !== WebSocket.OPEN)
+                continue;
+            const tracked = ws;
+            // 半开连接死连接回收（issue #460）：连续无活动/无 pong 则 terminate
+            if (tracked.isAlive === false) {
+                tracked.missedPings = (tracked.missedPings || 0) + 1;
+                if (tracked.missedPings >= 3) {
+                    try {
+                        ws.terminate?.();
+                    }
+                    catch { }
+                    continue;
+                }
+            }
+            else {
+                tracked.missedPings = 0;
+            }
+            tracked.isAlive = false;
+            try {
+                ws.ping();
+            }
+            catch {
+                try {
+                    ws.terminate?.();
+                }
+                catch { }
+                continue;
+            }
+            // 广播背压：缓冲积压严重时跳过心跳推送
+            if (ws.bufferedAmount <= BROADCAST_BACKPRESSURE_MAX_BYTES) {
+                try {
+                    ws.send(payload);
+                }
+                catch { }
             }
         }
     }
@@ -1269,6 +1313,8 @@ function pushSchedulerTasks() {
         for (const client of wss.clients) {
             if (client.readyState !== WebSocket.OPEN)
                 continue;
+            if (client.bufferedAmount > BROADCAST_BACKPRESSURE_MAX_BYTES)
+                continue;
             try {
                 client.send(payload);
             }
@@ -1287,6 +1333,8 @@ function pushNoticeToAll(level, text, textEn) {
     for (const client of wss.clients) {
         if (client.readyState !== WebSocket.OPEN)
             continue;
+        if (client.bufferedAmount > BROADCAST_BACKPRESSURE_MAX_BYTES)
+            continue;
         try {
             client.send(payload);
         }
@@ -1532,6 +1580,13 @@ function serializeShared(msg) {
     return s;
 }
 wss.on("connection", (ws) => {
+    const tracked = ws;
+    tracked.isAlive = true;
+    tracked.missedPings = 0;
+    ws.on("pong", () => {
+        tracked.isAlive = true;
+        tracked.missedPings = 0;
+    });
     // Count attached sockets (the control socket reports REAL sockets, not
     // cached client-session objects).
     service.noteSocketOpen();
@@ -1633,11 +1688,24 @@ wss.on("connection", (ws) => {
             return;
         }
         switch (msg.type) {
-            case "prompt":
+            case "prompt": {
+                const hasAttach = Boolean(msg.attachments && msg.attachments.length > 0);
+                if (!msg.text?.trim() && !hasAttach) {
+                    send({
+                        type: "notice",
+                        level: "warning",
+                        text: "发送已忽略：提示词为空且未附带文件或上下文引用。",
+                        textEn: "Prompt ignored: text is empty and no attachments were provided.",
+                    });
+                    break;
+                }
                 void cs.prompt(msg.text, msg.attachments, msg.queue);
                 break;
+            }
             case "queue_remove":
-                cs.removeQueued(msg.kind, msg.text, msg.index);
+                // #491：removeQueued 是 async——dispatch 是 fire-and-forget，缺 void 时
+                // 内部抛错即 unhandledRejection，而全仓没有兜底 handler，Node ≥15 直接崩进程。
+                void cs.removeQueued(msg.kind, msg.text, msg.index);
                 break;
             case "draft_update":
                 cs.saveDraft?.(msg.sessionId, msg.text, msg.ts);
@@ -1672,12 +1740,6 @@ wss.on("connection", (ws) => {
             case "rollback_session":
                 void cs.rollbackSession?.(msg.messageId, msg.conversationId, msg.restoreWorkspace);
                 break;
-            case "cycle_model":
-                void cs.cycleModel();
-                break;
-            case "cycle_thinking":
-                cs.cycleThinking();
-                break;
             case "get_state":
                 // Always a FULL snapshot: the client is (re)connecting or detected
                 // a rev/seq gap — it needs an authoritative state to rebuild from.
@@ -1697,6 +1759,9 @@ wss.on("connection", (ws) => {
                     send({ type: "tool_info", name: msg.name, found: false, unsupported: true });
                 }
                 break;
+            case "get_compacted_messages":
+                void cs.getCompactedMessages?.(msg.compactionMessageId, msg.conversationId);
+                break;
             case "list_sessions":
                 void cs.refreshSessions();
                 break;
@@ -1723,12 +1788,19 @@ wss.on("connection", (ws) => {
                     void cs.persistConversation(msg.id);
                 }
                 break;
+            case "pin_conversation":
+                if (typeof cs.setConversationPinned === "function") {
+                    void cs.setConversationPinned(msg.id, msg.pinned);
+                }
+                break;
+            case "pin_session":
+                if (typeof cs.pinSession === "function") {
+                    void cs.pinSession(msg.path, msg.pinned);
+                }
+                break;
             case "dismiss_finished_subagents":
                 void cs.dismissFinishedSubagents(msg.parentId);
                 break;
-            case "subagent_handoff":
-                void cs.handoffSubagent?.(msg.fromRunId, msg.toRunId, msg.payload);
-                break;
             case "switch_session":
                 void cs.switchSession(msg.path);
                 break;
@@ -2019,6 +2091,7 @@ wss.on("connection", (ws) => {
                     reviewModel: msg.reviewModel,
                     maxRounds: msg.maxRounds,
                     locked: msg.locked,
+                    execModel: msg.execModel,
                 });
                 break;
             case "clear_goal":
@@ -2036,6 +2109,7 @@ wss.on("connection", (ws) => {
                     reviewModel: msg.reviewModel,
                     maxRounds: msg.maxRounds,
                     locked: msg.locked,
+                    execModel: msg.execModel,
                 });
                 break;
             case "get_settings":
@@ -2207,6 +2281,9 @@ wss.on("connection", (ws) => {
                         done: async (ok, info) => {
                             if (ok) {
                                 await reloadPluginsAndPush(jobLang);
+                                if (typeof cs?.checkPluginUpdates === "function") {
+                                    void cs.checkPluginUpdates(false);
+                                }
                                 const isZh = jobLang() === "zh";
                                 const actionLabel = jobAction === "uninstall"
                                     ? isZh
@@ -2448,6 +2525,28 @@ wss.on("connection", (ws) => {
             case "plan_update":
                 cs.updatePlan?.(msg.steps, msg.activeStepId, msg.conversationId);
                 break;
+            case "plan_step_update":
+                cs.updatePlanStep?.(msg.stepId, msg.patch, msg.conversationId);
+                break;
+            case "plan_step_delete":
+                cs.deletePlanStep?.(msg.stepId, msg.conversationId);
+                break;
+            case "plan_step_add":
+                cs.addPlanStep?.(msg.step, msg.afterStepId, msg.conversationId);
+                break;
+            case "plan_clean_handoff":
+                void cs.planCleanHandoff?.(msg.steps, msg.prompt);
+                break;
+            case "set_plan_mode":
+                // 计划模式（只规划不实施）：会话级开关，热生效（提示词重建 + 工具硬闸门）。
+                void cs.setPlanMode?.(msg.enabled, msg.conversationId);
+                break;
+            case "set_delegate_mode":
+                // 审查者模式（自动委派）：会话级开关，默认关。开启后本对话只审阅，
+                // 用户 prompt 由服务端转给常驻落盘执行对话。DSH 引擎的实现在
+                // setDelegateMode 里直接拒（无 customTools 注册面 → 闸门无处可挂）。
+                void cs.setDelegateMode?.(msg.enabled, msg.conversationId);
+                break;
             case "page_response":
                 // 浏览器（page-picker 扩展经前端）对 browser_page 的回包：恢复挂起的
                 // pageCall；id 不匹配（超时后迟到/页面刷新）由 resolvePageCall 静默忽略。
@@ -2498,11 +2597,12 @@ wss.on("connection", (ws) => {
                     scheduler.upsert(msg.task);
                 }
                 catch (err) {
+                    const isVal = err instanceof SchedulerValidationError;
                     send({
                         type: "notice",
                         level: "error",
-                        text: `保存定时任务失败：${err.message}`,
-                        textEn: `Failed to save scheduled task: ${err.message}`,
+                        text: `保存定时任务失败：${isVal ? err.messageZh : err.message}`,
+                        textEn: `Failed to save scheduled task: ${isVal ? err.messageEn : err.message}`,
                     });
                 }
                 break;
@@ -2566,6 +2666,8 @@ wss.on("connection", (ws) => {
         service: SERVICE_INFO ?? undefined,
     });
     ws.on("message", (data) => {
+        tracked.isAlive = true;
+        tracked.missedPings = 0;
         let msg;
         try {
             msg = JSON.parse(data.toString());

package/dist/server/launch-origin.js

@@ -136,10 +136,6 @@ export function launchOrigin() {
     cached ??= detectLaunchOrigin();
     return cached;
 }
-/** 仅测试用：清掉缓存。 */
-export function resetLaunchOriginCache() {
-    cached = null;
-}
 /** 下发给浏览器的服务信息（null = 没有 supervisor，界面不提供「重启服务」）。 */
 export function toServiceInfo(origin) {
     if (!origin.supervisor)

package/dist/server/locales.js

@@ -13,9 +13,10 @@
  * 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 { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { extractServerStrings, registerServerStrings, unregisterServerStrings } from "./i18n.js";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 /** Packs available for download (alphabetical by code). */
 export const LOCALE_PACKS = [
     { code: "de", nativeName: "Deutsch" },
@@ -188,11 +189,8 @@ export async function installPack(dataDir, code, opts = {}) {
             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);
+            writeJsonAtomicSync(file, v.pack, 0);
             return { code, nativeName: v.pack.nativeName, version: v.pack.version };
         }
         catch (e) {

package/dist/server/lsp-tool.js

@@ -19,6 +19,7 @@ import { delimiter, extname, isAbsolute, join, relative, resolve, sep } from "no
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { pick } from "./i18n.js";
 export const LSP_TOOL_NAME = "lsp";
 export const LSP_SYMBOL_KINDS = {
     1: "File",
@@ -694,13 +695,22 @@ export async function getLiveLspDiagnostics(absPath, cwd) {
     });
     return `⚠️ Post-edit Diagnostics (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}`;
 }
+/** 文本大纲与 details.symbols 共用的展平符号数上限（顶层与子级一并计数）。 */
+const DOCUMENT_SYMBOL_OUTLINE_CAP = 300;
+/**
+ * details.symbols 的序列化体积预算（字符数）。details 随会话持久且整体 ≤64KB，
+ * 超限会被整条丢弃（见 serialize.ts 的 TOOL_DETAILS_CAP）；符号名/签名极长的
+ * 极端文件（生成的 .d.ts、protobuf 产物）下 300 个符号也可能撑爆，故按实际
+ * 序列化体积逐步收紧上限（预算留足余量给 count/truncated 等包装字段）。
+ */
+const DOCUMENT_SYMBOL_DETAILS_CHAR_BUDGET = 60_000;
 /**
  * 递归格式化 DocumentSymbol 列表为缩进的符号大纲树（做条数上限保护）
  */
 function formatDocumentSymbols(symbols, indent = "", lines = []) {
     for (const sym of symbols) {
-        if (lines.length >= 300) {
-            lines.push(`${indent}• ... [Truncated: outline exceeds 300 symbols]`);
+        if (lines.length >= DOCUMENT_SYMBOL_OUTLINE_CAP) {
+            lines.push(`${indent}• ... [Truncated: outline exceeds ${DOCUMENT_SYMBOL_OUTLINE_CAP} symbols]`);
             break;
         }
         const kind = LSP_SYMBOL_KINDS[sym.kind] || `Kind(${sym.kind})`;
@@ -716,6 +726,56 @@ function formatDocumentSymbols(symbols, indent = "", lines = []) {
     }
     return lines;
 }
+/**
+ * 与 formatDocumentSymbols 同口径的结构化裁剪：按展平后的符号数（先序遍历，
+ * 顶层与子级一并计数）截断到 cap 个。只在展平序列的边界上裁剪，保留符号的
+ * 父子结构保持一致 —— 父被裁掉则整棵子树不再出现；有符号被裁时 truncated 置真。
+ * 未触发截断时原样返回（不拷贝，避免大对象无谓重建）。
+ */
+function capDocumentSymbolTree(symbols, cap) {
+    let count = 0;
+    let truncated = false;
+    const walk = (list) => {
+        const kept = [];
+        let changed = false;
+        for (const sym of list) {
+            if (count >= cap) {
+                truncated = true;
+                break;
+            }
+            count += 1;
+            if (Array.isArray(sym.children) && sym.children.length > 0) {
+                const sub = walk(sym.children);
+                if (sub.changed || sub.kept.length !== sym.children.length) {
+                    changed = true;
+                    kept.push({ ...sym, children: sub.kept });
+                    continue;
+                }
+            }
+            kept.push(sym);
+        }
+        return { kept, changed };
+    };
+    const { kept } = walk(symbols);
+    return { capped: truncated ? kept : symbols, truncated };
+}
+/**
+ * details.symbols 的最终裁剪：先与文本大纲同口径按展平计数截到 300；再用实际
+ * 序列化体积校验 —— details 随会话持久且整体 ≤64KB，超限整条丢弃（见
+ * serialize.ts 的 TOOL_DETAILS_CAP），符号名/签名极长的极端文件下按半数逐步
+ * 收紧展平上限，保证结构化大纲真的能进快照而不是被整条丢掉。
+ */
+function capDocumentSymbolsForDetails(symbols) {
+    let cap = DOCUMENT_SYMBOL_OUTLINE_CAP;
+    let res = capDocumentSymbolTree(symbols, cap);
+    let size = JSON.stringify(res.capped).length;
+    while (size > DOCUMENT_SYMBOL_DETAILS_CHAR_BUDGET && cap > 1) {
+        cap = Math.floor(cap / 2);
+        res = capDocumentSymbolTree(symbols, cap);
+        size = JSON.stringify(res.capped).length;
+    }
+    return res;
+}
 /**
  * 递归单趟查找符号（两遍扫描：先严格精确匹配，未命中再执行大小写忽略回退，避免遮蔽后续精确符号；支持 containerName 点分路径）
  */
@@ -793,8 +853,10 @@ function findDefaultSourceFileForLsp(cwd) {
 }
 export function makeLspTool(options) {
     const cwd = options.cwd;
+    const getLang = options.lang ?? (() => "en");
     return defineTool({
         name: LSP_TOOL_NAME,
+        promptSnippet: "IDE-grade semantic analysis (LSP) across the workspace: definition, references, hover, diagnostics, symbols, impact check",
         label: "LSP code intelligence",
         description: `IDE-grade semantic analysis (LSP) across the workspace. Actions:
 - \`definition\`: definition of the symbol at \`line\`/\`character\` in \`path\` (file, line, snippet).
@@ -807,16 +869,18 @@ export function makeLspTool(options) {
 - \`cascade\`: impact check for \`path\` — report diagnostics of files referencing it.
 Lines are 1-indexed.`,
         parameters: Type.Object({
-            action: Type.Union([
-                Type.Literal("definition"),
-                Type.Literal("references"),
-                Type.Literal("hover"),
-                Type.Literal("diagnostics"),
-                Type.Literal("documentSymbol"),
-                Type.Literal("read_symbol"),
-                Type.Literal("workspaceSymbol"),
-                Type.Literal("cascade"),
-            ], {
+            action: Type.Unsafe({
+                type: "string",
+                enum: [
+                    "definition",
+                    "references",
+                    "hover",
+                    "diagnostics",
+                    "documentSymbol",
+                    "read_symbol",
+                    "workspaceSymbol",
+                    "cascade",
+                ],
                 description: "The LSP operation to perform.",
             }),
             path: Type.Optional(Type.String({
@@ -835,13 +899,16 @@ Lines are 1-indexed.`,
                 description: "1-indexed column/character position (defaults to 1).",
             })),
             timeout: Type.Optional(Type.Number({
-                description: "Timeout in seconds (defaults to 15).",
+                minimum: 1,
+                maximum: 120,
+                description: "Timeout in seconds (1-120, defaults to 15).",
             })),
             allowInstall: Type.Optional(Type.Boolean({
                 description: "Install the missing language server into ~/.pi-web/lsp-servers (user-space, no sudo). Default false: the tool returns an installHint instead.",
             })),
         }),
         async execute(_callId, params, _signal, _onUpdate, _ctx) {
+            const L = getLang();
             const action = params.action;
             let targetPath = params.path;
             if (!targetPath && action === "workspaceSymbol") {
@@ -851,7 +918,7 @@ Lines are 1-indexed.`,
                         content: [
                             {
                                 type: "text",
-                                text: `Error: Could not automatically detect a primary project source file to route language server. Please provide 'path' (pointing to any source file in the project, e.g. path='src/index.ts') to select the language server.`,
+                                text: pick(L, "错误：无法自动检测项目主要源码文件以路由语言服务器。请提供 'path' 参数（指向项目中任意源码文件，例如 path='src/index.ts'）。", "Error: Could not automatically detect a primary project source file to route language server. Please provide 'path' (pointing to any source file in the project, e.g. path='src/index.ts') to select the language server."),
                             },
                         ],
                         details: { ok: false, error: "Missing path: cannot route language server" },
@@ -860,14 +927,19 @@ Lines are 1-indexed.`,
             }
             if (!targetPath) {
                 return {
-                    content: [{ type: "text", text: `Error: 'path' parameter is required for action '${action}'.` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: pick(L, `错误：执行操作 '${action}' 时必须提供 'path' 参数。`, `Error: 'path' parameter is required for action '${action}'.`),
+                        },
+                    ],
                     details: { ok: false, error: "Missing path parameter" },
                 };
             }
             const absPath = isAbsolute(targetPath) ? targetPath : resolve(cwd, targetPath);
             const line = typeof params.line === "number" ? Math.max(1, params.line) : 1;
             const character = typeof params.character === "number" ? Math.max(1, params.character) : 1;
-            const timeoutMs = (params.timeout ?? 15) * 1000;
+            const timeoutMs = Math.max(1000, Math.min(120_000, Math.floor((params.timeout ?? 15) * 1000)));
             const rel = relative(cwd, absPath);
             if (rel === ".." ||
                 rel.startsWith(".." + sep) ||
@@ -875,13 +947,23 @@ Lines are 1-indexed.`,
                 rel.startsWith("..\\") ||
                 isAbsolute(rel)) {
                 return {
-                    content: [{ type: "text", text: `Error: Path traversal denied: ${targetPath} is outside workspace.` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: pick(L, `错误：路径穿越已被拒绝：${targetPath} 超出了工作区范围。`, `Error: Path traversal denied: ${targetPath} is outside workspace.`),
+                        },
+                    ],
                     details: { ok: false, error: "Path traversal denied" },
                 };
             }
             if (!existsSync(absPath)) {
                 return {
-                    content: [{ type: "text", text: `Error: File not found: ${targetPath}` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: pick(L, `错误：文件不存在：${targetPath}`, `Error: File not found: ${targetPath}`),
+                        },
+                    ],
                     details: { ok: false, error: "File not found" },
                 };
             }
@@ -890,7 +972,7 @@ Lines are 1-indexed.`,
                     content: [
                         {
                             type: "text",
-                            text: `Error: 'symbol' parameter is required for 'read_symbol' action (e.g. symbol="parseConfig" or "ClassName.methodName").`,
+                            text: pick(L, `错误：执行 'read_symbol' 操作必须提供 'symbol' 参数（例如 symbol="parseConfig" 或 "ClassName.methodName"）。`, `Error: 'symbol' parameter is required for 'read_symbol' action (e.g. symbol="parseConfig" or "ClassName.methodName").`),
                         },
                     ],
                     details: { ok: false, error: "Missing symbol parameter" },
@@ -901,7 +983,7 @@ Lines are 1-indexed.`,
                     content: [
                         {
                             type: "text",
-                            text: `Error: 'query' parameter cannot be empty for 'workspaceSymbol' action. Please provide a search term (e.g. query='User' or 'Router').`,
+                            text: pick(L, `错误：执行 'workspaceSymbol' 操作时 'query' 参数不能为空。请提供搜索词（例如 query='User' 或 'Router'）。`, `Error: 'query' parameter cannot be empty for 'workspaceSymbol' action. Please provide a search term (e.g. query='User' or 'Router').`),
                         },
                     ],
                     details: { ok: false, error: "Empty query parameter" },
@@ -1062,8 +1144,10 @@ Lines are 1-indexed.`,
                         };
                     }
                     const lines = formatDocumentSymbols(symbols);
-                    // details 随会话持久且整体 ≤64KB（超限整条丢弃）：symbols 与文本大纲同口径截断
-                    const detailsSymbols = symbols.length > 300 ? symbols.slice(0, 300) : symbols;
+                    // details 随会话持久且整体 ≤64KB（超限整条丢弃）：symbols 与文本大纲同口径
+                    // 截断 —— 按展平后的符号数（先序遍历，顶层与子级一并计数）截到 300，保留
+                    // 符号维持父子结构；再按序列化体积兜底收紧，极端文件下保证 details 进得了快照。
+                    const { capped: detailsSymbols, truncated: symbolsTruncated } = capDocumentSymbolsForDetails(symbols);
                     return {
                         content: [
                             {
@@ -1071,7 +1155,7 @@ Lines are 1-indexed.`,
                                 text: `Symbols in ${targetPath} (${symbols.length} top-level):\n${lines.join("\n")}`,
                             },
                         ],
-                        details: { ok: true, count: symbols.length, symbols: detailsSymbols },
+                        details: { ok: true, count: symbols.length, symbols: detailsSymbols, truncated: symbolsTruncated },
                     };
                 }
                 if (action === "read_symbol") {
@@ -1216,12 +1300,14 @@ Lines are 1-indexed.`,
                     const normalizePath = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
                     // 1. 收集种子位置：给了 line/character 就只查那个符号；否则查全部顶层符号。
                     const seeds = [];
+                    let seedTotal = 0; // 顶层符号总数（截断前），超出 MAX_SEEDS 时在输出尾部标明
                     if (typeof params.line === "number") {
                         seeds.push({ line: line - 1, character: character - 1 });
                     }
                     else {
                         const symResult = await client.request("textDocument/documentSymbol", { textDocument: { uri } }, timeoutMs);
                         const topSymbols = Array.isArray(symResult) ? symResult : [];
+                        seedTotal = topSymbols.length;
                         for (const sym of topSymbols.slice(0, MAX_SEEDS)) {
                             const pos = sym.selectionRange?.start ?? sym.range?.start ?? sym.location?.range?.start;
                             if (pos && typeof pos.line === "number") {
@@ -1264,6 +1350,10 @@ Lines are 1-indexed.`,
                             depPaths.add(refPath);
                         }
                     }
+                    // 只分析排序后的前 MAX_DEPENDENTS 个引用方，但计数必须如实上报：文本与
+                    // details 都带截断前的真实总数，超出部分用尾注标明（对照 references 动作
+                    // 的 "... and N more references" 口径），避免模型误以为清单是完整的。
+                    const totalReferencing = depPaths.size;
                     const dependents = [...depPaths].sort().slice(0, MAX_DEPENDENTS);
                     if (dependents.length === 0) {
                         return {
@@ -1324,7 +1414,7 @@ Lines are 1-indexed.`,
                     }
                     impacted.sort((a, b) => b.errors - a.errors || b.warnings - a.warnings);
                     const out = [];
-                    out.push(`Impact cascade for ${targetPath}: ${dependents.length} referencing file(s), ${impacted.length} with findings.`);
+                    out.push(`Impact cascade for ${targetPath}: ${totalReferencing} referencing file(s), ${impacted.length} with findings.`);
                     for (const item of impacted) {
                         out.push(`• ${item.path} — ${item.errors} error(s), ${item.warnings} warning(s)`);
                         for (const d of item.diagnostics.slice(0, 5)) {
@@ -1344,6 +1434,14 @@ Lines are 1-indexed.`,
                     if (notReported.length > 0) {
                         out.push(`Diagnostics not reported in time (${notReported.length}, server may still be analyzing): ${notReported.slice(0, 5).join(", ")}${notReported.length > 5 ? ", ..." : ""}`);
                     }
+                    // 截断尾注：与 references 动作的 "... and N more references" 同口径，
+                    // 让模型知道被丢弃的引用方/种子符号既不在 clean 也不在 notReported 里。
+                    if (totalReferencing > dependents.length) {
+                        out.push(`... and ${totalReferencing - dependents.length} more not analyzed`);
+                    }
+                    if (seedTotal > MAX_SEEDS) {
+                        out.push(`... and ${seedTotal - MAX_SEEDS} more top-level symbols not analyzed`);
+                    }
                     return {
                         content: [{ type: "text", text: out.join("\n") }],
                         details: {
@@ -1352,6 +1450,7 @@ Lines are 1-indexed.`,
                             clean,
                             notReported,
                             referencedFiles: dependents.map((p) => relative(cwd, p).replace(/\\/g, "/")),
+                            referencedFilesTotal: totalReferencing,
                         },
                     };
                 }

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

@@ -3,10 +3,12 @@
  */
 import { getServerBlock, pick } from "../../i18n.js";
 const NOTIFY_GUIDANCE_ZH = [
-    "- [[notify:<级别>:<内容>]] 仅向用户显示一个非打断性提醒，不会进入正文。级别为 info|warning|success|error。",
+    // #499：guidance 只能承诺协议真实支持的级别——success 从未存在于 notice 协议
+    // （protocol.ts 仅 info|warning|error），按指引用 success 会被静默降级成 info。
+    "- [[notify:<级别>:<内容>]] 仅向用户显示一个非打断性提醒，不会进入正文。级别为 info|warning|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:<level>:<message>]] shows a non-interruptive notice to the user only; it never enters the reply text. Levels: info|warning|error.",
 ];
 /** 语言感知的 notify guidance（issue #91）：en 用英译、zh 用中文，默认英文。 */
 export function getNotifyGuidance(lang = "en") {

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

@@ -10,7 +10,6 @@
  *         不需要额外状态。
  */
 import { getServerBlock, pick } from "../../i18n.js";
-export const RENAME_NAMESPACE = "conv";
 function extractTitle(token) {
     // args[0] 是主标题；kwargs 兼容 text/name/title
     const fromArgs = token.args.join(" ").trim();