guo6x/dsh-housekeeper

English · DeepSeek Harness 插件

管住 agent 的脏手：工具链台账、两阶段缓存清理、机器规则（AGENTS.md）随时改，全在 Web GUI 设置面板里完成。零运行时依赖，一条命令安装。

• 📋 工具链台账 —— 自动探测 node/pnpm/git/gh/ffmpeg/Edge/Chrome 的位置与版本，装了什么一目了然
• 🗑️ 诚实缓存清理 —— 扫描 agent 留下的 .tmp 与缓存目录：大小/文件数/修改时间、4000 文件截断标记、30 天未动高亮、点行展开内容预览；先生成计划，再确认删除
• 🛡️ 白名单保护 —— 只允许删「项目 .tmp」与「缓存根直接子目录」；.. 路径逃逸、符号链接逃逸、系统目录一律拒绝，删除前先 realpath 校验
• 📝 机器规则编辑 + 保命 —— 直接读写 ~/.dsh/AGENTS.md，每次保存自动备份上一版，一键恢复；保存即实时生效
• 🌍 可配置 —— 项目/缓存扫描根目录按平台默认（Windows: D:\github / D:\environment\cache），面板里可改，环境变量可覆盖
• 🤖 agent 工具 —— housekeeper_report（台账+磁盘占用报告）、housekeeper_plan（只审阅）与 housekeeper_clean（一次性 token 执行）

安装——复制、粘贴、验收

# 从 GitHub 直装——当前唯一受支持的发布渠道：
dsh plugin --profile web add github:guo6x/dsh-housekeeper

如果 dsh web 正在运行，重启它，再打开 设置 → 插件 → 环境管家。看到“工具链台账”区块，就说明安装完成。

要求：DSH web profile、Node ≥ 22。插件不需要账号、API key 或额外服务。

从本地 checkout 开发？在仓库目录执行 dsh plugin --profile web add .。仓库已提交 lib/ 构建产物，所以 GitHub 安装不会跑构建脚本。

60 秒完成一次安全验收

这段流程不会删除文件，也不会写入机器规则。

1. 打开 设置 → 插件 → 环境管家。
2. 查看自动发现的工具链与缓存候选项；点一行先预览内容。
3. 先不要勾选任何目录。这样已经在不改动机器的前提下验收了台账和候选列表。

想用对话完成同样的无副作用验收，直接粘贴：

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

真的准备清理时，再只勾选你认识的临时目录，点 生成清理计划。先阅读批准/拒绝的路径；在你明确使用该计划的一次性确认动作前，删除仍然不可能发生。

agent 也走同一条受审阅的路径：先要求 housekeeper_report，查看 housekeeper_plan，再决定是否把返回 token 交给 housekeeper_clean。

如果面板没有出现

• 确认插件安装在 web profile：dsh plugin --profile web list dsh-housekeeper。
• 安装后必须重启 dsh web；仅刷新浏览器不会加载新的宿主代码。
• 确认 Node 为 22 或更新版本。台账不依赖 Edge、Chrome 或云端凭据。

安全模型

• 全部路由仅接受回环地址（非 127.0.0.1/::1 一律 403）
• 清理白名单（满足全部条件才允许删除）：
  • 路径位于 <项目根>\<仓库>\ .tmp\ 之下，或 <缓存根>\ 的直接子目录
  • 规范化后不越过白名单根（拒绝 ..）
  • realpath 后仍落在白名单根内（拒绝符号链接逃逸）
  • 白名单根自身与仓库目录自身不可删
• 两阶段确认：先生成仅保存在内存中的清理计划；确认 token 5 分钟后失效、只能用一次，执行时再次走白名单与 realpath 校验
• 规则文件只读写 $DSH_HOME/AGENTS.md 单文件，路径不可参数化
• 无遥测、无网络外呼

原理

GUI 设置页 ──fetch──▶ /housekeeper/state|clean/plan→clean|rules（仅回环）──▶ 宿主插件
                         ├─ 探测：候选路径 + PATH 查找 + 版本
                         ├─ 扫描：按规则走查目录，统计大小（4000 文件上限）
                         ├─ 清理：白名单 + realpath 生成计划 → 一次性确认 token → 再校验后 rm
                         └─ 规则：读写 $DSH_HOME/AGENTS.md（64KB 上限）

开发

pnpm install
pnpm test              # 构建、安全回归套件、发布包内容检查

MIT 协议。问题与想法请提 issue。