chore: v0.8.2 — 版本升级（跟随 DSH 的 i18n）

AGENTS.md

@@ -407,6 +407,7 @@ interface BetterSidebarService {
 | **host 半无此服务** | `ctx.betterSidebar` 只在 client 侧存在；host 半需要 better-sidebar 数据走 `/sidebar/api/*` HTTP 路由 |
 | **portal 限制** | 整面板 slot 由 ui-layout 独占，外部 tab 只能进入 better-sidebar 的 portal 内部，无法全屏替换 |
 | **id 冲突** | `registerTab` / `registerFileViewer` 对重复 id 抛错；建议用包前缀（`my-plugin:xxx`） |
+| **i18n 跟随** | 侧边栏界面文案跟随 DSH 的 `ctx.locale`（`@deepseek-ai/dsh-client-locale`）：词典注册在 `betterSidebar` 命名空间，语言偏好（Host-backed `locale.preference`）与浏览器语言不一致时以 DSH 为准并实时切换；locale 服务缺失时回退浏览器语言。插件自身的 `t()`（`src/client/locales.ts`）由 `apply()` 挂接服务；消费插件**不要**依赖此内部函数——标题等字段传字符串或 `() => string` 即可（i18n 友好） |
 | **懒加载 chunk** | 内置重依赖（Univer/xterm/CodeMirror/pptx/docx）在独立 bundle（`lib/client-<name>.js`）中，经 `/sidebar/bundle` 路由按需下发；每个脚本把 factory 赋到插件自有全局注册表 `globalThis.__dshChunks__[<name>]`，由 `src/client/chunk-loader.ts` 用自定义 require（externals 经 `__DSH_MODULES__` seed 分支解析）物化——**不经过** `__ModuleLoader__` 注册；**核心 bundle 禁止静态 import `src/client/chunks/*`**（会把库拖回启动路径）；对消费插件透明——懒加载只作用于内置 descriptor，`component` 契约（`(props) => ReactNode` 纯渲染函数）不变 |
 
 ---

README.md

@@ -25,6 +25,7 @@ https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86
 - **🔁 会话隔离**：布局/分栏/Tab/两面板状态按会话持久化（localStorage），陈旧状态自动净化；聊天「产出文件」改在侧边栏打开（面板折叠时自动展开）
 - **⚙️ 声明式设置**：设置页「侧边卡片」分区按注册表渲染功能清单（小卡片网格，高亮 = 启用），每项可独立开/关；二级设置（子代理自动展开、终端工具、底部面板首展自动开终端、沙箱开关等）经齿轮按钮在原生弹窗中编辑
 - **🔌 服务化**：暴露 `ctx.betterSidebar` 服务，其他插件可注册侧边栏 tab 与文件预览器（内置 7 tab + 9 viewer 也走同一服务，详见 [AGENTS.md](./AGENTS.md)）
+- **🌏 多语言**：界面文案跟随 DSH 的语言设置（zh/en）实时切换——Host 偏好优先于浏览器语言，词典注册进 DSH 的 i18n 命名空间；切换语言无需刷新
 
 ## ⌨️ 快捷键
 

docs/plans/2026-08-12-follow-dsh-i18n-design.md

@@ -0,0 +1,60 @@
+# 跟随 DSH 的 i18n（ctx.locale）设计
+
+> 2026-08-12 · 随 v0.8.2 发布
+
+## 背景
+
+better-sidebar 的界面文案（约 260 处 `t()` 调用、28 个文件）此前自带 zh/en 词典并直接读
+`navigator.language`（`src/client/locales.ts` 头注释曾明言"renders outside the slot
+system's locale seat, so it reads the browser language directly"）。问题：
+
+- DSH 的语言偏好是 Host-backed（`locale.preference`，存于 `$DSH_HOME/settings.yaml`），
+  用户设置与浏览器语言不一致时侧边栏不跟随（如偏好 zh、浏览器 en 时侧边栏仍为英文）。
+- 词典游离在 DSH 的 i18n 注册表之外，无法参与公共命名空间回退等机制。
+
+DSH 的 i18n 系统（`@deepseek-ai/dsh-client-locale`）：
+
+- `ctx.locale` 服务（client-only）：`getSnapshot()/subscribe()` 是 LocaleFace
+  （uSES 安全，revision 递增），`locale/change` 事件在切换时触发；
+- `ctx.locale.register(ns, {zh, en})` 命名空间词典注册（typed 变体要求合并
+  `LocaleNamespaceMap`）；查询链 ns → common → zh → key；
+- 所有 DSH 客户端包以 `inject = [..., 'locale']` 消费。
+
+## 设计决策
+
+1. **结构镜像服务**（仓库惯例，`src/context-types.ts` 头注释）：本插件解析在 DSH
+   monorepo 单一 cordis 实例之外，上游 `declare module 'cordis'` augmentation 不达此
+   Context。新增 `SidebarLocaleService` 结构脸（只镜像用到的切片：
+   `getSnapshot` / `subscribe` / `register`），merge `Context.locale`。不引入
+   `@deepseek-ai/dsh-client-locale` 依赖、不做 value import（client bundle 纯度门）。
+2. **保留模块级 `t()`**：`t()` 被 28 个文件使用，穿 props 不可行。改为模块级 holder：
+   `apply()` 调 `attachLocale(ctx.locale)`，`t()`/`isZh()` 从 holder 读活跃 locale；
+   无 holder 时回退既有 `navigator.language` 检测（行为与改动前完全一致，也是 jsdom
+   测试与非标准组合的降级路径）。
+3. **根级重渲染触发**：侧边栏自行 `createRoot` 挂在 slot 系统之外，拿不到 `t` seat。
+   在 `Sidebar.tsx` 根组件加 `useSyncExternalStore(ctx.locale.getSnapshot/subscribe)`
+   （该文件已用此 API 订阅 sessions/store）；树内无 `React.memo`，根重渲染即整树
+   重渲染，所有渲染期 `t()` 求值读到新语言。事件期调用（intercept、api、subagent-tasks）
+   在调用时刻读当前语言，天然正确。SideCardSection 由 settings shell 渲染，shell 自身
+   订阅 locale revision（ui-settings-general 的 section rows 缓存含 locale revision），
+   自动跟随。
+4. **命名空间 `'betterSidebar'`**：`'sidebar'` 已被 DSH 的 ui-sidebar 占用。注册走
+   非类型化单语言重载 `register(ns, locale, dict)`（DSH 内 ui-permission 同款先例）；
+   键型安全由本地 `const en: Record<keyof typeof zh, string>` + 测试键集相等断言保证。
+5. **词典注册进 DSH 注册表**：`ctx.effect` 内注册 zh/en 并返回合并 disposer
+   （fiber 卸载时撤销，HMR 重激活不抛 "already registered"）。
+6. **xlsx 预览的 Univer locale pack**：`xlsx-view.tsx` 原内联 navigator 检测改走
+   `isZh()`（跟随 DSH 语言；Univer 实例在挂载时创建，语言切换不重建实例——可接受）。
+
+## 实施偏差记录
+
+- 无。计划与实施一致。
+- 版本号随 v0.8.2 发版提交（`package.json` + `dsh.plugin.json`）。
+
+## 验收
+
+- `pnpm typecheck` / `pnpm test` / `pnpm build`（纯度门）全绿；`tests/locales.spec.ts`
+  覆盖：无服务回退、attach 后跟随活跃 locale 实时切换、detach 恢复回退、占位符插值、
+  relativeTime 链路、命名空间名、zh/en 键集相等。
+- 手动：设置页切换语言 → 侧边栏全部文案实时切换；`locale.preference: zh` 且浏览器 en
+  → 侧边栏中文。

dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-better-sidebar",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "main": "./lib/index.js",
   "description": "VSCode 风格右侧侧边栏：文件资源管理器 / 编辑器 / 终端 / Git / 浏览器，按会话隔离。暴露服务供其他插件注册侧边栏页面和文件预览器",
   "engines": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-better-sidebar",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "DSH web plugin: a VSCode-like right sidebar (explorer / editor / terminal / git / browser), isolated per conversation session. Exposes a service for other plugins to register sidebar tabs and file viewers.",
   "private": true,
   "type": "module",
@@ -37,6 +37,7 @@
     "client": {
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-ui-conversation"
       ],

src/client/Sidebar.tsx

@@ -104,6 +104,15 @@ function buildNewTabOptions(state: SidebarState, ctx: Context, scope: SessionSco
 export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
   const { ctx, store } = props
 
+  // Copy freshness: re-render the whole tree when the DSH locale switches.
+  // The module-level t() reads the active locale at call time, so a root
+  // re-render alone re-localizes every panel (no memo barriers below).
+  const localeRevision = useSyncExternalStore(
+    useMemo(() => (callback: () => void) => ctx.locale.subscribe(callback), [ctx]),
+    useCallback(() => ctx.locale.getSnapshot().active, [ctx]),
+  )
+  void localeRevision
+
   // Narrow (mobile) viewports collapse the two panels into one: the right
   // panel becomes a full-width drawer holding BOTH workbenches, the bottom
   // panel (and its toggle button) disappears, and the layout push is

src/client/index.tsx

@@ -22,12 +22,13 @@ import { registerImeGuard } from './ime-guard.ts'
 import { loadPrefs } from './prefs.ts'
 import { SideCardSection } from './SideCardSection.tsx'
 import { api } from './api.ts'
-import { t } from './locales.ts'
+import { LOCALE_NS, attachLocale, t, zh, en } from './locales.ts'
 import css from './sidebar.module.css'
 import './layout.css'
 
-/** Services required before mounting (provided by the client runtime). */
-export const inject = ['slots', 'sessions', 'connection', 'workspaces']
+/** Services required before mounting (provided by the client runtime; the
+ *  locale service backs the sidebar's copy — see locales.ts). */
+export const inject = ['slots', 'sessions', 'connection', 'workspaces', 'locale']
 
 /**
  * Error boundary over the sidebar tree: a render error must never blank the
@@ -69,6 +70,17 @@ class SidebarBoundary extends Component<{ children: ReactNode }, { error: string
  * @param ctx - the client cordis context (slots, sessions).
  */
 export function apply(ctx: Context): void {
+  // The sidebar follows the DSH i18n system: attach the locale service so
+  // the module-level t()/isZh() resolve the Host-backed language preference
+  // (and switch live — the Sidebar root subscribes to it), and register the
+  // plugin's dictionaries into the shared locale registry. The disposers
+  // run on fiber disposal, so re-activation (HMR) re-registers cleanly.
+  attachLocale(ctx.locale)
+  ctx.effect(() => {
+    const offZh = ctx.locale.register(LOCALE_NS, 'zh', zh)
+    const offEn = ctx.locale.register(LOCALE_NS, 'en', en)
+    return () => { offZh(); offEn() }
+  }, 'dsh-better-sidebar: dictionaries')
   // One store instance per activation: production code creates it only here,
   // then hands it to the mounted panel and closes over it in the slot
   // registrations (the official createXXXStore() factory rule — no

src/client/locales.ts

@@ -1,11 +1,16 @@
 /**
- * Minimal zh/en copy for the sidebar. The plugin renders outside the slot
- * system's locale seat, so it reads the browser language directly (the DSH
- * locale preference and the browser language agree in practice; both default
- * from navigator.language anyway).
+ * Minimal zh/en copy for the sidebar. The copy follows the DSH i18n system:
+ * the client apply attaches the locale service (`ctx.locale`, provided by
+ * `@deepseek-ai/dsh-client-locale`) through {@link attachLocale}, and
+ * `t()`/`isZh()` resolve the active locale from it — the Host-backed
+ * `locale.preference` wins over the raw browser language and switches live.
+ * Without an attached service (standalone/test compositions) the browser
+ * language is used, matching the previous behavior. The dictionaries are
+ * also registered into the DSH locale registry under {@link LOCALE_NS}.
  */
 
-const zh = {
+/** The zh dictionary (also registered into the DSH locale registry under {@link LOCALE_NS}). */
+export const zh = {
   explorer: '资源管理器',
   git: '源代码管理',
   terminal: '终端',
@@ -204,7 +209,8 @@ const zh = {
   taskKillError: '终止失败',
 }
 
-const en: Record<keyof typeof zh, string> = {
+/** The en dictionary (key-set-equal to zh, enforced by the type annotation). */
+export const en: Record<keyof typeof zh, string> = {
   explorer: 'Explorer',
   git: 'Source Control',
   terminal: 'Terminal',
@@ -403,13 +409,42 @@ const en: Record<keyof typeof zh, string> = {
   taskKillError: 'Kill failed',
 }
 
-/** Translate a copy key in the browser's language (zh → zh, else en). */
+/**
+ * The dictionary namespace this plugin owns in the DSH locale registry
+ * (`'sidebar'` is taken by DSH's own ui-sidebar, hence this distinct name).
+ */
+export const LOCALE_NS = 'betterSidebar'
+
+/** The DSH locale service attached by the client apply (absent → browser detection). */
+let localeService: { getSnapshot(): { active: string } } | undefined
+
+/**
+ * Attach (or detach, with undefined) the DSH locale service. The sidebar
+ * mounts its own React root outside the slot system's locale seat, so the
+ * service rides this module-level holder: components keep calling the plain
+ * `t()` function, and the Sidebar root's locale subscription re-renders the
+ * whole tree on switches.
+ */
+export function attachLocale(service: { getSnapshot(): { active: string } } | undefined): void {
+  localeService = service
+}
+
+/**
+ * The active locale id ('zh' | 'en'): the DSH locale service's snapshot when
+ * attached, else the browser language.
+ */
+function activeLocale(): string {
+  return localeService?.getSnapshot().active
+    ?? (typeof navigator !== 'undefined' ? navigator.language : '')
+    ?? 'en'
+}
+
+/** Translate a copy key in the active locale (zh → zh, else en). */
 export type CopyKey = keyof typeof zh
 
 /** Translate a copy key; `{name}` placeholders interpolate from `params`. */
 export function t(key: CopyKey, params?: Record<string, string | number>): string {
-  const lang = typeof navigator !== 'undefined' ? navigator.language : 'en'
-  const dict = lang.toLowerCase().startsWith('zh') ? zh : en
+  const dict = activeLocale().toLowerCase().startsWith('zh') ? zh : en
   let text = dict[key]
   if (params !== undefined) {
     for (const [name, value] of Object.entries(params)) {
@@ -419,9 +454,9 @@ export function t(key: CopyKey, params?: Record<string, string | number>): strin
   return text
 }
 
-/** Whether the browser language is Chinese (used for selectors). */
+/** Whether the active locale is Chinese (used for selectors). */
 export function isZh(): boolean {
-  return typeof navigator !== 'undefined' && navigator.language.toLowerCase().startsWith('zh')
+  return activeLocale().toLowerCase().startsWith('zh')
 }
 
 /** Format an ISO 8601 author date relative to now (刚刚 / N 分钟前 / N 小时前 / 昨天 / date). */

src/client/xlsx-view.tsx

@@ -11,7 +11,7 @@
  */
 import { useEffect, useRef, useState } from 'react'
 import { mediaUrl } from './api.ts'
-import { t } from './locales.ts'
+import { isZh, t } from './locales.ts'
 import { BinaryFallback, type LoadState, type OfficeViewProps } from './office-shared.tsx'
 import { xlsxWorkbookToUniver } from './xlsx-to-univer.ts'
 import css from './sidebar.module.css'
@@ -54,14 +54,14 @@ export function XlsxView(props: OfficeViewProps): JSX.Element {
         const XLSX = await import('xlsx')
         const { createUniver, LocaleType, mergeLocales } = await import('@univerjs/presets')
         const { UniverSheetsCorePreset } = await import('@univerjs/preset-sheets-core')
-        // Locales pick the browser language; falls back to en-US.
-        const isZh = typeof navigator !== 'undefined' && navigator.language.toLowerCase().startsWith('zh')
-        const localePack = await (isZh
+        // Locales follow the DSH i18n system (the active locale); falls
+        // back to the browser language, then en-US.
+        const localePack = await (isZh()
           ? import('@univerjs/preset-sheets-core/locales/zh-CN').then(m => m.default).catch(() => null)
           : import('@univerjs/preset-sheets-core/locales/en-US').then(m => m.default).catch(() => null))
 
         const wb = XLSX.read(buf, { type: 'array' })
-        const locale = isZh ? LocaleType.ZH_CN : LocaleType.EN_US
+        const locale = isZh() ? LocaleType.ZH_CN : LocaleType.EN_US
         const workbookData = xlsxWorkbookToUniver(wb, '0.25.1', locale)
 
         if (cancelled) return

src/context-types.ts

@@ -265,6 +265,23 @@ export interface SidebarSessionsService {
   refreshSubagents?(parentSessionId: string): Promise<void>
 }
 
+/**
+ * The client locale service face (mirror of @deepseek-ai/dsh-client-locale's
+ * LocaleService — only the slices the sidebar touches). The sidebar follows
+ * the DSH i18n system: the active locale is the Host-backed preference
+ * (`locale.preference` in settings.yaml) rather than the raw browser
+ * language, and the sidebar's zh/en dictionaries register into the service's
+ * namespace registry under `betterSidebar`.
+ */
+export interface SidebarLocaleService {
+  /** Current immutable locale snapshot (uSES-safe; `active` is 'zh' | 'en' today). */
+  getSnapshot(): { active: string }
+  /** Subscribe to snapshot changes (locale switch or dictionary registration). */
+  subscribe(fn: () => void): () => void
+  /** Register one locale's dictionary for a namespace; returns the disposer. */
+  register(ns: string, locale: string, dict: Record<string, string>): () => void
+}
+
 /** The composer draft face the sidebar reaches through `ctx.conversation.input`. */
 export interface SidebarSessionInput {
   /** The live input store (draft read for append). */
@@ -372,6 +389,12 @@ declare module 'cordis' {
     settings: SidebarSettingsService
     invariants: SidebarInvariantsService
     tools: SidebarToolsService
+    /**
+     * The client locale service (`@deepseek-ai/dsh-client-locale`): the
+     * sidebar's copy follows its active locale and registers its
+     * dictionaries under the `betterSidebar` namespace. Client side only.
+     */
+    locale: SidebarLocaleService
     /**
      * The host background-task registry (`ctx.get('tasks')`; optional — the
      * sidebar routes degrade to a 503 when the deployment lacks it).

tests/locales.spec.ts

@@ -0,0 +1,109 @@
+/**
+ * Locale-following spec: the sidebar copy follows the DSH locale service
+ * (`ctx.locale`, provided by @deepseek-ai/dsh-client-locale) when attached
+ * through `attachLocale`, and falls back to the browser language otherwise.
+ * Covers attach/detach, live switching, dictionary parity, and placeholder
+ * interpolation.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { LOCALE_NS, attachLocale, en, isZh, relativeTime, t, zh } from '../src/client/locales.ts'
+
+/** Minimal structural fake of the DSH LocaleService face the sidebar uses. */
+class FakeLocale {
+  active: string = 'en'
+  getSnapshot(): { active: string } {
+    return { active: this.active }
+  }
+  subscribe(_fn: () => void): () => void {
+    return () => {}
+  }
+  register(_ns: string, _locale: string, _dict: Record<string, string>): () => void {
+    return () => {}
+  }
+  switchTo(id: string): void {
+    this.active = id
+  }
+}
+
+/** Point the browser-language fallback at a specific language (undefined = none). */
+function stubNavigatorLanguage(lang: string | undefined): void {
+  Object.defineProperty(globalThis, 'navigator', {
+    value: lang === undefined ? undefined : { language: lang },
+    configurable: true,
+  })
+}
+
+afterEach(() => {
+  attachLocale(undefined)
+  stubNavigatorLanguage(undefined)
+})
+
+describe('locales (DSH i18n following)', () => {
+  it('falls back to the browser language without an attached service', () => {
+    stubNavigatorLanguage('en-US')
+    expect(t('explorer')).toBe('Explorer')
+    expect(isZh()).toBe(false)
+
+    stubNavigatorLanguage('zh-CN')
+    expect(t('explorer')).toBe('资源管理器')
+    expect(isZh()).toBe(true)
+  })
+
+  it('defaults to English when no locale service and no browser language are available', () => {
+    expect(t('explorer')).toBe('Explorer')
+    expect(isZh()).toBe(false)
+  })
+
+  it('follows the attached locale service instead of the browser language', () => {
+    stubNavigatorLanguage('en-US')
+    const locale = new FakeLocale()
+    attachLocale(locale)
+
+    locale.switchTo('zh')
+    expect(t('git')).toBe('源代码管理')
+    expect(isZh()).toBe(true)
+
+    // Live switch: the service's active locale wins even though the
+    // browser still asks for en-US.
+    locale.switchTo('en')
+    expect(t('git')).toBe('Source Control')
+    expect(isZh()).toBe(false)
+  })
+
+  it('detaches back to the browser-language fallback', () => {
+    const locale = new FakeLocale()
+    locale.switchTo('zh')
+    attachLocale(locale)
+    expect(t('terminal')).toBe('终端')
+
+    stubNavigatorLanguage('en-US')
+    attachLocale(undefined)
+    expect(t('terminal')).toBe('Terminal')
+  })
+
+  it('interpolates {name} placeholders in the active locale', () => {
+    const locale = new FakeLocale()
+    attachLocale(locale)
+    locale.switchTo('zh')
+    expect(t('timeMinutesAgo', { n: 5 })).toBe('5 分钟前')
+    locale.switchTo('en')
+    expect(t('timeMinutesAgo', { n: 5 })).toBe('5 min ago')
+  })
+
+  it('drives the relative-time chain through the active locale', () => {
+    const locale = new FakeLocale()
+    attachLocale(locale)
+    locale.switchTo('zh')
+    expect(relativeTime(new Date().toISOString())).toBe('刚刚')
+    locale.switchTo('en')
+    expect(relativeTime(new Date().toISOString())).toBe('just now')
+  })
+
+  it('registers a namespace distinct from DSH ui-sidebar\'s own \'sidebar\'', () => {
+    expect(LOCALE_NS).toBe('betterSidebar')
+  })
+
+  it('keeps the zh and en dictionaries key-set-equal', () => {
+    expect(Object.keys(en).sort()).toEqual(Object.keys(zh).sort())
+  })
+})