Preface¶

DeepSeek Harness (command name dsh) is an agent runtime open-sourced by DeepSeek AI. The official repository summarizes its architecture in one sentence: Everything is a plugin. Models, tools, skills, sessions, sandboxes, and interfaces can all be combined or replaced on the Cordis kernel. There is also a separate community plugin directory site deepseek-harness-plugin.com in the community, which has no official affiliation with DeepSeek / Fangfang. It hosts community repositories, so do not treat it as an official app store.

LLMs are not reliable at arithmetic. Asking a model to mentally calculate 15 + 27 * sqrt(9) will occasionally lead to wrong operator precedence, or even just a random guess. The built-in bash tool in DSH can run echo $((15 + 27 * 3)), but the repository README points out two limitations: a new bash process must be spawned for each calculation, which is especially costly on Windows; bash arithmetic also does not support functions like sqrt, sin, log, pow, so the model has to guess again or temporarily write a script.

dsh-tool-calculator takes a different approach: it registers a calculator tool within the process, uses a handwritten recursive descent parser to evaluate expressions, and does not use eval, new Function, or spawn child processes. This article is collated after cross-checking with the community directory page, the README / package.json / src/evaluate.ts / test cases of the plugin’s GitHub repository, and the official DeepSeek Harness repository.

What is this¶

dsh-tool-calculator is a Tool & Capability type DSH plugin maintained by the GitHub organization omdsh-dev, with the repository address at omdsh-dev/dsh-tool-calculator. The directory page describes it in one sentence: a secure mathematical expression evaluator with zero dependencies, recursive descent parsing, and no arbitrary code execution. The README adds three constraints: zero dependencies, zero processes, pure function.

Both the directory page and the GitHub repository currently show 6 stars. The license is MIT (the LICENSE file’s copyright line reads Copyright (c) 2026 whiteicey), and the primary language is TypeScript. The directory page marks the inclusion date as 2026-08-03, and the latest push time is 2026-08-14. The package name in package.json is @deepseek-ai/dsh-tool-calculator, version 0.0.1, with private set to true; peer dependencies point to @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-tools, and @deepseek-ai/dsh-invariants. The README states that it has been migrated and verified to the profile / bundle plugin system of DSH 0.1.0-rc.6 (npm).

The problem it solves is very specific: extracting the task of “calculating a definite number” from mental arithmetic and bash arithmetic into a single tool call. The entry point is evaluate(expression: unknown): number. Non-string inputs will directly throw calculator: expression must be a string, and the evaluation result must be a finite number; any NaN / Infinity (caused by division by zero, square root of negative numbers, etc.) will be rejected.

Core Features¶

The plugin calls ctx.tools.register() in the Cordis entry src/index.ts to register a tool named calculator. The tool has only one required parameter expression (string), with a timeout of 1000 milliseconds, and the canonical return value is a number. The example given in the README is:

calculator { expression: "15 + 27 * sqrt(9)" }  →  96

After registration, it will enter the Code Mode SDK and can be written as await tools.calculator(...). The tool name complies with DeepSeek’s function name constraints: no more than 64 characters, and the character set is [A-Za-z0-9_-].

Supported operations are based on the README and the whitelist in src/evaluate.ts:

The operator precedence is: ** (right-associative) > unary ± > * / % > + -. There are 15 functions and 2 constants in total for functions and constants. Identifiers are looked up against the whitelist by name, and any unrecognized identifier will throw Unknown identifier. max / min support variable arguments; other functions have fixed arity contracts. For example, sqrt(9, 1), pow(2), and abs() will all be rejected due to incorrect argument counts.

The security model is what this plugin truly emphasizes. The parser’s tokenization and syntax layers do not use eval or new Function. The tokenization layer only recognizes numeric literals, identifiers, and operators; quotes, semicolons, backticks, {} [] will directly trigger an error. Evaluation only goes through whitelisted nodes, and the whitelist is checked with Object.hasOwn to avoid inherited properties like constructor / toString / __proto__ from the Object.prototype. The maximum expression length is 500 characters. The repository’s tests/evaluate.spec.ts includes both functional test cases and rejection test cases for constructor escape, process global, globalThis, quote injection, semicolon statements, and other malicious inputs.

There are no third-party runtime dependencies: devDependencies in package.json only include TypeScript, Vitest, and @types/node, and the evaluation function itself does not make network requests or spawn child processes.

Installation and Activation¶

The installation command given on the community directory page can be run in the DeepSeek Harness terminal:

dsh plugin add github:omdsh-dev/dsh-tool-calculator

The dsh CLI will pull the plugin from GitHub and add it to the current configuration. For reproducible installations, the directory page recommends pinning the commit hash:

dsh plugin add github:omdsh-dev/dsh-tool-calculator#commit

