dsh-cleancache-plugin

DSH 插件：Python 缓存清理工具，带有 Fluent Design UI、多语言支持和自定义规则。

功能特性

• 清理 Python 缓存目录和文件
  • 目录: __pycache__、.pytest_cache、.mypy_cache、.ruff_cache、.ipynb_checkpoints
  • 文件: *.pyc、*.pyo
• 默认演练模式：只报告会删除什么，不会实际删除
• Fluent Design UI（设置面板）：不是手动清理界面 —— 用户为每种清理类型设置 「清理」（勾选，蓝色对勾）或「不清理」（不勾选，仅空框），并可自定义添加 清理类型（添加后默认勾选），选择自动保存，清理工具只处理勾选（蓝色对勾）的类型
• 多语言支持：中文 (zh-CN) 和英文 (en-US)
• 自定义规则：支持文件和目录的删除/保护规则
• 保护规则：支持精确匹配、包含、开头、结尾、正则表达式、通配符 (glob)
• JSON 配置：支持从 JSON 文件加载完整配置
• 环境变量：支持通过环境变量添加额外保护目录

安装

1. 克隆或复制项目

git clone <repository-url>
cd dsh-cleancache-plugin

2. 编译 C++ 可执行文件

在 Developer Command Prompt for Visual Studio 中运行：

.\build.ps1

或手动编译：

cl /EHsc /std:c++17 /O2 /MT src\CleanCache.cpp shell32.lib /Fe:bin\CleanCache.exe

3. 安装 Node.js 依赖（可选，用于测试）

npm install

测试

npm test

或直接运行：

node smoke.mjs

测试输出示例

[INFO] DSH harness: C:\Users\...\@deepseek-ai\dsh
[INFO] Plugin lib: ...\dsh-cleancache-plugin\lib\index.js

[PASS]  bundled exe exists
[PASS]  plugin exports name/inject/Config/apply
[PASS]  tool registered
[PASS]  tool name = cleancache
[PASS]  has parameters target/execute/verbose/cacheDirs
[PASS]  has output schema + render
[PASS]  dry-run exit 0
[PASS]  dry-run returns stats
[PASS]  dry-run text contains 清理完成
[PASS]  execute:true deletes cache, keeps normal files
[PASS]  execute stats files>=1
[PASS]  default target = session cwd
[PASS]  resources/ui/index.html exists
[PASS]  resources/ui/styles.css exists
[PASS]  resources/ui/app.js exists
[PASS]  resources/locales/zh-CN.json exists
[PASS]  resources/locales/en-US.json exists
[PASS]  zh-CN.json is valid JSON
[PASS]  en-US.json is valid JSON
[PASS]  preset file is array
[PASS]  preset has tool-cleancache row
[PASS]  row name = dsh-cleancache-plugin
[PASS]  row has config
[PASS]  workspace == deployed
[PASS]  resourceManager loads zh-CN
[PASS]  resourceManager loads en-US
[PASS]  resourceManager fallback works

============================================================
[PASS] ALL CHECKS PASSED

安装（正式 npm 包）

dsh-cleancache-plugin 是一个标准 npm 包，同时是 DSH bundle 包：包内 cordis.patch.yml（dsh.bundle.patch）会自动注册 Web 端所需的两行插件 （工具行 + 宿主桥行），安装后无需再手动编辑 profile patch。

方式一：从 registry 安装（发布后）

cd $DSH_HOME\profiles\web
npm install dsh-cleancache-plugin

方式二：本地安装（未发布时）

cd $DSH_HOME\profiles\web
# 直接指向源码目录
npm install file:D:/test/dsh-plugin-cleancache
# 或使用打包好的 tarball（npm pack 产物）
npm install D:/test/dsh-plugin-cleancache/dsh-cleancache-plugin-0.1.0.tgz

方式三：打 tarball 手动分发

cd D:\test\dsh-plugin-cleancache
npm pack        # 生成 dsh-cleancache-plugin-0.1.0.tgz

