前言¶

在 DSH 的日常使用中，开发者经常要面对三类本地状态：本机工具链是否可用、智能体运行后留下的临时目录能不能删、机器规则 AGENTS.md 改过以后有没有留底。手动查工具、翻目录、改规则文件都能做，但缺少一个统一入口，也容易误删。

guo6x/dsh-housekeeper 是一个 DSH web profile 插件，把这几件事集中到 Web GUI 的 Settings → Plugins → 环境管家 中：工具链盘点、缓存候选扫描、两步清理，以及 AGENTS.md 编辑与备份。下面按“先检查、再计划、最后确认”的方式介绍它。

这是什么¶

核心功能¶

下面介绍三类能力：只读盘点、受控清理、机器规则编辑。

1. 工具链盘点¶

插件自动检测以下工具的位置和版本：

node
pnpm
git
gh
ffmpeg
Edge
Chrome

这一步只做报告，不创建清理计划、不删除文件、不修改机器规则。

2. 缓存扫描¶

扫描 .tmp 和缓存目录后，面板会展示候选目录的信息：

• 大小
• 文件数
• mtime
• 4000 文件截断标记
• 30 天未触碰高亮
• 点击展开内容预览

扫描存在 4000 文件上限；如果目录文件数很多，看到截断标记时，不要把列表当作完整清单。

3. 两步清理¶

先选择你认识的临时目录，再生成清理计划。清理计划会列出批准路径和拒绝路径。确认前不会删除文件；确认后执行删除，删除前再次检查白名单和 realpath。

白名单规则：

• 只允许项目 .tmp 目录和 cache-root 直接子项删除
• 拒绝 .. 逃逸
• 拒绝符号链接逃逸
• 拒绝系统路径
• 删除前再次检查 realpath

清理确认 token：

• 一次性
• 五分钟后过期
• 用于 housekeeper_clean 工具执行清理

4. AGENTS.md 编辑¶

插件可以读取和编辑机器规则文件 AGENTS.md。保存时自动备份上一版本，并支持一键恢复。

已核实资料中写明：规则端点只读写 $DSH_HOME/AGENTS.md，路径固定，上限 64KB。资料中另一处出现 ~/.dsh/AGENTS.md，但未说明两者等价关系，本文不将其作为确定路径。

5. Agent 工具¶

插件提供三个工具：

安装与启用¶

从 GitHub 安装¶

dsh plugin --profile web add github:guo6x/dsh-housekeeper

安装后，重启正在运行的 dsh web 进程，然后打开：

Settings → Plugins → 环境管家

看到 Toolchain inventory 部分，即安装完成。

检查插件是否安装¶

dsh plugin --profile web list dsh-housekeeper

本地开发安装¶

在仓库目录中运行：

dsh plugin --profile web add .

典型用法¶

先做只读盘点¶

先打开面板，做一轮不修改系统的检查：

1、查看检测到的 node、pnpm、git、gh、ffmpeg、Edge、Chrome 位置和版本。
2、查看 .tmp 与缓存目录候选项。
3、点击某一行预览内容。
4、不选择目录、不生成计划、不删除文件。

如果用 Agent 做同样验证，可以要求：

运行 housekeeper_report，总结检测到的工具链和最大缓存候选；不要创建清理计划、不要删除文件、不要修改机器规则。

再做清理计划¶

当你确认某些临时目录可以清理时：

1、只选择你能识别的临时目录。
2、选择生成清理计划。
3、阅读批准路径与拒绝路径。
4、使用计划对应的一次性确认操作执行删除。

对应的 Agent 流程是：

1、先请求 housekeeper_report。
2、再请求并审阅 housekeeper_plan。
3、确认无误后，才允许使用返回的一次性 token 调用 housekeeper_clean。

最后编辑机器规则¶

在面板中修改 AGENTS.md，保存后会自动备份上一版本。如果改错，可以一键恢复。注意该端点有 64KB 上限。

配置¶

扫描根按平台有默认值。已核实资料中给出 Windows 默认值：

D:\github
D:\environment\cache

这些扫描根可在面板编辑，并通过环境变量覆盖。本文不列出其他平台默认值，因为已核实事实未提供。

适用场景与注意¶

适合：

• 需要在 DSH web profile 中检查本机工具链的位置与版本
• 需要清理智能体运行后留下的 .tmp 与缓存目录，但希望先看计划再删除
• 需要编辑 AGENTS.md，并保留上一版本备份

注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码、许可证与本地权限。
• 已核实事实写明：无需账号、API key 或额外服务；路由仅接受 loopback clients；无遥测、无外部网络调用。
• 清理白名单只覆盖项目 .tmp 目录和 cache-root 直接子项；系统路径、.. 逃逸和符号链接逃逸会被拒绝。
• 清理 token 一次性且五分钟过期。
• 扫描有 4000 文件上限；被截断的目录不能直接当作完整清单。
• AGENTS.md 上限 64KB；已核实资料中出现 $DSH_HOME/AGENTS.md 和 ~/.dsh/AGENTS.md 两种写法，未说明等价关系，使用前请核对本地环境。

链接¶

• GitHub：https://github.com/guo6x/dsh-housekeeper
• 目录页 URL 未在已核实资料中给出，本文不在此列出。