功能定位：为什么 SafeW 需要独立 CSV 映射器
在 SafeW 的「隐私钱包」与「链上雷达」双核架构下，地址簿不再只是“联系人”，而是风险评分、闪兑白名单、匿名社交好友的同一主键。v5.3 之前，用户只能通过「设置-钱包-地址簿-添加」单条录入，空投猎人一次性交互 300+ 合约时，手动操作平均耗时 47 分钟，且因链名大小写不一致导致 12% 记录无法被雷达模块识别。v5.4.0 起，官方把「CSV 批量导入」拆成独立入口，并内置「字段映射向导」，核心目标只有一个：让链上标签与本地地址簿在 30 秒内完成主键对齐，后续风险扫描、闪兑白名单、群聊好友批量邀请都直接复用同一套数据。
经验性观察：当地址量超过 2000 条后，单条维护的出错率呈指数级上升；而映射器通过「字段对齐+冲突策略」把人为失误降到 1% 以内，为后续所有自动化流程奠定唯一可信源。
版本差异速览：v5.3 旧模板 vs v5.4 新映射器
| 维度 | v5.3 旧模板 | v5.4 新映射器 |
|---|---|---|
| 入口深度 | 设置-钱包-地址簿-⋮-导入（4 级） | 钱包首页-地址簿-⊕-CSV 导入（2 级） |
| 字段识别 | 硬编码 4 列：address、chain、name、note | 自动嗅探列头，支持 30+ 字段别名映射 |
| 链名校验 | 大小写敏感，需严格匹配“Ethereum” | 模糊匹配+下拉纠正，容错“eth/ETH/ERC20” |
| 冲突策略 | 遇到重复地址直接跳过，无提示 | 三选一：跳过/覆盖/重命名 |
| 批量上限 | 1 万行，超过需手动拆文件 | 10 万行，前端分页预览，内存占用降 40% |
新映射器把「入口深度」从 4 级减到 2 级，相当于把「批量导入」从二级菜单提升到一级动作；再配合模糊匹配与三选一冲突策略，用户不再需要事先清洗链名大小写，也不必担心重复地址静默失效。
前置准备：拿到官方模板的最短路径
虽然映射器支持“任意列头”，但官方仍提供「最小可用模板」用于对照。获取方式：
- 移动端：钱包首页-地址簿-⊕-CSV 导入-底部「下载示例文件」。
- 桌面端：侧栏-地址簿-Import-「Template.csv」。
示例文件仅 5 行，包含 address、chain、name、note、tag 五列，可直接在 Excel/Numbers 打开。经验性观察：若你的原文件列数≥20，建议先删掉空列再上传，否则前端嗅探会多耗时 2–3 秒。
示例：把 DeBank 导出的「Portfolio」表格直接粘贴到模板右侧，再删除无用列，即可在 1 分钟内得到合规文件。
三步完成映射：以 10 万条空投地址为例
Step 1 上传与编码检测
在「CSV 导入」面板点击「选择文件」，SafeW 会先读取前 1 KB 判断编码。经验性结论：Windows 简体系统默认导出的 CSV 常为 GB18030，若出现“锟斤拷”乱码，映射器会弹窗提示「转 UTF-8 再试」。转码方法：Excel→另存为→CSV UTF-8（逗号分隔）。
Step 2 字段对齐
系统把嗅探到的列头横向排布，下方提供下拉框。核心必填只有两列：address、chain。name 若为空，系统会 fallback 为“Unknown_序号”。下拉框支持别名联想：
- address / wallet / addr / 地址 都会自动归一。
- chain / network / blockchain / 链 同理。
若你的表头为中文“链名称”，需手动选一次，系统会记住本次映射关系，下次导入同结构文件将自动匹配。
Step 3 冲突策略与预览
10 万条数据会按 500 行一页预览，底部统计重复地址数。冲突策略建议：
若本次 CSV 来自最新空投清单，选「覆盖」；若只是补充标签，选「重命名」可避免旧备注丢失。
点击「开始导入」，进度条走完会生成「导入报告」JSON，可一键导出留档。经验性观察：iPhone 13 导入 10 万行峰值内存占用 380 MB，低于 v5.3 的 620 MB，后台不会触发 iOS jetsam 机制。
平台差异与最短入口对照
| 平台 | 最短入口 | 离线可用 | 最大行数 |
|---|---|---|---|
| Android 5.4.0 | 钱包-地址簿-⊕-CSV 导入 | 是 | 10 万 |
| iOS 5.4.0 | 同 Android | 是 | 10 万 |
| macOS 5.4.0 | 侧栏-地址簿-Import | 是 | 10 万 |
| Windows 5.4.0 | 同 macOS | 是 | 10 万 |
桌面端由于 V8 内存限制更宽松，导入 10 万行时 CPU 占用峰值比移动端低 15%，适合做市商一次性更新白名单。
常见失败分支与回退方案
失败 1：提示「链名无法识别」
原因：列值写“BSC”，但 SafeW 期望“BNBChain”。处置：回到预览页，底部「批量替换」输入 BSC→BNBChain，再点「重新校验」。若链名不在官方 120 条白名单，系统会标记为「Custom」，风险雷达将跳过该地址扫描。
失败 2：导入后中文备注成问号
原因：文件为 ANSI 编码。可复现验证：用 VS Code 打开，右下角显示“GB2312”。回退：另存为 UTF-8 with BOM 后重新上传，SafeW 会正确显示生僻字。
失败 3：覆盖策略导致旧标签丢失
回退：导入前先在「设置-备份」导出 wallet_contacts.json 作快照，若需回滚，删除当前地址簿再重新导入快照即可。经验性观察：快照文件含 createTime 字段，SafeW 导入时会保留原时间戳，不影响按“添加时间”排序。
是否值得用？决策矩阵
| 场景 | 数量级 | 建议 | 理由 |
|---|---|---|---|
| 个人空投地址 | ≤500 | 手动 | CSV 准备时间＞直接复制 |
| 工作室女巫筛查 | 1 万–5 万 | 映射器 | 需统一链名，后续雷达扫描才准确 |
| 做市商白名单 | ≥10 万 | 映射器+覆盖 | 桌面端 64 位客户端内存可承受，且支持断点续传 |
与第三方协同：如何用 GitHub Action 每日自动更新
经验性方案：把 SafeW 导出的 wallet_contacts.json 存到私有仓库，GitHub Action 每日拉链上标签 API，生成新 CSV，再调用 SafeW-CLI（官方开源工具）上传。CLI 命令示例：
safew-cli contacts import --file nightly.csv --conflict rename --report /tmp/report.json
注意：CLI 需传入 --otp，因导入接口强制二次验证。权限最小化：GitHub Secret 仅存放「导入专用」OTP 密钥，勿放完整助记词。
风险控制：混币地址与合规边界
SafeW 链上雷达已把 Tornado Cash 相关地址标记为「高风险」。若 CSV 包含此类地址，导入后会在本地显示⚠️图标，但不会被自动删除。经验性观察：若你计划申请欧洲内测的 SafeW Card，建议先把高风险地址移入「观察钱包」分组，避免出金环节触发人工审核。
验证与观测方法
- 导入完成后，在「设置-关于-诊断」打开「地址簿统计」，可看到 totalContacts、chainDistribution 两个实时指标。
- 进入「链上雷达-扫描设置」，把「仅扫描已导入地址」开关打开，再点「立即扫描」，观测「风险分数>70」的地址数是否下降；若下降，说明映射成功。
上述两步可在 30 秒内验证主键对齐结果，无需人工逐条比对。
最佳实践 10 条速查表
- 永远先下官方模板，再把自己的列复制进去，避免列顺序错位。
- 链名一列用官方白名单，可减少 90% 的“无法识别”警告。
- 文件>5 MB 时，先用「拆分」工具切成 2 万行/片，桌面端导入更快。
- 中文备注里若含英文逗号，用双引号包裹整列，防止错位。
- 覆盖策略前，先导出 JSON 快照，回滚只需 10 秒。
- 空投猎人可把「交互日期」写进 note，后续按关键词筛选即可。
- 做市商把「持仓价值」写进 tag，风险雷达可单独扫描>10 kU 地址。
- 若用 Excel 另存 CSV，记得选「CSV UTF-8（逗号分隔）」而非「CSV（MS-DOS）」。
- CLI 自动化上传时，加 --dry-run 先看报告，确认无误再去真写。
- 每月清理一次「0 余额且高风险」地址，保持本地数据库<5 万行，移动端滑动更流畅。
未来版本展望
官方 GitHub Discussion 已透露 v5.5 将支持「双向同步」：本地映射变更后可回写至远程私有仓库，并增加 GraphQL 订阅接口，方便团队多人协作。若通过，地址簿将升级为「链上标签 CDN」，做市商与媒体节点可实时共享威胁情报，而 CSV 映射器只是入口，不再是终点。
结论
SafeW v5.4.0 的 CSV 字段映射器把「批量导入」从插件级玩具提升到企业级管线：10 万行容错、链名模糊匹配、冲突三策略、跨平台入口统一。只要按官方模板、UTF-8 编码、覆盖策略先快照，就能在 30 秒内完成地址簿初始化，后续风险雷达、闪兑白名单、匿名社交全部复用同一主键。对于空投猎人、做市商、记者三种典型场景，导入耗时从过去的 47 分钟降到 30 秒，且支持 CLI 自动化。唯一需要注意的是：混币地址仍会被本地标记，若计划未来使用 SafeW Card 出金，应提前把高风险地址隔离到观察分组。随着 v5.5 双向同步的到来，CSV 映射器将成为链上标签 CDN 的本地缓存入口，值得现在就把流程跑通。
常见问题
映射器是否支持自定义链？
支持。链名不在官方 120 条白名单时会被标记为「Custom」，后续风险雷达将跳过该地址扫描，但闪兑白名单与地址标签仍可正常调用。
导入报告包含哪些字段？
报告为 JSON 格式，含 total、success、failed、duplicate、customChain 等计数，以及逐行错误提示，可用于 GitHub Action 自动告警。
能否回滚已覆盖的数据？
可以。导入前导出 wallet_contacts.json 快照，需要回滚时清空地址簿再重新导入快照即可，系统会保留原 createTime 时间戳。
移动端 10 万行会卡死吗？
经验性测试 iPhone 13 峰值内存 380 MB，低于 iOS jetsam 阈值；Android 8 GB 机型同理。官方采用分页预览+Web Worker，不会阻塞 UI。
CLI 的 --otp 如何自动化？
把 TOTP 密钥存为 GitHub Secret，Action 运行时通过 oathtool 生成动态码，再传给 safew-cli --otp ${{ steps.totp.outputs.code }} 即可。