dsh-plugin-calculator

一个面向 DeepSeek Harness (dsh) 的数学计算工具插件，偏重复杂计算时记录计算过程和结果。

为模型提供四个数学工具（v0.2.0）：

• basic_arithmetic：基本数学运算（加减乘除、幂运算、取模）
• scientific_calculation：科学数学计算（三角函数、对数、指数等）
• unit_conversion：单位换算（长度、重量、数据存储、时间、面积、体积、温度）
• evaluate_expression：多步表达式求值（括号、优先级、函数、变量）

三个数值工具都支持统一的精度控制参数：precision（小数位 0~15）与 round_mode（half-up / half-even / floor / ceil / trunc）。

功能特性

1. 基本数学运算 (basic_arithmetic)

支持六种基本运算：

• add：加法
• subtract：减法
• multiply：乘法
• divide：除法
• power：幂运算
• modulo：取模运算

2. 科学数学计算 (scientific_calculation)

支持多种科学计算：

• sqrt：平方根
• abs：绝对值
• ceil：向上取整
• floor：向下取整
• round：四舍五入
• log：对数（可选底数，默认自然对数）
• sin：正弦函数
• cos：余弦函数
• tan：正切函数
• exp：指数函数（e^x）

3. 单位换算 (unit_conversion)

覆盖七个单位组，单位大小写不敏感，跨组换算会明确报错：

| 组 | 单位 | |---|---| | 长度 | m km cm mm um in ft yd mi | | 重量 | kg g mg t lb oz | | 数据存储 | b bit；十进制 kb mb gb tb pb；二进制 kib mib gib tib | | 时间 | ms s min h d w | | 面积 | m2 km2 cm2 ha acre ft2 | | 体积 | l ml m3 gal qt cup ft3 | | 温度 | C F K（按标准公式含偏移量） |

4. 表达式求值 (evaluate_expression)

一次多变的多步计算：(12+8)*3/5、pi*r^2、max(a,b)+sqrt(c)。

• 运算符：+ - * / % ^（^ 右结合，也接受 **）、括号、一元正负
• 函数：sqrt cbrt abs round floor ceil trunc ln log10 log2 exp sin cos tan sign pow min max
• 常量：pi e tau
• 变量：variables 传 JSON 对象字符串（最多 20 个，值必须是有限数字），变量名大小写不敏感
• 不使用 eval：自研词法分析和递归下降解析，未知标识符、参数个数不符、括号不匹配等都给出可读原因

5. 精度控制

| 参数 | 说明 | |---|---| | precision | 0~15 的整数；不传则输出精确值 | | round_mode | half-up（默认，0.5 远离零）/ half-even（银行家舍入）/ floor / ceil / trunc |

实现上用十进制指数技巧规避二进制浮点噪声：1.005 保留 2 位按 half-up 得到 1.01，而不是 1.00。结果与精确值一致时会提示「结果未发生变化」，避免让人误以为发生了舍入。

本地开发

# 安装依赖
pnpm install

# 用绝对路径临时调试（name 指向本插件的入口文件）
cat > debug.patch.yml <<"EOF"
- insert:
    - id: calculator
      name: "E:/dsh-plugins/dsh-plugin-calculator/index.js"
EOF

# 启动 dsh Web 并加载插件，打开 http://127.0.0.1:3080
pnpm dsh web --patch ./debug.patch.yml

安装到 profile

先构建 tarball：

pnpm pack

然后把它安装到目标机器上的 dsh：

dsh plugin --profile web add ./dsh-plugin-calculator-0.2.0.tgz

验证配置是否生效：

dsh plugin --profile web --dump-config

卸载：

dsh plugin --profile web remove dsh-plugin-calculator

发布到 npm

# 确认已登录（首次先执行 npm login）
npm whoami

# 发布
npm publish

发布后，任何用户都可以通过 dsh plugin --profile web add dsh-plugin-calculator 安装。

使用示例

安装插件后，AI 模型可以调用以下工具：

基本运算

用户: 计算 23 加 45
AI: 调用 basic_arithmetic 工具，operation="add", a=23, b=45
结果: 23 + 45 = 68

科学计算

用户: 计算 16 的平方根
AI: 调用 scientific_calculation 工具，operation="sqrt", value=16
结果: √16 = 4

单位转换

用户: 把 100 公里转换成英里
AI: 调用 unit_conversion 工具，value=100, fromUnit="km", toUnit="mi"
结果: 100km = 62.13711922373339mi

表达式求值

用户: 半径 2.5 的圆面积是多少，保留 2 位小数
AI: 调用 evaluate_expression 工具，expression="pi*r^2", variables='{"r": 2.5}', precision=2
结果: pi*r^2 = 19.634954084936208
      ≈ 19.63（precision=2, round_mode=half-up）