唯一需要的配置：把包加进 profile 的 bundles

在 $DSH_HOME\profiles\web\package.json 中加一行（bundle 包机制，与 @deepseek-ai/dsh-base 相同）：

{
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-cleancache-plugin"]
    }
  }
}

然后重启 dsh web。bundle patch 会自动插入：

• cleancache-tool → 主入口 lib/index.js（注册 cleancache 工具；同时让 dsh-client-modules 发现包的 dsh.client 声明，把设置面板 bundle 以 /plugins/dsh-cleancache-plugin/client.js 提供给 GUI）
• cleancache-host → lib/host.js（POST /api/cleancache/run、 GET|POST /api/cleancache/config）

安装时（postinstall → scripts/ensure-profile-patch.mjs）还会自动创建/修复 $DSH_HOME\profiles\web\cordis.patch.yml：文件缺失时生成含顶层 [] 的模板； 已存在但只有注释（YAML 解析为 null，boot 的 parsePatchList 会抛错）时自动追加 [] —— 无需手动编辑该文件。

（可选）让 AI 能调用清理工具

工具默认不在 agent 预设中启用；在 agent 预设 （config/agent-presets/standard/agent.cordis.yml）取消注释或添加：

- id: tool-cleancache
  name: dsh-cleancache-plugin

本机快速部署（开发模式）

.\deploy.ps1          # 复制到 DSH node_modules、修复 junction、确保 profile patch 带 []
node smoke.mjs        # 自动同步 workspace -> 部署位置并跑 67 项检查

DSH 配置

Web 端无需手动配置（见上文「唯一需要的配置」）。以下配置用于 agent 预设里的 cleancache 工具（可选，均可不填，插件自带默认值）：

- id: tool-cleancache
  name: dsh-cleancache-plugin
  config:
    exePath: ""                    # 可选，自定义 exe 路径，默认使用内置
    timeoutMs: 120000              # 超时时间（毫秒）
    locale: zh-CN                  # 语言: zh-CN 或 en-US
    defaultProtected:              # 默认保护目录
      - venv
      - .venv
      - env
      - .env
      - site-packages
      - Lib
      - DLLs
      - Python*
    defaultCacheDirs:              # 默认缓存目录
      - __pycache__
      - .pytest_cache
      - .mypy_cache
      - .ruff_cache
      - .ipynb_checkpoints
    defaultCacheExts:              # 默认缓存扩展名
      - .pyc
      - .pyo

使用方式

1. 命令行使用

# 演练模式（默认）
CleanCache.exe D:\my-project

# 执行删除
CleanCache.exe D:\my-project -e

# 详细输出
CleanCache.exe D:\my-project -v

# 执行删除 + 详细输出
CleanCache.exe D:\my-project -e -v

# 使用 JSON 配置
CleanCache.exe --config config.json

# 显示帮助
CleanCache.exe -h

2. DSH 工具调用

在 DSH 中，模型可以调用 cleancache 工具：

{
  "target": "D:\\my-project",
  "execute": false,
  "verbose": true
}

3. UI 界面（设置面板）

CleanCache 界面以客户端插件形式注入 DSH Web GUI 的设置面板（导航项 「缓存清理」），样式逐项对齐 DSH 原生插件 UI（参照官方 dsh-client-ui-settings-plugins 的规范实现）：

