dsh-disk-guard

Readme

# dsh-disk-guard · DSH 磁盘守护插件

把 DSH 生态的**下载产物**与**缓存/临时文件**从 C 盘重定向到用户指定目录（默认自动挑剩余空间最大的非 C 盘），
并向每个会话注入**路径纪律提示词**，让 agent 每次运行都遵守，**防止 C 盘爆炸**。

## 它做什么

| 能力 | 说明 |
|---|---|
| 指定下载目录 | `downloadDir`：下载/导出/安装包/产物/大文件统一落盘处 |
| 指定缓存目录 | `cacheDir`（临时 `<cacheDir>/tmp`、npm 缓存 `<cacheDir>/npm`） |
| 环境重定向 | 把 `TMP/TEMP/TMPDIR` → 临时目录、`npm_config_cache` → npm 缓存（对子进程 bash/pwsh 生效） |
| 持久化继承 | 同步追加进 `$DSH_HOME/.env`（dsh-launch-environment 的 user-env 层，每次启动自动继承） |
| 提示词注入 | 每个会话首条用户消息前自动插入"路径纪律"块（见下文【提示词】） |
| 自带工具 | `disk_guard`：`status` 看配置/盘剩余/目录体积；`clean` 清理过期缓存；`set` 改目录即时生效 |
| C 盘体检 | DSH home 落在 C 盘时启动告警，附一键迁移脚本 |
| 智能默认 | 不配目录时自动选剩余空间最大的非 C 盘（≥5GB），只有 C 盘时退避到 home 旁并告警 |

## 快速安装（推荐，一条命令）

```powershell
# 在插件包目录（含 package.json 的那层）执行：
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
# 可选参数：
#   -ProfileDir <profile目录>   默认 $DSH_HOME\profiles\web
#   -DownloadDir <目录>         指定下载目录（缺省自动挑盘）
#   -CacheDir <目录>            指定缓存目录（缺省自动挑盘）
#   -SkipPnpmInstall            跳过 pnpm install（你手动装时用）
```

安装脚本会：拷贝插件到 `<profile>/vendor/dsh-disk-guard` → 生成 `$DSH_HOME/disk-guard.yaml`
（**以后改目录就改这个文件**）→ 把它接进 profile 的 `package.json`（依赖 + bundles）→ `pnpm install`
→ 把 `SKILL.md` 装进 `$DSH_HOME/skills/disk-guard/`。

**最后一步：重启 DSH（web GUI 或 headless）。** 启动日志出现

```
[dsh-disk-guard] 就绪 ── 下载=E:\dsh\downloads | 缓存=E:\dsh\cache | 临时=E:\dsh\cache\tmp | home=E:\dsh-home
```

即安装成功；之后每个会话第一条用户消息前都会出现【磁盘守护 · 路径纪律】提示词。

## 手动安装（不想用脚本时）

1. 构建：`cd dsh-disk-guard && npm install --no-save esbuild && node build.mjs`（产出 `lib/index.js`）
2. 拷贝整个目录到 `<profile>/vendor/dsh-disk-guard`
3. 编辑 `<profile>/package.json`：dependencies 加 `"dsh-disk-guard": "file:vendor\\dsh-disk-guard"`；
   `dsh.profile.bundles` 数组加 `"dsh-disk-guard"`
4. 在 profile 目录执行 `pnpm install`
5. 可选：生成 `$DSH_HOME/disk-guard.yaml`（参考 `config.example.yaml`），并在
   `<profile>/vendor/dsh-disk-guard/cordis.patch.yml` 的 config 里加一行
   `configFile: '~/.dsh/disk-guard.yaml'`（注意：patch 里的 `~` 指向用户主目录，不是 DSH home）
6. 重启 DSH

## 配置

三处可配，优先级：**外置 configFile > patch 行 config > 默认值**。

1. **外置 YAML**（推荐，唯一推荐用户常改的文件）：`$DSH_HOME/disk-guard.yaml`

```yaml
downloadDir: 'E:\\dsh\\downloads'
cacheDir: 'E:\\dsh\\cache'
# tempDir: ''        # 默认 <cacheDir>/tmp
# npmCacheDir: ''    # 默认 <cacheDir>/npm
# redirectEnv: true  # 设置 TMP/TEMP/TMPDIR/npm_config_cache
# writeUserEnvFile: true  # 同步追加 $DSH_HOME/.env
# injectPrompt: true      # 会话注入提示词
# cleanupOnBoot: false    # 启动清理过期临时文件
# maxAgeDays: 7
# warnC: true
```

2. **patch 行 config**：`cordis.patch.yml` 里本插件的 `config:` 段（重装会被脚本覆盖）。
3. **自动兜底**：什么都不配 → 挑剩余空间最大的非 C 盘（如 `E:\dsh\downloads`、`E:\dsh\cache`）。

路径支持 `~`（用户主目录）与 `%VAR%` 展开；相对路径以 DSH home 为基准。

## 工具：disk_guard

会话中随时可用（也可直接命令行调）：

- `disk_guard {action:"status"}`：下载/缓存/临时/npm 目录 + 各盘剩余空间 + 目录体积 + home 是否在 C 盘
- `disk_guard {action:"clean", scope:"temp"|"npm"|"all"}`：清理超过 `olderThanDays`（默认 maxAgeDays）的文件
  - `scope:"downloads"` 需要 `force:true`（下载产物属用户数据，二次确认）
  - 清理**只发生在插件自己管理的目录内**，绝不动目录外任何文件
- `disk_guard {action:"set", downloadDir:"E:\\dsh\\dl", cacheDir:"E:\\dsh\\cache"}`：写入外置 configFile 并即时生效（需已配置 configFile）

## 提示词（你要的那段）

插件在每个会话首条用户消息前自动注入（占位符替换为实际路径）；想整体自定义，把文本存到
`$DSH_HOME/disk-guard-prompt.md` 即可。

```text
【磁盘守护 dsh-disk-guard · 路径纪律】（本条为插件注入，请严格遵守）

1. 下载目录（默认下载/导出/安装包/产物/大文件保存处）：<downloadDir>
2. 缓存目录：<cacheDir>
   - 临时文件：<tempDir>
   - npm 等包缓存：<npmCacheDir>
3. 红线：禁止把任何大文件、下载、缓存或临时文件写到 C 盘
   （包括 %TEMP%、C:\Users\*\Temp、C:\Windows\Temp、用户目录、桌面、文档）。
4. 用户说"下载/存到/缓存"却没给路径时，一律按第 1、2 条执行；
   中间产物与临时文件放临时目录，用完后随手清理。
5. 需要看磁盘占用/清理过期缓存时，调用工具 disk_guard（status / clean），不要瞎猜。
```

**不装插件也能用的独立提示词**（粘贴到任意 agent 会话开头即可，首次运行会让 agent 向你确认目录）：

```text
【磁盘纪律】你运行在 Windows 上，必须遵守以下路径规则（首次执行先向用户确认下载目录与缓存目录，
并把确认结果写进工作区 .dsh-disk-policy.yaml 供以后复用）：
1. 所有下载、导出、安装包、产物、大文件保存到用户指定的下载目录（推荐非 C 盘，如 E:\dsh\downloads）。
2. 所有临时文件、缓存、中间产物放用户指定的缓存目录（如 E:\dsh\cache\tmp），用后即清。
3. 禁止向 C 盘写入任何大文件/缓存/临时文件（%TEMP%、C:\Users\*\Temp、C:\Windows\Temp、桌面、文档、用户目录）。
4. 用户未指定路径时默认走 1、2 条；被问磁盘占用时给出目录清单与实际占用，不要凭空回答。
5. 每次会话结束前检查：是否有本可删的大临时文件残留，有就清理并汇报。
```

## 迁移：DSH home 在 C 盘

若 `$DSH_HOME` 未设置，DSH 会把会话/附件/任务板/皮肤缓存全写到 `C:\Users\<user>\.dsh`。
运行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\migrate-c-drive.ps1 -MoveData -DeleteOld
```

脚本会：选一个非 C 盘（默认 `<最大盘>:\dsh-home`）→ `setx DSH_HOME <新家>` → 用 robocopy 把旧
`~/.dsh` 内容拷过去 → 校验后（`-DeleteOld`）删除 C 盘旧数据。**先退出 DSH 再迁移**；不确定时只加
`-MoveData` 不删旧，确认无误再补 `-DeleteOld`。

## 卸载

1. 编辑 `<profile>/package.json`：删依赖与 bundles 里的 `dsh-disk-guard`
2. `<profile>` 下 `pnpm install`
3. 删除 `<profile>/vendor/dsh-disk-guard`、`$DSH_HOME/disk-guard.yaml`、`$DSH_HOME/skills/disk-guard`
4. 想还原环境变量：删掉 `$DSH_HOME/.env` 里 dsh-disk-guard 追加的那几行

## 设计说明（为什么这么写）

- **运行期零第三方依赖**：yaml 构建时打进 bundle，源码只用 Node 内置 API。
- **路径解析确定化**：`~`/`%VAR%` 展开、相对路径锚定 DSH home，避免不同启动方式结果不一致。
- **清理有边界**：`removeOldFiles` 只接受插件自己解析出的目录，删除仅限超过阈值天数的文件。
- **注入一次、不刷屏**：按会话 id 去重，只在首条用户消息前注入，子代理会话跳过。
- **失败不阻断**：插件任何一步出错只记日志，不影响 DSH 其他功能。