Introduction¶

Everyone writing Agents faces a common problem: the model’s reasoning is fine, but when asked to calculate 1/3 + 1/6, it might directly give 0.5 or 0.3333333333333333. It is even more troublesome in finance and engineering scenarios. Once amounts, tax rates, compound interest, or unit conversions are silently rounded, errors propagate into quotes and reports unnoticed.

Existing approaches usually follow one of two paths: let the model calculate mentally, or provide it with a Python code executor. The former inevitably carries rounding risks; the latter has the problem that the model must write the code correctly first, and starting the interpreter has overhead every time. Jiheng takes a different approach: it does not perform reasoning, only calculation, and explicitly promises to “either give the exact value or clearly tell you why it cannot” — neither silently rounding nor silently failing.

Jiheng is maintained by CQQOOQ123, with source code on GitHub: https://github.com/CQQOOQ123/jiheng, and the community directory page is https://www.skillhub.cn/plugins/CQQOOQ123/jiheng, categorized under Workflows. It can be connected to clients like Claude Desktop, Cursor, and Codex as an MCP server, or loaded as a DSH plugin. The following sections introduce it in the order: “What is it” → “What can it do” → “How to install” → “How to use” → “Who is it for”.

What is it¶

One-sentence positioning: A precise mathematical execution layer for AI Agents / MCP clients, covering fractions, roots, symbols, statistics, finance, units, and dates. It is not responsible for reading the problem, modeling, or reasoning; that part is still left to the LLM; it only guarantees that “already obtained numbers” are calculated accurately and cleanly.

Two connection forms:

• MCP Server: uvx jiheng-mcp, add a JSON snippet to the client configuration.
• DSH Plugin: @local/jiheng, provides status viewing and strategy configuration in the settings page after loading.

Core Features¶

1. Precise calculation, no silent rounding. 1/3 is kept in fractional form, sqrt(2) in root form, 2^200 is bit-precise. The result text provides both the decimal result and the exact form.

2. Fail-loud error contract. When calculation fails, it returns isError: true with a correctable hint in the text, allowing the model to adjust the expression and retry; it will not return a “seemingly correct wrong number” or guess a unit to pass.

3. 19 capability packs covering a wide range. Statistics, finance, engineering, units, dates, distributions, ODEs, linear algebra, etc. The cost comparison table in the README shows it runs locally, requires no API key, and has a hot latency of about 3ms per call.

4. AI-native interface design. Supports submitting multiple named steps (intermediate variables) in a single call, reducing round trips between the model and the tool; provides functions() to list all functions and help("name") to query a single function signature.

5. Restricted permissions and scope. Does not connect to databases, scrape webpages, read files, save credentials, or initiate network requests. The design intent is to keep the calculator small, auditable, and offline-capable.

Trust indicators, per the original README: 19,000 expression-level acceptance tests, 1,000 comprehensive acceptance tests, and 19 capability packs; there is also a conclusion that a 1,000-question mixed benchmark scored 97.6%, see BENCHMARKS.md in the repository for details.

Installation and Activation¶

DSH Plugin Method¶

plugin_manager install_bundle target="D:\AI\DeepSeek-workplace\创造模式\dsh-calc"
plugin_manager set_bundle target="@local/jiheng" enabled=true

Step 1 installs the bundle content to the specified directory, Step 2 enables @local/jiheng. After loading, calc appears in the tools table, and the configuration page appears at Settings → Calculator. Note that the target path should be replaced with your actual plugin directory; the README example uses a Windows path.

MCP Server Method¶

First install uv (skip if already installed):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

Add to the configuration of clients like Claude Desktop, Cursor, and Codex:

{
  "mcpServers": {
    "jiheng": { "command": "uvx", "args": ["jiheng-mcp"] }
  }
}

The first time uvx is launched, it automatically downloads jiheng-mcp, and subsequent runs use the local cache.

Other installation methods:

If uv pip install jiheng-mcp==x.y.z reports unsatisfiable requirements but the PyPI page already has that version, try uv cache clean jiheng-mcp first; if it still fails, run the full uv cache clean. This is usually because uv has cached an old index locally.

Typical Usage¶

After loading, you can directly give instructions to the model, for example: “Use calc to calculate 1/3 + 1/6” or “Use calc to calculate mean([12,15,9,22])”. You can also refer to the parameter form of the tool call itself.

The tool receives a JSON parameter with only three optional fields:

{
  "expr": "Final expression (can be omitted if steps already give the result)",
  "steps": [{"name": "intermediate variable name", "expr": "sub-expression"}],
  "defs": {"const": {"k": 1.05}, "fn": {"f": {"p": ["x"], "e": "x^2"}}}
}

content[0].text returns a decimal-priority result with the exact form attached; on error, isError: true, and the text contains a correctable hint.

Several example calls from the README:

calc(expr="1/3 + 1/6")                         → 1/2
calc(expr="sqrt(2)*sqrt(2)")                   → 2
calc(expr="mean([12,15,9,22])")                → 14.5
calc(expr="loan_pmt(1000000, 0.049, 20)")      → Monthly payment
calc(expr="black_scholes_call(115,113,1,0.05,0.30)")
calc(expr="npv(0.08, [623,644,431,286], 1)")   → start=1 means first flow at end of year 1
calc(expr="functions()")                       → List all function names
calc(expr="help(\"norm_cdf\")")                → norm_cdf(x, mu, sigma) — Normal cumulative distribution

Submit multiple steps at once to reduce round trips. The example below breaks Black-Scholes down into three steps: d1, d2, and C:

