dsh-calc-tool 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yhy854
+
+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.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# dsh-calc-tool · DSH 精准计算器插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**专治大模型「算术脑补」与「心算翻车」！给 DeepSeek Harness 的 Agent 配一把零误差、高安全的硬核计算器。**
+
+用大模型处理账单、配比、数据统计或代码参数时，最怕什么？
+
+- **一本正经地算错**：模型靠概率「猜」出个看似合理的错数，混在报告里坑惨你。
+- **思维链里疯狂烧钱**：为了算对一道四则运算，模型在 Thinking 里来回列竖式、反复自我怀疑，白白烧掉几百上千个推理 Token。
+
+装上 `dsh-calc-tool` 后，模型遇到算术直接调 `calc` 工具，一步到位拿精确结果——既不会算错出幻觉，也不会在思维链里死磕心算浪费你的钱和时间！
+
+## ⚡ 超级便捷，三步一键安装
+
+不用折腾繁琐配置，直接用 DeepSeek Harness 官方插件面板三步搞定：
+
+1. 打开 DeepSeek Harness 桌面端，点击左侧边栏的 **「插件」** 按钮；
+2. 点击右上角 **「添加插件」**；
+3. 填入下面任意一行，点击安装即可。
+
+**npm 包名：**
+
+```
+dsh-calc-tool
+```
+
+**GitHub 地址：**
+
+```
+https://github.com/yhy854/dsh-calc-tool
+```
+
+装完按面板提示重启，**新开一个会话**让它算个数试试。
+
+💡 **随开随关，丝滑掌控**：完全接入 DSH 官方插件管理，装好开启即用；平时想用就开，不需要时在插件面板随手一点就能关闭，干净利落。
+
+## 效果与用法
+
+安装后 Agent 自动解锁 `calc` 工具，遇到计算自动调用：
+
+```
+calc { expression: "1280 * 0.85 + 42.5" }  →  1130.5
+calc { expression: "15 + 27 * sqrt(9)" }   →  96
+```
+
+## 支持的计算能力
+
+| 类别 | 支持内容 |
+|---|---|
+| 基础算术 | `+` `-` `*` `/` `%` `//`（整除）`**`（幂运算，右结合） |
+| 数学函数 | `abs` `ceil` `floor` `round` `trunc` `sign` `sqrt` `cbrt` `exp` `log` `log2` `log10` `sin` `cos` `tan` `asin` `acos` `atan` `pow` `hypot` `max` `min` |
+| 常用常量 | `PI`、`E` |
+| 语法特性 | 括号优先级、一元正负号、科学计数法（如 `1.5e3`） |
+
+**角度与弧度**：三角函数默认使用弧度；算角度只需写 `sin(30 * PI / 180)`。
+
+**运算优先级**：`**`（右结合） > 一元 `±` > `* / % //` > `+ -`。
+
+## 为什么比市面上随便写的计算器安全得多？
+
+很多简陋的计算器插件直接用 `eval()` 或 `new Function()` 配合正则过滤——这是巨大的安全漏洞！攻击者（或被提示词注入的模型）只需构造 `constructor.constructor("return process")()` 就能直接突破沙箱执行任意系统命令。
+
+本插件采用纯手写词法分析 + 递归下降解析器，彻底实现零代码执行风险：
+
+- **0 eval、0 new Function**：绝不走任何 JS 动态代码求值捷径。
+- **严格语法白名单**：词法层只认数字、白名单函数/常量、运算符、括号和逗号；遇到引号、分号、反引号、`{}`、`[]` 直接报错拦截，绝不搞「清洗后勉强执行」。
+- **防原型链污染（已通过回归测试锁死）**：白名单字典使用 `Object.create(null)` 创建（彻底剥离原型链），查表强制使用 `Object.hasOwn` 而非 `in` 运算符——防止 `__proto__`、`constructor`、`toString` 蒙混过关（早期版本曾用 `in` 被测试套件抓出漏洞，现已彻底焊死并配有 7 条专项回归测试）。
+- **防卡死护栏**：表达式上限 4096 字符、括号嵌套上限 64 层、函数参数上限 32 个，结果非有限数字（`NaN` / `Infinity`）一律拒绝。
+
+## 友好的结构化报错（帮模型秒纠错，不瞎重试）
+
+算式写错时，插件会返回清晰的错误码和位置，模型看一眼就能自己改对，不会卡在死循环里盲目重试：
+
+| 错误码 | 含义 |
+|---|---|
+| `CALC_PARSE_ERROR` | 语法错误（精准附带出错字符位置） |
+| `CALC_UNKNOWN_IDENTIFIER` | 调用了白名单之外的函数或变量名 |
+| `CALC_DIVIDE_BY_ZERO` | 除数为 0 |
+| `CALC_NOT_FINITE` | 结果溢出或对负数开偶次方 |
+| `CALC_LIMIT_EXCEEDED` | 超出长度 / 嵌套深度 / 参数个数上限 |
+| `CALC_BAD_ARGUMENT` | 传入参数类型或数量错误 |
+
+## 已知边界（实话实说）
+
+1. **IEEE 754 双精度浮点特性**：遵循 JavaScript 标准双精度浮点，`0.1 + 0.2` 会得出 `0.30000000000000004`。需要保留固定小数位时请配合 `round()` 或自行四舍五入。
+2. **安全整数范围**：±9e15（即 `Number.MAX_SAFE_INTEGER`），超大整数超出此范围会有精度损失。
+3. **定位纯粹**：专注于数值计算，不支持符号代数、矩阵运算或解方程。
+
+## 测试覆盖
+
+运行测试：
+
+```bash
+node test/evaluate.test.mjs
+```
+
+内置 43 条严苛测试用例，全量覆盖：
+
+- 数值正确性与运算符优先级（16 条）
+- 恶意攻击载荷拦截：`constructor.constructor` 链、`process.exit`、`globalThis`、`require`、模板字符串、分号注入、括号注入（16 条）
+- 原型链污染回归测试：`__proto__`、`constructor`、`toString`、`valueOf`、`hasOwnProperty`（7 条）
+- 资源上限守卫：超深括号嵌套、超长表达式轰炸（2 条）
+- 参数异常校验（2 条）
+
+## 兼容性
+
+| DSH 内核 | 状态 |
+|---|---|
+| `0.2.x` | 完美兼容（`peerDependencies` 写 `>=0.2.0-0`，覆盖 rc 预发布版） |
+
+> ⚠️ `peerDependencies` 范围请保持 `>=0.2.0-0` 不要乱改。写成 `^0.1.x` 会展开成 `<0.2.0-0` 从而把 `0.2.0-rc.1` 排除掉，导致 DSH 预检静默禁用插件。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-calc-tool
+      name: 'dsh-calc-tool'

