dsh-math-calculator 2.1.0 → 2.2.0

package/lib/types/index.d.ts

@@ -60,10 +60,43 @@ export interface MathResult {
      * 提示属于「给人/模型看的说明」，走这个字段即可。
      */
     notice?: string;
+    /**
+     * 批量模式：「部分成功」——本批有失败条目，但也有成功结果可用。
+     *
+     * 为什么要单独一个字段：`ok` 是布尔，说不了「废了几条、还剩几条」。
+     * 没有它，调用方只能二选一：整批当废（浪费成功条目）或整批当可用（把失败当成功）。
+     */
+    partial?: boolean;
+    /** 批量模式：失败条目数。 */
+    failed?: number;
+    /** 批量模式：成功条目数。 */
+    succeeded?: number;
 }
 /** 更新检测器配置。 */
 export declare function configureDetector(config: Partial<DetectorConfig>): Partial<DetectorConfig>;
-/** 工具主入口：永不抛异常。 */
+/**
+ * 取本次调用中被跳过的非法变量键（组装提示用）。
+ *
+ * @returns 被跳过的键与原因
+ */
+export declare function takeSkippedVariableKeys(): Array<{
+    name: string;
+    reason: string;
+}>;
+/**
+ * 清理被跳过的变量键记录（每次工具调用开头）。
+ */
+export declare function resetSkippedVariableKeys(): void;
+/**
+ * 工具主入口：永不抛异常。
+ *
+ * 所有失败都转成 `{ ok:false, error:{ type, message, hint } }`，
+ * 因为宿主侧把抛异常当成「工具坏了」，而这里的失败几乎都是**输入问题**，
+ * 调用方按 hint 改一下就能过。
+ *
+ * @param rawArguments - 宿主传进来的参数对象（可能是任意形态，这里先做白名单校验）
+ * @returns 永远是一个 MathResult，不会 throw
+ */
 export declare function runMathTool(rawArguments: unknown): MathResult;
 /**
  * 数学计算工具（`math_execute`）。

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

@@ -75,12 +75,32 @@ export interface MathArgs {
      * 一次算多条，省掉多次工具往返的开销。每条独立报错，
      * 不会因为一条失败就中断整批。
      *
-     * 例：`{operation:'evaluate', expressions:['1/7','2^0.5','log(10)']}`
+     * 两种条目形态：
+     *   - 字符串：`['1/7','2^0.5']`
+     *   - 带标签对象：`[{label:'储耗比-中值', expr:'139e8/152e4'}]`
+     *
+     * ## 为什么要 label
+     *
+     * 实测反馈：同一批算两个口径时（`['139e8/1743500','139e8/152e4']` → 7972 / 9144），
+     * 输出里**只有顺序号区分**，后续引用要回翻表达式原文 —— 报告里「一次差点引错」。
+     * 单批十几条时，纯靠位置对齐的心智负担很大。
      *
      * 为什么值得：每次工具调用都有固定开销（往返 + 结果文本进入上下文），
      * 算 5 条就多付 5 次。批量把 5 次往返压成 1 次。
      */
-    expressions?: string[];
+    expressions?: Array<string | {
+        label?: string;
+        expr?: string;
+    }>;
+    /**
+     * 精简输出（operation=evaluate 的批量模式）：只回「表达式 = 结果」。
+     *
+     * 去掉标题与「成功 N，失败 M」统计行。实测反馈：
+     * 批量 8—14 条时这些固定行本身也是开销，报告估算全程 terse 可省 40%+ 输出 token。
+     *
+     * 失败信息**不省**：省掉会让调用方以为全成功了。
+     */
+    terse?: boolean;
     data?: number[];
     dataY?: number[];
     distribution?: string;