Replace #commit with the actual commit hash. The repository README also adds the profile-based installation method for DSH 0.1.0-rc.6’s profile bundle. There are two different profiles: web and headless. Installing to the web profile will not automatically overwrite the headless profile, and dsh run defaults to headless.

# Interactive (web) profile
dsh plugin --profile web add github:omdsh-dev/dsh-tool-calculator

# One-off task (headless) profile
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-calculator

You can also first run npm pack and then install from a local tarball:

git clone https://github.com/omdsh-dev/dsh-tool-calculator
cd dsh-tool-calculator
npm install && npm pack
dsh plugin --profile web add ./deepseek-ai-dsh-tool-calculator-*.tgz
dsh plugin --profile headless add ./deepseek-ai-dsh-tool-calculator-*.tgz

The dsh.bundle in the package points to cordis.patch.yml. After installation, the tool-calculator entry will be inserted into the profile’s layer stack in the form of - insert:. The README specifically reminds: the patch for DSH 0.1.0-rc.6 is positioned by id, and writing - id: directly will throw entry not found; you must wrap it in a - insert: list. Use forward slashes for Windows paths, e.g. C:/....

Verify the installation:

dsh --profile web --dump-config | grep tool-calculator

The Node engine declared in package.json is ^22.19.0 || >=24.0.0. The README recommends starting with npx -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web (lib production mode), and do not use npm install -g for global installation.

Both the directory page and the README include the same security warning: The plugin runs with the permissions of the current dsh process, and code may be executed during installation. You should inspect the source code repository and license before installing.

Typical Usage¶

After installation, the agent will automatically gain access to the calculator tool, and no additional switches are generally needed. The run verification command given by the repository is:

dsh run "Use the calculator tool to calculate 1+2*3"

According to operator precedence, the result of this expression should be 7. Let’s look at the complete example in the README:

15 + 27 * sqrt(9)

First calculate sqrt(9) = 3, then 27 * 3 = 81, and finally 15 + 81 = 96. Parentheses change the order of operations: the test case (2 + 3) * 4 returns 20, while 2 + 3 * 4 returns 14. Exponentiation is right-associative, so 2 ** 3 ** 2 equals 512, not 64.

For trigonometric functions that need to use degrees, the repository states that the interface is consistent with Math.sin / Math.cos, which use radians. For example, 30 degrees should be written as:

sin(30 * PI / 180)

Run tests locally:

pnpm test

The corresponding script in package.json is vitest run tests, or you can use npm test. Currently, the test files include tests/evaluate.spec.ts (evaluation and rejection test cases) and tests/register.spec.ts (tool registration).

Applicable Scenarios and Notes¶

This plugin is suitable for the following use cases: coding agents need a definite arithmetic result instead of letting the model calculate mentally; expressions contain sqrt, log, pow or trigonometric functions that bash arithmetic cannot handle; you want calculations to happen within the current process instead of spawning a shell for a simple addition or subtraction. omdsh-dev also maintains a collection repository dsh-toolkit, which also includes a calculator tool with the same name; if you only need a calculator, you can install this standalone plugin.

There are several boundaries already written into the README and source code, do not treat them as “hidden capabilities” other than defects:
1. Does not support scientific notation. 1e5, 1e-5, 6.02e23 will be rejected by the tokenization layer, with the error message Scientific notation is not supported.
2. Does not support big integers. Evaluation uses JavaScript’s IEEE 754 double-precision floating point, with a safe integer range of approximately ±9e15, and precision loss will occur beyond this range.
3. Trigonometric functions use radians. Convert degrees to radians yourself by multiplying by PI / 180.
4. The result must be a finite number. When NaN or Infinity is obtained due to division by zero, square root of negative numbers, etc., the interface will throw an error instead of returning the special value to the model.
5. Maximum expression length is 500 characters. Ultra-long inputs will be directly rejected.

DeepSeek Harness is currently in developer preview, and the official README states that there will be breaking changes. This plugin adapts to the bundle / patch semantics of 0.1.0-rc.6 according to the README, please check the repository’s version adaptation notes before switching versions. The community directory is not an official app store, please use the installation command from the directory page: dsh plugin add github:omdsh-dev/dsh-tool-calculator.

One final reminder: the plugin runs in the current dsh process with the same permissions as the host. Even though this plugin’s evaluation path deliberately avoids eval / new Function, the installation action itself may still execute code from the repository. Read the source code and MIT license before installing, and pin the commit hash when you need a reproducible environment.

Conclusion¶

dsh-tool-calculator packages a very simple but often miscalculated task into a tool: safely evaluate mathematical expressions within the DSH process. It does not replace bash, nor does it expand into a general-purpose script engine; the whitelist, finite number requirement, and 500-character limit are all designed to make the task of “calculating a number” predictable.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-tool-calculator/

GitHub: https://github.com/omdsh-dev/dsh-tool-calculator