| name | fluxmount |
| version | 1.0.0 |
| description | FluxMount - 让 macOS 自由读写外接 NTFS 硬盘，傻瓜式、一次到位、插上即用、不再复发。当用户把 NTFS 格式的移动硬盘或 SSD 接到 Mac 却无法写入或复制文件、抱怨各种插件都传不进去、问 Mac 怎么往 NTFS 盘里写文件、或想要开机与热插拔自动可读写挂载时使用。覆盖国内网络典型坑（GitHub 被墙、Homebrew Tier-3 无预编译包、新版 Clang 编译报错、launchctl 弃用、沙箱禁 sudo），并提供一键安装、健康自检与干净卸载。作者 张昌宇 (Changyu Zhang)。 |
| agent_created | true |
FluxMount (macOS NTFS Read-Write)
让 Mac 自由读写外接 NTFS 硬盘。底层基于开源的 macFUSE + ntfs-3g，并配套开机与热插拔自动挂载，做到"插上即用、不再复发"。作者：张昌宇 (Changyu Zhang)，协议 MIT。
什么时候用这个 skill
- 用户把 NTFS 格式外接硬盘接到 Mac，能看不能写 / 复制失败 / 插件传不进文件。
- 用户问"Mac 怎么写 NTFS""有没有免费 NTFS 工具""能不能让盘自动可读写"。
- 用户已装过驱动但仍只读，需要排查（系统扩展未批准 / 免密 sudo 未配 / 代理未注册）。
根因（务必先讲给用户听）
macOS 原生对 NTFS 只支持只读挂载。无论用什么 App、插件、脚本，只要系统把它挂成只读，谁都写不进去。这不是插件不行，是系统层面锁了写权限。解法不是找更强插件，而是用 ntfs-3g 把它重新挂成读写。 用户盘里的数据不会被改动（我们只是重新挂载，不删不改任何文件）。
工作流程
1. 识别硬盘（只读命令，无需 sudo）
diskutil list
system_profiler SPStorageDataType | grep -iA6 ntfs
mount | grep -i ntfs
确认磁盘节点（如 /dev/disk12s2）、卷名，以及它被 macOS 以 (ntfs, ... read-only ...) 只读挂载。
2. 一键安装（用户本机终端运行）
把 skill 的 scripts/ 目录复制到本机后运行：
bash install.sh
bash install.sh --doctor
bash install.sh --status
bash install.sh --dry-run
install.sh 会自动：检测系统 → 装 macFUSE（国内镜像兜底 GitHub 被墙）→ 装 ntfs-3g（用 brew tap gromgit/homebrew-fuse + brew install ntfs-3g-mac，规避 Homebrew Tier-3 无包）→ 部署脚本到 /usr/local/bin → 配置免密 sudo → 注册开机 + 热插拔自动挂载（LaunchAgent，现代 bootstrap 方式）→ 立即挂载一次。安装前会自动备份被覆盖的文件到 ~/.fluxmount-backup，可随时回退。
注意：沙箱/远程环境通常禁止 sudo 与 launchctl 写操作，安装与批准系统扩展必须在用户真实终端完成，本 skill 负责生成脚本与指引，不会在你的电脑上做不可控的改动。
3. 用户只需一次的人工步骤（每个 Mac 一次）
- 打开 系统设置 → 隐私与安全性
- 找到"来自开发者 Benjamin Fleischer 的系统软件已被阻止"，点【允许】
- 重启电脑
- 重启后插上 NTFS 盘，等 5~8 秒即自动可读写，无需再敲命令
4. 验证
mount | grep macfuse
bash install.sh --doctor
Finder 里直接往盘里拖文件即可。用完安全弹出：diskutil unmount /Volumes/<盘名>。
资源
scripts/mount-ntfs-rw — 核心挂载脚本（多盘、幂等、退避重试、写权限校验、--dry-run、--status 状态查询）scripts/ntfs-automount — LaunchAgent 热插拔入口scripts/install.sh — 傻瓜式一键安装 + doctor 自检 + dry-run 预览scripts/uninstall.sh — 干净回滚（恢复安装前备份）references/troubleshooting.md — 排障手册（吸收竞品经验 + 国内网络坑）README.md — 面向 GitHub / SkillHub / ClawHub 的发布文档与竞品对比SAFETY.md — 安全与可回退说明（明确本工具改什么、不动什么、如何还原）manifest.yaml — OpenClaw / ClawHub 跨平台元数据
本 skill 相对竞品的特色（作者沉淀）
- 国内网络专治：macFUSE 下载走 kgithub / ghproxy 多个国内镜像兜底；ntfs-3g 用 gromgit tap 的
ntfs-3g-mac（有预编译包），避开 Homebrew 对旧 macOS 的 Tier-3 无包与 GitHub 被墙。
- 傻瓜式一次到位：单命令安装 + doctor 自检 + dry-run 预览，把"系统扩展批准 / 免密 sudo / 代理注册"三件最容易翻车的事都自动化或半自动化。
- 防复发：开机（RunAtLoad）+ 热插拔（StartOnMount）双触发；幂等（已可读写则跳过，不干扰正在用的盘）；指数退避重试 + 写权限校验。
- 多盘支持：遍历所有只读 NTFS 分区逐个重挂载，挂回原卷名（Finder 名字不变）。
- 安全可控：免密 sudo 仅放行
mount-ntfs-rw 一条命令；安装前自动备份被覆盖文件，uninstall 可完整还原；只重挂载、绝不删除或改动盘内数据。
踩坑经验（已固化到 troubleshooting.md）：GitHub 被墙用国内镜像；Homebrew brew install ntfs-3g 在 2026 年 macOS 15 Intel 上因 Tier-3 无 bottle 失败，应改 ntfs-3g-mac；新版 Xcode/Clang 把隐式函数声明当硬错误导致源码编译失败；launchctl load 在 macOS 15 已弃用，改用 launchctl bootstrap gui/$(id -u)；Bash 工具沙箱会禁 sudo/launchctl 写操作，验证需用户本机执行。
