# 设计笔记（NOTES）

本文件记录 **README 不覆盖的内容**：为什么这样设计、哪些方案被否决、上下游机制的关键事实。
目的是让未来的自己（或接手的人）不必重新调研一遍。

- 环境：DSH `0.1.5-rc.2` / profile `web` / Windows 11
- 记录时间：2026-09-21
- 本文件是**结论存档**，不是使用文档；安装与用法见 [README](./README.md)

---

## 1. 问题的根因

DSH 左侧栏底部的 `sidebar.footer.action` 是 `kind: "list"` 槽位。上游渲染结构：

```
footArea (flex-direction: column)
  ├── footerActions  (display: flex → 未声明 direction，默认 row)
  │     ├── cost-meter        (dsh-cost-meter, order 0)
  │     └── context-overview  (dsh-context, order 10)
  └── settingsArea   (Settings 行)
```

**根因**：上游 `footArea` 自己声明了 `flex-direction: column`，但它只装 `footerActions` +
`settingsArea` 两个块；真正装插件的是内层的 `footerActions`，而它**只写了 `display:flex`、
没有写 `flex-direction`**。于是同一槽位的所有注册者横向挤在一行。

这是**上游的布局缺失**，不是配置问题——所以没有开关可调，只能覆盖样式。

上游 CSS（`dsh-client-ui-sidebar/lib/client.js` 内联）关键两行：

```css
.hHd-Xa_footArea{flex-direction:column;flex:none;display:flex}
.hHd-Xa_settingsArea,.hHd-Xa_footerActions{flex:none;width:100%;min-width:0}
.hHd-Xa_footerActions{display:flex}   /* ← 问题所在：没有 direction */
```

## 2. 被否决的方案（都验证过）

| 方案 | 为什么不行 |
|---|---|
| **改 `node_modules` 里的 CSS** | DSH 升级 / `pnpm install` 会被覆盖；且属于修改上游包，不可维护 |
| **插件市场找现成的** | 已排查市场全部 **418 个插件**，无任何插件管理此槽位布局（详见 §3） |
| **`dsh web` 命令行参数** | `--help` 只有 `--host` / `--port` / `--no-host` / `--trusted-host`，**没有**自定义 CSS 入口 |
| **主题设置里注入 CSS** | `dsh-client-ui-theme` 暴露的设置项只有外观、字号，**没有** `customCss` / `userCss` 之类 |
| **`settings.yaml`** | 只有 `ui-onboarding` / `agent-default-model` / `ui-theme`，无样式相关项 |
| **改注册顺序（order）** | order 只决定同一行内的先后，**不改变容器方向**，解决不了拥挤 |
| **不装 dsh-context** | 治标不治本，且用户确实需要该插件 |

→ 结论：**注入一段 CSS 覆盖是唯一可行且可维护的路径。**

## 3. 市场排查记录（418 个插件）

搜索过市场缓存的完整清单（`$DSH_HOME/profiles/web/.dsh-market/discovery-compatibility-v1.json`，
当时共 418 条）。与"侧边栏布局"相关度最高的候选及其实际功能：

| 插件 | 实际做什么 | 是否解决 |
|---|---|---|
| `dsh-better-sidebar` | 右列 + 底部工作台；代码里**完全不引用** `sidebar.footer.action` | ❌ |
| `dsh-ui-tweaks` | 代码字号、时间轴切换、海报皮肤、Git 分支 | ❌ 作用于对话区 |
| `dsh-ui-appearance` | 主题配色、背景图、透明模糊（`--dsw-*` token） | ❌ 作用于视觉主题 |
| `@vlln/dsh-navbar` | 对话节点导航条 | ❌ |
| `@falling-ts/dsh-force-compact` | 上下文强制压缩 | ❌ |

**验证方法**：不只看名字/描述，而是在已安装插件的 `lib/*.js` 里 grep `sidebar.footer.action`
与 `footerActions` / `footArea`，确认为零命中。

## 4. 为什么用 `[class*="_footerActions"]` 而不是 `.hHd-Xa_footerActions`

类名里的 `hHd-Xa` 是 CSS-Module 的**哈希前缀**，会随上游构建变化（DSH 已从 rc.1 迭代到 rc.2）。

