dsh-math-calculator 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.1.0] — 2026-10-28
+
+公式库扩到 404 条、新增天体目录与类型学、工具定义瘦身 21%，并把「计算精度」与
+「显示精度」彻底分开。全部改动都有测试守（77 套 / 3717 项）。
+
+### 新增
+
+- **天体目录 \`bodies\`**（第 30 个 operation）：26 个具名天体
+  （太阳系 8 大行星 + 木卫二/土卫六/土卫二 + 谷神星/冥王星 + 5 颗系外行星 + 7 颗各亮度级恒星）
+  与 **32 类天体类型学**（白矮星、中子星、黑洞、褐矮星、热木星、流浪行星、戴森球…）。
+  每个数值带**依赖标记**：物理必然 / 随常数变 / 地球标定 / 历史偶然。
+- **常数传导**：\`bodyConstant + bodyFactor\` 回答「改了 α 或 G，天体数据哪些该重算」。
+  分三块：有幂次的（化学键能 ∝ α²）、**间接依赖**（行星平衡温度，要重跑）、
+  **绝不该动**（行星质量/半径/轨道 —— 改了就是篡改设定）。
+- **公式库 395 → 404**（第八批 \`formula-library-generic.ts\`）：
+  把烘焙进系数的常数剥出来，换成可换参数的普适形式。
+- **经验公式拆解**：每条经验式标注三级适用域 ——
+  无量纲通用（克莱伯 0.75）/ 形式可泛化但系数需重验（Fr≈0.4）/ **仅地球成立**
+  （Mifflin 代谢、风寒、Du Bois 表面积等 7 条）。用旧公式时输出会附「藏了什么、何时失效」。
+- **结果缓存**：键含常数与工作区指纹，改常数后必然失效。
+- **批量求值**：\`expressions\` 一次算最多 100 条，逐条独立报错。
+- **计算需求三档分流**：simple（不提醒）/ forced（提醒）/ fuzzy（按阈值），
+  不调用 LLM，成本近零。补上中文数字、工程语境（城墙厚度、射程、划桨）识别。
+- **显示精度可调**：默认 **8 位小数**，\`displayPrecision\` 单次覆盖或工作区固化。
+- **精度不足主动提醒**：按**相对误差**判断（阈值万分之一），
+  \`0.00000123456789\` 在 8 位下误差 0.37% 会提示「请传 displayPrecision:16」。
+
+### 变更
+
+- **\`displayPrecision\` 语义从「有效数字」改为「小数点后几位」**。
+  旧语义下 \`12345.678901234\` 只给 3 位小数（12345.679），与「保留 8 位」的直觉不符；
+  现在给 12345.67890123。\`formatValue\` 与 \`trimNumber\` 同步。
+- **默认显示精度 64 位 → 8 位小数**。整数永远完整（\`10^20+5\` 仍 21 位）。
+- **工具定义瘦身**：7789 → 6140 字符（省 21%，约 1100 token/轮）。
+  \`world\`/\`terrain\`/\`constants\` 等字段表移进 \`help\`，**参数一个没删**。
+  \`description\` 不再重复枚举 operation（\`enum\` 已列全）。
+- **恒星假设显式声明**：未给恒星参数时声明「已默认太阳」；给了模型不支持的光谱型
+  （如 \`F5III\` 巨星）时在输出**最前面**警告「只支持主序星，结论不能直接采信」。
+- **rust 提示词**：不再写死「3—4 位有效数字」，改为「保留几位由你判断」。
+
+### 修复
+
+- **检索修复从未生效**：\`index.ts\` 里有一份 \`findFormulas\` 旧副本，
+  \`formulas\` 操作调的是副本 —— 工具里查「贷款月供」0 条，而单元测试全绿。
+  抽出 \`scoreFormulas\` 作唯一实现。
+- **模糊匹配污染公式求值**：\`'完全不存在的公式xyz'\` 因二字词「公式」命中别的公式，
+  报 \`missing_params\` 而非 \`unknown_formula\`，模型会去补一堆无关参数。
+  拆成「检索用模糊、求值用严格」。
+- **缓存键串键**（两次）：① 手动列举参数漏掉 \`distribution\`/\`params\`，
+  二项 PMF 返回了正态 PDF；② 显式与默认同为 8 时撞键，显式调用继承了
+  「精度不足」提示。现改为全量 args 序列化 + 显式标记入键。
+- **状态变更必须清缓存**：覆盖/移除公式后仍命中旧值（\`kinetic_energy\` 覆盖得 18，
+  移除后仍 18，正确答案 9）。
+- **极小值显示成 0**：\`3.3e-9\` 在 8 位小数下 \`toFixed\` 得 \`"0.00000000"\`，
+  转回数字变 \`0\` —— 非零值显示成零属数据丢失。现凡会被舍入到 0 的一律用科学计数法。
+- **高精度显示丢位**：\`precision:30\` 只给 16 位（BigNumber 先转 Number 丢掉精度）。
+  现高精度路径直接用 BigNumber 格式化，并裁掉尾随零。
+- **\`1/1234567\` 显示成 \`8.1e-7\`**：数值对但看着像只有两位有效数字。
+  改用文本去尾随零，得 \`0.00000081\`。
+- **提示污染数据通道**：把提示拼进 \`result\` 使 \`0.1+0.2\` 从 \`0.3\` 变成两行，
+  一次跑挂 8 个套件。提示改走独立 \`notice\` 字段，只由渲染层展示。
+- **「只提示一次」破坏确定性**：同输入连调两次输出不再字节一致。
+  改为确定性判断（未固化 + 有小数 → 每次都带）。
+- **列表编号误伤小数**：\`1.5倍\` 里的 \`1.\` 被当列表编号，压低物理推演场景得分。
+- **序数误判为数量**：\`第三纪\`/\`第 3 次\` 让编年史文本误报计算需求。
+
+### 已知局限
+
+- 分流靠**词表匹配**，不是语义理解。\`洋流方向对港口结冰的影响\` 这类
+  既无数量也无疑问词的陈述型问题仍不提醒（可能是漏报，也可能是合理）。
+  继续加词表会推高误报风险，当前取舍是「0 误报优先」。
+- 缓存是进程内 Map（上限 256 条，LRU），不跨会话持久化。
+
 ## [2.0.0] — 2026-10-26
 
 首个公开发布版本。

package/README.md

@@ -14,7 +14,7 @@ DSH（DeepSeek Harness）原生的**高精度数学计算器**插件，附带可
 | 高精度计算 | 心算 / bash 拼 | BigNumber 64 位，整数输出完整定点 |
 | 符号运算 | 查表或近似 | 求导/积分/化简/展开，符号精确 |
 | 单位换算 | 自己查系数 | 73 个单位，温度按仿射换算 |
-| 写公式 | 每次都重推 | 395 条公式库，参数全可覆盖 |
+| 写公式 | 每次都重推 | 404 条公式库，参数全可覆盖 |
 | 改物理常数 | 无法验证 | 自动推导派生量 + 全公式偏差 |
 | 多项目数据 | 互相污染 | 工作区隔离，各持一套常数表与公式表 |
 | *（可选）* 架空世界设定 | 凭感觉 | 输入星球参数 → 出重力/气候/地形上限 |
@@ -47,12 +47,12 @@ npm run build
 
 ```powershell
 npm pack
