# 37b · 功能插件分区 v0.2.0：官方 token 化 + i18n + 交互升级（批次 3）

- 日期：2026-09-11
- 触发：用户三问 —— ① 确认样式交互是否符合规范、是否比 dsh-market 好（整合优秀交互）② 按项目**亮色调** ③ 亮/暗切换与多语言的实现复杂度
- 状态：**✅ 已实施（commit `5f42fb7`）并验证**

> **TL;DR**｜**结论**：「功能插件」section 升级 v0.2：**官方 `--dsw-*` design token**（自动跟随亮/暗/第三方主题）+ 官方 locale 中英双语。
> **关键**：交互补齐：搜索 / 状态徽章 / 全选清空 / 被自动禁用插件的行内提示与重试 / 重启后探活再刷新。
> **状态**：✅ 已实施并验证

## 一、调研结论（决定了做法）

| 事实 | 影响 |
|---|---|
| dsh 官方客户端（含设置面板）使用 **`--dsw-*` design token（CSS 变量）**：`--dsw-alias-label-primary/-secondary/-tertiary`、`--dsw-alias-bg-layer-{1,2,3}`、`--dsw-alias-border-l{1,2,3}`、`--dsw-alias-brand-primary`、`--dsw-alias-state-{error,success}-primary`、`--dsw-elevation-prominent` 等 | **正解不是"改成亮色十六进制"，而是改用官方 token** → 自动跟随主题 |
| 官方主题插件 = `@deepseek-ai/dsh-client-ui-theme` | **亮/暗切换由官方提供，我们零成本跟随**，不需要自己实现 |
| dsh-market（567KB client）**全量使用 `--dsw-*`**；交互词表含 更新/失败/确认/重启/卸载/已安装/停用/重试/重新安装/搜索插件/分类/暂无 | 我们 v0.1.0 的差距：硬编码深色、无搜索、无状态词、失败只有一行文字 |
| 官方 i18n：`ctx.effect(() => ctx.locale.register(NS, {zh, en}))` + `ctx.locale.bind(NS)`，`inject` 需含 `"locale"` | 多语言**复杂度低**，直接复用 |

## 二、v0.2.0 改动（`@dsh-local/business-plugins` client half）

1. **配色全部改官方 token**（原硬编码 `#f9fafb/#c9cdd4/#4f6ef7` 等）→ 与官方深色面板和谐，且**亮/暗/第三方主题自动适配**。
2. **文案走官方 locale**（zh/en 双语）；section label 改为 `t("section.label")`。
3. **交互升级**（对齐 dsh-market 的优秀做法）：
   - 搜索过滤（名称/描述）
   - 每行**状态徽章**：`已启用` / `未启用`
   - 全选 / 清空 + 「已选 N / M」计数
   - 加载态、空态
   - **被门户自动禁用的不兼容插件：行内 `⚠` 标记（悬浮显示真实 reason）+「重试」按钮** —— 与档案 34 的隔离机制闭环
4. **重启后自动刷新页面**：应用成功且实例重启时，先探活（最多 3 次 × 1.5s）再 `location.reload()`，避免实例重启窗口白屏。

## 三、验证

| 检查项 | 结果 |
|---|---|
| 已装版本 | ✅ guest `node_modules/@dsh-local/business-plugins/package.json` = **0.2.0** |
| token 化 | ✅ 已装 `lib/client.js` 含 `dsw-alias-label-primary` |
| i18n | ✅ 含 `locale.register` |
| bundle 被加载 | ✅ `.dsh-biz-plugins.log` 新增 `apply pid=2` 标记 |
| **UI 实拍** | ✅ headless Chrome 打开 guest 实例 → 设置面板 → **「功能插件」分区已出现**（与「通用设置 / Agent 预设」平级），显示 v0.2.0 locale 空态「**暂无功能插件（需管理员在门户投放）**」，配色融入官方面板 |

## 四、顺带修掉一个真实风险：bundle 源码从未进版本控制

`.gitignore` 的 `lib/`（本意忽略 TS 构建产物）**连 `poc/<plugin>/lib/` 一起忽略了** →
**平台两个自建 client bundle 的源码（`client.js` / `index.js`）从来没有进 git**：
`@dsh-local/business-plugins` 与 `@dsh-local/workspace-scoped-picker` 都中招。
→ 一旦 `/opt/dsh/docs/04-调整方案/poc/` 那份丢失，这两个插件**无法重建**。

**修法**（commit `04a2496`）：加反忽略 `!poc/*/lib/` + `!poc/*/lib/**`，并把两个 bundle 的 `lib/` 一并入库。

## 五、回答用户第 ③ 问（复杂度）

| 需求 | 做法 | 复杂度 | 本次是否已做 |
|---|---|---|---|
| 按项目亮色调 | 改用 `--dsw-*` token；主题由 dsh 决定 | 低 | ✅ |
| 亮/暗切换 | **不需要我们实现** —— 跟随官方 `dsh-client-ui-theme` | ≈ 零 | ✅（自动） |
| 多语言 | 官方 locale 机制，注册 zh/en | 低（~30 行） | ✅ |

## 六、后续

- 若要"平台统一指定亮色"：可在 profile 层设 dsh 主题默认值（未做，等需求）。
- 小尾巴仍在：admin 侧事故可见性（`audit` 只有写没有读 → 需加读取方法才能在门户显示「N 个用户启用失败」）、重启前 `dump-config` 预检、批量上限保护（N>5 只回滚）。