@@ -144,6 +164,13 @@ export interface MathArgs {
     workspaceVariables?: {
         [key: string]: number;
     };
+    /**
+     * 工作区开关：命名变量是否参与计算（默认关闭）。
+     *
+     * 打开后，缓存键会把变量内容算进去（否则改了变量会命中旧缓存）；
+     * 关闭时行为与未引入该功能时完全一致。
+     */
+    useWorkspaceVariables?: boolean;
     /** operation=feasibility：待校验的设定（约束 id → 值）。 */
     claims?: {
         [constraintId: string]: number;
@@ -156,6 +183,13 @@ export interface MathArgs {
     layer?: string;
     /** 单位缩放因子，检测「单位重定义陷阱」，如 { mass: 2 }。 */
     unitScales?: Record<string, number>;
+    /**
+     * 列单位清单时展开哪一维（`"length"` / `"长度"` 等）。
+     *
+     * 单位表收到近三百条后，全量展开一次是一万七千多字符；
+     * 默认只给各量纲的计数与样例，点名才展开。这与 help 的「用到时才读」一致。
+     */
+    unitScale?: string;
     /** 敏感性分析的基线值。 */
     sensitivityBase?: number;
     /** 敏感性分析的幂次（结果 = 输入^幂）。 */
@@ -297,6 +331,13 @@ export interface MathArgs {
     costWithPipeline?: boolean;
     /** 提示注入档位: off / brief / full（传了就切换并返回当前值）。 */
     promptMode?: string;
+    /**
+     * operation=help 时要取哪一节。省略则返回目录。
+     *
+     * 分节是为了让「每次调用只付用到的那一节」—— 旧版是一整块 5900 字符全量摊平，
+     * 算一条 1/3 也要读 3039 字符的 world 字段表。详见 `src/help.ts`。
+     */
+    helpTopic?: string;
     /** operation=formula-table 的动作: list / show / override / remove / add / disable / enable / reset */
     tableAction?: string;
     /** 目标公式 id。 */
@@ -372,8 +413,11 @@ export declare class CalcError extends Error {
  * 安全：删除 import / createUnit，防止表达式注入任意 JS 或改写单位表。
  * **不能**删 typed/parse/evaluate —— derivative/simplify 依赖它们。
  * 自定义函数（rank/nsolve…）在删除 import **之前**注册，顺序不能反。
+ *
+ * 单位注入（`injectUnitTable`）同理：也在删除 createUnit **之前**做，
+ * 注入完方法即被删除，所以表达式求值仍然拿不到它。
  */
-export declare function buildMath(numberMode: 'BigNumber' | 'number', precision: number): any;
+export declare function buildMath(numberMode: 'BigNumber' | 'number' | 'Fraction', precision: number): any;
 /**
  * 取 BigNumber 引擎（按 precision 缓存）。
  *
@@ -388,6 +432,26 @@ export declare function bignum(precision: number): any;
  * 用 BigNumber 只会更慢且没有意义。
  */
 export declare function fast(): any;
+/**
+ * 取**有理数**引擎（Fraction 模式）。
+ *
+ * ## 为什么需要它
+ *
+ * 定积分要按 Newton-Leibniz 代入上下限。用 BigNumber 引擎会出这种事：
+ *
+ *     原函数 1/3·x³，在 x=3 处
+ *     BigNumber → 8.99999999999999999999999999999999999999…
+ *     Fraction  → 9
+ *
+ * 因为 BigNumber 的 `1/3` 是**截断的小数**，乘 27 后回不到整数。
+ * 而 Fraction 保留精确分数，代入后能约分成整数 —— 结果 9 就是 9。
+ *
+ * 三角函数等无理性结果 Fraction 会退化成浮点，这是可接受的：
+ * 那些结果本来就不是有理数。
+ *
+ * @returns mathjs 实例（Fraction 模式）
+ */
+export declare function rational(): any;
 /**
  * 规范化输入：换行转语句分隔符、去多余分号、引号内原样保留。
  *
@@ -395,6 +459,26 @@ export declare function fast(): any;
  * 换行会被 mathjs 当成语句结束而报错。
  */
 export declare function normalizeSource(input: string): string;
+/**
+ * 把中文单位与中文量级词展开成 mathjs 能解析的形态。
+ *
+ * ## 两次展开，顺序有讲究
+ *
+ * 1. **量级词**（万/亿/万亿）→ 纯乘数括号，如 `(2.66 * 1e8)`
+ * 2. **中文单位**（里/丈/亩/斤/吨）→ `(450 * 1e8) * 1000 kg`
+ *
+ * 顺序反了会漏：`450 亿吨` 先走单位展开时，「亿吨」不在单位表里，
+ * 原样留下；先展开量级词得到 `(450 * 1e8)吨`，再让单位展开处理「吨」才对。
+ *
+ * ## 为什么走文本变换而不是注册进 mathjs
+ *
+ * `buildMath` 里刻意删掉了 `createUnit`（表达式求值不允许往引擎注入任意定义）。
+ * 放开这个边界来支持中文单位，代价远大于收益。
+ *
+ * @param source - 已做过基础归一化的表达式
+ * @returns 中文单位与量级词已展开的表达式
+ */
+export declare function normalizeChineseUnits(source: string): string;
 /**
  * 设置本次调用的显示精度（在工具入口调用）。
  *

package/lib/types/playbook.d.ts

@@ -90,6 +90,34 @@ export declare function buildPlaybook(state: {
  * @param state - 工作区状态
  * @returns 精简提示词
  */
+/**
+ * brief 档的指令集（每轮都随注入下发，**每个字都在付费**）。
+ *
+ * ## 字数按「使用频率 × 重要程度」分配
+ *
+ * 曾经的问题是比例失调：整段 817 字符里，「世界推演」占了 360（44%），
+ * 而它只对做架空世界设定那类会话有用 —— 算术、单位换算、统计这些
+ * **高频场景完全用不到**，却要为它每轮付 360 字符。
+ *
+ * 现在按三档分配：
+ *
+ * | 内容 | 频率 | 重要度 | 字数 |
+ * |---|---|---|---|
+ * | 行为约束（必须调用 / 不要心算） | 每轮 | 极高 | ~40 |
+ * | 该用哪个 operation（最常问） | 极高 | 高 | ~70 |
+ * | 可信度标签怎么读 | 中 | 极高 | ~60 |
+ * | 精度两层 | 中 | 高 | ~50 |
+ * | 世界推演分工（低频，压到极限） | 低 | 中 | ~80 |
+ *
+ * ## 顺手修掉两处自相矛盾
+ *
+ * 原第 5 条说「输出默认全精度（几十位小数）」、第 6 条说「默认 8 位小数」——
+ * 两条并列下发，模型读到的是互相冲突的指令。**8 位才是现状**（2.1.0 起），
+ * 「全精度」那句是过时表述，已删。
+ *
+ * @param state - 工作区状态（改过的常数、自创量）
+ * @returns 指令集文本
+ */
 export declare function buildBriefPlaybook(state: {
     changedConstants?: string[];
     customConstants?: number;

package/lib/types/units-data.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 度量单位数据：古今中外，尽量收全。
+ *
+ * ## 公制中转
+ *
+ * 每个单位都只声明「它等于多少**该量纲的公制基准单位**」（`factor`），
+ * 换算于是变成 `value × 源factor ÷ 目标factor` 两步，任何两个单位都能互通。
+ * 这样加一个单位只需一行数据，不需要和已有单位两两配对（那是 O(n²) 的维护地狱）。
+ *
+ * 基准单位见 `units.ts` 的 `BASE_UNIT`：长度 m、质量 kg、时间 s、面积 m²、
+ * 体积 m³、能量 J、功率 W、温度 K、速度 m/s、压强 Pa，以及本模块新增量纲各自的基准。
+ *
+ * ## 为什么收这么多
+ *
+ * 作者写「这堵墙高三丈」「追了三十里地」「秤上三斤二两」时，
+ * 换算系数全靠脑记 —— 记错一次就是一次事故（实测反馈里有 3~4 次因为这个中断重算）。
+ * 收进表里，就把「记错数」变成「打错名」，后者一眼就能看出来。
+ *
+ * ## 收录原则
+ *
+ * · **不收需要上下文才能定的**（「一箭之地」「一盏茶工夫」）—— 猜就是错
+ * · **同一名字在不同体系有歧义时，收常用那个并在 note 里标明另一体系**
+ *   （加仑、担、石、马力都是这样）
+ * · **历史单位标朝代/年代**——尺、斤、里的数值历代不同，这是事实，不是精度问题
+ *
+ * @module dsh-math-calculator/units-data
+ */
+import type { Dimension, UnitDef } from './units.js';
+/**
+ * SI 词头（十进制），从最大到最小。
+ *
+ * 用于批量生成 `km`/`cm`/`mm` 这类前缀单位，避免手写几十行同构数据。
+ */
+export declare const SI_PREFIXES: Array<[string, number]>;
+/**
+ * 用 SI 词头批量生成一组单位。
+ *
+ * @param base - 词头后面的单位符号（如 `'m'` → `km`/`cm`/`mm`）
+ * @param dimension - 量纲
+ * @param baseFactor - 该单位本身的公制等值（如 `'t'` 的 1000 kg）
+ * @param aliasPrefix - 中文名前缀（如 `'千'\,`'厘'`），省略则不给中文别名
+ * @returns 单位定义数组（含词头为 1 的那个基础单位）
+ */
+/**
+ * 长度。
+ *
+ * 基准 m。收录：SI（含词头）、中国历代市制与古制、英制/美制、航海、
+ * 天文、日/俄/印等地域单位、微观与专业单位。
+ */
+export declare const LENGTH_UNITS: UnitDef[];
+/**
+ * 质量。
+ *
+ * 基准 kg。中国市制与古制、英制三套吨、金衡、药衡、日/俄等。
+ */
+export declare const MASS_UNITS: UnitDef[];
+/**
+ * 时间。
+ *
+ * 基准 s。含中国古制（刻/时辰/更/炷香）、佛家/道家时间、地质年代、天文周期。
+ */
+export declare const TIME_UNITS: UnitDef[];
+/**
+ * 面积。
+ *
+ * 基准 m²。中国市制亩/顷（各地亩不同）、英制 acre/rood、日本町/反步。
+ */
+export declare const AREA_UNITS: UnitDef[];
+/**
+ * 体积。
+ *
+ * 基准 m³。中国市制（斗/升/石）、英制美制（加仑三种！）、
+ * 烹饪量（杯/勺/茶匙）、酒桶、日本（合/升/石）。
+ *
+ * ⚠ 体积是歧义最多的量纲：加仑（美/英差 20%）、盎司（液量/常衡）、
+ * 夸脱、品脱都分英美两制。表里默认收**美制**并在 note 标明英制差异。
+ */
+export declare const VOLUME_UNITS: UnitDef[];
+/**
+ * 能量。
+ *
+ * 基准 J。含营养学卡路里、英制 BTU/therm、化石燃料（吨油当量/吨煤当量）、
+ * 火药与核武当量、以及家常能源计量（度、方气）。
+ */
+export declare const ENERGY_UNITS: UnitDef[];
+/**
+ * 功率。
+ *
+ * 基准 W。含马力两套（英制 745.7 / 公制 735）、制冷吨、
+ * 人力畜力（写古代题材最需要）、以及天体量级（太阳光度）。
+ */
+export declare const POWER_UNITS: UnitDef[];
+/**
+ * 温度、速度、压强，以及本模块新增的几个量纲。
+ *
+ * ## 温度为什么特殊
+ *
+ * 温度是**仿射**变换（`K = °C + 273.15`），不是比例。
+ * 表里的 `factor` 只表示「每 1 单位等于多少 K 的**间隔**」，
+ * 实际换算由 `units.ts` 的 `convert()` 用专门分支处理偏移。
+ * 只收三种有偏移的温标 + 一种无偏移的（K）。列氏/兰氏也收了，方便历史文本。
+ */
+export declare const TEMPERATURE_UNITS: UnitDef[];
+/**
+ * 速度。
+ *
+ * 基准 m/s。含航海（节）、航空（马赫两套基准）、
+ * 古代表述（「日行百里」拆成速度）、以及天体量级。
+ */
+export declare const SPEED_UNITS: UnitDef[];
+/**
+ * 压强。
+ *
+ * 基准 Pa。含工程（psi/bar）、气象（hPa/atm）、医学（mmHg）、真空（Torr）、
+ * 以及水柱/汞柱高度这类「用液柱高表示压强」的写法。
+ */
+export declare const PRESSURE_UNITS: UnitDef[];
+/**
+ * 本模块新增的量纲。
+ *
+ * 原表只有 10 个量纲（长/质/时/面/体/能/功/温/速/压）。写小说时还会撞上：
+ * 数据量（「这段代码多大」）、角度（「转三十度」）、力（「拉弓要多少牛」）、
+ * 频率（「一秒几次」）。
+ *
+ * 这些量纲的**基准单位也是公制 SI**，所以「公制中转」对它们同样成立。
+ */
+/** 数据量（十进制与二进制两套并存，差 2.4%~7%，是企业价目表最常见的坑）。 */
+export declare const DATA_UNITS: UnitDef[];
+/** 平面角。基准 rad（弧度）。 */
+export declare const ANGLE_UNITS: UnitDef[];
+/** 力。基准 N。 */
+export declare const FORCE_UNITS: UnitDef[];
+/** 频率（次要但常用）。基准 Hz。 */
+export declare const FREQUENCY_UNITS: UnitDef[];
+/**
+ * 用 SI 词头批量生成一组单位。
+ *
+ * 便于将来按需生成（当前表内的前缀单位已直接列在数据里，避免运行期拼装开销）。
+ *
+ * @param base - 词头后面的单位符号（如 'm' → km/cm/mm）
+ * @param dimension - 量纲
+ * @param baseFactor - 该单位本身的公制等值（如 't' 的 1000 kg）
+ * @returns 单位定义数组
+ */
+export declare function withPrefixes(base: string, dimension: Dimension, baseFactor: number): UnitDef[];
+/**
+ * 全部单位：公制（含 SI 词头）、中国市制与古制、英制与美制、航海、天文、
+ * 日本、俄国、印度、古希腊罗马，以及数据量 / 角度 / 力 / 频率。
+ *
+ * 每个条目只声明「等于多少**公制基准单位**」，因此任意两者都能互换 ——
+ * 这就是「公制做换算中转」的实现方式。
+ */
+/**
+ * 中国古制与市制的细分单位。
+ *
+ * ## 为什么这么多条
+ *
+ * 中文里长度、重量、容量三套都是**十进制细分**（尺寸分厘毫丝忽），
+ * 而且历代数值不同。写小说时「一厘银」「三忽」这类说法会出现，
+ * 但换算系数从来没人记得住 —— 这正是该收进表的理由。
+ *
+ * ⚠ 历代数值差异极大，表内统一用**市制（1929 年定制）**为基准，
+ * 古制差异写在 note 里；要精确到某朝代用 `customUnits` 覆盖。
+ */
+export declare const CHINA_EXTRA_UNITS: UnitDef[];
+/**
+ * 欧洲列强的传统单位（工业革命前后，写蒸汽朋克/历史题材的刚需）。
+ *
+ * ## 为什么这些必须收
+ *
+ * 公制是 1795 年法国才立、1875 年才国际化的。在此之前**每个国家各有一套**，
+ * 而且同一国不同行业还不一样（例如英国有常衡/金衡/药衡三套重量）。
+ *
+ * 写 1700—1900 年的故事时，人物说的「一普特面粉」「三十维尔斯特」是真的，
+ * 换算系数却没人记得住。这些数值来自当时的官方定义或学界通行近似。
+ */
+/** 俄制（沙俄，16—20 世纪初）。 */
+export declare const RUSSIA_UNITS: UnitDef[];
+/** 德制（普鲁士/各邦，1872 年统一前）。 */
+export declare const GERMANY_UNITS: UnitDef[];
+/** 法制（公制诞生地，但旧制 au 1795 前仍在使用）。 */
+export declare const FRANCE_UNITS: UnitDef[];
+/** 西班牙/葡萄牙/意大利/荷兰/北欧。 */
+export declare const OTHER_EUROPE_UNITS: UnitDef[];
+/**
+ * 东亚、南亚、西亚的传统单位。
+ *
+ * 日本是用户明确点名的：尺贯法（shakkan-hō）自成一套，且与中国市制
+ * 同字不同值（日尺 30.3 cm vs 市尺 32 cm，日斤 600 g vs 市斤 500 g）。
+ * 写日式题材（武士、町人、和风奇幻）时这些是刚需。
+ */
+/** 日本尺贯法（1891 年法定，沿用至公制化）。 */
+export declare const JAPAN_UNITS: UnitDef[];
+/** 印度（莫卧儿与英属时期）。 */
+export declare const INDIA_UNITS: UnitDef[];
+/** 阿拉伯/奥斯曼/波斯。 */
+export declare const ARABIA_UNITS: UnitDef[];
+/** 东南亚与其它。 */
+export declare const SEA_OTHER_UNITS: UnitDef[];
+/**
+ * 全部单位：公制（含 SI 词头）、中国市制与历代、日本尺贯法、
+ * 俄/德/法/西/葡/意/荷/北欧传统单位、印度/阿拉伯/奥斯曼、
+ * 英美制、航海与天文，以及数据量/角度/力/频率。
+ *
+ * 每个条目只声明「等于多少**公制基准单位**」，因此任意两者都能互换 ——
+ * 这就是「公制做换算中转」的实现方式。
+ *
+ * 条数见 `ALL_UNITS.length`（当前 429：度量衡 398 + 科学 31）。
+ */
+/**
+ * 电学、光学、化学与核物理的 SI 单位（补齐量纲断层）。
+ *
+ * ## 为什么必须补这一批
+ *
+ * 原来的单位表只有 4 个 SI 基本单位（m / kg / s / K），缺安培、摩尔、坎德拉 ——
+ * 于是**整个电学、光学、化学、核物理领域无法换算**：
+ * 写「十二伏电池」「三毫居里放射源」「0.5 戈瑞剂量」时工具一律不认识。
+ *
+ * 这一批把 7 个 SI 基本单位补全，并把 22 个具名导出单位落地，
+ * 连带 18 个新量纲（电流/电荷/电压/电容/电阻/电导/磁通/磁通密度/电感/
+ * 立体角/发光强度/光通量/照度/物质的量/活度/吸收剂量/剂量当量/催化活度）。
+ *
+ * ## 溯源
+ *
+ * 全部按 BIPM《SI Brochure》第 9 版（2019）Table 2/3/5。
+ * 非 SI 单位（Ci、rad、U、gauss）按 NIST SP 811 与 ISO 80000 系列。
+ *
+ * ## 一处同名冲突
+ *
+ * 辐射吸收剂量的 `rad` 与平面角弧度 `rad` 同名（插件已收弧度）。
+ * 辐射那条主名用 `rad_dose`，别名写 `rad (dose)` —— 两个都是正式写法，
+ * 但主名不能撞，否则查表时永远命中弧度。
+ */
+export declare const SI_ELECTRO_OPTICAL_UNITS: UnitDef[];
+/**
+ * 全部单位：公制（含 SI 词头）、中国市制与历代、日本尺贯法、
+ * 俄/德/法/西/葡/意/荷/北欧传统单位、印度/阿拉伯/奥斯曼、
+ * 英美制、航海与天文、电学/光学/化学/核物理的 SI 单位，
+ * 以及数据量/角度/力/频率。
+ *
+ * 每个条目只声明「等于多少**公制基准单位**」，因此任意两者都能互换 ——
+ * 这就是「公制做换算中转」的实现方式。
+ *
+ * 条数见 `ALL_UNITS.length`：462 条 / 32 个量纲
+ * （度量衡与科学两类，见 `UnitDef.category`）。
+ */
+export declare const ALL_UNITS: UnitDef[];
+/** 各量纲的基准（公制中转点）。换算永远「先乘到基准、再除以目标」。 */
+export declare const DIMENSION_BASE: Record<Dimension, string>;
+/** 量纲的中文名。 */
+export declare const DIMENSION_LABEL: Record<Dimension, string>;
+/** 量纲排列顺序（列单位时分组的顺序）。 */
+export declare const DIMENSION_ORDER: Dimension[];

package/lib/types/units.d.ts

@@ -35,6 +35,31 @@
  * @module dsh-math-calculator/units
  */
 /** 一个单位。 */
+/**
+ * 单位的**用途分类**。
+ *
+ * ## 为什么要分
+ *
+ * 这两类的使用场景完全不同，混在一张表里会让列表变得没法读：
+ *
+ * | 分类 | 例子 | 谁会用 |
+ * |---|---|---|
+ * | `measure`（度量衡） | 里、斤、斗、俄尺、日尺、加仑、英亩 | 写小说、算账、历史考据 |
+ * | `science`（科学） | eV、里德伯、靶恩、玻尔半径、amu、erg、slug | 物理/化学/天文计算 |
+ *
+ * 一个作者问「三丈是多少米」，不该在 422 条里跟「玻尔半径」挤在一起找；
+ * 反过来，算原子结合能的人也不关心「日尺」。分开列，两边都清爽。
+ *
+ * ## 判据
+ *
+ * · **度量衡**：日常生活、贸易、历史、工程里**人真的会说出口**的量
+ * · **科学**：只在专业计算里出现，日常语境说了没人懂（「这块地 3 靶恩」是笑话）
+ *
+ * 边界情况按「作者会不会在正文里写它」判：`psi` 会（工程题材），
+ * 所以算度量衡；`hartree` 不会（原子物理单位），算科学。
+ */
+export type UnitCategory = 'measure' | 'science';
+/** 一个单位。 */
 export interface UnitDef {
     /** 单位名（作者会写的写法）。 */
     name: string;
@@ -44,21 +69,46 @@ export interface UnitDef {
     dimension: Dimension;
     /** 换算到该量纲基准单位的系数（基准单位见 BASE_UNIT）。 */
     factor: number;
+    /**
+     * 用途分类，默认 `measure`（度量衡）。
+     *
+     * 省略时按度量衡处理 —— 表里绝大多数是这一类，
+     * 只给科学单位显式标 `science`，比逐条标更不容易漏。
+     */
+    category?: UnitCategory;
     /** 说明（什么时候用、有什么坑）。 */
     note?: string;
 }
-/** 支持的量纲。 */
-export type Dimension = 'length' | 'mass' | 'time' | 'area' | 'volume' | 'energy' | 'power' | 'temperature' | 'speed';
-/** 每个量纲的基准单位（factor = 1 的那个）。 */
+/**
+ * 支持的量纲。
+ *
+ * 分两层：**物理量纲**（长/质/时/面/体/能/功/温/速/压）与**扩展量纲**
+ * （数据量/角度/力/频率）—— 后者是写小说时同样会撞上的（「这段代码多大」
+ * 「转三十度」「拉弓要多少牛」），它们各自的公制基准也定义在 units-data。
+ */
+export type Dimension = 'length' | 'mass' | 'time' | 'area' | 'volume' | 'energy' | 'power' | 'temperature' | 'speed' | 'pressure' | 'data' | 'angle' | 'force' | 'frequency' | 'current' | 'charge' | 'voltage' | 'capacitance' | 'resistance' | 'conductance' | 'magnetic_flux' | 'magnetic_flux_density' | 'inductance' | 'solid_angle' | 'luminous_intensity' | 'luminous_flux' | 'illuminance' | 'amount_of_substance' | 'activity' | 'absorbed_dose' | 'dose_equivalent' | 'catalytic_activity';
+/**
+ * 每个量纲的基准单位（factor = 1 的那个）—— 即「公制中转点」。
+ *
+ * 定义在 `units-data.ts`，这里再导出，保持旧的导入路径可用。
+ */
+import { DIMENSION_LABEL, DIMENSION_ORDER } from './units-data.js';
+/** 每个量纲的基准单位 —— 即「公制中转点」。 */
 export declare const BASE_UNIT: Record<Dimension, string>;
 /** 量纲的中文名。 */
-export declare const DIMENSION_LABEL: Record<Dimension, string>;
+export { DIMENSION_LABEL, DIMENSION_ORDER };
 /**
  * 内置单位表。
  *
  * ⚠️ 中文古制的换算**历朝不同**，这里用最常见的近似值并在 note 里标注。
  * 作者若需要精确到某个朝代，用 `customUnits` 覆盖。
  */
+/**
+ * 内置单位表 —— 从 `units-data.ts` 导入（那里按体系分节，便于查阅与扩充）。
+ *
+ * 现在是 **288 条**：公制（含 SI 词头）、中国市制与古制、英制与美制、
+ * 航海、天文、日本、俄国、印度、古希腊罗马，外加数据量/角度/力/频率。
+ */
 export declare const UNITS: UnitDef[];
 /**
  * 按名字查单位（含别名）。

package/lib/types/workspace.d.ts

@@ -74,6 +74,19 @@ export interface WorkspaceData {
      * 未设置时沿用计算精度（即完整输出，旧行为）。
      */
     displayPrecision?: number;
+    /**
+     * 是否让 `variables` 里的命名变量**参与计算**。
+     *
+     * ## 为什么默认关闭
+     *
+     * 打开后，同一个调用在不同工作区状态下会给出不同结果 ——
+     * 那会削弱「同输入同输出」，而后者是本项目做 hash 复现与回归对比的基础。
+     * 所以这是一个**显式的、逐工作区的**选择，不默认生效。
+     *
+     * 关闭时 `variables` 仍然照常存着（能 show、能 remove），
+     * 只是不参与计算 —— 与未引入这个功能时的行为完全一致。
+     */
+    useWorkspaceVariables?: boolean;
     /** 创建时间。 */
     createdAt: string;
     /** 最后修改时间。 */
@@ -336,4 +349,41 @@ export declare function bindHostWorkspace(rawId: unknown, rawTitle: unknown, mak
  * @param name - 工作区名；省略用当前活动工作区
  * @returns 显示有效位数；未设置返回 undefined
  */
+/**
+ * 读出当前工作区里登记的命名变量（`variables` 字段）。
+ *
+ * ## 这个函数为什么存在
+ *
+ * 工作区的 `variables` 字段、写入路径（`action2:"set"` + `workspaceVariables`）、
+ * 删除路径（`remove-variable`）、显示（`show`）**都已经有了**，
+ * 唯独**读取路径缺**——存进去的变量在计算里根本用不到。
+ *
+ * 实测：
+ *
+ * ```
+ *   {action2:"set", workspaceVariables:{BTU_LB:1260000}}  → 变量 2 个   ✓ 存住了
+ *   {expression:"BTU_LB/1000"}                            → Undefined symbol  ✗ 用不了
+ * ```
+ *
+ * 也就是说这是「能删不能加、加了用不了」的半成品，不是需要从头设计的新能力。
+ *
+ * ## 失败时返回空对象，不抛异常
+ *
+ * 读工作区失败（文件损坏、目录不可写）不该让一次正常计算失败。
+ * 但**空对象与「真的没有变量」无法区分**，所以缓存指纹那边
+ * 不能只靠这个函数的返回值 —— 见 `index.ts` 里的 `workspaceVariablesFingerprint`。
+ *
+ * @param name - 工作区名；省略则用当前工作区
+ * @returns 变量字典（数字形态）；读不到时为空对象
+ */
+export declare function workspaceVariablesOf(name?: string): Record<string, number>;
+/**
+ * 读当前工作区固化的**显示**精度（小数点后几位）。
+ *
+ * 未设或读到 0 时返回 undefined，调用方据此回落默认值。
+ * 语义与「本次调用传入的 displayPrecision」一致：都是小数点后位数。
+ *
+ * @param name - 工作区名；省略则用当前工作区
+ * @returns 显示位数；未设或读不到返回 undefined
+ */
 export declare function displayPrecisionOf(name?: string): number | undefined;