pi-web-ui 0.97.0 → 0.99.0

package/dist/server/goal-service.js

@@ -532,7 +532,9 @@ export class GoalService {
         conv.goalGeneration += 1;
         // 上一轮目标可能还留着常驻执行者子代理（委托执行）：先停掉再开新的，
         // 否则旧循环会在新目标上继续派活（代次已作废，但角色对话得收）。
-        this.stopDelegated(conv);
+        // await 到 dismiss 完全落定：后面的 spawn 名额检查才不会数到还在收尾的
+        // 旧执行者而误报上限（issue #464；stopDelegated 自身已按会话串行化）。
+        await this.stopDelegated(conv);
         const goal = conv.goal;
         goal.reviewing = false;
         goal.conversationId = goalConversationId;
@@ -817,10 +819,15 @@ export class GoalService {
                             aborted = true;
                         };
                         ac.signal.addEventListener("abort", onAbort, { once: true });
-                        const choose = isChoice ? ctx.ui.select(qTitle, params.options) : ctx.ui.input(qTitle);
-                        const ans = (await choose);
-                        ac.signal.removeEventListener("abort", onAbort);
-                        clearIdle();
+                        let ans;
+                        try {
+                            const choose = isChoice ? ctx.ui.select(qTitle, params.options) : ctx.ui.input(qTitle);
+                            ans = (await choose);
+                        }
+                        finally {
+                            ac.signal.removeEventListener("abort", onAbort);
+                            clearIdle();
+                        }
                         if (aborted || ac.signal.aborted) {
                             return {
                                 content: [
@@ -1120,7 +1127,8 @@ export class GoalService {
         const conv = this.host.activeConv();
         conv.goalGeneration += 1;
         // 委托执行：停掉在飞的执行者（循环靠代次作废 + 代次守卫退出）。
-        this.stopDelegated(conv);
+        // await 落定，保证旧执行者已移出会话表，后续重设目标不再误报名额（issue #464）。
+        await this.stopDelegated(conv);
         this.resetLoopCounters(conv);
         this.clearGoalFields(conv);
         this.emitGoalStatus();
@@ -1154,14 +1162,15 @@ export class GoalService {
      */
     async stopAllGoals() {
         let stopped = 0;
-        // 直接迭代：stopDelegated 只发 fire-and-forget 的停/收请求，不会同步改这张表
-        // （循环退出是异步的，靠代次守卫），无需快照。
-        for (const convId of this.delegatedLoops.keys()) {
+        // 快照迭代：await stopDelegated 期间，循环退出的回调可能增删这张表。
+        for (const convId of [...this.delegatedLoops.keys()]) {
             const conv = this.host.getConv(convId);
             if (!conv)
                 continue;
             conv.goalGeneration += 1; // 作废在飞回调（循环靠代次守卫退出）
-            this.stopDelegated(conv); // 停执行者 + 唤醒 verdict 等待者 + 清 roles/phase
+            // 逐个 await 停/收落定（stopDelegated 已按会话串行化，issue #464）：
+            // 停执行者 + 唤醒 verdict 等待者 + 清 roles/phase
+            await this.stopDelegated(conv);
             this.resetLoopCounters(conv);
             this.clearGoalFields(conv);
             stopped++;
@@ -1205,6 +1214,8 @@ export class GoalService {
                 }
                 conv.goalGeneration += 1;
                 // 委托执行：手动停止也要把在飞的执行者停掉（否则它还在后台改工作区）。
+                // 本钩子是同步上下文，fire-and-forget 即可：stopDelegated 已按会话
+                // 串行化（issue #464），重设/清除目标的一方会先等这次 dismiss 落定。
                 this.stopDelegated(conv);
                 this.resetLoopCounters(conv);
                 g.conversationId = null;
@@ -1398,7 +1409,24 @@ export class GoalService {
         conv.goal.roles = {};
         return exec?.convId;
     }
+    stopInflight = new Map();
+    /**
+     * 停掉委托执行者（stop + dismiss + 唤醒等待者）。同一会话并发调用时按序串行：
+     * 上一次 stop/dismiss 未落定前，下一次先等它 —— 否则重设目标时旧执行者尚未
+     * 移出会话表，随后 spawn 的名额检查会数到它而误报容量上限（issue #464）。
+     * 同步上下文（onAgentEnd 等钩子）可以继续 fire-and-forget，串行化由这里兜住。
+     */
     stopDelegated(conv) {
+        const prev = this.stopInflight.get(conv.id);
+        const run = prev ? prev.catch(() => { }).then(() => this.stopDelegatedNow(conv)) : this.stopDelegatedNow(conv);
+        this.stopInflight.set(conv.id, run);
+        void run.finally(() => {
+            if (this.stopInflight.get(conv.id) === run)
+                this.stopInflight.delete(conv.id);
+        });
+        return run;
+    }
+    async stopDelegatedNow(conv) {
         // 排队的启动请求一并作废：setGoal 会在后面按新代次重新排，clearGoal 则不需要。
         this.delegatedPending.delete(conv.id);
         conv.awaitingVerdict = undefined;
@@ -1411,6 +1439,30 @@ export class GoalService {
             settle("gone");
         }
         const execId = this.detachRoleExec(conv);
+        if (execId) {
+            try {
+                await this.host.stopRoleAgent?.(execId);
+            }
+            catch { }
+            try {
+                // issue #464: 必须等待执行者完全 dismiss 移出会话表，避免立即重设目标时误报容量超限
+                await this.host.dismissRoleAgent?.(execId);
+            }
+            catch { }
+        }
+        conv.goal.phase = "idle";
+    }
+    /** 会话过户时清理目标审查态并唤醒等待者（issue #457）。 */
+    notifyTakeover(conv) {
+        this.delegatedPending.delete(conv.id);
+        conv.awaitingVerdict = undefined;
+        void this.flushDeferredPrompts(conv);
+        const settle = this.verdictWaiters.get(conv.id);
+        if (settle) {
+            this.verdictWaiters.delete(conv.id);
+            settle("gone");
+        }
+        const execId = this.detachRoleExec(conv);
         if (execId) {
             void this.host.stopRoleAgent?.(execId).catch(() => { });
             void this.host.dismissRoleAgent?.(execId).catch(() => { });
@@ -1581,6 +1633,14 @@ export class GoalService {
                 // 落盘对话在左栏/历史里没有「子代理」微标，用带前缀的标题保持可辨识。
                 title: this.roleConvTitle(goalText),
             });
+            // #490/案1：spawn 的长 await 期间目标可能被重设/清除（goalGeneration 已变，
+            // stopDelegated 当时无可停执行者）——老循环不得把带着老目标首轮 prompt 的
+            // 执行者写回 conv.roleExec，否则新循环会把它当现役执行者 steer（上下文被
+            // 老目标污染，新目标首轮产出混入老目标工作）。就地停掉并让老循环按代次退出。
+            if (conv.goalGeneration !== goalGeneration) {
+                void host.stopRoleAgent?.(convId).catch(() => { });
+                return undefined;
+            }
             conv.roleExec = { convId, generation: (conv.roleExec?.generation ?? 0) + 1 };
             g.roles = { ...g.roles, executor: { convId, spawned: true } };
             this.beginRoundVitals(conv, convId);
@@ -1762,6 +1822,13 @@ export class GoalService {
             phase: "start",
             round,
         });
+        // #490/案2：pushReviewCard 的 await 窗口里 setGoal/clearGoal 可能已清掉
+        // awaitingVerdict（此刻 verdictWaiters 尚未登记，stopDelegated 的 settle 落空）
+        // ——不复检就会继续登记 waiter 并把老目标的审查指令投进主对话：主对话白烧
+        // 一轮审查、老循环干等 20 分钟超时，新目标的 pending 循环全程无法启动。
+        if (!conv.awaitingVerdict || conv.awaitingVerdict.round !== round) {
+            return "gone";
+        }
         const verdict = await new Promise((resolve) => {
             let settled = false;
             let timer;

package/dist/server/index.js

@@ -56,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";
@@ -89,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
@@ -976,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" };
@@ -988,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 { }
             }
         }
     }
@@ -1272,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);
             }
@@ -1290,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);
         }
@@ -1535,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();
@@ -1651,7 +1703,9 @@ wss.on("connection", (ws) => {
                 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);
@@ -1686,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.
@@ -1745,12 +1793,14 @@ wss.on("connection", (ws) => {
                     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;
@@ -2231,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
@@ -2472,6 +2525,18 @@ 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);
@@ -2532,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;
@@ -2600,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,6 +853,7 @@ 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",
@@ -838,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") {
@@ -854,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" },
@@ -863,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) ||
@@ -878,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" },
                 };
             }
@@ -893,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" },
@@ -904,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" },
@@ -1065,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: [
                             {
@@ -1074,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") {
@@ -1219,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") {
@@ -1267,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 {
@@ -1327,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)) {
@@ -1347,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: {
@@ -1355,6 +1450,7 @@ Lines are 1-indexed.`,
                             clean,
                             notReported,
                             referencedFiles: dependents.map((p) => relative(cwd, p).replace(/\\/g, "/")),
+                            referencedFilesTotal: totalReferencing,
                         },
                     };
                 }