前言¶

寫 Agent 的人都會遇到一類問題：模型推理沒問題，但讓它算 1/3 + 1/6，它可能直接給 0.5，也可能給 0.3333333333333333。更麻煩的是金融和工程場景，金額、稅率、複利、單位換算一旦被靜默舍入，錯誤會一路傳進報價和報表，而且沒人發現。

已有做法通常是兩條路：讓模型自己心算，或者給它一個 Python 代碼執行器。前者必然有舍入風險；後者的問題是模型必須先寫對代碼，且每次啓動解釋器都有開銷。璣衡 Jiheng 的做法不同：它不做推理，只做計算，而且明確承諾「要麼給出精確值，要麼明確告訴你爲什麼給不了」——既不靜默舍入，也不靜默失敗。

Jiheng 由 CQQOOQ123 維護，源碼在 GitHub：https://github.com/CQQOOQ123/jiheng ，社區目錄頁是 https://www.skillhub.cn/plugins/CQQOOQ123/jiheng ，分類爲工作流。它既可以作爲 MCP 服務器接入 Claude Desktop、Cursor、Codex 等客戶端，也可以作爲 DSH 插件裝載。下面按「是什麼 → 能做什麼 → 怎麼裝 → 怎麼用 → 適合誰」的順序介紹。

這是什麼¶

一句話定位：給 AI Agent / MCP 客戶端使用的精確數學執行層，覆蓋分數、根號、符號、統計、金融、單位、日期。它不負責讀題、建模、推理，那部分仍然交給 LLM；它只保證「已經拿到的數字」算得準、算得乾淨。

兩個接入形態：

• MCP 服務器：uvx jiheng-mcp，在客戶端配置里加一段 JSON 即可。
• DSH 插件：@local/jiheng，裝載後在設置頁提供狀態查看與策略配置。

核心功能¶

1、精確計算，不靜默舍入。 1/3 保留分數形式，sqrt(2) 保留根號，2^200 逐位精確。結果文本里十進制結果與精確形式同時給出。

2、fail-loud 錯誤契約。 計算失敗時返回 isError: true，文本中包含可修正的提示，讓模型能自己調整表達式重試；不會返回「看起來對的錯數」或猜一個單位矇混過去。

3、19 個能力包，覆蓋面較廣。 統計、金融、工程、單位、日期、分佈、ODE、線代等。README 給出的代價對比表顯示，它在本地運行、無需 API key、熱延遲約 3ms/次。

4、AI 原生接口設計。 支持一次調用提交多個命名 steps（中間變量），減少模型與工具之間的往返；提供 functions() 列出全部函數、help("name") 查詢單個函數簽名。

5、權限與範圍剋制。 不連接數據庫、不抓網頁、不讀文件、不保存憑據、不發起網絡請求。設計意圖是讓計算器保持小、可審計、可離線。

可信度指標按 README 原文：19,000 條表達式級驗收、1,000 條綜合驗收、19 個能力包；另有 1000 題混合基準得分 97.6% 的結論，詳見倉庫內 BENCHMARKS.md。

安裝與啓用¶

DSH 插件方式¶

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

第一步把 bundle 內容安裝到指定目錄，第二步啓用 @local/jiheng。裝載後工具表出現 calc，設置 → 計算器 出現配置頁。注意 target 路徑替換爲你實際的插件目錄，README 示例用的是 Windows 路徑。

MCP 服務器方式¶

先裝 uv（已裝可跳過）：

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

在 Claude Desktop、Cursor、Codex 等客戶端的配置里加入：

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

首次啓動 uvx 會自動下載 jiheng-mcp，之後走本地緩存。

其他安裝方式：

如果 uv pip install jiheng-mcp==x.y.z 報 unsatisfiable 但 PyPI 頁面已有該版本，先執行 uv cache clean jiheng-mcp 再試；仍失敗則執行完整 uv cache clean，通常是 uv 本地緩存了舊索引。

典型用法¶

裝載後直接給模型下指令即可，例如：「用 calc 算 1/3 + 1/6」「用 calc 算 mean([12,15,9,22])」。也可以看工具調用本身的參數形式。

工具接收一個 JSON 參數，只有三個可選字段：

{
  "expr": "最終表達式（可省略，若 steps 已給出結果）",
  "steps": [{"name": "中間變量名", "expr": "子表達式"}],
  "defs": {"const": {"k": 1.05}, "fn": {"f": {"p": ["x"], "e": "x^2"}}}
}

返回 content[0].text 爲十進制優先結果並附精確形式；出錯時 isError: true，文本含可修正提示。

幾個來自 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)")      → 月供
calc(expr="black_scholes_call(115,113,1,0.05,0.30)")
calc(expr="npv(0.08, [623,644,431,286], 1)")   → start=1 表示首筆第 1 年末
calc(expr="functions()")                       → 全部函數名
calc(expr="help(\"norm_cdf\")")                → norm_cdf(x, mu, sigma) — 正態累積分佈

多步一次提交，減少往返。下面這個例子把 Black-Scholes 拆成 d1、d2、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)"}
  ]
}

一個容易踩的坑，README 專門標註過：N(expr, digits) 是數值求值，不是正態 CDF；CDF 要用 norm_cdf(x)。

