fluxmount

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   # 查看所有 NTFS 盘的可读写状态
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 一次）

1. 打开 系统设置 → 隐私与安全性
2. 找到"来自开发者 Benjamin Fleischer 的系统软件已被阻止"，点【允许】
3. 重启电脑
4. 重启后插上 NTFS 盘，等 5~8 秒即自动可读写，无需再敲命令

4. 验证

mount | grep macfuse              # 应看到 (macfuse, ... rw ...)
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 写操作，验证需用户本机执行。