-& "...\dsh.cmd" plugin --profile desktop add ./dsh-math-calculator-2.0.0.tgz
+& "...\dsh.cmd" plugin --profile desktop add ./dsh-math-calculator-2.1.0.tgz
 ```
 
 ---
 
-## 29 个 operation
+## 30 个 operation
 
 ### 基础运算
 
@@ -81,7 +81,7 @@ npm pack
 
 | operation | 说明 | 示例 |
 |---|---|---|
-| `formula` | 调用 395 条公式之一 | `{"formula":"escape_velocity","overrides":{"M":5.97e24,"r":6371000},"operation":"formula"}` |
+| `formula` | 调用 404 条公式之一 | `{"formula":"escape_velocity","overrides":{"M":5.97e24,"r":6371000},"operation":"formula"}` |
 | `formulas` | 检索公式库 | `{"query":"重力","operation":"formulas"}` |
 | `world` | 星球参数 → 体感画像 | `{"world":{"planetRadius":1.4,"rotationHours":40},"operation":"world"}` |
 | `terrain` | 局地气候（配合 world） | `{"world":{"planetMass":2},"terrain":{"kind":"coastal","latitudeDeg":58},"operation":"world"}` |
@@ -89,6 +89,10 @@ npm pack
 | `quantities` | 哪些物理量该跟着变 | `{"constants":{"G":1.3e-10},"constantName":"G","operation":"quantities"}` |
 | `impact` | 改常数 → 全公式偏差 | `{"constants":{"c":1.5e8},"operation":"impact"}` |
 | `feasibility` | 设定一致性校验 | `{"world":{"planetMass":2},"claims":{"creatureHeight":50},"operation":"feasibility"}` |
+| `bodies` | 天体目录与类型学（26 具名天体 + 32 类型） | `{"bodyName":"mars"}` / `{"bodyType":"中子星"}` / `{"bodyConstant":"alpha_fs","bodyFactor":2}` |
+| `balance` | 收支盘点（多项一起看，给最短板） | `{"balance":{"grain":{"demand":2.7e6,"supply":3.1e6}}}` |
+| `units` | 单位换算（73 个单位，含中文古制） | `{"unitValue":30,"unitFrom":"里","unitTo":"km"}` |
+| `custom` | 自创常数/新物理量 | `{"operation":"custom","action2":"add"}` |
 
 ### 恒星结构（S3）
 
@@ -126,13 +130,51 @@ npm pack
 后端接口一条没删，恢复界面只需重建前端（见 `docs/ui-removed.md` 第七节）。
 所有修改都落到**当前工作区**，不同世界观互不影响。
 
+### 成本控制：schema 瘦身 / 缓存 / 批量
+
+工具定义是**每轮请求都重复计费**的固定成本，所以做了三件事：
+
+| 措施 | 效果 |
+|---|---|
+| schema 瘦身（详细字段挪进 `help`） | 7789 → 6140 字符，约省 21%（≈1100 token/轮） |
+| 结果缓存（键含常数与工作区指纹） | 同一式子重复调用不再重算；改常数后**必然失效** |
+| 批量求值 `expressions` | 一次算最多 100 条，逐条独立报错 |
+
+三条都是纯收益、不改语义：参数一个没删、缓存键漏一项就会算错（有测试守）。
+
+### 显示精度：默认 8 位小数，可调、可固化
+
+计算精度与显示精度**分开**：
+
+| 参数 | 语义 | 默认 |
+|---|---|---|
+| `precision` | **计算**精度（BigNumber 有效位） | 64，不要为好看调低（`(10^20+1)-(10^20)` 在 20 位时算出 0） |
+| `displayPrecision` | **显示**精度：**小数点后几位** | 8 |
+
+- 整数永远完整：`10^20+5` 仍是 21 位，不受显示精度影响
+- 截断会丢精度时主动提醒：`0.00000123456789` 在 8 位下相对误差 0.37%，会附上「请传 displayPrecision:16」
+- 固化一次即全局生效：`{"operation":"workspace","action2":"set","displayPrecision":8}`
+
+### 计算需求分流：心算 / 强制用工具
+
+预警器在外部分三档（不调用 LLM，成本近零）：
+
+| 档 | 判据 | 处置 |
+|---|---|---|
+| `simple` | 短、数字少、纯四则 | 不提醒（想用工具仍可用） |
+| `forced` | 数据/汇总/金融/物理推演信号 | 提醒（这类心算易错且错得看不出来） |
+| `fuzzy` | 其它数学需求 | 按阈值提醒 |
+
+物理推演类**一律不算 simple**——`1.5 倍重力下山能长多高` 心算给「大概 3000 米」，
+工具给 3262 米并提示「已接近花岗岩极限」。差别不在精度，在于知不知道这个数意味着什么。
+
 ### 面向 AI 的设计
 
 插件对 AI 有三层提示（详见 [ADR-0002](../docs/adr/0002-plugin-ai-facing.md)）：
 
 | 层 | 位置 | 预算 |
 |---|---|---|
-| 工具描述 | `TOOL_DESCRIPTION` | ≤ 800 字符，枚举 29 个 operation 与读输出规则 |
+| 工具描述 | `TOOL_DESCRIPTION` | ≤ 800 字符，枚举 30 个 operation 与读输出规则 |
 | 系统提示 | `systemPrompt.section`（brief） | ≤ 320 字符，每轮注入 |
 | 主动提醒 | `agent/pre-step` 钩子 | 每会话 ≤ 3 次，检测到计算需求才触发 |
 
@@ -141,7 +183,7 @@ npm pack
 
 ### 公式库扩展（全局包 + 工作区临时）
 
-395 条内置公式不够时，不必改代码：
+404 条内置公式不够时，不必改代码：
 
 | 级别 | 存放 | 范围 | 用法 |
 |---|---|---|---|
@@ -181,7 +223,7 @@ npm pack
 {"operation":"formulas","query":"freq:low"}    // 低频：量子/核物理/相对论/金融
 ```
 
