dsh-math-calculator 2.0.0 → 2.1.0

package/lib/types/format.d.ts

@@ -19,12 +19,41 @@ export declare function safeNumber(value: number): JsonValue;
  */
 export declare function isIntegerLike(value: any): boolean;
 /**
- * 选择一个能暴露出完整精度的格式化方式。
+ * 格式化输出值：**整数完整，小数按「小数点后几位」截断**。
  *
- * - 整数 → `notation:'fixed'`（否则 `50!` 会显示成科学计数法，看着像近似值）
- * - 其余 → `notation:'auto'` + 指定有效数字
+ * ## 计算精度 vs 显示精度
+ *
+ * `precision` 是计算精度（BigNumber 的有效位数），拿它直接当显示位数有两个毛病：
+ *   · 64 位全吐出来，一行里六十个数字，人和 AI 都读不下去
+ *   · 真调低 precision 又会**算错大数** —— 实测 `(10^20+1)-(10^20)`
+ *     在 precision=20 时得 0（应为 1）
+ *
+ * 所以拆成两层：计算永远按 `precision`（默认 64）走，显示用 `displayPrecision`。
+ *
+ * ## displayPrecision 的语义是「小数点后几位」，不是「有效数字」
+ *
+ * 这个区别很重要，实测对比：
+ *
+ *   数值              有效数字=8（旧）    小数位=8（现在）
+ *   12345.678901234   12345.679           12345.67890123
+ *   1/7               0.14285714          0.14285714
+ *   2^0.5             1.4142136           1.41421356
+ *
+ * 说「保留 8 位」时想的是小数位 —— 而有效数字语义下，
+ * 数字越大得到的小数位越少，`12345.678901234` 只给 3 位小数，与直觉不符。
+ *
+ * ## 整数不做截断
+ *
+ * `10^20+5`、`50!` 这类整数照原样输出。把 `10^20+5` 写成 `1e20` 是**丢信息**，
+ * 不是简洁 —— 作者问「等于多少」，答案就该精确到个位。
+ *
+ * @param math - mathjs 实例
+ * @param value - 待格式化的值
+ * @param precision - 计算精度（BigNumber 有效位数）
+ * @param displayPrecision - **小数点后保留几位**；省略则输出完整精度
+ * @returns 显示串
  */
-export declare function formatValue(math: any, value: any, precision: number): string;
+export declare function formatValue(math: any, value: any, precision: number, displayPrecision?: number): string;
 /**
  * 把 mathjs 的任意返回值转成可 JSON 化的值。
  * Matrix / Complex / Unit / Fraction / BigNumber / Range / ResultSet 分别处理。

package/lib/types/formula-library-generic.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 公式库第八批：**普适版经验式**（把烘焙的常数拆出来，让它们随世界变）。
+ *
+ * ## 这一批解决什么问题
+ *
+ * 前七批里有一批经验公式把常数**烘焙进了系数**：
+ *
+ *   船舶极限航速 = 1.34 × sqrt(L)     ← 1.34 里藏着 g = 9.81
+ *   宜居带内边界 = sqrt(L / 1.1)      ← 1.1 是「地球温室条件下的辐照阈值」
+ *   硬度估强度  = 3 × H × 9.80665e6   ← 9.8 是地球重力换算
+ *
+ * 它们在**地球**上对，但作者写 1.5 倍重力的星球时照抄就会错，而且错得隐蔽
+ * （数字看着正常，只是用了地球的常数）。
+ *
+ * 本批把这些式子重写成**显式暴露物理量**的形式：
+ *
+ *   hull_speed_generic      = Fr × sqrt(g × L) × 1.944    ← g 由 world 给出
+ *   habitable_inner_generic = sqrt(L / (flux × S0))       ← S0 由 L☉/AU 推出
+ *   hardness_yield_generic  = 3 × H × g / 1e-6 × 1e6      ← g 可替换
+ *
+ * ## 与旧版并存，不是替换
+ *
+ * 旧的 `hull_speed`（1.34）**保留**：作者要写地球上的船时它更快更省事，
+ * 而且那是船舶工程界的标准式。新版只是给「非地球重力」的场景一个正确入口。
+ * 两版的 desc 都写明适用域，让作者知道该用哪个。
+ *
+ * ## 单位约定
+ *
+ * 同前几批：**SI 基本单位**，但保留各村行业惯用单位（节、kgf/mm²）并在参数说明里写明。
+ *
+ * @module dsh-math-calculator/formula-library-generic
+ */
+import type { FormulaDef } from './formula-library.js';
+/**
+ * 第八批公式：把烘焙常数拆出来的普适形式。
+ */
+export declare const GENERIC_FORMULAS: FormulaDef[];

