TSUNAGI///Matrix — MAPPING

matrix-tsunagi — TSUNAGI///Matrix

TSUNAGI 的 BMW E46 M3 工具背后的计算逻辑，以库、命令行和 MCP 服务的形式提供。 读取 MSS54HP DME 镜像和行驶日志，获取这次行驶所支持的 VE 映射修正。读取 SMG II 变速箱镜像，解码并比较其标定数据。读取 DME 备份或仪表 EEPROM 备份，检查其中的内容。只需在自己的机器上操作，无需车辆和线缆。

npx matrix-tsunagi mapping ve --sample

--sample 会使用软件包附带的练习文件运行。处理自己的文件时，请将其替换为 --bin <file.bin> --log <file.csv>。

为 AI 助手安装（Claude、ChatGPT 等）： 请参阅 INSTALL.md。本文档旨在让你可以把此仓库交给助手，由它为相应的客户端安装合适的内容。

TSUNAGI///M 是 TSUNAGI 面向 E46 M3（S54 发动机、MSS54HP DME、SMG II）的一系列工具。 车主可在 m3.tsunagi.app 使用这些工具；AI 助手则在这里使用。 TSUNAGI///Matrix 是这一系列工具面向 AI 助手的入口：它本身不执行任何计算，而是一次一个类别地将各工具自身的代码交给助手。 此软件包包含两个类别。MAPPING：MSS54HP CSL CONVERT /// TUNER 和 E46M3SMG2 /// MAPPING。 MIGRATION：它会读取 MSS54HP CSL CONVERT /// BOOT 和 E46 M35080 /// MIGRATION 的备份，但仅限读取。

试着这样问

如何根据 Testo 日志修正经过 CSL 转换的 MSS54HP 的 VE（alpha-N）映射？

npx matrix-tsunagi mapping ve --bin my.bin --log drive.csv --out tuned.bin

其中会列出哪些单元格需要更改以及更改幅度、哪些单元格需要更多行驶数据以及如何采集；使用 --out 还可生成修正了校验和的调校 BIN。对于相同的两个文件，该文件与 TUNER 的 DOWNLOAD TUNED 输出逐字节一致。

我的 MSS54HP BIN 里有什么？校验和是否正确？应用了哪些补丁？

npx matrix-tsunagi mapping bin my.bin

为什么我的日志大部分都被丢弃了？

npx matrix-tsunagi mapping log drive.csv --bin my.bin

会列出样本被排除的所有原因（发动机未热、瞬态、全负载、超速滑行等），并说明下次行驶时需要如何调整。

我的行驶数据支持什么 rf_korr 表？ （实验性）

npx matrix-tsunagi mapping rfkorr --bin my.bin --log drive.csv

排气温度密度修正（KF_RF_KORR_DRREL），逐个单元格列出，并附上每个单元格的依据。

我的 SMG II 换挡点是什么？这个 SMG 镜像是什么？

npx matrix-tsunagi mapping smg2 image smg.bin
npx matrix-tsunagi mapping smg2 read smg.bin --xdf Siemens_SMG_II_510_512K.xdf --item "A1 Speed"

smg2 image 无需其他输入：它会说明镜像是 24 KiB 标定窗口还是完整的 512 KiB 闪存映像，并给出 ZB 编号以及 CRC 校验和是否正确。 smg2 read 会解码 MS4X 定义中命名的所有项目，并应用 E46M3SMG2 /// MAPPING 对该定义所做的修正。其中包括各挡位和程序的换挡速度阈值、齿轮比，以及离合器和起步设置。 定义文件（Siemens_SMG_II_510_24K.xdf 或 _512K.xdf）由 MS4X Dev Team 提供，本软件包不附带，因此请自行提供。 E46M3SMG2 /// MAPPING 的 WORKS 构建包含该定义文件。

两份 SMG II 标定数据之间有哪些变化？

npx matrix-tsunagi mapping smg2 compare before.bin after.bin --xdf Siemens_SMG_II_510_512K.xdf

我的 DME 备份里是什么引导加载程序？CSL 转换还剩下什么？

npx matrix-tsunagi migration boot backup dme-backup.bin

从 BOOT 的完整 1 MiB 备份中读取每个处理器上的标准 M3 或 CSL 引导加载程序、每个引导加载程序的 CRC 是否正确、程序编号以及剩余阶段。 migration boot compare a.bin b.bin 会指出两份备份的差异位置。

这块仪表 EEPROM 记录的里程是多少？这份转储真的是读取所得吗？

npx matrix-tsunagi migration m35080 read eeprom.bin

从 1 KB 的 M35080 备份中读取：这是否是实际芯片读取结果（总线断开或短路时会读出重复字节）、安全计数器中的里程、布局和校验和，以及 VIN 副本是否一致。 migration m35080 compare a.bin b.bin 会显示两份转储之间哪些区域发生了变化。

MIGRATION 仅提供读取功能。此软件包不包含会修改镜像的功能，npm run verify 会检查软件包中是否存在此类功能。 VIN 和 DME 的身份记录绝不会被打印，因为命令输出的内容会进入与助手的对话。

