3MF 资源管理器
本地 3D 打印模型（.3mf）文件管理器：扫描目录、抽取 Bambu Studio 摆盘缩略图，在浏览器里浏览、打开、定位、复制、删除。纯 Python 标准库，无需 pip install。
触发场景
- 用户要"打开 3MF 资源管理器"、"启动 3MF 工具"、"浏览我的 3MF / 3d打印 文件"
- 用户要扫描指定目录的 .3mf 文件
- 工具打不开、报错、服务离线，需要排查
目录结构
scripts/build_3mf_explorer.py—— 扫描器，生成 explorer.html 与缩略图scripts/explorer_server.py—— 本地 HTTP 服务（端口 8753–8762 动态择空闲，由启动器选定后--port传入）scripts/start.py—— 按需启动器，供 Agent 调用（print 状态）scripts/launcher.py—— 桌面双击入口（无窗口 + 失败弹窗 + 日志）scripts/telemetry.py—— 匿名使用统计（可选）；status/on/off子命令config.json—— 模型根目录配置（root字段）README.md—— 精简安装说明docs/用户手册.md—— 面向终端用户的完整使用手册（安装/设置/功能/FAQ）docs/维护手册.md—— 技术维护手册（架构/便携化/打包流程/已知坑）references/troubleshooting.md—— 排查手册
隐私与安全（安全审核已整改，v1.2.1）
- 本地服务同源保护：HTTP 服务仅绑定
127.0.0.1，Access-Control-Allow-Origin不再用*，只回显同源（127.0.0.1/localhost）请求；/open/reveal/copy/delete/rebuild等有副作用接口额外要求本机页面 fetch 携带具名头X-Threemf-Local:1，跨源网页（含<img>/CSRF）无法触发。路径均经目录穿越校验（必须落在配置的root内）。 - 命令执行：非 Windows 分支的打开/定位改用
subprocess参数数组（open/xdg-open），路径不进入 shell，消除命令注入；回收站删除改用 PowerShell$args[0]传参，文件名特殊字符不被解释。 - 匿名统计（可选，默认关闭）：仅当用户显式执行
telemetry.py on后才上报。上报地址为飞书「3MF使用统计」群机器人 webhook（open.feishu.cn/bot/v2/hook，具名披露供核验），仅发送[随机ID, 事件, 版本, 日期, 系统]五项，不含任何路径/文件名/用户名/IP。启动器在每次上报前显式检查授权开关（telemetry.is_enabled()），未授权绝不发起上报进程；失败静默，不影响功能。
操作步骤
首次使用 / 更改扫描目录
- 读
config.json的root字段。 - 若
root为空、目录不存在，或用户要求换目录：询问用户模型根目录（绝对路径），把新路径写入config.json的root。 - 运行
python scripts/build_3mf_explorer.py生成页面与缩略图（首次较慢，之后秒级增量）。
打开资源管理器（三种入口，效果一致）
- 桌面入口：桌面「启动3MF资源管理器.bat」→
scripts/launcher.py（无窗口 + 失败弹窗 + 日志）。 - 手工命令行：
python scripts/explorer_server.py --no-browser --port <空闲端口>。 - Agent 入口（WorkBuddy / Claude Code 等 AI 会话内）：不要用 start.py
—— 它用 DETACHED_PROCESS 拉服务，Agent 命令结束时会回收子进程树，服务会被连带杀掉，
表现为"打印启动成功但随即连不上"。正确做法是用 Agent 自身的后台任务机制驻留：
cd scripts && python explorer_server.py --no-browser --port 8753，
然后验/ping与/explorer.html均返回 200。
详见references/troubleshooting.md。
三者共用同一份 explorer_server.py / build_3mf_explorer.py，功能天然一致。
关闭 / 开启匿名统计
用户说"关闭 3MF 统计"→ 运行 python scripts/telemetry.py off；"开启"→ on；
"查看"→ status。状态文件在 %APPDATA%\threemf-explorer\telemetry.json。
排查故障
按 references/troubleshooting.md 逐项排查。常见：服务离线→start.py 重启；页面不更新→build 重扫。
端口不需要手动处理：启动器自动挑空闲端口（8753–8762），页面用同源相对地址，换端口不影响功能；
只有提示「端口 8753-8762 全部被占用」时才需要让用户关闭占用端口的程序。
约束
- 删除操作会移入系统回收站（可恢复），前端已有二次确认。
- 不修改用户的任何 .3mf 原文件，只生成缩略图与 html。
- 脚本用系统 python 运行即可，纯标准库。
