dsh-math-calculator 2.0.0 → 2.1.0

package/lib/index.js

@@ -27,15 +27,17 @@ import { containsNonFinite, formatValue, toFiniteNumber, toJsonValue, unwrapResu
 import { describe, binomialCdf, binomialPmf, chiSquareCdf, exponentialCdf, linearRegression, normalCdf, normalInv, normalPdf, poissonCdf, poissonPmf, polynomialRegression, quantile, studentTCdf, } from './stats.js';
 import { SymbolicError, symbolicDerivative, symbolicExpand, symbolicIntegral, symbolicRootsWithComplex, symbolicSimplify, } from './symbolic.js';
 import { parseLinearEquation, solveLinearSystem_, splitEquations, } from './systems.js';
-import { FormulaError, buildFormulaScope, describeFormula, listFormulasByFrequency, listFormulaCategories, resolveExpression, resolveParams, } from './formulas.js';
+import { FormulaError, buildFormulaScope, describeFormula, listFormulasByFrequency, listFormulaCategories, resolveExpression, resolveParams, resolveFormulaStrict, scoreFormulas, } from './formulas.js';
 import { BUILTINS } from './formula-builtins.js';
-import { currentWorkspace, loadWorkspace, bindHostWorkspace, cwdOfExec, cwdOfSession, scopeFromCwd, setLastExecShape, switchWorkspace, } from './workspace.js';
+import { getActiveConstants, } from './constants-graph.js';
+import { currentWorkspace, loadWorkspace, bindHostWorkspace, cwdOfExec, cwdOfSession, displayPrecisionOf, scopeFromCwd, setLastExecShape, switchWorkspace, } from './workspace.js';
 import { buildApiRoutes } from './api.js';
 import { materializeFormulas, } from './formula-table.js';
 import { FORMULAS } from './formulas.js';
 import { TOOL_DESCRIPTION, buildSystemPromptSection, setPromptMode, suggestOperation, } from './awareness.js';
 import { buildReminderMessage, recordPrompt, shouldPromptNow, } from './detector.js';
-import { CalcError, bignum, fast, normalizeSource, safeNumberForJson, trimNumber, } from './ops/shared.js';
+import { CalcError, bignum, currentDisplayPrecision, fast, normalizeSource, safeNumberForJson, setActiveDisplayPrecision, trimNumber, } from './ops/shared.js';
+import { PRECISION_LOSS_THRESHOLD, consumePrecisionLoss, isDisplayPrecisionExplicit, setDisplayPrecisionExplicit, } from './precision-report.js';
 import { opOde } from './ops/ode-op.js';
 import { opWorld } from './ops/world-op.js';
 import { opConstants } from './ops/constants-op.js';
@@ -48,6 +50,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';
 // ────────────────────────────────────────────────────────────────────────────
 // 常量
 // ────────────────────────────────────────────────────────────────────────────
@@ -61,6 +66,18 @@ export function configureDetector(config) {
     return detectorConfig;
 }
 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';
@@ -72,6 +89,14 @@ const MAX_INPUT_LENGTH = 4_000;
  * 留给「世界观推演」足够大的复杂网络。再大就接近 1~2 秒，性价比下降。
  */
 const MAX_MATRIX_SIZE = 200;
+/**
+ * 批量求值的条数上限。
+ *
+ * 为什么不设很大：批量是为了省往返，不是拿来跑百万条数据的。
+ * 100 条已能覆盖「一个表格的几列」这类常见需求；再多应该走
+ * 代码沙箱/数据引用（本插件不做），否则结果文本本身就把上下文撑满了。
+ */
+const MAX_BATCH_EXPRESSIONS = 100;
 const OPERATIONS = [
     'auto',
     'evaluate',
@@ -101,6 +126,7 @@ const OPERATIONS = [
     'custom',
     'units',
     'balance',
+    'bodies',
     'help',
 ];
 /** 禁用标识符（防止把宿主全局塞进表达式）。 */
@@ -330,10 +356,76 @@ function opEvaluate(engine, expression, scope, precision) {
     }
     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, expressions, scope, precision) {
+    const items = expressions.slice(0, MAX_BATCH_EXPRESSIONS);
+    if (items.length === 0) {
+        throw new CalcError('invalid_argument', 'expressions 为空', '例如 ["1/7","2^0.5"]');
+    }
+    const shown = [];
+    const values = [];
+    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 }),
+    };
+}
 function opDerivative(expression, variable, precision) {
     const text = normalizeSource(expression);
     if (text === '')
@@ -763,7 +855,7 @@ function opMatrix(expression, engine, precision, args) {
         throw translateError(error);
     }
     return {
-        result: formatValue(engine, raw, precision),
+        result: formatValue(engine, raw, precision, currentDisplayPrecision()),
         value: toJsonValue(raw),
     };
 }
