dsh-math-calculator 2.1.1 → 2.2.0

package/src/index.ts

@@ -40,6 +40,7 @@ import {
   containsNonFinite,
   formatValue,
   isIntegerLike,
+  isNonFiniteValue,
   toFiniteNumber,
   toJsonValue,
   unwrapResult,
@@ -134,6 +135,7 @@ import {
   switchWorkspace,
   updateWorkspace,
   workspaceDirectory,
+  workspaceVariablesOf,
   type SavedTerrain,
   type WorkspaceData,
 } from './workspace.js'
@@ -190,6 +192,8 @@ import {
   currentDisplayPrecision,
   fast,
   normalizeSource,
+  normalizeChineseUnits,
+  rational,
   safeNumberForJson,
   setActiveDisplayPrecision,
   trimNumber,
@@ -211,7 +215,10 @@ import { opImpact } from './ops/impact-op.js'
 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 { opDerivation, DERIVATION_SUBCOMMANDS } from './ops/derivation-op.js'
+import { WORLD_KEYS } from './world-params.js'
+import { opHelp, HELP_TOPICS } 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'
@@ -258,6 +265,17 @@ export interface MathResult {
    * 提示属于「给人/模型看的说明」，走这个字段即可。
    */
   notice?: string
+  /**
+   * 批量模式：「部分成功」——本批有失败条目，但也有成功结果可用。
+   *
+   * 为什么要单独一个字段：`ok` 是布尔，说不了「废了几条、还剩几条」。
+   * 没有它，调用方只能二选一：整批当废（浪费成功条目）或整批当可用（把失败当成功）。
+   */
+  partial?: boolean
+  /** 批量模式：失败条目数。 */
+  failed?: number
+  /** 批量模式：成功条目数。 */
+  succeeded?: number
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -388,7 +406,216 @@ const RISKY_FUNCTION_LIMITS = new Map<string, number>([
 // ────────────────────────────────────────────────────────────────────────────
 
 /** 把任意异常翻译成带类型的 CalcError。 */
-function translateError(raw: unknown, fallbackType = 'internal'): CalcError {
+/**
+ * 给括号类语法错补一句「在哪一层、哪一对对不上」。
+ *
+ * ## 为什么需要它
+ *
+ * 原来的提示是一句固定文案「检查括号是否配对、运算符是否连续」——
+ * 对长公式等于没说。实测反馈原话：char 25 指向的是多余的右括号，
+ * 真正缺的那个左括号在更前面，人得自己数。
+ *
+ * 这里做的是**最小可用的定位**，不是完整解析器：
+ *   · 扫一遍得到每个括号的层级与配对状态
+ *   · 报出第一处不配对的位置（缺左 / 多右）
+ *   · 回显表达式并在下方标出各层的起止
+ *
+ * ## 为什么不做「自动补括号」
+ *
+ * 猜意图补全括号，猜错时会把报错变成一个**算错的数** ——
+ * 比直接报错糟得多。这里只指出位置，补不补、补在哪，由调用方决定。
+ *
+ * @param source - 归一化后的表达式
+ * @returns 提示文本；括号本身平衡时返回空串（说明不是括号问题）
+ */
+function diagnoseParentheses(source: string): string {
+  if (typeof source !== 'string' || source === '') return ''
+  const openAt: Array<{ index: number; depth: number }> = []
+  const pairs: Array<{ open: number; close: number; depth: number }> = []
+  let depth = 0
+  let firstUnexpectedClose = -1
+  /** 引号内的括号不算结构（例如 5 cm to "inch(2)" 这类）。 */
+  let inQuote: string | null = 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: string[] = []
+  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: string[] = []
+    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: string, engineText: string): string {
+  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: string): CalcError | null {
+  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: unknown, fallbackType = 'internal', source = ''): CalcError {
   if (raw instanceof CalcError) return raw
   if (raw instanceof SymbolicError) {
     return new CalcError(raw.stage, raw.message, '符号引擎的能力有限，可尝试 operation="integral" 配数值区间。')
@@ -396,11 +623,40 @@ function translateError(raw: unknown, fallbackType = 'internal'): CalcError {
   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, '两侧单位必须同量纲。')
@@ -427,6 +683,156 @@ function translateError(raw: unknown, fallbackType = 'internal'): CalcError {
 // 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: any, scope: Record<string, unknown>): void {
+  if (!node || typeof node !== 'object') return
+  const defined = new Set(Object.keys(scope ?? {}))
+  const problems: string[] = []
+
+  const visit = (current: any, parent: any): void => {
+    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: any[] = 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: any): void {
   if (!node || typeof node.traverse !== 'function') return
   node.traverse((current: any) => {
@@ -458,6 +864,61 @@ function guardAst(node: any): void {
   })
 }
 
+/**
+ * 判断表达式里有没有**显式要求的目标单位**。
+ *
+ * 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: any): boolean {
+  let found = false
+  if (!node || typeof node !== 'object') return false
+  const visit = (current: any, depth: number): void => {
+    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: any): void {
   if (!node || typeof node.traverse !== 'function') return
   node.traverse((current: any) => {
@@ -478,27 +939,138 @@ function guardComplexity(node: any): void {
 // ────────────────────────────────────────────────────────────────────────────
 
 /** 把 variables 字典转成 mathjs 可用的 scope。 */
+/**
+ * 是否把工作区里登记的命名变量并入作用域。
+ *
+ * ## 这是显式开关，默认关闭
+ *
+ * 打开后同一个调用在不同工作区状态下会给出不同结果 ——
+ * 那会削弱「同输入同输出」。所以：
+ *   · 默认关闭，**不改变任何现有调用的行为**
+ *   · 要开就在工作区里固化：`{action2:"set", useWorkspaceVariables:true}`
+ *
+ * 关掉后 `workspaceVariables` 里存的东西仍然存着（能 show、能 remove），
+ * 只是不参与计算 —— 与旧版行为完全一致。
+ *
+ * @param name - 工作区名；省略用当前工作区
+ * @returns 是否启用
+ */
+function useWorkspaceVariables(name?: string): boolean {
+  try {
+    const data = loadWorkspace(name ?? activeWorkspaceNameForCache())
+    return data.useWorkspaceVariables === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 把工作区变量与本次传入的变量合成最终作用域输入。
+ *
+ * ## 优先级：本次参数 > 工作区
+ *
+ * 临时覆盖长期，符合「显式优先」。同名的键以本次传入为准 ——
+ * 这样「临时想换个值算一下」不必先去改工作区。
+ *
+ * ## 两个来源都要规范化
+ *
+ * `buildScope` 会校验变量名与取值，所以这里不能只做浅合并：
+ * 否则工作区里存了非法名字（历史上可能写进去过），
+ * 会绕过校验直接进 mathjs 作用域。
+ *
+ * @param passed - 本次调用传的 `variables` 参数
+ * @returns 合并后的变量字典；开关关闭时原样返回 passed
+ */
+function mergeWorkspaceVariables(passed: unknown): unknown {
+  if (!useWorkspaceVariables()) return passed
+  const stored = workspaceVariablesOf()
+  const incoming =
+    passed && typeof passed === 'object' && !Array.isArray(passed)
+      ? (passed as Record<string, unknown>)
+      : {}
+  if (Object.keys(stored).length === 0 && Object.keys(incoming).length === 0) return passed
+  return { ...stored, ...incoming }
+}
+
+/**
+ * 收集上一次 `buildScope` 跳过的非法变量键。
+ *
+ * 模块级、每次调用开头清空 —— 与 `activeDisplayPrecision` 同样的理由：
+ * 逐层传参要改四十多个函数签名，而这个信息只在**入口**用来组装一条提示。
+ */
+let skippedVariableKeys: Array<{ name: string; reason: string }> = []
+
+/**
+ * 取本次调用中被跳过的非法变量键（组装提示用）。
+ *
+ * @returns 被跳过的键与原因
+ */
+export function takeSkippedVariableKeys(): Array<{ name: string; reason: string }> {
+  const taken = skippedVariableKeys
+  skippedVariableKeys = []
+  return taken
+}
+
+/**
+ * 清理被跳过的变量键记录（每次工具调用开头）。
+ */
+export function resetSkippedVariableKeys(): void {
+  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: any, variables: unknown): Record<string, any> {
   const scope: Record<string, any> = {}
   if (!variables || typeof variables !== 'object' || Array.isArray(variables)) return scope
   for (const [key, raw] of Object.entries(variables as Record<string, unknown>)) {
     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') {
       // 允许字符串形式的大数，例如 "1e100"
       try {
         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
@@ -548,6 +1120,24 @@ function opEvaluate(engine: any, expression: string, scope: Record<string, any>,
   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}）`)
   }
@@ -555,11 +1145,14 @@ function opEvaluate(engine: any, expression: string, scope: Record<string, any>,
   try {
     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: any
   try {
     raw = node.evaluate(scope)
@@ -568,8 +1161,53 @@ function opEvaluate(engine: any, expression: string, scope: Record<string, any>,
   }
 
   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),
   }
 }
@@ -598,9 +1236,10 @@ function opEvaluate(engine: any, expression: string, scope: Record<string, any>,
  */
 function opEvaluateBatch(
   engine: any,
-  expressions: string[],
+  expressions: Array<string | { label?: string; expr?: string }>,
   scope: Record<string, any>,
   precision: number,
+  terse = false,
 ): Outcome {
   const items = expressions.slice(0, MAX_BATCH_EXPRESSIONS)
   if (items.length === 0) {
@@ -608,44 +1247,290 @@ function opEvaluateBatch(
   }
 
   const shown: string[] = []
-  const values: Array<{ expression: string; ok: boolean; result?: string; error?: string }> = []
+  const values: Array<{ expression: string; label?: string; ok: boolean; result?: string; error?: string }> = []
+  /** 量级类提示（不影响成败，只提醒核对）。 */
+  const magnitudeWarnings: string[] = []
   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 as { label?: string; expr?: string }) ?? {}
+    /**
+     * ## 元素里的未知键也要点名
+     *
+     * 顶层的未知参数有 `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 as Record<string, unknown>).filter(function (k) { return !allowedEntryKeys.includes(k) })
+    if (unknownEntryKeys.length > 0) {
+      const echoName = (entry as { label?: string }).label || String((entry as { expr?: string }).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: any
+      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 as { sanity?: unknown }).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: string[] = []
+    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,
+      } as never),
+    }
+  }
+
   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: string[] = []
+  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 } as never),
+    result: [header, '', ...shown, '', ...summary].join('\n'),
+    value: toJsonValue({
+      count: items.length,
+      success: successCount,
+      failed: failCount,
+      magnitudeWarnings: magnitudeWarnings.length,
+      items: values,
+    } as never),
   }
 }
 
@@ -674,10 +1559,86 @@ function opDerivative(expression: string, variable: string, precision: number):
   return { result: symbolic, value: symbolic }
 }
 
-function opIntegral(expression: string, variable: string, precision: number): Outcome {
+function opIntegral(
+  expression: string,
+  variable: string,
+  precision: number,
+  from?: number,
+  to?: number,
+): Outcome {
   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: any
+    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 }
 }
 
@@ -1563,7 +2524,12 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
 
   const overrides = (args.overrides ?? {}) as Record<string, number | string>
 
-  let resolved: { values: Record<string, unknown>; overridden: string[]; missing: string[] }
+  let resolved: {
+    values: Record<string, unknown>
+    overridden: string[]
+    missing: string[]
+    unknownKeys: string[]
+  }
   try {
     resolved = resolveParams(formula, overrides)
   } catch (error) {
@@ -1581,6 +2547,17 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
     )
   }
 
+  /**
+   * ── 未知参数名：明确告知，不静默丢弃 ──
+   *
+   * 实测反馈：overrides 的 key 拼错时公式**照常出数**，只是那个参数用了默认值。
+   * 报告里那次「236 倍缺口」误判就是这么来的 —— 而结果看着完全正常。
+   *
+   * 这里不抛错（可能是调用方故意传常数名，或用法上无伤），
+   * 而是把「你没生效的参数」写成一条提示，让调用方能自己判断。
+   */
+  const unknownOverrideKeys = resolved.unknownKeys ?? []
+
   const expression = resolveExpression(formula, args.customExpression)
   const scope = buildFormulaScope(engine, resolved.values)
 
@@ -1619,7 +2596,7 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
   try {
     node = engine.parse(expression)
   } catch (error) {
-    throw translateError(error, 'syntax')
+    throw translateError(error, 'syntax', expression)
   }
   guardAst(node)
   guardComplexity(node)
@@ -1634,6 +2611,22 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
   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('、') +
+        '。若这是拼写笔误，结果可能已偏离——请核对后重算。',
+    )
+  }
+
   /**
    * 经验公式的适用性提示。
    *
@@ -1834,123 +2827,6 @@ function opFormulas(args: MathArgs): Outcome {
   return { result: lines.join('\n'), value: { query, matches: matches.map((m) => m.id) } }
 }
 
-/** 能力清单。 */
-
-/** 能力清单。 */
-function opHelp(): Outcome {
-  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'),
-  }
-}
 
 // ────────────────────────────────────────────────────────────────────────────
 // 主流程
@@ -1976,6 +2852,123 @@ function normalizeOperation(value: unknown): MathOperation {
 }
 
 /** 工具主入口：永不抛异常。 */
+/**
+ * 承认的参数名白名单 —— 从 `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: ReadonlySet<string> = new Set<string>([
+  // 基础计算
+  '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: readonly string[] = WORLD_KEYS
+
+/**
+ * 查有没有拼错/多余的参数名。
+ *
+ * ## 为什么大小写变体也一律报错
+ *
+ * 做过一版「容忍大小写差异」（把 `DisplayPrecision` 归一到 `displayPrecision`），
+ * 实测发现更糟：**参数被接受，却因为代码只读小写键而完全不生效**，
+ * 输出静默退回 8 位。那不是宽容，那是另一种静默 ——
+ * 比直接报错更难排查，因为连错误信息都没有。
+ *
+ * 所以这里只做**精确匹配**：名字必须是白名单里那个写法，一个字母都不差。
+ *
+ * @param rawArguments - 调用方原样的参数对象
+ * @returns 认不出的键；空数组表示全部可识别
+ */
+function findUnknownArguments(rawArguments: unknown): string[] {
+  if (rawArguments === null || typeof rawArguments !== 'object' || Array.isArray(rawArguments)) return []
+  const unknown: string[] = []
+  for (const key of Object.keys(rawArguments as Record<string, unknown>)) {
+    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: unknown): MathResult {
   const args = (rawArguments ?? {}) as Partial<MathArgs>
   const input = typeof args.expression === 'string' ? args.expression.trim() : ''
@@ -1986,6 +2979,22 @@ export function runMathTool(rawArguments: unknown): MathResult {
   let displayPrecision: number | undefined
 
   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)
     /**
      * 显示精度：本次显式给 > 工作区固化值 > 沿用计算精度。
@@ -2052,9 +3061,26 @@ export function runMathTool(rawArguments: unknown): MathResult {
     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
 
@@ -2151,6 +3177,11 @@ export function runMathTool(rawArguments: unknown): MathResult {
           stableArgs(restForCache),
           activeWorkspaceNameForCache(),
           constantsFingerprint(),
+          /**
+           * 变量内容必须进键：见 `workspaceVariablesFingerprint` 的说明。
+           * 开关关闭时这一项是常量 'disabled'，等价于旧行为。
+           */
+          workspaceVariablesFingerprint(),
         ])
         const cached = getCached(key)
         if (cached !== undefined) {
@@ -2172,26 +3203,80 @@ export function runMathTool(rawArguments: unknown): MathResult {
      * 缓存它们只会挤占单条计算的位置。
      */
     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 ?? {}) as Record<string, unknown>
+      const failedCount = typeof batchValue.failed === 'number' ? batchValue.failed : 0
+      const succeededCount = typeof batchValue.success === 'number' ? batchValue.success : 0
       const batchResult: MathResult = {
-        ok: true,
+        ok: failedCount === 0,
         operation: 'evaluate',
         input: args.expressions.join(' ; ').slice(0, 200),
         result: outcome.result,
         precision,
       }
       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)
@@ -2298,6 +3383,56 @@ export function runMathTool(rawArguments: unknown): MathResult {
     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
+    }
+
     /**
      * ── 精度不足提醒 ──
      *
@@ -2316,22 +3451,37 @@ export function runMathTool(rawArguments: unknown): MathResult {
      *
      * 取「两条提示取更强的」：精度损失提示优先于泛泛的「可以调」提示。
      */
-    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) + '。'
     }
 
     /**
@@ -2357,7 +3507,8 @@ export function runMathTool(rawArguments: unknown): MathResult {
       'simplify', 'expand', 'roots', 'matrix', 'eigen', 'dist',
       'regression', 'ode', 'formula',
     ]
-    if (STRICT_FINITE_OPERATIONS.includes(operation) && containsNonFinite(result.value)) {
+    
+if (STRICT_FINITE_OPERATIONS.includes(operation) && containsNonFinite(result.value)) {
       throw new CalcError(
         'non_finite',
         `计算结果非有限（${outcome.result}）`,
@@ -2435,16 +3586,23 @@ function clampPrecision(value: unknown): number {
  */
 function maybeDisplayPrecisionHint(resultText: string): string {
   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 ''
   }