package/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect x="8" y="4" width="48" height="56" rx="8" fill="#1F2937"/>
+  <rect x="14" y="10" width="36" height="14" rx="3" fill="#A7F3D0"/>
+  <g fill="#F9FAFB">
+    <rect x="14" y="30" width="10" height="10" rx="2"/>
+    <rect x="27" y="30" width="10" height="10" rx="2"/>
+    <rect x="40" y="30" width="10" height="10" rx="2"/>
+    <rect x="14" y="44" width="10" height="10" rx="2"/>
+    <rect x="27" y="44" width="10" height="10" rx="2"/>
+  </g>
+  <rect x="40" y="44" width="10" height="10" rx="2" fill="#34D399"/>
+</svg>

package/index.js

@@ -0,0 +1,44 @@
+import { evaluate, CalcError } from './lib/evaluate.js'
+
+export const name = 'dsh-calc-tool'
+export const inject = ['tools']
+
+const DESCRIPTION = [
+  'Evaluate a mathematical expression exactly and return a finite number.',
+  'CRITICAL RULE: NEVER do arithmetic or math calculations mentally! Mental math is prone to hallucination and wastes reasoning tokens—ALWAYS call this tool for any calculation beyond trivial single-digit addition.',
+  'Supports + - * / % // (integer division) ** (power, right-associative), parentheses, unary +/-.',
+  'Functions: abs ceil floor round trunc sign sqrt cbrt exp log log2 log10 sin cos tan asin acos atan pow hypot max min.',
+  'Constants: PI E. Trigonometry uses radians; for degrees write sin(30 * PI / 180).',
+].join(' ')
+
+export function apply(ctx) {
+  ctx.effect(() =>
+    ctx.tools.register({
+      name: 'calc',
+      description: DESCRIPTION,
+      parameters: {
+        expression: {
+          type: 'string',
+          required: true,
+          description: 'Mathematical expression, e.g. "15 + 27 * sqrt(9)" or "1280 * 0.85"',
+        },
+      },
+      output: {
+        schema: { type: 'number' },
+        render: (args, value) => [{ type: 'text', text: `${args.expression} = ${value}` }],
+      },
+      async execute(args) {
+        try {
+          return evaluate(args.expression)
+        } catch (error) {
+          if (error instanceof CalcError) {
+            throw new Error(`${error.code}: ${error.message}`)
+          }
+          throw error
+        }
+      },
+      isConcurrencySafe: () => true,
+      timeoutMs: 1000,
+    }),
+  )
+}

