3D Filament Tracker#

把散落在淘宝/京东/拼多多订单截图里的 3D 打印耗材，整理成一张可交互的库存表。

触发方式#

• 用户说「统计一下我的 3D 打印耗材」/「3D 耗材库存」/「filament tracker」
• 用户给一堆订单截图说「帮我看看买了哪些料」
• 用户问「我还剩多少卷 PLA」/「哪些颜色已经在用了」
• /3d-filament-tracker

它解决什么#

3D 打印耗材一买就是几十卷，散在多个店铺多个订单里。 靠脑子记不住：哪个颜色买了几卷？哪些已经塞进打印机了？哪些用光了？哪些还在库存？

传统方案：

• Excel —— 每改一次状态都要手动算合计，没颜色提示
• 拍照堆桌上 —— 不知道总数也不知道库存
• Bambu Studio 内置料盘 —— 只管插上去那一卷，不管库房

这个 skill 给你一份 单文件 HTML 跟踪器：浏览器打开就能用，状态存在 localStorage，可导出 JSON 备份。

核心交互模式：双步进器 + 现有数联动#

每行耗材有两个状态：

text

原始购买数 = 现有 + 已用光
现有       = 在用 + 库存

UI 上每行两个步进器：

text

[在用 −  N/总  +]   [已用 −  N/总  +]
 绿色背景           灰色背景

约束： 在用 + 已用 ≤ 总卷数（步进器自动 disable）

「已用」+1 时全部联动重算：

• 该行「现有」列减 1
• 该颜色合计减 1
• 该材料小计减 1
• 顶部 pill：现有合计 −1 / 已用光 +1
• 「库存」pill：减 1

「在用」+1 时不影响现有数（耗材还在你手上），只是把它从库存挪到在用。

流程#

Phase 1：读图整理#

1. 用 Read 工具读用户给的所有订单截图（一次可读多张）
2. 提取每条订单的： 材料（PLA / PETG / ASA / PA / TPU / PC...）+ 品牌/系列（拓竹 PLA Basic / POLYMAKER 高速 PETG / 三绿 PLA Matte...）+ 颜色 + 卷数 + 来源标记（散装 / 套装 / 赠品 / 赔付）
3. 用一个 Markdown 表先给用户对一遍。 不要一上来就生成 HTML，先确认数据，往返几轮把数字校准
4. 同色不同来源（散装+套装+赔付）拆成多行，每行带「来源」标签，便于追踪到底是哪一卷在用
5. 套装也按颜色拆开统计， 不要按套装维度计数（套装是采购概念，颜色是使用概念）

Phase 2：生成 HTML#

用 templates/template.html 作为骨架，填充用户的实际数据。每行 <tr> 必须有 data-id（kebab-case，例 pla-black-散装），唯一即可。

关键 CSS class：

• material-pla / material-petg / material-asa —— 左侧色条
• tag-pla / tag-petg / tag-asa —— 行内标签
• color-total —— 同色合计行
• total-row —— 材料小计行
• group —— 材料分组标题行
• badge-set / badge-gift —— 套装/赠品标记

每个色组结束插一个 <tr class="color-total"> 显示合计；每个材料块结束插一个 <tr class="total-row">。这两个的「卷数」单元格内容由 JS 自动重算，初始填什么数字都行。

Phase 3：交付#

• HTML 文件放到 <workspace>/3d-printing/耗材/耗材统计.html
• 截图也放在同目录
• 提示用户： 第一次点完后立刻点「📥 导出状态」存一份 JSON，搬目录或换浏览器就靠这份恢复

关键工程点（不要踩坑）#

1. localStorage 按文件路径隔离#

• file:///Users/.../耗材统计.html 和 file:///Users/.../moved/耗材统计.html 是两个独立 origin，状态不会自动迁移
• 所以必须提供 JSON 导出/导入
• 搬目录前先让用户导出一份；移完再让用户重新导入

2. 「现有」≠ 「原始」#

• 「卷数」列显示的是 现有（= 总数 − 已用），会随交互变化
• 步进器分母固定显示 原始购买数，所以用 data-total 锁住，不能从 .qty 单元格读
• 初始化时把 HTML 里写死的初始 .qty 值 snapshot 到 tr.dataset.total，之后所有读数走 getTotal(tr) 而不是 parseInt(qty.textContent)

3. 合计行不能 hardcode#

• 颜色合计 / 材料小计 / 总计 全部由 JS 重算
• HTML 里写的初始数字只是占位，加载时 recomputeAggregates() 立刻覆盖
• 重算逻辑：从上往下遍历 tbody，遇到 .group 行重置 colorAcc/materialAcc，遇到 [data-id] 行累加 (total − consumed)，遇到 .color-total 写 colorAcc 并清零，遇到 .total-row 写 materialAcc 并清零

4. 双步进器互相约束#

• 在用 + 已用 ≤ 总数
• 单步进器自身能减到 0
• 任何一个 +1 之前先检查 next + other > total ? return : commit
• disable 状态算 (using + consumed) >= total 时 + 按钮全部 disable

5. JSON 兼容旧版本（v3 → v4）#

• 早期版本只有「在用」一个值，state 是 {id: number}
• 现在 state 是 {id: {using: N, consumed: M}}
• importState 时检测 typeof v === 'number' → 自动迁移成 {using: v, consumed: 0}

视觉规范#

整行底色根据状态：

• 浅 绿 = 该批次全在用
• 浅 黄 = 部分在用
• 浅 灰 + 删除线 = 全部用光
• 白 = 全在库存

色卡（ .swatch）尽量贴近实物颜色：

• 拓竹 PLA Basic 系列用商品页配色
• Silk 系列用 linear-gradient 模拟丝绸渐变
• 透明色用半透明
• 实在拿不准就用 #7f8c8d 灰

不要做的事#

• ❌ 不要用复杂前端框架（React/Vue）—— 单文件 HTML + 原生 JS，用户双击就能用
• ❌ 不要把状态存到外部数据库 —— localStorage + JSON 文件就够了
• ❌ 不要按套装维度统计 —— 用户关心的是颜色，不是 SKU
• ❌ 不要改步进器分母 —— 分母永远是原始购买数，让用户能看到"我之前总共买过几卷"
• ❌ 不要在 HTML 里硬编码合计数字让它和 JS 不同步 —— 合计永远 JS 算

同步发布#

跟着 [[feedback_skill_publishing_flow]] 走：公网 GitHub + ClawHub。这个 skill 不涉及 SAP 业务， 不推 SAP 内网。