• 全部使用 DSH 设计令牌 var(--dsw-alias-*)（bg-layer-2/3、bg-module-platform、 border-l2、label-primary/secondary/tertiary/dimmed、brand-primary、 state-warn-primary、interactive-bg-hover），明暗主题自动跟随。
• 布局规范与原生一致：分区 max-width:760px、标题 18px/600、说明 13px tertiary；分类卡片 border-radius:12px、hover/open 边框 label-dimmed、 表头 14×16 内边距；计数为 border-radius:999px 胶囊徽章；箭头为 16px chevron（展开旋转 180°）；按钮/输入框 border-radius:8px、焦点环 outline:2px brand-primary。
• 交互语义保留「勾选 = 清理该类型」（主题自适应对勾框），键盘可操作 （Enter/空格切换，表头为原生 <button>）。
• 高危项显式确认机制：node_modules、*.jar、*.class、*.exe、 *.pdb、*.ilk、Debug、Release 等默认不勾选（HIGH_RISK 列表， 带「高危」胶囊标记）。只有用户主动勾选后才进入清理范围：客户端记录 confirmedHighRisk 显式确认集（localStorage 键 v5），服务端 lib/runner.js 的 sanitizeSavedSettings() 对所有消费方（模型工具、 /api/cleancache/run、/api/cleancache/config）统一净化——没有显式 确认的高危项永远进不了配置，旧版本残留的勾选在加载时自动剥离。

界面不是手动清理面板，而是设置面板：列出所有清理类型（缓存目录 + 缓存文件 类型），每项名称右侧有一个选择框 —— 不勾选时仅显示空框（不清理该类型），勾选时 为主题自适应填充 + 对勾（清理该类型）：浅色模式黑底白勾，深色模式白底黑勾。 每个分组下方可自定义添加清理类型（自定义项带选择框，默认勾选，可移除）。 选择会自动保存：

• 客户端（浏览器）：localStorage（键 cleancache-ui.settings.v5， { selection, customItems, confirmedHighRisk }，自动迁移 v1/v3/v4）。

• 服务端：POST /api/cleancache/config 写入 $DSH_HOME/storages/cleancache-settings.json， 模型工具 cleancache 与宿主桥 POST /api/cleancache/run 在未显式指定 cacheDirs/cacheExts 时都会按该设置执行（只清理勾选类型）。

• 客户端 bundle：ui/lib/client.js（exports["./client"]，随 dsh.client 声明自动被发现），注册 settings.section 分区（id cleancache）。

• 宿主桥接 lib/host.js（注册名 dsh-cleancache-plugin/host）：注入 webServer， 提供 POST /api/cleancache/run 与 GET|POST /api/cleancache/config（POST 接受 { cacheDirs, cacheExts, confirmedHighRisk }，含自定义类型），复用 lib/runner.js 调用 exe。

• 注册方式：bundle patch（cordis.patch.yml）自动插入，无需手动编辑 $DSH_HOME\profiles\web\cordis.patch.yml。

⚠️ 安装/升级后需重启 dsh web 才会生效：客户端 bundle 由 dsh-client-modules 在启动时注入 boot manifest，运行中的页面不会自动加载 新分区。旧版独立 HTML 界面位于 resources/ui/，仅供预览（已同步为同样的 设置面板样式）。

JSON 配置示例

{
  "rootPath": "D:\\my-project",
  "dryRun": false,
  "verbose": true,
  "cacheDirs": ["__pycache__", ".pytest_cache"],
  "cacheExts": [".pyc", ".pyo"],
  "protectedDirs": ["venv", ".venv", "node_modules"],
  "protectionRules": [
    {
      "type": "directory",
      "match": "exact",
      "value": "node_modules"
    },
    {
      "type": "directory",
      "match": "starts",
      "value": "build"
    },
    {
      "type": "file",
      "match": "ends",
      "value": ".env"
    },
    {
      "type": "extension",
      "match": "exact",
      "value": ".pdb"
    },
    {
      "type": "pattern",
      "match": "glob",
      "value": "*.log"
    },
    {
      "type": "path",
      "match": "contains",
      "value": "C:\\Windows"
    }
  ],
  "customRules": [
    {
      "pattern": "*.tmp",
      "type": "file",
      "action": "delete"
    },
    {
      "pattern": "node_modules",
      "type": "dir",
      "action": "keep"
    },
    {
      "pattern": ".pyd",
      "type": "ext",
      "action": "delete"
    }
  ]
}

配置字段说明

