dsh-math-calculator 2.0.0 → 2.1.0

package/lib/result-cache.js

@@ -0,0 +1,144 @@
+/**
+ * 计算结果缓存：同样的输入不再算第二遍。
+ *
+ * ## 为什么值得做（而不只是优化）
+ *
+ * 反复算同一个式子在真实使用里很常见：
+ *   · 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
+ */
+/** 缓存容量上限。 */
+const MAX_ENTRIES = 256;
+/** 主存储。Map 保留插入顺序，正好用来做 LRU。 */
+const store = new Map();
+/** 命中/未命中统计（供诊断）。 */
+let hits = 0;
+let misses = 0;
+/**
+ * 把一个值规范成稳定的字符串，用于参与缓存键。
+ *
+ * 为什么不用 JSON.stringify：对象键的顺序不保证一致
+ * （`{a:1,b:2}` 与 `{b:2,a:1}` 应视为同一个键），
+ * 且浮点表示可能因来源不同而不一致。这里按键名排序后拼接。
+ *
+ * @param value - 任意值
+ * @returns 稳定字符串
+ */
+function stableStringify(value) {
+    if (value === null || value === undefined)
+        return String(value);
+    const kind = typeof value;
+    if (kind === 'number') {
+        // 数字统一用 15 位有效数字，避免 -0 / 0.1+0.2 这类表示差异
+        return Number.isFinite(value) ? value.toPrecision(15) : String(value);
+    }
+    if (kind === 'string' || kind === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return '[' + value.map(stableStringify).join(',') + ']';
+    if (kind === 'object') {
+        const object = value;
+        const keys = Object.keys(object).sort();
+        return '{' + keys.map(function (key) {
+            return key + ':' + stableStringify(object[key]);
+        }).join(',') + '}';
+    }
+    return String(value);
+}
+/**
+ * 计算缓存键。
+ *
+ * @param parts - 参与键的各个部分（按固定顺序传入）
+ * @returns 键字符串
+ */
+export function cacheKey(parts) {
+    return parts.map(stableStringify).join('\u0001');
+}
+/**
+ * 取缓存。
+ *
+ * @param key - 缓存键
+ * @returns 命中则返回缓存值；未命中返回 undefined
+ */
+export function getCached(key) {
+    const entry = store.get(key);
+    if (entry === undefined) {
+        misses++;
+        return undefined;
+    }
+    hits++;
+    entry.hits++;
+    // LRU：命中后移到队尾（最新）
+    store.delete(key);
+    store.set(key, entry);
+    return entry.value;
+}
+/**
+ * 存缓存。
+ *
+ * @param key - 缓存键
+ * @param value - 要缓存的值
+ */
+export function setCached(key, value) {
+    if (store.has(key))
+        store.delete(key);
+    store.set(key, { value, hits: 0 });
+    // 超容量时淘汰最久未使用的（队首）
+    while (store.size > MAX_ENTRIES) {
+        const oldest = store.keys().next();
+        if (oldest.done)
+            break;
+        store.delete(oldest.value);
+    }
+}
+/**
+ * 清空缓存（改常数、切工作区时应当调用）。
+ *
+ * 为什么需要显式清空：缓存的键里已经含常数与工作区，
+ * 理论上不会串；但**清空是个安全网**——
+ * 万一某条路径漏把常数放进键里，清空能兜住，而不是静默返回旧值。
+ */
+export function clearCache() {
+    store.clear();
+}
+/**
+ * 缓存统计（供诊断与测试）。
+ *
+ * @returns 条目数、命中、未命中
+ */
+export function cacheStats() {
+    return { size: store.size, hits: hits, misses: misses };
+}
+/**
+ * 重置统计（不影响已存条目）。
+ */
+export function resetCacheStats() {
+    hits = 0;
+    misses = 0;
+}

package/lib/types/awareness.d.ts

@@ -32,10 +32,16 @@ export declare function getPromptMode(): PromptMode;
 /**
  * 第一层：工具描述。
  *
- * 这是模型**每次**看工具清单时都会读到的内容，所以必须：
- *   - 完整列出 operation（漏一个，模型就不知道它存在）
- *   - 写「何时使用」而不是只写「是什么」
- *   - 给出触发关键词，让模型在遇到这类问题时想起它
+ * 这是模型**每次**看工具清单时都会读到的内容 —— 属于每轮固定成本，
+ * 所以要跟 parameters schema 一样抠字数。
+ *
+ * 压缩原则：
+ *   · **不重复 enum**：operation 的取值已在 schema 的 enum 里列全（300 字符），
+ *     这里再列一遍是纯重复。只保留「怎么选」的判断线索。
+ *   · **能移到 help 的就移**：详细字段表、单位清单等只在用到时才需要，
+ *     放 help 里不占每轮成本。
+ *   · **保留行为约束**：如「必须调本工具」「精度分两层」这类会改变模型行为的，
+ *     不能砍 —— 它们省下的重算远多于自身开销。
  */
 export declare const TOOL_DESCRIPTION: string;
 /**

package/lib/types/body-catalog.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 天体目录：恒星、行星、卫星、小天体的代表性样本。
+ *
+ * ## 为什么需要这个，而不是让作者自己查
+ *
+ * 写架空世界时最费劲的一步是「先锚一个现实参照物」：我要写一颗潮汐锁定的
+ * 红矮星行星，它该多大、多重、多少度？没有参照，数字全靠猜。
+ *
+ * 本文件收录真实观测值（尽量带来源量级），让作者能：
+ *   · 直接拿某颗真实天体当基线改（「比开普勒-1649c 再热一点」）
+ *   · 或看一组同类天体的分布范围，判断自己的设定落在什么分位
+ *
+ * ## 最关键的设计：区分「物理决定」与「只在地球标定」
+ *
+ * 这是本项目反复强调的分层。改物理常数（α、G、c）时，不同量必须区别对待：
+ *
+ * | 类别 | 例 | 改常数时会怎样 |
+ * |---|---|---|
+ * | `first-principles` | 质量、半径、轨道半径 | **不变**。它们由引力与初始条件决定，与 α 几乎无关 |
+ * | `scaled` | 光度、有效温度、寿命 | **变**。由核反应速率与斯特藩-玻尔兹曼决定，依赖 α |
+ * | `calibrated` | 行星平衡温度、反照率、温室增温 | **只在地球标定下可信**。超出适用域时本文件只给方向 |
+ * | `contingent` | 大气成分、云量、磁场、板块 | **不可推导**。这是历史偶然，不是物理必然 |
+ *
+ * ⚠️ 最容易犯的错：把 `calibrated` 的数值当成物理定律。
+ * 地球反照率 0.30 不是物理常数，是「有云、有海、有冰」的结果——
+ * 换一颗行星就完全不同。所以每个 calibrated 条目都写明适用域。
+ *
+ * ## 收录标准
+ *
+ * 只收**有可靠观测或可靠理论**的样本，不收「疑似存在的系外行星」。
+ * 数值给到有效位数为止，不假装精确——观测误差本来就大。
+ *
+ * @module dsh-math-calculator/body-catalog
+ */
+/** 一个量对物理常数的依赖方式（决定改常数后它该不该变）。 */
+export type ConstantDependence = 'first-principles' | 'scaled' | 'calibrated' | 'contingent';
+/** 一条带来源的数值。 */
+export interface MeasuredValue {
+    /** 数值。 */
+    value: number;
+    /** 单位。 */
+    unit: string;
+    /**
+     * 对物理常数的依赖方式。
+     *
+     * 改常数后是否重算，由它决定：
+     *   first-principles / contingent → **不变**
+     *   scaled                        → **会变**（由公式决定）
+     *   calibrated                    → **只在地球适用域内可信**
+     */
+    dependence: ConstantDependence;
+    /** 观测/理论误差（1σ 或量级）。没有就给 undefined，别编。 */
+    uncertainty?: number;
+    /** 适用域（calibrated 必填）。 */
+    domain?: string;
+    /** 来源（尽量写具体：任务名 / 目录名 / 理论）。 */
+    source: string;
+}
+/** 天体类别。 */
+export type BodyKind = 'star' | 'planet-terrestrial' | 'planet-gas-giant' | 'planet-ice-giant' | 'planet-super-earth' | 'planet-mini-neptune' | 'moon' | 'dwarf-planet' | 'asteroid' | 'kuiper-object';
+/** 一个天体的目录条目。 */
+export interface BodyEntry {
+    /** 标识。 */
+    id: string;
+    /** 中文名。 */
+    name: string;
+    /** 类别。 */
+    kind: BodyKind;
+    /** 一句话：它是什么样的天体，读者会怎么感知。 */
+    summary: string;
+    /** 宿主恒星（行星/卫星才填）。 */
+    host?: string;
+    /** 轨道半长轴（AU）。 */
+    semiMajorAxisAU?: MeasuredValue;
+    /** 质量（地球质量）。 */
+    massEarth?: MeasuredValue;
+    /** 半径（地球半径）。 */
+    radiusEarth?: MeasuredValue;
+    /** 表面重力（地球 g）。由 M/R² 算出时标 first-principles。 */
+    surfaceGravityG?: MeasuredValue;
+    /** 平衡温度 K（不含温室）。 */
+    equilibriumTempK?: MeasuredValue;
+    /** 实测表面/有效温度 K。 */
+    surfaceTempK?: MeasuredValue;
+    /** 几何反照率。 */
+    albedo?: MeasuredValue;
+    /** 自转周期（小时）。 */
+    rotationHours?: MeasuredValue;
+    /** 轴倾角（度）。 */
+    obliquityDeg?: MeasuredValue;
+    /** 轨道偏心率。 */
+    eccentricity?: MeasuredValue;
+    /** 大气压（地球=1）。 */
+    pressureAtm?: MeasuredValue;
+    /** 主要大气成分（百分比的粗描述）。 */
+    atmosphere?: string;
+    /** 是否潮汐锁定。 */
+    tidallyLocked?: boolean;
+    /** 作者需要注意的要点。 */
+    notes: string;
+}
+/** 恒星目录条目（比 STAR_CLASSES 更细，带真实样本）。 */
+export interface NamedStar extends BodyEntry {
+    kind: 'star';
+    /** 光谱型。 */
+    spectralType: string;
+    /** 亮度级：V 主序 / IV 次巨星 / III 巨星 / II 亮巨星 / I 超巨星 / D 白矮星。 */
+    luminosityClass: 'V' | 'IV' | 'III' | 'II' | 'I' | 'D';
+    /** 光度（太阳）。 */
+    luminositySun: MeasuredValue;
+    /** 质量（太阳）。 */
+    massSun: MeasuredValue;
+    /** 半径（太阳）。 */
+    radiusSun: MeasuredValue;
+    /** 有效温度 K。 */
+    effectiveTempK: MeasuredValue;
+}
+/**
+ * 各亮度级的代表性恒星。
+ *
+ * ## 为什么必须补这一层
+ *
+ * 原 `star-catalog.ts` 只有主序星（V）。而同样光谱字母的巨星比主序星亮
+ * 20—100 倍 —— 作者写「F5-IIIa」时，用 F5V 顶替会让平衡温度差出几百开
+ * （实测：0.98 AU 处 257 K vs 576 K，从冰封翻到熔融）。
+ *
+ * 下面这些是各亮度级里最有名的样本，可直接拿来当参照。
+ */
+export declare const NAMED_STARS: NamedStar[];
+/**
+ * 行星样本。
+ *
+ * 太阳系 8 颗 + 代表性系外行星。数值全部带 dependence 标记：
+ * 质量与半径是 first-principles（改常数不会让火星变重），
+ * 平衡温度与反照率是 calibrated（只在与观测匹配的大气模型下可信）。
+ */
+export declare const NAMED_PLANETS: BodyEntry[];
+/** 矮行星与小天体样本。 */
+export declare const NAMED_SMALL_BODIES: BodyEntry[];
+/** 全部带名字的天体（恒星 + 行星 + 小天体）。 */
+export declare const ALL_NAMED_BODIES: Array<NamedStar | BodyEntry>;
+/** 按 id 索引。 */
+export declare const BODY_INDEX: Map<string, NamedStar | BodyEntry>;
+/** 按类别分组（给检索用）。 */
+export declare function bodiesByKind(kind: BodyKind): Array<NamedStar | BodyEntry>;
+/**
+ * 判断某个量在改物理常数后是否该重算。
+ *
+ * 为什么单独做成函数：作者（和 AI）最容易犯的错就是
+ * 「改了 α 之后把行星质量也跟着改」——质量由引力与初始条件决定，
+ * 与精细结构常数几乎无关，改了就是篡改设定。
+ *
+ * @param dependence - 该量的依赖类别
+ * @returns 改常数后是否应重算
+ */
+export declare function shouldRescaleOnConstantChange(dependence: ConstantDependence): boolean;

package/lib/types/body-scaling.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 天体量的常数传导：改了基础物理常数之后，天体数据里**哪些必须重算、哪些绝不能动**。
+ *
+ * ## 这是本模块存在的唯一理由
+ *
+ * 「把宇宙所有星体的数据都补上」听起来是填表，但一旦作者改了 α、G 或 c，
+ * 这张表立刻分裂成两类：
+ *
+ * | 类别 | 例 | 改 α 之后 |
+ * |---|---|---|
+ * | **不变** | 行星质量、半径、轨道半长轴 | 完全不动。它们由引力与初始条件决定，与电磁力几乎无关 |
+ * | **必变** | 恒星光度、寿命、有效温度、平衡温度 | 跟着 α 走，公式自己会算 |
+ * | **不可推导** | 大气成分、云量、反照率、磁场、板块 | 没有公式，是历史偶然。只能提示作者「这条要你自己定」 |
+ *
+ * 最容易犯的错有两个，都是**静默**的：
+ *   1. 改了 α 之后把行星质量也跟着改 —— 那是篡改设定（本模块明确拒绝）
+ *   2. 改了 α 之后忘了恒星光度要变 —— 于是气候结论还是旧的
+ *
+ * ## 传导链（α 为例）
+ *
+ * ```
+ * α ↑
+ *  ├→ 库仑势垒 ↑ → 核聚变点火温度 ↑ → 同质量恒星光度 ↓、寿命 ↑
+ *  ├→ 电子散射不透明度 ↑ → 辐射压 ↑ → 恒星光度 ↓
+ *  ├→ 化学键能 ∝ α² → 材料强度、生物体型上限 ↑
+ *  └→ 玻尔半径 ∝ 1/α → 原子尺度 ↓ → 物质密度 ↑
+ *
+ * 行星质量、半径、轨道：**不动**（它们的定义式里没有 α）
+ * 平衡温度：随恒星光度变（因为辐照变了）
+ * 反照率：不动，但它的数值本身只是地球标定
+ * ```
+ *
+ * @module dsh-math-calculator/body-scaling
+ */
+import type { ConstantDependence, MeasuredValue } from './body-catalog.js';
+/** 一条传导结论。 */
+export interface ScalingRule {
+    /** 受影响的天体量（中文名）。 */
+    quantity: string;
+    /** 依赖哪个常数。 */
+    constant: string;
+    /** 随常数变化的幂次（相对变化 = 常数相对变化 ^ exponent）。0 表示无关。 */
+    exponent: number;
+    /** 可信度。 */
+    confidence: 'exact' | 'empirical' | 'order-of-magnitude' | 'direction-only';
+    /** 一句话说明机制。 */
+    mechanism: string;
+    /** 适用域；超出只降级不拒绝。 */
+    domain: string;
+}
+/**
+ * 常数 → 天体量的传导规则表。
+ *
+ * `exponent` 是这个表的核心：它回答「α 变 1%，这个量变百分之几」。
+ * 0 表示无关 —— 此时让它变才是错的。
+ */
+export declare const SCALING_RULES: ScalingRule[];
+/**
+ * 查某个天体量依赖哪个常数、怎么变。
+ *
+ * @param quantity - 量名（中文，如「恒星寿命」）
+ * @returns 匹配的规则（可能多条）；没找到返回空数组
+ */
+export declare function rulesFor(quantity: string): ScalingRule[];
+/**
+ * 一次改常数后的传导结果。
+ */
+export interface ScalingOutcome {
+    /** 改了哪个常数。 */
+    constant: string;
+    /** 变化率（如 1.5 表示变成原来的 1.5 倍，即 +50%）。 */
+    factor: number;
+    /** 有明确幂次的量：按指数重算。 */
+    effects: Array<{
+        quantity: string;
+        /** 该量的变化倍数。 */
+        multiplier: number;
+        /** 一句话结论。 */
+        text: string;
+        confidence: ScalingRule['confidence'];
+    }>;
+    /**
+     * **间接依赖**的量：要重算，但不能用幂次算。
+     *
+     * 例：行星平衡温度 T ∝ L^0.25，而 α 通过恒星结构改变 L。
+     * 这不是幂律关系，所以不能给出倍数 —— 只能提示「改完必须用 world 重跑」。
+     *
+     * ⚠️ 必须与 `unchanged` 严格分开：把这类量误列进「不该动」，
+     * 作者就会拿着旧温度去写新宇宙，那是这个功能最要命的失败模式。
+     */
+    indirect: Array<{
+        quantity: string;
+        reason: string;
+    }>;
+    /** 真正不该动的量（幂次严格为 0 且无间接依赖）。 */
+    unchanged: string[];
+}
+/**
+ * 计算某个常数变化后，各天体量的变化倍数。
+ *
+ * @param constant - 常数名（如 'alpha_fs'、'G'、'c'）
+ * @param factor - 该常数变成原来的几倍
+ * @returns 传导结果
+ */
+export declare function propagateConstantChange(constant: string, factor: number): ScalingOutcome;
+/**
+ * 检查一条天体数据在改常数后是否应重算。
+ *
+ * @param value - 一条带依赖标记的数值
+ * @param constant - 改动的常数名
+ * @returns 是否应重算；以及原因
+ */
+export declare function howToTreatValue(value: MeasuredValue, constant: string): {
+    rescale: boolean;
+    reason: string;
+};
+/**
+ * 依赖类别的人话说明（给输出用）。
+ *
+ * @param dependence - 依赖类别
+ * @returns 说明
+ */
+export declare function describeDependence(dependence: ConstantDependence): string;

package/lib/types/body-taxonomy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 天体类型学：从已观测到纯理论预言，按「科幻创作会遇到什么」来分类。
+ *
+ * ## 为什么不能只收太阳系
+ *
+ * 太阳系只有 8 颗行星、1 颗恒星，而科幻创作要的是「一整个宇宙的可能性空间」：
+ * 流浪行星、热木星、超级地球、中子星、黑洞、白矮星、褐矮星、戴森球……
+ * 这些在太阳系里一个都没有，但作者天天要用。
+ *
+ * ## 三类条目，可信度天差地别
+ *
+ * | 类别 | 例 | 依据 | 本文件怎么处理 |
+ * |---|---|---|---|
+ * | **已观测** | 热木星、超级地球、潮汐锁定行星 | 凌星/径向速度/直接成像 | 给观测值或严格推算 |
+ * | **理论预言** | 中子星、黑洞、白矮星、褐星 | 广义相对论/恒星演化模型 | 给理论值 + 标注「未直接观测」 |
+ * | **纯思辨** | 戴森球、伯纳德星、质量 1e15 kg 的「行星」 | 没有观测也没有严格理论 | 给量纲约束 + 明确标「思辨」 |
+ *
+ * ⚠️ 最容易误导作者的做法：把三类混在一起给数字，不标注来源。
+ * 于是「中子星表面重力 1e11 g」和「戴森球厚 1 公里」看起来一样权威——
+ * 前者是物理必然，后者只是某人拍脑袋。所以每条都必须带 `evidence`。
+ *
+ * ## 「预言的一个一个加」怎么理解
+ *
+ * 这里的「预言」指**理论预言**（theoretical prediction），不是占星术。
+ * 每类都写清：哪些参数由物理锁死（改不了）、哪些由形成历史决定（可以编）。
+ *
+ * @module dsh-math-calculator/body-taxonomy
+ */
+/** 天体类型的证据等级。 */
+export type EvidenceLevel = 'observed' | 'theoretical' | 'speculative';
+/** 一个天体类型。 */
+export interface BodyType {
+    /** 标识。 */
+    id: string;
+    /** 中文名。 */
+    name: string;
+    /** 英文名（便于检索与查文献）。 */
+    nameEn: string;
+    /** 归类：恒星残骸 / 行星 / 小天体 / 人工结构 / 纯思辨。 */
+    family: 'stellar-remnant' | 'star' | 'planet' | 'small-body' | 'exotic' | 'artificial';
+    /** 证据等级。 */
+    evidence: EvidenceLevel;
+    /** 依据（观测证据或理论出处）。 */
+    basis: string;
+    /** 一句话：读者会怎么感知到它。 */
+    perception: string;
+    /** 典型质量（kg）。 */
+    massKg?: number;
+    /** 典型半径（km）。 */
+    radiusKm?: number;
+    /** 典型表面重力（以地球 g 为单位）。 */
+    gravityG?: number;
+    /** 典型表面/有效温度 K。 */
+    tempK?: number;
+    /** 典型密度 kg/m³。 */
+    densityKgM3?: number;
+    /**
+     * 物理锁死的性质：改不了的部分。
+     *
+     * 例：中子星的半径与质量被状态方程锁死（1.4 M☉ 对应约 11—12 km），
+     * 作者可以编它的磁场、转速、伴星，但编不了「半径 1000 km 的中子星」。
+     */
+    lockedBy?: string;
+    /** 作者可以自由发挥的部分（编这些不会与物理冲突）。 */
+    freeToAuthor?: string;
+    /** 写这类天体时最容易踩的坑。 */
+    pitfall?: string;
+    /** 科幻创作中的典型用法。 */
+    narrativeUse?: string;
+    /** 对物理常数的依赖（改 α 之类会不会变）。 */
+    constantDependence?: 'first-principles' | 'scaled' | 'calibrated' | 'contingent';
+}
+/**
+ * 天体类型总表。
+ *
+ * 按「创作时先想到什么」排序：恒星残骸最震撼，人工结构最极端，纯思辨放最后。
+ */
+export declare const BODY_TYPES: BodyType[];
+/** 按族分组。 */
+export declare function typesByFamily(family: BodyType['family']): BodyType[];
+/** 按证据等级分组。 */
+export declare function typesByEvidence(evidence: EvidenceLevel): BodyType[];
+/** 族的显示顺序。 */
+export declare const FAMILY_ORDER: Array<BodyType['family']>;
+/** 族的中文名。 */
+export declare const FAMILY_LABEL: Record<BodyType['family'], string>;
+/** 证据等级的中文名与说明。 */
+export declare const EVIDENCE_LABEL: Record<EvidenceLevel, string>;
+/**
+ * 按名字或名字片段查类型。
+ *
+ * @param query - 中文名/英文名/id 片段
+ * @returns 匹配的类型；没有返回 undefined
+ */
+export declare function findBodyType(query: string): BodyType | undefined;

package/lib/types/detector.d.ts

@@ -35,6 +35,14 @@ export interface DetectionResult {
     signals: string[];
     /** 提取到的候选表达式（供参考，不自动执行）。 */
     candidates: string[];
+    /**
+     * 分流档位：simple（不提醒）/ forced（必须用工具）/ fuzzy（按阈值）。
+     *
+     * 与 `score` 的区别：score 只回答「数学需求强不强」，
+     * 而档位回答「该心算还是该用工具」——
+     * `2+2` 得分很高但该心算，`20 个数字求和` 得分低但最该用工具。
+     */
+    demandClass?: DemandClass;
 }
 /** 检测配置。 */
 export interface DetectorConfig {
@@ -53,6 +61,16 @@ export interface DetectorConfig {
 export declare const DEFAULT_DETECTOR_CONFIG: DetectorConfig;
 /** 重置某个会话的检测状态（测试或用户手动清除时用）。 */
 export declare function resetDetectionState(sessionKey?: string): void;
+/**
+ * 分流结论。
+ *
+ * | 档位 | 含义 | 处置 |
+ * |---|---|---|
+ * | `simple` | 短、少数字、纯四则、无数据信号 | **不提醒**（AI 自己算即可，想用工具仍可用） |
+ * | `forced` | 有数据/汇总/多步信号 | **强提醒**：这类务必用工具 |
+ * | `fuzzy` | 其它数学需求 | 一般提醒 |
+ */
+export type DemandClass = 'simple' | 'forced' | 'fuzzy';
 /**
  * 检测文本里的计算需求。
  *

package/lib/types/empirical-decomposition.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 经验公式的底层原理拆解：区分「物理内核」与「纯标定」，并明确标注哪些只在现实宇宙成立。
+ *
+ * ## 对上一版的自纠（2026-10-26 修订）
+ *
+ * 上一版把 `hull_speed` 归为 `scalable`（可泛化），理由是
+ * 「1.34 = Fr·√g 组合，换重力就能重算」。**这个判断过头了。**
+ *
+ * 真实的物理内核只有 Froude 数本身：
+ *
+ *   v = Fr · √(g·L)      ← 这是**量纲分析**的结论，跨世界成立
+ *   Fr ≈ 0.4             ← 这是**经验值**，来自地球船舶的观测
+ *
+ * 而 Fr ≈ 0.4 是怎么来的？它是「兴波阻力急剧上升」的临界点，
+ * 本质上由**自由液面重力波的色散关系**决定：
+ *
+ *   波速 c = √(g·λ/(2π))        ← 深水重力波，**含 1/(2π)**
+ *   兴波极限 ≈ 船速追上自己的船首波 → 波长 ≈ 船长 L
+ *   代入得 v_limit ≈ √(g·L/(2π)) ≈ 0.4·√(g·L)
+ *
+ * 所以 Fr ≈ 0.4 ≈ 1/√(2π) **不是纯粹的经验拟合，而是色散关系的推论**。
+ * 这一点上一版说错了：它不是「地球船舶的经验常数」，而是物理推出来的。
+ *
+ * ## 但 Fr 的推导仍依赖「水」这个介质
+ *
+ * 1/(2π) 来自重力的**色散关系**（ω² = g·k），本身与介质无关；
+ * 但 `Fr ≈ 0.4` 的**数值**还隐含：
+ *   · 介质是**液体**（有自由表面）
+ *   · 表面张力可忽略（内河船长尺度下成立）
+ *   · 兴波阻力主导（黏性阻力次要）
+ *
+ * 换一个**液体介质**（液氨、液态甲烷、岩浆），色散关系中的表面张力与黏性会变，
+ * 临界 Fr 会移动。所以：
+ *   · **量纲形式** Fr·√(g·L) → 跨世界成立
+ *   · **数值 0.4** → 只在「类水液体 + 宏观尺度」域成立
+ *
+ * ## 结论：三级标注，而不是两级
+ *
+ * | 级别 | 含义 | 例 |
+ * |---|---|---|
+ * | `dimensionless` | 量纲/标度形式跨世界成立，数值也无需改 | 克莱伯指数 0.75 |
+ * | `scalable-with-caveat` | **形式**可泛化，但**系数**需重新标定或验证 | Froude 0.4、潮汐系数 |
+ * | `earth-only` | 形式本身就是地球拟合，换世界无意义 | Mifflin 代谢、风寒、Du Bois |
+ *
+ * 上一版把 `hull_speed` 放在 `dimensionless` 那一侧，等于宣称
+ * 「0.4 换世界也精确成立」——那是**过度自信**。现在它被降级到 middle 档。
+ *
+ * @module dsh-math-calculator/empirical-decomposition
+ */
+/** 拆解类型（三级）。 */
+export type DecompositionKind = 'dimensionless' | 'scalable-with-caveat' | 'earth-only';
+/** 一条经验公式的拆解。 */
+export interface EmpiricalNote {
+    /** 公式 id。 */
+    id: string;
+    /** 中文名。 */
+    name: string;
+    /** 原表达式。 */
+    expr: string;
+    /** 拆解级别。 */
+    kind: DecompositionKind;
+    /**
+     * **底层原理**：这条式子真正的起点是什么。
+     *
+     * 与 `bakedIn` 的区别：bakedIn 说「哪个数字藏了什么」，
+     * principle 说「物理上为什么会有这条式子」。
+     */
+    principle: string;
+    /** 被烘焙的常数（原本藏起来的量）。 */
+    bakedIn?: string;
+    /**
+     * 泛化后**形式仍然成立**的部分（不含数值系数）。
+     *
+     * 写成「量纲正确但系数待定」的形式，让作者知道哪些能留、哪些要自己标。
+     */
+    genericForm?: string;
+    /** 泛化后**必须重新标定**的系数（以及为什么）。 */
+    retuneNeeded?: string;
+    /** 泛化后需要哪些物理量。 */
+    needsFrom?: string[];
+    /** 在什么条件下**形式本身**就失效（不是系数不准，而是式子不该用）。 */
+    breaksWhen?: string;
+    /** 一句话给作者。 */
+    advice: string;
+}
+/**
+ * 经验公式拆解表。
+ *
+ * 排序：从「最可靠」到「最只能在现实中用」。
+ */
+export declare const EMPIRICAL_NOTES: EmpiricalNote[];
+/** 拆解级别的人话说明。 */
+export declare const KIND_LABEL: Record<DecompositionKind, string>;
+/**
+ * 按级别分组。
+ *
+ * @param kind - 拆解级别
+ * @returns 该级别的条目
+ */
+export declare function notesByKind(kind: DecompositionKind): EmpiricalNote[];
+/**
+ * 查一条公式的拆解说明。
+ *
+ * @param id - 公式 id
+ * @returns 说明；没收录返回 undefined
+ */
+export declare function empiricalNoteOf(id: string): EmpiricalNote | undefined;