-当前分布：高频 113 / 中频 199 / 低频 30（共 395 条）。
+当前分布：高频 144 / 中频 228 / 低频 32（共 404 条）。
 
 ### 基础运算扩展
 
@@ -296,7 +338,7 @@ npm pack
 {"operation":"quantities","constants":{"G":1.3e-10},"constantName":"G"}
 //    → 普朗克长度 ∝√G、玻尔半径与 G 无关、表面重力 ∝G
 
-// 4. 看全部 395 条公式相对现实的偏差
+// 4. 看全部 404 条公式相对现实的偏差
 {"operation":"impact","constants":{"c":1.5e8}}
 //    → 11 条受影响：质能 -75%、黑体辐射 +300%、维恩位移 -50%
 
@@ -370,7 +412,7 @@ npm pack
 
 插件做了三层感知机制，避免模型「自己心算一遍」：
 
-1. **工具描述**枚举全部 29 个 operation，并写明「凡是需要数值计算都必须调用」
+1. **工具描述**枚举全部 30 个 operation，并写明「凡是需要数值计算都必须调用」
 2. **系统提示注入**（`ctx.systemPrompt.section`）每轮对话提醒，默认 `brief` 档，可用 `{"promptMode":"full"}` 切换
 3. **`agent/pre-step` 钩子**实时检测用户消息里的计算需求，命中则插入提醒（每会话最多 3 次，用过插件后静默）
 
