内容
# 双水箱模型 MCP 服务器，用于电池老化机制识别
[English](#dual-water-tank-mcp-for-battery-aging-mechanism-identification) | [中文](#双水箱模型mcp服务器用于电池老化机制识别)
本项目是一个用于锂离子电池双水箱模型参数识别的 MCP 服务器。输入为充电/放电电压-容量数据，输出为双水箱模型参数、拟合曲线、误差、符号选择结果和批量汇总。它主要面向电池老化机制识别，例如容量损失、锂库存变化、正负极容量变化等参数分析。
项目保持两层结构：
- `dual_water_tank_mcp/`：核心模型代码，包括数据读取、列识别、充放电识别、模型计算、遗传算法拟合、批量输出和 CLI。
- `dual_water_tank_mcp/server.py`：MCP 薄接口层，只负责把核心函数暴露成 MCP 工具。
后续如果需要修正或改进模型，直接改 `dual_water_tank_mcp/` 下的核心代码，然后重启 MCP 服务即可。
## 功能
- 读取 `.xlsx`、`.xls`、`.csv`、`.txt`、`.tsv` 电池测试数据。
- 自动识别电压列和容量列。
- 根据电压趋势自动识别充电或放电。
- 自动处理正负极化学计量比 `y/x` 的充放电符号。
- 自动分别尝试 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。
- 根据数据容量范围自动适配遗传算法容量上下限。
- 支持单文件拟合和批量拟合。
- 默认把最终结果输出到桌面文件夹。
- 可以作为 MCP server 被 Codex、Claude 等 agent 调用。
## 从 GitHub 到安装
如果项目已经上传到 GitHub，先克隆仓库：
```powershell
git clone <你的 GitHub 仓库地址>
cd dual-water-tank-mcp
```
如果已经有本地源码，直接进入项目根目录，例如：
```powershell
cd "D:\desktop\PSG\1.1 github\dual-water-tank-mcp"
```
需要 Python 3.10 或更高版本，建议同时安装 Git。
检查版本：
```powershell
python --version
git --version
```
可以直接使用仓库自带的一键 MCP 启动脚本。第一次运行会自动创建 `.venv` 并安装依赖：
```powershell
.\run_mcp.cmd
```
MCP 客户端也应该调用这个脚本。用户不需要修改模型代码、Python 文件或 MCP server 文件。
命令行预览示例：
```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```
命令行拟合示例：
```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"
```
## 启动 MCP
在 Codex、Claude Desktop、Claude Code 或其他 MCP 客户端中添加这个 MCP server。
Windows MCP 配置示例：
```json
{
"mcpServers": {
"dual-water-tank-model": {
"command": "C:\\path\\to\\dual-water-tank-mcp\\run_mcp.cmd",
"args": []
}
}
}
```
macOS/Linux MCP 配置示例：
```json
{
"mcpServers": {
"dual-water-tank-model": {
"command": "/path/to/dual-water-tank-mcp/run_mcp.sh",
"args": []
}
}
}
```
macOS/Linux 需要先给脚本执行权限：
```bash
chmod +x run_mcp.sh dual-water-tank.sh
```
仓库里也提供了可复制修改的配置文件：
- `examples/mcp_config_windows.json`
- `examples/mcp_config_macos_linux.json`
配置完成后，在 MCP 客户端中刷新或重启连接。看到 `dual-water-tank-model` 可用，就说明已经连上。
## MCP 已连接后怎么用
连接成功以后，不需要手动运行 Python 或命令行脚本。你只需要在支持 MCP 的客户端里提出需求，客户端会调用本项目暴露的 MCP 工具。
推荐流程：
1. 如果不确定输入数据格式，先调用 `preview_dual_water_tank_data`。
2. 单文件拟合调用 `fit_dual_water_tank`。
3. 批量拟合调用 `batch_fit_dual_water_tank`。
4. 打开桌面输出目录里的 `result.json`、`fitted_curve.csv` 或 `batch_summary.csv` 查看结果。
最终结果默认输出到桌面：
```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```
在作者的 Windows 电脑上，通常是：
```text
D:\desktop\dual water tank output\
```
MCP 返回结果里也会包含 `output_dir`、`curve_csv`、`result_json` 等路径。
用户可以这样对 MCP 客户端说：
```text
请使用 dual-water-tank MCP 预览 test_cases/25C_0.1C/25C_0.1C.xlsx。
```
```text
请使用 dual-water-tank MCP 拟合 test_cases/25C_0.1C/25C_0.1C.xlsx，并把最终结果保存到桌面。
```
```text
请使用 dual-water-tank MCP 批量拟合 D:\my_battery_data 里面的所有 Excel 文件。
最终结果输出到桌面的 dual water tank output 文件夹。
```
```text
请使用 dual-water-tank MCP 拟合 D:\data\cell.xlsx。
anode_path 使用 D:\data\anode.txt，cathode_path 使用 D:\data\cathode.txt。
自动判断充放电方向和 I*R 符号。
```
## MCP 工具
MCP server 暴露这些工具：
- `preview_dual_water_tank_data`：预览一个数据集，返回自动识别到的列、充放电方向、容量范围、电压范围和电流估计。
- `fit_dual_water_tank`：拟合一个文件或一个工作表，输出 `result.json` 和 `fitted_curve.csv`。
- `batch_fit_dual_water_tank`：拟合一个文件夹或文件列表，输出每个文件的结果和批量汇总。
## 工具调用示例
`preview_dual_water_tank_data` 示例：
```json
{
"data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx"
}
```
`fit_dual_water_tank` 示例：
```json
{
"data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx",
"direction": "auto",
"resistance_sign": "auto"
}
```
`fit_dual_water_tank` 可选参数示例：
```json
{
"data_file": "D:/data/cell.xlsx",
"anode_path": "D:/data/anode.txt",
"cathode_path": "D:/data/cathode.txt",
"current": 65,
"direction": "auto",
"resistance_sign": "auto",
"voltage_col": "B",
"capacity_col": "C",
"output_dir": "D:/desktop/dual water tank output/my_run"
}
```
`batch_fit_dual_water_tank` 示例：
```json
{
"input_dir": "D:/my_battery_data",
"direction": "auto",
"resistance_sign": "auto"
}
```
## 模型符号约定
模型保留原始五个参数：
```text
[y0, Cp, x0, Cn, R]
```
充电：
```text
y = y0 - Q / Cp
x = x0 + Q / Cn
V = Upos(y) - Uneg(x) + I * R
```
放电：
```text
y = y0 + Q / Cp
x = x0 - Q / Cn
V = Upos(y) - Uneg(x) - I * R
```
`I` 按正的电流大小输入。默认 `resistance_sign` 为 `auto`，工具会对检测到的方向分别拟合 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。最终选择的符号和两个候选的 RMSE 会写入 `result.json` 的 `resistance_sign_selection` 字段。
可选的电阻符号模式：
```text
auto | physics | positive | negative | matlab
```
- `auto`：同时拟合 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。
- `physics`：充电用 `+I*R`，放电用 `-I*R`。
- `positive`：强制 `+I*R`。
- `negative`：强制 `-I*R`。
- `matlab`：始终使用 `+I*R`，对应原 MATLAB 目标函数实际执行的公式。
原 MATLAB 目标函数在给定充电示例中实际使用 `+I*R`，但脚本注释中有一处写成充电 `-I*R`。因为代码和注释冲突，所以本 MCP 默认使用数据驱动的符号选择。
## 输入数据规则
推荐全电池数据至少包含两列：
| 电压 | 容量 |
| --- | --- |
| `voltage_V` | `capacity_Ah` |
没有表头也可以。程序会根据数值特征识别电压列和容量列：
- 电压列通常在常见电池电压范围内，并且有合理电压跨度。
- 容量列通常有明显跨度，并且大体单调。
- 相邻的电压/容量列会获得额外评分，因为这符合常见测试设备导出格式。
充放电识别会先把容量归一化为从零向前增加，再比较末端电压和起始电压：
- 电压整体上升：`charge`
- 电压整体下降：`discharge`
- 近似平坦：退回到线性电压-容量斜率判断
电流大小可以通过 `current` 显式传入。如果不传，工具会尝试从文件名解析 C-rate。例如 `25C_0.1C.xlsx` 会识别为 `0.1C`，温度含义的 `25C` 不会被当成倍率。
## 半电池 OCV 文件
自带测试案例包含匹配的半电池 OCV 文件：
```text
test_cases/25C_0.1C/anode.txt
test_cases/25C_0.1C/cathode.txt
```
默认情况下，MCP 使用这套测试案例里的电极文件，方便新用户下载后立刻跑通 demo。真实实验中，如果要使用自己的半电池 OCV 曲线，请传入 `anode_path` 和 `cathode_path`。
## 输出文件
单文件拟合会输出：
- `result.json`：拟合参数、RMSE、符号选择、化学计量比范围和派生参数。
- `fitted_curve.csv`：容量、实测电压、模型电压、残差、正负极电势和 `x/y`。
批量任务额外输出：
- `batch_summary.csv`：每个拟合文件一行摘要。
- `batch_summary.json`：完整批量结果和错误信息。
如果不传 `output_dir`，最终结果会写到：
```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```
默认不会污染输入数据文件夹。
## 测试案例
仓库包含一个测试案例：
```text
test_cases/25C_0.1C/
```
文件：
- `25C_0.1C.xlsx`：全电池电压-容量测试数据。
- `anode.txt`：负极半电池 OCV 曲线。
- `cathode.txt`：正极半电池 OCV 曲线。
快速预览：
```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```
快速拟合：
```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C/25C_0.1C.xlsx"
```
## 仓库结构
```text
dual_water_tank_mcp/ Python package and MCP server
test_cases/25C_0.1C/ Example full-cell dataset plus anode/cathode OCV files
references/original_resource/ Original MATLAB scripts, notes, and source references
examples/ MCP configuration examples
Desktop/dual water tank output/ Generated results outside the repository
```
## 本地调试
快速预览：
```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```
快速拟合但不保存文件：
```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C/25C_0.1C.xlsx" --no-save --population-size 20 --generations 1 --max-points 100
```
运行符号诊断脚本：
```powershell
python scripts\diagnose_parameter_gap.py
```
开发者安装方式，仅在需要修改代码时使用：
```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
```
## 许可证
本仓库 Python 代码使用 Apache License 2.0，见 `LICENSE`。项目署名见 `NOTICE`。
Apache License 2.0 包含明确的专利授权和专利终止条款。`references/original_resource/` 中的参考资料可能有其原始版权、专利或使用限制。本仓库代码使用 Apache License 2.0 不会改变这些外部参考资料的权属或许可状态。
