Project Cleaner / 项目清理助手

Project Cleaner is a local Codex plugin for auditing development project folders that were installed, cloned, generated, or experimented with and are no longer needed.

Project Cleaner 是一个本地 Codex 插件，用于盘点那些曾经安装、克隆、生成或试验过，但现在不再需要的开发项目目录。

What It Does / 它能做什么

• Scan selected folders for project-like directories.
• 查找指定目录下看起来像项目的文件夹。
• Report size, last modified date, project type, git cleanliness, and cleanup risk.
• 汇总大小、最后修改日期、项目类型、Git 状态和清理风险。
• Prefer safe quarantine over permanent deletion.
• 默认推荐“隔离移动”，而不是永久删除。
• Require explicit confirmation before destructive actions.
• 任何破坏性操作前都要求明确确认。
• Generate Markdown or JSON reports for review.
• 生成 Markdown 或 JSON 报告，方便人工复核。
• Block dirty Git repositories unless explicitly allowed.
• 默认阻止清理有未提交变更的 Git 仓库，除非明确允许。

Included Files / 包含内容

• .codex-plugin/plugin.json: Codex plugin manifest.
• .codex-plugin/plugin.json：Codex 插件清单。
• skills/project-cleaner/SKILL.md: Codex workflow and safety rules.
• skills/project-cleaner/SKILL.md：Codex 工作流和安全规则。
• skills/project-cleaner/scripts/project_cleaner.py: Self-contained script bundled with the installable skill.
• skills/project-cleaner/scripts/project_cleaner.py：随可安装 skill 打包的独立脚本。
• scripts/project_cleaner.py: Audit, quarantine, and deletion helper.
• scripts/project_cleaner.py：审计、隔离和删除辅助脚本。
• assets/: Plugin icon and logo.
• assets/：插件图标和 logo。

Usage / 使用方法

Run an audit first:

先执行只读审计：

python3 scripts/project_cleaner.py scan ~/Documents/Codex ~/Project --min-age-days 30 --min-size 100MB --format markdown

If installed as a Codex skill, run the bundled script from the skill directory:

如果已经作为 Codex skill 安装，可以从 skill 目录运行自带脚本：

python3 ~/.codex/skills/project-cleaner/scripts/project_cleaner.py scan ~/Documents/Codex --min-age-days 30 --format markdown

Include JSON output:

输出 JSON：

python3 scripts/project_cleaner.py scan ~/Documents/Codex --min-age-days 30 --format json

Limit the report:

限制输出数量：

python3 scripts/project_cleaner.py scan ~/Project --min-age-days 60 --limit 20

Preview a quarantine move:

预览隔离移动：

python3 scripts/project_cleaner.py quarantine /path/to/project --dry-run

Move a confirmed project to quarantine:

把已确认的项目移动到隔离区：

python3 scripts/project_cleaner.py quarantine /path/to/project --quarantine-root ~/.Trash/project-cleaner

Permanently delete only after explicit confirmation:

只有在明确确认后才永久删除：

python3 scripts/project_cleaner.py delete /path/to/project --confirm

Safety Model / 安全策略

Project Cleaner is conservative by design. It does not delete anything during scanning, treats dirty Git repositories as high risk, and refuses unsafe targets such as the home directory or filesystem root.

Project Cleaner 默认非常保守。扫描阶段不会删除任何内容；有未提交或未跟踪文件的 Git 仓库会被标记为高风险；脚本会拒绝删除主目录、文件系统根目录等危险目标。

Quarantined folders receive a .project-cleaner-quarantine.json manifest so you can see where they came from and when they were moved.

被隔离的文件夹会写入 .project-cleaner-quarantine.json 清单，方便之后查看来源路径和移动时间。

Recommended Codex Prompt / 推荐 Codex 提示词

Scan my project folders and show me cleanup candidates. Do not delete anything yet.
扫描我的项目目录，列出可能可以清理的候选项。暂时不要删除任何内容。

License / 许可证

MIT