dsh-storage-inspector

再使用上面的 link: 安装命令

### 从 npm 安装

正式发布后，推荐使用：

```bash
dsh plugin --profile desktop add dsh-storage-inspector

如果 npm 版本尚未同步，可暂时使用上面的 GitHub link: 开发安装方式。

使用

设置页

打开 DSH 的 设置 → 存储，可查看：

• 总物理占用与总逻辑大小；
• 各模块占用及分类；
• 最大文件榜；
• 缓存、活动配置、会话和运行时的分级建议；
• 缓存命中与强制刷新状态。

Agent 工具

在对话中询问：

DSH 占多少空间？

模型可以调用摘要：

{
  "name": "storage_report",
  "arguments": { "detail": "summary" }
}

需要最大文件榜和完整明细时使用：

{
  "name": "storage_report",
  "arguments": { "detail": "full" }
}

summary 默认不携带最大文件榜，适合日常对话；full 才返回完整明细，避免把大量路径塞进上下文。

开发与测试

环境要求：Node.js >=20。

npm test
npm run preflight
npm pack --dry-run
node --check lib/scan.js
node --check lib/index.js
node --check lib/client.js

当前测试覆盖：

• 白盒：fixture、权限、符号链接、硬链接、物理/逻辑口径、模块分级、缓存、建议构造、真实 ~/.dsh 集成扫描；
• 黑盒：Host 工具注册契约、HTTP loopback 栅栏、设置页请求与 403 行为、卸载清理、安装后的工具与设置入口；
• 发布预检：manifest、patch 插入语义、locale、icon、README、运行时文件和核心依赖隔离。

相关维护资料：上线部署方案、测试方案、验证清单。

故障排查

设置页显示“仅本机可用”

这是预期的安全行为。请确认你是从 DSH 本机打开设置页，不要通过反向代理、远程端口转发或跨站 iframe 访问。

数字和 Finder / du 不一样

先确认比较的是同一口径：插件主数字是物理块大小，同时提供逻辑大小。macOS 文件系统、稀疏文件、硬链接和大量小文件都可能造成差异。

修改代码后没有变化

确认插件仍以 link: 安装；然后完全重启 DSH。未启用 HMR 时，热替换不会自动加载新模块。

想删除 dsh-runtimes/ 或 sessions/

不要直接删除。前者是 DSH 自带运行时，后者由会话归档类工具负责；本插件 V1 只提供观察和解释，不提供删除按钮。

版本计划

• V1（当前）：只读扫描、双口径、模块占用、Top 文件、可解释建议、设置页 + Agent 工具；
• V2（计划）：dry-run 清理预览、白名单、废纸篓、undo 日志；sessions/ 继续交给专门的会话归档插件；
• V3（原则）：不提供直接永久删除。

贡献与发布

欢迎提交 Issue / Pull Request。建议先说明：

• 操作系统与 DSH 版本；
• npm test 和 npm run preflight 结果；
• 复现步骤与期望行为；
• 是否涉及路径、权限、符号链接或硬链接。

提交前请不要上传 .env、token、cookie、私钥或真实会话路径。发布前必须通过测试、预检和 npm pack --dry-run，并确认 tarball 不含 node_modules、敏感信息或工作区绝对路径。

License

MIT

使用

设置页

打开 DSH 的 设置 → 存储，可查看：

• 总物理占用与总逻辑大小；
• 各模块占用及分类；
• 最大文件榜；
• 缓存、活动配置、会话和运行时的分级建议；
• 缓存命中与强制刷新状态。

Agent 工具

在对话中询问：

DSH 占多少空间？

模型可以调用摘要：

{
  "name": "storage_report",
  "arguments": { "detail": "summary" }
}

需要最大文件榜和完整明细时使用：

{
  "name": "storage_report",
  "arguments": { "detail": "full" }
}

summary 默认不携带最大文件榜，适合日常对话；full 才返回完整明细，避免把大量路径塞进上下文。