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 旁并告警

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

# 在插件包目录（含 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

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 即可。

【磁盘守护 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 向你确认目录）：

【磁盘纪律】你运行在 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 -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 其他功能。