dsh-math-calculator 2.0.0 → 2.1.0

package/src/playbook.ts

@@ -281,9 +281,11 @@ export function buildPlaybook(state: {
     out.push('- ' + item.step + '：' + item.do + '（' + item.skip + '）')
   }
   out.push('')
-  out.push('### 两条底线')
+  out.push('### 三条底线')
   out.push('1. **不要反驳用户的设定。** 插件指出「按这个参数会怎样」，你转述，并给出「想保留的话可以怎么调」。')
   out.push('2. **不要编数字。** 算不出来的（混沌、超出现有物理、插件没覆盖的），标待定或问用户。')
+  out.push('3. **不要照抄全精度。** 工具输出保留几十位小数，是为了**让你有得选**，不是让你全部抄出去。转述时保留几位，由你判断——依据是这个数在文中要干什么：读者只需要量级感就给少的，要拿去核对数字就给多的，要参与后续计算就给够。插件不给固定档位，因为「几位合适」是语境问题，不是物理问题。')
+  out.push('   唯一硬边界：**该精确的整数不能截断**（`10^20+5` 就是 `100000000000000000005`，写成 `1e20` 是丢信息，不是简洁）。')
   return out.join(String.fromCharCode(10))
 }
 
@@ -303,6 +305,8 @@ export function buildBriefPlaybook(state: {
   out.push('- 该写的（结语、描写、叙事判断）由你生成，别照抄工具输出')
   out.push('- 硬约束（物质不存在等）如实说；叙事选择（要巨兽、要灵能）不反驳，只讲代价')
   out.push('- 算不出来的别编，标待定或问用户')
+  out.push('- 工具输出默认是**全精度**（可能几十位小数），是供你取舍的原料。**保留几位你来定**：读者只要感觉就少给，要核对就多给，要接着算就管够。别把 60 位抄给读者，也别把该精确的整数（如 10^20+5）截成科学计数法')
+  out.push('- 工具输出默认按**小数点后 8 位**显示（整数永远完整，如 10^20+5 不会被截）。需要更多位就单次传 `displayPrecision`；想全局换一档用 `{operation:"workspace", action2:"set", displayPrecision:N}` 固化一次。注意 `precision`（计算精度）不要调低，它一低大数就会算错')
   if ((state.changedConstants ?? []).length > 0) {
     out.push('- 本区改过常数，先跑 dimensionless 确认不是单位重定义')
   }
@@ -420,5 +424,6 @@ export function buildConfiguredPlaybook(state: {
   out.push('### 底线')
   out.push('1. 不要反驳用户的设定——说清「按这个参数会怎样」，并给出「想保留可以怎么调」。')
   out.push('2. 不要编数字——算不出来的标待定或问用户。')
+  out.push('3. 不要照抄全精度——工具输出保留几十位小数是为让你有得选，不是让你全抄。保留几位由你判断：读者只要量级就少给，要核对就多给，要参与后续计算就管够。唯一硬边界是该精确的整数不能截断（`10^20+5` 写成 `1e20` 是丢信息）。')
   return out.join(String.fromCharCode(10))
 }

package/src/precision-report.ts

@@ -0,0 +1,87 @@
+/**
+ * 显示精度的损失追踪：判断「当前位数够不够用」。
+ *
+ * ## 为什么需要这个模块
+ *
+ * 显示精度截断是**悄悄发生**的，作者与模型都不会察觉：
+ *
+ *   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 const PRECISION_LOSS_THRESHOLD = 1e-4
+
+/** 本轮调用中已记录的最大相对误差。 */
+let maxRelativeLoss = 0
+
+/**
+ * 记录一次截断造成的相对误差。
+ *
+ * @param relativeLoss - |显示值−真值| / |真值|
+ */
+export function reportPrecisionLoss(relativeLoss: number): void {
+  if (Number.isFinite(relativeLoss) && relativeLoss > maxRelativeLoss) {
+    maxRelativeLoss = relativeLoss
+  }
+}
+
+/**
+ * 取出并清空本轮的最大相对误差。
+ *
+ * 清空是必要的：每次工具调用开始都要重新统计，
+ * 否则上一轮的损失会一直挂在本轮结果上。
+ *
+ * @returns 最大相对误差；0 表示没有可感知的损失
+ */
+export function consumePrecisionLoss(): number {
+  const value = maxRelativeLoss
+  maxRelativeLoss = 0
+  return value
+}
+
+/**
+ * 本轮显示精度是否由调用方**显式**指定。
+ *
+ * 为什么要区分：作者自己写 `displayPrecision:2` 时，截断是他的意图，
+ * 再提醒「精度不够」就是啰嗦。只有用默认值时才值得提醒。
+ */
+let displayPrecisionExplicit = false
+
+/**
+ * 标记本轮显示精度是否来自显式参数。
+ *
+ * @param explicit - 是否显式
+ */
+export function setDisplayPrecisionExplicit(explicit: boolean): void {
+  displayPrecisionExplicit = explicit
+}
+
+/**
+ * 当前显示精度是否来自显式参数。
+ *
+ * @returns 是否显式
+ */
+export function isDisplayPrecisionExplicit(): boolean {
+  return displayPrecisionExplicit
+}

package/src/result-cache.ts

@@ -0,0 +1,157 @@
+/**
+ * 计算结果缓存：同样的输入不再算第二遍。
+ *
+ * ## 为什么值得做（而不只是优化）
+ *
+ * 反复算同一个式子在真实使用里很常见：
+ *   · 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
+ */
+
+/** 一条缓存记录。 */
+interface CacheEntry {
+  /** 缓存的返回值（不深拷贝，调用方不得修改）。 */
+  value: unknown
+  /** 命中次数（供统计）。 */
+  hits: number
+}
+
+/** 缓存容量上限。 */
+const MAX_ENTRIES = 256
+
+/** 主存储。Map 保留插入顺序，正好用来做 LRU。 */
+const store = new Map<string, CacheEntry>()
+
+/** 命中/未命中统计（供诊断）。 */
+let hits = 0
+let misses = 0
+
+/**
+ * 把一个值规范成稳定的字符串，用于参与缓存键。
+ *
+ * 为什么不用 JSON.stringify：对象键的顺序不保证一致
+ * （`{a:1,b:2}` 与 `{b:2,a:1}` 应视为同一个键），
+ * 且浮点表示可能因来源不同而不一致。这里按键名排序后拼接。
+ *
+ * @param value - 任意值
+ * @returns 稳定字符串
+ */
+function stableStringify(value: unknown): string {
+  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 as number) ? (value as number).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 as Record<string, unknown>
+    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: readonly unknown[]): string {
+  return parts.map(stableStringify).join('\u0001')
+}
+
+/**
+ * 取缓存。
+ *
+ * @param key - 缓存键
+ * @returns 命中则返回缓存值；未命中返回 undefined
+ */
+export function getCached(key: string): unknown {
+  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: string, value: unknown): void {
+  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(): void {
+  store.clear()
+}
+
+/**
+ * 缓存统计（供诊断与测试）。
+ *
+ * @returns 条目数、命中、未命中
+ */
+export function cacheStats(): { size: number; hits: number; misses: number } {
+  return { size: store.size, hits: hits, misses: misses }
+}
+
+/**
+ * 重置统计（不影响已存条目）。
+ */
+export function resetCacheStats(): void {
+  hits = 0
+  misses = 0
+}

package/src/workspace.ts

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

@@ -260,6 +260,14 @@ export interface WorldProfile {
   warnings: string[]
   /** 读者能直接感知的要点（供主模型二创）。 */
   highlights: string[]
+  /**
+   * 恒星假设说明：哪些地方**替代了用户设定**或**补了默认值**。
+   *
+   * 与 `warnings` 的区别：`warnings` 说「你给的世界有物理问题」，
+   * 这里说「我动了你的输入」。后者更要紧——整份结论都建立在它之上，
+   * 所以必须显式返回、由上层放到输出最前面。
+   */
+  starNotes: string[]
 }
 
 const EARTH = {
@@ -404,6 +412,14 @@ export function generateWorld(params: WorldParams, options: WorldOptions = {}):
   //   a) starClass='M5V' → 按光谱型基准表填充（省去查表）
   //   b) 直接给 starMass/starRadius/starTemp
   // 显式参数优先于 starClass —— 用户想微调时不会被基准值覆盖。
+  //
+  // ⚠️ 目录里**只有主序星（V）**：O5V…M5V 共 9 种，没有巨星（III）、次巨星、白矮星。
+  // 同样光谱字母的巨星比主序星亮 20—100 倍，用主序值顶替会让平衡温度差出几百开。
+  //
+  // 实测踩到过：传 starClass='F5III'（某设定里的 F5-IIIa 巨星）时，旧实现静默回退到
+  // 最近的主序型 G2V（太阳），而那句提示被推到最后一百多行之后——读前 20 行的人永远看不到。
+  // 现在这类替换会记进 starNotes，并被放到输出的**最前面**。
+  const starNotes: string[] = []
   let baseStar: StarClass
   if (typeof params.starClass === 'string' && params.starClass.trim() !== '') {
     const requested = STAR_INDEX.get(params.starClass.trim())
@@ -412,17 +428,40 @@ export function generateWorld(params: WorldParams, options: WorldOptions = {}):
       // 允许简写（如 '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)
@@ -937,5 +976,13 @@ export function generateWorld(params: WorldParams, options: WorldOptions = {}):
     },
     warnings,
     highlights,
+    /**
+     * 恒星假设说明（替代了用户设定、或用了默认值）。
+     *
+     * 与 `warnings` 分开：`warnings` 是「你给的世界有个物理问题」，
+     * `starNotes` 是「我改了/补了你的输入」。两者性质不同，呈现位置也不同——
+     * `starNotes` 必须出现在输出最前面，因为整份结论都建立在它之上。
+     */
+    starNotes,
   }
 }