{
  "steps": [
    {"name": "d1", "expr": "(ln(115/113)+(0.05+0.3^2/2)*1)/(0.3*sqrt(1))"},
    {"name": "d2", "expr": "d1-0.3*sqrt(1)"},
    {"name": "C", "expr": "115*norm_cdf(d1)-113*exp(-0.05)*norm_cdf(d2)"}
  ]
}

A common pitfall, specifically noted in the README: N(expr, digits) is numerical evaluation, not the Normal CDF; use norm_cdf(x) for the CDF.

Function coverage by category:

• Operations/Constants: + - * / % ** ^, pi, e
• Statistics: sum mean std std_pop std_sample var_pop var_sample median quantile min max count corr cov regression
• Finance: loan_pmt npv(rate, flows[, start]) annuity_pv discount_factor irr bond_price bond_duration black_scholes_call black_scholes_put irr_all
• Units: unit_convert unit_add unit_mul unit_div unit_pow unit_eval + convert
• Dates: days_between date_add weekday
• Symbols: solve diff integrate simplify expand factor subs limit series taylor
• Engineering: stress strain bending_stress beam_cantilever_point heat_flux thermal_resistance
• Distributions: norm_pdf norm_cdf norm_quantile t_pdf chi2_pdf

For the complete 61+ functions, see AI-USAGE.md in the repository.

Configuration and Strategy¶

Usage Policy. Can be selected in the settings page or written into config.policy in cordis.patch.yml:

The default complex means ordinary arithmetic operations are not forced to use the tool; only professional calculations like amounts, fractions, units, and symbols trigger it, reducing the overhead of the model calling the tool.

Limits. Settings → Calculator → Limits, write to <calcHome>/settings.json, takes effect immediately (default values taken from the README):

Worker Pool. Default 1 persistent process, about 3ms per call. Pools can be enabled for high concurrency or heavy symbolic tasks, configured in cordis.patch.yml:

workers: 1        # 1..maxWorkers, or auto
maxWorkers: 8     # Hard limit 16; each approx 52MB

auto means starting with 1, automatically scaling up to maxWorkers when busy. The settings page can view running/ready status and switch. The external interface has GET/POST /calc/workers and POST /calc/batch (1..200 expressions in parallel); when the worker finishes starting, it sends a {"ready":true} handshake, and after scaling, it waits for all to be ready before returning.

Environment Variables. Common ones: DSH_CALC_PYTHON specifies the worker interpreter (default auto-detect), DSH_CALC_HOME specifies the formula/settings directory (default ./.calc or ~/.calc), DSH_CALC_TIMEOUT_MS single evaluation timeout (default 8000ms). See the README for the full list.

Architecture Level. In DSH Host (Node, persistent), index.js registers two tools: calc / calc_shard, spawning 1..N persistent worker.py processes via JSON line protocol. The evaluation logic is implemented in calc_core.py using an AST whitelist + exact rational numbers (Frac). From a source code perspective, the worker and AST whitelist are worth looking at, as they determine what it can execute and what it rejects.

Suitable Scenarios and Notes¶

Suitable Scenarios:

• Finance and Quant Agents: amounts, compound interest, discounting, option pricing, where floating-point rounding cannot be tolerated.
• Engineering and Data Agents: unit conversion, date spans, column statistics, where definitions must be fixed.
• Scenarios needing “ready-made functions + stable parseable output” without wanting to write Python calling logic into the Agent.
• Local execution, no API key, latency-sensitive scenarios (approx. 3ms/call, no network round trip).

Scenarios that are not suitable, also noted in the README:

• Risch-level symbolic integration, Meijer-G, PDEs — the symbolic depth is “sufficient, not Wolfram-level”; for such needs, use Wolfram/Mathematica (or SymPy).
• Large CSV/DataFrame processing — Jiheng does not read files; data must be retrieved first and then passed to it for calculation.
• Real-time quotes, news, web queries — this is a calculation layer, not a data layer; data must first be fetched by other MCP tools.
• Arbitrary programming tasks — code executors should be used for that.

The division of data pipeline responsibilities is roughly as follows: Database MCP or File MCP retrieves data and returns an array; Jiheng receives the numbers to perform statistical, financial, unit, and date calculations; large table joins/ETL are delegated to DuckDB or code execution; plotting is delegated to the Chart MCP. A typical example from the README is calculating CAGR, mean, and NPV after retrieving 12 months of revenue.

Pre-use check: Jiheng’s DSH plugin runs with the permissions of the current dsh process. Before installing, it is recommended to open the source code to verify the AST whitelist in calc_core.py, the configuration items in cordis.patch.yml, and the repository license (README marks it as MIT, license: "MIT" in package.json, version 0.3.9). The community directory page is an independent site with no official affiliation with DeepSeek / Hyperbolic. The star count in the plugin link is 0, so ecosystem activity needs to be evaluated by yourself.

Conclusion¶

The value of Jiheng is not “another calculator,” but in the boundaries it draws: reasoning is the LLM’s job, precise calculation is Jiheng’s job, connected by a single calc tool, neither letting the model calculate mentally nor making it write code. If your Agent’s output has ever contained “seemingly correct wrong numbers,” spending a few minutes to install a local, API-key-free plugin is likely more cost-effective than continuing to tweak prompts.

• GitHub: https://github.com/CQQOOQ123/jiheng
• Community Directory: https://www.skillhub.cn/plugins/CQQOOQ123/jiheng
• Entry to detailed docs: AI-USAGE.md (function list), PACKS.md (capability packs), QUALITY.md (quality audit), BENCHMARKS.md (benchmarks and limits), llms.txt in the repository