dsh-math-calculator 2.0.0 → 2.1.1

package/src/index.ts

@@ -88,6 +88,8 @@ import {
   listFormulaCategories,
   resolveExpression,
   resolveParams,
+  resolveFormulaStrict,
+  scoreFormulas,
   type FormulaDef,
 } from './formulas.js'
 import { BUILTINS } from './formula-builtins.js'
@@ -126,6 +128,7 @@ import {
   bindHostWorkspace,
   cwdOfExec,
   cwdOfSession,
+  displayPrecisionOf,
   scopeFromCwd,
   setLastExecShape,
   switchWorkspace,
@@ -184,14 +187,22 @@ import {
 import {
   CalcError,
   bignum,
+  currentDisplayPrecision,
   fast,
   normalizeSource,
   safeNumberForJson,
+  setActiveDisplayPrecision,
   trimNumber,
   type MathArgs,
   type MathOperation,
   type Outcome,
 } 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'
 import { opConstants } from './ops/constants-op.js'
@@ -204,6 +215,9 @@ import { opDerivation } from './ops/derivation-op.js'
 import { opCustom } from './ops/custom-op.js'
 import { opUnits } from './ops/units-op.js'
 import { opBalance } from './ops/balance-op.js'
+import { opBodies } from './ops/bodies-op.js'
+import { KIND_LABEL, empiricalNoteOf } from './empirical-decomposition.js'
+import { cacheKey, clearCache, getCached, setCached } from './result-cache.js'
 
 // ────────────────────────────────────────────────────────────────────────────
 // 类型
@@ -228,6 +242,22 @@ export interface MathResult {
   value?: JsonValue
   variables?: { [key: string]: JsonValue }
   error?: { type: string; message: string; hint?: string }
+  /**
+   * 本次结果来自缓存（未重新计算）。
+   *
+   * 为什么要暴露：AI 需要知道「这个数是刚算的还是回忆的」——
+   * 若它以为自己刚验证过而实际只是缓存，会把「没改过设定」误当成「验证通过」。
+   * 改动常数或切换工作区后缓存键会变，所以不会出现「改了设定还拿旧值」。
+   */
+  cached?: boolean
+  /**
+   * 附加提示（渲染时展示给模型，**不进入 `result`**）。
+   *
+   * 为什么要分开：`result` 是数据通道，调用方会做精确相等比较；
+   * 往里拼提示会让 `0.1+0.2` 从 `0.3` 变成两行，破坏所有精确断言。
+   * 提示属于「给人/模型看的说明」，走这个字段即可。
+   */
+  notice?: string
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -246,6 +276,18 @@ export function configureDetector(config: Partial<DetectorConfig>): Partial<Dete
 }
 
 const DEFAULT_PRECISION = 64
+/**
+ * 显示精度默认值：**小数点后 8 位**。
+ *
+ * 为什么不默认「完整输出」：64 位小数一条结果就是六十五个字符，
+ * 人和 AI 都得自己截断。8 位小数对创作与工程核对都够用，
+ * 而整数永远完整输出（`10^20+5` 不受影响）。
+ *
+ * 为什么是 8 而不是 6：6 位小数在千级数字上只剩 `5307.267206`，
+ * 而实测常见需求（月供、速度、重力）到这个精度就够；
+ * 再少会让「1.5 倍重力 = 14.71 m/s²」这类值看着不够准。
+ */
+const DEFAULT_DISPLAY_PRECISION = 8
 const MIN_PRECISION = 1
 const MAX_PRECISION = 256
 const DEFAULT_VARIABLE = 'x'
@@ -257,6 +299,14 @@ const MAX_INPUT_LENGTH = 4_000
  * 留给「世界观推演」足够大的复杂网络。再大就接近 1~2 秒，性价比下降。
  */
 const MAX_MATRIX_SIZE = 200
+/**
+ * 批量求值的条数上限。
+ *
+ * 为什么不设很大：批量是为了省往返，不是拿来跑百万条数据的。
+ * 100 条已能覆盖「一个表格的几列」这类常见需求；再多应该走
+ * 代码沙箱/数据引用（本插件不做），否则结果文本本身就把上下文撑满了。
+ */
+const MAX_BATCH_EXPRESSIONS = 100
 
 const OPERATIONS: readonly MathOperation[] = [
   'auto',
@@ -287,6 +337,7 @@ const OPERATIONS: readonly MathOperation[] = [
   'custom',
   'units',
   'balance',
+  'bodies',
   'help',
 ]
 
@@ -518,11 +569,86 @@ function opEvaluate(engine: any, expression: string, scope: Record<string, any>,
 
   const value = unwrapResult(raw)
   return {
-    result: formatValue(engine, value, precision),
+    result: formatValue(engine, value, precision, currentDisplayPrecision()),
     value: toJsonValue(value),
   }
 }
 
+/**
+ * 批量求值（operation=evaluate 的批量模式）。
+ *
+ * ## 为什么要批量
+ *
+ * 每次工具调用都有固定开销：一次往返 + 结果文本进入上下文。
+ * 算 5 个式子的代价是 5 次往返；批量把 5 次压成 1 次。
+ *
+ * ## 设计要点
+ *
+ * 1. **逐条独立报错**：一条失败不影响其它条 —— 作者常常一次问五件事，
+ *    其中一条写错不该让另外四条白算。
+ * 2. **失败也占用输出行**：明确写出哪条错了、错在哪，而不是静默跳过
+ *    （静默跳过会让人以为「这条没算」而不是「这条错了」）。
+ * 3. **结果紧凑**：一行一条 `表达式 = 值`，不逐条输出完整诊断块。
+ *
+ * @param engine - mathjs 实例
+ * @param expressions - 待算的表达式数组
+ * @param scope - 变量作用域
+ * @param precision - 计算精度
+ * @returns 结果文本与结构化值
+ */
+function opEvaluateBatch(
+  engine: any,
+  expressions: string[],
+  scope: Record<string, any>,
+  precision: number,
+): Outcome {
+  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: string[] = []
+  const values: Array<{ expression: string; ok: boolean; result?: string; error?: 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' })
+      shown.push('  （空表达式）→ 跳过')
+      failCount++
+      continue
+    }
+    try {
+      const node = engine.parse(expression)
+      guardAst(node)
+      guardComplexity(node)
+      const value = unwrapResult(node.evaluate(scope))
+      const text = formatValue(engine, value, precision, currentDisplayPrecision())
+      values.push({ expression, ok: true, result: text })
+      shown.push('  ' + expression + ' = ' + text)
+      successCount++
+    } catch (error) {
+      const translated = translateError(error)
+      values.push({ expression, ok: false, error: translated.type })
+      // 失败要显眼，但不能长篇大论 —— 一行说清哪条、什么类型
+      shown.push('  ' + expression + ' → 失败[' + translated.type + ']' +
+        (translated.hint ? '：' + translated.hint : ''))
+      failCount++
+    }
+  }
+
+  const header = items.length < expressions.length
+    ? `═══ 批量求值（前 ${items.length} 条，共给了 ${expressions.length} 条）═══`
+    : `═══ 批量求值（${items.length} 条）═══`
+
+  return {
+    result: [header, '', ...shown, '', `成功 ${successCount}，失败 ${failCount}`].join('\n'),
+    value: toJsonValue({ count: items.length, success: successCount, failed: failCount, items: values } as never),
+  }
+}
+
 function opDerivative(expression: string, variable: string, precision: number): Outcome {
   const text = normalizeSource(expression)
   if (text === '') throw new CalcError('invalid_argument', '表达式为空')
@@ -982,7 +1108,7 @@ function opMatrix(expression: string, engine: any, precision: number, args: Math
     throw translateError(error)
   }
   return {
-    result: formatValue(engine, raw, precision),
+    result: formatValue(engine, raw, precision, currentDisplayPrecision()),
     value: toJsonValue(raw),
   }
 }
@@ -1394,33 +1520,21 @@ function currentFormulas(): FormulaType[] {
 }
 
 /** 在当前工作区的公式表里检索。 */
+/**
+ * 在当前工作区的公式集里检索。
+ *
+ * ⚠️ 检索逻辑**必须**复用 `scoreFormulas`，不能在这里再写一份。
+ * 曾经这里复制了 `findFormulas` 的旧实现（只做整串子串匹配），
+ * 于是 `formulas.ts` 里的检索修好了，这个走工作区集的副本还是旧的：
+ * 工具里查「贷款月供」0 条，而单元测试直接调 `findFormulas` 全绿 —— 测试骗了自己。
+ * 现在两边共用一份，差异只剩「检索哪一批公式」。
+ *
+ * @param query - 查询串
+ * @param limit - 最多返回条数
+ * @returns 按相关度排序的公式
+ */
 function findInCurrentWorkspace(query: string, limit: number) {
-  const formulas = currentFormulas()
-  const text = query.trim().toLowerCase()
-  if (text === '') return []
-
-  const scored: Array<{ formula: FormulaType; score: number }> = []
-  for (const formula of formulas) {
-    let score = 0
-    const id = formula.id.toLowerCase()
-    if (id === text) score += 5000
-    else if (id.includes(text)) score += 800
-    for (const key of formula.keys ?? []) {
-      const lowered = String(key).toLowerCase()
-      if (lowered === text) score += 2000
-      else if (lowered.includes(text)) score += 400
-    }
-    if (formula.name === query) score += 3000
-    else if (formula.name.includes(query)) score += 700
-    else if (formula.name.toLowerCase().includes(text)) score += 350
-    if (formula.desc.toLowerCase().includes(text)) score += 80
-    if (formula.cat.toLowerCase().includes(text)) score += 20
-    if (score > 0) scored.push({ formula, score })
-  }
-  return scored
-    .sort((left, right) => right.score - left.score || left.formula.id.localeCompare(right.formula.id))
-    .slice(0, limit)
-    .map((entry) => entry.formula)
+  return scoreFormulas(currentFormulas(), query, limit)
 }
 
 function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
@@ -1429,8 +1543,17 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
     throw new CalcError('invalid_argument', '需要 formula 参数', '传公式 id 或名称，例如 "escape_velocity"、"逃逸速度"。用 operation="formulas" 检索。')
   }
 
-  const matches = findInCurrentWorkspace(query, 5)
-  if (matches.length === 0) {
+  /**
+   * 单个公式解析用**严格匹配**，不用模糊检索。
+   *
+   * `formulas`（检索）和 `formula`（求值）的取向相反：
+   *   检索要「想得到」，模糊是对的；
+   *   求值要「指哪儿打哪儿」，模糊会把 `'不存在xyz'` 里的子词「公式」
+   *   匹配到别的公式，于是报 `missing_params` 而不是 `unknown_formula`，
+   *   模型以为公式找到了、只是缺参数，去补一堆无关参数。
+   */
+  const formula = resolveFormulaStrict(currentFormulas(), query)
+  if (!formula) {
     throw new CalcError(
       'unknown_formula',
       `没有匹配 "${query}" 的公式`,
@@ -1438,7 +1561,6 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
     )
   }
 
-  const formula = matches[0]
   const overrides = (args.overrides ?? {}) as Record<string, number | string>
 
   let resolved: { values: Record<string, unknown>; overridden: string[]; missing: string[] }
@@ -1510,9 +1632,36 @@ function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
   }
 
   const parts = [describeFormula(formula, expression, resolved.values, resolved.overridden)]
-  parts.push(`结果: ${formatValue(engine, raw, precision)}${formula.unit ? ` ${formula.unit}` : ''}`)
-  if (matches.length > 1) {
-    parts.push(`（另有 ${matches.length - 1} 条相近公式，可用更精确的 id 指定）`)
+  parts.push(`结果: ${formatValue(engine, raw, precision, currentDisplayPrecision())}${formula.unit ? ` ${formula.unit}` : ''}`)
+
+  /**
+   * 经验公式的适用性提示。
+   *
+   * 为什么要挂在输出里：一批经验式把常数**烘焙进了系数**
+   * （船舶航速 1.34 里藏着 g=9.81、宜居带 1.1 隐含地球温室条件）。
+   * 作者在非地球世界里照抄会算错，而且错得隐蔽——数字看着正常，只是用了地球常数。
+   *
+   * 三级标注（2026-10-26 修订）：
+   *   dimensionless         形式与数值都跨世界成立
+   *   scalable-with-caveat  形式可泛化，但系数需重新验证
+   *   earth-only            仅在地球成立，换世界必须换公式
+   *
+   * 关键区分：**形式可泛化 ≠ 系数可直接用**。上一版把两者混为一谈，
+   * 等于宣称 Fr=0.4 换世界也精确成立——那是过度自信。
+   */
+  const empiricalNote = empiricalNoteOf(formula.id)
+  if (empiricalNote) {
+    parts.push('')
+    parts.push('【适用域：' + KIND_LABEL[empiricalNote.kind] + '】')
+    if (empiricalNote.principle) parts.push('  底层原理：' + empiricalNote.principle)
+    if (empiricalNote.bakedIn) parts.push('  藏了什么：' + empiricalNote.bakedIn)
+    if (empiricalNote.genericForm) parts.push('  可沿用的形式：' + empiricalNote.genericForm)
+    if (empiricalNote.retuneNeeded) parts.push('  必须重新标定的：' + empiricalNote.retuneNeeded)
+    if (empiricalNote.breaksWhen) parts.push('  何时失效：' + empiricalNote.breaksWhen)
+    if (empiricalNote.advice) parts.push('  建议：' + empiricalNote.advice)
+    if (empiricalNote.needsFrom && empiricalNote.needsFrom.length > 0) {
+      parts.push('  需要这些量：' + empiricalNote.needsFrom.join('、'))
+    }
   }
 
   return {
@@ -1696,6 +1845,8 @@ function opHelp(): Outcome {
       '【求值与代数】',
       '  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）',
@@ -1741,7 +1892,26 @@ function opHelp(): Outcome {
       '【世界观推演】',
       '  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         单位换算：把「三里」「两丈」「五百斤」换成标准单位',
@@ -1751,6 +1921,10 @@ function opHelp(): Outcome {
       '  balance       收支盘点：粮/水/能/地/财政/军费/信息 多项一起看，给最短板',
       '                例：balance={grain:{demand:2.7e6,supply:3.1e6,unit:"kg/年"}}',
       '                回答「这个王国养不养得起二十万兵」这类问题（feasibility 只管单项上限）',
+      '  bodies        天体目录：太阳系 8 大行星 + 卫星 + 代表性系外行星 + 各亮度级恒星',
+      '                例：bodyName="mars" / bodyKind="moon" / 不带参数列全部',
+      '                bodyConstant="alpha_fs", bodyFactor=2 → 看改常数后哪些天体数据要重算',
+      '                （关键：行星质量/半径/轨道与 α 无关，绝不跟着改）',
       '',
       '【数据管理】',
       '  workspace     工作区管理（一个世界观 = 一套常数表 + 公式表 + 地点 + 变量）',
@@ -1808,9 +1982,74 @@ export function runMathTool(rawArguments: unknown): MathResult {
 
   let operation: MathOperation = 'auto'
   let precision = DEFAULT_PRECISION
+  /** 显示有效位数；undefined = 未设定（沿用计算精度，即完整输出）。 */
+  let displayPrecision: number | undefined
 
   try {
     precision = clampPrecision(args.precision)
+    /**
+     * 显示精度：本次显式给 > 工作区固化值 > 沿用计算精度。
+     *
+     * 优先级这样排，是为了让「临时想看更多」不必改工作区设置：
+     *   · 对话开始时定一次（workspace set displayPrecision）
+     *   · 某次需要更多，那一次单独传 displayPrecision 即可
+     */
+    /**
+     * 显示精度：本次显式给 > 工作区固化值 > **默认 8 位小数**。
+     *
+     * ## 为什么默认不是「完整输出」
+     *
+     * 原来未设时按 64 位全吐，结果一条公式回来六十五个数字，
+     * 人和 AI 都得自己截断才能读。默认 8 位小数后：
+     *   · 月供 5307.26720623（可读）
+     *   · 整数照旧完整（10^20+5 仍是 21 位）
+     *
+     * ## 8 是「小数点后 8 位」，不是 8 位有效数字
+     *
+     * 这点很关键：有效数字语义下 `12345.678901234` 只会给 3 位小数，
+     * 与「保留 8 位」的直觉不符。
+     *
+     * ## 需要更多时
+     *
+     * 单次传 `displayPrecision` 即可（如 12），或固化到工作区。
+     * 大整数/数论场景整数本就完整，不受影响。
+     */
+    /**
+     * 显示精度优先级：本次 displayPrecision > 工作区固化 > **由 precision 推出** > 默认 8 位。
+     *
+     * ## 为什么要看 precision
+     *
+     * 原来未设显示精度时一律用默认 8 位小数，结果 `precision:30` 算出的
+     * `1/3` 只显示 `0.33333333` —— 调用方明确要求 30 位却只给 8 位，
+     * 这是把「计算精度」的心智模型搞坏了。
+     *
+     * 判据：只要调用方**显式**给了 precision（且不是默认值），
+     * 就认为他想要看到那么多位，显示位数取 precision。
+     * 没显式给时才回落默认 8 位。
+     */
+    const explicitPrecision = args.precision !== undefined && Number.isFinite(Number(args.precision))
+    const explicitDisplay = clampDisplayPrecision(args.displayPrecision) !== undefined
+    displayPrecision =
+      clampDisplayPrecision(args.displayPrecision) ??
+      displayPrecisionOf() ??
+      (explicitPrecision ? Math.min(64, precision) : DEFAULT_DISPLAY_PRECISION)
+    /**
+     * 记录「显示精度是否由调用方显式指定」。
+     *
+     * 用途：只有用默认值时才提醒「精度可能不够」。
+     * 调用方自己写 `displayPrecision:2` 时，截断是他的意图，再提醒就啰嗦了。
+     *
+     * 另外每次调用开头都要清空损失统计，否则上一轮的误差会挂到本轮结果上。
+     */
+    setDisplayPrecisionExplicit(explicitDisplay)
+    consumePrecisionLoss()
+    /**
+     * 设成模块级，让 trimNumber（solve / matrix / stats 等四十多个调用点）自动生效。
+     *
+     * 不逐个改函数签名，是因为「显示精度在一次调用内全局一致」——
+     * 入口设一次即可，各层读同一个值。
+     */
+    setActiveDisplayPrecision(displayPrecision)
     const variable = normalizeVariable(args.variable)
     const requested = normalizeOperation(args.operation)
     const known = knownNumbers(args.variables)
@@ -1844,7 +2083,106 @@ export function runMathTool(rawArguments: unknown): MathResult {
       }
     }
 
+    /**
+     * ── 缓存查询 ──
+     *
+     * 只缓存**纯计算型** operation：它们的结果只取决于参数、常数与工作区，
+     * 不随时间变化。`world`/`derivation`/`impact`/`bodies` 这类也确定，
+     * 但输出较长、不是高频重复对象，缓存收益低于占位成本，故不纳入。
+     *
+     * `workspace` / `formula-table` / `promptMode` 有**副作用**（会改状态），
+     * 绝不能缓存 —— 命中会跳过副作用，行为就变了。
+     *
+     * 键里必须含常数与工作区指纹：改常数后同一式子结果不同，
+     * 漏了这条会静默返回「改之前」的数。
+     */
+    const CACHEABLE: MathOperation[] = [
+      'auto', 'evaluate', 'solve', 'system', 'derivative', 'integral',
+      'simplify', 'expand', 'roots', 'matrix', 'eigen', 'stats', 'dist',
+      'regression', 'ode', 'formula', 'units',
+    ]
+    /**
+     * 状态变更类操作：先清空缓存，再走正常流程。
+     *
+     * 为什么必须在**查询之前**清：这些操作会改变后续计算的结果
+     * （改公式表覆盖、切工作区、改常数、改显示精度），
+     * 而其自身不在 CACHEABLE 里，所以不会被缓存命中 ——
+     * 但它们影响过的**下游计算**仍在缓存里，不清就会拿到旧值。
+     *
+     * 实测踩到：先覆盖 kinetic_energy 公式算出 18，移除覆盖后
+     * 再算同一公式仍得 18（缓存命中），而正确答案是 9。
+     * 这类错很隐蔽——两个数都是「算出来的」，只是后者属于旧公式表。
+     */
+    const MUTATING: MathOperation[] = ['workspace', 'formula-table']
+    if (MUTATING.includes(operation)) {
+      clearCache()
+    }
+
+    let cacheHitKey: string | undefined
+    if (CACHEABLE.includes(operation)) {
+      try {
+        /**
+         * 缓存键用**整个 args 的稳定序列化**，而不是手动列举几个参数。
+         *
+         * 为什么改（踩过）：最初只列了 expression/formula/overrides/data 等几项，
+         * 结果 `dist` 的 `distribution`/`params`/`x` 没进键 ——
+         * 先算正态分布、再算二项分布时**命中了正态的结果**，
+         * 二项 PMF 返回了正态的 PDF。这类串键的错最难发现（结果看着像个正常的数）。
+         *
+         * 现在把 args 全量序列化（排除纯显示选项），漏一个参数的可能性归零。
+         * 代价是多算几次字符串，与「算错」比起来不值一提。
+         */
+        const { displayPrecision: _dp, promptMode: _pm, ...restForCache } = args as Record<string, unknown>
+        /**
+         * 键里要带「显示精度是否显式」这一位。
+         *
+         * 踩过：显式传 `displayPrecision:8` 与用默认值 8 是**同一个数值**，
+         * 键就撞了 —— 显式调用命中了默认调用的缓存，连带返回那条
+         * 「精度不足」提示（默认调用才该有）。结果作者自己指定了精度，
+         * 却被告知「精度不够，请调高」，自相矛盾。
+         *
+         * 两者的输出确实不同（提示有无），所以键必须区分。
+         */
+        const key = cacheKey([
+          operation,
+          precision,
+          displayPrecision ?? -1,
+          explicitDisplay ? 'explicit' : 'default',
+          stableArgs(restForCache),
+          activeWorkspaceNameForCache(),
+          constantsFingerprint(),
+        ])
+        const cached = getCached(key)
+        if (cached !== undefined) {
+          cacheHitKey = key
+          // 命中：直接返回，但仍标注是缓存结果，便于观察
+          return { ...(cached as MathResult), cached: true }
+        }
+        cacheHitKey = key
+      } catch {
+        /* 缓存键构造失败不影响计算（可能含不可序列化的参数） */
+      }
+    }
+
     let outcome: Outcome
+    /**
+     * 批量模式优先：给了 expressions 就走批量，忽略单条 expression。
+     *
+     * 不缓存批量结果：批量通常是一次性探查（同一批式子很少重复出现），
+     * 缓存它们只会挤占单条计算的位置。
+     */
+    if (Array.isArray(args.expressions) && args.expressions.length > 0) {
+      outcome = opEvaluateBatch(engine, args.expressions, scope, precision)
+      const batchResult: MathResult = {
+        ok: true,
+        operation: 'evaluate',
+        input: args.expressions.join(' ; ').slice(0, 200),
+        result: outcome.result,
+        precision,
+      }
+      if (outcome.value !== undefined) batchResult.value = outcome.value
+      return batchResult
+    }
     switch (operation) {
       case 'help':
         outcome = opHelp()
@@ -1927,6 +2265,9 @@ export function runMathTool(rawArguments: unknown): MathResult {
       case 'balance':
         outcome = opBalance(args)
         break
+      case 'bodies':
+        outcome = opBodies(args)
+        break
       case 'evaluate':
       default:
         outcome = opEvaluate(engine, input, scope, precision)
@@ -1944,6 +2285,55 @@ export function runMathTool(rawArguments: unknown): MathResult {
     const variables = scopeSummary(args.variables)
     if (variables !== undefined) result.variables = variables
 
+    /**
+     * ── 显示精度提示（方案 B）──
+     *
+     * 放进独立的 `notice` 字段，**不拼进 `result`**：
+     * `result` 是数据通道，做精确相等断言的调用方依赖它保持干净；
+     * `notice` 只在渲染时展示给模型看。
+     *
+     * 确定性：没固化 + 结果有小数 → 每次都带同样的提示，
+     * 所以「同输入同输出」不受影响。
+     */
+    const hintNote = maybeDisplayPrecisionHint(result.result)
+    if (hintNote) result.notice = hintNote
+
+    /**
+     * ── 精度不足提醒 ──
+     *
+     * 与上面那条「可以调精度」不同：这条是**具体的**——本次结果真的因为位数不够
+     * 而丢了精度。判据是相对误差超过万分之一。
+     *
+     * ## 什么时候该提醒
+     *
+     * 例：`0.00000123456789` 在 8 位小数下变成 `0.00000123`，
+     * 相对误差约 0.3%。作者看到这个数会以为是精确值，实际已经偏了。
+     * 而 `1/7` 在 8 位小数下误差约 1e-9，完全不用提。
+     *
+     * ## 什么时候不提醒
+     *
+     * 调用方自己指定了 `displayPrecision` 时不提 —— 那是他的选择。
+     *
+     * 取「两条提示取更强的」：精度损失提示优先于泛泛的「可以调」提示。
+     */
+    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()
+    }
+
     /**
      * 非有限结果的处理：**数值型** operation 才算错误，分析型的不算。
      *
@@ -1974,6 +2364,14 @@ export function runMathTool(rawArguments: unknown): MathResult {
         '常见于除以零、tan(π/2)、log(0)。若要符号形式可改用 operation="simplify"。',
       )
     }
+    // 写缓存（只在成功路径；错误不缓存，否则同一个错会一直被命中）
+    if (cacheHitKey !== undefined) {
+      try {
+        setCached(cacheHitKey, result)
+      } catch {
+        /* 写入失败不影响返回 */
+      }
+    }
     return result
   } catch (error) {
     const translated = translateError(error)
@@ -2008,6 +2406,136 @@ function clampPrecision(value: unknown): number {
   return Math.min(MAX_PRECISION, Math.max(MIN_PRECISION, Math.round(numeric)))
 }
 
+/**
+ * 首次调用时提示显示精度可调（方案 B）。
+ *
+ * ## 为什么需要这个
+ *
+ * 提示词里的「开工时定一次显示精度」实测没被触发：它在注入文本第 607 字符，
+ * 而且「开工」这个时机对模型并不存在（每轮都像「继续」）。
+ *
+ * 但**拿到结果的那一刻**不同：模型手上正拿着一个被截断过的小数，
+ * 这时说「这个位数可以调」才有说服力 —— 需求在眼前，建议才有效。
+ *
+ * ## 为什么放进独立的 notice 字段，而不是拼进 result
+ *
+ * 试过拼进 result，代价太大：一条 `0.1+0.2` 的结果从 `0.3` 变成两行，
+ * 所有做**精确相等**断言的调用方（测试、脚本、下游工具）全部失效 ——
+ * 实测一次跑挂 8 个套件。
+ *
+ * `result` 是数据通道，必须保持干净；`notice` 只用于渲染给模型看。
+ *
+ * ## 为什么不用「每会话只提示一次」
+ *
+ * 那个版本破坏了「同输入同输出」的确定性（第一次带提示、第二次不带）。
+ * 现在改成确定性判断：没固化 + 结果里有小数 → 每次都带。
+ *
+ * @param resultText - 已格式化的结果文本
+ * @returns 提示文本；不该提示时返回空串
+ */
+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 固化 —— 固化后此提示消失。'
+    )
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 常数指纹：把当前生效的常数压成一个稳定字符串，用于缓存键。
+ *
+ * 为什么必须有它：改了 c 之后，同样的表达式结果不同。
+ * 若缓存键不含常数，命中时会返回「改之前」的数 —— 那是静默错误，
+ * 而且是本插件最不能出的那种错（作者以为看到的是新宇宙的结果）。
+ *
+ * 只取**基础旋钮**就够：派生量由它们唯一决定。
+ *
+ * @returns 指纹字符串
+ */
+function constantsFingerprint(): string {
+  try {
+    const active = getActiveConstants() as Record<string, unknown>
+    const keys = Object.keys(active).sort()
+    return keys.map(function (key) {
+      const value = active[key]
+      return key + '=' + (typeof value === 'number' ? value.toPrecision(15) : String(value))
+    }).join(';')
+  } catch {
+    // 读不到就返回随机值，等于禁用缓存（宁可慢，不可错）
+    return 'unknown-' + Math.random()
+  }
+}
+
+/**
+ * 当前工作区名（缓存键用）。
+ *
+ * 不同工作区有各自的公式表、自定义常数与变量，
+ * 同一个表达式可能给出不同结果，所以必须进键。
+ *
+ * @returns 工作区名
+ */
+function activeWorkspaceNameForCache(): string {
+  try {
+    return currentWorkspace()
+  } catch {
+    return 'unknown-' + Math.random()
+  }
+}
+
+/**
+ * 把参数对象序列化成稳定字符串（缓存键用）。
+ *
+ * 与 `stableStringify` 的区别：这个专为「可能含各种嵌套」的调用参数而写，
+ * 遇到不可序列化的值就退化成类型标记 —— 宁可少命中，不可串键。
+ *
+ * @param value - 参数值
+ * @returns 稳定字符串
+ */
+function stableArgs(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  const kind = typeof value
+  if (kind === 'number') {
+    return Number.isFinite(value as number) ? (value as number).toPrecision(15) : String(value)
+  }
+  if (kind === 'string' || kind === 'boolean') return String(value)
+  if (Array.isArray(value)) return '[' + value.map(stableArgs).join(',') + ']'
+  if (kind === 'object') {
+    const object = value as Record<string, unknown>
+    const keys = Object.keys(object).sort()
+    return '{' + keys.map(function (key) {
+      return key + ':' + stableArgs(object[key])
+    }).join(',') + '}'
+  }
+  return '?' + kind
+}
+
+/**
+ * 解析**显示**精度。
+ *
+ * 与 `clampPrecision` 的区别：这个不影响计算，只影响写出来的位数，
+ * 所以允许更宽的范围（1—64）并且**允许返回 undefined**（= 不截断）。
+ *
+ * 传 0 视为「清除」，与工作区的约定一致。
+ *
+ * @param value - 原始参数
+ * @returns 显示位数；未给或非法返回 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)))
+}
+
 function normalizeVariable(value: unknown): string {
   if (typeof value !== 'string' || value.trim() === '') return DEFAULT_VARIABLE
   const trimmed = value.trim()
@@ -2047,6 +2575,16 @@ const OUTPUT_SCHEMA = {
     precision: { type: 'integer', required: true, description: '使用的精度' },
     value: { type: 'json', description: '机器可读结果' },
     variables: { type: 'object', additionalProperties: true, description: '本次使用的变量' },
+    /**
+     * 附加提示（渲染时展示，不进 `result`）。
+     *
+     * ⚠️ 必须声明在这里。宿主用 `additionalProperties: false` **校验**工具输出，
+     * 漏一个字段就会让整次调用判为「invalid output」而失败 ——
+     * 实测踩过：加了 notice 却忘了声明，`bodies` 调用直接被宿主拒绝。
+     */
+    notice: { type: 'string', description: '附加提示（显示精度/精度不足等）' },
+    /** 结果来自缓存（未重算）。同样必须声明，否则命中缓存时调用失败。 */
+    cached: { type: 'boolean', description: '是否命中缓存' },
     error: {
       type: 'object',
       additionalProperties: false,
@@ -2068,7 +2606,13 @@ function renderResult(value: any): Array<{ type: 'text'; text: string }> {
     return [{ type: 'text', text: hint ? `错误[${type}]: ${message}\n提示: ${hint}` : `错误[${type}]: ${message}` }]
   }
   const result = typeof payload.result === 'string' ? payload.result : String(payload.result ?? '')
-  return [{ type: 'text', text: result }]
+  /**
+   * notice 只在渲染时追加，不进 `result` 本身。
+   *
+   * 这样模型看得到提示，而依赖 `result` 精确相等的调用方不受影响。
+   */
+  const notice = typeof payload.notice === 'string' && payload.notice !== '' ? payload.notice : ''
+  return [{ type: 'text', text: notice ? `${result}\n\n（${notice}）` : result }]
 }
 
 const PARAMETER_SPEC = {
@@ -2078,6 +2622,12 @@ const PARAMETER_SPEC = {
       '数学表达式、方程或待处理数据。多方程用逗号分隔（3x + 2y = 10, x - y = 1）。' +
       '例：10^20 + 5、factorial(50)、x^3 * sin(x)、[[1,2],[3,4]] * [[5],[6]]、[1,2,3,4]。operation=help 时可空。',
   },
+  expressions: {
+    type: 'array',
+    description:
+      '批量求值（operation=evaluate）：一次算多条，省多次往返。' +
+      '逐条独立报错，一条失败不影响其它条。例：["1/7","2^0.5","log(10)"]。',
+  },
   variables: {
     type: 'object',
     additionalProperties: true,
@@ -2086,10 +2636,11 @@ const PARAMETER_SPEC = {
   operation: {
     type: 'string',
     enum: OPERATIONS,
+    // 不逐个解释每个 operation 名称：enum 里已经列全，而 `help` 有完整说明。
+    // 这里只给「怎么选」的判断线索，那才是 AI 真正需要的。
     description:
-      '默认 auto。evaluate=求值，solve=解方程（多方程自动识别为线性方程组），system=显式线性系统，' +
-      'derivative=求导，integral=符号积分，simplify=化简，expand=展开，roots=多项式求根，' +
-      'matrix=矩阵运算，eigen=特征值/特征向量，stats=描述统计，dist=概率分布，regression=回归，help=能力清单。',
+      '默认 auto。简易算式用 evaluate；数据用 stats/dist/regression；' +
+      '改动设定后用 world/derivation；不确定就调 help 看全表。',
   },
   variable: {
     type: 'string',
@@ -2116,17 +2667,51 @@ const PARAMETER_SPEC = {
     type: 'array',
     description:
       '项目自定义单位，可覆盖内置（如把「里」定成 576 m）。' +
-      '每项 {name, dimension, factor, aliases?, note?}，factor 是换成该量纲基准单位的系数。' +
-      'dimension 可用：length/mass/time/area/volume/energy/power/temperature/speed。',
+      '每项 {name, dimension, factor}；dimension 见 help。',
   },
   balance: {
     type: 'object',
     additionalProperties: true,
     description:
-      '收支盘点（operation=balance）。每项 {demand: 需求量, supply: 能提供多少, unit?: 单位}。' +
-      '内置键名 grain/water/energy/land/fiscal/army/info，也可自定。' +
-      '给最短板 K=min(supply/demand)，回答「几项一起看这个势力撑不撑得住」。' +
-      '只判社会收支；单项生理/工程上限请用 feasibility。',
+      '收支盘点（operation=balance）：每项 {demand, supply, unit?}，给最短板。' +
+      '只判社会收支；单项生理/工程上限用 feasibility。',
+  },
+  bodyName: {
+    type: 'string',
+    description:
+      '查单个天体（operation=bodies）。可给 id（mars）或中文名（火星）。' +
+      '已收录太阳系全 8 大行星 + 月球类卫星 + 代表性系外行星 + 矮行星 + 各亮度级恒星。',
+  },
+  bodyKind: {
+    type: 'string',
+    description:
+      '按类别筛天体（operation=bodies）：star / planet-terrestrial / planet-super-earth / ' +
+      'planet-mini-neptune / planet-gas-giant / moon / dwarf-planet / asteroid。',
+  },
+  bodyConstant: {
+    type: 'string',
+    description:
+      '改常数后看天体数据哪些该重算（operation=bodies）。' +
+      '例：bodyConstant="alpha_fs", bodyFactor=2 —— α 变成两倍，' +
+      '输出分「必须重算的量」与「绝不该动的量」两块。' +
+      '后者尤其重要：行星质量、半径、轨道与 α 无关，跟着改就是篡改设定。',
+  },
+  bodyFactor: {
+    type: 'number',
+    description: '常数变化倍数（operation=bodies，默认 2）。',
+  },
+  bodyType: {
+    type: 'string',
+    description:
+      '查天体**类型**（operation=bodies）。与 bodyName 的区别：bodyName 查具名天体（火星、木卫二），' +
+      'bodyType 查类型学条目（中子星、热木星、流浪行星、戴森球）。' +
+      '每个类型都标了证据等级，并列明「物理锁死项」（编不了）与「可自由发挥项」。',
+  },
+  bodyEvidence: {
+    type: 'string',
+    description:
+      '按证据等级筛天体类型（operation=bodies）：observed（已观测）/ ' +
+      'theoretical（理论预言，物理必然但未直接观测）/ speculative（纯思辨）。',
   },
   matrix: {
     type: 'array',
@@ -2138,7 +2723,18 @@ const PARAMETER_SPEC = {
   },
   precision: {
     type: 'integer',
-    description: 'BigNumber 有效数字位数，默认 64，范围 1-256。',
+    description:
+      '**计算精度**：BigNumber 有效数字位数，默认 64，范围 1-256。' +
+      '⚠️ 不要为了「输出好看」调低它——它决定计算的正确性：' +
+      '`(10^20+1)-(10^20)` 在 precision=20 时会得 0（应为 1）。' +
+      '只想让输出短一些，用 displayPrecision。',
+  },
+  displayPrecision: {
+    type: 'integer',
+    description:
+      '**显示精度：小数点后几位**（0-64，默认 8）。只截小数，整数永远完整。' +
+      '例 8 → 1/7 得 0.14285714。全局换档用 workspace set displayPrecision=N。' +
+      '别用 precision 达此目的（会算错大数）。',
   },
   data: {
     type: 'array',
@@ -2214,14 +2810,12 @@ const PARAMETER_SPEC = {
   world: {
     type: 'object',
     additionalProperties: true,
+    // 字段清单不写在 schema 里：schema 每轮都要付费，而这些字段只在
+    // 真用 world 时才需要。全文见 help（operation="help", query="world"）。
     description:
-      'operation="world" 的世界参数，**全部可选，默认地球**。只改你想改的那几个即可。\n' +
-      '恒星：starMass(太阳质量)、starRadius(太阳半径)、starTemp(K,默认5778)\n' +
-      '轨道：orbitAU(AU,默认1)、eccentricity(默认0.0167)\n' +
-      '行星：planetMass(地球质量,默认1)、planetRadius(地球半径,默认1)、rotationHours(默认23.93)、obliquityDeg(默认23.44)、albedo(默认0.306)\n' +
-      '大气：pressure(Pa,默认101325)、molarMass(kg/mol,默认0.02896)、gamma(默认1.4)、greenhouse(增温K,默认33)\n' +
-      '地表：materialStrength(Pa,默认1.3e8花岗岩)、materialDensity(默认2700)\n' +
-      '例：{"planetRadius":1.4,"rotationHours":40,"obliquityDeg":45,"greenhouse":10}',
+      '星球参数（operation=world），全部可选，默认地球。' +
+      '常用键：planetMass/planetRadius（地球倍数）、starMass/starTemp、rotationHours、obliquityDeg、greenhouse。' +
+      '完整字段表见 help 的 world 条目。',
   },
   planetRadius: {
     type: 'number',
@@ -2242,24 +2836,18 @@ const PARAMETER_SPEC = {
   terrain: {
     type: 'object',
     additionalProperties: true,
+    // 同上：地形字段有九项，逐项列在 schema 里太贵。
     description:
-      'operation="world" 的局部地形推演。给了就会额外输出该地点的气候细节。\n' +
-      'kind: coastal/plain/plateau/mountain/valley/desert/forest/tundra/island/lake\n' +
-      'elevation: 海拔 m | distanceToSea: 距海 km | latitudeDeg: 纬度\n' +
-      'annualPrecipMm: 基准年降水 mm | humidity: 0-1\n' +
-      'windward: 1=迎风坡, -1=背风坡 | reliefHeight: 山峰相对高度 m\n' +
-      'oceanCurrent: warm/cold/none | surface: soil/sand/rock/ice/water/vegetation\n' +
-      '例：{"kind":"coastal","elevation":20,"distanceToSea":5,"latitudeDeg":60,"oceanCurrent":"warm"}',
+      '局部地形（operation=world 附带），给了就额外输出该地点气候细节。' +
+      '常用键：kind、elevation、latitudeDeg、oceanCurrent。完整键表见 help。',
   },
   constants: {
     type: 'object',
     additionalProperties: true,
+    // 旋钮清单移进 help：只有要改常数时才需要，不该每轮付费
     description:
-      'operation="constants" 要改的物理常数（**只能改基础旋钮**，派生量会自动重算）。\n' +
-      '基础旋钮: c(光速) / G(引力常数) / h(普朗克) / kB(玻尔兹曼) / e_charge(元电荷) / ' +
-      'me(电子质量) / mp(质子质量) / NA(阿伏伽德罗) / epsilon0(真空介电常数)\n' +
-      '派生量（会自动跟随，不能直接改）: hbar, R, mu0, kCoulomb, sigma, bWien, alpha_fs, Ry, muB\n' +
-      '例：{"c": 1.5e8} 会让 mu0/sigma/alpha_fs 等自动重算，并评估世界偏离程度。',
+      '要改的物理常数（operation=constants），只能改基础旋钮，派生量自动重算。' +
+      '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 条目。',
   },
 } as const