内容
# SymKit
> **Mathematica 风格的符号计算，由大语言模型驱动。**
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[]()
[]()
🌐 **English** | [简体中文](README.zh-CN.md)
## 如果你拥有Mathematica的符号引擎，由自然语言驱动
Mathematica 给我们带来了精确的符号数学。大型语言模型（LLMs）赋予了我们自然语言推理的能力。 **SymKit 将两者结合起来。**
它是一个MCP服务器，允许AI代理执行逐步的符号推导：计算、转换、验证和存储公式，带有完整的来源记录 —— 所有这些都通过对话。
```text
┌────────────────────────────────────────────────────────────────────┐
│ │
│ 你用自然语言描述数学问题 │
│ ↓ │
│ SymKit 执行、验证并记录每一步 │
│ ↓ │
│ 你获得一个精确的、可重复使用的公式，附带审计轨迹 │
│ │
└────────────────────────────────────────────────────────────────────┘
```
## 为什么选择SymKit？
| 传统的大型语言模型 | SymKit |
|---|---|
| ❌ "答案是近似值……" | ✅ "精确表达式是……" |
| ❌ "让我再计算一次" | ✅ 每一步都记录且可验证 |
| ❌ "我认为这些单位可以……" | ✅ 量纲分析检查每个结果 |
| ❌ "这个公式从哪里来？" | ✅ 完整的来源记录：基础公式 + 推导步骤 |
| ❌ 计算结果丢失在聊天记录中 | ✅ 存储为可重复使用的Markdown + YAML |
## SymKit的功能
SymKit **不是一个公式数据库**。它是一个 **符号推导引擎**，可以从现有的公式中创建新的公式。
```text
已知公式 新公式
┌─────────────────┐ ┌────────────────────────────┐
│ F = -kx │ │ │
│ F = ma │ ──组合──▶ │ ω = √(k/m) │
│ d²x/dt² = a │ │ （简谐振子） │
└─────────────────┘ └────────────────────────────┘
```
将其用于物理、工程、化学、生物、经济学 —— 任何需要组合和转换数学关系的领域。
## ⚡ 四大超能力
| 能力 | 含义 | 工具 |
|---|---|---|
| **推导** | 将基础公式组合成新的公式 | `derive`, `intent_execute`, `math` |
| **控制** | 审查、注解和回滚每一步 | `session_*`, `*_step` |
| **验证** | 符号化和量纲验证 | `session_verify_*`, `assume*` |
| **输出** | 将结果转换为Python、LaTeX、Markdown或SymPy | `generate_*` |
## 🚀 实际演示
**从基本原理推导物理定律：**
```text
用户：推导简谐振子的角频率。
SymKit：
1. 加载 F = -kx 和 F = m·d²x/dt²
2. 代入 → m·d²x/dt² = -kx
3. 求解常微分方程 → x(t) = A·cos(ωt + φ), ω = √(k/m)
4. 验证代入：d²x/dt² = -ω²x ✓
5. 存储结果并附带完整推导历史
```
**构建自定义工程模型：**
```text
用户：找到RC高通滤波器的截止频率。
SymKit：
1. 加载 Q = CV 和 V = IR
2. 推导电容电抗 X_c = 1/(2πfC)
3. 在截止频率处设置 X_c = R
4. 求解 f → f_c = 1 / (2πRC) ✓
```
**验证微积分结果：**
```text
用户：计算并验证 ∫(x² + 3x) dx。
→ 结果：x³/3 + 3x²/2 + C
→ 验证：d/dx(x³/3 + 3x²/2) = x² + 3x ✓
```
## 🛠️ 41种MCP工具，一个连贯的工作流
SymKit公开了 **41种MCP工具**，涵盖8个类别。所有工具都通过几个高级工具连接起来，而高级用户可以直接使用单个步骤。
| 类别 | 工具 | 数量 |
|---|---|---|
| **统一数学** | `math` | 1 |
| **会话管理** | `session_start`, `session_show`, `session_rollback`, `session_complete`, ... | 17 |
| **假设** | `assume`, `show_assumptions`, `assume_for_step`, `list_assumptions`, `check_assumption_conflicts`, `clear_step_assumptions` | 6 |
| **公式搜索** | `formula_search`, `formula_get`, `formula_add`, `formula_categories` | 4 |
| **符号注册** | `register_symbol`, `lookup_symbol`, `list_domain_symbols`, `check_symbol_conflicts` | 4 |
| **代码生成** | `generate_python_function`, `generate_latex_derivation`, `generate_derivation_report`, `generate_sympy_script` | 4 |
| **推导与编排** | `derive`, `intent_execute`, `list_patterns` | 3 |
| **工具发现** | `tool_categories`, `tool_recommend` | 2 |
`math()`工具本身涵盖了约25种符号运算 —— 微积分、常微分方程、矩阵、向量分析、积分变换 —— 并且可以直接将结果写入推导会话。
## 🔍 公式搜索工作流
SymKit可以从Wikidata拉取权威公式，从SciPy拉取物理常量，自动规范大型语言模型查询，并将选择的公式直接加载到推导会话中。
**推荐工作流：**
```text
1. 搜索
formula_search("纳维-斯托克斯方程", domain="流体动力学")
2. 获取和加载
formula_get("Q201321", source="wikidata", load_into_session=True)
3. 推导
math("简化", "...", session=True)
4. 完成
session_complete(description="不可压缩NS动量方程")
```
**查询规范化：** 你可以自然地编写查询 —— `流体动力学`、`流体力学`和`cfd`都解析为同一个领域；`Navier–Stokes`（en dash）和`Navier-Stokes`（hyphen）匹配同一个Wikidata项目。
**MathML处理：**Wikidata有时会返回渲染的MathML用于搜索预览。调用`formula_get`获取原始LaTeX和SymPy-ready字符串。
## 🎛️ 你拥有每一步
SymKit中的推导是一个不可变的、可验证的步骤链。你可以：
- **创建** — `session_record_step`
- **读取** — `session_get_steps`, `session_show`
- **注解** — `session_add_note`
- **回滚** — `session_rollback`
- **验证** — `session_verify_step`, `session_verify_session`
表达式永远不会在原地编辑。如果出现问题，回滚到上一个良好状态并继续。这使得整个推导过程可重复。
## 🌍 与MCP生态系统配合使用
SymKit旨在扩展而非取代你的科学计算栈。它处理推导、验证和来源；原始符号计算和基础公式委托给SymPy-MCP。
**何时使用SymKit：**
- ✅ 从现有公式推导新公式
- ✅ 构建温度/压力/参数修正模型
- ✅ 为任何量化领域创建自定义模型
- ✅ 生成验证的、可引用的推导结果
**何时使用其他工具：**
- ❌ 查询基本物理公式 → 使用 `sympy-mcp`
- ❌ 获取物理常量 → 使用 `sympy-mcp` 或 `SciPy`
- ❌ 临床评分 → 使用 `medical-calc-mcp`
- ❌ 阅读教科书公式 → 直接使用参考文献
## 📦 60秒上手
### 要求
- **Python 3.10+**
- **uv** （推荐）
```bash
# 安装
uv add symkit-mcp
# 或使用pip
pip install symkit-mcp
```
### 数据存储位置
安装后，SymKit在每个用户目录中存储运行时数据（通过`platformdirs`解析）：派生公式和会话JSON保存在`~/.local/share/symkit/`（Linux）、 `%LOCALAPPDATA%\symkit`（Windows）或 `~/Library/Application Support/symkit`（macOS）。设置环境变量`SYMKIT_DATA_DIR`以覆盖此位置。种子公式（雷诺数、纳维-斯托克斯方程等）以内置只读方式存储在软件包中；通过`formula_add`添加的用户公式写入可写入的覆盖层，并按ID覆盖种子。
### 连接到Claude Desktop / Cherry Studio
相同的JSON文件可在任何MCP兼容的客户端（Claude Desktop、Cherry Studio等）中使用。
**如果从PyPI安装：**
```json
{
"mcpServers": {
"symkit": {
"command": "uvx",
"args": ["symkit-mcp"]
}
}
}
```
**如果从本地源目录运行（无需安装）：**
```json
{
"mcpServers": {
"symkit": {
"command": "uv",
"args": [
"run",
"--no-sync",
"--directory",
"<your-local-symkit-mcp-path>",
"python",
"-m",
"symkit_mcp.server"
]
}
}
}
```
替换 `--directory` 为你的本地 `symkit-mcp` 克隆的绝对路径。 `--no-sync` 跳过每次启动时的依赖解析；手动运行 `uv sync` 当依赖项更改时。
### 从源码编译
```bash
git clone https://github.com/LBurny/symkit-mcp.git
cd symkit-mcp
uv sync --all-extras
uv run symkit-mcp
```
## 🏗️ 清洁架构，构建可扩展
```text
symkit-mcp/
├── src/
│ ├── symkit/ # 纯领域逻辑（无MCP依赖）
│ │ ├── domain/ # 实体，值对象，推导引擎
│ │ ├── application/ # 用例
│ │ └── infrastructure/ # SymPy引擎，适配器，持久化
│ └── symkit_mcp/ # MCP服务器层
│ ├── server.py
│ └── tools/ # 41种MCP工具
├── formulas/ # 种子公式库（源代码树）
├── tests/ # 295个测试
└── pyproject.toml
```
- **领域驱动设计** —— 核心逻辑独立于MCP和SymPy。
- **可插拔引擎** —— 通过协议交换符号引擎或验证器。
- **基于文件的持久化** —— 公式和会话存储在可读的Markdown/YAML/JSON中。
## 🧪 开发
```bash
# 运行完整测试套件
uv run pytest
# 校验和类型检查
uv run ruff check src/ tests/
uv run mypy src/
# 启动开发服务器
uv run symkit-mcp
```
## 📖 了解更多
- [架构](ARCHITECTURE.md) —— DDD分层和职责
- [SymKit设计](docs/symkit-design.md) —— 深入技术设计（英文）
- [SymKit设计（中文）](docs/symkit-design.zh-CN.md) —— 中文设计文档
- [SymKit vs SymPy-MCP](docs/symkit-vs-sympy-mcp.md) —— 功能比较
- [路线图](ROADMAP.md) —— 即将推出的功能
## 🙏 致谢
SymKit建立在[nsforge-mcp](https://github.com/u9401066/nsforge-mcp)的基础上，它开创了神经符号公式推导方法。nsforge-mcp的原始中文README可以在[这里](https://github.com/u9401066/nsforge-mcp/blob/master/README.zh-TW.md)找到。
SymKit与[sympy-mcp](https://github.com/sdiehl/sympy-mcp)配合使用，后者提供了SymPy 기반的符号计算和基础公式查找，SymKit在此基础上构建。
## 📄 License
Apache 2.0 —— 见 [LICENSE](LICENSE)。
<p align="center">
<strong>停止回答数学问题。开始推导新知识。</strong>
</p>