@@ -433,7 +475,7 @@ node run-all-tests.mjs # 58 套 / 2321 项
 src/
 ├── index.ts            插件入口 + 工具定义 + operation 分发（2032 行）
 ├── ops/                8 个较大的 operation 实现
-├── formula-library*.ts 395 条公式（7 个批次，含势力运行与通用计算批次）
+├── formula-library*.ts 404 条公式（8 个批次，含势力运行与通用计算批次）
 ├── constants-graph.ts  43 个常数的依赖图（23 基础旋钮 / 20 派生）
 ├── quantities.ts       量纲分析与缩放指数
 ├── feasibility.ts      11 条设定约束

package/dsh.plugin.json

@@ -1,8 +1,15 @@
-{
-  "id": "dsh-math-calculator",
-  "version": "2.0.0",
-  "main": "lib/index.js",
-  "description": "DSH 原生数学与架空世界推演插件：高精度计算、342 条公式、常数与星球推演。",
-  "engines": { "dsh": ">=0.1.1-rc.2 <0.4.0" },
-  "contributes": { "tools": ["math_execute"], "skills": [] }
-}
+{
+  "id": "dsh-math-calculator",
+  "version": "2.1.0",
+  "main": "lib/index.js",
+  "description": "DSH 原生数学与架空世界推演插件：高精度计算、342 条公式、常数与星球推演。",
+  "engines": {
+    "dsh": ">=0.1.1-rc.2 <0.4.0"
+  },
+  "contributes": {
+    "tools": [
+      "math_execute"
+    ],
+    "skills": []
+  }
+}

