MWI 市场伴侣 · 功能说明文档
写在前面
⚠️ 关于合规性说明
本插件不包含任何自动购买功能，因自动功能会违反游戏规则第4.2条。
✅ 本插件：在客户端直接跳转到市场中某个物品的页面。这与玩家手动 Shift 点击背包中的物品效果完全一致。
❌ 违规插件：提供一键完成多种物品的批量购买。这会批量向服务器发送请求，属于自动化操作。
因此，所有的购买行为均需玩家手动操作
插件仅负责帮你找到物品、算清数量，剩下的交给你来完成。
如果你不信任一键跳转市场的功能，插件亦提供了购物车内物品在市场内高亮的功能。
插件已提交管理员查看，1.4.1起一切功能均确保合规。
一、插件简介
本插件的核心功能是制作缺料的计算助手与手动采购辅助工具。当你打开任意制作弹窗时，它会自动分析当前制作动作所需的材料，精准计算出你还缺少哪些、缺少多少，并可添加至购物车内，帮助你快速跳转到市场对应的物品页面。
v1.3.0 起，插件核心数据来源从 DOM 解析迁移至游戏数据层（initClientData），配方数据更精确，并自动计算工匠茶等 buff 对材料消耗的影响。
v1.3.1 新增市场弹窗自动预填缺料数量和采购导航条，大幅提升连续采购多种材料的效率。
v1.3.5 新增制作计划与库存锁定机制，解决多配方共用材料时的缺口误算问题。
v1.4.0 新增英语界面支持（双语 i18n），可在设置面板中切换插件语言。
v1.4.1 移除采购自动跳转功能，改为导航栏内联购齐横幅，所有市场页面跳转均由玩家手动点击触发，确保合规。
v1.4.2 新增 Z-score 安全边际概率模型、升级链树形展示、任务追踪面板，并移除多余的回退跳转方案，进一步确保合规。
v1.4.3 新增余量标记与升级链步骤筛选，金币不再参与工匠茶减免计算，设置面板新增功能建议与打赏入口。
v1.4.5 修复脚本加载时机导致部分用户库存读取失败的问题，全链材料加入购物车时同步创建制作计划，新增使用说明页面入口，社区反馈支持完成标记。
v1.4.6 升级链「加入全链材料」现在为每个勾选步骤创建独立制作计划，路过产物的材料也能正确锁定库存，解决多条升级链共享中间材料时缺口误算的问题。
v1.4.7 修复全链材料加入购物清单时未扣除已有购物车数量的问题，升级链树展示中材料可用库存现在正确扣除购物车已认购量。
v1.5.0 新增购物清单市场价格显示与预估总价栏，设置面板按功能分组归类，语言检测改为始终跟随游戏设置。
v1.6.0 深色主题视觉大更新（接近纯黑底 + 琥珀金主色），设置项改为滑动开关，设置面板重排为 4 组分类，修复拖动调整面板尺寸的相关问题。
v1.6.1 制作面板新增「被其他计划锁定」提示：材料行徽章尾部显示 🔒N，摘要行新增琥珀色锁定标签，悬停查看每个计划各锁多少。消除"库存明明够为什么还显示缺"的困惑。
v1.7.0 新增对外公共 API window.MWIMM，开放给其他用户脚本读写购物车、监听变化、跳转市场（完整文档随脚本顶部注释一并发布）；新增「采购下一个 快捷键」，购齐当前物品时按一下自定义键即可跳到下一个待购物品的市场页，单键与组合键均支持。
📖 完整使用说明请访问：https://mate.colacola.cloud/guide
💬 功能建议与社区反馈：https://mate.colacola.cloud/community
二、致谢名单
优化思路提供
- Mooooooooo
- AlphB
- wangchyan
- mutallip
- Foreversunny与他的朋友们
- Joey
- baozi
- Star
BUG反馈
（排名不分先后）
三、更新日志
v1.7.0
新增
- 公共 API（
window.MWIMM）：暴露给其他用户脚本/插件读写购物车、监听变化、跳转市场。提供 addToCart / setCartItemQuantity / removeFromCart / clearCart 写入方法，getCartItems / getCartItem / hasCartItem / getCartCount 读取方法，以及 resolveItemName / openMarketplace / normalizeItemId 辅助方法；事件订阅支持 ready（插件就绪，晚到的监听器会立即触发一次）与 cart:change（购物车持久化时广播最新快照）。完整使用文档已写在脚本顶部注释里，含中英文双语字段说明与示例代码
- 「采购下一个」快捷键：购齐当前物品且购物车还有下一个待购物品时，按下自定义快捷键即可跳转到下一个物品的市场页（等同于点击横幅上的「Next item ▶」按钮）。设置面板「市场与采购」分组新增「采购下一个 快捷键」一行，点击进入捕获模式按下任意键组合即可绑定，支持单键（Space / Q / F5 …）也支持组合键（Ctrl+Shift+N …）；Esc 取消，点按钮以外区域亦可静默退出
- 横幅快捷键徽章：购齐横幅上、「Next item ▶」按钮旁多了一个键盘徽章，已设置时显示当前快捷键，未设置时显示「未设置快捷键」并可点击直达设置面板对应行（黄色高亮闪烁 1.6 秒）。徽章只在横幅显示时存在，不占用常驻 UI 空间
改进
- 购物车写入路径拆分：内部把
addToCart 拆成 _addToCartCore（仅写、不持久化）+ 包装器，让 API 数组写入只触发一次 saveCart 与一次 cart:change 广播，避免重复 IO 和重复重渲染
安全网
- 快捷键作用域严格隔离：仅在「物品购齐 + 购物车还有下一项」事件触发后才装填；按下消费、目标已被外部移除/清空、新一轮购齐事件覆盖，以及「全部购齐」事件均会自动卸下；横幅淡出 ≠ 卸下（仍可后悔再按）。
input / textarea / select / contenteditable 聚焦时全局监听一律放行，聊天框打字百分百不受影响。捕获模式下点击按钮以外任意位置自动取消，不会卡死全局热键
v1.6.1
新增
- 材料行锁定提示：制作面板每个材料的徽章尾部新增
（🔒N） 后缀，显示该材料被其他计划占用的总量；徽章 hover 完整列出每个计划各占用多少
- 摘要行锁定汇总：数据层/工匠/已有计划标签旁新增琥珀色「🔒锁 N 种」标签，hover 显示每种材料被哪些计划按多少锁定
- 升级材料同等处理：升级链材料行的锁定提示与主材料行保持一致
改进
- 防异常换行：徽章加
white-space: nowrap，防止长数字下徽章内部字符被浏览器在括号、空格处断开（该修复对所有徽章生效，包括原有的缺料/余量徽章）
底层
- 新增
getLockedDetails() 函数：与 getEffectiveInventory 对称，同一套遍历逻辑分别返回"有效库存"和"锁定明细"，保持现有算法不动
- 摘要面板 structKey 新增
hl 维度：锁定存在性切换时触发 DOM 重建，纯数字变化走快路径，避免抖动
- 零 localStorage 新 key，向后 100% 兼容，可一键回滚到 v1.6.0 不留残留
v1.6.0
视觉更新
- 深色主题：面板底色从深灰蓝换成接近纯黑（
#08080e），主色统一为琥珀金（数量、价格、市场高亮等），文字层级改用白色透明度阶梯
- 滑动开关：设置项的开关从文字按钮改为滑动开关样式（琥珀金激活 + 圆形 thumb 动画）
- FAB 金色气泡：购物车未补齐数量的气泡改为金色发光，数字放大加粗
- Toast 放大：右上角消息字体从 12px 加大到 14px，padding 相应加大
设置面板重排
- 从三组重排为四组：显示 / 计算 / 市场与采购 / 界面与同步，按使用频率排序
- 分组标题重构：去除突兀的横线，用留白做分隔，颜色统一为柔白
- 保留所有配置：开关的 localStorage 键值完全不变，原有设置自动继承
修复
- 面板尺寸"拉回"问题：购物车为空时拖动 resize 手柄，松手后面板不再被内容缩回，拖多大就保持多大
- F12/窗口缩放后位置与尺寸自动恢复：打开 DevTools、调整浏览器窗口、缩放页面（Ctrl±）等场景下，FAB、购物车面板、制作计划面板的位置和尺寸只做"视觉临时 clamp"，不再把 clamp 结果写回 storage 覆盖原始值；可视区域恢复后，UI 自动回到用户原本拖到的位置
- 市场价格刷新秒加载：价格请求加超时保护 + localStorage 缓存（1 小时内命中缓存，不发网络请求）
- 手动修改数量保护：手动改数量后 5 分钟内不被自动同步覆盖，解决囤货物品被自动回填改回的问题
- 多处稳定性修复：Observer 收窄到游戏容器避免无谓刷新、监听器重绑防累积、WebSocket 拦截防重装、定时器生命周期管理、版本号统一
底层
- CSS 变量化：提取 79 个设计 token 到
:root{} 块，后续调整配色只改一处
v1.5.0
新增
- 市场实时价格：购物清单内显示物品的市场价格（数据来源：
marketplace.json API），展示单件价格与行小计。价格优先级：卖单价 > 买单价 > 均价
- 购物车总价栏：购物清单底部显示预估总花费，无市场价格的物品单独标注数量
- 设置面板分组：设置项按「市场与采购」「制作辅助」「系统」三组归类，附分组标题
- 价格显示开关与总价开关：可独立控制每行价格信息和底部总价栏的显示
改进
- 语言检测改进：移除手动语言切换按钮，始终跟随游戏
i18nextLng 设置，切换游戏语言后插件自动同步
v1.4.8
新增
- 自动语言检测：首次安装时自动读取游戏语言设置（
i18nextLng），无需手动切换插件语言。已手动设置过语言的用户不受影响
改进
- Housing 面板签名缓存：房屋建造面板的数据未变化时跳过 DOM 写入，减少与其他插件（Toolasha / Shopping List）同时运行时的 MutationObserver 连锁触发
- 全链路错误捕获：刷新流程中的数据提取、徽章渲染、摘要面板渲染均增加独立的 try-catch 保护，错误信息输出到控制台而非静默失败。渲染失败时自动清除签名缓存以确保下次刷新重试
- 控制台版本号统一：所有 console.log 中的版本号改为动态读取
SCRIPT.version，不再硬编码旧版本号
v1.4.7
修复
- 全链材料购物车去重：「加入全链材料」时，计算缺口后扣除购物车中已有的数量，只添加净增量到购物清单，避免重复添加导致采购数量偏多
- 升级链树库存扣除购物车认购量：升级链树展示中，材料的可用库存现在正确扣除购物车已认购量，缺口显示更准确
v1.4.6
改进
- 逐步制作计划：「加入全链材料」现在为每个勾选步骤创建独立制作计划（而非仅最终产物一个聚合计划）。路过产物的材料独立锁定库存，解决多条升级链共享中间材料时缺口误算的问题
- 链内库存显示优化：升级链树的材料库存计算现在排除自身链所有步骤的锁定，仅受其他链计划影响，显示更准确
- 逐步进度追踪：制作中间步骤时 WS 事件能正确匹配对应步骤的计划，进度条逐步更新
v1.4.5
修复
- WS 库存读取时机：将脚本加载时机从
document-idle 改为 document-start，WebSocket 拦截提前至脚本顶层执行，修复部分用户因脚本加载晚于游戏 WS 初始化导致库存数据缺失的问题
新增
- 全链材料同步制作计划：升级链「加入全链材料」时自动创建/更新制作计划，锁定全链叶子材料的库存。取消勾选步骤后重新点击可正确回退锁定范围，避免多链共享材料时的缺口误算
- 使用说明页面：新增 mate.colacola.cloud/guide 使用说明页面，支持中英双语。设置面板新增「📖 使用说明」按钮
- 反馈完成标记：社区反馈支持「✅ 已解决」状态标记，前端自动显示完成徽章
v1.4.3
新增
- 余量标记：材料充足时显示蓝色「余 X」徽章，直观展示做完后还能剩余多少材料。升级链树和升级物品行同样支持余量显示
- 升级链步骤筛选：升级链树的每个步骤标题前新增复选框，点击「加入全链材料」时仅添加勾选步骤的材料，方便跳过不需要制作的低级步骤
- 功能建议与打赏入口：设置面板底部新增「💡 功能建议」和「❤ 打赏作者」按钮，跳转至外部页面提交建议或查看打赏排行
修复
- 金币不参与工匠茶减免：金币消耗不再受工匠茶 buff 和 Z-score 安全边际的影响，改为线性计算，缺料结果更准确
- 同配方多任务计划累加：多个任务使用相同配方时，制作计划的次数和材料锁定量正确累加，而非覆盖
v1.4.2
新增
- Z-score 安全边际：基于二项分布的材料安全边际概率模型，支持 Z-90%/95%/99%/99.9% 四档置信度，缺料徽章显示
需求量⁺安全边际 格式。设置面板新增 Z-score 等级和暴饮袋子等级选项
- 升级链树形展示：升级链配方（如装备升级序列）自动在摘要面板中展示完整链树，列出每步所需材料及缺口。支持展开/收起切换。新增「加入全链材料」按钮，一键汇总全链叶子材料加入购物清单
- 任务追踪面板：购物清单新增任务面板，显示当前活跃生产任务的进度，提供「补缺料」和「建计划」快捷按钮。通过 WS 实时更新任务状态
合规性改进
- 移除回退跳转方案：删除
openMarketplaceByVisibleMenu 函数（通过模拟点击物品+菜单跳转市场的方式），市场跳转现在仅使用 React 内部方法，严格保证 1:1 人机操作对应
v1.4.1
变更
- 移除「采购自动跳转」功能：根据mo9反馈，购买完成后自动导航至下一个物品的市场页面不符合 1:1 人机操作对应规则（一次人类操作应只产生一个服务器请求）。该功能及其设置开关已被完全移除
新增
- 导航栏内联购齐横幅：当某物品购齐并从购物清单移除后，采购导航条内会滑入一条内联横幅，显示购齐提示和下一个待购物品信息，附带「采购下一个 ▶」按钮。点击按钮才会跳转到下一个物品的市场页面，确保每次市场页面跳转都由玩家手动触发
- 全部购齐横幅：购物清单全部购齐后，导航栏显示「🎉 购物清单全部购齐！」完成提示，5秒后自动淡出
清理
- 移除
_tryAutoAdvanceMarket 函数及所有调用
- 移除
STATE.autoAdvanceEnabled 及其持久化逻辑
- 移除设置面板中「采购自动跳转」行及事件处理
- 移除相关 i18n 键（
s_auto_advance、toast_advance_on/off、toast_auto_jump、toast_all_purchased）
v1.4.0
新增
- 双语支持（i18n）：插件界面新增英语支持，所有 UI 文本（按钮、标签、Toast 提示、设置面板等 120+ 处）均已翻译。设置面板底部新增「界面语言 / Language」开关，点击可在中文与英语之间切换
- 物品名称双语解析：从游戏 i18n 资源中分别提取中英文物品名称映射，切换语言后购物清单和导航条中的物品名称自动更新为对应语言，无需重新添加
优化
- 面板默认宽度加宽：从 346px 调整为 390px，适配英语界面下较长的按钮和标签文本
- 变量遮蔽修复：修复
getItemName 内部 const t 遮蔽全局翻译函数 t() 导致回退路径崩溃的问题
修复
- 强化面板库存归零：修复同物品多个强化等级条目互相覆盖导致库存显示为 0 的问题。改用 hash 主键存储，仅聚合 inventory 位置的物品
- 暴饮袋子加成丢失：修复
_detailMap 仅含背包物品后找不到装备栏暴饮袋的问题，改用 getEquippedLevel 从全位置 hashMap 查找
- 工匠茶检测不稳定：优先使用 WS 截获的饮品插槽数据（
actionTypeDrinkSlotsMap），React Fiber 作为回退
- 强化面板重建冷却：游戏每次强化完成后会拆毁并重建面板 DOM，空白期间新增 6 秒冷却保护，防止数据闪烁
- 跨面板 tab 干扰：
isCurrentActionMode 将 tab 搜索限定在 modal 所属的面板容器内
v1.3.6 及更早版本
- 核心功能上线：缺料自动计算、购物清单、市场跳转与高亮
- 游戏数据层接入（
initClientData），生产配方不再依赖 DOM 解析
- 工匠茶与暴饮袋子自动计算材料减免，数据来源标记可视化确认 buff 状态
- 炼金、强化等动态输入场景智能回退 DOM 解析
- WebSocket 精确库存追踪，购买后自动扣减购物清单
- 市场弹窗预填缺料数量、采购导航条、WS 市场数据缓存
- 制作计划与库存锁定：自动创建制作计划并锁定材料，解决多配方共用材料时缺口误算
- 制作计划面板：独立侧面板查看进度与锁定详情，支持编辑制作次数
- WS 实时追踪制作进度，完成后自动释放锁定库存
- 收藏保护、常备数量、补齐自动收起
- 清空分级（主按钮清非收藏 / 下拉清全部）
- 房屋建造面板缺料计算支持
- "当前行动"界面手动输入计划次数
- 面板拖动、锁定、调整大小、物品搜索、数量可编辑、从背包添加
- 多版本稳定性修复与优化
