dsh-math-calculator 0.0.0-stage → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,221 @@
+# 更新日志
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [2.0.0] — 2026-10-26
+
+首个公开发布版本。
+
+### 新增
+
+- **公式库 355 → 395 条**，补的是**通用计算**（第七批 `formula-library-basic.ts`）。
+  起因是实测：35 个常见计算需求只命中 17 个，缺的全在金融/几何/化学/电学/工程：
+  - 金融 10 条：等额本息月供、单利、年金现值、NPV、直线折旧、盈亏平衡销量、
+    实际年利率、复利翻倍时间、通胀后购买力、毛利率
+  - 几何 8 条：余弦定理、正弦定理、扇形面积、球冠体积、梯形、椭圆、圆环体、正多边形
+  - 化学 8 条：溶度积、滴定体积、质量摩尔浓度、质量百分比、ppm、标准气体体积、
+    摩尔数换粒子数、放射性剩余量
+  - 电学 7 条：容抗、感抗、LC 谐振、分压、用电量、电池续航、变压器匝数
+  - 工程 6 条：齿轮比、雷诺数、热应力、弹簧储能、液压推力、皮带轮转速比
+  - 天文 1 条：主序星寿命（此前只在 `world` 内部算，没暴露成公式）
+
+  这批全部做了数值验算，且尽量带**可自证的端点**：余弦定理在 3-4-5 直角三角形
+  上应得 5；球冠 h=r 得半球 2π/3、h=2r 得整球 4π/3；正多边形 n=4,s=2 得正方形面积 4；
+  单利与年复利在 t=1 时必须相等。
+
+### 修复
+
+- **检索查不到中文复合词**（比补公式更影响体感）：`findFormulas` 只做整串子串匹配，
+  于是 `粮食` 能查到 4 条、`粮食产量` 却是 0 条；`比热` 能查到、`比热容` 查不到。
+  用户和 AI 不会总说最短形式。现在加了：
+  - 中文 2—4 字滑窗子词匹配（`粮食产量` 能对上关键词「粮食」「产量」）
+  - 同义词表（`比热容`→`比热`、`月供`→`贷款`、`粘度`→`黏度` 等 30 组）
+  - 词元按长度加权，长词命中排前面，避免「粮食产量」把所有含「量」的公式挤上来
+  - 默认返回上限 10 → 20（宽查询不再被截断）
+
+- **`world` 顶层参数静默失效**：此前只认 4 个便捷参数
+  （`planetRadius`/`planetMass`/`rotationHours`/`obliquityDeg`），
+  于是 `{operation:'world', starMass:10}` 里的 `starMass` 被**静默丢弃** ——
+  输出仍是太阳（主序寿命 10 Gyr），一句报错都没有。作者以为算的是 10 倍质量恒星。
+  现在改为遍历 `WORLD_PARAMS` 全量白名单派生便捷参数，且 `world` 内同名键优先。
+
+- **频次测试写死绝对值**：`formula-story.mjs` 断言「高频 50—130 条」，
+  公式库一扩容就误报失败。它本意是「高频不应占满全库」的比例约束，
+  改成占 20%—60% 的比例断言。
+
+### 修复
+
+- **主动提醒命中率归零**（最严重的一条）：`agent/pre-step` 钩子用
+  `content.includes('math_execute')` 判断「本会话是否已用过插件」，而我们的系统提示
+  每轮都注入、且必然包含这个词 —— 于是 `toolUsedInSession` 恒为 `true`，
+  检测器从第一轮之后**永久静默**。
+
+  实测：检测器本身命中率 72%（13/18 条真实作者语句，误报 0/6），但经过钩子后
+  实际命中率 **0**。修法是改成**结构化判断**：只看 `role === 'tool'` 消息、
+  assistant 的 `tool_calls` 数组、或 content 里的 `type: 'tool_use'` 块。
+  「用户问 math_execute 怎么用」也不再被误判成「已用过」。
+
+  修后实测：真实对话历史（含系统提示）下命中率 **90%**（9/10），
+  真调过工具后仍正确静默（4/4）。
+
+- **工具描述漏了 3 个 operation**：`TOOL_DESCRIPTION` 里没有 `derivation`、
+  `custom`、`feasibility`，模型因此不知道它们存在 —— 而所有测试全绿。
+  原因是 `test/awareness.mjs` 里手写了一份 operation 清单，加新 op 时没同步。
+  现在清单**从 schema enum 派生**（唯一真相），并加反向断言与长度预算（≤900 字符）。
+  描述长度 810 → 718 字符，同时覆盖全部 29 个 operation。
+
+- **检测器缺势力收支类词表**：`balance` 是新增能力，但检测器词表里没有
+  「养得起/够不够/军费/粮草」这类说法，导致「这个王国养得起二十万兵吗」评分 0。
+  已补两条意图模式，命中率 72% → 83%。
+
+- **`help` 让作者去点一个不存在的面板**：数据管理那段还写着「侧栏『数学工作区』入口
+  可图形化管理」，但界面 2026-10-25 已全部移除。AI 照读会把作者引到一个点不开的入口。
+  已改成「本插件没有图形界面，全部经工具与 HTTP 路由操作」。
+  同时 `test/advanced.mjs` 里那条「help 必须提到侧栏入口」的断言原本把错误行为
+  写成了预期，改为反向断言（不许出现「侧栏」，必须说明「没有图形界面」）。
+
+- **世界推演的措辞违反项目铁律**：1.4 g 以上会输出「生物**必须**更矮壮」，
+  而铁律要求输出措辞不出现「错误/禁止/必须」（`test/ai-brief.mjs` 守着这条）。
+  改成「生物得长成矮壮型才撑得住」。这一条是**实际使用验收**跑出来的，
+  原来的世界推演测试只看数值不看措辞。
+
+- **单位清单的伪精度**：`亩` 的系数是 666.6…（无限循环），清单里显示成
+  `666.6666666666666`，看着像精确值。系数改用独立格式化，显示 `666.667`。
+
+### 测试
+
+- 新增 `test/real-usage.mjs`（94 项）：**作者视角的实际使用验收**。
+  与其它套件不同，它验的是「拿去能不能用」而不是「算得对不对」：
+  输出里不许出现已删界面、`Infinity`/`NaN`/`undefined`/`[object Object]`；
+  必须有单位与可信度标签；措辞不许反驳作者设定；错误必须给修复方向；
+  输出体积有上限（AI 读得下）；并把「1.5 g 星球 → 50 米巨兽站不住 →
+  300 米塔能建 → 王国养不养得起兵 → 火箭飞不出去 → 三十里多长」串成一个
+  完整场景，检查前后自洽。
+
+### 移除
+
+- **UI 全部移除**（2026-10-25，`14f6ed0`）。做了三版（目录树 18 节点 → 精简 10 节点 →
+  单页工作台）效果始终不好，决定砍掉：`src/client.ts`（2497 行）、`lib/client.js`
+  （138.8 KB）、9 个客户端测试套件、`tsconfig.client.json`、`package.json` 的
+  `dsh.client` 与 `exports["./client"]`。**后端模块一个没动**，能力全部保留，
+  只经 `math_execute`（27 种 operation）与 HTTP 路由给 AI。见 `docs/ui-removed.md`。
+
+### 新增
+
+- **世界参数校验（三档）**：`world-params.ts` 的 `range` 此前是**纯装饰** ——
+  22 处声明没有任何代码读取，实测 `planetMass=-5`、`planetRadius=0`、`albedo=5`
+  都 200 OK 存进去了。新增 `src/world-validation.ts` 让范围真正生效：
+  - **硬拒绝 400**：`range.hard` 且**低于下界** —— 会算出无穷/非数/负物理量
+    （零半径 → 重力 Infinity、零质量 → 离心比 Infinity、零轨道 → 80 处 Infinity）；
+  - **软警告 200 + `warnings[]`**：越界但仍照设定算（`planetMass=500`、`albedo=1.5`），
+    消息里给出范围与代价。**上界一律走这一档** —— 「质量大得离谱」是设定自由，
+    拦了就违反「不反驳用户设定」；
+  - **静默接受**：在范围内。
+
+  哪些参数标 `hard` 是**实测**出来的（逐个取极端值跑推演、统计产物里 `Infinity`/`NaN`
+  个数），不是拍的。实测还暴露了探针自身的 bug：`planet.surfaceGravity` 其实是
+  显示串（`'Infinity'` 字符串），只看 `typeof === 'number'` 会整片漏判。
+
+- **`invalid` 判定档**（`dead-universe.ts`）：检出物理量非有限/为负时判 `invalid`，
+  与 `dead` 分开 —— `dead` 是「死寂宇宙」这种合法设定，`invalid` 是「参数本身算不出数」。
+  混在一起会让作者以为「世界设得太狠」，实际是把半径写成了 0。渲染措辞仍只讲怎么改，
+  不写「错误/禁止/必须」。
+
+- **逐颗卫星 `moons` 可存档**：`world.ts` 早已支持 `MoonSpec[]`（洛希极限/希尔球/
+  相邻间距/观感），但 `moons` 不在白名单里，导致「多卫星系统」只能直接调 tool、
+  存不进工作区。`ParamSpec.kind` 新增 `'array'` 与 `itemShape`，现在能存能校验。
+
+### 修复
+
+- **`Infinity`/`NaN` 会流到 AI**（最伤可信度的一条）：`/summary` 的
+  `derived[].value` 曾是裸 `Infinity`（只有 `text` 被格式化成 `—`），
+  `verdict.causes` 里也有 `"表面重力不成立：Infinity m/s²"`。AI 会当成真数字写进结语
+  ——「这颗星球重力是 Infinity」。现在 `deriveAll` 用 `finite()` 统一归一化，
+  `judgeDead` 的原因描述改成中文（不出现字面量），整个响应不含 `Infinity`。
+- **`save-world` 的双白名单事故**：该路由曾自带一份 14 键硬编码白名单，
+  而 `WORLD_PARAMS` 有 23 个基础量 —— 于是 `starClass`（「我要 G2V 恒星」）、
+  `hasLiquid`、`materialStrength/Density`、`moonCount/Mass/Distance`、
+  `lightPollution`、`galaxyBand` 共 9 个键被**静默丢弃**：返回 200 OK，不报错不提示。
+  现在白名单只留一个真相。
+- **类型静默强转**：`Number(true)===1`、`Number([])===0`、`Number(['7'])===7` ——
+  `{planetMass:true}` 曾静默存成 1。现在只接受 `number` 与数字字符串，其余 400。
+- **注入给 AI 的 operation 数量是旧的**：`awareness.ts` 的系统提示写「共 25 个」，
+  实际 27 个（漏了 `derivation` 与 `custom`）。`integration.mjs` 的断言清单同样只有 25 个，
+  现在补齐到 27 并加了**反向断言**（schema 里不许有清单外的名字）。
+- **`npm run preflight` 因 UI 移除而崩溃**：它仍在 `readFileSync('lib/client.js')`，
+  文件已删 → `ENOENT`，装机前自检直接非零退出。改为反向断言（客户端产物确实不存在、
+  无 `dsh.client`、无 `exports["./client"]`、无 `tsconfig.client.json`），
+  与 `test/integration.mjs` 第 5 节互为印证。
+- **`tsconfig.json` 仍排除 `src/client.ts`**：文件早不存在，排除项清掉。
+
+### 测试
+
+- 新增 `test/validation.mjs`（82 项）：硬边界拒绝、软范围只警告、类型严格性、
+  逐颗卫星校验、元数据自身完整性（标了 hard 的必须有上下界、array 型必须有 itemShape）。
+- 新增 `test/sanity.mjs`（34 项）：`findPhysicsIssues` 检出能力、`invalid` 与 `dead`
+  分离、渲染不泄 `Infinity`、坏存档兜底、正常链路不受影响。
+- 新增 `test/summary.mjs`（37 项）：`deriveAll()` 的白名单过滤 —— UI 三版删掉后，
+  它是「`派生量绝不入库`」唯一还在运行的实现点。
+- 新增 `test/ai-journey.mjs`（58 项）：把「作者说一句话 → AI 该走的那条链」复刻成路由调用
+  （`world-params` → `solve-anchor` → `save-world` → `summary` → `derive/dead`），
+  跑在真派发上（含路由顺序与前缀）；逐个试存全部 24 个基础量。
+  取代了原来「重启 DSH 人肉看」的验证方式。
+- 四个新套件都做过**反向对照**（故意破坏实现确认测试变红），避免装饰性测试。
+- 全量基线：**56 套 / 2232 项 → 60 套 / 2444 项**，全绿。
+
+### 文档
+
+- 删除 7 篇只描述已删界面的文档（`ui-simplified.md`、`ui-v3-workbench.md`、
+  `ui-feedback-fixes.md`、`ui-implementation-status.md`、`ui-v2-panels.md`、
+  `client-ui-architecture.md`、`ui-conventions.md`）。
+- 另外 12 篇加「已作废 / 仍有效」说明而非删除 —— 它们承载的知识比界面更长久：
+  `ui-redesign-v3.md` 改题为「参数分层与自洽推演」（三层结构与四条自洽规则是领域核心）、
+  `ui-design-v2.md` 是用户原始设计稿、`adr/0002` 是决策历史（只追加 superseded 说明）。
+- `README.md`：UI 章节改为「AI 调用，没有面板」，operation 数量 25 → 27，
+  补「世界参数校验三档」与「逐颗卫星」两节。
+
+## [2.0.0] — 2026-10-24（内部定稿，未发布）
+
+> 这是公开发布前的内部定稿，内容并入上方 2.0.0 一起发布。
+> 保留原文是为了记录当时的取舍（例如那版还带界面，后来整体移除了）。
+
+### 能力
+
+- **计算内核**：BigNumber 64 位高精度求值、符号微积分（求导/积分/化简/展开）、
+  解方程与线性系统、矩阵（秩/行列式/迹/奇异值/零空间/逆）、统计与概率分布、
+  回归、ODE（RK4）。
+- **UI（令牌化）**：左栏「全局管理」与右栏「本工作区工作台」共用同一套宿主设计令牌
+  （`--dsw-alias-*` / `--dsw-font-*` / `--dsw-radius-*`），无写死颜色；
+  **新建工作区即生成同名数据表**（`<工作区名>.json`，含常数/公式/地点/变量四张子表），
+  切换工作区后右栏自动跟随。
+- **公式库 342 条**，每条带**三轴标签**：
+  `layer`（离最底层规则的远近：基本/数学/导出/经验/工程/约定）、
+  `domains`（学科领域，多标签）、`frequency`（**主角视角感知频率**）。
+  检索：`freq:` / `layer:` / `domain:` / `symbol:` / `keyword`。
+- **两级公式扩展**：全局公式包（`$DSH_HOME/math-calc/formula-packs/global.json`，写盘即生效）
+  + 工作区临时公式；新增时校验 id、表达式可解析、**符号必须已定义**（拼错变量当场拒绝）。
+- **符号消歧**：同一字母不同含义（`m` = 质量/米）可查 `symbol:m@质量`。
+- **常数推演**：无量纲优先（α/μ/α_s/α_G）、尺度阶梯、单位旋钮与物理改动分离、矛盾清单。
+- **世界推演**：恒星（质光/寿命/宜居带/α 敏感度）→ 气候 → 天空配色 → 卫星系统 →
+  化学窗口与生命硬否决 → 跨模块一致性检查 → 经验系数可信度标注。
+- **UI**：左侧入口 = **全局管理**（所有工作区：创建/切换/删除，常数表、公式表、设置）；
+  右侧边栏页签 = **本工作区工作台** —— 工作区切换器、本区数据表（常数/公式/地点/变量）、
+  **开关**（提示档位、公式启停）、**管理**（变量与地点的增删）。
+  左栏切换工作区后右栏**自动跟随**（同一 client bundle 内的订阅 + 宿主 `sidebarRight` store）。
+
+### 工程质量
+
+- 全量 **41 套 / 1716 项**测试；含确定性、真机宿主契约、**对抗性兼容性**（敌意 ctx、
+  服务抢占、全局污染、数据损坏）与**客户端注册契约**回归。
+- `preflight` 装机前自检：入口契约、客户端席位、运行期依赖、注释覆盖、清单一致性、
+  peer 版本可接受性。
+- `doccheck` 强制：每个模块有头注释、每条导出有文档注释（321 导出 / 0 缺失）。
+
+### 修复（相对内部早期版本）
+
+- **客户端注册 id 必须等于包名**：此前用 `<包名>-client`，宿主按包名查找不到模块，
+  导致桌面端每次启动都报 `import failed` 并致命退出。
+- **客户端入口幂等**：宿主会重放 bundle，重复注册会抛错并升级为致命错误。
+- **peer 依赖接受 prerelease**：`>=0.1.0 <0.3.0` 不接受 `0.1.7-rc.2`，改为 `>=0.1.0-0 <0.3.0`。
+- **工作区切换自动落盘**：此前切到不存在的工作区只产生内存对象，`current` 会指向幽灵工作区。
+- 工作区创建兼容 `name` 参数（此前只认 `workspace`，误报「不能是 default」）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 czkssg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.