函數覆蓋面按類別列一句：

• 運算/常量：+ - * / % ** ^、pi、e
• 統計：sum mean std std_pop std_sample var_pop var_sample median quantile min max count corr cov regression
• 金融：loan_pmt npv(rate, flows[, start]) annuity_pv discount_factor irr bond_price bond_duration black_scholes_call black_scholes_put irr_all
• 單位：unit_convert unit_add unit_mul unit_div unit_pow unit_eval + convert
• 日期：days_between date_add weekday
• 符號：solve diff integrate simplify expand factor subs limit series taylor
• 工程：stress strain bending_stress beam_cantilever_point heat_flux thermal_resistance
• 分佈：norm_pdf norm_cdf norm_quantile t_pdf chi2_pdf

完整 61+ 函數見倉庫 AI-USAGE.md。

配置與策略¶

使用策略（policy）。 可在設置頁選，也可寫進 cordis.patch.yml 的 config.policy：

默認 complex 意味着普通四則運算不會強制走工具，只在金額、分數、單位、符號這類專業計算上插入，減少模型調用工具的開銷。

限額。 設置 → 計算器 → 限額，寫入 <calcHome>/settings.json，立即生效（默認值取自 README）：

Worker 池。 默認 1 個常駐進程，單次約 3ms。高併發或重符號任務可以開池，仍在 cordis.patch.yml 裏配置：

workers: 1        # 1..maxWorkers，或 auto
maxWorkers: 8     # 硬上限 16；每個約 52MB

auto 表示起始 1 個，忙時自動擴到 maxWorkers。設置頁可查看運行中/就緒狀態並切換。對外接口有 GET/POST /calc/workers 和 POST /calc/batch（1..200 條表達式並行）；worker 啓動完成會發 {"ready":true} 握手，擴容後等全部就緒再返回。

環境變量。 常用幾項：DSH_CALC_PYTHON 指定 worker 解釋器（默認自動探測），DSH_CALC_HOME 指定公式/設置目錄（默認 ./.calc 或 ~/.calc），DSH_CALC_TIMEOUT_MS 單次求值超時（默認 8000ms）。完整列表見 README。

架構層面。 DSH Host（Node，常駐）裏的 index.js 註冊 calc / calc_shard 兩個工具，通過 JSON 行協議 spawn 1..N 個 worker.py 常駐進程，求值邏輯在 calc_core.py 裏做 AST 白名單 + 精確有理數（Frac）。源碼層面值得看一眼的是 worker 與 AST 白名單，這決定了它能執行什麼、拒絕什麼。

適用場景與注意¶

適合的場景：

• 金融、量化類 Agent：金額、複利、折現、期權定價，不能容忍浮點舍入。
• 工程和數據類 Agent：單位換算、日期跨度、列統計，口徑要固定。
• 需要「現成函數 + 穩定可解析輸出」而不想把 Python 調用邏輯寫進 Agent 裏的場景。
• 本地運行、無 API key、延遲敏感的場景（約 3ms/次，無網絡往返）。

不太適合的場景，README 也寫明瞭：

• Risch 級符號積分、Meijer-G、PDE——符號深度是「夠用，非 Wolfram 級」，這類需求用 Wolfram / Mathematica（或 SymPy）。
• 大型 CSV / DataFrame 處理——Jiheng 不讀文件，先取數據再交給它算。
• 實時行情、新聞、網頁查詢——這是計算層不是數據層，需要先由別的 MCP 工具取數。
• 任意編程任務——那該用代碼解釋器。

數據鏈路的分工大致是這樣：數據庫 MCP 或文件 MCP 取數返回數組，Jiheng 接收數字做統計、金融、單位、日期計算，大表 join / ETL 交給 DuckDB 或代碼執行，畫圖交給圖表 MCP。README 給出的典型例子是取 12 個月營收後算 CAGR、mean、NPV。

使用前的檢查： Jiheng 的 DSH 插件以當前 dsh 進程權限運行，安裝前建議打開源碼覈對 calc_core.py 的 AST 白名單、cordis.patch.yml 的配置項，以及倉庫許可證（README 標註爲 MIT，package.json 中 license: "MIT"，版本 0.3.9）。社區目錄頁本身是獨立站點，與 DeepSeek / 幻方無官方從屬關係。插件線索中的星標數爲 0，生態活躍度需要自己評估。

結尾¶

Jiheng 的價值不在「又一個計算器」，而在它劃清了界線：推理是 LLM 的事，精確計算是它的事，兩者用一個 calc 工具銜接，既不讓模型心算、也不讓它寫代碼。如果你的 Agent 輸出裏出現過「看起來對的錯數」，花幾分鐘裝一個本地運行、無需 API key 的插件，大概率比繼續調提示詞划算。

• GitHub：https://github.com/CQQOOQ123/jiheng
• 社區目錄頁：https://www.skillhub.cn/plugins/CQQOOQ123/jiheng
• 詳細文檔入口：倉庫內 AI-USAGE.md（函數清單）、PACKS.md（能力包）、QUALITY.md（質量審計）、BENCHMARKS.md（基準與限制）、llms.txt