技能介绍

要解决的问题

macOS 在 Finder 操作中会悄悄给文件附加 .DS_Store、._* AppleDouble、__MACOSX 目录、资源叉和 com.apple.metadata:* 扩展属性。这些元数据一旦混入复制、Git 提交、CI 产物、SCP 传输或归档，交付物就被污染：跨平台同事拉到 ._foo.js，CI 归档里夹带资源叉记录，干净仓库的 git status 突然多出一堆无用变更。.gitignore 挡不住已跟踪文件、Hook 和 SCP 暂存区；Finder 的"压缩"也不会替你清理这些内容。

技能如何工作

该技能围绕随附的 scripts/macos_hygiene.py CLI 组织，默认只检查、不改动：

scan：扫描工作区；--format json 输出机器可读结果，--xattrs 显式读取会随传输进入载荷的 FinderInfo、ResourceFork 与 com.apple.metadata:*
clean：先预览，仅在用户明确授权后加 --apply 清理高置信垃圾；不确定项转人工复核，不擅自删除
check-git --scope all：覆盖工作区、暂存区和已跟踪路径
install-repo-guard --ci both：安装本地 Hook、仓库内工具与 CI 模板（GitHub Actions / GitLab CI，Python 3.11 与 3.14 矩阵）；Hook 可被 --no-verify 绕过，CI 门禁才是硬约束
stage --manifest / scp --manifest-out：构造无污染传输副本并生成 SHA-256 审计清单
archive create / archive verify：验证归档完整性、危险路径/链接、资源上限和元数据污染

退出码语义明确：0 通过、1 发现策略违规、2 运行错误，可直接用于流水线阻断。

适用边界

目标是交付物卫生，不是让本机磁盘永不产生元数据；工具不改全局配置和用户 Shell 配置
CI 上必须按环境收紧 --max-members、--max-total-bytes、--max-member-bytes、--max-compression-ratio 等归档上限
归档验收只检查 ZIP/TAR 内部成员路径与属性记录，宿主文件的文件系统 xattr 不属于归档内容
com.apple.provenance 等宿主层属性不等同于载荷污染，需存储或传输端另行治理
无法防御同 UID 的恶意本地进程；发布前应确认扫描、check-git、暂存清单与归档验证均返回 0，CI 失败时阻断流水线

截图预览

使用场景

macOS 开发者发布前用 scan --xattrs 清理 .DS_Store、._*、__MACOSX，并用 check-git --scope all 阻断污染提交。
维护 GitHub Actions/GitLab CI 的工程师用 install-repo-guard --ci both 在 Python 矩阵运行检查，合并前阻断违规。
通过 SCP 向外部交付文件的工程师使用 scp --manifest-out 生成无污染传输包和 SHA-256 审计清单。
发布软件或数据集的工程师用 archive create/verify 在 CI 限制下验证 ZIP/TAR 完整性、路径和元数据污染。