dsh-math-calculator 2.1.1 → 2.2.0

package/lib/index.js

@@ -23,20 +23,19 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { nullspaceOf, rankOf, singularValuesOf } from './numeric.js';
 import { ambiguousSymbols, explainSymbol, symbolMeanings } from './symbols.js';
 import { DOMAINS, DOMAIN_NAMES, LAYERS, domainCounts, domainsOf, formulasByDomain, formulasByLayer, layerCounts, layerOf, } from './taxonomy.js';
-import { containsNonFinite, formatValue, toFiniteNumber, toJsonValue, unwrapResult, } from './format.js';
+import { containsNonFinite, formatValue, isNonFiniteValue, toFiniteNumber, toJsonValue, unwrapResult, } from './format.js';
 import { describe, binomialCdf, binomialPmf, chiSquareCdf, exponentialCdf, linearRegression, normalCdf, normalInv, normalPdf, poissonCdf, poissonPmf, polynomialRegression, quantile, studentTCdf, } from './stats.js';
 import { SymbolicError, symbolicDerivative, symbolicExpand, symbolicIntegral, symbolicRootsWithComplex, symbolicSimplify, } from './symbolic.js';
 import { parseLinearEquation, solveLinearSystem_, splitEquations, } from './systems.js';
 import { FormulaError, buildFormulaScope, describeFormula, listFormulasByFrequency, listFormulaCategories, resolveExpression, resolveParams, resolveFormulaStrict, scoreFormulas, } from './formulas.js';
 import { BUILTINS } from './formula-builtins.js';
 import { getActiveConstants, } from './constants-graph.js';
-import { currentWorkspace, loadWorkspace, bindHostWorkspace, cwdOfExec, cwdOfSession, displayPrecisionOf, scopeFromCwd, setLastExecShape, switchWorkspace, } from './workspace.js';
+import { currentWorkspace, loadWorkspace, bindHostWorkspace, cwdOfExec, cwdOfSession, displayPrecisionOf, scopeFromCwd, setLastExecShape, switchWorkspace, workspaceVariablesOf, } from './workspace.js';
 import { buildApiRoutes } from './api.js';
 import { materializeFormulas, } from './formula-table.js';
-import { FORMULAS } from './formulas.js';
 import { TOOL_DESCRIPTION, buildSystemPromptSection, setPromptMode, suggestOperation, } from './awareness.js';
 import { buildReminderMessage, recordPrompt, shouldPromptNow, } from './detector.js';
-import { CalcError, bignum, currentDisplayPrecision, fast, normalizeSource, safeNumberForJson, setActiveDisplayPrecision, trimNumber, } from './ops/shared.js';
+import { CalcError, bignum, currentDisplayPrecision, fast, normalizeSource, normalizeChineseUnits, rational, safeNumberForJson, setActiveDisplayPrecision, trimNumber, } from './ops/shared.js';
 import { PRECISION_LOSS_THRESHOLD, consumePrecisionLoss, isDisplayPrecisionExplicit, setDisplayPrecisionExplicit, } from './precision-report.js';
 import { opOde } from './ops/ode-op.js';
 import { opWorld } from './ops/world-op.js';
@@ -47,6 +46,9 @@ import { opQuantities } from './ops/quantities-op.js';
 import { opFormulaTable } from './ops/formula-table-op.js';
 import { opFeasibility } from './ops/feasibility-op.js';
 import { opDerivation } from './ops/derivation-op.js';
+import { WORLD_KEYS } from './world-params.js';
+import { opHelp } from './help.js';
+import { annotateMagnitude, annotateMetricPrefix, checkAnchors, checkAngleUnit, checkLabelMagnitude, explainUnitResult, findBatchAnomalies } from './guards.js';
 import { opCustom } from './ops/custom-op.js';
 import { opUnits } from './ops/units-op.js';
 import { opBalance } from './ops/balance-op.js';
