---

和同类插件有何不同

DSH 生态里有不少「单点功能」插件（只做回退、或只做归档等）。本插件刻意选择不同的定位：做成一套可开箱即用的全家桶，而非叠加多个小插件。

维度	本插件（dsh-essentials-bundle）	单点同类竞品（如 dsh-rewind / dsh-turn-rewind / dsh-turn-delete / dsh-unarchive）
定位	全家桶：5 类场景一个包搞定	通常只解决一个功能点，需要装多个插件才能凑齐
覆盖	壁纸 + 用量统计 + 会话管理 + 每轮撤销 + 文件浏览器/编辑器	多为回退或归档单一能力
独占卖点	带产物回退的每轮撤销（fork + git 磁盘快照回退 + 文件快照 + 子代理清理）、文件浏览器 / 就地编辑器	多为纯消息层回退，不带文件/子代理回收
生态入口	以 dsh-plugin / cordis-plugin topic 收录，便于发现	分类更分散
变更原则	只注入不覆盖，零依赖，跨小版本内置 fail-open 降级	各自实现，契约侵入深浅不一

一句话：如果只想补一个功能，装对应的小插件即可；如果你想要一套开箱即用的 DSH 基础体验，装这一个 bundle 就够了。

---

功能模块

围绕 DSH 聊天工作流的日常使用，这个 bundle 把 5 类高频能力打包进一个插件，开箱即用。

🖼 模块一：聊天界面换张背景

不想再看默认的纯白/纯黑聊天窗？在 设置 → 通用 → 壁纸背景 上传一张本地图，或直接粘贴一个图片 URL，聊天区立刻变成你的风格。

• 支持透明度、暗化、对齐、模糊、缩放、暗角、覆盖范围、场景增强逐项微调；
• 配置保存到浏览器 localStorage，下次打开依旧是你的设定；
• 适合用一张半透明的氛围图，把聊天区打造成专注的 workspace。

📊 模块二：实时盯着 token 花了多少

代码写嗨了怕超额度？在 设置 → 查看用量 查看统计面板：

• 汇总输入 / 输出 / 缓存读取 token 与消息条数；
• 下方列出每个会话的明细，找出最费 token 的那轮；
• 每 60s 自动刷新，不用手动点。

🗂 模块三：整理越来越长的会话列表

会话一多就乱？在 设置 → 会话管理 集中管理：

• 删除会话，带运行中保护（agent 还在跑时不给删）+ 二次确认防误删；
• 一键清空子代理记录，释放磁盘并让列表更清爽。

↩️ 模块四：撤销点错的那一轮

AI 这轮答歪了、还顺手改乱了磁盘文件？在每个 AI 回复的操作行点撤销图标：

• 整轮对话被移除（fork），并回退该轮对磁盘的改动：改写的内容还原、该轮新建的文件删除、删除的文件找回；
• 一并清理这轮新开的子代理记录，回到干净状态。
• 磁盘回退基于「隔离 git 快照」：插件在每轮结束时，把会话工作目录用独立 git 仓库（~/.dsh/essentials/snap-repo/，不碰工作区的 .git、不污染真实提交历史）拍一次快照，撤销时把工作目录恢复到上一轮边界。需服务器装好 git，未检测到 git 时磁盘回退自动停用（插件编辑器快照 + 子代理清理仍生效），不影响其他模块。

📁 模块五：不开文件管理器就在旁边翻文件

边聊边改代码，还要切出去看文件？装了这个插件，右侧会有个常驻文件面板：

• 折叠树懒加载会话工作目录，不用一次读全；
• 按文件名搜索快速定位；
• Markdown / 代码高亮预览，直接看内容；
• 就地编辑（Ctrl+S 保存）与新建文件 / 新建文件夹 / 重命名 / 删除，改代码不用离开页面。

---

适配版本

项	说明
适配 DSH	仅验证 v0.1.1-rc.2（组件由 DSH web 启动时注入，client 模块清单在启动时构建，升级 DSH 后如失效请重启）
兼容性	低版本未测试。 插件的撤销 / 会话管理依赖较新的 DSH 内部契约（sessions.fork(atSeq)、workspaceRegistry 等），这些 API 无文档保证，跨小版本可能变更签名；相关调用已做 fail-open 降级，但在旧版本上可能退回基础行为，请以 v0.1.1-rc.2 为准
插件版本	1.3.0
平台	DSH Web

