dsh-tmp-cleaner：守护 /tmp 清理进程

前言¶

智能体开发中，磁盘空间管理常被忽视。当 /tmp 目录堆积大量临时文件时，轻则影响性能，重则导致服务异常。多数开发者会依赖系统定期清理，但这种方式不够可控，且在容器或 Android 环境下可能失效。

DSH 插件 dsh-tmp-cleaner 提供了一个常驻守护进程与兜底清理机制，并通过设置页提供可视化的状态与配置入口。

是什么¶

dsh-tmp-cleaner 是一个 DSH 插件，维护者 yezitotempeace，分类为 admin-security。它通过启动时拉起 tmp-clean watch 守护进程、进程内看门狗自动复活、到期时由 dsh 进程兜底执行清理，确保 /tmp 空间持续可控。设置页提供状态查看、配置修改、立即清理与演练功能，所有请求走 /tmp-clean/api/*。

核心功能¶

1. 启动守护进程¶

web 启动（或 HMR 重载本插件）时，插件会调用 apply()：

若 watch.pid 对应的进程确实是 tmp-clean（通过核对 /proc/<pid>/cmdline 防止 PID 复用误判），则保持不变；
否则 detached 拉起 tmp-clean watch；
异常只写入 stderr，不影响 web 启动。

2. 进程内看门狗¶

每 2 分钟检查一次守护进程状态：

Android 的 phantom process killer 可能杀掉 detached 子进程，导致设置页显示「守护进程：未运行」；
掉线后 ≤2 分钟自动复活，重拉有 5 分钟冷却，避免连环刷进程；
若守护进程持续缺席 ≥3 分钟，且按 interval_hours 已到期，则由 dsh 进程自己执行 tmp-clean run 兜底清理。

3. 设置页¶

插件注册到 settings.section 槽位（id tmp-cleaner，order 60，标签「临时清理」）：

状态默认走快路径（不扫盘，页面秒开）；
「扫描大小」按钮触发完整扫描 /tmp 实际占用（7–20 秒）；
读取失败时给出原因和「重试」按钮（web 刚重启后常见）；
守护进程未运行时显示「看门狗 2 分钟内自动拉起」。

4. API 接口¶

所有请求走 /tmp-clean/api/*：

GET /tmp-clean/api/status → tmp-clean status --json --fast + 日志尾
GET /tmp-clean/api/status?scan=1 → 完整扫描 /tmp 实际占用
POST /tmp-clean/api/revive → 手动拉起守护进程（带冷却）
POST /tmp-clean/api/config → tmp-clean config set …
POST /tmp-clean/api/run → tmp-clean run [--dry-run]

5. 清理工具¶

清理工具本体是零依赖 Python 3 脚本，命令行与设置页共用同一份配置。工具默认使用随包自带的 bin/tmp-clean（通过 import.meta.url 定位），查找顺序为 TMP_CLEAN_TOOL 环境变量 → 包内 bin/tmp-clean → 旧的 /root/dsh-bin/tmp-clean。执行时使用 python3（可用 TMP_CLEAN_PYTHON 覆盖）。

安装与启用¶

安装¶

把仓库放进 /root/dsh-tmp-cleaner，在 profile 的 dependencies 加 "dsh-tmp-cleaner": "link:/root/dsh-tmp-cleaner"、dsh.profile.bundles 加 dsh-tmp-cleaner，建 node_modules/dsh-tmp-cleaner 链接，重启一次 web。

工具已随包提供（bin/tmp-clean，Python 3，零第三方依赖），不需要另外复制到 /root/dsh-bin/。

卸载¶

反做上述步骤，并 kill $(cat /root/.tmp-clean/watch.pid)。

配置¶

配置文件为 /root/.tmp-clean/config.json，命令行与设置页共用：

字段	默认	说明
`enabled`	true	是否启用自动清理
`interval_hours`	24	清理周期（小时）
`max_size_gb`	20	超过该占用就清
`target_size_gb`	10	清到该占用为止
`min_age_hours`	2	只删这么旧的目录
`poll_minutes`	15	守护进程轮询间隔
`dry_run`	false	演练模式（不真删）

测试¶

node test/host-test.mjs     # 假 ctx：4 条路由 + 快/慢状态 + revive + CLI 读写往返
node test/client-test.mjs   # 假 loader：materialize bundle + 注册/渲染断言
node test/probe-web.mjs     # 对运行中的 web 探测（需有效本地 cookie）

适用场景与注意¶

适合需要常驻守护进程与兜底清理机制的场景，尤其是 Android 环境或容器环境，系统定期清理可能失效。

务必确认插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

结尾¶

dsh-tmp-cleaner 通过进程内看门狗与兜底清理，确保 /tmp 空间持续可控，并提供设置页与 API 接口，便于运维与调试。更多信息可参考：

目录页：https://www.skillhub.cn/plugins/yezitotempeace/dsh-tmp-cleaner
GitHub：https://github.com/yezitotempeace/dsh-tmp-cleaner