@@ -1161,54 +1253,40 @@ function currentFormulas() {
     return materialized.formulas;
 }
 /** 在当前工作区的公式表里检索。 */
+/**
+ * 在当前工作区的公式集里检索。
+ *
+ * ⚠️ 检索逻辑**必须**复用 `scoreFormulas`，不能在这里再写一份。
+ * 曾经这里复制了 `findFormulas` 的旧实现（只做整串子串匹配），
+ * 于是 `formulas.ts` 里的检索修好了，这个走工作区集的副本还是旧的：
+ * 工具里查「贷款月供」0 条，而单元测试直接调 `findFormulas` 全绿 —— 测试骗了自己。
+ * 现在两边共用一份，差异只剩「检索哪一批公式」。
+ *
+ * @param query - 查询串
+ * @param limit - 最多返回条数
+ * @returns 按相关度排序的公式
+ */
 function findInCurrentWorkspace(query, limit) {
-    const formulas = currentFormulas();
-    const text = query.trim().toLowerCase();
-    if (text === '')
-        return [];
-    const scored = [];
-    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, engine, precision) {
     const query = (args.formula ?? args.expression ?? '').trim();
     if (query === '') {
         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}" 的公式`, '用 operation="formulas" 按关键词检索，或直接 operation="evaluate" 写自己的表达式。');
     }