| 字段 | 类型 | 说明 | |------|------|------| | rootPath | string | 要扫描的目录路径 | | dryRun | boolean | true=演练模式，false=执行删除 | | verbose | boolean | true=显示详细输出 | | cacheDirs | string[] | 要删除的缓存目录名称列表 | | cacheExts | string[] | 要删除的缓存文件扩展名列表 | | protectedDirs | string[] | 受保护的目录名称列表 | | protectionRules | object[] | 保护规则列表 | | customRules | object[] | 自定义规则列表 |

protectionRules 字段

| 字段 | 类型 | 可选值 | 说明 | |------|------|--------|------| | type | string | directory, file, extension, pattern, path | 匹配类型 | | match | string | exact, contains, starts, ends, regex, glob | 匹配模式 | | value | string | - | 匹配值 |

customRules 字段

| 字段 | 类型 | 可选值 | 说明 | |------|------|--------|------| | pattern | string | - | 匹配模式（支持通配符） | | type | string | file, dir, ext, path, pattern | 匹配类型 | | action | string | delete, keep | 操作类型 |

环境变量

| 变量名 | 说明 | |--------|------| | CLEANCACHE_EXTRA_PROTECTED | 额外保护目录，用分号分隔，例如 dir1;dir2;dir3 |

文件结构

dsh-cleancache-plugin/
├── bin/
│   └── CleanCache.exe              # 编译后的 C++ 可执行文件
├── lib/
│   ├── index.js                    # DSH 工具主入口（cleancache 工具）
│   ├── host.js                     # Web 宿主桥（/api/cleancache/*）
│   └── runner.js                   # 共享 exe 调用 + UI 设置持久化
├── ui/
│   └── lib/client.js               # 设置面板客户端 bundle（dsh.client）
├── cordis.patch.yml                # bundle patch：自动注册工具 + 宿主桥
├── resources/
│   ├── ui/
│   │   ├── index.html              # 旧版独立预览 UI（Fluent 风格）
│   │   ├── styles.css              # 预览样式（主题自适应选择框）
│   │   └── app.js                  # 预览交互逻辑
│   └── locales/
│       ├── zh-CN.json              # 中文语言包
│       └── en-US.json              # 英文语言包
├── src/
│   └── CleanCache.cpp              # C++ 源码
├── build.ps1                       # 编译脚本
├── deploy.ps1                      # 本机快速部署脚本
├── package.json                    # NPM 包配置（bundle + client 声明）
├── LICENSE                         # MIT 许可证
├── smoke.mjs                       # 测试脚本（65 项检查）
└── README.md                       # 本文档

编译 C++

使用脚本（推荐）

.\build.ps1

手动编译

在 Developer Command Prompt for Visual Studio 中：

cd src
cl /EHsc /std:c++17 /O2 /MT CleanCache.cpp shell32.lib /Fe:..\bin\CleanCache.exe

编译要求

• Visual Studio 2019 或更高版本
• Windows SDK
• C++17 标准库支持

故障排除

1. cl.exe 未找到

请从 Developer Command Prompt for Visual Studio 运行。

2. 链接错误 LNK2019: CommandLineToArgvW

编译时需要链接 shell32.lib：

cl /EHsc /std:c++17 /O2 /MT CleanCache.cpp shell32.lib /Fe:CleanCache.exe

3. 中文显示乱码

确保控制台使用 UTF-8 编码：

chcp 65001

4. UI 未加载

• 全新安装/升级后需重启 dsh web（客户端 bundle 在启动时注入 boot manifest）。
• 确认 $DSH_HOME\profiles\web\package.json 的 dsh.profile.bundles 包含 dsh-cleancache-plugin，且该包已安装到 profile 的 node_modules。
• 只改了 ui/lib/client.js 时无需重启：HMR 会自动重载，刷新页面即可。

5. 语言包未生效

检查 resources/locales/ 目录是否存在对应的 JSON 文件，并确保 JSON 格式正确。

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT