# dsh-housekeeper

**Repository Path**: su_pf/dsh-housekeeper

## Basic Information

- **Project Name**: dsh-housekeeper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧹 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_clean`（走同一白名单，最多 10 路径/次）

## 安装

```sh
dsh plugin --profile web add dsh-housekeeper
```

重启 `dsh web` 后，**设置 → 插件 → 环境管家**。

要求：DSH web profile、Node ≥ 22。

## 安全模型

- 全部路由仅接受回环地址（非 127.0.0.1/::1 一律 403）
- **清理白名单**（满足全部条件才允许删除）：
  - 路径位于 `<项目根>\<仓库>\ .tmp\` 之下，或 `<缓存根>\` 的直接子目录
  - 规范化后不越过白名单根（拒绝 `..`）
  - `realpath` 后仍落在白名单根内（拒绝符号链接逃逸）
  - 白名单根自身与仓库目录自身不可删
- 规则文件只读写 `$DSH_HOME/AGENTS.md` 单文件，路径不可参数化
- 无遥测、无网络外呼

## 原理

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

## 开发

```sh
pnpm install
node build.mjs         # esbuild → lib/index.js（宿主 ESM）+ lib/client.js（ModuleLoader 包）
node tests/core.mjs    # 白名单/扫描/清理 21 项沙箱单测（无需真实环境）
```

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