package/lib/types/formulas.d.ts

@@ -12,7 +12,7 @@
  */
 import { CONSTANTS, type FormulaDef } from './formula-library.js';
 /**
- * 全部公式 = 主批次 + 扩展 + 感知层 + 故事 + 势力动力学 + 通用计算基础件。
+ * 全部公式 = 主批次 + 扩展 + 感知层 + 故事 + 势力动力学 + 通用计算 + 普适经验式。
  * 分批组织而不是单文件拼接，避免 formula-library.ts 无限膨胀。
  */
 export declare const FORMULAS: FormulaDef[];
@@ -63,21 +63,49 @@ export declare function resolveParams(formula: FormulaDef, overrides: Overrides,
  */
 export declare function buildFormulaScope(engine: any, values: Record<string, unknown>): Record<string, any>;
 /**
- * 查找公式。支持 id 精确匹配、名称子串、关键词、分类、同义词与中文子词。
- * 返回按相关度排序的候选。
+ * 在一组公式里按相关度检索（**检索逻辑的唯一实现**）。
+ *
+ * 为什么要单独抽出来：这段逻辑曾经被**复制成两份** ——
+ * `formulas.ts` 里的 `findFormulas` 和 `index.ts` 里的 `findInCurrentWorkspace`。
+ * 于是修好了一份、另一份还是旧的：`formulas` 操作走 `findInCurrentWorkspace`，
+ * 真实工具里查「贷款月供」仍然是 0 条，而单元测试调 `findFormulas` 全部通过。
+ * **测试绿了，工具没修**。现在两边都调这个函数，物理上不可能再不一致。
+ *
+ * @param formulas - 待检索的公式集（内置全量，或「工作区叠加后的当前集」）
+ * @param query - 查询串
+ * @param limit - 最多返回条数
+ * @returns 按相关度排序的公式
+ */
+export declare function scoreFormulas(formulas: readonly FormulaDef[], query: string, limit?: number): FormulaDef[];
+/**
+ * 查找公式（内置全量集）。支持 id 精确、名称子串、关键词、分类、同义词与中文子词。
  *
  * 排序优先级：整串精确 > id 精确 > 关键词精确 > id 子串 > 名称精确 > 名称子串 > 描述 > 分类。
  * 注意：分类命中给的分要低，否则搜「重力」会把整个 physics/gravity
  * 分类的公式都挤到最前面，把真正相关的 gravitation 埋掉。
  *
- * ⚠️ 词元匹配的分数按**词长加权**：命中 4 个字比命中 2 个字更相关。
- * 否则「粮食产量」会把所有含「量」的公式都召回到同一档。
- *
  * @param query - 查询串（关键词 / 同义词 / 中文复合词都行）
- * @param limit - 最多返回条数。宽泛查询给大一点，否则会被截断成 10 条
+ * @param limit - 最多返回条数
  * @returns 按相关度排序的公式
  */
 export declare function findFormulas(query: string, limit?: number): FormulaDef[];
+/**
+ * 严格解析单个公式（不做子词/同义词模糊匹配）。
+ *
+ * 为什么必须与 `scoreFormulas` 分开：
+ *   检索（`formulas` 操作）追求「想得到」，模糊匹配是对的；
+ *   求值（`formula` 操作）追求「指哪儿打哪儿」，模糊匹配是灾难 ——
+ *   传 `'完全不存在的公式xyz'` 时，子词「公式」会命中别的公式，
+ *   于是本该报 `unknown_formula` 的地方变成 `missing_params`，
+ *   模型会以为「公式找到了，只是缺参数」，然后去补一堆无关参数。
+ *
+ * 这里只认四种关系：id 精确、名称精确、id 包含、名称包含。
+ *
+ * @param formulas - 待解析的公式集
+ * @param query - 公式 id 或名称
+ * @returns 唯一命中的公式；没有命中返回 `undefined`
+ */
+export declare function resolveFormulaStrict(formulas: readonly FormulaDef[], query: string): FormulaDef | undefined;
 /** 某条公式的读者视角频次。 */
 export declare function formulaFrequency(formula: FormulaDef): 'high' | 'medium' | 'low';
 /** 按频次筛选公式。 */

package/lib/types/index.d.ts

@@ -44,6 +44,22 @@ export interface MathResult {
         message: string;
         hint?: string;
     };
+    /**
+     * 本次结果来自缓存（未重新计算）。
+     *
+     * 为什么要暴露：AI 需要知道「这个数是刚算的还是回忆的」——
+     * 若它以为自己刚验证过而实际只是缓存，会把「没改过设定」误当成「验证通过」。
+     * 改动常数或切换工作区后缓存键会变，所以不会出现「改了设定还拿旧值」。
+     */
+    cached?: boolean;
+    /**
+     * 附加提示（渲染时展示给模型，**不进入 `result`**）。
+     *
+     * 为什么要分开：`result` 是数据通道，调用方会做精确相等比较；
+     * 往里拼提示会让 `0.1+0.2` 从 `0.3` 变成两行，破坏所有精确断言。
+     * 提示属于「给人/模型看的说明」，走这个字段即可。
+     */
+    notice?: string;
 }
 /** 更新检测器配置。 */
 export declare function configureDetector(config: Partial<DetectorConfig>): Partial<DetectorConfig>;

