Community写作与编辑github.com

file-singlify(文件单副本化)

扫描磁盘或目录,找出重复文件和目录,生成单副本化方案,估算节省空间,并保守地报告操作建议,绝不自动执行破坏性操作。

file-singlify(文件单副本化) 是什么?

该技能通过扫描指定磁盘、目录或挂载路径,识别因多次复制、备份、同步、迁移造成的重复文件和目录。它采用“目录优先”策略:先根据目录结构一致性查找冗余,再通过文件哈希(MD5或SHA256)精确确认重复。核心原则是只读和模拟运行:脚本不会自动删除、移动或创建链接,而是生成包含重复组、规范副本映射、节省空间估算和“top-4 推荐命令”的结构化报告(支持Markdown、JSON、CSV)。每个条目都带有置信度(confirmed/uncertain)和建议操作(keep/delete/replace_with_link等),不确定项会提示用户确认。该技能特别适合存储清理、去重和备份优化场景,支持macOS、Linux和Windows平台,并能根据当前操作系统和Shell自动调整输出的命令行语法。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add host452b/polish

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

file-singlify(文件单副本化) 是做什么的?

本技能的功能

扫描某个磁盘 / 目录 / 挂载路径,找出因多次复制、备份、同步、迁移产生的重复文件和重复目录,生成「单副本化」方案:每组保留一份规范副本,其余映射为引用 / 待删除 / 链接建议,并估算可节省的空间。

核心原则:默认只读、只执行模拟运行。绝不直接删除、移动、覆盖、改写、创建硬/软链接。任何破坏性操作都必须先出报告、再等待用户明确确认。 脚本本身永远只读 —— --action-mode 仅修改报告里 suggested_action 的标签,不执行任何实际操作。

何时使用

  • 用户需要扫描某个盘、目录或一组文件夹,查找“完全相同的文件”、“重复目录”、“冗余备份”、“多次复制”。
  • 用户希望保留一份原始文件、生成引用映射、删除建议、硬/软链接建议、去重报告、节省空间估算。
  • 关键词:去重 / 单副本化 / 重复目录折叠 / dedup / canonical copy / storage cleanup

不适用: 用户需要的是文件内容分析、压缩、或与重复检测无关的整理。

默认工作流程

  1. 路径与权限检查 — 确认当前环境能否访问 root_path。能访问就直接运行脚本;不能访问则要求用户提供目录清单 / 目录树 / 压缩包 / 可访问挂载路径。绝不虚构扫描结果。
  2. 运行脚本(目录优先) — 先根据目录一致性查找冗余,再用哈希确认文件。整个目录被重复复制是最大空间浪费的来源,优先展示目录级别的结果。
  3. 读取脚本输出,整理并呈现给用户 — 优先介绍重复目录组,再介绍重复文件组、规范副本映射、节省空间、风险项。对于脚本标记为 uncertain / manual_review 的项,向用户提问并澄清,不要替用户做决定。
  4. 给出 top-4 后续命令 — 脚本会根据当前操作系统/Shell生成 top-4 推荐命令(安全优先顺序:验证 → 隔离 → 硬链接 → 删除),详见报告第10节或JSON中的 recommended_commands。将其呈现给用户,并根据用户真实的操作系统与Shell调整语法;脚本默认自动探测,必要时可使用 --target-os / --target-shell 覆盖。只提供命令,不执行。 命令中使用的是代表性样本路径,用户需要逐行应用到映射表中。
  5. 执行破坏性操作前再次确认 — 当用户想要真正删除或替换链接时,先复述计划并要求明确确认;脚本不会执行这些操作,用户需自行执行或另行授权。

何时运行脚本

如果环境可以直接读取 root_path,就运行脚本;如果只拿到清单或目录树,则按照同样的判定逻辑(目录结构一致 → 文件大小一致 → 内容哈希确认)进行人工分析,并明确说明“未做哈希确认”。

python3 scripts/scan_file_singlify.py <root_path> \
  --scan-mode directory-first \      # 或 file-only
  --hash-algorithm md5 \             # md5 | sha256 | both(严格模式用 both)
  --output-format markdown \         # markdown | json | csv
  --action-mode report-only \        # report-only|link-plan|delete-plan|hardlink-plan|symlink-plan
  --exclude-patterns ".git,node_modules,cache,temp" \
  --include-patterns "*.jpg,*.mp4" \
  --min-file-size 1024 \
  --prefer "/Volumes/Primary" \      # 优先保留此路径作为规范副本
  --target-os auto \                 # auto|macos|linux|windows(用于生成 top-4 命令)
  --target-shell auto                # auto|bash|zsh|fish|powershell|cmd

完整参数与判定细节请参阅脚本的 --help、references/matching-rules.md 与 references/safety-rules.md。

输出格式

脚本会生成结构化报告,包含:扫描范围、参数、总文件/目录/容量、重复目录组、疑似重复目录、重复文件组(哈希确认)、节省空间估算、规范副本映射表、top-4 推荐命令(根据操作系统/Shell生成)、风险与不确定项、下一步建议。markdown 格式供人类阅读,json 格式供程序消费(包含 recommended_commands),csv 格式是重复→规范副本的映射表。

每个映射行都包含 confidence(confirmed / uncertain)和 suggested_action(keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review)。

安全边界

  • 默认绝不删除文件、绝不自动创建硬/软链接。 脚本只读。
  • 仅凭文件名 / 大小 / 修改时间 不能判定文件相同 —— 这些只用于筛选候选;最终结论必须通过哈希确认(相同大小 + 相同哈希)。
  • 对系统目录、隐藏目录、应用目录、Git 仓库、数据库、照片图库、云同步目录需格外谨慎。
  • 不跟随符号链接、不递归遍历符号链接;遇到目录循环时停止递归并报告。
  • 权限不足的文件 / 零字节文件 / 特殊文件 / 已硬链接的文件 → 标记并跳过,归入“跳过 / 不确定”分类,不作为确定的重复处理。
  • 当无法判断规范副本时,列出候选并要求用户确认,不自行决定。

常见错误

错误纠正措施
未确认能否访问路径就“假装扫描”先确认能否访问;不能访问就要目录清单,绝不虚构结果
仅凭文件名/大小/时间就判定重复只作为候选;必须使用哈希确认
一上来就对所有文件做哈希先进行目录一致性筛选,再对候选文件做哈希
报告还没出就建议删除或替换链接先出报告、等待明确确认;脚本不执行破坏性操作
替用户决定 uncertain 项将不确定项作为问题抛回给用户

相关技能