dsh-math-calculator 2.3.2 → 2.3.3

package/src/help.ts

@@ -269,30 +269,67 @@ const STATS_BODY = (): string => `【统计与概率】
     A/B 结果差异是不是巧合 → t 分布`
 
 /** 【微分方程】ODE 数值解。 */
-const ODE_BODY = (): string => `【微分方程】ode 数值求解（RK4）
+const ODE_BODY = (): string => `【动力学】连续用 ode，离散用 recurrence
 
+  ★★ 先判断：你的模型是「连续变化」还是「按期结算」？
+     连续（每个人随时都在增长）→ ode
+     离散（年度结算、批次解锁、世代更替）→ recurrence
+     两者答案不同，写年表必须用离散值（见下面第 3 段）。
+
+══ 1. ode：连续时间积分（RK4）══
   一阶方程组（SIR / 捕食模型）与二阶方程（自动降阶）都能解。
 
   参数：
-    expression  状态方程，多个用分号分隔。等号左边是导数变量
-                例："S'=-k1*S*I; I'=k1*S*I-k2*I; R'=k2*I"   ← SIR 传染病
-                    "x'=y; y'=-k*x"                        ← 简谐振子
-    initial     初值对象 {S:999, I:1, R:0}
+    expression  状态方程，分号分隔。等号左边是导数变量
+                例："S'=-k1*S*I; I'=k1*S*I-k2*I; R'=k2*I"   ← SIR
+                    "x'=y; y'=-k*x"                        ← 简谐
+    initial     初值 {S:999, I:1, R:0}
     from/to     积分区间（默认 0 → 10）
-    steps       RK4 步数（默认 1000，刚性方程要加大）
-    samples     返回的采样点数（默认 24，只要不爆内存可以调大）
+    steps       RK4 步数（默认 1000，刚性方程加大）
+    samples     返回采样点数（默认 24）
+    at           ★ 要精确输出的时点，如 [5,10,20]
+
+  返回：轨迹、终点值、极值、指定时点的值、**发散警告**
+
+  ★ at 是什么用的：默认采样是均匀的（t = 1, 2.9, 4.8, …），
+    写年表时「第 5 年、第 10 年」一个都对不上。传 at:[5,10,20] 就精确给那几个。
+
+  ★ 二阶方程降阶：y'' 写成 y'=y_d; y_d'=…（y_d = dy/dt）。
+    缺辅助变量会提示补哪个，不会静默给错。
+
+  ★ 数值解不是解析解：steps 太少会失真，刚性方程易发散 ——
+    看到发散警告就加大 steps，或换解析思路。
+
+══ 2. recurrence：离散递推（出逐年表）══
+  {operation:"recurrence", recurrence:"P*2", initial:{P:1}, periods:20}
+  → 逐期表 + 终值 + 与连续模型的差额
+
+  参数：
+    recurrence  下一期 = f(本期)。单状态最常见：
+                "P*2"                 ← 每期翻倍
+                "P*min(1.2, 1000/P)"   ← 带资源上限的年度增长
+    initial     初值，可多个状态（逗号/分号分隔的表达式各自求一次）
+    periods     迭代期数（默认 12，上限 5000）
 
-  返回：轨迹（时间序列）、终点值、极值、**发散警告**
+  ★ 支持 min()/max() 约束 —— 「增速 20% 但不超过 1000」这种写法直接可用，
+    结果会在第 38 期左右平滑收敛到 1000，不会越过。
 
-  ★ 二阶方程降阶：y'' 要写成 y'=y_d; y_d'=…，y_d 表示 dy/dt。
-    缺了辅助变量会提示补哪个，不会静默给错。
+══ 3. 为什么非要区分（实测数字）══
+  同一件事「从 1 起每年 ×2」：
+     离散（recurrence）   2^19        = 524,288
+     连续（ode, 0.693P）  e^(0.693×19) = 522,824
+     差 0.28%
 
-  ★ 数值解不是解析解：steps 太少会失真，且刚性方程（变化极快）
-    容易发散——看到发散警告就加大 steps，或换解析思路。
+  0.28% 看着可忽略，但第 33 年换成本「亿人」时差 0.5 亿 ——
+  **而写作时写的是「第 33 年，四十二亿人」这种具体整数。**
+  连续模型的 4.24e9 会让你在「42 亿还是 43 亿」上反复纠结。
 