package/lib/types/ops/bodies-op.d.ts

@@ -0,0 +1,35 @@
+/**
+ * operation="bodies" 的实现：天体目录查询与常数传导。
+ *
+ * ## 三种用法
+ *
+ * ```jsonc
+ * // 1. 列出全部天体（按类别分组）
+ * { "operation": "bodies" }
+ *
+ * // 2. 查某个天体 / 按类别筛
+ * { "operation": "bodies", "bodyName": "mars" }
+ * { "operation": "bodies", "bodyKind": "planet-terrestrial" }
+ *
+ * // 3. 改常数后，看天体数据哪些该重算（**这是最容易出错的一步**）
+ * { "operation": "bodies", "bodyConstant": "alpha_fs", "bodyFactor": 2 }
+ * ```
+ *
+ * ## 第 3 种为什么重要
+ *
+ * 作者改了 α 之后，最容易犯两个**静默**的错：
+ *   · 把行星质量也跟着改（错：质量与 α 无关，那是篡改设定）
+ *   · 忘了恒星光度要变（错：气候结论还是旧的）
+ *
+ * 这里把「该变的」和「不该动的」分成两块明确列出来。
+ *
+ * @module dsh-math-calculator/ops/bodies-op
+ */
+import { type MathArgs, type Outcome } from './shared.js';
+/**
+ * `bodies`：天体目录、类型学与常数传导。
+ *
+ * @param args - 工具参数
+ * @returns 结果文本与结构化值
+ */
+export declare function opBodies(args: MathArgs): Outcome;

package/lib/types/ops/shared.d.ts

@@ -21,7 +21,7 @@ import type { WorldParams } from '../world.js';
  * "27 个 operation" 断言都直接依赖它。新增 operation 必须同步改三处，
  * 否则模型看得到名字却调不通，或测试直接变红。
  */