选择器匹配**后缀**而非前缀，因此：

- 上游换哈希 → 仍然命中
- 若上游将来补上 `flex-direction: column` → 本规则退化为无害的重复声明，不会造成破坏

已写测试验证：命中 `hHd-Xa_footerActions` 与 `Zz9-Qq_footerActions`（任意哈希），
且**不误伤** `settingsArea` / `footArea`。

**代价**：若上游彻底重命名该 class（去掉 `_footerActions` 后缀），本插件会静默失效。
README 的「故障排查」给了重新探测类名的命令。

## 5. DSH client 插件的机制事实（踩过的坑）

来自 `dsh-client-modules` 的解析规则，写插件时必须满足：

1. `package.json` 必须声明 `dsh.client.platform = "web"`；
2. **必须**提供 `exports["./client"]`，否则启动直接抛错：
   `declares dsh.client but exports no "./client" bundle`；
3. browser 半侧产物**必须**用 `window.__ModuleLoader__.load({ id, factory })` 包装
   （已装的 `dsh-context` / `dsh-cost-meter` / `dsh-pet` 三者**都是**这个格式，不是标准 ESM）；
4. host 半侧导出约定为 `export { Config, apply, inject, name }`；
5. 浏览器侧的 bundle 路由是 `/plugins/<entry-id>/client.js`，且走 combo 路由合并加载。

**样式注入是官方做法**：DSH 官方 `dsh-client-ui-sidebar` 自己在 `lib/client.js` 里就是
`style[data-plugin-css="..."]` + `document.createElement("style")`；生态皮肤插件
`dsh-dream-skin` 用同一模式。本插件沿用该约定，并非自创 hack。

## 6. 收录渠道（结论）

| 渠道 | 机制 | 需要做什么 |
|---|---|---|
| [dshfind](https://dshfind.com) | 每天 UTC 02:17 扫 GitHub topic `dsh-plugin` | 仓库**公开** + 加 topic，**无需 PR/issue** |
| [DSH Plugin Radar](https://github.com/AdamPlatin123/awesome-dsh-plugins) | 往 `PLUGINS.md` 提 PR，做 k8s 运行实测 | 可选，能拿到 🟩 已兼容标记 |
| `dsh-market`（profile 内置） | 自带发现缓存 | 自动 |

**收录 ≠ 兼容**：Radar 明确声明静态检查不等于运行可用。本插件的收录状态若是 ⬜ 待测试属正常。

## 7. 排查中确认的环境事实（与本插件无关，但值得留档）

- **`D:\coding_workspace` 下 npm 直连极慢**：`registry.npmjs.org` 实测约 **317 KB/s**，
  而 `registry.npmmirror.com` 约 **7.5 MB/s**（约 20 倍差距）。
  大包（如 `dsh-pet` 的 tarball 约 57 MB）在直连下会因 pnpm 的 fetch 超时**反复从头下载**。
  已在 `~/.dsh/profiles/web/.npmrc` 与 `~/.npmrc` 配置 npmmirror 镜像 + 放宽超时。
- **Git 的 credential helper 曾不可用**：`C:\Program Files\Git\mingw64\bin` 不在 PATH，
  而 Git 系统配置是 `credential.helper = manager`，导致 helper 启动失败
  （报 `line 1: C:/Program: No such file or directory`——路径含空格未加引号），
  git 退化为交互式提示，表现为**无限弹 "Connect to GitHub"** 与 `ls-remote` 超时。
  已把该目录加入用户 PATH 修复。
- **GitHub Desktop 与 git 命令行凭据不共享**：Desktop 存的是
  `GitHub - https://api.github.com/<user>`，命令行需要的是 `git:https://github.com`。

## 8. 下一步（如果还要改）

- 若折叠态（56px 图标栏）间距不合适 → 调 `lib/client.js` 里 `_collapsed` 规则的 `gap`
- 若上游重构了该槽位 → 先用 README 里的探测命令确认新类名，再改选择器
- 若想覆盖右侧栏 → 那是另一套槽位（`sidebar.right.pane.tab` 等），本插件不涉及