它能做什么？

npx matrix-tsunagi describe

面向 AI 助手

• 运行一次 npx matrix-tsunagi describe。每条命令都会在 stdout 输出 JSON，错误会以 JSON 格式输出到 stderr，并以退出代码 1 结束。
• 每个结果都包含可转述的 summary、包含数值的 result，以及 source，其中说明了由哪个工具和版本计算，以及该计算是否为实验性计算。
• 只有在所有者必须将结果写入车辆时，才会出现 apply。其中会注明应用名称、应用是免费的还是 WORKS，以及具体操作方式。apply.how 和 source.note 使用英语和日语。
• 如果还没有任何文件，请添加 --sample，以展示命令如何处理练习用 BIN 和行驶记录。

所有数据都不会发送到任何地方。文件会从你提供的路径读取。

Claude 插件

plugin/ 是 Claude 插件，一个包含两部分的套件。公开部分会在这台电脑（Claude Code）上运行 MAPPING 和 MIGRATION 服务，并提供 matrix-public Skill。WORKS 部分是 TUNER WORKS 连接器（bridge/，在 m3 上登录），并提供 tuner-drive Skill，让所有者可以在 TUNER WORKS 中交流的同时记录车辆数据，也可以通过手机操作。它可以暂存标定更改、保存会话并与所有者的云端同步；每一步都需要所有者确认。连接车辆并写入数据仍由所有者在屏幕上操作。Skills 只是入口：操作流程来自服务（about_matrix 的 howToUse、tuner_guide），因此会随工具更新，无需安装新插件；插件运行 npm 上最新版的 matrix-tsunagi。安装方法请参阅 INSTALL.md。

MCP

共有两个服务，每个类别各一个。

MAPPING 服务以工具形式提供相同的计算功能。TUNER 工具包括：read_bin、read_log、propose_ve 和 propose_rfkorr。SMG2 工具包括：smg2_image、smg2_read 和 smg2_compare。此外还有 about_matrix。它通过 stdio 在本地运行。

MIGRATION 服务（npx -y matrix-tsunagi mcp migration 或 npx -y matrix-tsunagi-migration）提供 boot_backup、boot_compare、m35080_read、m35080_compare 和 about_matrix，全部为只读工具。

Claude Code：

claude mcp add matrix-tsunagi-mapping -- npx -y matrix-tsunagi mcp mapping

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "matrix-tsunagi-mapping": {
      "command": "npx",
      "args": ["-y", "matrix-tsunagi", "mcp", "mapping"]
    }
  }
}

在 Windows 上，如果找不到 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "matrix-tsunagi", "mcp", "mapping"]。

远程服务（ChatGPT）

对于无法运行 npm 的助手，MAPPING 服务也可通过远程方式运行：

https://matrix-mcp.tsunagi.app/mcp/mapping

在 ChatGPT 中，开启 Developer mode（Settings → Security and login），然后使用该 URL 将其添加为插件。在聊天中附上 BIN 和行驶记录并提出请求。 文件会作为 ChatGPT 文件参数传送到服务：服务从 ChatGPT 提供的临时链接下载文件，在内存中进行计算，返回结果后不会保留任何内容。 它只会返回数值，因此请使用免费的 TUNER 制作调校后的 BIN。它仅提供 MAPPING 功能，因为 MIGRATION 的转储文件包含 VIN 和里程数据，应保留在你的设备上。 关于文件处理方式，请参阅隐私政策第 11 节。

库

import { mapping } from 'matrix-tsunagi';
import fs from 'node:fs';

const ve = mapping.proposeVe({
  bin: new Uint8Array(fs.readFileSync('my.bin')),
  csv: fs.readFileSync('drive.csv', 'utf8'),
});
console.log(ve.summary);
fs.writeFileSync('tuned.bin', ve.tunedBin);

mapping.readBin、mapping.readLog 和 mapping.proposeRfKorr 使用相同的输入。SMG2 提供 mapping.smg2Image({ image })、mapping.smg2Read({ image, xdf, item }) 和 mapping.smg2Compare({ image, other, xdf })，其中 xdf 是定义文件的文本。

在车辆中写入结果

计算是免费的。将结果写入车辆需在各应用中完成。

结果	由以下工具写入车辆
VE 映射（ve）	MSS54HP CSL CONVERT /// TUNER，免费，可在浏览器中通过 K+DCAN 线缆使用。--out 也会在此处保存同一文件。
rf_korr 表（rfkorr）	TUNER 的 WORKS 版本会生成并写入文件。此软件包只返回数值。
DME 备份（migration boot）	通过 OBD 备份 DME、验证备份并规划其 CSL 转换，均在 MSS54HP CSL CONVERT /// BOOT 的 WORKS 版本中完成。
仪表 EEPROM（migration m35080）	读取、备份和修复 M35080，并将车辆的真实里程和编码转移到替换仪表上，均在 E46 M35080 /// MIGRATION 的 WORKS 版本中完成。计数器只会递增；该工具会保留真实读数。
SMG II 校准（smg2）	从车辆读取、编辑和导出校准数据，均在 E46M3SMG2 /// MAPPING 的 WORKS 版本中完成，该版本包含 MS4X 定义。此软件包只负责读取、解码和比较。