-export type MathOperation = 'auto' | 'evaluate' | 'solve' | 'system' | 'derivative' | 'integral' | 'simplify' | 'expand' | 'roots' | 'matrix' | 'eigen' | 'stats' | 'dist' | 'regression' | 'formula' | 'formulas' | 'ode' | 'world' | 'constants' | 'workspace' | 'impact' | 'quantities' | 'formula-table' | 'feasibility' | 'derivation' | 'custom' | 'units' | 'balance' | 'help';
+export type MathOperation = 'auto' | 'evaluate' | 'solve' | 'system' | 'derivative' | 'integral' | 'simplify' | 'expand' | 'roots' | 'matrix' | 'eigen' | 'stats' | 'dist' | 'regression' | 'formula' | 'formulas' | 'ode' | 'world' | 'constants' | 'workspace' | 'impact' | 'quantities' | 'formula-table' | 'feasibility' | 'derivation' | 'custom' | 'units' | 'balance' | 'bodies' | 'help';
 /**
  * 所有 operation 共用的参数对象。
  *
@@ -38,6 +38,49 @@ export interface MathArgs {
     matrix?: number[][];
     vector?: number[];
     precision?: number;
+    /**
+     * **显示**精度：**小数点后几位**（与计算精度分开）。
+     *
+     * ## 为什么要分开
+     *
+     * `precision` 是**计算**精度：它决定 BigNumber 的有效位数，
+     * 调低会真的把大数算错 —— 实测 `(10^20+1)-(10^20)`：
+     *
+     *   precision=64 → 1（正确）
+     *   precision=20 → 0（算错了）
+     *
+     * 所以它不能为了让输出好看而调低。而 `displayPrecision` 只影响**写出来的位数**，
+     * 计算仍然按 `precision`（默认 64）进行 —— 大数运算照样精确，只是显示得短些。
+     *
+     * ## 语义是「小数点后几位」，不是「有效数字」
+     *
+     * 这个区别很大：
+     *   8 位小数   → 12345.678901234 得 12345.67890123
+     *   8 位有效数字 → 同一个数得 12345.679（只剩 3 位小数）
+     *
+     * 说「保留 8 位」时想的是小数位，所以按小数位实现。
+     *
+     * ## 怎么用
+     *
+     * 一次设定即固化到当前工作区（后续调用自动沿用），也可每次覆盖：
+     *   { operation:'workspace', action2:'set', displayPrecision:8 }  ← 固化
+     *   { operation:'evaluate', expression:'1/7', displayPrecision:6 }  ← 临时
+     *
+     * 默认 8 位小数；工程核对可给 12—16；整数永远完整，不受此参数影响。
+     */
+    displayPrecision?: number;
+    /**
+     * 批量表达式（operation=evaluate 的批量模式）。
+     *
+     * 一次算多条，省掉多次工具往返的开销。每条独立报错，
+     * 不会因为一条失败就中断整批。
+     *
+     * 例：`{operation:'evaluate', expressions:['1/7','2^0.5','log(10)']}`
+     *
+     * 为什么值得：每次工具调用都有固定开销（往返 + 结果文本进入上下文），
+     * 算 5 条就多付 5 次。批量把 5 次往返压成 1 次。
+     */
+    expressions?: string[];
     data?: number[];
     dataY?: number[];
     distribution?: string;
@@ -174,6 +217,30 @@ export interface MathArgs {
         supply: number;
         unit?: string;
     }>;
+    /** 查单个天体：id（mars）或中文名（火星）。 */
+    bodyName?: string;
+    /** 按类别筛：star / planet-terrestrial / moon / dwarf-planet … */
+    bodyKind?: string;
+    /**
+     * 改常数后看天体数据哪些该重算。
+     *
+     * 例：`bodyConstant:"alpha_fs", bodyFactor:2` 表示 α 变成两倍，
+     * 输出会分成「必须重算的量」与「绝不该动的量」两块——
+     * 后者尤其重要：行星质量、半径、轨道与 α 无关，改了就是篡改设定。
+     */
+    bodyConstant?: string;
+    /** 常数变化倍数（默认 2）。 */
+    bodyFactor?: number;
+    /**
+     * 查天体**类型**（operation=bodies）。
+     *
+     * 与 bodyName 的区别：bodyName 查具名天体（火星、木卫二），
+     * bodyType 查类型学条目（中子星、热木星、戴森球）——
+     * 面向宇宙科幻创作，含理论预言与纯思辨类。
+     */
+    bodyType?: string;
+    /** 按证据等级筛类型：observed / theoretical / speculative。 */
+    bodyEvidence?: string;
     /** 叙事锚点 id（如 creatureHeight）。 */
     anchor?: string;
     /** 锚点想要的值（如 50 米）。 */
