zclean

# zclean <div align="center"> <pre> zclean AI 编程运行时卫生 </pre> **适用于 Claude Code、Codex、Cursor、Windsurf、MCP 服务器、代理浏览器和本地开发缓存的 AI 编程运行时卫生。** [](https://www.npmjs.com/package/z-clean) [](https://www.npmjs.com/package/z-clean) [](https://opensource.org/licenses/MIT) [](#) [](#platform-status) [](#) [](#) [](https://github.com/TheStack-ai/zclean) [](https://github.com/rohitg00/awesome-claude-code-toolkit) [English](README.md) | [한국어](README.ko.md) | [中文](README.zh.md) </div> <p align="center"> <img src="assets/zclean-hero.png" alt="zclean AI 编程运行时卫生横幅" width="960"> </p> --- ## 什么是 zclean `zclean` 是一个零依赖的命令行工具，用于保持 AI 编程会话不会留下运行时垃圾。 它有助于解决两个本地卫生问题： 1. **僵尸 AI 运行时进程**。 由 Claude Code、Codex、Cursor 样式的代理、Windsurf 和其他 AI 编程工具遗弃的孤儿 MCP 服务器、子代理、无头浏览器、包运行器、沙盒和开发服务器。 2. **安全的工作区缓存清理**。 清理常见的项目缓存目录，例如 `.next/cache`、`.turbo`、`.vite`、`.parcel-cache`、`node_modules/.cache`、`.pytest_cache`、`.ruff_cache`、`.mypy_cache` 和 Python `__pycache__`。 它仅限于本地运行，默认进行干运行，并且在进行销毁性清理之前需要 `--yes` 参数。 ## zclean 不是什么 `zclean` 不是应用程序卸载程序、系统优化器、磁盘映射、遥测代理或全磁盘清理器。它不会遍历整个 Mac、删除文档、移除应用程序或触及任意文件夹。 目标更狭隘：**AI 编程清理和开发者工作区卫生**。 ## 快速开始 首先进行只读审计。这不会安装钩子、调度作业或清理任何内容： ```bash npx --yes z-clean audit ``` 在清理前查看候选者： ```bash npx --yes z-clean npx --yes z-clean report ``` 当您准备好继续使用它时，安装命令行工具： ```bash npm install -g z-clean zclean report ``` 只有在您决定清理时才进行清理： ```bash zclean --yes zclean cache --yes ``` 可选自动化： ```bash zclean init ``` `zclean init` 安装 Claude Code 会话钩子和本地操作系统调度器。仅在查看干运行输出后运行它。它不会安装持久守护进程。 ## 开发者为什么使用它 AI 编程工具在工作时会产生许多短生命周期的运行时： - MCP 服务器 - Claude Code 子代理 - Codex 沙盒 - 无头 Chromium 或 Playwright 会话 - `npm exec`、`tsx`、`bun`、`deno` 和 Python 助手 - 构建监视器，如 Vite、Next.js、webpack 和 esbuild 当代理崩溃、终端关闭或会话突然结束时，这些子进程可能会继续运行。它们会占用内存、端口、文件句柄和 CPU。zclean 会找到它们，解释为什么它们是候选者，并且只有在安全检查通过时才会清理它们。 ## 核心命令 | 命令 | 功能 | |---------|--------------| | `zclean` | AI 运行时僵尸进程的干运行扫描 | | `zclean --yes` | 终止已验证的僵尸运行时进程 | | `zclean report` | 人类可读的 AI 运行时卫生报告 | | `zclean report --json` | 机器可读的报告，用于 CI、本地仪表板或代理 | | `zclean audit` | `zclean report` 的别名 | | `zclean cache` | 支持的工作区缓存目录的干运行扫描 | | `zclean cache --yes` | 删除支持的工作区缓存目录 | | `zclean cache --json` | 机器可读的缓存卫生报告 | | `zclean history` | 最近的清理历史 | | `zclean history --json` | 清理历史和累计统计 | | `zclean protect list` | 显示受保护的进程模式 | | `zclean protect add <entry>` | 添加受保护的进程模式 | | `zclean protect remove <entry>` | 删除受保护的进程模式 | | `zclean protect remove --index=N` | 按索引删除受保护的条目 | | `zclean doctor` | 检查钩子、调度器、配置和进程枚举健康状况 | | `zclean doctor --json` | 结构化的健康检查输出 | | `zclean init` | 安装 Claude Code 钩子和操作系统调度器 | | `zclean status` | 显示当前僵尸状态和最近的清理 | | `zclean logs` | 显示详细的清理日志 | | `zclean config` | 显示当前配置 | | `zclean uninstall` | 删除钩子和调度器 | ## 运行时清理 干运行： ```bash zclean ``` 示例输出： ```text zclean - 扫描僵尸进程... 发现 12 个僵尸进程： PID 26413 node 367 MB 18h claude mcp-server PID 62830 chrome 200 MB 3h agent-browser PID 26221 npm 142 MB 2d npm exec task-master-ai 可回收的总内存：2.4 GB 运行 zclean --yes 来清理这些进程。 ``` 实际清理： ```bash zclean --yes ``` 安全规则： - 手动扫描默认情况下是干运行。 - 清理需要 `--yes` 参数。 - 活动父会话受到保护。 - tmux、screen、PM2、Forever、Docker 和 VS Code 子进程被跳过。 - 在每次终止之前重新验证 PID 以避免 PID 回收事故。 ## 工作区缓存清理 干运行： ```bash zclean cache ``` 清理支持的缓存目录： ```bash zclean cache --yes ``` 扫描另一个工作区： ```bash zclean cache --path=/path/to/project ``` 支持的默认缓存目标： | 缓存路径 | 常见来源 | |------------|---------------| | `.next/cache` | Next.js | | `.nuxt` | Nuxt | | `.turbo` | Turborepo | | `.vite` | Vite | | `.parcel-cache` | Parcel | | `node_modules/.cache` | JavaScript 工具 | | `.pytest_cache` | pytest | | `.ruff_cache` | Ruff | | `.mypy_cache` | mypy | | `__pycache__` | Python 字节码 | `zclean cache --json` 仅发出相对路径。它不会暴露绝对本地路径，并且除非存在 `--yes` 参数，否则不会删除任何内容。 ## 报告和 JSON 接口 `zclean report --json` 设计用于脚本、CI 注释、本地仪表板和其他代理： ```bash zclean report --json ``` 报告包括： - `schemaVersion: 1` - AI 运行时卫生状态 - 候选计数和可回收内存 - 按风险排名的候选列表 - 扫描警告和错误 - 清理历史摘要 - 安全防护措施 - 推荐的后续操作 原始命令行和本地文件系统路径从公共 JSON 接口中省略。 ## 历史、保护和医生 机器可读的历史： ```bash zclean history --json ``` 保护列表管理： ```bash zclean protect list zclean protect add "mcp-server-keep" zclean protect remove "mcp-server-keep" ``` 健康检查： ```bash zclean doctor zclean doctor --json ``` `doctor --json` 仅在设置健康时退出 `0`。警告和错误退出 `1`，以便自动化可以诚实地处理非健康状态。 ## 配置 `~/.zclean/config.json`: ```json { "whitelist": [], "maxAge": "24h", "memoryThreshold": "500MB", "maxKillBatch": 20, "sigterm_timeout": 10, "dryRunDefault": true, "logRetention": "30d", "customAiDirs": [] } ``` | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `whitelist` | `[]` | 进程名称模式，从不终止；使用 `zclean protect` 管理 | | `maxAge` | `"24h"` | 仅在该年龄后标记孤立的 AI 路径运行时进程 | | `memoryThreshold` | `"500MB"` | 在此内存使用量以上标记 AI 路径运行时孤立进程 | | `maxKillBatch` | `20` | 每次调用的最大进程终止数 | | `sigterm_timeout` | `10` | 在 SIGTERM 后等待 SIGKILL 的秒数 | | `dryRunDefault` | `true` | 手动扫描默认情况下保持干运行；清理仍然需要 `--yes` | | `logRetention` | `"30d"` | 清理历史保留 | | `customAiDirs` | `[]` | 要检测的其他 AI 工具目录，例如 `[".mytool"]` | ## 支持的工具 | 工具或运行时 | 覆盖范围 | |-----------------|----------| | Claude Code | MCP 服务器、子代理、会话、代理浏览器、Playwright | | Codex | `codex exec`、Codex 沙盒 | | Cursor 和 Windsurf 样式的代理 | AI 路径运行时残留和浏览器助手 | | Aider | 孤立的 Aider/Python 进程 | | Gemini CLI | 孤立的 Gemini 进程 | | MCP 服务器 | `mcp-server-*` 模式 | | JavaScript 运行时 | AI 路径上的 `node`、`tsx`、`ts-node`、`bun`、`deno` | | 构建工具 | AI 路径上的 Vite、Next.js、webpack、esbuild | | 工作区缓存 | Next.js、Nuxt、Turborepo、Vite、Parcel、Python、JS 工具缓存 | ## 平台状态 | 平台 | 状态 | |----------|--------| | macOS | launchd 调度器、Claude Code 钩子、干运行和清理路径 | | Linux | systemd 用户定时器、Claude Code 钩子、干运行和清理路径 | | Windows | 任务调度器安装程序和非破坏性 CI 覆盖；运行 `zclean doctor` 以确认本地调度器和进程枚举健康状况 | ## 常见问题 ### zclean 会终止我的 Claude Code 会话吗？ 手动和调度扫描通过检查父进程是否存活来保护活动会话。Claude Code `SessionEnd` 钩子传递 `--session-pid`，因此清理仅限于刚刚结束的会话的后代。 ### zclean 会删除我的项目文件吗？ 不。运行时清理会终止已验证的僵尸进程。缓存清理仅删除支持的缓存目录，并且仅在 `--yes` 参数存在时。 ### zclean 是通用的 Mac 清理器吗？ 不。zclean 专注于 AI 编程运行时清理和安全开发者工作区缓存清理。它不卸载应用程序、不绘制磁盘映射、不扫描整个磁盘。 ### 调度器会减慢我的机器吗？ 不。调度器运行单个扫描并退出。没有持久的后台守护进程。 ### 如何删除 zclean？ ```bash zclean uninstall npm uninstall -g z-clean ``` 如果您仅使用 `npx --yes z-clean`，则没有全局包需要卸载。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 添加进程模式？编辑 `src/detector/patterns.js`。 添加缓存目标？保持确定性、限定工作区范围、干运行优先。 ## 许可证 MIT - 参见 [LICENSE](LICENSE)。 由 [TheStack-ai](https://github.com/TheStack-ai) 构建。