dsh-clean-reset

DSH 插件：干净地重置 DSH 的插件状态，专门处理插件残留——插件异常、卸载不干净、安装中断留下的半套状态。绝不触碰工作区记录（sessions、凭据、匿名 ID、工作区目录一律不动）。

它清理什么

残留类型	位置	模式
dsh.profile.bundles 里指向已卸载/未安装包的陈旧条目（典型的启动崩溃源）、重复条目	profiles/<name>/package.json	scan / fix
失效的 link:/file: 依赖（目标目录已被删）、既没安装又不在 lockfile 里的断裂依赖	profiles/<name>/package.json	scan / fix
patch 层里挂载已消失插件的行（含 !!js 行），以及双重挂载（bundle 通道已挂载、patch 层又手动挂一遍 → 启动时报 duplicate prefix）	profiles/<name>/cordis.patch.yml、$DSH_HOME/cordis.patch.yml	scan / fix
插件市场 state 里指向已卸载插件的禁用项 / 分组成员	profiles/<name>/.dsh-market/state.json、.ntes-dsh-market/state.json	scan / fix
settings.yaml 里属于已卸载插件的孤儿配置段	$DSH_HOME/settings.yaml	scan / purge
已归属的插件数据：pet.json 存档、cache/*、skin-center/*、.agent-presets/* 中不匹配任何已装插件的目录、错层的 profiles/node_modules（真错层 pnpm 树才会删；dsh 自管理的模块回退目录从不报告也不删除）	$DSH_HOME/	scan / purge
重装整个 node_modules + lockfile 后重新 pnpm install	profiles/<name>/	rebuild

永远不动：sessions/、.credentials.yaml、.anonymous-user-id、settings 核心段（llm-*、ui-*、permission、agent-presets、agent-default-model）、工作区目录。

安装

# npm 发布版（推荐给普通用户）
dsh plugin --profile web add dsh-clean-reset

# 本地源码（自己开发/改完即用）
dsh plugin --profile web add <你的插件目录>

# Git 仓库
dsh plugin --profile web add github:<user>/dsh-clean-reset

安装后 dsh 会把 dsh-clean-reset 追加进 profile 的 dsh.profile.bundles，web 会话里即可用 dsh_clean_reset 工具（说一句「帮我清一下插件残留」即可）。安装后重启 dsh web 生效。

Windows 安装注意：0.1.0 若报 ERR_PNPM_EPERM … symlink '@deepseek-ai'，加一个 flag 即可： dsh plugin --profile web add dsh-clean-reset --config.resolve-peers-from-workspace-root=false 0.1.1 起已移除会触发该行为的可选 peer 声明，不再需要此 flag。

发布到 npm（给别人装）

cd <插件目录>
npm login          # 首次需要登录 npm 账号
npm publish        # 发布（改动后再发需先 npm version patch）

前置检查已就绪：name（dsh-clean-reset）在 npm 上未被占用、MIT LICENSE、files 白名单（只发布 lib/、bin/、cordis.patch.yml、README、LICENSE）、零构建步骤（无需 allowBuilds）、bin 入口（装完即可 npx dsh-clean-reset）。发布后用 npm pack --dry-run 可随时预览包内容。

用法

方式一：设置页按钮（Web UI）

打开设置（侧边栏底部齿轮），左侧导航会出现 「插件重置」 页面，里面有：

• 页面顶部显示插件版本号（dsh-clean-reset vX.Y.Z）
• 目标 Profile 选择器
• 扫描残留：实时列出发现（严重度标色 + 修复建议）
• 一键清理 / 重建环境：破坏性按钮都是两步确认（第一次点击变成「确认执行」，8 秒内再点一次才真正执行，另有取消按钮）；「一键清理」= 修复（package.json/patch 层/市场 state）+ 清除孤儿数据（settings 段与已归属插件数据），确认时会列出将删除的具体路径
• 结果面板：发现 / 已执行 / 错误 / 「始终不动」清单；扫描干净时不显示多余提示
• 中英双语：界面与发现明细跟随 DSH 语言设置（中文界面显示中文，其余回退英文）；CLI 与面向模型的工具说明固定英文

按钮通过同源 HTTP 路由（/dsh-clean-reset/*，市场插件同款模式）调用宿主上的引擎，与 CLI/工具完全同一套逻辑。安装后需要重启 dsh web 才会出现（客户端插件图在启动时扫描）。

方式二：会话内工具 dsh_clean_reset

• mode: "scan"（默认）：只报告，零写入。发现什么先给用户看。
• mode: "fix" | "purge" | "clean" | "rebuild" | "all"：必须先 scan → 用户明确同意 → 再带 confirm: true 调用，否则工具直接拒绝。clean = fix + purge 一次完成。
• profile：默认当前启动的 profile；传 "all" 覆盖所有 profile。
• keep：purge 时保留的 settings 键。

rebuild 会删除本 profile 的 node_modules（含本插件自身），建议在 DSH 停掉后用 CLI 执行；运行中的 DSH 可能锁住原生模块导致删除失败（此时会报错并跳过 pnpm 步骤，不会留下半截状态）。

方式三：独立 CLI（profile 起不来时的救援路径）

profile 因为插件残留无法启动时，不依赖 DSH 引导，直接用 node 跑：

node "$DSH_HOME/profiles/web/node_modules/dsh-clean-reset/bin/reset.mjs" scan
node "$DSH_HOME/profiles/web/node_modules/dsh-clean-reset/bin/reset.mjs" fix --profile web --yes
node "$DSH_HOME/profiles/web/node_modules/dsh-clean-reset/bin/reset.mjs" all --profile web --yes

node bin/reset.mjs [mode] [options]

modes:  scan (默认，只报告) · fix (修 manifest/patch/市场 state) · purge (清孤儿 settings 段与数据)
        clean (fix + purge 一次完成) · rebuild (fix 后删 node_modules+lockfile 并 pnpm install)
        all (fix+purge+rebuild)
options:
  --profile <name>  目标 profile（可重复；默认全部）
  --home <dir>      DSH home 覆盖（默认 $DSH_HOME 或 ~/.dsh）
  --keep <key>      purge 必须保留的 settings 键（可重复）
  --yes             跳过确认
  --json            输出机器可读 JSON

退出码：0 干净；1 有发现/有改动；2 用法或致命错误。

安全设计

• scan 永远只读；所有写入都是先写临时文件再原子 rename。
• patch 文件按行区间删除，注释、!!js 表达式、无关配置逐字节保留；条目上方紧邻的注释不会被误删。
• settings 删除基于 yaml Document（保留注释与格式）。
• 破坏性模式必须 confirm: true（工具）/ --yes 或交互确认（CLI）。
• 引擎是纯 Node 实现，yaml 依赖懒加载——坏得只剩半个 node_modules 时 CLI 也能尽量给出报告。

开发

npm install          # 只需 yaml（netease registry 环境用 --registry https://npm.nie.netease.com/）
node test/smoke.mjs  # 全部夹具测试（在系统临时目录建假 DSH home，不碰真实数据）
# 想连 tool 注册一起测：DSH_INSTALL_DEPS=<dsh 安装目录>\node_modules\@deepseek-ai node test/smoke.mjs

目录结构：

cordis.patch.yml    bundle patch：把插件挂进 profile 组合
lib/index.js        cordis 插件入口：注册 dsh_clean_reset 工具 + 挂载 HTTP 路由
lib/host-routes.js  设置页按钮的后端：同源 /dsh-clean-reset/* 路由
lib/client.js       客户端半身：设置里的「插件重置」页面（含按钮与两步确认）
lib/engine.js       核心引擎（纯 Node，零 DSH 依赖）
bin/reset.mjs       独立 CLI
test/smoke.mjs      夹具测试（含路由与客户端注册测试）

已知边界

• settings.yaml 的孤儿判定是启发式的：核心白名单（llm-*/ui-*/permission/agent-presets/agent-default-model）+ 已安装插件名派生键之外的一律列为候选，purge 前清单会完整列出、可 --keep。
• purge 会删除「名称不匹配任何已安装插件」的 cache/*、skin-center/*、.agent-presets/* 目录和 pet.json——执行前确认面板会列出具体路径；若某目录是你手动创建且名字恰好像插件残留，请改名或用 --keep。
• profiles/node_modules 有两种身份：dsh 每次启动自动重建的模块回退目录（全是链接、无 pnpm 元数据——不是残留，插件不会报告也不会删）；只有真正跑错层的 pnpm 树（真实目录 + .modules.yaml 等）才会被报告，且只有在所有 profile 依赖自足时才会被 purge 删除。
• 修改 package.json/bundles 后需要重启 DSH 才生效；cordis.patch.yml 会被运行中的 DSH 热重载。