@@ -328,7 +395,31 @@ export declare function fast(): any;
  * 换行会被 mathjs 当成语句结束而报错。
  */
 export declare function normalizeSource(input: string): string;
-/** 数字修剪：去掉浮点噪声。 */
-export declare function trimNumber(value: number, precision: number): string;
+/**
+ * 设置本次调用的显示精度（在工具入口调用）。
+ *
+ * @param value - 显示有效位数；undefined = 不截断
+ */
+export declare function setActiveDisplayPrecision(value: number | undefined): void;
+/**
+ * 取当前显示精度。
+ *
+ * @returns 显示有效位数；未设置返回 undefined
+ */
+export declare function currentDisplayPrecision(): number | undefined;
+/**
+ * 数字修剪：去掉浮点噪声，按**小数点后几位**保留。
+ *
+ * 语义与 `formatValue` 的 `displayPrecision` 保持一致：**小数位**，不是有效数字。
+ *
+ * 为什么统一成小数位：说「保留 8 位」时想的是小数位。
+ * 有效数字语义下 `12345.678901234` 只给 3 位小数（12345.679），与直觉不符。
+ *
+ * @param value - 数值
+ * @param precision - 计算精度（未设显示精度时作为退路）
+ * @param displayPrecision - **小数点后保留几位**；省略则用模块级当前值
+ * @returns 显示串
+ */
+export declare function trimNumber(value: number, precision: number, displayPrecision?: number): string;
 /** 把数字安全地塞进 JsonValue（非有限值转字符串）。 */
 export declare function safeNumberForJson(value: number): JsonValue;

package/lib/types/precision-report.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 显示精度的损失追踪：判断「当前位数够不够用」。
+ *
+ * ## 为什么需要这个模块
+ *
+ * 显示精度截断是**悄悄发生**的，作者与模型都不会察觉：
+ *
+ *   1/7                 8 位小数 → 0.14285714        损失约 1e-9（无感）
+ *   123456.789012345    8 位小数 → 123456.78901235    损失约 5e-9（无感）
+ *   0.00000123456789    8 位小数 → 0.00000123        相对损失约 0.3%（有感！）
+ *
+ * 最后一个例子是关键：数值很小时，8 位小数只留下 3 位有效数字，
+ * 相对误差 0.3% —— 作者以为拿到的是精确值，实际已经偏了。
+ *
+ * 本模块只做一件事：记住本轮格式化过程中最大的相对误差，
+ * 让工具层能据此提醒「该调高 displayPrecision 了」。
+ *
+ * ## 为什么不写在 format.ts
+ *
+ * `format.ts` 不依赖任何其它模块，而 `shared.ts` 已经导入它。
+ * 把状态放进 `format.ts` 就得反向导入，形成循环。
+ * 单独一个模块两边都能用，依赖方向干净。
+ *
+ * ## 阈值
+ *
+ * 取 1e-4（万分之一）：低于它的损失对创作与工程核对都无影响；
+ * 高于它说明显示值已经明显偏离真值，值得提醒一次。
+ *
+ * @module dsh-math-calculator/precision-report
+ */
+/** 允许的最大相对误差（万分之一）。超过就提醒。 */
+export declare const PRECISION_LOSS_THRESHOLD = 0.0001;
+/**
+ * 记录一次截断造成的相对误差。
+ *
+ * @param relativeLoss - |显示值−真值| / |真值|
+ */
+export declare function reportPrecisionLoss(relativeLoss: number): void;
+/**
+ * 取出并清空本轮的最大相对误差。
+ *
+ * 清空是必要的：每次工具调用开始都要重新统计，
+ * 否则上一轮的损失会一直挂在本轮结果上。
+ *
+ * @returns 最大相对误差；0 表示没有可感知的损失
+ */
+export declare function consumePrecisionLoss(): number;
+/**
+ * 标记本轮显示精度是否来自显式参数。
+ *
+ * @param explicit - 是否显式
+ */
+export declare function setDisplayPrecisionExplicit(explicit: boolean): void;
+/**
+ * 当前显示精度是否来自显式参数。
+ *
+ * @returns 是否显式
+ */
+export declare function isDisplayPrecisionExplicit(): boolean;

package/lib/types/result-cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 计算结果缓存：同样的输入不再算第二遍。
+ *
+ * ## 为什么值得做（而不只是优化）
+ *
+ * 反复算同一个式子在真实使用里很常见：
+ *   · AI 校验自己的结论（「再算一次确认」）——输入完全相同
+ *   · 同一批数据换着角度问（同一条 `1/7` 在几个不同问题里出现）
+ *   · 推演时反复引用同一个常量式
+ *
+ * 每次重算的代价不只是 CPU，还有**结果文本再次进入上下文**：
+ * 一个 64 位小数的返回值约 65 字符，重复十次就是 650 字符的 token。
+ * 缓存命中时仍要返回结果（AI 需要看到值），但省掉了重算，
+ * 更重要的是对**批量和重复调用**能显著降低总开销。
+ *
+ * ## 缓存键必须包含什么
+ *
+ * 少放一个就会返回**错的结果**——这比不缓存危险得多：
+ *   · 规范化后的表达式（`1/7` 与 `1 / 7` 应算同一条，但不能把 `1/7` 和 `2/7` 撞车）
+ *   · operation（`evaluate "1+1"` 与 `solve "1+1"` 结果不同）
+ *   · precision（计算精度不同，结果不同）
+ *   · displayPrecision（只影响显示，但也进键——否则命中后位数不对）
+ *   · **当前常数状态**（改了 c/G 之后同样的式子结果不同）
+ *   · **工作区**（不同世界的公式表/变量可能不同）
+ *
+ * 最后两项最容易漏。实测过：改常数后若缓存不失效，
+ * 会返回「改之前」的数——那是静默错误。
+ *
+ * ## 容量与淘汰
+ *
+ * 固定容量 + LRU。不设 TTL：常数或工作区一变，键就变了，旧条目自然不再命中；
+ * 保留它们没有危害，只是占内存，所以用容量上限控制。
+ *
+ * @module dsh-math-calculator/result-cache
+ */
+/**
+ * 计算缓存键。
+ *
+ * @param parts - 参与键的各个部分（按固定顺序传入）
+ * @returns 键字符串
+ */
+export declare function cacheKey(parts: readonly unknown[]): string;
+/**
+ * 取缓存。
+ *
+ * @param key - 缓存键
+ * @returns 命中则返回缓存值；未命中返回 undefined
+ */
+export declare function getCached(key: string): unknown;
+/**
+ * 存缓存。
+ *
+ * @param key - 缓存键
+ * @param value - 要缓存的值
+ */
+export declare function setCached(key: string, value: unknown): void;
+/**
+ * 清空缓存（改常数、切工作区时应当调用）。
+ *
+ * 为什么需要显式清空：缓存的键里已经含常数与工作区，
+ * 理论上不会串；但**清空是个安全网**——
+ * 万一某条路径漏把常数放进键里，清空能兜住，而不是静默返回旧值。
+ */
+export declare function clearCache(): void;
+/**
+ * 缓存统计（供诊断与测试）。
+ *
+ * @returns 条目数、命中、未命中
+ */
+export declare function cacheStats(): {
+    size: number;
+    hits: number;
+    misses: number;
+};
+/**
+ * 重置统计（不影响已存条目）。
+ */
+export declare function resetCacheStats(): void;