-    const formula = matches[0];
     const overrides = (args.overrides ?? {});
     let resolved;
     try {
@@ -1274,9 +1352,41 @@ function opFormula(args, engine, precision) {
         throw translateError(error);
     }
     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 {
         result: parts.join('\n'),
@@ -1455,6 +1565,8 @@ function opHelp() {
             '【求值与代数】',
             '  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）',
@@ -1500,7 +1612,26 @@ function opHelp() {
             '【世界观推演】',
             '  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         单位换算：把「三里」「两丈」「五百斤」换成标准单位',
@@ -1510,6 +1641,10 @@ function opHelp() {
             '  balance       收支盘点：粮/水/能/地/财政/军费/信息 多项一起看，给最短板',
             '                例：balance={grain:{demand:2.7e6,supply:3.1e6,unit:"kg/年"}}',
             '                回答「这个王国养不养得起二十万兵」这类问题（feasibility 只管单项上限）',
+            '  bodies        天体目录：太阳系 8 大行星 + 卫星 + 代表性系外行星 + 各亮度级恒星',
+            '                例：bodyName="mars" / bodyKind="moon" / 不带参数列全部',
+            '                bodyConstant="alpha_fs", bodyFactor=2 → 看改常数后哪些天体数据要重算',
+            '                （关键：行星质量/半径/轨道与 α 无关，绝不跟着改）',
             '',
             '【数据管理】',
             '  workspace     工作区管理（一个世界观 = 一套常数表 + 公式表 + 地点 + 变量）',
@@ -1565,8 +1700,73 @@ export function runMathTool(rawArguments) {
     const input = typeof args.expression === 'string' ? args.expression.trim() : '';
     let operation = 'auto';
     let precision = DEFAULT_PRECISION;
+    /** 显示有效位数；undefined = 未设定（沿用计算精度，即完整输出）。 */
+    let displayPrecision;
     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);
@@ -1592,7 +1792,106 @@ export function runMathTool(rawArguments) {
                 precision,
             };
         }
+        /**
+         * ── 缓存查询 ──
+         *
+         * 只缓存**纯计算型** operation：它们的结果只取决于参数、常数与工作区，
+         * 不随时间变化。`world`/`derivation`/`impact`/`bodies` 这类也确定，
+         * 但输出较长、不是高频重复对象，缓存收益低于占位成本，故不纳入。
+         *
+         * `workspace` / `formula-table` / `promptMode` 有**副作用**（会改状态），
+         * 绝不能缓存 —— 命中会跳过副作用，行为就变了。
+         *
+         * 键里必须含常数与工作区指纹：改常数后同一式子结果不同，
+         * 漏了这条会静默返回「改之前」的数。
+         */
+        const CACHEABLE = [
+            '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 = ['workspace', 'formula-table'];
+        if (MUTATING.includes(operation)) {
+            clearCache();
+        }
+        let cacheHitKey;
+        if (CACHEABLE.includes(operation)) {
+            try {
+                /**
+                 * 缓存键用**整个 args 的稳定序列化**，而不是手动列举几个参数。
+                 *
+                 * 为什么改（踩过）：最初只列了 expression/formula/overrides/data 等几项，
+                 * 结果 `dist` 的 `distribution`/`params`/`x` 没进键 ——
+                 * 先算正态分布、再算二项分布时**命中了正态的结果**，
+                 * 二项 PMF 返回了正态的 PDF。这类串键的错最难发现（结果看着像个正常的数）。
+                 *
+                 * 现在把 args 全量序列化（排除纯显示选项），漏一个参数的可能性归零。
+                 * 代价是多算几次字符串，与「算错」比起来不值一提。
+                 */
+                const { displayPrecision: _dp, promptMode: _pm, ...restForCache } = args;
+                /**
+                 * 键里要带「显示精度是否显式」这一位。
+                 *
+                 * 踩过：显式传 `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, cached: true };
+                }
+                cacheHitKey = key;
+            }
+            catch {
+                /* 缓存键构造失败不影响计算（可能含不可序列化的参数） */
+            }
+        }
         let outcome;
+        /**
+         * 批量模式优先：给了 expressions 就走批量，忽略单条 expression。
+         *
+         * 不缓存批量结果：批量通常是一次性探查（同一批式子很少重复出现），
+         * 缓存它们只会挤占单条计算的位置。
+         */
+        if (Array.isArray(args.expressions) && args.expressions.length > 0) {
+            outcome = opEvaluateBatch(engine, args.expressions, scope, precision);
+            const batchResult = {
+                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();
@@ -1675,6 +1974,9 @@ export function runMathTool(rawArguments) {
             case 'balance':
                 outcome = opBalance(args);
                 break;
+            case 'bodies':
+                outcome = opBodies(args);
+                break;
             case 'evaluate':
             default:
                 outcome = opEvaluate(engine, input, scope, precision);
@@ -1692,6 +1994,55 @@ export function runMathTool(rawArguments) {
         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 才算错误，分析型的不算。
          *
@@ -1718,6 +2069,15 @@ export function runMathTool(rawArguments) {
         if (STRICT_FINITE_OPERATIONS.includes(operation) && containsNonFinite(result.value)) {
             throw new CalcError('non_finite', `计算结果非有限（${outcome.result}）`, '常见于除以零、tan(π/2)、log(0)。若要符号形式可改用 operation="simplify"。');
         }
+        // 写缓存（只在成功路径；错误不缓存，否则同一个错会一直被命中）
+        if (cacheHitKey !== undefined) {
+            try {
+                setCached(cacheHitKey, result);
+            }
+            catch {
+                /* 写入失败不影响返回 */
+            }
+        }
         return result;
     }
     catch (error) {
@@ -1753,6 +2113,140 @@ function clampPrecision(value) {
         return DEFAULT_PRECISION;
     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) {
+    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() {
+    try {
+        const active = getActiveConstants();
+        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() {
+    try {
+        return currentWorkspace();
+    }
+    catch {
+        return 'unknown-' + Math.random();
+    }
+}
+/**
+ * 把参数对象序列化成稳定字符串（缓存键用）。
+ *
+ * 与 `stableStringify` 的区别：这个专为「可能含各种嵌套」的调用参数而写，
+ * 遇到不可序列化的值就退化成类型标记 —— 宁可少命中，不可串键。
+ *
+ * @param value - 参数值
+ * @returns 稳定字符串
+ */
+function stableArgs(value) {
+    if (value === null || value === undefined)
+        return '';
+    const kind = typeof value;
+    if (kind === 'number') {
+        return Number.isFinite(value) ? value.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;
+        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) {
+    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) {
     if (typeof value !== 'string' || value.trim() === '')
         return DEFAULT_VARIABLE;
@@ -1811,7 +2305,13 @@ function renderResult(value) {
         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 = {
     expression: {
@@ -1819,6 +2319,11 @@ const PARAMETER_SPEC = {
         description: '数学表达式、方程或待处理数据。多方程用逗号分隔（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,
@@ -1827,9 +2332,10 @@ const PARAMETER_SPEC = {
     operation: {
         type: 'string',
         enum: OPERATIONS,
-        description: '默认 auto。evaluate=求值，solve=解方程（多方程自动识别为线性方程组），system=显式线性系统，' +
-            'derivative=求导，integral=符号积分，simplify=化简，expand=展开，roots=多项式求根，' +
-            'matrix=矩阵运算，eigen=特征值/特征向量，stats=描述统计，dist=概率分布，regression=回归，help=能力清单。',
+        // 不逐个解释每个 operation 名称：enum 里已经列全，而 `help` 有完整说明。
+        // 这里只给「怎么选」的判断线索，那才是 AI 真正需要的。
+        description: '默认 auto。简易算式用 evaluate；数据用 stats/dist/regression；' +
+            '改动设定后用 world/derivation；不确定就调 help 看全表。',
     },
     variable: {
         type: 'string',
@@ -1853,16 +2359,45 @@ const PARAMETER_SPEC = {
     customUnits: {
         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。',
+        description: '收支盘点（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',
@@ -1874,7 +2409,16 @@ 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',
@@ -1946,13 +2490,11 @@ const PARAMETER_SPEC = {
     world: {
         type: 'object',
         additionalProperties: true,
-        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}',
+        // 字段清单不写在 schema 里：schema 每轮都要付费，而这些字段只在
+        // 真用 world 时才需要。全文见 help（operation="help", query="world"）。
+        description: '星球参数（operation=world），全部可选，默认地球。' +
+            '常用键：planetMass/planetRadius（地球倍数）、starMass/starTemp、rotationHours、obliquityDeg、greenhouse。' +
+            '完整字段表见 help 的 world 条目。',
     },
     planetRadius: {
         type: 'number',
@@ -1973,22 +2515,16 @@ const PARAMETER_SPEC = {
     terrain: {
         type: 'object',
         additionalProperties: true,
-        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"}',
+        // 同上：地形字段有九项，逐项列在 schema 里太贵。
+        description: '局部地形（operation=world 附带），给了就额外输出该地点气候细节。' +
+            '常用键：kind、elevation、latitudeDeg、oceanCurrent。完整键表见 help。',
     },
     constants: {
         type: 'object',
         additionalProperties: true,
-        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 等自动重算，并评估世界偏离程度。',
+        // 旋钮清单移进 help：只有要改常数时才需要，不该每轮付费
+        description: '要改的物理常数（operation=constants），只能改基础旋钮，派生量自动重算。' +
+            '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 条目。',
     },
 };
 /**