package/lib/awareness.js

@@ -42,31 +42,34 @@ export function getPromptMode() {
 /**
  * 第一层：工具描述。
  *
- * 这是模型**每次**看工具清单时都会读到的内容，所以必须：
- *   - 完整列出 operation（漏一个，模型就不知道它存在）
- *   - 写「何时使用」而不是只写「是什么」
- *   - 给出触发关键词，让模型在遇到这类问题时想起它
+ * 这是模型**每次**看工具清单时都会读到的内容 —— 属于每轮固定成本，
+ * 所以要跟 parameters schema 一样抠字数。
+ *
+ * 压缩原则：
+ *   · **不重复 enum**：operation 的取值已在 schema 的 enum 里列全（300 字符），
+ *     这里再列一遍是纯重复。只保留「怎么选」的判断线索。
+ *   · **能移到 help 的就移**：详细字段表、单位清单等只在用到时才需要，
+ *     放 help 里不占每轮成本。
+ *   · **保留行为约束**：如「必须调本工具」「精度分两层」这类会改变模型行为的，
+ *     不能砍 —— 它们省下的重算远多于自身开销。
  */
 export const TOOL_DESCRIPTION = [
     '本地数学与物理推演引擎（BigNumber 64 位 + 符号代数 + 架空世界推演）。',
     '',
     '⚠️ 数值计算必须调用本工具：不要心算、不要用 bash 拼凑算术。',
-    '触发：算术/三角、解方程、求导积分、矩阵、统计、单位换算、公式求值、',
-    '改常数看后果、推演星球/恒星/卫星/生命、势力收支与承压。',
+    '触发场景：算术/三角、解方程、微积分、线代、统计、单位换算、公式求值、',
+    '改常数看后果、推演星球/恒星/卫星/生命、势力收支。',
     '',
-    'operation（共 29 个；不填=auto，含等号判为方程；完整说明用 help）：',
-    '  求值 evaluate | 方程 solve system | 微积分 derivative integral | 代数 simplify expand roots',
-    '  线代 matrix eigen | 统计 stats dist regression | 微分方程 ode',
-    '  公式 formula formulas | 世界 world | 常数 constants quantities impact',
-    '  单位 units | 收支 balance | 推演 derivation（pipeline/dead/backSolve/flip 等）',
-    '  自创量 custom | 设定校验 feasibility | 数据 workspace formula-table | 自查 help',
+    'operation 见参数 enum（30 个）；不确定用 help。选法：一条式子用 evaluate，',
+    '数据用 stats/dist，改设定后用 world/derivation。',
     '',
     '读输出约定：',
     '  · [精确]/[标度]/[量级]/[仅方向] 是可信度标签，引用时保留；',
     '  · 【跨模块一致性】✓/⚠/✗，看到 ✗ 先修正设定；',
     '  · 【模型可信度】标出哪些数只是地球标定，常数偏离现实时会失真。',
     '',
-    '精度默认 64 位（precision 可调 1-256）。失败返回 ok=false + error.hint，按提示修正。',
+    '精度分两层：precision（计算，默认 64，调低会算错大数）不要为好看而动；',
+    'displayPrecision（显示，**小数点后几位**，默认 8）只截小数、整数永远完整。',
 ].join('\n');
 /**
  * 第二层：系统提示注入。