omdsh-dev/dsh-tool-calculator

dsh-tool-calculator

English

DSH 计算器工具插件 —— 安全的数学表达式求值器。零依赖、零进程、纯函数。

动机

Agent 做算术不稳定是 LLM 的通病。DSH 内置的 bash 工具可以调用 echo $((15 + 27 * 3)) 完成计算，但有两个问题：

1. 每次算术都起一个 bash 进程——Windows 上尤其昂贵（创建进程、加载 shell、执行、收集输出），高频调用时累积延迟显著
2. bash 算术语法有限——不支持 sqrt、sin、cos、log、pow 等数学函数，agent 在这些场景下只能猜答案或写脚本

本插件提供零依赖、零进程、纯函数的计算器——一次函数调用，毫秒级得出结果，覆盖常用初等数学函数。

安全模型

无 eval、无 new Function。 使用手写递归下降解析器（词法层 + 语法层），只求值白名单节点：

• 词法层只识别数字字面量、白名单标识符、运算符；引号、分号、反引号、{} [] 直接报错
• 标识符按名查白名单表（15 个函数 + 2 个常量），查不到即抛 Unknown identifier
• 求值结果必须是有限数字，NaN/Infinity（除零、负数开方等）统一拒绝

new Function + 正则白名单是不安全的——constructor.constructor(...) 可直达 Function 构造器执行任意代码，process.exit(0) 可直接杀死宿主进程（均已实测复现）。本实现不使用任何代码求值捷径。

架构

┌──────────────────────────────┐
│         DSH Agent             │
│  tool call: calculator { ... }│
└──────────┬───────────────────┘
           │ ctx.tools.register()
┌──────────▼───────────────────┐
│     src/index.ts             │
│     Cordis 插件入口           │
└──────────┬───────────────────┘
           │
┌──────────▼───────────────────┐
│     src/evaluate.ts          │
│     tokenize() → parse()     │
│     递归下降解析器            │
└──────────────────────────────┘

• src/index.ts：Cordis 插件入口（name/inject/apply），注册 calculator 工具
• src/evaluate.ts：evaluate(expression: unknown): number——入口独立校验类型（非字符串抛 calculator: expression must be a string），返回有限数字，非法输入全部抛错

工具声明

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import { evaluate } from './evaluate.ts'

export const name = '@deepseek-ai/dsh-tool-calculator'
export const inject = ['tools']

export function apply(ctx: Context): void {
  ctx.tools.register(defineTool({
    name: 'calculator',
    description:
      'Evaluate a mathematical expression safely. ' +
      'Supports +, -, *, /, %, **, parentheses, and functions: ' +
      'abs, ceil, floor, round, max, min, sqrt, pow, log, log2, log10, exp, sin, cos, tan, PI, E.',
    parameters: {
      expression: {
        type: 'string',
        required: true,
        description: 'Mathematical expression, e.g. "15 + 27 * sqrt(9)"',
      },
    },
    output: {
      schema: { type: 'number' },
      render: (_args, value) => [{ type: 'text', text: String(value) }],
    },
    execute: async (args) => evaluate(args.expression),
    timeoutMs: 1000,
  }))
}