dsh-math-calculator 2.1.1 → 2.2.0

package/src/units.ts

@@ -35,6 +35,34 @@
  * @module dsh-math-calculator/units
  */
 
+import { ALL_UNITS } from './units-data.js'
+
+/** 一个单位。 */
+/**
+ * 单位的**用途分类**。
+ *
+ * ## 为什么要分
+ *
+ * 这两类的使用场景完全不同，混在一张表里会让列表变得没法读：
+ *
+ * | 分类 | 例子 | 谁会用 |
+ * |---|---|---|
+ * | `measure`（度量衡） | 里、斤、斗、俄尺、日尺、加仑、英亩 | 写小说、算账、历史考据 |
+ * | `science`（科学） | eV、里德伯、靶恩、玻尔半径、amu、erg、slug | 物理/化学/天文计算 |
+ *
+ * 一个作者问「三丈是多少米」，不该在 422 条里跟「玻尔半径」挤在一起找；
+ * 反过来，算原子结合能的人也不关心「日尺」。分开列，两边都清爽。
+ *
+ * ## 判据
+ *
+ * · **度量衡**：日常生活、贸易、历史、工程里**人真的会说出口**的量
+ * · **科学**：只在专业计算里出现，日常语境说了没人懂（「这块地 3 靶恩」是笑话）
+ *
+ * 边界情况按「作者会不会在正文里写它」判：`psi` 会（工程题材），
+ * 所以算度量衡；`hartree` 不会（原子物理单位），算科学。
+ */
+export type UnitCategory = 'measure' | 'science'
+
 /** 一个单位。 */
 export interface UnitDef {
   /** 单位名（作者会写的写法）。 */
@@ -45,12 +73,26 @@ export interface UnitDef {
   dimension: Dimension
   /** 换算到该量纲基准单位的系数（基准单位见 BASE_UNIT）。 */
   factor: number
+  /**
+   * 用途分类，默认 `measure`（度量衡）。
+   *
+   * 省略时按度量衡处理 —— 表里绝大多数是这一类，
+   * 只给科学单位显式标 `science`，比逐条标更不容易漏。
+   */
+  category?: UnitCategory
   /** 说明（什么时候用、有什么坑）。 */
   note?: string
 }
 
-/** 支持的量纲。 */
+/**
+ * 支持的量纲。
+ *
+ * 分两层：**物理量纲**（长/质/时/面/体/能/功/温/速/压）与**扩展量纲**
+ * （数据量/角度/力/频率）—— 后者是写小说时同样会撞上的（「这段代码多大」
+ * 「转三十度」「拉弓要多少牛」），它们各自的公制基准也定义在 units-data。
+ */
 export type Dimension =
+  // ── 力学与几何（14 个原有）──
   | 'length'
   | 'mass'
   | 'time'
@@ -60,32 +102,45 @@ export type Dimension =
   | 'power'
   | 'temperature'
   | 'speed'
+  | 'pressure'
+  | 'data'
+  | 'angle'
+  | 'force'
+  | 'frequency'
+  // ── 电学（8 个）──
+  | 'current'
+  | 'charge'
+  | 'voltage'
+  | 'capacitance'
+  | 'resistance'
+  | 'conductance'
+  | 'magnetic_flux'
+  | 'magnetic_flux_density'
+  | 'inductance'
+  // ── 光学（3 个）──
+  | 'solid_angle'
+  | 'luminous_intensity'
+  | 'luminous_flux'
+  | 'illuminance'
+  // ── 化学与核物理（5 个）──
+  | 'amount_of_substance'
+  | 'activity'
+  | 'absorbed_dose'
+  | 'dose_equivalent'
+  | 'catalytic_activity'
 
-/** 每个量纲的基准单位（factor = 1 的那个）。 */
-export const BASE_UNIT: Record<Dimension, string> = {
-  length: 'm',
-  mass: 'kg',
-  time: 's',
-  area: 'm²',
-  volume: 'm³',
-  energy: 'J',
-  power: 'W',
-  temperature: 'K',
-  speed: 'm/s',
-}
+/**
+ * 每个量纲的基准单位（factor = 1 的那个）—— 即「公制中转点」。
+ *
+ * 定义在 `units-data.ts`，这里再导出，保持旧的导入路径可用。
+ */
+import { DIMENSION_BASE, DIMENSION_LABEL, DIMENSION_ORDER } from './units-data.js'
+
+/** 每个量纲的基准单位 —— 即「公制中转点」。 */
+export const BASE_UNIT = DIMENSION_BASE
 
 /** 量纲的中文名。 */
-export const DIMENSION_LABEL: Record<Dimension, string> = {
-  length: '长度',
-  mass: '质量',
-  time: '时间',
-  area: '面积',
-  volume: '体积',
-  energy: '能量',
-  power: '功率',
-  temperature: '温度',
-  speed: '速度',
-}
+export { DIMENSION_LABEL, DIMENSION_ORDER }
 
 /**
  * 内置单位表。
@@ -93,104 +148,13 @@ export const DIMENSION_LABEL: Record<Dimension, string> = {
  * ⚠️ 中文古制的换算**历朝不同**，这里用最常见的近似值并在 note 里标注。
  * 作者若需要精确到某个朝代，用 `customUnits` 覆盖。
  */
-export const UNITS: UnitDef[] = [
-  // ── 长度 ──
-  { name: 'm', dimension: 'length', factor: 1, note: '基准单位' },
-  { name: 'km', dimension: 'length', factor: 1000 },
-  { name: 'cm', dimension: 'length', factor: 0.01 },
-  { name: 'mm', dimension: 'length', factor: 0.001 },
-  {
-    name: '里',
-    dimension: 'length',
-    factor: 500,
-    note: '市里 = 500 m。周制约 415 m、汉制约 415 m、清制 576 m——写古代按朝代覆盖',
-  },
-  { name: '丈', dimension: 'length', factor: 3.2, note: '市丈 = 3.2 m（10 尺）' },
-  { name: '尺', dimension: 'length', factor: 0.32, note: '市尺 ≈ 32 cm。汉尺约 23 cm、明清营造尺约 32 cm' },
-  { name: '寸', dimension: 'length', factor: 0.032, note: '市寸 = 1/10 尺' },
-  { name: '步', dimension: 'length', factor: 1.6, note: '古代一步 ≈ 5 尺 ≈ 1.6 m（「百步穿杨」约 160 m）' },
-  { name: 'mile', aliases: ['英里', 'mi'], dimension: 'length', factor: 1609.344 },
-  { name: 'ft', aliases: ['英尺'], dimension: 'length', factor: 0.3048 },
-  { name: 'in', aliases: ['英寸'], dimension: 'length', factor: 0.0254 },
-  { name: 'nmi', aliases: ['海里'], dimension: 'length', factor: 1852 },
-  { name: 'AU', aliases: ['天文单位'], dimension: 'length', factor: 1.495978707e11, note: '日地平均距离' },
-  { name: 'ly', aliases: ['光年'], dimension: 'length', factor: 9.4607304725808e15 },
-  { name: 'pc', aliases: ['秒差距'], dimension: 'length', factor: 3.0856775814913673e16 },
-  { name: 'Rearth', aliases: ['地球半径'], dimension: 'length', factor: 6.371e6 },
-  { name: 'Rsun', aliases: ['太阳半径'], dimension: 'length', factor: 6.957e8 },
-
-  // ── 质量 ──
-  { name: 'kg', dimension: 'mass', factor: 1, note: '基准单位' },
-  { name: 'g', dimension: 'mass', factor: 0.001 },
-  { name: 't', aliases: ['吨'], dimension: 'mass', factor: 1000 },
-  { name: '斤', dimension: 'mass', factor: 0.5, note: '市斤 = 500 g（10 两）' },
-  { name: '两', dimension: 'mass', factor: 0.05, note: '市两 = 50 g' },
-  { name: '石', dimension: 'mass', factor: 60, note: '容量/重量混用单位，此处按「一石米约 60 kg」估' },
-  { name: 'lb', aliases: ['磅'], dimension: 'mass', factor: 0.45359237 },
-  { name: 'oz', aliases: ['盎司'], dimension: 'mass', factor: 0.028349523125 },
-  { name: 'Mearth', aliases: ['地球质量'], dimension: 'mass', factor: 5.972e24 },
-  { name: 'Msun', aliases: ['太阳质量'], dimension: 'mass', factor: 1.989e30 },
-
-  // ── 时间 ──
-  { name: 's', dimension: 'time', factor: 1, note: '基准单位' },
-  { name: 'min', aliases: ['分钟'], dimension: 'time', factor: 60 },
-  { name: 'h', aliases: ['小时'], dimension: 'time', factor: 3600, note: '与普朗克常数 h 同名，单位换算里按小时理解' },
-  { name: 'day', aliases: ['天', '日'], dimension: 'time', factor: 86400 },
-  { name: 'year', aliases: ['年'], dimension: 'time', factor: 3.15576e7, note: '儒略年 = 365.25 天' },
-  { name: 'Gyr', aliases: ['十亿年'], dimension: 'time', factor: 3.15576e16 },
-  { name: '刻', dimension: 'time', factor: 900, note: '古代一刻 ≈ 15 分钟（百刻制一天）' },
-  { name: '时辰', dimension: 'time', factor: 7200, note: '一个时辰 = 2 小时（十二时辰制）' },
-  { name: '更', dimension: 'time', factor: 7200, note: '一夜五更，每更约 2 小时' },
-
-  // ── 面积 ──
-  { name: 'm²', dimension: 'area', factor: 1, note: '基准单位' },
-  { name: 'km²', dimension: 'area', factor: 1e6 },
-  { name: 'ha', aliases: ['公顷'], dimension: 'area', factor: 1e4 },
-  { name: '亩', dimension: 'area', factor: 666.6666666666666, note: '市亩 ≈ 666.7 m²（15 亩 = 1 公顷）' },
-  { name: '顷', dimension: 'area', factor: 66666.66666666667, note: '一顷 = 100 亩' },
-  { name: 'acre', aliases: ['英亩'], dimension: 'area', factor: 4046.8564224 },
-
-  // ── 体积 ──
-  { name: 'm³', dimension: 'volume', factor: 1, note: '基准单位' },
-  { name: 'L', aliases: ['升'], dimension: 'volume', factor: 0.001 },
-  { name: '斗', dimension: 'volume', factor: 0.01, note: '市斗 = 10 L；古代一斗约 2—20 L，差异极大' },
-  { name: 'gal', aliases: ['加仑'], dimension: 'volume', factor: 0.003785411784, note: '美制加仑' },
-
-  // ── 能量 ──
-  { name: 'J', dimension: 'energy', factor: 1, note: '基准单位' },
-  { name: 'kJ', dimension: 'energy', factor: 1000 },
-  { name: 'MJ', dimension: 'energy', factor: 1e6 },
-  { name: 'GJ', dimension: 'energy', factor: 1e9 },
-  { name: 'kWh', aliases: ['度'], dimension: 'energy', factor: 3.6e6, note: '一度电 = 3.6 MJ' },
-  { name: 'cal', aliases: ['卡'], dimension: 'energy', factor: 4.184 },
-  { name: 'kcal', aliases: ['大卡', '千卡'], dimension: 'energy', factor: 4184, note: '营养学的「卡路里」其实是大卡' },
-  { name: 'TNT', dimension: 'energy', factor: 4.184e9, note: '1 吨 TNT 当量' },
-  { name: 'eV', dimension: 'energy', factor: 1.602176634e-19 },
-  { name: 'eVperBond', aliases: [], dimension: 'energy', factor: 1.602176634e-19 },
-
-  // ── 功率 ──
-  { name: 'W', dimension: 'power', factor: 1, note: '基准单位' },
-  { name: 'kW', dimension: 'power', factor: 1000 },
-  { name: 'MW', dimension: 'power', factor: 1e6 },
-  { name: 'GW', dimension: 'power', factor: 1e9 },
-  { name: 'TW', dimension: 'power', factor: 1e12 },
-  { name: 'hp', aliases: ['马力'], dimension: 'power', factor: 745.6998715822702 },
-  { name: '人', aliases: ['人力'], dimension: 'power', factor: 75, note: '一个成年人持续体力输出约 75—100 W（长时间）' },
-  { name: '畜', aliases: ['畜力'], dimension: 'power', factor: 500, note: '一头上等役畜持续输出约 500 W' },
-
-  // ── 温度 ──
-  // 温度是仿射换算（有偏移），不能只用系数；见 convert() 里的专门分支
-  { name: 'K', dimension: 'temperature', factor: 1, note: '基准单位，无偏移' },
-  { name: '°C', aliases: ['℃', '摄氏度'], dimension: 'temperature', factor: 1, note: 'K = °C + 273.15' },
-  { name: '°F', aliases: ['℉', '华氏度'], dimension: 'temperature', factor: 5 / 9, note: 'K = (°F + 459.67) × 5/9' },
-
-  // ── 速度 ──
-  { name: 'm/s', dimension: 'speed', factor: 1, note: '基准单位' },
-  { name: 'km/h', dimension: 'speed', factor: 1 / 3.6 },
-  { name: 'mph', aliases: ['英里每小时'], dimension: 'speed', factor: 0.44704 },
-  { name: 'mach', aliases: ['马赫'], dimension: 'speed', factor: 340.29, note: '按海平面 15°C 声速折算；高空声速更低' },
-  { name: 'c', aliases: ['光速'], dimension: 'speed', factor: 299792458 },
-]
+/**
+ * 内置单位表 —— 从 `units-data.ts` 导入（那里按体系分节，便于查阅与扩充）。
+ *
+ * 现在是 **288 条**：公制（含 SI 词头）、中国市制与古制、英制与美制、
+ * 航海、天文、日本、俄国、印度、古希腊罗马，外加数据量/角度/力/频率。
+ */
+export const UNITS: UnitDef[] = ALL_UNITS
 
 /**
  * 按名字查单位（含别名）。
@@ -325,14 +289,69 @@ export function convert(
   } else {
     const inBase = value * from.factor
     result = inBase / to.factor
-    steps.push('1 ' + from.name + ' = ' + from.factor + ' ' + BASE_UNIT[from.dimension])
-    steps.push(
-      show(value) + ' ' + from.name + ' = ' + show(inBase) + ' ' + BASE_UNIT[from.dimension],
-    )
-    steps.push(
-      '1 ' + to.name + ' = ' + to.factor + ' ' + BASE_UNIT[to.dimension] +
-      '，故结果 = ' + show(result) + ' ' + to.name,
-    )
+    /**
+     * 代入过程只写「有信息量」的步骤。
+     *
+     * ## 修的是什么
+     *
+     * 实测反馈（2026-11-06）原话：换算 kg → t 时「代入过程」里出现
+     * 「1 kg = 1 kg」「9.0000e+15 kg = 9.0000e+15 kg」这类**同义重复**，
+     * 属无效信息 —— 而且它让输出**看起来有内容，其实没有**。
+     *
+     * 根因：当 from 或 to 恰好是基准单位（factor = 1）时，
+     * 那一步就是「X = X」，什么都没说明。
+     *
+     * 现在的规则：
+     *   · from.factor ≠ 1 时才写「1 from = N base」（否则 1 = 1，无信息）
+     *   · from.factor ≠ 1 时才写「value from = inBase base」（上面那行是它的依据）
+     *   · to.factor ≠ 1 时才写「1 to = M base」；无论哪种都写「故结果 = ...」
+     *
+     * 换算到基准单位时，过程就只剩一行结论 —— 那本来就是它的全部信息。
+     */
+    const fromIsBase = from.factor === 1
+    const toIsBase = to.factor === 1
+    const baseName = BASE_UNIT[from.dimension]
+
+    /**
+     * ## 合并成一行，避免同一个换算关系说两遍
+     *
+     * 踩过：`t → kg` 时先写「1 t = 1000 kg」，再写
+     * 「9.0000e+15 t = 9.0000e+15 kg」—— 两行说的是**同一件事**
+     * （因为 inBase 恰好等于 inBase，且 to 就是基准单位）。
+     *
+     * 现在按信息量分三种：
+     *   · 源非基准、目标非基准 → 「1 from = N base，1 to = M base，故结果」
+     *   · 源非基准、目标是基准 → 「value from = X base，故结果 = X to」
+     *   · 源是基准、目标非基准 → 「1 to = M base，故结果」
+     *   · 两者都是基准       → 只剩结论（其实同名，前面已处理）
+     */
+    if (!fromIsBase && !toIsBase) {
+      /**
+       * 两个都非基准 → 中间值**必须给**。
+       *
+       * 它是「30 里 = 15000 m = 15 km」这条链的中段：
+       * 少了它，调用方无法核对「500 × 30」这一步是否算对。
+       * 这与「去掉同义重复」不冲突 —— 重复指的是 `1 X = 1 X` 那种零信息行，
+       * 而中间值是真信息。
+       */
+      steps.push('1 ' + from.name + ' = ' + from.factor + ' ' + baseName)
+      steps.push(show(value) + ' ' + from.name + ' = ' + show(inBase) + ' ' + baseName)
+      steps.push('1 ' + to.name + ' = ' + to.factor + ' ' + baseName)
+      steps.push('故结果 = ' + show(result) + ' ' + to.name)
+    } else if (!fromIsBase && toIsBase) {
+      steps.push(show(value) + ' ' + from.name + ' = ' + show(inBase) + ' ' + baseName)
+      steps.push('故结果 = ' + show(result) + ' ' + to.name)
+    } else if (fromIsBase && !toIsBase) {
+      steps.push('1 ' + to.name + ' = ' + to.factor + ' ' + baseName)
+      steps.push('故结果 = ' + show(result) + ' ' + to.name)
+    } else {
+      steps.push('故结果 = ' + show(result) + ' ' + to.name)
+    }
+  }
+  if (from.name === to.name) {
+    /** 源与目标同名：换算本身无操作，别编出一段过程。 */
+    steps.length = 0
+    steps.push('源单位与目标单位同名，数值不变。')
   }
 
   if (from.note) warnings.push(from.name + '：' + from.note)

