玑衡 Jiheng — 给 AI 的精确数学执行层
English | 中文
[test] [PyPI] [License: MIT]
不是让计算器替 AI 思考，而是让 AI 不必自己心算。
模型擅长推理，却不擅长算术。一个被静默舍入的数字，可能一路传进报价、报表或仓位里。
玑衡只做一件事：要么给出精确值，要么明确告诉你为什么给不了。
这是什么
给 AI Agent / MCP 客户端使用的精确数学执行层：分数、根号、符号、统计、金融、单位、日期。
既可以作为 MCP 服务器，也可以作为 DSH 插件 接入。
给谁用
- 做 AI Agent / MCP 客户端的开发者
- 金融、量化、工程、数据类 Agent
- 需要精确数字、单位、日期、统计口径，不能接受静默舍入的场景
为什么用它
1/3 保留分数，sqrt(2) 保留根号，2^200 逐位精确- 不静默舍入，不猜单位，不返回“看起来对的错数”
- 错误要么明确，要么可行动，让模型能自己修正
- 本地运行，无 API key，毫秒级延迟
快速开始（MCP）
DSH 插件：@local/jiheng，设置页可查看状态与策略。
uv pip install jiheng-mcp==x.y.z 若报 unsatisfiable，但 PyPI 页面已有该版本：
执行 uv cache clean jiheng-mcp 后重试；仍失败则执行完整 uv cache clean。通常是 uv 本地缓存了旧索引。
可信度
- 19,000 表达式级验收
- 1,000 综合验收
- 19 个能力包
- fail-loud 错误契约：不静默失败
- 外部 benchmark 结论见 BENCHMARKS.md
不做什么
- 不负责读题、建模、推理：那是 LLM 的工作
- 不替代 Wolfram 级符号积分 / PDE
- 不抓实时行情、不读大型 CSV：先取数，再计算
详细文档
为什么选 Jiheng
不同工具优化的目标不同。Jiheng 只专注一件事：
给 AI 代理一个快、准、本地、接口干净的精确计算器。
适合用 Jiheng：
- 你在做 AI Agent / MCP 客户端，需要一个可靠的计算器工具
- 需要精确值（金额、分数、根号），不能静默舍入
- 想要一条命令、本地运行、毫秒级延迟
- 需要金融、单位、日期、工程等现成函数，不想写 Python
- 需要稳定可解析的输出，以及模型能自己修正的错误提示
不适合用 Jiheng：
- Risch 级符号积分、Meijer-G、PDE → 用 Wolfram / Mathematica
- 大型 CSV / DataFrame 处理 → 用代码执行 / DuckDB
- 实时行情、新闻、网页查询 → 先取数据，再交给 Jiheng
- 任意编程任务 → 用代码解释器
互操作（Interoperability）
Jiheng 是计算层，不是数据层。它不连接数据库、不抓网页、不读文件，
只负责把“已经拿到的数字”算准。数据获取交给专门的 MCP 工具，两者组合使用：
典型链路：
为什么不在 calc 里内置数据库连接：
- 不保存数据库凭据
- 不暴露 SQL 执行面
- 不发起网络请求
- 计算器保持小、可审计、可离线
如果你需要“只读 SQLite / DuckDB / CSV”，建议用独立的数据工具或 MCP，
把结果数字交给 Jiheng 计算。
快速开始
30 秒上手（MCP）
1. 安装 uv（已装可跳过）
2. 让客户端启动 Jiheng
在 Claude Desktop、Cursor、Codex 等 MCP 客户端配置里加入：
第一次启动时 uvx 会自动下载 jiheng-mcp，之后走本地缓存。
3. 重启客户端，直接提问
其他安装方式
DSH 插件
装载后工具表出现 calc；设置 → 计算器 出现配置页。
直接跑 MCP server（调试用）
工具参数
返回：content[0].text 为十进制优先的结果（附精确形式）；错误时 isError: true，
文本中包含可修正的提示。
工具用法示例
多步一次提交（推荐，减少往返）：
⚠️ 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
- 函数发现：
functions()、help("name")
完整 61+ 函数见 AI-USAGE.md。
配置
使用策略（policy）
设置页可选，或 cordis.patch.yml 的 config.policy：
限额
设置 → 计算器 → 限额（存 <calcHome>/settings.json，立即生效）：
Worker 池
默认 1 个常驻进程（单次约 3ms）；高并发/重符号任务可开池：
auto：起始 1 个，忙时自动扩到 maxWorkers- 设置页可查看 运行中/就绪，切换 1..8 / 自动 / 自定义，保存即生效
- 接口：
GET/POST /calc/workers、POST /calc/batch（1..200 条表达式并行）
- worker 启动完成发
{"ready":true} 握手；扩容后等全部就绪再返回
环境变量
架构
- 常驻 worker：避免每次 250–800ms 的 Python 启动
- 禁
eval：AST 白名单，只允许数字/字符串/列表/四则/幂/白名单函数
- 精确优先：能 Fraction 就 Fraction，涉及根号/π/超越函数才进 SymPy
精度契约
- 四则/整数幂/百分比/统计 → 精确有理数：
1/7*7 = 1、2^200 精确
- 分数/根号/常量保留符号，同时给
d 字段（30 位小数）
- 超越函数能化简就化简（
sin(pi/6)=1/2、log(1000,10)=3）
- 精确分数过大时降级为小数，标
exact=false
- 永不静默舍入；所有近似都有说明
错误协议（方便模型一次改对）
设置页与 HTTP 路由
/calc/status：版本、策略、注册状态、worker/就绪数、目录POST /calc/policy：{policy, customRules}GET/POST /calc/limits：限额；{"reset":true} 恢复默认GET/POST /calc/workers：worker 池POST /calc/batch：{exprs:[...]} 并行求值GET/POST /calc/packs：公式包/能力包
能力包扩展
.calc/plugins/*.py（或包内 packs/）：
- 纯函数、无 IO、无状态；输入输出为精确值
- 修改/新增后自动热加载（worker 校验 mtime）
- 指导文档：
PACKS.md
拆题并行（calc_shard）
mode: integrate / sum；op: sum / mean / max / min- 只适合可分解题型（区间积分、区间求和、参数扫描）
测试与基准
基准（1000 题混合题集，deepseek-v4-flash，自然使用模式）：97.6%（976/1000）。
黑盒验收（0.3.9 候选）
说明：这是生成式验收集，覆盖行为一致性、精确契约和 fail-loud 边界；难度以工程/量化计算为主，不等同于竞赛数学。
常见问题
Q：std 是样本还是总体？
A：std/std_pop/var/var_pop 是总体；std_sample/var_sample 是样本。
sharpe、zscore、cov 内部使用样本口径（ddof=1）；max_drawdown 默认要求价格严格 >0，allow_leading_zeros=1 时允许前导 0。
Q：为什么 N(...) 不等于正态 CDF？
A：N(expr, digits) 是数值求值；正态 CDF 用 norm_cdf(x)。
Q：npv 第一笔为什么不折现？
A：默认 start=0（flows[0] 在 t=0）；年末现金流用 npv(rate, flows, 1)。
Q：非法日期会怎样？
A：明确报错（如 2026-02-30），不会顺延到 3 月 2 日。
Q：api retries exhausted 是什么？
A：模型 API 连续重试 6 次仍失败（限流/网络），不是计算器错误；用 --resume 补跑。
开发与发布
- CI：
.github/workflows/test.yml 在 push / PR 时跑核心、能力包、文档、客户端、MCP 冒烟测试
- 发布：
.github/workflows/publish.yml 在 GitHub Release 发布时自动构建并上传 PyPI
（Trusted Publishing：GitHub OIDC，无需长期 token）
发布流程：
PyPI 项目需在 Publishing 里配置 GitHub publisher：
手动发布（备用）：
已知限制
- 表达式不是 Python：不支持推导式/循环/赋值（有意为之）
- 单位表覆盖常用类别，不是全量单位库
- 循环小数/超越函数是近似（有
exact=false 标记）
- 单点符号运算无法用
calc_shard 切分
- 宿主重启前改
index.js 不热更新；calc_core.py 在 worker 重启后生效
安装 / 打包
Docker：
版本与品牌
当前 0.3.9。
版本号唯一来源：dsh-calc/package.json；scripts/bump_version.py 同步
pyproject.toml 与 mcp_server.py。
许可证
MIT（见 LICENSE）。
允许任何人自由使用、修改、分发、商用，保留版权声明即可，无担保。
package.json 与 pyproject.toml 已声明 MIT。
为什么选 MIT
- AI/Agent 生态主流是 MIT：MCP SDK、LangChain、Ollama、llama.cpp、React/Vue 等
- 计算器的价值在“被集成”，不在“禁止别人用”；宽松许可证提高采用率
- 依赖（SymPy）是 BSD，与 MIT 完全兼容
- 公司内部工具/闭源产品可以放心接入，不会被 GPL 传染
MIT 项目怎么保护自己
MIT 不限制别人复制代码，保护来自许可证之外：
典型案例：React（Meta）、VS Code、Ollama、LangChain 都是 MIT/宽松许可，
靠品牌、生态、企业服务/托管平台赚钱，而不是靠许可证封锁。
MCP Registry
mcp-name: io.github.CQQOOQ123/jiheng