@@ -2475,6 +3633,43 @@ function constantsFingerprint(): string {
   }
 }
 
+/**
+ * 工作区变量指纹（缓存键用）。
+ *
+ * ## 为什么必须有这一条
+ *
+ * 缓存键原本只含**工作区名**与**常数指纹**，不含变量内容。于是：
+ *
+ * ```
+ *   存 BTU_LB=1260000 → 算 30*BTU_LB → 得数，进缓存
+ *   改成 BTU_LB=126000   → 再算 → 命中旧缓存 → 还是按 1260000 的数
+ * ```
+ *
+ * 这是**静默返回改之前的数**，比不缓存危险得多 ——
+ * 与「改常数后必须失效」是同一条道理，只是状态源换成了变量。
+ *
+ * ## 开关关闭时返回固定串（而不是空）
+ *
+ * 空串与「有变量但指纹为空」无法区分。返回一个明确的常量，
+ * 让键的行为在「开关关闭」这件事上也保持稳定。
+ *
+ * @returns 稳定的指纹字符串
+ */
+function workspaceVariablesFingerprint(): string {
+  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()
+  }
+}
+
 /**
  * 当前工作区名（缓存键用）。
  *
@@ -2522,18 +3717,28 @@ function stableArgs(value: unknown): string {
  * 解析**显示**精度。
  *
  * 与 `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: unknown): number | undefined {
   if (value === undefined || value === null || value === '') return undefined
   const numeric = typeof value === 'number' ? value : Number(value)
-  if (!Number.isFinite(numeric) || numeric <= 0) return undefined
-  return Math.min(64, Math.max(1, Math.round(numeric)))
+  if (!Number.isFinite(numeric) || numeric < 0) return undefined
+  return Math.min(64, Math.max(0, Math.round(numeric)))
 }
 
 function normalizeVariable(value: unknown): string {
@@ -2585,6 +3790,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,
@@ -2597,6 +3813,50 @@ const OUTPUT_SCHEMA = {
   },
 } as const
 
+/**
+ * 编译期守卫：`KNOWN_ARGUMENT_KEYS` 必须覆盖 `MathArgs` 的每一个键。
+ *
+ * 手写白名单最大的风险是**与接口漂移** —— 新增一个参数却忘了加进白名单，
+ * 那条新参数就会被自己的校验拦下（比不校验更糟）。
+ * 这里用「键的联合类型必须被白名单收住」的写法把漂移变成编译期报错。
+ *
+ * 少了哪个键，tsc 会直接指出该键名。
+ */
+type MathArgsKeys = keyof MathArgs
+type _KeysCovered = MathArgsKeys extends string ? (MathArgsKeys extends KnownKeyUnion ? true : never) : never
+type KnownKeyUnion =
+  | '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' | 'planetRadius' | 'planetMass' | 'rotationHours' | 'obliquityDeg'
+  | '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'
+
+/** 运行期再兜一次：白名单里不许有接口没有的键（防止手滑多写）。 */
+const _KEY_SET_MATCHES_INTERFACE: ReadonlySet<string> = KNOWN_ARGUMENT_KEYS
+void 0 as unknown as _KeysCovered
+void _KEY_SET_MATCHES_INTERFACE
+
 function renderResult(value: any): Array<{ type: 'text'; text: string }> {
   const payload = (value ?? {}) as Partial<MathResult>
   if (payload.ok === false) {
@@ -2624,14 +3884,41 @@ 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',
@@ -2685,16 +3972,13 @@ 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。',
+      'bodies：按类别筛。star / planet-terrestrial / planet-gas-giant / moon / dwarf-planet 等，全文见 help。',
   },
   bodyConstant: {
     type: 'string',
     description:
-      '改常数后看天体数据哪些该重算（operation=bodies）。' +
-      '例：bodyConstant="alpha_fs", bodyFactor=2 —— α 变成两倍，' +
-      '输出分「必须重算的量」与「绝不该动的量」两块。' +
-      '后者尤其重要：行星质量、半径、轨道与 α 无关，跟着改就是篡改设定。',
+      'bodies：改常数后看哪些天体数据该重算。例 bodyConstant="alpha_fs", bodyFactor=2。' +
+      '输出分「必须重算」与「绝不该动」两块（行星质量/半径/轨道与 α 无关）。',
   },
   bodyFactor: {
     type: 'number',
@@ -2702,16 +3986,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',
@@ -2724,17 +4003,14 @@ const PARAMETER_SPEC = {
   precision: {
     type: 'integer',
     description:
-      '**计算精度**：BigNumber 有效数字位数，默认 64，范围 1-256。' +
-      '⚠️ 不要为了「输出好看」调低它——它决定计算的正确性：' +
-      '`(10^20+1)-(10^20)` 在 precision=20 时会得 0（应为 1）。' +
-      '只想让输出短一些，用 displayPrecision。',
+      '**计算精度**（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 达此目的（会算错大数）。',
+      '**显示精度：小数点后几位**（0-64，默认 8）。只截小数、整数永远完整，0 = 只留整数。' +
+      '可用 workspace set displayPrecision=N 固化（那里的 0 = 清除）。',
   },
   data: {
     type: 'array',
@@ -2770,15 +4046,12 @@ const PARAMETER_SPEC = {
     type: 'object',
     additionalProperties: true,
     description:
-      '覆盖公式里的任意参数 —— 这是架空世界改造的关键。' +
-      '例如把重力改成 1.5 倍地球：{"g": 14.71}；把光速改成 1e8：{"c": 100000000}。' +
-      '任何带默认值的参数都能这样覆盖。',
+      '覆盖公式任意参数 —— 架空世界改造的关键。例：重力 1.5 倍 {"g": 14.71}、光速 {"c": 1e8}。',
   },
   customExpression: {
     type: 'string',
     description:
-      'structure 级改造：临时替换公式的表达式，仍沿用该公式的参数名。' +
-      '例如 operation="formula", formula="weight", customExpression="m * g * 1.3" 表示该世界重力异常 +30%。',
+      'structure 级改造：临时替换公式表达式，沿用其参数名。例 formula="weight", customExpression="m*g*1.3" 表示重力 +30%。',
   },
   query: {
     type: 'string',
@@ -2814,8 +4087,8 @@ const PARAMETER_SPEC = {
     // 真用 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',
@@ -2847,7 +4120,13 @@ const PARAMETER_SPEC = {
     // 旋钮清单移进 help：只有要改常数时才需要，不该每轮付费
     description:
       '要改的物理常数（operation=constants），只能改基础旋钮，派生量自动重算。' +
-      '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 条目。',
+      '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 节。',
+  },
+  helpTopic: {
+    type: 'string',
+    description:
+      'operation="help" 时要取哪一节，省略则返回目录。目录里每节都有简介，' +
+      '按需逐节取比一次读全文省得多（单节约 400 字符，全文 5900）。',
   },
 } as const