# 🧹 dsh-housekeeper — 环境管家

[English](README.md) · [DeepSeek Harness](https://github.com/deepseek-ai/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 执行）

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

```sh
# 从 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 上限）
```

## 开发

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

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