前言¶
在 DSH 里，工作区往往对应真实磁盘路径，侧栏里会挂着多条会话。多人共用机器、偶尔把浏览器留在前台，或者本机里还有别的同事能点开同一个 DSH 页面时，「整条工作区树在界面上裸露」会变成一种很具体的尴尬：不用进终端，点几下就能看见某个目录下的对话历史。
逐个会话加锁、或者靠操作系统账户隔离，都能缓解一部分问题，但和「按文件夹整棵收起来」不是同一种模型。dsh-workspace-lock（维护者 phzt-hub，社区分类 admin-security）做的是后者：在 Web 界面里给整个工作区文件夹加密码锁，锁上后侧栏收起该文件夹、其下会话行批量隐藏，锁/解锁集中在「工作区锁」面板；忘记密码可走 QQ 邮箱验证码重置。下文按安装、日常使用、边界与找回说明，事实以插件 README 与仓库元数据为准。
这是什么¶
dsh-workspace-lock 是跑在 DSH web profile 上的 Cordis 插件，当前仓库版本为 0.2.2，许可证 MIT，要求 Node ≥ 20。它不加密磁盘上的项目文件，而是在 DSH 侧栏与主界面里做「门禁」：锁定后界面上看不见、点不进该文件夹及其会话；本机其他程序、命令行、备份仍能读到明文——防的是别人随手点开你的 DSH。
核心功能¶
文件夹级锁定，不是逐个会话锁¶
锁定对象是整个工作区文件夹。一锁上，侧栏里该文件夹立刻收起，内部会话行整批隐藏，不会出现「每个会话弹一次密码页」的逐个会话锁。锁/解锁都在「工作区锁」面板完成。
三种操作语义¶
面板里每个文件夹一行，对应三种动作：
- 锁定：进入锁定状态，侧栏收起、会话隐藏。
- 解锁（只在本页）：仅在当前页面临时解开；刷新后重新锁上。
- 解除锁定（永久，需要密码）：从状态文件里删掉该路径的锁定记录，需验证总密码。
自动重新上锁¶
默认 15 分钟无操作自动重新上锁；可在面板里修改，设为 0 表示不自动锁。
QQ 邮箱找回密码¶
忘记总密码时，可用 QQ 邮箱收 6 位验证码重置（10 分钟有效，最多试 5 次）。锁定页与面板都提供找回入口；改找回邮箱需总密码，防止他人把自己的邮箱写进配置再走找回流程。
宿主 API 与状态持久化¶
密码与锁定路径由宿主侧 API 管理，状态默认写在 $DSH_HOME/workspace-lock/state.json（未设置 DSH_HOME 时为 ~/.dsh/workspace-lock/state.json，权限 0600）。密码仅存 scrypt 派生值；SMTP 授权码写在同一文件，不回传页面。主要路由包括：
GET /api/ws-lock/statePOST /api/ws-lock/password、/verify、/toggle、/configPOST /api/ws-lock/test-email、/recover/request、/recover/verify
界面通过多处插槽挂载：sidebar.panellist 增加锁图标面板，main 展示文件夹清单与配置，shell.overlay 在兜底场景用全屏密码页挡住进入锁定目录的会话；侧栏对文件夹行的收起与会话隐藏因 DSH 未提供专用钩子，插件在 shell.overlay 侧结合 DOM 与会话/工作区 props 实现（DSH 升级侧栏结构时，最坏情况是「不再收起」或「会话仍显示」，而非进程崩溃）。
安装与启用¶
插件属 web profile，宿主端仅使用 Node 内置模块（crypto / fs / os / path / tls），无原生依赖，也不依赖外部托管服务。安装任选其一：
# 从 npm 安装
dsh plugin --profile web add dsh-workspace-lock
# 或者直接从 GitHub 源码安装
dsh plugin --profile web add github:phzt-hub/dsh-workspace-lock
装完后必须重启 dsh web：宿主端代码需重启才生效（浏览器端模块可热替换）。重启后左侧侧栏出现锁图标，点开即「工作区锁」面板。
若需改状态文件位置，可在 cordis.patch.yml 对应条目下增加 config.statePath，例如：
- id: dsh-workspace-lock
config:
statePath: /opt/dsh/workspace-lock/state.json
典型用法¶
首次：设总密码并锁定文件夹¶
- 打开侧栏锁图标，进入「工作区锁」面板。
- 设置总密码（后续锁定、永久解除、改找回邮箱都会用到）。
- 在文件夹清单中对目标路径点「锁定」。
锁定后侧栏该文件夹收起，其下会话不可见；若从其他入口误入锁定目录下的会话，shell.overlay 会用全屏密码页兜底。
临时查看：只在本页解锁¶
需要短时间查看内容时，使用「解锁（只在本页）」。看完刷新页面即恢复锁定，无需改状态文件。
不再需要锁：永久解除¶
确认不再对该文件夹做界面锁定时，使用「解除锁定（永久，需要密码）」，会从 state.json 的 lockedPaths 中移除该路径。
配置 QQ 邮箱找回¶
在 QQ 邮箱：设置 → 账户 → 开启 POP3/SMTP 服务 → 生成授权码（不是登录密码）。在面板填入邮箱与授权码后，先点「发一封测试邮件」确认链路，再依赖「忘记密码」流程收验证码设新密码。
自动锁 idle 时间¶
在面板调整自动重新上锁分钟数；设为 0 关闭 idle 自动锁，仅保留手动锁定与刷新后恢复锁的行为（针对「只在本页解锁」）。
适用场景与注意¶
适合谁： 同一台机器或同一浏览器会话可能被他人短暂使用、又希望在 DSH 里按目录粒度隐藏整块工作区与会话时，可用本插件做界面层门禁。社区目录将其归为 admin-security，侧重管理面的访问控制，而非存储加密。
务必区分的边界： README 明确说明这是门禁，不是磁盘加密。锁定后 DSH 内不可见、不可进，但本机其他程序与备份仍能读明文。
插件权限： 插件以当前 dsh web 进程权限运行，状态文件与 API 在同一宿主进程内处理。安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全策略。
忘记密码且未配邮箱： 锁屏与面板都无法进入时，只能停掉 DSH，编辑 ~/.dsh/workspace-lock/state.json，删除 password 与 lockedPaths（或删除整个文件）后重启。「只在本页解锁」本身只在浏览器内存，刷新也会回到锁定。
开发与升级： 修改宿主代码后同样需要重启 dsh web；仓库提供 node test/smoke.mjs 等校验，界面行为需在装进 profile 后在浏览器中确认。
结尾¶
dsh-workspace-lock 把「工作区文件夹 + 其下全部会话」收成一把总锁，操作集中在「工作区锁」面板，并可选 QQ 邮箱找回与 idle 自动重锁。若你正在 DSH 生态里找目录级界面隐藏而非全盘加密，可以从 npm 或 GitHub 安装，重启 dsh web 后从侧栏锁图标开始配置。
