# 设计说明 / Design notes

这个文档记录 `toomuch-plugins` 做什么、怎么做、依赖哪些约定。改代码前先看这里。

## 1. 目标

DSH Web 左侧栏从上到下是：品牌行 → 新会话 → **全局面板入口** → 工作区 → 设置。

「全局面板入口」这一列会随着装的插件越来越多：插件、插件市场、定时任务、MCP Studio、
上下文、技能管理器、系统监控……每多一个插件，这一列就多一行，大约每行 40px。

本插件的目标只有一个：**在需要时把这列收起来，把空间还给工作区**。

## 2. 范围

做：

- 折叠侧栏根节点下的**全局面板入口列表**（一个 `<nav>`）。
- 在侧栏底部放一个开关，随时展开 / 收起。
- 记住选择，刷新后保持。

不做（有意为之）：

- **不碰品牌行、新会话、设置**。在 Linux / Windows 上，品牌行里的「收起侧栏」按钮是
  唯一的收起入口，把它一起藏掉等于少一个功能。
- **不隐藏任何面板本身**，只是不显示入口；面板内容从别处照常能打开。
- **不改动 Host 侧行为**，不注入任何 DSH 内部模块，不读写任何配置。

## 3. 依赖的 DOM 约定

插件不 import DSH 的内部包，纯粹靠下面几条约定工作（都来自
`@deepseek-ai/dsh-client-ui-sidebar`）：

| 约定 | 用途 |
| --- | --- |
| 侧栏根节点下有一个**直接子元素** `<nav>`，class 为 `panelList` | 全局面板入口列表，本插件要折叠的就是它 |
| 插槽 `sidebar.footer.action` | 侧栏底部那一行（「设置」旁边） |
| 插槽项的 `wide` 属性 | 窄栏（rail）模式下按钮收成圆形图标 |
| CSS 变量 `--dsw-alias-*` | 主题色 / 圆角 / 间距，跟随 DSH 明暗主题 |

**为什么向上回溯而不是直接 `document.querySelector('nav.panelList')`：**
class 名可能被构建工具 hash 或改名，而「直接子元素 `<nav>`」是结构关系，更稳定。
实现里从开关自己的根节点开始，逐级向上找「第一个含直接子 `<nav>` 的祖先」，直到
`document.body` 为止 —— 侧栏根节点一定是其中之一。

## 4. 状态与持久化

- 状态就一个布尔值：`collapsed`。
- 默认 **收起**（首次安装即刻生效，这是这个插件存在的意义）。
- 持久化用 `localStorage`，key = `dsh.sidebar-panel-collapse`，值 `'collapsed'` /
  `'expanded'`。
- 读取规则：**只有明确存了 `'expanded'` 才算展开**，其余一律按收起处理。这样即使
  localStorage 被清空、或者存了脏值，行为也是安全的默认值。

## 5. 数据流

```
用户点开关
   └─> setCollapsed(next)
          ├─> React 重新渲染（按钮文案 / 图标变化）
          └─> useEffect 重新执行 applyNav()
                 └─> nav.style.display = collapsed ? 'none' : ''
          └─> writeStored(collapsed)  // localStorage
```

`useEffect` 在每次渲染后都重新套用 `display`，因为 DSH 侧栏重渲染时可能重建这个
`<nav>`，只设一次会被覆盖。

## 6. 代码结构

| 文件 | 角色 |
| --- | --- |
| `src/index.js` | Host 半边。不需要任何 Host 能力，所以 `apply()` 是空的 |
| `src/client.js` | Client 半边。全部逻辑在这里：`FooterToggle` 组件 + 折叠 / 展开 |
| `cordis.patch.yml` | 往 profile 里插入一行插件加载记录（包名 `toomuch-plugins`，即仓库根） |
| `locale/{en,zh}.json` | 插件列表里显示的标题和描述 |

`package.json` 的 `exports` 把 Host 半边指向 `.`（`src/index.js`），Client 半边指向
`./client`（`src/client.js`）；DSH 通过这两个入口分别加载。

## 7. 兼容性风险

- 本插件依赖 DSH 内部 DOM 结构。DSH 改版后如果侧栏结构变了，最坏情况是**找不到目标
  `<nav>`，什么都不做** —— 不会报错、不会弄坏界面，属于安全失效。
- 不 import DSH 内部包，因此 DSH 升级不会让插件直接加载失败。
- 样式全部走 `--dsw-alias-*` 变量，不写死颜色；主题改动时不会失配。

## 8. 验证清单

改完代码后至少过一遍：

1. 装上插件后，侧栏底部「设置」上方出现开关。
2. 默认状态是收起的；点一下展开，再点一下收起。
3. 刷新页面后状态保持。
4. 展开成宽栏（≥ 展开宽度）时开关是一行文字；窄栏（56px rail）时是圆钮。
5. 收起状态下，工作区区域明显变高。
6. 没有全局面板时，开关点了不报错。
7. 浏览器控制台无报错。

## 9. 后续可能的扩展（都没做）

- 支持「折叠时仍显示某一个常用面板」。
- 支持把多个插件的侧栏行一起折叠（那更适合 `dsh-sidebar-quiet` 这类插件去做）。
- 记住每个窗口的展开状态而不是全局一个状态。