@@ -172,7 +174,207 @@ const RISKY_FUNCTION_LIMITS = new Map([
 // 错误
 // ────────────────────────────────────────────────────────────────────────────
 /** 把任意异常翻译成带类型的 CalcError。 */
-function translateError(raw, fallbackType = 'internal') {
+/**
+ * 给括号类语法错补一句「在哪一层、哪一对对不上」。
+ *
+ * ## 为什么需要它
+ *
+ * 原来的提示是一句固定文案「检查括号是否配对、运算符是否连续」——
+ * 对长公式等于没说。实测反馈原话：char 25 指向的是多余的右括号，
+ * 真正缺的那个左括号在更前面，人得自己数。
+ *
+ * 这里做的是**最小可用的定位**，不是完整解析器：
+ *   · 扫一遍得到每个括号的层级与配对状态
+ *   · 报出第一处不配对的位置（缺左 / 多右）
+ *   · 回显表达式并在下方标出各层的起止
+ *
+ * ## 为什么不做「自动补括号」
+ *
+ * 猜意图补全括号，猜错时会把报错变成一个**算错的数** ——
+ * 比直接报错糟得多。这里只指出位置，补不补、补在哪，由调用方决定。
+ *
+ * @param source - 归一化后的表达式
+ * @returns 提示文本；括号本身平衡时返回空串（说明不是括号问题）
+ */
+function diagnoseParentheses(source) {
+    if (typeof source !== 'string' || source === '')
+        return '';
+    const openAt = [];
+    const pairs = [];
+    let depth = 0;
+    let firstUnexpectedClose = -1;
+    /** 引号内的括号不算结构（例如 5 cm to "inch(2)" 这类）。 */
+    let inQuote = null;
+    for (let i = 0; i < source.length; i += 1) {
+        const ch = source[i];
+        if (inQuote !== null) {
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === '(') {
+            openAt.push({ index: i, depth });
+            depth += 1;
+        }
+        else if (ch === ')') {
+            depth -= 1;
+            const opened = openAt.pop();
+            if (opened === undefined) {
+                if (firstUnexpectedClose < 0)
+                    firstUnexpectedClose = i;
+                depth = 0;
+            }
+            else {
+                pairs.push({ open: opened.index, close: i, depth: opened.depth });
+            }
+        }
+    }
+    const lines = [];
+    if (firstUnexpectedClose >= 0) {
+        lines.push('第 ' + (firstUnexpectedClose + 1) + ' 个字符处的 ")" 没有对应的左括号');
+        if (openAt.length > 0) {
+            lines.push('这几个左括号始终没配上: ' + openAt.map(function (o) { return '第 ' + (o.index + 1) + ' 字符'; }).join('、'));
+        }
+        lines.push('多数情况是它前面漏了一个 "("');
+    }
+    else if (openAt.length > 0) {
+        lines.push('这几个左括号没有闭合: ' + openAt.map(function (o) { return '第 ' + (o.index + 1) + ' 字符'; }).join('、'));
+        lines.push('在末尾补上 ' + openAt.length + ' 个 ")" 即可（若本意不是这样，删掉多余的 "("）');
+    }
+    else {
+        return '';
+    }
+    /** 回显表达式并标出层级（超过 120 字符只给结论，避免糊成一片）。 */
+    if (source.length <= 120) {
+        const marks = [];
+        for (let i = 0; i < source.length; i += 1)
+            marks.push(' ');
+        for (const pair of pairs) {
+            marks[pair.open] = String(Math.min(9, pair.depth));
+            marks[pair.close] = String(Math.min(9, pair.depth));
+        }
+        lines.push('');
+        lines.push(source);
+        lines.push(marks.join(''));
+        lines.push('（数字标的是括号层级，同层级的左右括号应该一一对应）');
+    }
+    return lines.join('\n');
+}
+/**
+ * 语法错误的具体解释：**先认常见误因，再退到通用诊断**。
+ *
+ * ## 为什么需要分类
+ *
+ * 实测反馈（2026-11-06 第二份）列了三种同 `syntax` 但原因完全不同的情况：
+ *
+ * ```
+ *   / 112.5e8     → 「检查括号是否配对、运算符是否连续」
+ *   2.66亿 * 330  → 没有任何提示
+ *   1,000 * 2     → 仍说「检查括号」  ← 真因是千分位逗号
+ * ```
+ *
+ * 第三条最糟：**提示指向了错误的方向**。用户会去数括号，而问题是逗号。
+ *
+ * ## 顺序：具体 → 通用
+ *
+ * 越具体的误因越先判，因为它们能被可靠识别；都认不出才用括号诊断兜底。
+ *
+ * @param source - 归一化后的表达式
+ * @param engineText - 引擎给的原始消息（含 char 位置）
+ * @returns 解释文本
+ */
+function explainSyntax(source, engineText) {
+    const at = engineText.match(/char ([0-9]+)/i);
+    const position = at ? Number(at[1]) : 0;
+    /** 出错字符附近的一小段，便于用户对照。 */
+    const snippet = position > 0 && source.length > 0
+        ? source.slice(Math.max(0, position - 1), Math.min(source.length, position + 6))
+        : '';
+    /**
+     * ① 千分位逗号 —— 中文语料里极常见（`1,000`、`139,000,000`）。
+     * 引擎把逗号当分隔符，报语法错。
+     */
+    if (/[0-9],[0-9]{3}/.test(source)) {
+        return '无法解析：表达式里有**千分位逗号**（如 1,000）。去掉逗号即可 —— 千分位只是书写习惯，不参与计算。';
+    }
+    /**
+     * ② 中文/未知字符 —— 量级词与中文单位若无对应展开，会落到这里。
+     * 给出可操作的下一步（而不是「检查括号」）。
+     */
+    if (/[\u4e00-\u9fff]/.test(source)) {
+        return '无法解析：表达式里有中文。中文单位（里/丈/亩/斤/吨）与量级词（万/亿/万亿）可直接写；' +
+            '其它中文标识符请改用英文变量名，或先存进工作区。';
+    }
+    /**
+     * ③ 运算符位置 —— 开头/连续运算符。
+     */
+    if (/^[*/+^]|\/\/|[*/+^]{2,}/.test(source)) {
+        return '无法解析：运算符位置不对' + (position > 0 ? '（第 ' + position + ' 个字符附近「' + snippet + '」）' : '') +
+            '。检查是否以运算符开头，或出现连续运算符。';
+    }
+    /**
+     * ④ 兜底：括号诊断（它会给出层级图），再退到通用建议。
+     */
+    const diagnostic = diagnoseParentheses(source);
+    if (diagnostic)
+        return diagnostic;
+    return '检查括号是否配对、运算符是否连续。' +
+        (position > 0 ? '（引擎报错位置：第 ' + position + ' 个字符「' + snippet + '」）' : '');
+}
+/**
+ * 把 mathjs `Unexpected type of argument in function to` 这类内部报错
+ * 翻译成调用方能行动的说法。
+ *
+ * ## 为什么它必须单独处理
+ *
+ * 实测（1107 报告问题 6）：
+ *
+ * ```
+ *   (0.907 kg / (10 hp * 0.475)) to min
+ *   → 错误[internal]: Unexpected type of argument in function to
+ *      (expected: Unit or string or ... actual: function, index: 1)
+ * ```
+ *
+ * `internal` 在本项目的约定里意思是**工具自己坏了** —— 会让人去重试，
+ * 而真实原因有四种，全部是写法问题：
+ *
+ * ```
+ *   ① 目标单位名撞上内置函数   1 s to min    → actual: function
+ *      （min/max/mean/sum/abs/round… 在 mathjs 里是函数，不是单位）
+ *   ② 值根本不是单位           0.5 to kW     → actual: Unit | identifier
+ *      （`to` 只能把**带单位的量**换算，裸数字没有单位可换）
+ *   ③ 值算了半天不是有限数     (1/0) to kW
+ *   ④ 目标单位拼错             2 m to cmm
+ * ```
+ *
+ * 四类的修复方向完全不同，所以不能笼统说「检查写法」。
+ *
+ * @param message - mathjs 的原始消息
+ * @returns 翻译后的错误；认不出时返回 null（交给上层兜底）
+ */
+function translateToError(message) {
+    if (!/in function to\b/i.test(message))
+        return null;
+    /** ① 目标单位名是内置函数：消息里 `actual: function` 就是这个信号。 */
+    if (/actual: function/i.test(message)) {
+        const known = ['min', 'max', 'mean', 'median', 'mode', 'sum', 'prod', 'std', 'variance', 'abs', 'sqrt', 'exp', 'log', 'floor', 'ceil', 'round', 'sign', 'norm', 'size', 'index', 'count', 'map', 'filter'];
+        return new CalcError('unit_name_conflict', '目标单位名与内置函数同名，mathjs 把它当函数而不是单位', '常见撞名: ' + known.slice(0, 10).join(' / ') + ' …' +
+            '。时间单位写全称（minute / hour / second），或改用 operation="units"' +
+            '（units 的单位表与函数命名空间互不干扰）。');
+    }
+    /** ② 值不是单位：`actual: Unit | identifier` 说明左边根本没解析成带单位的量。 */
+    if (/actual: Unit \| identifier/i.test(message)) {
+        return new CalcError('not_a_quantity', 'to 只能给「带单位的量」换算，左边这个值不带单位', '要么写成带单位的形态（1 hp、2 kg），要么先去算出一个带单位的结果；' +
+            '纯数字换单位请用 operation="units"（给 unitValue/unitFrom/unitTo）。');
+    }
+    /** ③ 剩下的是「左边算出来不是有限数量」，最典型是除以零。（按 4 类） */
+    return new CalcError('not_a_quantity', 'to 的目标单位没被识别，或左边的值不构成可换算的量', '检查目标单位拼写（cm / cm^3 / MJ/kg）；若左边算式含除法，先确认它没除以零。');
+}
+function translateError(raw, fallbackType = 'internal', source = '') {
     if (raw instanceof CalcError)
         return raw;
     if (raw instanceof SymbolicError) {
@@ -180,11 +382,36 @@ function translateError(raw, fallbackType = 'internal') {
     }
     const message = raw instanceof Error ? raw.message : String(raw ?? '未知错误');
     const text = message.trim() || '未知错误';
+    /** `to` 的四种写法错误优先翻译 —— 它原本一律落进 `internal`。 */
+    const toError = translateToError(text);
+    if (toError)
+        return toError;
     if (/Undefined symbol/i.test(text)) {
         return new CalcError('unknown_symbol', text, '先定义变量，或通过 variables 参数传入，例如 {"m": 500}。');
     }
-    if (/Unexpected end of expression|Value expected|Parenthesis|Invalid left hand side|SyntaxError|Unexpected operator/i.test(text)) {
-        return new CalcError('syntax', text, '检查括号是否配对、运算符是否连续。');
+    /**
+     * 未定义的函数也归 `unknown_symbol`，不归 `internal`。
+     *
+     * 实测反馈：`nosuchfunc(1)` 报 `internal`，而 `internal` 的含义是
+     * 「工具自己坏了」—— 会误导用户去重试同一个错。函数名打错是**输入问题**，
+     * 该给可操作的提示。
+     */
+    if (/Undefined function/i.test(text)) {
+        const name = text.match(/Undefined function\s+(\S+)/i)?.[1] ?? '';
+        return new CalcError('unknown_symbol', name ? '没有名为 "' + name + '" 的函数' : text, '可用 operation="help" 查看支持的全部函数与公式。');
+    }
+    /**
+     * ⚠️ `SyntaxError` 与 `Syntax error` **不是同一个字符串**：一个是标识符名、一个是消息文本。
+     * mathjs 抛的是后者（`Syntax error in part "某中文*2" (char 1)`）。
+     *
+     * 踩过：正则只写了前者，于是这类错误落到了末尾的兜底分支 ——
+     * 表现为「错误类型对（syntax）、但没有任何 hint」。这类漏判不报错、不显眼，
+     * 靠的是对照实验（同样是语法错，`1+*2` 有提示而 `某中文*2` 没有）才揪出来。
+     *
+     * 所以两种写法都收，并且用 `\s*` 容忍中间空格差异。
+     */
+    if (/Unexpected end of expression|Value expected|Parenthesis|Invalid left hand side|Syntax\s*Error|Unexpected operator/i.test(text)) {
+        return new CalcError('syntax', text, explainSyntax(source, text));
     }
     if (/Units do not match|Cannot convert|not found.*unit/i.test(text)) {
         return new CalcError('unit_mismatch', text, '两侧单位必须同量纲。');
@@ -209,6 +436,152 @@ function translateError(raw, fallbackType = 'internal') {
 // ────────────────────────────────────────────────────────────────────────────
 // AST 安全校验
 // ────────────────────────────────────────────────────────────────────────────
+/**
+ * mathjs 内置的**单字母单位符号**。
+ *
+ * 实测确认的完整清单（`math.evaluate('1 X')` 能得到 Unit 的那些）。
+ * 注意 `i`（虚数单位）与 `e`（自然常数）**不在**此列 —— 它们是常量不是单位。
+ */
+const BARE_UNIT_LETTERS = new Set('ABCFHJKLNSTVWbghlmst'.split(''));
+/**
+ * 拦下「未定义的单字母变量被当成单位」这一类**静默错误**。
+ *
+ * ## 为什么这是最危险的一类
+ *
+ * 实测反馈（`math_execute_实测问题与改进建议.md` 的 P0-2）：
+ *
+ * ```
+ * rho=2035; rho*V   → 2.035 kV     ← V 被当成伏特
+ * rho=2035; rho*m   → 2.035 km     ← m 被当成米
+ * rho=2035; rho*g   → 2.035 kg     ← g 被当成克
+ * ```
+ *
+ * 不报错、不警告，而且数字看着正常（2.035 是个"合理"的数）。
+ * 而物理推演里最规范的变量名恰恰都是单字母：m/V/W/T/L/P/A/C/h/g。
+ * **工具在惩罚最规范的命名习惯。**
+ *
+ * ## 为什么不能简单地「未定义就报错」
+ *
+ * 因为 mathjs 把 `5 V`（单位）与 `rho*V`（变量）解析成**完全相同**的 AST：
+ *
+ * ```
+ * 5 V    → OperatorNode(*) [ConstantNode(5), SymbolNode(V)]
+ * rho*V  → OperatorNode(*) [SymbolNode(rho), SymbolNode(V)]
+ * ```
+ *
+ * 语法层无法区分，只能看**上下文**。所以判据是：
+ *
+ * · 放行：符号处「单位位置」—— 父是乘法且兄弟里有数字（`5 V`、`9.81 m`），
+ *   或父是幂且指数是数字（`s^2`）。这些是真单位用法。
+ * · 报错：符号与**已定义变量同级**（`rho*V` 的兄弟 rho 已定义），
+ *   或它**单独出现**（`V` 一个字母单独求值，语义含糊）。
+ * · 其它：放行（如纯单位表达式 `9.81 m/s^2`）。
+ *
+ * ## 已知的取舍
+ *
+ * 批内混用「变量 + 单位」会被拦（`["v=30", "9.81 m/s^2 * v"]` 里的 m/s）。
+ * 这是有意的：那种写法本身含糊，报错比猜更安全，且提示会说明两种写法。
+ *
+ * @param node - 已解析的 AST
+ * @param scope - 当前作用域（含已定义变量）
+ */
+function guardBareUnitSymbols(node, scope) {
+    if (!node || typeof node !== 'object')
+        return;
+    const defined = new Set(Object.keys(scope ?? {}));
+    const problems = [];
+    const visit = (current, parent) => {
+        if (!current || typeof current !== 'object')
+            return;
+        if (current.type === 'SymbolNode') {
+            const name = String(current.name ?? '');
+            if (name.length === 1 && !defined.has(name) && BARE_UNIT_LETTERS.has(name)) {
+                const siblings = Array.isArray(parent?.args) ? parent.args : [];
+                const others = siblings.filter((a) => a !== current);
+                const hasConstantSibling = others.some((a) => a?.type === 'ConstantNode');
+                const hasDefinedSibling = others.some((a) => a?.type === 'SymbolNode' && defined.has(String(a.name)));
+                /**
+                 * ★ 顺序是判据的一部分，不能只看「同级有没有数字」。
+                 *
+                 * mathjs 保留了书写顺序，于是：
+                 *
+                 *   2 b   → OperatorNode(*) [0:ConstantNode(2), 1:SymbolNode(b)]   ← 单位
+                 *   b*2   → OperatorNode(*) [0:SymbolNode(b), 1:ConstantNode(2)]   ← 变量
+                 *
+                 * 两者兄弟都含数字，旧判据一律放过 —— 结果 `b*2` 被算成
+                 * 「2 b（单位）」，静默给出 `2 b`。实测踩到过：
+                 * 批量里 `b=oops*2` 失败之后，后续 `d=b*2` 不报错、算出 `2 b`，
+                 * 一个依赖失败步骤的下游悄悄变成了合法结果（虚成功）。
+                 *
+                 * 单位写法是「数字在前、符号在后」；符号在前是**变量乘数字**。
+                 */
+                const symbolIndex = siblings.indexOf(current);
+                const constantIndex = siblings.findIndex((a) => a?.type === 'ConstantNode');
+                const constantBefore = constantIndex >= 0 && constantIndex < symbolIndex;
+                // 单位位置：数字 × 单位（数字在前）、或 数字 × 单位的幂
+                const isUnitPosition = (parent?.type === 'OperatorNode' && parent.op === '*' && constantBefore) ||
+                    (parent?.type === 'OperatorNode' && parent.op === '^' && hasConstantSibling);
+                /**
+                 * 三个条件里**任一**成立就报：都不是「数字在前的单位写法」时，
+                 * 这个单字母就不该被静默当成单位。
+                 *
+                 * 踩过的坑：旧版只报了「有已定义兄弟」与「单独出现」两种情况，
+                 * 于是 `b*2`（符号在前、没有已定义兄弟、又不是根）三条全不命中，
+                 * 被放过去算成 `2 b` —— 批量里一个失败步骤的下游就这样变成了
+                 * 「成功」，而且是合法单位结果，最难看出来的那种。
+                 */
+                if (!isUnitPosition) {
+                    const isBareSymbolChild = parent?.type === 'OperatorNode' &&
+                        parent.op === '*' &&
+                        siblings.length === 2 &&
+                        siblings.every((a) => a === current || a?.type === 'ConstantNode');
+                    if (hasDefinedSibling || parent === null || isBareSymbolChild)
+                        problems.push(name);
+                }
+            }
+            return;
+        }
+        for (const key of ['args', 'items']) {
+            const list = current[key];
+            if (Array.isArray(list))
+                for (const child of list)
+                    visit(child, current);
+        }
+        if (current.content)
+            visit(current.content, current);
+        if (current.object)
+            visit(current.object, current);
+        if (current.index)
+            visit(current.index, current);
+        /**
+         * ★ 赋值语句的右半部分挂在 `value` 上，不在 `args` 里。
+         *
+         * 踩过的坑：`d=b*2` 的 AST 是 `AssignmentNode(name=d, value=OperatorNode(*))`，
+         * 而这里原本只走 `args/items/content/object/index` —— 赋值右侧**整个不被遍历**。
+         * 于是批量里 `b=oops*2` 失败之后，`d=b*2` 从未被判据看到，
+         * 直接被 mathjs 当成「2 b」算出一个合法单位结果。
+         *
+         * 这类「下游悄悄变成虚成功」比报错难发现得多：批量汇总里它是「成功」。
+         */
+        if (current.value && typeof current.value === 'object')
+            visit(current.value, current);
+    };
+    visit(node, null);
+    if (problems.length > 0) {
+        const uniq = [...new Set(problems)];
+        const list = uniq.map((n) => '"' + n + '"').join('、');
+        /**
+         * 「为什么报错」这句写在 `hint` 里，不写 `message`。
+         *
+         * 批量模式的失败行格式是 `失败[type]：<hint>`，**只显示 hint**；
+         * 单条模式两者都回。把「既是变量名也是单位符号」放进 hint，
+         * 两种模式都能看到 —— 这是用户理解报错原因的唯一线索。
+         */
+        throw new CalcError('unknown_symbol', '未定义的标识符 ' + list, list + ' 既是变量名也是单位符号。若要当单位用，请写成带数字的形式（如 "5 V"）；' +
+            '若要当变量，请先在本次调用里赋值，或通过 variables 参数传入（如 {"' +
+            uniq[0] + '": 100}）。');
+    }
+}
 function guardAst(node) {
     if (!node || typeof node.traverse !== 'function')
         return;
@@ -240,6 +613,65 @@ function guardAst(node) {
         }
     });
 }
+/**
+ * 判断表达式里有没有**显式要求的目标单位**。
+ *
+ * mathjs 里三种写法都表示「换成这个单位」：
+ *
+ * ```
+ *   5 cm to inch            OperatorNode(op=to)
+ *   to(5 cm, inch)          FunctionNode(fn=to)
+ *   (10 hp/0.475).to('kW')  FunctionNode(fn=AccessorNode(property=to))
+ * ```
+ *
+ * ## 为什么需要这个判断
+ *
+ * 输出层的单位归位（`normalizeUnitPrefix`）会在「没人指定单位」时挑一个顺口的档。
+ * 但调用方一旦写了 `.to(...)`，选择权就该归他 —— 否则会出现
+ * `2 m to cm` 被改成 `2 m` 这种**把用户的换算悄悄撤回**的回归。
+ * 数字仍然合法（`2 m` 是个正经长度），所以这类错误不会被怀疑。
+ *
+ * @param node - 已解析的 AST；解析失败时调用方本来就走不到这里
+ * @returns 有显式目标单位时为 true
+ */
+function usesExplicitUnitConversion(node) {
+    let found = false;
+    if (!node || typeof node !== 'object')
+        return false;
+    const visit = (current, depth) => {
+        if (found || !current || typeof current !== 'object' || depth > 64)
+            return;
+        if (current.type === 'OperatorNode' && String(current.op ?? '') === 'to') {
+            found = true;
+            return;
+        }
+        if (current.type === 'FunctionNode') {
+            if (String(current.fn?.name ?? '') === 'to') {
+                found = true;
+                return;
+            }
+            /** `.to('kW')` 的 fn 是 AccessorNode，属性名挂在 index 上。 */
+            const indexNode = current.fn?.index;
+            const property = typeof indexNode?.value === 'string' ? indexNode.value : indexNode?.name;
+            if (typeof property === 'string' && property.replace(/^["']|["']$/g, '') === 'to') {
+                found = true;
+                return;
+            }
+        }
+        for (const key of ['args', 'items']) {
+            const list = current[key];
+            if (Array.isArray(list))
+                for (const child of list)
+                    visit(child, depth + 1);
+        }
+        for (const key of ['content', 'object', 'index', 'value']) {
+            if (current[key])
+                visit(current[key], depth + 1);
+        }
+    };
+    visit(node, 0);
+    return found;
+}
 function guardComplexity(node) {
     if (!node || typeof node.traverse !== 'function')
         return;
@@ -261,17 +693,124 @@ function guardComplexity(node) {
 // 输入处理
 // ────────────────────────────────────────────────────────────────────────────
 /** 把 variables 字典转成 mathjs 可用的 scope。 */
+/**
+ * 是否把工作区里登记的命名变量并入作用域。
+ *
+ * ## 这是显式开关，默认关闭
+ *
+ * 打开后同一个调用在不同工作区状态下会给出不同结果 ——
+ * 那会削弱「同输入同输出」。所以：
+ *   · 默认关闭，**不改变任何现有调用的行为**
+ *   · 要开就在工作区里固化：`{action2:"set", useWorkspaceVariables:true}`
+ *
+ * 关掉后 `workspaceVariables` 里存的东西仍然存着（能 show、能 remove），
+ * 只是不参与计算 —— 与旧版行为完全一致。
+ *
+ * @param name - 工作区名；省略用当前工作区
+ * @returns 是否启用
+ */
+function useWorkspaceVariables(name) {
+    try {
+        const data = loadWorkspace(name ?? activeWorkspaceNameForCache());
+        return data.useWorkspaceVariables === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 把工作区变量与本次传入的变量合成最终作用域输入。
+ *
+ * ## 优先级：本次参数 > 工作区
+ *
+ * 临时覆盖长期，符合「显式优先」。同名的键以本次传入为准 ——
+ * 这样「临时想换个值算一下」不必先去改工作区。
+ *
+ * ## 两个来源都要规范化
+ *
+ * `buildScope` 会校验变量名与取值，所以这里不能只做浅合并：
+ * 否则工作区里存了非法名字（历史上可能写进去过），
+ * 会绕过校验直接进 mathjs 作用域。
+ *
+ * @param passed - 本次调用传的 `variables` 参数
+ * @returns 合并后的变量字典；开关关闭时原样返回 passed
+ */
+function mergeWorkspaceVariables(passed) {
+    if (!useWorkspaceVariables())
+        return passed;
+    const stored = workspaceVariablesOf();
+    const incoming = passed && typeof passed === 'object' && !Array.isArray(passed)
+        ? passed
+        : {};
+    if (Object.keys(stored).length === 0 && Object.keys(incoming).length === 0)
+        return passed;
+    return { ...stored, ...incoming };
+}
+/**
+ * 收集上一次 `buildScope` 跳过的非法变量键。
+ *
+ * 模块级、每次调用开头清空 —— 与 `activeDisplayPrecision` 同样的理由：
+ * 逐层传参要改四十多个函数签名，而这个信息只在**入口**用来组装一条提示。
+ */
+let skippedVariableKeys = [];
+/**
+ * 取本次调用中被跳过的非法变量键（组装提示用）。
+ *
+ * @returns 被跳过的键与原因
+ */
+export function takeSkippedVariableKeys() {
+    const taken = skippedVariableKeys;
+    skippedVariableKeys = [];
+    return taken;
+}
+/**
+ * 清理被跳过的变量键记录（每次工具调用开头）。
+ */
+export function resetSkippedVariableKeys() {
+    skippedVariableKeys = [];
+}
+/**
+ * 把变量字典装进 mathjs 作用域。
+ *
+ * ## 非法键只跳过，不中止整批
+ *
+ * 实测反馈（2026-11-06 第二份）：
+ *
+ * ```
+ *   expressions: ["P*330", "Q+1"], variables: {"P":1000, "Q":5, "人口":1}
+ *   → ok:false，连合法的 P*330 都没算
+ * ```
+ *
+ * 一个键名写错，前面排队的算式全白写的 —— 而这类语料的**概念名几乎全是中文**
+ * （人口/粮食/石料），用户第一反应就是用中文命名。
+ *
+ * 现在：合法的键照常进作用域，非法的记进 `skippedVariableKeys`，
+ * 由入口在结果里列出来。**算出来的数仍然是对的** —— 只是那个中文键没生效。
+ *
+ * ## 为什么不做「支持中文变量名」
+ *
+ * 那要放宽 mathjs 的词法，而词法宽松会带来新的歧义
+ * （中文字符与单位名、量级词的边界更难判）。
+ * 相比之下「跳过 + 明确告知」既解决了痛点，又不引入不确定性。
+ *
+ * @param engine - mathjs 实例
+ * @param variables - 变量字典
+ * @returns 可用的作用域对象
+ */
 function buildScope(engine, variables) {
     const scope = {};
     if (!variables || typeof variables !== 'object' || Array.isArray(variables))
         return scope;
     for (const [key, raw] of Object.entries(variables)) {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-            throw new CalcError('invalid_argument', `变量名 "${key}" 不合法`, '变量名只能含字母、数字、下划线。');
+            skippedVariableKeys.push({ name: key, reason: '标识符只能含字母、数字、下划线' });
+            continue;
         }
         if (typeof raw === 'number') {
-            if (!Number.isFinite(raw))
-                throw new CalcError('invalid_argument', `变量 "${key}" 不是有限数字`);
+            if (!Number.isFinite(raw)) {
+                skippedVariableKeys.push({ name: key, reason: '不是有限数字' });
+                continue;
+            }
             scope[key] = engine.bignumber(String(raw));
         }
         else if (typeof raw === 'string') {
@@ -280,14 +819,14 @@ function buildScope(engine, variables) {
                 scope[key] = engine.bignumber(raw.trim());
             }
             catch {
-                throw new CalcError('invalid_argument', `变量 "${key}" 无法解析为数字: ${raw}`);
+                skippedVariableKeys.push({ name: key, reason: '无法解析为数字' });
             }
         }
         else if (typeof raw === 'boolean') {
             scope[key] = raw;
         }
         else {
-            throw new CalcError('invalid_argument', `变量 "${key}" 必须是数字或数字字符串`);
+            skippedVariableKeys.push({ name: key, reason: '必须是数字或数字字符串' });
         }
     }
     return scope;
@@ -335,6 +874,24 @@ function opEvaluate(engine, expression, scope, precision) {
     if (expression === '') {
         throw new CalcError('invalid_argument', '表达式为空');
     }
+    /**
+     * 数学记号归一化（`**` → `^`、`π` → `pi`、`ln(` → `log(`、`×`/`÷`）。
+     *
+     * 为什么必须在这里：其它 op（derivative / integral / stats / solve…）
+     * 都在内部调了 `normalizeSource`，**只有 evaluate 漏了** ——
+     * 于是 `2**10`、`π`、`2 × 3` 这些直觉写法在 evaluate 上全部报错，
+     * 而同一套写法在 formula 的 overrides 里却能过（实测反馈的语法糖问题）。
+     *
+     * 幂等：这些替换重复执行结果不变，所以不会因多次归一化而出错。
+     */
+    expression = normalizeSource(expression);
+    /**
+     * 中文单位展开：把「1 里 + 3 米」变成 mathjs 能算的形态。
+     *
+     * 必须放在 normalizeSource **之后**：前者处理数学记号（× ÷ π **），
+     * 后者处理单位名；顺序反了会让 `2 × 3 里` 这类混合写法漏掉。
+     */
+    expression = normalizeChineseUnits(expression);
     if (expression.length > MAX_INPUT_LENGTH) {
         throw new CalcError('too_large', `表达式过长（${expression.length} > ${MAX_INPUT_LENGTH}）`);
     }
@@ -343,10 +900,12 @@ function opEvaluate(engine, expression, scope, precision) {
         node = engine.parse(expression);
     }
     catch (error) {
-        throw translateError(error, 'syntax');
+        throw translateError(error, 'syntax', expression);
     }
     guardAst(node);
     guardComplexity(node);
+    // 拦「未定义单字母被当单位」的静默错误（实测反馈 P0-2）
+    guardBareUnitSymbols(node, scope);
     let raw;
     try {
         raw = node.evaluate(scope);
@@ -355,8 +914,49 @@ function opEvaluate(engine, expression, scope, precision) {
         throw translateError(error);
     }
     const value = unwrapResult(raw);
+    /**
+     * ## 非有限值必须在**这里**拦，不能指望顶层
+     *
+     * 顶层的 `containsNonFinite(result.value)` 拿到的是**序列化后**的值：
+     * 带单位的结果被压成字符串 `"Infinity g"`，而那个判据只认恰好 `"Infinity"`。
+     * 于是：
+     *
+     * ```
+     *   1/0          →  错误[non_finite]      ✓ 拦住
+     *   (1/0)*2 kg   →  ok=true, "Infinity g"  ✗ 放过
+     * ```
+     *
+     * 而后者更危险：它看起来**像个带单位的正经结果**（`Infinity g` 读起来
+     * 像「无穷克」，不像「算错了」），而且会顺着链式推演传下去。
+     *
+     * 所以判在原始对象上 —— `isNonFiniteValue` 会下钻到 `Unit.value`。
+     * 注意 `1e400`、`2^1024` 这类**有限的极大数**不能误判：
+     * 它们转成双精度才溢出，而 BigNumber 自己知道自己是有限的。
+     */
+    if (isNonFiniteValue(value)) {
+        const shown = String(raw);
+        throw new CalcError('non_finite', `计算结果非有限（${shown}）`, '常见于除以零、tan(π/2)、log(0)。若要符号形式可改用 operation="simplify"。');
+    }
+    /**
+     * 表达式里写了目标单位（`.to('cm')`、`5 cm to inch`）时，**不归位**。
+     *
+     * 归位的职责是「调用方没指定时挑一个顺口的档」；指定了就不该被改写。
+     * 详见 `formatValue` 的 `respectExplicitUnit` 参数说明 —— 那里记着
+     * `2 m to cm` 被改回 `2 m` 这条回归。
+     */
+    const explicitUnit = usesExplicitUnitConversion(node);
+    const text = formatValue(engine, value, precision, currentDisplayPrecision(), explicitUnit);
     return {
-        result: formatValue(engine, value, precision, currentDisplayPrecision()),
+        /**
+         * 带 SI 质量前缀时补一句中文量级参照（如 `87.78 Tg（= 8778 万吨）`）。
+         *
+         * 只对「质量 × 克」这一族生效 —— 它是中文语料里量级混用最严重的场景，
+         * 也是实测反馈里唯一真实出过事故的地方（两次把「吨」当成「亿吨」）。
+         *
+         * 其它单位、复合单位一律原样返回：量级词在那个位置不适用，
+         * 硬套只会制造噪音。
+         */
+        result: annotateMetricPrefix(text),
         value: toJsonValue(value),
     };
 }
@@ -382,48 +982,280 @@ function opEvaluate(engine, expression, scope, precision) {
  * @param precision - 计算精度
  * @returns 结果文本与结构化值
  */
-function opEvaluateBatch(engine, expressions, scope, precision) {
+function opEvaluateBatch(engine, expressions, scope, precision, terse = false) {
     const items = expressions.slice(0, MAX_BATCH_EXPRESSIONS);
     if (items.length === 0) {
         throw new CalcError('invalid_argument', 'expressions 为空', '例如 ["1/7","2^0.5"]');
     }
     const shown = [];
     const values = [];
+    /** 量级类提示（不影响成败，只提醒核对）。 */
+    const magnitudeWarnings = [];
     let successCount = 0;
     let failCount = 0;
     for (const raw of items) {
-        const expression = typeof raw === 'string' ? raw.trim() : String(raw ?? '');
-        if (expression === '') {
-            values.push({ expression, ok: false, error: 'empty' });
+        /**
+         * 两种条目形态：
+         *   字符串 `"1/7"`
+         *   带标签对象 `{label:"储耗比-中值", expr:"139e8/152e4"}`
+         *
+         * ## 为什么要 label
+         *
+         * 实测反馈：同一批算两个口径（`["139e8/1743500","139e8/152e4"]` → 7972 / 9144），
+         * 输出里**只有顺序号区分**。后续引用时得回翻表达式原文，
+         * 报告里「一次差点引错」。
+         *
+         * 批内条目一多（该会话单批最多 14 条），纯靠位置对齐的心智负担很大。
+         */
+        /**
+         * ## 纯数字元素自动转成表达式
+         *
+         * 实测反馈（2026-11-06 第二份）：`expressions: [0.5, 9.9, 10]` 五条全被当成
+         * **「空表达式」跳过**，汇总「成功 0，失败 5」。
+         *
+         * 这是**类型错误被伪装成内容错误** —— 用户传的是合法数字，
+         * 工具说「空表达式」，会让人去翻数据源而不是检查类型。
+         *
+         * 转成字符串是零风险的：`0.5` → `"0.5"` → 正常求值得 0.5。
+         * 布尔与 null 不转换（那不是「一个数」，是调用方写错了，该报错）。
+         */
+        const entry = typeof raw === 'string'
+            ? { expr: raw }
+            : typeof raw === 'number' && Number.isFinite(raw)
+                ? { expr: String(raw) }
+                : raw ?? {};
+        /**
+         * ## 元素里的未知键也要点名
+         *
+         * 顶层的未知参数有 `findUnknownArguments` 拦着，但**数组元素内部没查**。
+         * 实测（2026-11-06）：
+         *
+         * ```
+         *   {expressions:[{label:'a', expr:'1+1', unit:'kg/day'}]}  → ok=true，unit 被静默丢弃
+         *   {expression:'1+1', unit:'kg/day'}                       → 报 unknown_argument ✓
+         * ```
+         *
+         * 危险在于：将来若要加 `unit` / `assumption` 这类**按条**的参数，
+         * 它们必然写在这个位置 —— 而现有行为会让它们**静默不生效**，
+         * 调用方以为生效了。这正是本项目一直在打击的那类问题。
+         *
+         * 处理方式：认不出的键当作**该条失败**（而不是整批失败），
+         * 这样一条写错不影响其余条目 —— 与「逐条独立报错」的既有约定一致。
+         */
+        /** 元素级允许的键。新增一条按条参数时记得加在这里，否则会被自己的校验拦下。 */
+        const allowedEntryKeys = ['label', 'expr', 'sanity'];
+        const unknownEntryKeys = typeof raw === 'string'
+            ? []
+            : Object.keys(raw).filter(function (k) { return !allowedEntryKeys.includes(k); });
+        if (unknownEntryKeys.length > 0) {
+            const echoName = entry.label || String(entry.expr ?? '');
+            values.push({ expression: '', label: String(echoName), ok: false, error: 'unknown_argument' });
+            shown.push('  ' + echoName + ' → 失败[unknown_argument]：这一条里有认不出的键 ' +
+                unknownEntryKeys.join('、') + '（只接受 ' + allowedEntryKeys.join(' / ') + '）');
+            failCount++;
+            continue;
+        }
+        const label = typeof entry.label === 'string' ? entry.label.trim() : '';
+        const rawExpression = String(entry.expr ?? '').trim();
+        if (rawExpression === '') {
+            values.push({ expression: rawExpression, label, ok: false, error: 'empty' });
             shown.push('  （空表达式）→ 跳过');
             failCount++;
             continue;
         }
+        /**
+         * 归一化只用于**计算**，回显仍用用户原文。
+         *
+         * 否则用户写 `π`、`2**10` 会看到自己被回显成 `pi`、`2^10` ——
+         * 那会让人怀疑「我传的到底被改成了什么」。
+         */
+        const expression = normalizeChineseUnits(normalizeSource(rawExpression));
         try {
-            const node = engine.parse(expression);
+            /**
+             * 解析单独包一层：给 `translateError` 传 `'syntax'` 作为兜底类型。
+             *
+             * 为什么：单条求值里写的是 `translateError(error, 'syntax')`，
+             * 而批量这里原来是 `translateError(error)` —— 默认兜底是 `internal`。
+             * 于是 `不存在xyz(1)` 在单条里报 syntax、在批量里报 internal。
+             * `internal` 的含义是「工具自己坏了」，会误导人去重试同一个错，必须对齐。
+             */
+            let node;
+            try {
+                node = engine.parse(expression);
+            }
+            catch (error) {
+                throw translateError(error, 'syntax', expression);
+            }
             guardAst(node);
             guardComplexity(node);
+            // 拦「未定义单字母被当单位」的静默错误（实测反馈 P0-2）
+            guardBareUnitSymbols(node, scope);
             const value = unwrapResult(node.evaluate(scope));
-            const text = formatValue(engine, value, precision, currentDisplayPrecision());
-            values.push({ expression, ok: true, result: text });
-            shown.push('  ' + expression + ' = ' + text);
+            /**
+             * ## 批量也必须拦非有限值
+             *
+             * 实测（1107 报告问题 2、3）：单条 `1/0` 报错，批量却宣告
+             * 「算式全部求值成功（4 条）」，其中就包括 `1/0` 与 `log(0)`。
+             *
+             * 这构成一条危险的对称破坏：**同一个式子，换个调用方式就从「错」
+             * 变成「对」**。而批量恰恰是 AI 最常用的形态（一次算 8—14 条），
+             * 于是最该拦住的地方恰好不拦。
+             *
+             * 归入 `failed` 而不是单独一类，理由是与单条 `non_finite` 对齐：
+             * 调用方的分流逻辑只需要认 `ok/partial/failed` 三个字段。
+             */
+            if (isNonFiniteValue(value)) {
+                throw new CalcError('non_finite', `计算结果非有限（${String(value)}）`, '常见于除以零、tan(π/2)、log(0)。若要符号形式可改用 operation="simplify"。');
+            }
+            /** 批量同样要尊重显式目标单位（见 `usesExplicitUnitConversion`）。 */
+            const text = formatValue(engine, value, precision, currentDisplayPrecision(), usesExplicitUnitConversion(node));
+            values.push({ expression, label: label || undefined, ok: true, result: text });
+            /**
+             * 回显格式：有 label 用 label，否则用用户原文。
+             *
+             * 回显原文（`π` 而不是 `pi`）是刻意的 —— 否则用户会怀疑「我传的到底被改成了什么」。
+             */
+            const echo = label ? label : rawExpression;
+            /**
+             * 量级标注：给裸数字配上「这是 10 的几次方」。
+             *
+             * 实测复盘里最贵的一次错误是：`/1e9` 算出 2133 却贴上「万吨」标签，
+             * 据此指控原文「错了 10 倍」。返回体当时只有一行裸数字，看不出量级。
+             * 标上 `(~10³)` 之后，「2133 与万吨差一个量级」这件事人眼即可发现。
+             */
+            /**
+             * 量级标注：给裸数字配上「这是 10 的几次方」。
+             *
+             * 实测复盘里最贵的一次错误是：`/1e9` 算出 2133 却贴上「万吨」标签，
+             * 据此指控原文「错了 10 倍」。返回体当时只有一行裸数字，看不出量级。
+             *
+             * ## 带单位的结果另走一条
+             *
+             * `annotateMagnitude` 内部做 `Number(text)`，而 `87.78 Mt` 会得到 NaN ——
+             * 带单位时它静默失效。所以这里按结果形态分派：
+             * 纯数字走 `(~10^N)`，带单位走 `explainUnitResult`（给出基准值与中文量级）。
+             */
+            const shownValue = annotateMagnitude(text);
+            const unitExplain = explainUnitResult(text);
+            shown.push('  ' + echo + (label ? '（' + rawExpression + '）' : '') + ' = ' + shownValue +
+                (unitExplain ? '｜' + unitExplain : ''));
+            /**
+             * label 与结果的量级核对：只有 label 里**明确写了量级词**（万/亿/千…）才查，
+             * 且结果本身已跨过那个量级时才提示 —— 宁漏勿误。
+             */
+            if (label) {
+                const warn = checkLabelMagnitude(label, text);
+                if (warn)
+                    magnitudeWarnings.push(warn);
+            }
+            /**
+             * ③ 锚点比对：调用方给了 `sanity` 就拿它的判据去比。
+             *
+             * 三条来源共用同一个 `magnitudeWarnings` 通道 —— 它的下游
+             * （terse 分支、汇总行、结构化计数）全部自动生效，不必改三处。
+             *
+             * 为什么在这里而不是在缓存层：批量路径**根本不走缓存**（见上方注释），
+             * 所以不存在「换锚点却命中旧提示」的问题。
+             */
+            if (typeof entry === 'object' && entry !== null) {
+                const sanity = entry.sanity;
+                const anchorWarn = checkAnchors(sanity, text);
+                if (anchorWarn) {
+                    const anchorEcho = label || rawExpression;
+                    magnitudeWarnings.push(anchorEcho + ' → ' + anchorWarn);
+                }
+            }
             successCount++;
         }
         catch (error) {
             const translated = translateError(error);
-            values.push({ expression, ok: false, error: translated.type });
+            values.push({ expression, label: label || undefined, ok: false, error: translated.type });
             // 失败要显眼，但不能长篇大论 —— 一行说清哪条、什么类型
-            shown.push('  ' + expression + ' → 失败[' + translated.type + ']' +
+            const echo = label ? label : rawExpression;
+            shown.push('  ' + echo + ' → 失败[' + translated.type + ']' +
                 (translated.hint ? '：' + translated.hint : ''));
             failCount++;
         }
     }
+    /**
+     * `terse` 模式：只回「表达式 = 结果」，去掉标题与统计。
+     *
+     * 实测反馈：批量 8—14 条时，标题与统计行本身也是固定开销；
+     * 报告估算「若全程 terse，省 40%+ 工具输出 token」。
+     *
+     * 但**失败信息不能省**：省掉失败行会让调用方以为「全成功了」。
+     */
+    if (terse) {
+        /**
+         * terse 的承诺是「省掉标题与统计」，**不是**省掉风险提示。
+         *
+         * 踩过：第一版把 ⚠ 量级提示一起省了，于是 terse 用户看到的是一行干净数字，
+         * 而干净正是最危险的 —— 他会以为没问题。
+         */
+        const terseWarnings = [];
+        const terseBatch = findBatchAnomalies(values
+            .filter(function (v) { return v.ok && typeof v.result === 'string'; })
+            .map(function (v) { return { label: v.label, result: String(v.result) }; }));
+        if (terseBatch)
+            magnitudeWarnings.push(terseBatch);
+        if (magnitudeWarnings.length > 0) {
+            terseWarnings.push('');
+            for (const warning of magnitudeWarnings)
+                terseWarnings.push(warning);
+        }
+        return {
+            result: [...shown.map((s) => s.trim()), ...terseWarnings].join('\n'),
+            value: toJsonValue({
+                count: items.length,
+                success: successCount,
+                failed: failCount,
+                magnitudeWarnings: magnitudeWarnings.length,
+                items: values,
+            }),
+        };
+    }
     const header = items.length < expressions.length
         ? `═══ 批量求值（前 ${items.length} 条，共给了 ${expressions.length} 条）═══`
         : `═══ 批量求值（${items.length} 条）═══`;
+    /**
+     * 同批次量级一致性比对。
+     *
+     * 真实案例：四条「年耗/年产（万吨）」全部用了 /1e9（实际是千吨），
+     * 全部偏大 10 倍、全部报「成功」。单条看不出问题，四条一起就该看出来。
+     */
+    const batchWarning = findBatchAnomalies(values
+        .filter(function (v) { return v.ok && typeof v.result === 'string'; })
+        .map(function (v) { return { label: v.label, result: String(v.result) }; }));
+    if (batchWarning)
+        magnitudeWarnings.push(batchWarning);
+    /**
+     * 分级语义：把「算式没塌」与「结论已验证」分开。
+     *
+     * 实测反馈原话：「成功 7，失败 0」会让调用方跳过复核 ——
+     * 因为「成功」两个字读起来像「对了」。这里显式说明它只表示什么。
+     */
+    const summary = [];
+    if (failCount === 0) {
+        summary.push('算式全部求值成功（' + successCount + ' 条，只表示算式无语法/符号错，不含结论正确性判断）');
+    }
+    else {
+        summary.push('成功 ' + successCount + '，失败 ' + failCount);
+    }
+    if (magnitudeWarnings.length > 0) {
+        summary.push('');
+        summary.push('⚠ 量级待核（' + magnitudeWarnings.length + ' 条）：');
+        for (const warning of magnitudeWarnings)
+            summary.push(warning);
+    }
     return {
-        result: [header, '', ...shown, '', `成功 ${successCount}，失败 ${failCount}`].join('\n'),
-        value: toJsonValue({ count: items.length, success: successCount, failed: failCount, items: values }),
+        result: [header, '', ...shown, '', ...summary].join('\n'),
+        value: toJsonValue({
+            count: items.length,
+            success: successCount,
+            failed: failCount,
+            magnitudeWarnings: magnitudeWarnings.length,
+            items: values,
+        }),
     };
 }
 function opDerivative(expression, variable, precision) {
@@ -454,11 +1286,68 @@ function opDerivative(expression, variable, precision) {
     }
     return { result: symbolic, value: symbolic };
 }
-function opIntegral(expression, variable, precision) {
+function opIntegral(expression, variable, precision, from, to) {
     const text = normalizeSource(expression);
     if (text === '')
         throw new CalcError('invalid_argument', '表达式为空');
+    // 只给一端是含糊的输入：要么两端都给，要么都不给
+    if ((from === undefined) !== (to === undefined)) {
+        throw new CalcError('invalid_argument', '定积分需要同时给 from 与 to', '需要同时给两端（如 from=0, to=3）；只给一端无法确定积分区间。');
+    }
     const primitive = symbolicIntegral(text, variable);
+    /**
+     * ── 给了上下限：算定积分 ──
+     *
+     * 实测反馈（P1-3）：以前传 `from`/`to` 会被**静默忽略**，
+     * 只返回不定积分 `1/3*x^3 + C` —— 调用者以为拿到了定积分。
+     * 文档的原话：「绝不要静默忽略已传入的参数，这是最伤信任的行为。」
+     *
+     * 现在按 Newton-Leibniz 算 F(to) − F(from)。
+     */
+    if (from !== undefined && to !== undefined) {
+        const engine = bignum(precision);
+        /**
+         * 用**有理数引擎**代入，而不是 BigNumber。
+         *
+         * 实测对比（原函数 1/3·x³ 在 x=3 处）：
+         *   BigNumber → 8.99999999999999999999999999999999999999…
+         *   Fraction  → 9
+         *
+         * BigNumber 的 `1/3` 是截断小数，乘 27 回不到整数。
+         * 定积分出现的多半是有理系数多项式，Fraction 能约分回精确值。
+         */
+        const rationalEngine = rational();
+        let exact;
+        try {
+            const F = rationalEngine.parse(primitive);
+            const upper = F.evaluate({ [variable]: to });
+            const lower = F.evaluate({ [variable]: from });
+            exact = rationalEngine.subtract(upper, lower);
+        }
+        catch (error) {
+            throw new CalcError('unsupported', '原函数 ' + primitive + ' 无法代入上下限求值', '这是符号引擎的能力边界。可改用 operation="evaluate" 自己做数值积分（如黎曼和）。');
+        }
+        /**
+         * 显示：优先精确形式（整数或分数），并给出 BigNumber 小数近似。
+         *
+         * 为什么两个都给：`1/3` 这种系数在定积分里很常见，
+         * 化为 `6.75` 会丢「精确等于 27/4」这个信息；而工程场景又常需要小数。
+         */
+        const exactTextRaw = rationalEngine.format(exact);
+        // 分母为 1 时不该写成 `9/1`（mathjs 的 ratio 格式会保留 /1）
+        const exactText = exactTextRaw.replace(/\/1$/, '');
+        const asNumber = Number(rationalEngine.number(exact));
+        const decimalText = Number.isFinite(asNumber)
+            ? formatValue(engine, engine.bignumber(String(asNumber)), precision, currentDisplayPrecision())
+            : exactText;
+        const isFraction = exactText.includes('/');
+        return {
+            result: '原函数：' + primitive + ' + C\n' +
+                '定积分 ∫[' + from + '→' + to + '] ' + text + ' d' + variable + ' = ' +
+                exactText + (isFraction ? '（= ' + decimalText + '）' : ''),
+            value: toJsonValue(exactText),
+        };
+    }
     return { result: `${primitive} + C`, value: primitive };
 }
 function opSimplify(expression) {
@@ -1302,6 +2191,16 @@ function opFormula(args, engine, precision) {
         const required = Object.entries(formula.params).map(([name, spec]) => `${name}: ${spec.desc}`);
         throw new CalcError('missing_params', `公式 "${formula.name}" 缺少参数: ${resolved.missing.join(', ')}`, `完整参数表 —— ${required.join('；')}。用 overrides 传入，例如 {"${resolved.missing[0]}": 100}。`);
     }
+    /**
+     * ── 未知参数名：明确告知，不静默丢弃 ──
+     *
+     * 实测反馈：overrides 的 key 拼错时公式**照常出数**，只是那个参数用了默认值。
+     * 报告里那次「236 倍缺口」误判就是这么来的 —— 而结果看着完全正常。
+     *
+     * 这里不抛错（可能是调用方故意传常数名，或用法上无伤），
+     * 而是把「你没生效的参数」写成一条提示，让调用方能自己判断。
+     */
+    const unknownOverrideKeys = resolved.unknownKeys ?? [];
     const expression = resolveExpression(formula, args.customExpression);
     const scope = buildFormulaScope(engine, resolved.values);
     // 走 JS 实现的公式（数组逐元素运算这类 mathjs 表达不好的）
@@ -1340,7 +2239,7 @@ function opFormula(args, engine, precision) {
         node = engine.parse(expression);
     }
     catch (error) {
-        throw translateError(error, 'syntax');
+        throw translateError(error, 'syntax', expression);
     }
     guardAst(node);
     guardComplexity(node);
@@ -1353,6 +2252,19 @@ function opFormula(args, engine, precision) {
     }
     const parts = [describeFormula(formula, expression, resolved.values, resolved.overridden)];
     parts.push(`结果: ${formatValue(engine, raw, precision, currentDisplayPrecision())}${formula.unit ? ` ${formula.unit}` : ''}`);
+    /**
+     * 未知参数名提示：把「你没生效的 key」明确说出来。
+     *
+     * 紧跟在结果后面（而不是压到输出末尾），因为这类问题会直接改变结论，
+     * 读者必须第一眼就看到。
+     */
+    if (unknownOverrideKeys.length > 0) {
+        parts.push('');
+        parts.push('⚠ 以下 overrides 的 key 不在公式「' + formula.name + '」的参数里，**已被忽略**：' +
+            unknownOverrideKeys.join('、') +
+            '。该公式的参数是：' + Object.keys(formula.params).join('、') +
+            '。若这是拼写笔误，结果可能已偏离——请核对后重算。');
+    }
     /**
      * 经验公式的适用性提示。
      *
@@ -1555,122 +2467,6 @@ function opFormulas(args) {
     }
     return { result: lines.join('\n'), value: { query, matches: matches.map((m) => m.id) } };
 }
-/** 能力清单。 */
-/** 能力清单。 */
-function opHelp() {
-    return {
-        result: [
-            '══════ math_execute 完整能力清单 ══════',
-            '',
-            '【求值与代数】',
-            '  evaluate      任意 mathjs 表达式；BigNumber 64 位精度',
-            '                例：10^20+5、factorial(50)、(1+2i)*(3-i)、5 cm to inch、sin(30 deg)',
-            '                批量：给 expressions=["1/7","2^0.5","log(10)"] 一次算多条，',
-            '                      逐条独立报错；比多次调用省往返',
-            '  solve         解方程。多方程逗号分隔 = 方程组',
-            '                例：3x + 2y = 10, x - y = 1  /  x^2 - 5x + 6 = 0',
-            '  system        显式线性系统（matrix + vector）',
-            '  derivative    符号求导（order 可指定高阶）',
-            '  integral      符号不定积分',
-            '  simplify      符号化简',
-            '  expand        符号展开',
-            '  roots         多项式求根（含复数根）',
-            '',
-            '【扩展函数】（可直接写在表达式里）',
-            '  rank(A)       矩阵的秩；nullspace(A) 零空间基；svd(A) 奇异值',
-            '  factorize(n)  整数质因数分解',
-            '  nsolve("表达式", 初值)  数值求根（牛顿法 + 二分兜底）',
-            '',
-            '【线性代数】',
-            '  matrix        矩阵乘法/求逆/行列式/转置/迹；只给 matrix 时输出完整画像',
-            '                （秩/行列式/迹/奇异值/零空间/逆）',
-            '  eigen         特征值与特征向量',
-            '',
-            '【统计与概率】',
-            '  stats         描述统计（均值/中位数/众数/方差/标准差/分位数/偏度/峰度）',
-            '  dist          概率分布：normal/binomial/poisson/exponential/chisquare/t/normalinv',
-            '  regression    线性与多项式回归（含 R²）',
-            '',
-            '【微分方程】',
-            '  ode           数值求解 ODE（RK4）：一阶方程组（SIR/捕食模型）、二阶方程自动降阶',
-            '                返回轨迹、终点值、极值、发散警告',
-            '',
-            '【公式库】',
-            '  formula       调用已收录的 ' + FORMULAS.length + ' 条自然科学公式',
-            '                例：formula="escape_velocity", overrides={M,r}',
-            '                任何参数可覆盖 —— 架空世界改造的关键',
-            '  formulas      检索与分类：',
-            '                query="关键词"       按名称/关键词',
-            '                query="layer:derived"  按规则层级（fundamental=基本规则、mathematical=数学基础（与基本同级）、derived/phenomenological/engineering/conventional）',
-            '                query="domain:物理"    按学科领域（多标签）',
-            '                query="freq:high"      按主角感知频率',
-            '                query="symbol:m"       按符号含义',
-            '  formula-table 两级扩展：工作区临时公式（覆盖/自定义/停用）+ 全局公式包',
-            '                （tableAction: global-list / global-add / global-remove）',
-            '                字段与校验规则见 docs/formula-authoring.md',
-            '',
-            '【世界观推演】',
-            '  world         输入星球参数 → 体感画像：重力/昼夜/季节/纬度气候/地形上限 +',
-            '                天空配色/恒星结构与寿命/卫星系统/化学窗口/生命闸门/跨模块一致性检查',
-            '                【world 完整字段表】（全部可选，默认地球）',
-            '                  恒星：starMass(太阳质量)、starRadius(太阳半径)、starTemp(K,默认5778)',
-            '                  轨道：orbitAU(AU,默认1)、eccentricity(默认0.0167)',
-            '                  行星：planetMass(地球质量)、planetRadius(地球半径)、rotationHours(默认23.93)、',
-            '                        obliquityDeg(默认23.44)、albedo(默认0.306)',
-            '                  大气：pressure(Pa,默认101325)、molarMass(kg/mol,默认0.02896)、',
-            '                        gamma(默认1.4)、greenhouse(增温K,默认33)',
-            '                  地表：materialStrength(Pa,默认1.3e8花岗岩)、materialDensity(默认2700)',
-            '                  地形 terrain（附带）：kind=coastal/plain/plateau/mountain/valley/desert/',
-            '                        forest/tundra/island/lake；elevation(海拔m)、distanceToSea(km)、',
-            '                        latitudeDeg、annualPrecipMm、humidity(0-1)、windward(1迎风/-1背风)、',
-            '                        reliefHeight(m)、oceanCurrent=warm/cold/none、',
-            '                        surface=soil/sand/rock/ice/water/vegetation',
-            '  constants     改变物理常数，自动推导派生量并评估世界偏离度',
-            '                【可改的基础旋钮】c(光速) / G(引力常数) / h(普朗克) / kB(玻尔兹曼) /',
-            '                  e_charge(元电荷) / me(电子质量) / mp(质子质量) / NA(阿伏伽德罗) /',
-            '                  epsilon0(真空介电常数)',
-            '                【派生量，自动跟随，不能直接改】hbar / R / mu0 / kCoulomb / sigma /',
-            '                  bWien / alpha_fs / Ry / muB',
-            '                例：{c:1.5e8} → mu0/sigma/alpha_fs 等自动重算并评估偏离度',
-            '  quantities    看哪些物理量该跟着常数变、哪些不该（量纲分析 + 缩放指数）',
-            '  impact        改常数后跑全部公式并与现实对比，算每条偏差',
-            '  units         单位换算：把「三里」「两丈」「五百斤」换成标准单位',
-            '                不带单位参数 → 列出全部可用单位（含中文古制与天文单位）',
-            '                例：unitValue=30, unitFrom="里", unitTo="km" → 15 km',
-            '                自创单位用 customUnits 覆盖（如把「里」定成 576 m）',
-            '  balance       收支盘点：粮/水/能/地/财政/军费/信息 多项一起看，给最短板',
-            '                例：balance={grain:{demand:2.7e6,supply:3.1e6,unit:"kg/年"}}',
-            '                回答「这个王国养不养得起二十万兵」这类问题（feasibility 只管单项上限）',
-            '  bodies        天体目录：太阳系 8 大行星 + 卫星 + 代表性系外行星 + 各亮度级恒星',
-            '                例：bodyName="mars" / bodyKind="moon" / 不带参数列全部',
-            '                bodyConstant="alpha_fs", bodyFactor=2 → 看改常数后哪些天体数据要重算',
-            '                （关键：行星质量/半径/轨道与 α 无关，绝不跟着改）',
-            '',
-            '【数据管理】',
-            '  workspace     工作区管理（一个世界观 = 一套常数表 + 公式表 + 地点 + 变量）',
-            '                action2: list/show/create/switch/save/set/add-terrain/delete/reset',
-            '                stats/cleanup 可查看存储与清理；不同工作区完全隔离',
-            '                注意：本插件没有图形界面（2026-10-25 已移除），全部经工具与 HTTP 路由操作',
-            '',
-            '【其他】',
-            '  help          本清单',
-            '  prompt-mode   调整系统提示注入档位（off/brief/full）',
-            '',
-            '【常用参数】',
-            '  expression    表达式/方程（多方程用逗号）',
-            '  variables     变量字典，如 {"m":500,"v":30}',
-            '  operation     上面的值；不填=auto',
-            '  precision     有效数字位数，默认 64，范围 1-256',
-            '  variable      求导/求根的自变量，默认 x',
-            '  overrides     公式参数覆盖',
-            '  constants     要改的物理常数',
-            '  world         星球参数',
-            '  terrain       局部地形参数',
-            '',
-            '【失败时】返回 ok=false + error.type/message/hint，按 hint 修正即可，不会崩溃。',
-        ].join('\n'),
-    };
-}
 // ────────────────────────────────────────────────────────────────────────────
 // 主流程
 // ────────────────────────────────────────────────────────────────────────────
@@ -1695,6 +2491,123 @@ function normalizeOperation(value) {
     return lowered;
 }
 /** 工具主入口：永不抛异常。 */
+/**
+ * 承认的参数名白名单 —— 从 `MathArgs` 接口派生，不手写。
+ *
+ * ## 为什么需要这份白名单
+ *
+ * 踩过的坑：`{expression:'1+3', foo_bar_baz:123}` 会**静默成功**并返回 3。
+ * 调用方以为参数生效了，实际被整个吞掉。这类「以为做了、其实没做」
+ * 比报错危险得多 —— 与 overrides 里 key 拼错被丢弃是同一类问题。
+ *
+ * ## 为什么不靠 JSON Schema 的 additionalProperties
+ *
+ * 工具的 input schema 是宿主侧契约，加严会影响所有历史调用；
+ * 而「参数名拼错」这件事在本工具内部就能判，判得更早、提示更具体。
+ *
+ * ## 白名单从哪来
+ *
+ * 不手写清单（手写必然与接口漂移）。用 TypeScript 的类型约束保证
+ * `KNOWN_ARGUMENT_KEYS` 覆盖 `MathArgs` 的全部键：少一个键 tsconfig 会报错。
+ * 见文件末尾的 `_AssertKeysCoverMathArgs`。
+ */
+const KNOWN_ARGUMENT_KEYS = new Set([
+    // 基础计算
+    'expression', 'expressions', 'terse', 'variables', 'operation', 'variable',
+    'matrix', 'vector', 'precision', 'displayPrecision',
+    // 数据与统计
+    'data', 'dataY', 'distribution', 'params', 'x', 'degree',
+    // 公式
+    'formula', 'overrides', 'query', 'customExpression',
+    // 微分方程 / 物理
+    'initial', 'from', 'to', 'steps', 'samples',
+    // 星球与推演
+    'world', 'terrain', 'constants', 'derivation', 'layer',
+    // 工作区
+    'action2', 'workspace', 'name', 'description', 'terrainName', 'workspaceVariables',
+    'useWorkspaceVariables',
+    // 设定一致性
+    'claims', 'listConstraints',
+    // 单位
+    'unitValue', 'unitFrom', 'unitTo', 'customUnits', 'unitScales', 'unitScale',
+    // 收支
+    'balance',
+    // 天体
+    'bodyName', 'bodyKind', 'bodyConstant', 'bodyFactor', 'bodyType', 'bodyEvidence',
+    // 逆推校准
+    'anchor', 'anchorValue', 'compareFrom', 'compareTo',
+    // 幻想层
+    'fantasyAbility', 'fantasyDemand', 'fantasyPhysical', 'fantasyBodyArea',
+    // 混沌 / 继承 / 对比
+    'lyapunov', 'inheritDerived', 'inheritBase', 'inheritSync', 'diffA', 'diffB',
+    // 观测者 / 图 / 时间轴 / 白皮书 / 溯源 / 算力
+    'observerKind', 'graphDepths', 'timelineFrom', 'timelineTo', 'timelineSteps',
+    'whitepaperMode', 'traceTarget', 'costKind', 'costX', 'costY',
+    'costIterations', 'costCombos', 'costWithPipeline',
+    // 提示档位与帮助分节
+    'promptMode',
+    'helpTopic',
+    // 公式表
+    'tableAction', 'formulaId', 'newExpression', 'newParams', 'customFormula',
+    // 自定义常数
+    'customAction', 'customConstant', 'customConstantName', 'expectedDimension',
+    // 结论文翻转
+    'flipClaim', 'flipEpsilon', 'flipBase',
+    // 杂项
+    'threshold', 'worstLimit', 'variableName', 'constantName',
+    'emptyOnly', 'dryRun', 'olderThanDays', 'keep', 'tempPrefixes',
+    'sensitivityBase', 'sensitivityExponent',
+]);
+/**
+ * world 的**顶层简写参数**（`{operation:'world', starMass:10}` 这种写法）。
+ *
+ * 这些键**不在 `MathArgs` 接口里**，但它们是合法输入 —— 由 `WORLD_PARAMS` 决定，
+ * `opWorld` 会遍历它把顶层值并入 `world`。
+ *
+ * 踩过的坑：白名单第一版只抄了接口里的 4 个（planetRadius/planetMass/rotationHours/obliquityDeg），
+ * 于是 `{operation:'world', starMass:10}` 被新加的校验拦下 —— **world 套件当场红**。
+ * 教训：白名单不能只认 TypeScript 接口，接口落后于实现的部分会变成假阳性。
+ * 所以这里**从真实数据源 `WORLD_KEYS` 派生**，接口补不全也不影响。
+ */
+const WORLD_SHORTHAND_KEYS = WORLD_KEYS;
+/**
+ * 查有没有拼错/多余的参数名。
+ *
+ * ## 为什么大小写变体也一律报错
+ *
+ * 做过一版「容忍大小写差异」（把 `DisplayPrecision` 归一到 `displayPrecision`），
+ * 实测发现更糟：**参数被接受，却因为代码只读小写键而完全不生效**，
+ * 输出静默退回 8 位。那不是宽容，那是另一种静默 ——
+ * 比直接报错更难排查，因为连错误信息都没有。
+ *
+ * 所以这里只做**精确匹配**：名字必须是白名单里那个写法，一个字母都不差。
+ *
+ * @param rawArguments - 调用方原样的参数对象
+ * @returns 认不出的键；空数组表示全部可识别
+ */
+function findUnknownArguments(rawArguments) {
+    if (rawArguments === null || typeof rawArguments !== 'object' || Array.isArray(rawArguments))
+        return [];
+    const unknown = [];
+    for (const key of Object.keys(rawArguments)) {
+        if (KNOWN_ARGUMENT_KEYS.has(key))
+            continue;
+        if (WORLD_SHORTHAND_KEYS.includes(key))
+            continue;
+        unknown.push(key);
+    }
+    return unknown.sort();
+}
+/**
+ * 工具主入口：永不抛异常。
+ *
+ * 所有失败都转成 `{ ok:false, error:{ type, message, hint } }`，
+ * 因为宿主侧把抛异常当成「工具坏了」，而这里的失败几乎都是**输入问题**，
+ * 调用方按 hint 改一下就能过。
+ *
+ * @param rawArguments - 宿主传进来的参数对象（可能是任意形态，这里先做白名单校验）
+ * @returns 永远是一个 MathResult，不会 throw
+ */
 export function runMathTool(rawArguments) {
     const args = (rawArguments ?? {});
     const input = typeof args.expression === 'string' ? args.expression.trim() : '';
@@ -1703,6 +2616,18 @@ export function runMathTool(rawArguments) {
     /** 显示有效位数；undefined = 未设定（沿用计算精度，即完整输出）。 */
     let displayPrecision;
     try {
+        /**
+         * 先把「认不出的参数名」拦下来。
+         *
+         * 不静默继续算 —— 那样调用方会以为某个参数已经生效
+         * （实测见过：`displayPrecision:0`、`format`、`sigfigs` 都是这样被吞的）。
+         */
+        const unknownArguments = findUnknownArguments(rawArguments);
+        if (unknownArguments.length > 0) {
+            throw new CalcError('unknown_argument', '这些参数名认不出来，已经被忽略（本次没有生效）: ' + unknownArguments.join('、'), '按名字传给 help 可查用法: {operation:"help"}。' +
+                '常见原因：拼写笔误、大小写、把某个 operation 的子字段提到了顶层' +
+                '（如 terrain 的字段要放在 terrain 对象里）。');
+        }
         precision = clampPrecision(args.precision);
         /**
          * 显示精度：本次显式给 > 工作区固化值 > 沿用计算精度。
@@ -1769,9 +2694,26 @@ export function runMathTool(rawArguments) {
         setActiveDisplayPrecision(displayPrecision);
         const variable = normalizeVariable(args.variable);
         const requested = normalizeOperation(args.operation);
-        const known = knownNumbers(args.variables);
+        /**
+         * 作用域输入按「本次参数 > 工作区变量」合并。
+         *
+         * 合并只发生在**计算路径**（这一处），且受工作区开关 `useWorkspaceVariables` 控制；
+         * 开关关闭时 `mergeWorkspaceVariables` 原样返回 `args.variables`，
+         * 行为与旧版完全一致。
+         *
+         * 为什么只在这一处合并、而不是每个 operation 各自去读工作区：
+         * 那样每个 op 都要自己处理「合并 + 优先级 + 缓存指纹」，
+         * 迟早有一处漏掉（缓存指纹漏掉就是静默返回旧值）。
+         */
+        const scopeVariables = mergeWorkspaceVariables(args.variables);
+        const known = knownNumbers(scopeVariables);
         const engine = bignum(precision);
-        const scope = buildScope(engine, args.variables);
+        /**
+         * 每次调用开头清空「被跳过的变量键」记录，避免串到上一次调用。
+         * 与 `activeDisplayPrecision` 同理：模块级状态必须每次开头复位。
+         */
+        resetSkippedVariableKeys();
+        const scope = buildScope(engine, scopeVariables);
         operation = requested === 'auto' ? detectOperation(input, args) : requested;
         // 提示档位切换（不影响计算，只影响注入给模型的内容）
         if (args.promptMode !== undefined) {
@@ -1859,6 +2801,11 @@ export function runMathTool(rawArguments) {
                     stableArgs(restForCache),
                     activeWorkspaceNameForCache(),
                     constantsFingerprint(),
+                    /**
+                     * 变量内容必须进键：见 `workspaceVariablesFingerprint` 的说明。
+                     * 开关关闭时这一项是常量 'disabled'，等价于旧行为。
+                     */
+                    workspaceVariablesFingerprint(),
                 ]);
                 const cached = getCached(key);
                 if (cached !== undefined) {
@@ -1880,9 +2827,37 @@ export function runMathTool(rawArguments) {
          * 缓存它们只会挤占单条计算的位置。
          */
         if (Array.isArray(args.expressions) && args.expressions.length > 0) {
-            outcome = opEvaluateBatch(engine, args.expressions, scope, precision);
+            outcome = opEvaluateBatch(engine, args.expressions, scope, precision, args.terse === true);
+            /**
+             * 批量里**有失败**时，顶层 `ok` 必须为 false。
+             *
+             * ## 修的是什么
+             *
+             * 实测反馈（2026-11-06）：批量里一条 `unknown_symbol` 失败时，
+             * `result` 里写着「→ 失败[unknown_symbol]」，但 `ok` 仍是 `true`、
+             * `error` 是 `undefined`。于是任何写 `if (r.ok)` 的调用方
+             * **都会把失败当成成功**，再把失败文本当数值用。
+             *
+             * 原话：「我在本次任务中多次写 `if (!r.ok)` 来判断成败，
+             *   得到的结果是『永远成功』——因为 `ok` 永远是 `true`。」
+             *
+             * ## 为什么不是「一条失败就整批失败」
+             *
+             * 「一条失败不影响其它条」是这个批量模式的核心优点，不能丢。
+             * 所以这里分开表达：
+             *   · `ok: false`      —— 告诉自动化流程「本批**不是**全好」
+             *   · `partial: true`  —— 告诉它「但有成功的条目可用」
+             *   · `failed / succeeded` —— 给出具体数量，便于分流处理
+             *
+             * 顶层 `error` 仍是 `undefined`（这是**批量**失败，不是某个单条的错误；
+             * 每条的原因都在 `value.items` 里）。若硬塞一个 error，
+             * 反而会让「只有第 3 条错」被读成「整个调用都错了」。
+             */
+            const batchValue = (outcome.value ?? {});
+            const failedCount = typeof batchValue.failed === 'number' ? batchValue.failed : 0;
+            const succeededCount = typeof batchValue.success === 'number' ? batchValue.success : 0;
             const batchResult = {
-                ok: true,
+                ok: failedCount === 0,
                 operation: 'evaluate',
                 input: args.expressions.join(' ; ').slice(0, 200),
                 result: outcome.result,
@@ -1890,17 +2865,37 @@ export function runMathTool(rawArguments) {
             };
             if (outcome.value !== undefined)
                 batchResult.value = outcome.value;
+            if (failedCount > 0) {
+                batchResult.partial = succeededCount > 0;
+                batchResult.failed = failedCount;
+                batchResult.succeeded = succeededCount;
+            }
+            /**
+             * 被跳过的变量键在**批量路径**也要告知。
+             *
+             * 踩过：第一版只在函数末尾的单条路径上组装这条提示，
+             * 而批量在 3078 行就 return 了 —— 于是批量调用永远看不到它。
+             * 这正是实测反馈里的原始场景（一批算式 + 一个中文变量名）。
+             */
+            const skippedInBatch = takeSkippedVariableKeys();
+            if (skippedInBatch.length > 0) {
+                const parts = skippedInBatch.map(function (item) { return item.name + '（' + item.reason + '）'; });
+                batchResult.notice =
+                    '这些变量名没被采用，已跳过（其余照算）: ' + parts.join('；') +
+                        '。变量名只能含字母、数字、下划线；中文名可先存进工作区再引用。';
+            }
             return batchResult;
         }
         switch (operation) {
             case 'help':
-                outcome = opHelp();
+                /** 分节帮助：给了 helpTopic 就回那一节，否则回目录。详见 `src/help.ts`。 */
+                outcome = opHelp(typeof args.helpTopic === 'string' ? args.helpTopic : undefined);
                 break;
             case 'derivative':
                 outcome = opDerivative(input, variable, precision);
                 break;
             case 'integral':
-                outcome = opIntegral(input, variable, precision);
+                outcome = opIntegral(input, variable, precision, typeof args.from === 'number' ? args.from : undefined, typeof args.to === 'number' ? args.to : undefined);
                 break;
             case 'simplify':
                 outcome = opSimplify(input);
@@ -2007,6 +3002,52 @@ export function runMathTool(rawArguments) {
         const hintNote = maybeDisplayPrecisionHint(result.result);
         if (hintNote)
             result.notice = hintNote;
+        /**
+         * 三角函数按弧度算时补一句说明。
+         *
+         * 走 `notice` 而不是拼进 `result`：`result` 是数据通道，
+         * 往里拼提示会让依赖精确相等（`sin(30) = -0.98803162`）的调用方失配 ——
+         * 这与「显示精度提示走 notice」是同一条既有约定。
+         *
+         * 实测反馈（2026-11-06 第二份）：中文工程语境里 `sin(30)` 的默认读法是 30 度，
+         * 而工具按弧度给出 `-0.988` —— 数字看着正常，用户不会察觉。
+         */
+        if (operation === 'evaluate' && input !== '') {
+            const angleNote = checkAngleUnit(input);
+            if (angleNote) {
+                result.notice = result.notice ? result.notice + '\n' + angleNote : angleNote;
+            }
+        }
+        /**
+         * 带单位的结果补说明：「这个数有多大、等价于什么」。
+         *
+         * 实测：`evaluate` 带单位的结果只有裸文本（`87.78 Mt`，notice 为空），
+         * 而 `units` 操作有【代入过程】【注意】——两者信息量差得远。
+         * 模型看到 `87.78 Mt` 并不知道它是 8778 万吨。
+         *
+         * 用户原话：「面向 AI 的运算信息最好把信息注释写到位。」
+         */
+        {
+            const unitNote = explainUnitResult(result.result);
+            if (unitNote) {
+                result.notice = result.notice ? result.notice + '\n' + unitNote : unitNote;
+            }
+        }
+        /**
+         * 被跳过的变量键要告知，不能静默。
+         *
+         * 实测反馈（2026-11-06 第二份）：`variables` 里写了一个中文键，
+         * 整批中止、合法算式一条没算。现在改成「跳过 + 告知」——
+         * 算出来的数是对的，但调用方必须知道哪个键没生效，
+         * 否则它会以为 `人口` 已经传进去了。
+         */
+        const skippedVars = takeSkippedVariableKeys();
+        if (skippedVars.length > 0) {
+            const parts = skippedVars.map(function (item) { return item.name + '（' + item.reason + '）'; });
+            const skipNote = '这些变量名没被采用，已跳过（其余照算）: ' + parts.join('；') +
+                '。变量名只能含字母、数字、下划线；中文名可先存进工作区再引用。';
+            result.notice = result.notice ? result.notice + '\n' + skipNote : skipNote;
+        }
         /**
          * ── 精度不足提醒 ──
          *
@@ -2025,23 +3066,37 @@ export function runMathTool(rawArguments) {
          *
          * 取「两条提示取更强的」：精度损失提示优先于泛泛的「可以调」提示。
          */
-        if (!isDisplayPrecisionExplicit()) {
-            const loss = consumePrecisionLoss();
-            if (loss > PRECISION_LOSS_THRESHOLD) {
-                /*
-                 * 建议的位数：在当前基础上再加 8 位，上限 64。
-                 * 这样「8 → 16」「16 → 24」都合理，且不会建议一个超范围的值。
-                 */
-                const suggested = Math.min(64, displayPrecision + 8);
-                result.notice =
-                    '注意：本次结果按 ' + displayPrecision + ' 位小数截断后，相对误差约 ' +
-                        (loss * 100).toFixed(loss > 0.1 ? 0 : 2) + '%。' +
-                        '若需要精确值，请传 displayPrecision:' + suggested + '（或更高）。';
-            }
-        }
-        else {
-            // 显式指定时也要清空，避免残留到下轮
-            consumePrecisionLoss();
+        /**
+         * ── 精度损失：只在**真的丢精度**时提示一句 ──
+         *
+         * 与旧实现的关键区别：旧版只要「未固化 + 结果有小数」就附一段说明，
+         * 一次 60+ 次调用的会话里出现 60+ 次（用户实测反馈：纯噪音）。
+         * 现在判据是**相对误差超过万分之一**，普通计算（`1/7` 误差 1e-9）不提示。
+         *
+         * 两种情况的说法不同：
+         *   · 未显式指定 → 已自动改用科学计数法，说明为什么换格式
+         *   · 显式指定   → 格式按你要求的保留，但告知这个位数丢了精度
+         */
+        const loss = consumePrecisionLoss();
+        /**
+         * 显式指定时用**更宽松**的提示阈值。
+         *
+         * 理由：调用方既然写了 `displayPrecision:4`，就已经接受「4 位小数的精度」。
+         * `1/7` → `0.1429` 的相对误差是 0.03% —— 那是他要求的结果，不值得提示。
+         * 只有丢到 1% 以上（如 `disp:4` 下的 σ 直接归零）才该说一句。
+         *
+         * 未显式指定时保持万分之一：那时代码替用户做了取舍，要说明。
+         */
+        const noticeThreshold = isDisplayPrecisionExplicit() ? 1e-2 : PRECISION_LOSS_THRESHOLD;
+        if (loss > noticeThreshold) {
+            const percent = loss >= 1 ? '>100' : (loss * 100).toFixed(loss > 0.1 ? 0 : 2);
+            result.notice = isDisplayPrecisionExplicit()
+                ? '按你指定的 ' + displayPrecision + ' 位小数定点显示会丢约 ' + percent +
+                    '% 的精度，结果已按该位数给出。需要精确值请传 displayPrecision:' +
+                    Math.min(64, displayPrecision + 8) + '。'
+                : '本次结果已改用科学计数法：按 ' + displayPrecision + ' 位小数定点显示会丢约 ' +
+                    percent + '% 的精度。要定点显示请传 displayPrecision:' +
+                    Math.min(64, displayPrecision + 8) + '。';
         }
         /**
          * 非有限结果的处理：**数值型** operation 才算错误，分析型的不算。
@@ -2142,17 +3197,23 @@ function clampPrecision(value) {
  */
 function maybeDisplayPrecisionHint(resultText) {
     try {
-        // 调用方自己指定了精度就不必再教他怎么指定
-        if (isDisplayPrecisionExplicit())
-            return '';
-        // 已固化过就不提示（用户/AI 已经做过选择）
-        if (displayPrecisionOf(currentWorkspace()) !== undefined)
-            return '';
-        // 没有小数就没有截断问题，不必提示
-        if (!/\d\.\d/.test(resultText))
-            return '';
-        return ('显示精度 ' + DEFAULT_DISPLAY_PRECISION + ' 位小数，整数不受影响。要更多位就传 displayPrecision，' +
-            '或用 workspace set displayPrecision=N 固化 —— 固化后此提示消失。');
+        /**
+         * ── 这条通用提示已被移除（2026-11-02，依据实测反馈）──
+         *
+         * 原实现：「未固化显示精度 + 结果里有小数」就附一行说明。
+         * 实测代价：一次 60+ 次调用的会话里，这条提示出现 **60+ 次** —— 纯噪音。
+         *
+         * 为什么不能改成「只提示前 3 次」：那会破坏「同输入同输出」的确定性
+         * （第一次带提示、第二次不带，输出不再字节一致），本项目把它当硬不变量。
+         *
+         * 现在改为**只在真的丢精度时**提示一句具体的说明（见下方的精度损失分支），
+         * 而且格式本身已自动换成科学计数法，所以那种情况也很少出现。
+         *
+         * 「显示精度可调」这件事已经写在工具描述、系统提示与 playbook 三处，
+         * 不需要每次调用重复提醒。
+         */
+        void resultText;
+        return '';
     }
     catch {
         return '';
@@ -2183,6 +3244,45 @@ function constantsFingerprint() {
         return 'unknown-' + Math.random();
     }
 }
+/**
+ * 工作区变量指纹（缓存键用）。
+ *
+ * ## 为什么必须有这一条
+ *
+ * 缓存键原本只含**工作区名**与**常数指纹**，不含变量内容。于是：
+ *
+ * ```
+ *   存 BTU_LB=1260000 → 算 30*BTU_LB → 得数，进缓存
+ *   改成 BTU_LB=126000   → 再算 → 命中旧缓存 → 还是按 1260000 的数
+ * ```
+ *
+ * 这是**静默返回改之前的数**，比不缓存危险得多 ——
+ * 与「改常数后必须失效」是同一条道理，只是状态源换成了变量。
+ *
+ * ## 开关关闭时返回固定串（而不是空）
+ *
+ * 空串与「有变量但指纹为空」无法区分。返回一个明确的常量，
+ * 让键的行为在「开关关闭」这件事上也保持稳定。
+ *
+ * @returns 稳定的指纹字符串
+ */
+function workspaceVariablesFingerprint() {
+    if (!useWorkspaceVariables())
+        return 'disabled';
+    try {
+        const stored = workspaceVariablesOf();
+        const keys = Object.keys(stored).sort();
+        if (keys.length === 0)
+            return 'empty';
+        return keys
+            .map(function (key) { return key + '=' + stored[key].toPrecision(15); })
+            .join(';');
+    }
+    catch {
+        // 读不到就给随机值 —— 宁可慢，不可错（与 constantsFingerprint 同策略）
+        return 'unknown-' + Math.random();
+    }
+}
 /**
  * 当前工作区名（缓存键用）。
  *
@@ -2232,20 +3332,30 @@ function stableArgs(value) {
  * 解析**显示**精度。
  *
  * 与 `clampPrecision` 的区别：这个不影响计算，只影响写出来的位数，
- * 所以允许更宽的范围（1—64）并且**允许返回 undefined**（= 不截断）。
+ * 所以允许更宽的范围（**0—64**）并且**允许返回 undefined**（= 没给）。
+ *
+ * ## 0 在这里是「0 位小数」，不是「清除」
+ *
+ * 踩过的坑：这里原先把 `<= 0` 当作未给，于是 `displayPrecision: 0`
+ * 被静默丢弃、照旧输出 8 位小数 —— 而 schema 上白纸黑字写着「0-64」。
+ * 文档与实现对不上，正是这个项目一直要避免的那类问题。
  *
- * 传 0 视为「清除」，与工作区的约定一致。
+ * **两处 0 的语义刻意不同，各有各的理由**：
+ *   · 本次参数 `displayPrecision: 0` → `3.14159265` 显示成 `3`
+ *     （问的是「这次显示几位」，0 是合法答案）
+ *   · 工作区 `set displayPrecision: 0` → 清除固化值
+ *     （问的是「要不要保存」，0 表示不要）
  *
  * @param value - 原始参数
- * @returns 显示位数；未给或非法返回 undefined
+ * @returns 显示位数（0—64）；未给或非法返回 undefined
  */
 function clampDisplayPrecision(value) {
     if (value === undefined || value === null || value === '')
         return undefined;
     const numeric = typeof value === 'number' ? value : Number(value);
-    if (!Number.isFinite(numeric) || numeric <= 0)
+    if (!Number.isFinite(numeric) || numeric < 0)
         return undefined;
-    return Math.min(64, Math.max(1, Math.round(numeric)));
+    return Math.min(64, Math.max(0, Math.round(numeric)));
 }
 function normalizeVariable(value) {
     if (typeof value !== 'string' || value.trim() === '')
@@ -2295,6 +3405,17 @@ const OUTPUT_SCHEMA = {
         notice: { type: 'string', description: '附加提示（显示精度/精度不足等）' },
         /** 结果来自缓存（未重算）。同样必须声明，否则命中缓存时调用失败。 */
         cached: { type: 'boolean', description: '是否命中缓存' },
+        /**
+         * 批量模式下「部分成功」。
+         *
+         * 语义：本批**有失败条目**（所以 `ok` 是 false），但**也有成功的**可用。
+         * 没这个字段时，调用方无法区分「整批全废」与「废一条、其余可用」。
+         */
+        partial: { type: 'boolean', description: '批量部分成功（有失败条目但仍有成功结果）' },
+        /** 批量模式：失败条目数。 */
+        failed: { type: 'integer', description: '批量中失败条数' },
+        /** 批量模式：成功条目数。 */
+        succeeded: { type: 'integer', description: '批量中成功条数' },
         error: {
             type: 'object',
             additionalProperties: false,
@@ -2306,6 +3427,10 @@ const OUTPUT_SCHEMA = {
         },
     },
 };
+/** 运行期再兜一次：白名单里不许有接口没有的键（防止手滑多写）。 */
+const _KEY_SET_MATCHES_INTERFACE = KNOWN_ARGUMENT_KEYS;
+void 0;
+void _KEY_SET_MATCHES_INTERFACE;
 function renderResult(value) {
     const payload = (value ?? {});
     if (payload.ok === false) {
@@ -2331,13 +3456,40 @@ const PARAMETER_SPEC = {
     },
     expressions: {
         type: 'array',
-        description: '批量求值（operation=evaluate）：一次算多条，省多次往返。' +
-            '逐条独立报错，一条失败不影响其它条。例：["1/7","2^0.5","log(10)"]。',
+        /**
+         * ## 这里声明 items，是推翻了之前「刻意不声明」的决定
+         *
+         * 之前的理由是「不声明也收得进来 + 省 schema 长度」。但那是错的：
+         * **不声明等于模型看不见元素级字段**。上一轮修「元素里的未知键被静默忽略」时
+         * 就撞上了这个 —— 校验现在会拒绝未声明的键，而模型不知道能写什么。
+         *
+         * 加了 `sanity` 之后更明显：一个模型看不见的参数等于不存在。
+         * 所以把 items 加回来，长度从别处腾（`operation` 与 `customExpression` 各压一段）。
+         */
+        items: {
+            type: 'json',
+            description: '字符串（"1/7"）或对象 {label?, expr, sanity?}。' +
+                'sanity 给锚点：{max,min,expect,note}，例 {max:1e10,note:"帝国总兵力"}。',
+        },
+        description: '批量求值，逐条独立报错。',
+    },
+    terse: {
+        type: 'boolean',
+        description: '省 token：只回「表达式 = 结果」。失败条照常标出原因。',
     },
     variables: {
         type: 'object',
         additionalProperties: true,
-        description: '变量字典，注入表达式求值的环境。例：{"m": 500, "v": 30, "c": 299792458}。值可为数字或数字字符串（大数）。',
+        description: '变量字典，注入表达式求值的环境。例：{"m": 500, "v": 30}。值可为数字或数字字符串。',
+    },
+    workspaceVariables: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'workspace/action2=set：把命名常数存进工作区，免去重打。默认不参与计算。',
+    },
+    useWorkspaceVariables: {
+        type: 'boolean',
+        description: 'workspace/action2=set：命名变量是否参与计算（默认 false）。详见 help。',
     },
     operation: {
         type: 'string',
@@ -2384,15 +3536,12 @@ const PARAMETER_SPEC = {
     },
     bodyKind: {
         type: 'string',
-        description: '按类别筛天体（operation=bodies）：star / planet-terrestrial / planet-super-earth / ' +
-            'planet-mini-neptune / planet-gas-giant / moon / dwarf-planet / asteroid。',
+        description: 'bodies：按类别筛。star / planet-terrestrial / planet-gas-giant / moon / dwarf-planet 等，全文见 help。',
     },
     bodyConstant: {
         type: 'string',
-        description: '改常数后看天体数据哪些该重算（operation=bodies）。' +
-            '例：bodyConstant="alpha_fs", bodyFactor=2 —— α 变成两倍，' +
-            '输出分「必须重算的量」与「绝不该动的量」两块。' +
-            '后者尤其重要：行星质量、半径、轨道与 α 无关，跟着改就是篡改设定。',
+        description: 'bodies：改常数后看哪些天体数据该重算。例 bodyConstant="alpha_fs", bodyFactor=2。' +
+            '输出分「必须重算」与「绝不该动」两块（行星质量/半径/轨道与 α 无关）。',
     },
     bodyFactor: {
         type: 'number',
@@ -2400,14 +3549,11 @@ const PARAMETER_SPEC = {
     },
     bodyType: {
         type: 'string',
-        description: '查天体**类型**（operation=bodies）。与 bodyName 的区别：bodyName 查具名天体（火星、木卫二），' +
-            'bodyType 查类型学条目（中子星、热木星、流浪行星、戴森球）。' +
-            '每个类型都标了证据等级，并列明「物理锁死项」（编不了）与「可自由发挥项」。',
+        description: 'bodies：查天体类型学（中子星/热木星/戴森球等），每类标证据等级与物理锁死项。',
     },
     bodyEvidence: {
         type: 'string',
-        description: '按证据等级筛天体类型（operation=bodies）：observed（已观测）/ ' +
-            'theoretical（理论预言，物理必然但未直接观测）/ speculative（纯思辨）。',
+        description: 'bodies：按证据等级筛：observed（已观测）/ theoretical（理论预言）/ speculative（纯思辨）。',
     },
     matrix: {
         type: 'array',
@@ -2419,16 +3565,13 @@ const PARAMETER_SPEC = {
     },
     precision: {
         type: 'integer',
-        description: '**计算精度**：BigNumber 有效数字位数，默认 64，范围 1-256。' +
-            '⚠️ 不要为了「输出好看」调低它——它决定计算的正确性：' +
-            '`(10^20+1)-(10^20)` 在 precision=20 时会得 0（应为 1）。' +
-            '只想让输出短一些，用 displayPrecision。',
+        description: '**计算精度**（BigNumber 有效位，默认 64，1-256）。⚠️ 调低会算错大数：' +
+            '`(10^20+1)-(10^20)` 在 precision=20 得 0。只想输出短些用 displayPrecision。',
     },
     displayPrecision: {
         type: 'integer',
-        description: '**显示精度：小数点后几位**（0-64，默认 8）。只截小数，整数永远完整。' +
-            '例 8 → 1/7 得 0.14285714。全局换档用 workspace set displayPrecision=N。' +
-            '别用 precision 达此目的（会算错大数）。',
+        description: '**显示精度：小数点后几位**（0-64，默认 8）。只截小数、整数永远完整，0 = 只留整数。' +
+            '可用 workspace set displayPrecision=N 固化（那里的 0 = 清除）。',
     },
     data: {
         type: 'array',
@@ -2462,14 +3605,11 @@ const PARAMETER_SPEC = {
     overrides: {
         type: 'object',
         additionalProperties: true,
-        description: '覆盖公式里的任意参数 —— 这是架空世界改造的关键。' +
-            '例如把重力改成 1.5 倍地球：{"g": 14.71}；把光速改成 1e8：{"c": 100000000}。' +
-            '任何带默认值的参数都能这样覆盖。',
+        description: '覆盖公式任意参数 —— 架空世界改造的关键。例：重力 1.5 倍 {"g": 14.71}、光速 {"c": 1e8}。',
     },
     customExpression: {
         type: 'string',
-        description: 'structure 级改造：临时替换公式的表达式，仍沿用该公式的参数名。' +
-            '例如 operation="formula", formula="weight", customExpression="m * g * 1.3" 表示该世界重力异常 +30%。',
+        description: 'structure 级改造：临时替换公式表达式，沿用其参数名。例 formula="weight", customExpression="m*g*1.3" 表示重力 +30%。',
     },
     query: {
         type: 'string',
@@ -2503,8 +3643,8 @@ const PARAMETER_SPEC = {
         // 字段清单不写在 schema 里：schema 每轮都要付费，而这些字段只在
         // 真用 world 时才需要。全文见 help（operation="help", query="world"）。
         description: '星球参数（operation=world），全部可选，默认地球。' +
-            '常用键：planetMass/planetRadius（地球倍数）、starMass/starTemp、rotationHours、obliquityDeg、greenhouse。' +
-            '完整字段表见 help 的 world 条目。',
+            '常用键：planetMass/planetRadius、starMass/starTemp、rotationHours、obliquityDeg。' +
+            '完整字段表见 help。',
     },
     planetRadius: {
         type: 'number',
@@ -2534,7 +3674,12 @@ const PARAMETER_SPEC = {
         additionalProperties: true,
         // 旋钮清单移进 help：只有要改常数时才需要，不该每轮付费
         description: '要改的物理常数（operation=constants），只能改基础旋钮，派生量自动重算。' +
-            '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 条目。',
+            '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 节。',
+    },
+    helpTopic: {
+        type: 'string',
+        description: 'operation="help" 时要取哪一节，省略则返回目录。目录里每节都有简介，' +
+            '按需逐节取比一次读全文省得多（单节约 400 字符，全文 5900）。',
     },
 };
 /**