---

安装

本插件作为 profile 的外部包（out-of-tree / file 依赖） 使用。

# 1. 打包（在插件目录）
npm pack

# 2. 在 DSH 的 web profile（如 ~/.dsh/profiles/web）里作为 file 依赖安装
#    package.json 增加：
#      "dependencies": { "dsh-essentials-bundle": "file:/path/to/dsh-essentials-bundle-<ver>.tgz" }
cd ~/.dsh/profiles/web
pnpm install

# 3. 本插件自带 dsh.bundle（cordis.patch.yml），会自动 insert 进 profile 的 Loader entries。
#    其 cordis 插件名 = 包名 dsh-essentials-bundle（与 lib 导出的 name 一致）

安装后重启 DSH web，插件即以 dsh-essentials-bundle 的 cordis 名称加载（client 模块清单在启动时构建，改名/换装后需重启）。

---

界面入口

功能	入口位置
🖼 壁纸背景	设置 → 通用 → 壁纸背景
📊 查看用量	设置 → 查看用量（顶级节）
🗂 会话管理	设置 → 会话管理（顶级节）
↩️ 撤销该轮对话	每条 AI 回复操作行 → 撤销图标（复制按钮旁）
📁 文件浏览	会话头部 → 文件浏览按钮，打开右侧常驻面板

---

后端路由（/dsh-essentials/*，同源只读 / 有限写）

方法	路径	作用
GET	/usage	Token 用量汇总 + 按会话
GET	/subagents	统计子代理记录
POST	/subagents/clear	清空全部子代理记录
GET	/files	列目录（白名单内）
GET	/read	读取文本文件（≤256KB，拒二进制）
POST	/write	编辑已存在文本文件（写前快照）
POST	/create	新建文本文件（白名单内）
POST	/rename	重命名文件/文件夹（白名单内）
POST	/delete-entry	删除文件/文件夹（递归，白名单内）
GET	/search	递归按文件名搜索
POST	/mkdir	新建文件夹
GET	/cwd	取最新会话工作目录
POST	/upload	上传背景图（≤16MB）
GET	/file/<name>	读取已上传的背景图（作为壁纸 img src）
POST	/session/delete	删除会话（防误删 + 路径双保险）
POST	/session/undo-seq	解析可撤销信息（fork 边界 / 时间窗 / 文件清单）
POST	/session/undo-artifacts	回退该轮产物（git 磁盘快照还原 + 文件快照 + 子代理记录）

---

配置与数据

• 持久化设置：全部壁纸配置存浏览器 localStorage（键前缀 dsh-essentials:）。
• 上传图 / 撤销快照：存放于用户数据目录（~/.dsh/essentials/，含 uploads/、snapshots/（插件编辑器快照）、snap-repo/（git 磁盘快照仓库）、snap-meta.json（轮次↔快照映射））。
• git 依赖：磁盘产物回退依赖服务器可执行的 git（sudo apt-get install -y git）。无 git 时该功能自动停用并降级，不影响其他模块。
• zstd 依赖：会话日志是 .zstd 压缩，Token 用量统计依赖服务器可执行的 zstd（通常随 DSH 运行环境自带）。插件启动时会探测 zstd --version，缺失时用量统计跳过解码、仅打印一条警告（不丢数据、不影响其他模块）；建议 sudo apt-get install -y zstd。

---

设计要点

• 零依赖：原生 node: API + 内联少量实现（简易 Markdown 渲染 / 轻量语法高亮），无第三方运行时依赖。
• 不覆盖核心：仅注入插槽与 dsh.client 声明，所有路由都是只读 / 有限写。
• 安全：
  • 会话删除：agents running 保护 + SESSION_ID_RE 白名单 + 路径穿越双保险。
  • 文件操作：允许根白名单（ALLOWED_ROOTS）+ 大小上限 + 二进制拒读。
  • 上传：扩展名 / Content-Type 白名单 + 去路径穿越文件名清洗。

---

License

MIT