package/src/workspace.ts

@@ -81,6 +81,19 @@ export interface WorkspaceData {
    * 未设置时沿用计算精度（即完整输出，旧行为）。
    */
   displayPrecision?: number
+  /**
+   * 是否让 `variables` 里的命名变量**参与计算**。
+   *
+   * ## 为什么默认关闭
+   *
+   * 打开后，同一个调用在不同工作区状态下会给出不同结果 ——
+   * 那会削弱「同输入同输出」，而后者是本项目做 hash 复现与回归对比的基础。
+   * 所以这是一个**显式的、逐工作区的**选择，不默认生效。
+   *
+   * 关闭时 `variables` 仍然照常存着（能 show、能 remove），
+   * 只是不参与计算 —— 与未引入这个功能时的行为完全一致。
+   */
+  useWorkspaceVariables?: boolean
   /** 创建时间。 */
   createdAt: string
   /** 最后修改时间。 */
@@ -899,6 +912,58 @@ export function bindHostWorkspace(
  * @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 function workspaceVariablesOf(name?: string): Record<string, number> {
+  try {
+    const data = loadWorkspace(name ?? activeWorkspaceName)
+    const source = data.variables
+    if (!source || typeof source !== 'object') return {}
+    const result: Record<string, number> = {}
+    for (const [key, value] of Object.entries(source)) {
+      const numeric = typeof value === 'number' ? value : Number(value)
+      if (Number.isFinite(numeric)) result[key] = numeric
+    }
+    return result
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 读当前工作区固化的**显示**精度（小数点后几位）。
+ *
+ * 未设或读到 0 时返回 undefined，调用方据此回落默认值。
+ * 语义与「本次调用传入的 displayPrecision」一致：都是小数点后位数。
+ *
+ * @param name - 工作区名；省略则用当前工作区
+ * @returns 显示位数；未设或读不到返回 undefined
+ */
 export function displayPrecisionOf(name?: string): number | undefined {
   try {
     const data = loadWorkspace(name ?? activeWorkspaceName)