WORKS 版本面向在 MESH 购买了 MILE 的用户，以及 TSUNAGI 曾为其车辆提供服务的车主（可按需申请）。 这些版本包括 TUNER 的实验性功能、E46M3SMG2 /// MAPPING、E46M3 /// MONITORING、MSS54HP CSL CONVERT /// BOOT 和 E46 M35080 /// MIGRATION。 MILE 为一次性付款，无订阅，也无需续费。 购买者可以将 MILE 分配给一个 MILESTONE，以表达希望资金用于何处。这只是记录在案的愿望，并不保证会发布任何内容或确定发布日期。

输入

• BIN：65,536 字节的 MSS54HP 校准部分文件（“0401 partial BIN”），即 TUNER 读取和写入的文件。
• 日志：带标题行的 CSV，可以是 Testo 的 MSS54 导出文件，也可以是 TUNER 导出的 CSV。列名按 Testo 和 TUNER 使用的拼写匹配。如果缺少必需列，错误信息会列出可接受的标题。
• SMG II 镜像：24,576 字节的校准窗口，或 524,288 字节的 SMG II 510 完整闪存，格式与 E46M3SMG2 /// MAPPING 读取和导出的一致。
• DME 备份：1,048,576 字节的完整 MSS54HP 镜像（主从模块），格式与 BOOT 备份的一致。
• M35080 镜像：1,024 字节的仪表 EEPROM，格式与 E46 M35080 /// MIGRATION 备份的一致。
• XDF：MS4X Dev Team 的 TunerPro 定义；窗口文件使用 Siemens_SMG_II_510_24K.xdf，完整读取文件使用 _512K.xdf。如果提供的是另一种格式，程序会拒绝读取，而不会从错误偏移处读取。

数值来源

此软件包不会重新实现任何功能，而是打包各工具自身公共代码库中的代码，版本固定在其子模块所指定的提交上： mushitaro/mss54hp-csl-convert-tuner（vendor/tuner）和 mushitaro/e46m3smg2-mapping（vendor/smg2）， mushitaro/mss54hp-csl-convert-boot（vendor/boot）和 mushitaro/e46-m35080-migration（vendor/m35080）。 每个结果都会在 source 中注明工具、版本和提交。

npm run verify 会将调校后的 BIN 与从同一提交中 TUNER 自身的 DOWNLOAD TUNED 测得的 SHA-256 值进行核对。 它还会逐项将 SMG2 的解码结果与应用自身的 loadDefinition 进行核对。 每项检查都有一个对照测试，用于证明比较可能失败。 SMG2 检查需要 MS4X 定义和车辆镜像，这些内容并未公开。缺少这些内容时，检查会报告 SKIP，而不是通过。

git clone --recursive https://github.com/mushitaro/matrix-tsunagi
cd matrix-tsunagi && npm install && npm run verify

日语

这是一个软件包，可将 TSUNAGI///M（BMW E46 M3 的工具套件）中的计算用于库、命令行和 MCP。 TSUNAGI///Matrix 是连接 M 工具与 AI 助手的门户。它本身不进行计算，而是按类别打包并提供各工具的代码。 它可根据 MSS54HP 的 BIN 和行驶日志（Testo 的 CSV），生成 VE 映射修正建议、指出日志中未使用的部分及其修正方法，并输出 rf_korr 表格（测试中）。 根据 SMG II 的图像，它可输出 ZB 编号和校验和、校准解码结果（如换挡点），以及两份数据的比较结果。解码需要您已有的 MS4X XDF。 MIGRATION 仅会读取 DME 备份（引导加载程序类型和 CRC、CSL 转换的剩余工作）和仪表盘 M35080 备份（里程、校验和、VIN 是否匹配），不会进行写入。不会输出 VIN 和 DME 的识别信息。 所有计算均在您的 PC 上进行，不会发送到任何地方。即使没有文件，也可以使用 --sample 进行试用。

VE 映射可通过 MSS54HP CSL CONVERT /// TUNER（免费，在浏览器中运行）写入车辆。 rf_korr 等测试中的功能，可通过 TUNER 的工坊版生成文件并写入。 从 SMG II 车辆读取、编辑和导出数据，可通过 E46M3SMG2 /// MAPPING 的工坊版完成。工坊版还包含 XDF。 工坊版供通过 MESH 购买 MILE 的用户，以及主动申请的施工车主使用。 MILE 为一次性付款，不会自动续订。 分配到 MILESTONE 仅表示所选用途，不代表承诺公开或确定时间。

许可证

MIT，© TSUNAGI。有关随附内容（包括练习用 BIN），请参阅 THIRD-PARTY-NOTICES.md。