package/lib/types/workspace.d.ts

@@ -61,6 +61,19 @@ export interface WorkspaceData {
      * 用发行前的量纲检查发现「公式算出来的不是想要的量」。
      */
     customConstants?: CustomConstant[];
+    /**
+     * 本工作区的**显示**有效位数（不影响计算精度）。
+     *
+     * 为什么存在这里：AI 在对话里读到的每个数字都带着几十位小数，
+     * 逐个自己截断既费 token 又容易出错。定一次、存下来、后续沿用，
+     * 是「让 AI 估计一个够用的精度并固化」的实现方式。
+     *
+     * 计算仍然按 `precision`（默认 64）走，只有输出被截断 ——
+     * 所以 `(10^20+1)-(10^20)` 照样得 1，不会因为显示短了就算错。
+     *
+     * 未设置时沿用计算精度（即完整输出，旧行为）。
+     */
+    displayPrecision?: number;
     /** 创建时间。 */
     createdAt: string;
     /** 最后修改时间。 */
@@ -313,3 +326,14 @@ export declare function bindHostWorkspace(rawId: unknown, rawTitle: unknown, mak
     created: boolean;
     workspace: WorkspaceData;
 };
+/**
+ * 读取当前工作区的显示精度（未设置返回 undefined = 沿用计算精度）。
+ *
+ * 为什么单独做一个函数：工具入口每轮都要问一次「现在显示几位」，
+ * 而这里要吸收掉「工作区文件损坏 / 不存在」等各种异常 ——
+ * 读取失败不该让整个计算挂掉，退回完整输出即可。
+ *
+ * @param name - 工作区名；省略用当前活动工作区
+ * @returns 显示有效位数；未设置返回 undefined
+ */
+export declare function displayPrecisionOf(name?: string): number | undefined;

package/lib/types/world.d.ts

@@ -229,6 +229,14 @@ export interface WorldProfile {
     warnings: string[];
     /** 读者能直接感知的要点（供主模型二创）。 */
     highlights: string[];
+    /**
+     * 恒星假设说明：哪些地方**替代了用户设定**或**补了默认值**。
+     *
+     * 与 `warnings` 的区别：`warnings` 说「你给的世界有物理问题」，
+     * 这里说「我动了你的输入」。后者更要紧——整份结论都建立在它之上，
+     * 所以必须显式返回、由上层放到输出最前面。
+     */
+    starNotes: string[];
 }
 /**
  * 世界推演主函数。

package/lib/workspace.js

@@ -739,3 +739,25 @@ export function bindHostWorkspace(rawId, rawTitle, makeCurrent = true) {
     }
     return { bound: true, name, workspaceId: hostId, created: !existed, workspace: data };
 }
+/**
+ * 读取当前工作区的显示精度（未设置返回 undefined = 沿用计算精度）。
+ *
+ * 为什么单独做一个函数：工具入口每轮都要问一次「现在显示几位」，
+ * 而这里要吸收掉「工作区文件损坏 / 不存在」等各种异常 ——
+ * 读取失败不该让整个计算挂掉，退回完整输出即可。
+ *
+ * @param name - 工作区名；省略用当前活动工作区
+ * @returns 显示有效位数；未设置返回 undefined
+ */
+export function displayPrecisionOf(name) {
+    try {
+        const data = loadWorkspace(name ?? activeWorkspaceName);
+        const value = data.displayPrecision;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/world.js

@@ -143,6 +143,14 @@ export function generateWorld(params, options = {}) {
     //   a) starClass='M5V' → 按光谱型基准表填充（省去查表）
     //   b) 直接给 starMass/starRadius/starTemp
     // 显式参数优先于 starClass —— 用户想微调时不会被基准值覆盖。
+    //
+    // ⚠️ 目录里**只有主序星（V）**：O5V…M5V 共 9 种，没有巨星（III）、次巨星、白矮星。
+    // 同样光谱字母的巨星比主序星亮 20—100 倍，用主序值顶替会让平衡温度差出几百开。
+    //
+    // 实测踩到过：传 starClass='F5III'（某设定里的 F5-IIIa 巨星）时，旧实现静默回退到
+    // 最近的主序型 G2V（太阳），而那句提示被推到最后一百多行之后——读前 20 行的人永远看不到。
+    // 现在这类替换会记进 starNotes，并被放到输出的**最前面**。
+    const starNotes = [];
     let baseStar;
     if (typeof params.starClass === 'string' && params.starClass.trim() !== '') {
         const requested = STAR_INDEX.get(params.starClass.trim());
@@ -152,16 +160,35 @@ export function generateWorld(params, options = {}) {
             // 允许简写（如 'G2' → 'G2V'）
             const upper = params.starClass.trim().toUpperCase();
             const prefixed = STAR_CLASSES.find((s) => s.id.startsWith(upper));
-            baseStar = prefixed ?? closestStarClass(num(params.starTemp, 5778));
-            if (!prefixed) {
-                warnings.push(`未找到光谱型 "${params.starClass}"，按给定温度推断为 ${baseStar.id}。` +
+            if (prefixed) {
+                baseStar = prefixed;
+            }
+            else {
+                baseStar = closestStarClass(num(params.starTemp, 5778));
+                starNotes.push(`未找到光谱型「${params.starClass}」，已按温度推断为 ${baseStar.id}（主序星）。` +
                     `可选值：${STAR_CLASSES.map((s) => s.id).join(', ')}`);
+                // 亮度级 I/II/III/IV = 巨/次巨星：同样的光谱字母，亮度高出一个数量级
+                const lumMatch = params.starClass.trim().match(/(III|II|IV|I)\b/i);
+                const lum = lumMatch ? lumMatch[1].toUpperCase() : undefined;
+                if (lum !== undefined && lum !== 'V') {
+                    starNotes.push(`⚠ 你给的是「${lum}」级（巨/次巨星），而本模型只支持主序星（V）。` +
+                        '同光谱字母的巨星比主序星亮 20—100 倍，因此温度、宜居带、日照量都会显著偏低——' +
+                        '这个结果不能直接采信。要接近真实，请显式给 starMass 与 starRadius。');
+                }
             }
         }
     }
     else {
         // 没给 starClass：按温度反查最接近的光谱型（用于补全半径/质量）
         baseStar = closestStarClass(num(params.starTemp, 5778));
+        // 完全没给恒星信息 = 默认太阳，这必须说在最前面
+        const gaveAnyStar = params.starMass !== undefined ||
+            params.starRadius !== undefined ||
+            params.starTemp !== undefined;
+        if (!gaveAnyStar) {
+            starNotes.push('没有给任何恒星参数，已默认成太阳（G2V，1 L☉，5778 K）。' +
+                '若这颗行星绕的不是太阳型恒星（例如 K 型橙星或 F 型巨星），温度与宜居带会差很多。');
+        }
     }
     const starMassSun = num(params.starMass, baseStar.massSun);
     const starRadiusSun = num(params.starRadius, baseStar.radiusSun);
@@ -604,5 +631,13 @@ export function generateWorld(params, options = {}) {
         },
         warnings,
         highlights,
+        /**
+         * 恒星假设说明（替代了用户设定、或用了默认值）。
+         *
+         * 与 `warnings` 分开：`warnings` 是「你给的世界有个物理问题」，
+         * `starNotes` 是「我改了/补了你的输入」。两者性质不同，呈现位置也不同——
+         * `starNotes` 必须出现在输出最前面，因为整份结论都建立在它之上。
+         */
+        starNotes,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-math-calculator",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "DSH 原生的高精度数学计算器插件：BigNumber 64 位求值、符号微积分、线性代数（秩/零空间/奇异值/特征值）、统计概率与回归、微分方程、单位换算、395 条公式库（三轴标签）、物理常数推演。全部本地执行，不联网。附带一组可选的世界观推演工具。",
   "type": "module",