单位换算（扩展单位）

用户: 1GB 是多少 MB？1 公顷是多少平方米？
AI: 调用 unit_conversion，value=1, fromUnit="gb", toUnit="mb"
结果: 1gb = 1000mb

技术细节

参数验证

• 所有数字参数都会进行类型转换和验证
• 提供详细的错误信息帮助调试

输出格式

• 工具返回格式化的字符串，包含计算过程和结果
• 支持中文显示，提升用户体验

安全性

• 所有计算都在本地执行，不涉及外部 API 调用
• 输入验证防止常见的数学错误（如除零、负数平方根等）
• 表达式求值不使用 eval/Function，仅按白名单函数与运算符解析

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-plugin-calculator
• npm：https://www.npmjs.com/package/dsh-plugin-calculator

典型场景

1. 精确算术（避免模型心算出错）

用户：帮我算一下 1234.56 × 78.9 精确到分

basic_arithmetic 由真实计算引擎得出结果，不依赖模型估算。

2. 单位换算

用户：100 英里是多少公里

unit_conversion 支持长度/重量/温度等常见单位换算。

3. 科学计算

用户：算一下 log2(1024) 和 30 度的正弦

scientific_calculation 覆盖开方、对数、三角函数等。

5. 多步算式一次算完

用户：把 (12+8)*3/5 和 半径 2.5 的圆面积算出来

evaluate_expression 支持括号、优先级、函数与变量，结果可指定保留位数。

6. 批量口径核算

用户：这批数字都按同一公式算一遍

多次调用或组合运算，保证口径一致、结果可复现。

安全边界

• 纯本地计算：不联网、不读写文件，无副作用。
• 不执行任意代码：只解析算术表达式与受支持的函数，不 eval 任意脚本。
• 精度说明：浮点运算遵循 IEEE 754 语义；涉及金额的场景请显式传 precision 与 round_mode，不要让调用方自行猜测舍入口径。
• 表达式资源上限：表达式长度 ≤ 500 字符、变量 ≤ 20 个，超出直接报错。
• 除零等异常明确报错：不做静默兜底，避免错误结果被当作正确值使用。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-csv-explorer | 统计出的数值可用本插件做进一步核算 | | dsh-table-render | 计算结果整理后用 render_table 出表 | | dsh-text-stats | 字数/行数统计与本插件的数值计算互补 | | dsh-token-budget-tools | 估算 token 成本时可用本插件做乘法核算 |

RoadMap

v0.2（已完成）

• ✅ 表达式求值（括号、变量与多步运算）
• ✅ 精度控制参数（小数位 + 五种舍入模式）
• ✅ 扩展单位库（数据存储、时间、面积、体积）

v0.3（展望）

• 货币换算（需联网汇率，独立开关）
• 百分数/复利等财务常用函数
• 与 dsh-csv-explorer 联动：对列数据批量套用公式
• 表达式里的自定义函数定义（如 f(x)=x^2+1）

版本历史

v0.2.0 (2026-09-30)

• ✨ 新增 evaluate_expression 工具：括号、运算符优先级、右结合幂、18 个内置函数、常量与变量（不使用 eval）
• ✨ 新增精度控制：precision（0~15）与 round_mode（half-up / half-even / floor / ceil / trunc），覆盖三个数值工具
• ✨ 单位库从长度/重量/温度扩展到数据存储、时间、面积、体积，共 7 组 40+ 单位；跨组换算明确报错
• 🐛 修复参数 schema 中的 required: false（框架不允许显式 false，此前会导致插件注册直接抛错）
• 🧪 测试从“复制逻辑的打印脚本”重写为真实调用工具的断言脚本，87 项断言

v0.1.1

• 早期版本：基本运算、科学计算、单位转换三个工具

FAQ

Q：会算错浮点吗？ 浮点是 IEEE 754 语义，0.1 + 0.2 这类会有典型误差。金额场景建议明确舍入位数。

Q：支持表达式吗？ 支持。evaluate_expression 可以一次算 (12+8)*3/5、pi*r^2 这类多步算式，支持括号、函数与变量，且不使用 eval。

Q：舍入模式怎么选？ 一般场景用默认 half-up；对分布敏感的统计场景用 half-even（银行家舍入）；只截断不舍入用 trunc；明确向下/向上取整用 floor / ceil。

Q：温度换算为什么和别处差 1 度？ 温度换算涉及偏移量（如摄氏/华氏），请确认使用的换算口径；插件按标准公式计算。

Q：能算汇率吗？ 不能，需要联网汇率源，属 v0.3 规划。

版本说明

当前版本：0.1.0（首个版本）

• calculate：基础四则运算与括号表达式求值
• 科学计算：三角函数（弧度制）等
• 单位换算与中文结果输出，参数经类型转换与校验

License

MIT