# Excel / WPS 公式助手 · Formula Helper

一套帮你在 **Microsoft Excel 或 WPS** 里快速写出复杂公式并落地到表格的工具，灵感来自微软 Excel 电竞比赛（FMWC / Excel World Championship）。

包含两部分，可独立使用，也可搭配：

| 工具 | 形态 | 给谁用 |
|------|------|--------|
| **公式助手** | 单文件网页 `公式助手.html` | 人手动用：选任务、填参数、一键复制公式 |
| **excel-mcp-server** | Python MCP 服务器 | 给 AI 客户端（Claude Desktop / Cursor 等）调用，直接读写 `.xlsx` |

## 截图

| 模板库 | AI 生成 | 报错诊断 |
|:---:|:---:|:---:|
| ![模板库](screenshots/templates.jpg) | ![AI 生成](screenshots/ai.jpg) | ![报错诊断](screenshots/errors.jpg) |

> 在线体验（GitHub Pages）：**https://maoxin1234.github.io/excel-formula-helper/**

---

## 一、公式助手（`公式助手.html`）

**双击即用，无需安装，离线可用，微软 Excel 与 WPS 通用。**

### 功能
- **模板库**：选任务 → 填参数 → 实时生成公式 → 一键复制
  - 查找匹配：VLOOKUP / XLOOKUP / INDEX+MATCH
  - 条件汇总：SUMIFS / COUNTIFS / AVERAGEIFS
  - 文本处理：合并、截取、按符号分段、清洗去空格
  - 日期时间：工龄/年龄、月末推算、工作日推算
  - 排名统计：RANK、去重计数
  - 动态数组（新版）：FILTER / UNIQUE / SORT / LET / LAMBDA、筛选+排序+取前 N
  - 数据透视替代：二维交叉汇总、动态透视、占比 / 累计占比
  - 逻辑防错：IFS 多区间分级、IFERROR 防错包裹
- **AI 生成**：用自然语言描述任务，调用大模型生成公式。支持多家厂商：
  Anthropic、OpenAI、Google Gemini、DeepSeek、通义千问、Kimi、智谱 GLM，以及任意 OpenAI 兼容端点（含本地 Ollama）。
- **报错诊断面板**：`#N/A` `#VALUE!` `#REF!` `#DIV/0!` `#NAME?` `#SPILL!` `#NUM!` 的成因、逐项排查清单与修复方案。
- **中文环境适配**：一键把公式参数分隔符在 `,` / `;` 间切换。

### AI 功能说明
- API Key 仅保存在本机浏览器 `localStorage`，不上传任何第三方；请求由浏览器直接发往所选厂商。
- 浏览器直连可能遇到 **CORS 跨域**限制。国内网络建议优先选 DeepSeek / Kimi（对浏览器较友好），或用支持跨域的中转地址（“自定义”选项填 Base URL）。

---

## 二、excel-mcp-server（`excel_mcp_server.py`）

一个 [MCP](https://modelcontextprotocol.io) 服务器，让 AI 客户端**直接读写本地 Excel 文件**——读结构、读区域、写公式、批量铺数据、套模板、查报错。

### 依赖
```bash
pip install "mcp[cli]" openpyxl
# 可选：把公式重算成真实值，需要本机安装 LibreOffice
```

### 工具列表
| 工具 | 作用 |
|------|------|
| `list_sheets` | 列出工作表及尺寸 |
| `read_range` | 读区域（值或公式原文） |
| `write_value` | 写单个值 |
| `write_rows` | 一次写入整片二维数据（表头+数据） |
| `write_formula` | 写公式，支持向下智能填充（行号自增、`$` 锁定、不误伤工作表名） |
| `create_workbook` | 新建工作簿 |
| `recalculate` | 调 LibreOffice 把公式重算为真实值 |
| `list_templates` / `build_from_template` | 内置公式模板库 |
| `diagnose_error` | 报错代码诊断 |
| `flush` | 把缓存中未保存的修改强制落盘 |

### 接入方式

**Claude Desktop** — 编辑 `claude_desktop_config.json`：
```json
{
  "mcpServers": {
    "excel-helper": {
      "command": "python",
      "args": ["/绝对路径/excel_mcp_server.py"],
      "env": { "EXCEL_MCP_ROOT": "/允许访问的根目录" }
    }
  }
}
```

**Claude Code**：
```bash
claude mcp add excel-helper python "/绝对路径/excel_mcp_server.py"
```

接好后，直接用自然语言即可，例如：
> “看一下 `销售.xlsx` 的结构，在 D 列填每行所属部门当月金额合计，填到第 200 行。”

### 安全
- 默认仅允许访问用户主目录；用环境变量 `EXCEL_MCP_ROOT` 可收紧到指定文件夹。
- `openpyxl` 只写公式不计算值——文件需用 Excel / WPS 打开（或调用 `recalculate`）后才显示结果。

---

## 兼容性
- Microsoft Excel 365 / 2019 及以上，WPS 表格较新版本。
- 部分动态数组函数（FILTER / UNIQUE / SORT / LET / LAMBDA / XLOOKUP / TAKE）需较新版本，旧版请用模板里给出的兼容写法。

## 许可证
[MIT](LICENSE)