-  ★ 写故事时的常见用法：
-    传染病扩散（SIR）、捕食者-猎物振荡（Lotka-Volterra）、
-    碳循环、人口动态、冷却曲线`
+  ★ 所以 recurrence 会在结果末尾直接给出「连续近似 vs 离散」的差额，
+    让你一眼看出「用 ode 顶替会差多少」。
+
+★ 写故事时的常见用法：
+  传染病扩散（SIR）、捕食者-猎物振荡（Lotka-Volterra）、
+  碳循环、人口动态、冷却曲线、**逐年人口/资源年表**`
 
 /** 【公式库】442 条公式的调用与检索。 */
 const FORMULA_BODY = (): string => `【公式库】共 ${FORMULAS.length} 条自然科学公式
@@ -832,7 +869,7 @@ export const HELP_TOPICS: HelpTopic[] = [
     tier: 'core',
     /** 实践文档信号量 250，断层第一：算术/带单位/批量/label 全落在这一节。 */
     weight: 250,
-    title: '求值（evaluate）',
+    title: '求值 evaluate',
     summary: '算一条式子。物理量带单位写，量纲错当场拦下；批量一次多条。',
     aliases: ['算式', '计算', '求值', 'mathjs', 'expression'],
     body: EVALUATE_BODY,
@@ -846,7 +883,7 @@ export const HELP_TOPICS: HelpTopic[] = [
      * 前者要写方程、要看解的形式（唯一解/无穷多解/无解）。
      */
     weight: 59,
-    title: '解方程与微积分（solve / derivative / integral）',
+    title: '解方程与微积分（solve）',
     summary: '解方程与方程组、符号求导积分。退化方程组会说「无穷多解」而非静默给单解。',
     aliases: ['方程', '求解', 'solve', '积分', '求导', '微积分', 'algebra'],
     body: ALGEBRA_BODY,
@@ -856,7 +893,7 @@ export const HELP_TOPICS: HelpTopic[] = [
     tier: 'core',
     /** 信号量 173：中制单位（里/丈/斤/亩）与 to 换算在各文档频繁出现。 */
     weight: 173,
-    title: '单位换算与输出单位（units）',
+    title: '单位换算 units',
     summary: '中外古今单位换算、自定义单位，以及输出为什么是大数配吨/公里。',
     aliases: ['单位', '换算', '里', '丈', '斤', '亩', 'unit', 'conversion'],
     body: UNITS_BODY,
@@ -877,7 +914,7 @@ export const HELP_TOPICS: HelpTopic[] = [
     /** 信号量 26。 */
     weight: 26,
     title: '世界观推演（world / 地形 / 气候）',
-    summary: '星球参数得体感画像：重力昼夜气候、天空、恒星寿命、卫星、生命闸门。★ 完整字段表在这里。',
+    summary: '星球参数 → 体感画像：重力昼夜气候、天空、恒星寿命、卫星、生命闸门。★ 字段表在这。',
     aliases: ['星球', '世界', '重力', '气候', '恒星', '地形', 'world', 'planet'],
     body: WORLD_BODY,
   },
@@ -894,7 +931,7 @@ export const HELP_TOPICS: HelpTopic[] = [
     /** 新增节，文档中尚无信号；按用户明确要求保留 core。 */
     weight: 0,
     title: '工程 / 生物 / 材料 / 财政 / 宏观（57 条领域公式）',
-    summary: '梁柱应力、热机煤耗、管流泵功率；扩散供氧、异速生长、遗传平衡；胡克与断裂韧性、熔点与结合能；财政赤字与债务螺旋、GDP 恒等式与增长核算。每条都写了 scaling 律或恒等式来源。',
+    summary: '梁柱应力、热机煤耗、泵功率；扩散供氧、异速生长；胡克与断裂韧性、熔点与结合能；财政赤字与债务螺旋。★ 每条都写了 scaling 律。',
     aliases: ['工程', '生物', '材料', '经济', '宏观', '财政', '税收', '债务', '建筑', '结构', '热机', '流体', '生态', '畜牧', '通胀', '作物'],
     body: DOMAINS_BODY,
   },
@@ -922,13 +959,30 @@ export const HELP_TOPICS: HelpTopic[] = [
   },
   {
     key: 'ode',
-    tier: 'extra',
-    /** 信号量 4 —— 最低的一档。 */
-    weight: 4,
-    short: '微分方程',
-    title: '微分方程（ode）',
-    summary: 'RK4 数值解一阶方程组与二阶方程，返回轨迹/终点值/极值/发散警告。',
-    aliases: ['微分方程', 'ode', '传染病', '捕食模型', 'rk4'],
+    /**
+     * ★ 从 extra 提到 core（2026-11-08）。
+     *
+     * 实测反馈里最重的一条：该会话「写了 300 行 Python 做逐年迭代、参数扫描、
+     * 双状态耦合」，而 ode 就在那里 —— 只是排在「低频」栏的最后一行。
+     *
+     * 所以「低频」这个分档本身是错的：它表达的是「用得少」，
+     * 但用得少不等于「该在想建模时绕过它」。
+     */
+    tier: 'core',
+    /**
+     * 权重从 4 提到 60。
+     *
+     * 原来的 4 是「实践文档里出现 4 次」的信号量 —— 但这只反映**已经发生的使用**，
+     * 不反映**该用而没用的机会数**。实测那份会话里手写了 6 个脚本做逐年迭代，
+     * 那些都该是一次 ode/recurrence 调用。所以按「错过的机会」重估。
+     */
+    weight: 60,
+    short: '微分方程与递推',
+    title: '动力学：微分方程与离散递推（ode / recurrence）',
+    summary:
+      '连续用 ode（RK4，支持 min() 约束/多状态）；离散用 recurrence 出逐年表。' +
+      '★ 写年表用离散值；ode 传 at:[5,10,20] 精确取那几个年份。',
+    aliases: ['微分方程', 'ode', '递推', 'recurrence', '逐年', '年表', '增长模型', '传染病', '捕食模型', 'rk4'],
     body: ODE_BODY,
   },
   {
@@ -955,12 +1009,13 @@ export const HELP_TOPICS: HelpTopic[] = [
   },
   {
     key: 'derivation',
-    tier: 'extra',
+    /** 同上，从 extra 提到 core：参数扫描与结论翻转是建模的一部分。 */
+    tier: 'core',
     /** 信号量 21。 */
     weight: 21,
     short: '推演栈 29 子命令',
     title: '推演栈（derivation 子命令）',
-    summary: '八层推演栈、混沌拦截、结论翻转、逆推校准、敏感度、相图、白皮书、算力、幻想层、文明极限。',
+    summary: '敏感度/结论翻转/逆推校准/相图/算力预算等 29 子命令。★ 全部子命令在这。',
     aliases: ['推演', 'derivation', '混沌', '白皮书', '相图', '敏感度', '算力'],
     body: DERIVATION_BODY,
   },
@@ -977,12 +1032,13 @@ export const HELP_TOPICS: HelpTopic[] = [
   },
   {
     key: 'recipe',
-    tier: 'extra',
+    /** 同上：配方是「怎么把上面几个串起来」，属于建模段。 */
+    tier: 'core',
     /** 信号量 17。 */
     weight: 17,
     short: '锚点/账本/错误码',
     title: '常见配方（锚点/账本闭合/多步链/错误码）',
-    summary: '跨节组合用法：sanity 锚点比对你自己给的判据、账本闭合、多步链、错误码对照。',
+    summary: '锚点比对、账本闭合、多步链、三条推演配方（文明/巨兽/材料）、错误码。',
     aliases: ['锚点', 'sanity', '账本', '闭合', '多步', '错误', '配方'],
     body: RECIPE_BODY,
   },
@@ -1057,12 +1113,45 @@ function renderIndex(): string {
   const byWeight = (a: HelpTopic, b: HelpTopic) => (b.weight ?? 0) - (a.weight ?? 0)
   const core = HELP_TOPICS.filter((item) => item.tier === 'core').sort(byWeight)
   const extra = HELP_TOPICS.filter((item) => item.tier === 'extra').sort(byWeight)
+  /**
+   * ## 目录分三段：算术 / 建模与推演 / 其余
+   *
+   * 实测反馈（能力评估文档第 4 节）是本轮最重的一条：
+   *
+   * > 「一个能做动力学 + 参数扫描 + 499 条领域公式的工具，被排在了『低频』栏里。」
+   * > 「我写了 300 行 Python 做逐年迭代、参数扫描、双状态耦合 ——
+   * >   而 ode、sensitivity、formula 就在那里，只是排在了『低频』栏的最后一行。」
+   *
+   * 原始证据也很硬：该会话调用 math_execute 18 次、手写 Python 6 个脚本约 300 行，
+   * 而脚本做的事（逐年迭代、参数扫描、状态耦合）工具全都有对应的 operation。
+   *
+   * ## 所以改动只有一处，但很关键
+   *
+   * 不是「再加一句说明」，而是**把建模类从『低频』栏里提出来单独成段**。
+   * 因为「低频」这个词本身就在劝退 —— 它表达的是「用得少」，
+   * 而 `ode` 用得少不代表不该在写增长模型时想起它。
+   *
+   * 并且在这一段的开头直接给一句**触发词**：「正在手写循环/逐年表/参数扫描？先看这几节」。
+   * 文档的建议原话也是这句：「能力不缺，缺的是一句『你正在手写循环？先看这里』」。
+   */
+  const MODELING_KEYS = ['ode', 'formula', 'derivation', 'recipe', 'world', 'domains']
+  const isModeling = (topic: HelpTopic) => MODELING_KEYS.includes(topic.key)
+  const arithmetic = core.filter((topic) => !isModeling(topic))
+  const modeling = core.filter(isModeling)
   const lines: string[] = [
     '══════ math_execute 能力目录（' + HELP_TOPICS.length + ' 节）══════',
     'helpTopic:"键名" 取该节全文；也可用中文词（矩阵/星球/单位…）。',
     '',
+    '  ── 一、算术 ──',
   ]
-  for (const topic of core) {
+  for (const topic of arithmetic) {
+    lines.push('  ' + topic.key.padEnd(10) + topic.title)
+    lines.push('    ' + topic.summary)
+  }
+  lines.push('')
+  lines.push('  ── 二、建模与推演 ──')
+  lines.push('  ★ 正在手写循环 / 逐年表 / 参数扫描？先看这几节，别用脚本重写')
+  for (const topic of modeling) {
     lines.push('  ' + topic.key.padEnd(10) + topic.title)
     lines.push('    ' + topic.summary)
   }
@@ -1072,7 +1161,7 @@ function renderIndex(): string {
    * 而它们本来只是「顺带知道一下」的存在。
    */
   lines.push('')
-  lines.push('  低频（同样可查，正文里有完整说明）:')
+  lines.push('  ── 三、其余能力（同样可查，正文里有完整说明）──')
   const folded = extra.map(function (item) {
     const label = item.short ?? item.title.slice(0, 8)
     return item.key + '=' + label

package/src/index.ts

@@ -208,6 +208,7 @@ import {
   setDisplayPrecisionExplicit,
 } from './precision-report.js'
 import { opOde } from './ops/ode-op.js'
+import { opRecurrence } from './ops/recurrence-op.js'
 import { opWorld } from './ops/world-op.js'
 import { opConstants } from './ops/constants-op.js'
 import { opWorkspace } from './ops/workspace-op.js'
@@ -349,6 +350,7 @@ const OPERATIONS: readonly MathOperation[] = [
   'formula',
   'formulas',
   'ode',
+  'recurrence',
   'world',
   'constants',
   'workspace',
@@ -2677,6 +2679,25 @@ function formaliveUnitOf(formula: FormulaDef, name: string): string {
   return unitFromDescription(spec.desc, (name) => { try { return findUnit(name) !== undefined } catch { return false } })
 }
 function opFormula(args: MathArgs, engine: any, precision: number): Outcome {
+  /**
+   * ## 批量调公式：`formulas: [...]`（结构性不足文档第四节）
+   *
+   * 实测反馈：「需要对 22 条公式做批量调用，但 `formula` 不支持 expressions 数组，
+   * 每次只能手动拆成单条 evaluate，等于放弃了公式库的全部价值。」
+   *
+   * 这不是「再开一个 operation」，而是**同一条公式的 N 次调用**——
+   * 所以做成 `formula` 的数组入参，语义与单个调用完全一致（含 unitFrom/unitTo/terse）。
+   *
+   * 元素两种写法：
+   *   · 字符串          "kleiber"
+   *   · 对象            {formula:"kleiber", overrides:{m:100}, label:"鼠"}
+   *
+   * ★ 一条失败不影响其它条 —— 与 `evaluate` 的 expressions 同一条纪律：
+   *   批量是「多条独立查询」，不是「一个事务」。汇总里会如实报 failed 条数。
+   */
+  if (Array.isArray((args as any).formulas) && (args as any).formulas.length > 0) {
+    return opFormulaBatch(args, engine, precision)
+  }
   const query = (args.formula ?? args.expression ?? '').trim()
   if (query === '') {
     throw new CalcError('invalid_argument', '需要 formula 参数', '传公式 id 或名称，例如 "escape_velocity"、"逃逸速度"。用 operation="formulas" 检索。')
@@ -3211,10 +3232,12 @@ const KNOWN_ARGUMENT_KEYS: ReadonlySet<string> = new Set<string>([
   'matrix', 'vector', 'precision', 'displayPrecision',
   // 数据与统计
   'data', 'dataY', 'distribution', 'params', 'x', 'degree',
-  // 公式
-  'formula', 'overrides', 'query', 'customExpression',
-  // 微分方程 / 物理
-  'initial', 'from', 'to', 'steps', 'samples',
+  // 公式（formulas 是批量，一次算多条）
+  'formula', 'formulas', 'overrides', 'query', 'customExpression',
+  // 微分方程 / 物理（at 是 ode 的指定采样时点）
+  'initial', 'from', 'to', 'steps', 'samples', 'at',
+  // 离散递推
+  'recurrence', 'periods',
   // 星球与推演
   'world', 'terrain', 'constants', 'derivation', 'layer',
   // 工作区
@@ -3478,7 +3501,7 @@ export function runMathTool(rawArguments: unknown): MathResult {
     const CACHEABLE: MathOperation[] = [
       'auto', 'evaluate', 'solve', 'system', 'derivative', 'integral',
       'simplify', 'expand', 'roots', 'matrix', 'eigen', 'stats', 'dist',
-      'regression', 'ode', 'formula', 'units',
+      'regression', 'ode', 'recurrence', 'formula', 'units',
     ]
     /**
      * 状态变更类操作：先清空缓存，再走正常流程。
@@ -3661,15 +3684,50 @@ export function runMathTool(rawArguments: unknown): MathResult {
       case 'regression':
         outcome = opRegression(args, input, precision)
         break
-      case 'formula':
+      case 'formula': {
         outcome = opFormula(args, engine, precision)
+        /**
+         * 批量公式的成败要在这里汇总成 `ok/partial/failed/succeeded`。
+         *
+         * 与 `evaluate` 的批量走同一套语义（见上方 3590 行那段注释）：
+         *   · `ok:false` 告诉自动化流程「本批不是全好」
+         *   · `partial:true` 告诉它「但有成功的条目可用」
+         *   · 顶层 `error` 仍是 `undefined`（这是批量失败，不是整体错误）
+         *
+         * 踩过：这些字段直接在 `opFormulaBatch` 的返回值上展开，
+         * 会被 `Outcome` 类型断言吞掉 —— 正文写着「成功 0，失败 3」，
+         * 而结构化字段全是 `undefined`。所以在这里显式赋给 `MathResult`。
+         */
+        if (Array.isArray((args as any).formulas)) {
+          const batch = (outcome.value ?? {}) as Record<string, unknown>
+          const failedCount = typeof batch.failed === 'number' ? batch.failed : 0
+          const succeededCount = typeof batch.succeeded === 'number' ? batch.succeeded : 0
+          const batched: MathResult = {
+            ok: failedCount === 0,
+            operation: 'formula',
+            input: 'formulas: ' + (args as any).formulas.length + ' 条',
+            result: outcome.result,
+            precision,
+          }
+          if (outcome.value !== undefined) batched.value = outcome.value
+          if (failedCount > 0) {
+            batched.partial = succeededCount > 0
+            batched.failed = failedCount
+            batched.succeeded = succeededCount
+          }
+          outcome = batched
+        }
         break
+      }
       case 'formulas':
         outcome = opFormulas(args)
         break
       case 'ode':
         outcome = opOde(args, engine, precision)
         break
+      case 'recurrence':
+        outcome = opRecurrence(args, precision)
+        break
       case 'world':
         outcome = opWorld(args, precision)
         break
@@ -3712,14 +3770,29 @@ export function runMathTool(rawArguments: unknown): MathResult {
         break
     }
 
+    /**
+     * ## 这里重新构造 `MathResult`，所以 `outcome` 上的成败字段必须**显式搬过来**
+     *
+     * 踩过两次，都是同一类：
+     *   ① 批量公式把 `ok/partial/failed/succeeded` 挂在 `outcome` 上 → 被这里覆盖成 `ok:true`
+     *   ② 早先 `evaluate` 批量也有同样问题，但它有独立的组装分支绕过去了
+     *
+     * 教训：`Outcome` 只是中间载体，真正的返回对象在这一处生成。
+     * 想加任何顶层字段，都得在这里接一次。
+     */
+    const batchOk = (outcome as any).ok as boolean | undefined
     const result: MathResult = {
-      ok: true,
+      ok: batchOk === undefined ? true : batchOk,
       operation,
       input,
       result: outcome.result,
       precision,
     }
     if (outcome.value !== undefined) result.value = outcome.value
+    for (const key of ['partial', 'failed', 'succeeded'] as const) {
+      const value = (outcome as any)[key]
+      if (value !== undefined) (result as any)[key] = value
+    }
     const variables = scopeSummary(args.variables)
     if (variables !== undefined) result.variables = variables
 
@@ -4238,8 +4311,7 @@ const PARAMETER_SPEC = {
   expression: {
     type: 'string',
     description:
-      '数学表达式、方程或待处理数据。多方程用逗号分隔（3x + 2y = 10, x - y = 1）。' +
-      '例：10^20 + 5、factorial(50)、x^3 * sin(x)、[[1,2],[3,4]] * [[5],[6]]、[1,2,3,4]。operation=help 时可空。',
+      '表达式、方程或数据。多方程逗号分隔。例：10^20+5、x^3*sin(x)、[[1,2],[3,4]]*[[5],[6]]。',
   },
   expressions: {
     type: 'array',
@@ -4285,8 +4357,7 @@ const PARAMETER_SPEC = {
     // 不逐个解释每个 operation 名称：enum 里已经列全，而 `help` 有完整说明。
     // 这里只给「怎么选」的判断线索，那才是 AI 真正需要的。
     description:
-      '默认 auto。简易算式用 evaluate；数据用 stats/dist/regression；' +
-      '改动设定后用 world/derivation；不确定就调 help 看全表。',
+      '默认 auto。简易算式 evaluate；数据 stats；改设定 world/derivation；不确定调 help。',
   },
   variable: {
     type: 'string',
@@ -4301,9 +4372,7 @@ const PARAMETER_SPEC = {
   unitFrom: {
     type: 'string',
     description:
-      '源单位。operation=units 时使用。支持中文古制（里/丈/尺/寸/步/亩/顷/斤/两/石/斗/刻/时辰/更）、' +
-      '英制（英里/英尺/磅/加仑）、天文（AU/光年/秒差距/地球半径/太阳半径）。' +
-      '只给单位不给参数则列出全部可用单位。',
+      '源单位（units）。支持中文古制（里/丈/斤/亩/时辰/刻）、英制（英里/磅/加仑）、天文（AU/光年）。只给单位不给数值则列全表。',
   },
   unitTo: {
     type: 'string',
@@ -4319,14 +4388,12 @@ const PARAMETER_SPEC = {
     type: 'object',
     additionalProperties: true,
     description:
-      '收支盘点（operation=balance）：每项 {demand, supply, unit?}，给最短板。' +
-      '只判社会收支；单项生理/工程上限用 feasibility。',
+      '收支盘点（balance）：每项 {demand, supply, unit?}，给最短板。单项上限用 feasibility。',
   },
   bodyName: {
     type: 'string',
     description:
-      '查单个天体（operation=bodies）。可给 id（mars）或中文名（火星）。' +
-      '已收录太阳系全 8 大行星 + 月球类卫星 + 代表性系外行星 + 矮行星 + 各亮度级恒星。',
+      '查天体（bodies）：id（mars）或中文名（火星）。含行星、卫星、系外行星、矮行星、各级恒星。',
   },
   bodyKind: {
     type: 'string',
@@ -4336,8 +4403,7 @@ const PARAMETER_SPEC = {
   bodyConstant: {
     type: 'string',
     description:
-      'bodies：改常数后看哪些天体数据该重算。例 bodyConstant="alpha_fs", bodyFactor=2。' +
-      '输出分「必须重算」与「绝不该动」两块（行星质量/半径/轨道与 α 无关）。',
+      'bodies：改常数后看哪些天体数据该重算。例 alpha_fs + bodyFactor=2。分「必须重算」与「绝不该动」两块。',
   },
   bodyFactor: {
     type: 'number',
@@ -4368,8 +4434,7 @@ const PARAMETER_SPEC = {
   displayPrecision: {
     type: 'integer',
     description:
-      '**显示精度：小数点后几位**（0-64，默认 8）。只截小数、整数永远完整，0 = 只留整数。' +
-      '可用 workspace set displayPrecision=N 固化（那里的 0 = 清除）。',
+      '**显示精度：小数点后几位**（0-64，默认 8）。只截小数、整数完整，0=只留整数。可 workspace set 固化（0=清除）。',
   },
   data: {
     type: 'array',
@@ -4398,30 +4463,32 @@ const PARAMETER_SPEC = {
   formula: {
     type: 'string',
     description:
-      'operation="formula" 时要调的公式 id 或名称，例如 "escape_velocity"、"逃逸速度"、"cobb_douglas"。' +
-      '用 operation="formulas" 检索可用公式。',
+      'operation="formula"：公式 id 或名称，如 "escape_velocity"、"逃逸速度"。检索用 operation="formulas"；多条用 formulas 数组。',
   },
+  formulas: { type: 'array', items: { type: 'json', description: '"kleiber" 或 {formula, overrides?, label?}' }, description: '批量调多条公式；一条失败不影响其它条。' },
   overrides: {
     type: 'object',
     additionalProperties: true,
     description:
-      '覆盖公式任意参数 —— 架空世界改造的关键。例：重力 1.5 倍 {"g": 14.71}、光速 {"c": 1e8}。',
+      '覆盖公式任意参数（架空改造的关键）。例：重力 1.5 倍 {"g":14.71}、光速 {"c":1e8}。',
   },
   customExpression: {
     type: 'string',
     description:
-      'structure 级改造：临时替换公式表达式，沿用其参数名。例 formula="weight", customExpression="m*g*1.3" 表示重力 +30%。',
+      'structure 级改造：临时替换公式表达式，沿用参数名。例 customExpression="m*g*1.3" 即重力 +30%。',
   },
   query: {
     type: 'string',
     description: 'operation="formulas" 的检索关键词，例如 "重力"、"熵"、"人口"；传 "*" 或留空列出全部分类。',
   },
+  recurrence: { type: 'string', description: 'operation="recurrence"：下一期 = f(本期)，如 "P*2"、"P*min(1.2,1000/P)"。配 initial 与 periods 出逐期表。' },
+  periods: { type: 'integer', description: 'recurrence 的迭代期数（默认 12，上限 5000）。' },
+  at: { type: 'array', items: { type: 'number' }, description: 'ode 要精确输出的时点，如 [5,10,20]（写年表用）。' },
   initial: {
     type: 'object',
     additionalProperties: true,
     description:
-      'operation="ode" 的初值条件。例如 {"S": 999, "I": 1, "R": 0}。' +
-      '二阶方程降阶后可能还需要辅助变量（如 y_d 表示 dy/dt），缺了会提示补哪个。',
+      'ode/recurrence 初值，如 {"S":999,"I":1}。二阶降阶需辅助变量 y_d=dy/dt，缺了会提示。',
   },
   from: {
     type: 'number',
@@ -4445,9 +4512,7 @@ const PARAMETER_SPEC = {
     // 字段清单不写在 schema 里：schema 每轮都要付费，而这些字段只在
     // 真用 world 时才需要。全文见 help（operation="help", query="world"）。
     description:
-      '星球参数（operation=world），全部可选，默认地球。' +
-      '常用键：planetMass/planetRadius、starMass/starTemp、rotationHours、obliquityDeg。' +
-      '完整字段表见 help。',
+      '星球参数（world），可选，默认地球。常用键 planetMass、starMass、rotationHours、obliquityDeg。完整见 help。',
   },
   planetRadius: {
     type: 'number',
@@ -4470,16 +4535,14 @@ const PARAMETER_SPEC = {
     additionalProperties: true,
     // 同上：地形字段有九项，逐项列在 schema 里太贵。
     description:
-      '局部地形（operation=world 附带），给了就额外输出该地点气候细节。' +
-      '常用键：kind、elevation、latitudeDeg、oceanCurrent。完整键表见 help。',
+      '局部地形（world 附带）。常用键 kind、elevation、latitudeDeg、oceanCurrent。完整见 help。',
   },
   constants: {
     type: 'object',
     additionalProperties: true,
     // 旋钮清单移进 help：只有要改常数时才需要，不该每轮付费
     description:
-      '要改的物理常数（operation=constants），只能改基础旋钮，派生量自动重算。' +
-      '例：{c:1.5e8}。可用旋钮清单见 help 的 constants 节。',
+      '要改的物理常数（constants）：只改基础旋钮，派生量自动重算。例 {c:1.5e8}。旋钮清单见 help。',
   },
   helpTopic: {
     type: 'string',
@@ -4558,6 +4621,98 @@ function checkPrecisionTruncation(
     ' 位可能已失真。需要精确值时请用 precision:64（默认），' +
     '只想让输出短些请用 displayPrecision。'
 }
+
+/**
+ * 批量调公式（`formulas: [...]`）。
+ *
+ * ## 为什么复用 opFormula 而不是重写一套
+ *
+ * 单个调用涉及：严格解析、overrides 覆盖、单位换算、terse 精简、
+ * 适用域提示、未生效 key 上报 —— 这些逻辑**必须与单条完全一致**。
+ * 重写一套必然漂移，而「单条能算、批量算得不一样」正是这个项目
+ * 反复修过的那类缺陷（1107 报告的批量非有限值、单条/批量输出不一致）。
+ *
+ * 所以这里只做三件事：逐条调用、收集结果、汇总成败。
+ *
+ * ## 失败语义
+ *
+ * 一条失败 → 该条在输出里标 `失败[type]`，继续算下一条，
+ * 最后由 `ok`/`failed`/`succeeded` 如实汇总。**不因为一条错就中断整批**。
+ *
+ * @param args - 含 `formulas` 数组的入参
+ * @param engine - mathjs 实例
+ * @param precision - 计算精度
+ * @returns 批量结果
+ */
+function opFormulaBatch(args: MathArgs, engine: any, precision: number): Outcome {
+  const list = (args as any).formulas as any[]
+  const lines: string[] = []
+  const rows: Record<string, unknown>[] = []
+  let failed = 0
+  lines.push('═══ 批量公式（' + list.length + ' 条）═══')
+  lines.push('')
+  for (let index = 0; index < list.length; index += 1) {
+    const item = list[index]
+    const isObject = item !== null && typeof item === 'object'
+    const id = String(isObject ? (item.formula ?? item.id ?? '') : item).trim()
+    const label = isObject && item.label !== undefined ? String(item.label) : ''
+    /** 逐条构造入参：继承顶层公共参数（terse/unitFrom/unitTo/precision），再叠加元素自己的。 */
+    const oneArgs: MathArgs = {
+      ...args,
+      formulas: undefined,
+      formula: id,
+      expression: undefined,
+      overrides: isObject && item.overrides ? item.overrides : (isObject ? undefined : args.overrides),
+    } as MathArgs
+    (oneArgs as any).formulas = undefined
+    if (isObject && item.terse !== undefined) (oneArgs as any).terse = item.terse
+    const prefix = label === '' ? '' : label + '（' + id + '）'
+    try {
+      const outcome = opFormula(oneArgs, engine, precision)
+      const text = String(outcome.result ?? '').trim()
+      /**
+       * 抓「结果:」那一行 —— 公式输出的第一行是标题（名称 + 分类），
+       * 数值在「结果:」行上。只取首行会得到 `克莱伯定律（代谢率） [physics/scaling]`，
+       * 数值整个丢了，而批量恰恰是为了看一串数。
+       */
+      const valueLine = text.split(/\r?\n/).find(function (line) { return line.trim().startsWith('结果') })
+      const first = valueLine ?? (text.split(/\r?\n/).find(function (line) { return line.trim() !== '' }) ?? '')
+      /** terse 输出本身已是 `kleiber = 31622…`，别再加一层 `id = ` 变成 `kleiber = kleiber = …`。 */
+      const alreadyNamed = String(first).trim().startsWith(id + ' =')
+      const shown = String(first).replace(/^结果\s*[:：]\s*/, '').trim()
+      const body = alreadyNamed ? shown : id + ' = ' + shown
+      lines.push('  ' + (prefix === '' ? body : prefix + ' = ' + shown))
+      rows.push({ formula: id, label: label === '' ? null : label, ok: true, result: outcome.value ?? null })
+    } catch (error) {
+      failed += 1
+      const type = (error as any)?.type ?? 'unknown'
+      const message = String((error as any)?.message ?? error).slice(0, 120)
+      lines.push('  ' + (prefix === '' ? id : prefix) + ' → 失败[' + type + '] ' + message)
+      rows.push({ formula: id, label: label === '' ? null : label, ok: false, error: type })
+    }
+  }
+  const succeeded = list.length - failed
+  lines.push('')
+  lines.push(
+    failed === 0
+      ? '全部 ' + succeeded + ' 条都有结果（只表示公式存在且参数可算，不含结论正确性判断）'
+      : '成功 ' + succeeded + '，失败 ' + failed + '（失败条已逐条标注原因）',
+  )
+  /**
+   * 汇总字段必须**真的出现在返回值里**：`ok` / `failed` / `succeeded` / `partial`。
+   *
+   * 踩过：`{...cond ? {...} : {...}}` 这种写法在 Outcome 类型下会被类型断言吞掉，
+   * 实测返回 `ok=true` 却 `failed=undefined` —— 而正文里明明写着「成功 0，失败 3」。
+   * 正文与结构化字段不一致，比只给正文更糟（调用方读哪个？）。
+   * 所以改成显式赋值。
+   */
+  /** 汇总字段放进 `value`，由调用方（`runMathTool`）提升到顶层 `MathResult`。 */
+  return {
+    result: lines.join('\n'),
+    value: toJsonValue({ count: list.length, succeeded, failed, rows }),
+  }
+}
+
 /**
  * 数学计算工具（`math_execute`）。
  *