# ev-diagnosis-mcp

新能源汽车维修诊断的 MCP 服务。给 AI 客户端补上通用模型里没有的那部分：中文新能源维修的实战经验、故障码到原因到报价的完整链路、车型高发关联。

零第三方依赖，纯本地数据，不联网、不调模型、不传数据。

English: [README_EN.md](README_EN.md)

在线看真实输出样例（不用装）：https://ev-intake.app.workbuddy.host/demo.html

---

## 它解决什么

通用大模型回答"比亚迪汉EV冬天续航掉得快"，给的是教科书式的可能原因列表。真正值钱的是这类东西：

> 雨季/涉水后绝缘故障高发，多数源于连接器进水而非电池本体，优先查线束与接口。
> 特斯拉绝缘故障多为底部磕碰或充电口进水，分段兆欧表测量是王道。

这类判断不在通用语料里，来自维修现场。本服务把 190 条这样的经验做成可检索数据，外加 896 条标准故障码定义、146 条中文维修条目、44 条车型通病映射。

## 安装

```bash
npx -y ev-diagnosis-mcp      # 直接用（已发布后）
node server.mjs              # 本地源码
```

客户端配置：

```json
{
  "mcpServers": {
    "ev-diagnosis": {
      "command": "npx",
      "args": ["-y", "ev-diagnosis-mcp"]
    }
  }
}
```

完整示例见 `mcp-config.example.json`。支持 MCP 协议 2024-11-05 / 2025-03-26 / 2025-06-18。

## 工具（7 个）

| 工具 | 干什么 | 数据 |
|---|---|---|
| `diagnose_full` | 输车型+现象+故障码，直接出结论：原因概率排序、检查顺序（先不花钱后花钱）、报价分档、车型高发关联、车主白话 | 综合 |
| `lookup_fault_code` | 故障码查询：精确 / 前缀 / 中文关键词。返回原因、诊断步骤、方案、工时、报价、配件、避坑 | 146 条 |
| `lookup_dtc` | 标准故障码定义：英文原文 + 术语级中文对照 + 制造商，并提示本库是否有中文维修条目 | 896 条 |
| `search_experience` | 老师傅实战经验检索，按关键词，不限故障码 | 190 条 |
| `list_model_issues` | 车型通病：车型 × 故障码关联 | 44 条 |
| `symptom_to_codes` | 现象反查故障码 | 40 条 |
| `kb_stats` | 数据规模、每条数据集的来源与真实性等级 | — |

另提供 `resources`（kb://datasets、kb://provenance、kb://fault-codes、kb://dtc-index、kb://experience）和 2 个 `prompts`（diagnose_intake、owner_explain）。

## 输出长什么样

`diagnose_full({"brand":"特斯拉","model":"Model 3","symptom":"涉水后无法上电，仪表报高压系统故障","extra":"昨晚暴雨，涉水深度约20cm"})` 的真实输出（节选）：

```
## 可能原因（按概率排序，启发式估计，非统计值）
1. 高压线束破损对地 — 约 21%
2. 涉水导致连接器进水 — 约 18%
3. 电池包内部绝缘下降 — 约 15%

## 检查与处理顺序（先不花钱的，后花钱的）
1. [排查·几乎不花钱] 用绝缘检测仪测整包正/负对地绝缘阻值(标准>500Ω/V)
2. [排查·几乎不花钱] 分段断开高压部件(电池、MCU、OBC、压缩机)分别测量定位漏点
...
6. [维修·换密封件 500-2000 元] 断开维修开关MSD并验电

## 报价分档
- 换密封件：500 - 2000 元
- 换 OBC：3000 - 8000 元
- 换壳体/拆包：8000 - 20000 元

## 老师傅经验
- P0AA6：雨季/涉水后绝缘故障高发，多数源于连接器进水而非电池本体，优先查线束与接口。
- P0AA6：特斯拉绝缘故障多为底部磕碰或充电口进水，分段兆欧表测量是王道。

## 可以直接发给车主的一段话
您这车出现「涉水后无法上电，仪表报高压系统故障」，最常见的原因是高压线束破损对地，
大概 21% 的可能性（经验排序，不是统计值）。处理上会先用绝缘检测仪测整包正/负对地绝缘阻值，
这一步基本不花钱；确认不了再往下查。费用大概 500 到 20000 元，具体看坏在哪一档，修之前会跟您确认。
高压部分要断电验电后再动，我们自己不会带电操作。
```

## 数据来源与真实性

这件事必须说清楚，否则没法判断结论能信几分。用 `kb_stats` 随时可查：

| 数据集 | 条数 | 来源 | 等级 |
|---|---|---|---|
| 标准故障码定义 | 896 | ModelScope `Never84/Vehicle_DTC_Diagnostic_Trouble_Code_Definitions`，Apache 2.0 | **A** |
| 车型与电池类型 | 34 | 公开车型参数 | **A** |
| 中文故障码维修库 | 146 | 团队维修知识库（含国标与整车厂公开手册整理） | B |
| 老师傅实战经验 | 190 | 团队维修知识库沉淀 | B |
| 车型通病 | 44 | 团队维修知识库沉淀 | B |
| 现象 → 故障码 | 40 | 团队维修知识库沉淀 | B |
| 常用配件 | 56 | 公开配件信息 | B |

- **A** = 公开数据集或真实工单，可追溯
- **B** = 结构化整理，字段按行业惯例补全，**未逐条实车验证**
- **C** = 样例数据（本版不含）

`diagnose_full` 里的概率是启发式排序（经验与通病是否佐证、排查成本高低），**不是统计概率**，输出里也已标注。报价是行业通行区间，需按车型年款与实际工位校准。

导入真实工单后，条目会被标成 `source=real_workorder`，等级自动升为 A，并在 `kb_stats` 里单独计数。导入脚本：`tools/import_workorders.py`（CSV / Excel / JSON）。

**本服务输出为维修辅助参考，不构成维修结论。高压作业须由具备资质人员按整车厂手册执行。**

## 测试

```bash
npm test        # 或 node test.mjs
```

37 条断言：协议握手、工具清单、7 个工具实调、resources、prompts、异常输入（未知工具 / 未知方法 / 空输入）。当前全绿。

看单次输出：`node preview.mjs diagnose_full '{"brand":"比亚迪","model":"汉EV","symptom":"冬天续航掉得快"}'`

## 发布到目录

需要 GitHub 与 npm 账号（本仓库里 `GITHUB_USER` 是占位符，用 `python tools/prepare_release.py --user <你的GitHub用户名>` 一键替换）：

1. 官方 MCP Registry：`mcp-publisher init` → GitHub 登录 → `mcp-publisher publish`。其他目录多从它同步，命名空间 `io.github.<用户名>/ev-diagnosis` 一旦确定不可改
2. npm：`npm publish --access public`
3. Glama：仓库加 `mcp-server` topic，自动爬取
4. mcp.so / Smithery / LobeHub / Awesome MCP Servers / Cline Marketplace：见 `delivery/publish/市场提交文案.md`

## 路线图

- 真实工单导入后重算等级，把 B 类数据逐步替换成 A 类
- 车型通病从 44 条扩到 200 条以上（靠真实工单，不靠造数）
- 鉴权与计费（现在完全开放，等有用户再做）

## 许可

代码 MIT。数据部分：896 条标准码来自 Apache 2.0 数据集，其余为团队知识库，允许在本服务内使用。