package/lib/evaluate.js

@@ -0,0 +1,312 @@
+/**
+ * 安全数学表达式求值器。
+ * 无 eval / 无 new Function / 无 Proxy。手写词法 + 递归下降。
+ * 白名单标识符查表，表外即抛错。
+ */
+
+export class CalcError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'CalcError'
+    this.code = code
+  }
+}
+
+const FUNCS = Object.assign(Object.create(null), {
+  abs: Math.abs,
+  ceil: Math.ceil,
+  floor: Math.floor,
+  round: Math.round,
+  trunc: Math.trunc,
+  sign: Math.sign,
+  sqrt: Math.sqrt,
+  cbrt: Math.cbrt,
+  exp: Math.exp,
+  log: Math.log,
+  log2: Math.log2,
+  log10: Math.log10,
+  sin: Math.sin,
+  cos: Math.cos,
+  tan: Math.tan,
+  asin: Math.asin,
+  acos: Math.acos,
+  atan: Math.atan,
+  pow: Math.pow,
+  hypot: Math.hypot,
+  max: Math.max,
+  min: Math.min,
+})
+
+const CONSTS = Object.assign(Object.create(null), { PI: Math.PI, E: Math.E })
+const MULTI = ['**', '//']
+
+const MAX_LENGTH = 4096
+const MAX_DEPTH = 64
+const MAX_ARGS = 32
+
+function tokenize(src) {
+  const tokens = []
+  let i = 0
+  let parenDepth = 0
+
+  while (i < src.length) {
+    const c = src[i]
+
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      i += 1
+      continue
+    }
+
+    if (c >= '0' && c <= '9') {
+      let j = i
+      while (j < src.length && src[j] >= '0' && src[j] <= '9') j += 1
+      if (src[j] === '.') {
+        j += 1
+        while (j < src.length && src[j] >= '0' && src[j] <= '9') j += 1
+      }
+      if (src[j] === 'e' || src[j] === 'E') {
+        let k = j + 1
+        if (src[k] === '+' || src[k] === '-') k += 1
+        if (src[k] >= '0' && src[k] <= '9') {
+          while (k < src.length && src[k] >= '0' && src[k] <= '9') k += 1
+          j = k
+        }
+      }
+      const text = src.slice(i, j)
+      const value = Number(text)
+      if (!Number.isFinite(value)) {
+        throw new CalcError('CALC_PARSE_ERROR', `无法解析的数字: ${text}`)
+      }
+      tokens.push({ t: 'num', v: value })
+      i = j
+      continue
+    }
+
+    if (/[A-Za-z_]/.test(c)) {
+      let j = i
+      while (j < src.length && /[A-Za-z0-9_]/.test(src[j])) j += 1
+      const text = src.slice(i, j)
+      // 必须用 own-property 判定。`text in FUNCS` 会把 __proto__ / constructor /
+      // toString 这类继承来的成员误判为合法标识符（原型污染）。
+      if (!Object.hasOwn(FUNCS, text) && !Object.hasOwn(CONSTS, text)) {
+        throw new CalcError(
+          'CALC_UNKNOWN_IDENTIFIER',
+          `未知标识符: ${text}。可用函数: ${Object.keys(FUNCS).join(', ')}；可用常量: ${Object.keys(CONSTS).join(', ')}`,
+        )
+      }
+      tokens.push({ t: 'id', v: text })
+      i = j
+      continue
+    }
+
+    const two = src.slice(i, i + 2)
+    if (MULTI.includes(two)) {
+      tokens.push({ t: 'op', v: two })
+      i += 2
+      continue
+    }
+
+    if ('+-*/%(),'.includes(c)) {
+      if (c === '(') {
+        parenDepth += 1
+        if (parenDepth > MAX_DEPTH) {
+          throw new CalcError('CALC_LIMIT_EXCEEDED', `括号嵌套超过 ${MAX_DEPTH} 层`)
+        }
+      } else if (c === ')') {
+        parenDepth -= 1
+      }
+      tokens.push({ t: 'op', v: c })
+      i += 1
+      continue
+    }
+
+    throw new CalcError('CALC_PARSE_ERROR', `非法字符 "${c}"（位置 ${i}）`)
+  }
+
+  return tokens
+}
+
+function parse(tokens) {
+  let pos = 0
+  let depth = 0
+
+  const peek = () => tokens[pos]
+  const isOp = (v) => peek() !== undefined && peek().t === 'op' && peek().v === v
+
+  function expect(v) {
+    if (!isOp(v)) {
+      const got = peek() === undefined ? '表达式结束' : `"${peek().v}"`
+      throw new CalcError('CALC_PARSE_ERROR', `期望 "${v}"，实际是 ${got}`)
+    }
+    pos += 1
+  }
+
+  function enter() {
+    depth += 1
+    if (depth > MAX_DEPTH) {
+      throw new CalcError('CALC_LIMIT_EXCEEDED', `表达式嵌套超过 ${MAX_DEPTH} 层`)
+    }
+  }
+
+  function additive() {
+    enter()
+    let left = multiplicative()
+    while (isOp('+') || isOp('-')) {
+      const op = tokens[pos].v
+      pos += 1
+      left = { t: 'bin', op, l: left, r: multiplicative() }
+    }
+    depth -= 1
+    return left
+  }
+
+  function multiplicative() {
+    let left = unary()
+    while (isOp('*') || isOp('/') || isOp('%') || isOp('//')) {
+      const op = tokens[pos].v
+      pos += 1
+      left = { t: 'bin', op, l: left, r: unary() }
+    }
+    return left
+  }
+
+  function unary() {
+    if (isOp('-') || isOp('+')) {
+      const op = tokens[pos].v
+      pos += 1
+      return { t: 'un', op, e: unary() }
+    }
+    return power()
+  }
+
+  function power() {
+    const base = primary()
+    if (isOp('**')) {
+      pos += 1
+      return { t: 'bin', op: '**', l: base, r: unary() }
+    }
+    return base
+  }
+
+  function primary() {
+    const tk = peek()
+    if (tk === undefined) {
+      throw new CalcError('CALC_PARSE_ERROR', '表达式意外结束')
+    }
+
+    if (tk.t === 'num') {
+      pos += 1
+      return { t: 'num', v: tk.v }
+    }
+
+    if (tk.t === 'id') {
+      pos += 1
+      if (isOp('(')) {
+        if (!Object.hasOwn(FUNCS, tk.v)) {
+          throw new CalcError('CALC_UNKNOWN_IDENTIFIER', `${tk.v} 不是函数`)
+        }
+        pos += 1
+        const args = []
+        if (!isOp(')')) {
+          args.push(additive())
+          while (isOp(',')) {
+            pos += 1
+            if (args.length >= MAX_ARGS) {
+              throw new CalcError('CALC_LIMIT_EXCEEDED', `参数超过 ${MAX_ARGS} 个`)
+            }
+            args.push(additive())
+          }
+        }
+        expect(')')
+        return { t: 'call', name: tk.v, args }
+      }
+      if (!Object.hasOwn(CONSTS, tk.v)) {
+        throw new CalcError('CALC_UNKNOWN_IDENTIFIER', `${tk.v} 是函数，需要写成 ${tk.v}(...)`)
+      }
+      return { t: 'num', v: CONSTS[tk.v] }
+    }
+
+    if (tk.t === 'op' && tk.v === '(') {
+      pos += 1
+      const inner = additive()
+      expect(')')
+      depth -= 1
+      return inner
+    }
+
+    throw new CalcError('CALC_PARSE_ERROR', `意外的 "${tk.v}"`)
+  }
+
+  if (tokens.length === 0) {
+    throw new CalcError('CALC_PARSE_ERROR', '表达式为空')
+  }
+
+  const ast = additive()
+  if (pos !== tokens.length) {
+    throw new CalcError('CALC_PARSE_ERROR', `"${tokens[pos].v}" 之后存在多余内容`)
+  }
+  return ast
+}
+
+function evalNode(node) {
+  switch (node.t) {
+    case 'num':
+      return node.v
+
+    case 'un':
+      return node.op === '-' ? -evalNode(node.e) : evalNode(node.e)
+
+    case 'bin': {
+      const a = evalNode(node.l)
+      const b = evalNode(node.r)
+      switch (node.op) {
+        case '+': return a + b
+        case '-': return a - b
+        case '*': return a * b
+        case '/':
+          if (b === 0) throw new CalcError('CALC_DIVIDE_BY_ZERO', '除数为 0')
+          return a / b
+        case '//':
+          if (b === 0) throw new CalcError('CALC_DIVIDE_BY_ZERO', '除数为 0')
+          return Math.floor(a / b)
+        case '%':
+          if (b === 0) throw new CalcError('CALC_DIVIDE_BY_ZERO', '取模的除数为 0')
+          return a % b
+        case '**': return a ** b
+        default:
+          throw new CalcError('CALC_PARSE_ERROR', `未知运算符 ${node.op}`)
+      }
+    }
+
+    case 'call': {
+      const fn = FUNCS[node.name]
+      const args = node.args.map(evalNode)
+      return fn(...args)
+    }
+
+    default:
+      throw new CalcError('CALC_PARSE_ERROR', `未知节点 ${node.t}`)
+  }
+}
+
+/** 求值入口：接收 unknown，返回有限数字，非法输入抛 CalcError。 */
+export function evaluate(expression) {
+  if (typeof expression !== 'string') {
+    throw new CalcError('CALC_BAD_ARGUMENT', 'expression 必须是字符串')
+  }
+  const src = expression.trim()
+  if (src.length === 0) {
+    throw new CalcError('CALC_BAD_ARGUMENT', 'expression 不能为空')
+  }
+  if (src.length > MAX_LENGTH) {
+    throw new CalcError('CALC_LIMIT_EXCEEDED', `表达式长度超过 ${MAX_LENGTH} 字符`)
+  }
+
+  const value = evalNode(parse(tokenize(src)))
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new CalcError('CALC_NOT_FINITE', `结果不是有限数字（${String(value)}）`)
+  }
+
+  return value
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Precision Calculator",
+    "description": "Stop LLM arithmetic hallucinations! Gives the agent a deterministic, sandboxed math evaluator that saves reasoning tokens and never guesses numbers."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "精准计算器 (防算术幻觉)",
+    "description": "专治大模型算数翻车！给 Agent 配一把绝对精准的硬核计算器，告别心算瞎猜，省下思维链里反复演算的冤枉 Token。"
+  }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "dsh-calc-tool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "DeepSeek Harness 专属硬核计算器：终结大模型算术脑补与幻觉，0 误差秒出结果，省下反复验算的巨量 Token。",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yhy854/dsh-calc-tool.git"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "lib/*.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "calculator",
+    "math",
+    "计算器",
+    "算术",
+    "防幻觉"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.0-0"
+  },
+  "license": "MIT"
+}