@sidleo3/dsh-chat 0.0.4

package/client/scoped-mode-editor.js

@@ -0,0 +1,111 @@
+/**
+ * 通用的"两作用域 × 多选项"设置块。
+ *
+ * 飞书的任务过程展示（私聊/群聊各自 off / 实时过程卡 / 逐步直播）就是这一形态；
+ * 其他渠道以后要加同类设置直接复用，不必各写一份。
+ *
+ * @module dsh-chat/client/scoped-mode-editor
+ */
+
+import * as React from 'react';
+
+const h = React.createElement;
+
+/**
+ * 两作用域模式选择器。
+ *
+ * **选完即存**：没有「保存」按钮——卡片里只有两个下拉，按钮挂在右上角还常驻灰色，
+ * 第一眼既不知道它保存什么，也不知道改哪里才能点亮它。失败则回滚到外部真值并说明原因。
+ *
+ * @param props - {
+ *   title, description, scopes: [{ key, label }], options: [{ value, label, help }],
+ *   value: { [scopeKey]: optionValue }, disabled, saving, error, translate, onSave,
+ * }。
+ * @returns React 元素。
+ */
+export function ScopedModeEditor({
+  title,
+  description,
+  scopes,
+  options,
+  value = {},
+  disabled = false,
+  saving = false,
+  error = null,
+  translate,
+  onSave,
+}) {
+  const t = typeof translate === 'function' ? translate : (key) => key;
+  const [draft, setDraft] = React.useState(() => ({ ...value }));
+  const [pending, setPending] = React.useState(null);
+  const [failed, setFailed] = React.useState(null);
+  /**
+   * 帮助文案只显示"正在操作的那个作用域"的：两个作用域共用同一组选项，
+   * 各贴一遍就是同一句话重复两次（截图里就是这么重复的）。
+   */
+  const [helpFor, setHelpFor] = React.useState(scopes[0]?.key ?? null);
+
+  const same = (a, b) => scopes.every((scope) => (a[scope.key] ?? null) === (b[scope.key] ?? null));
+  const locked = disabled || saving || pending !== null;
+
+  // 外部值变化（例如重新读取）时同步草稿；已经在草稿上的值不重建对象，避免多余重渲染。
+  React.useEffect(() => {
+    if (pending !== null) return;
+    setDraft((current) => (same(current, value) ? current : { ...value }));
+    // same/scopes 每次渲染都是新引用，这里只以 value/pending 为触发条件。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, pending]);
+
+  const choose = async (scopeKey, nextValue) => {
+    if (locked) return;
+    const next = { ...draft, [scopeKey]: nextValue };
+    setDraft(next);          // 乐观：下拉立刻反映选择
+    setFailed(null);
+    setPending(scopeKey);
+    try {
+      await onSave({ ...next });
+    } catch (cause) {
+      setDraft({ ...value }); // 失败回滚到外部真值，并把原因留在卡片上
+      setFailed(cause?.message ?? String(cause));
+    } finally {
+      setPending(null);
+    }
+  };
+
+  const savingHint = pending !== null
+    ? h('span', { className: 'dchat-status' }, t('保存中…'))
+    : null;
+  const help = options.find((option) => option.value === (draft[helpFor] ?? options[0]?.value))?.help;
+  // 选项文案由调用方给**键**，这里翻译：渠道不必各自准备两份文案。
+
+  return h('section', { className: 'dchat-card' },
+    h('div', { className: 'dchat-cardHeader' },
+      h('div', { className: 'dchat-cardHeading' },
+        h('h3', { className: 'dchat-cardTitle' }, title),
+        description ? h('p', { className: 'dchat-cardDescription' }, description) : null),
+      savingHint ? h('div', { className: 'dchat-actions' }, savingHint) : null),
+    h('div', { className: 'dchat-scopeGrid' }, scopes.map((scope) => {
+      const selected = draft[scope.key] ?? options[0]?.value;
+      const selectId = `dchat-mode-${scope.key}`;
+      return h('div', { key: scope.key, className: 'dchat-scopeRow' },
+        h('label', { className: 'dchat-scopeLabel', htmlFor: selectId }, scope.label),
+        h('select', {
+          id: selectId,
+          className: 'dchat-select',
+          value: selected,
+          disabled: locked,
+          'aria-label': `${title} · ${scope.label}`,
+          onFocus: () => setHelpFor(scope.key),
+          onChange: (event) => {
+            setHelpFor(scope.key);
+            void choose(scope.key, event.target.value);
+          },
+        }, options.map((option) => h('option', {
+          key: option.value, value: option.value,
+        }, t(option.label))),
+        scope.key === helpFor && help
+          ? h('p', { className: 'dchat-cardDescription' }, t(help))
+          : null));
+    })),
+    failed || error ? h('p', { className: 'dchat-error', role: 'alert' }, failed ?? error) : null);
+}

package/client/section.js

@@ -0,0 +1,250 @@
+/**
+ * 设置页「Chat机器人」入口：一个 hub 入口 + 由已安装渠道插件动态生成的左栏。
+ *
+ * 渠道页由各渠道包注册到 hub 声明的子槽 `chat.channel.page`（keyed，key = 渠道 id）。
+ *
+ * @module dsh-chat/client/section
+ */
+
+import * as React from 'react';
+
+import { channelIconUri } from '../shared/channel-rail.mjs';
+import { CHANNEL_PAGE_SLOT } from '../shared/contract.mjs';
+import { BotList } from './bot-list.js';
+import { DiagnosticsPanel } from './diagnostics.js';
+import { CHANNEL_ORDER_KEY, orderedItems, useListOrder } from './list-order.js';
+import { VersionPanel } from './version-panel.js';
+
+const h = React.createElement;
+
+/** 未安装任何渠道插件时给出的安装提示。 */
+const KNOWN_CHANNEL_PACKAGES = Object.freeze([
+  'dsh-chat-feishu',
+  'dsh-chat-weixin',
+]);
+
+function ChannelMark({ entry }) {
+  // 渠道图标（和侧边栏会话行徽标同一份）；没有图标才退回首字母。
+  const iconUri = channelIconUri(entry.icon);
+  if (iconUri) {
+    return h('span', {
+      // 有真图标就不套那个"字母块"的边框与底色，让它看起来就是应用图标。
+      className: 'dchat-channelMark dchat-channelMarkIcon',
+      'aria-hidden': 'true',
+    }, h('img', { src: iconUri, alt: '', width: 20, height: 20 }));
+  }
+  if (typeof entry.logo === 'function') {
+    return h('span', { className: 'dchat-channelMark', 'aria-hidden': 'true' }, h(entry.logo));
+  }
+  const initial = entry.id.slice(0, 1).toUpperCase();
+  return h('span', { className: 'dchat-channelMark', 'aria-hidden': 'true' }, initial);
+}
+
+/**
+ * 设置页 section 组件。props 由 slot 框架注入：`t` / `renderSlot` 与注册时的 `inject`。
+ *
+ * @param props - { channels, chatUi, translate, t, renderSlot }。
+ * @returns React 元素。
+ */
+export function ChatSettingsSection(props) {
+  const { channels, chatUi, translate, t: frameworkT, renderSlot, connection } = props;
+  /** 版本与更新默认收起：右上角入口按需展开（只在展开时读一次数据）。 */
+  const [showVersions, setShowVersions] = React.useState(false);
+  /** 诊断同理：不看时不请求（读日志要碰文件系统，没必要常驻）。 */
+  const [showDiagnostics, setShowDiagnostics] = React.useState(false);
+  /**
+   * 右栏两级视图：`{ kind: 'bots' }` 机器人列表 → `{ kind: 'channel', botId }` 机器人设置页。
+   * 和 dsh-im 同构：渠道 → 机器人 → 设置。
+   */
+  const [view, setView] = React.useState({ kind: 'bots', botId: null });
+  const t = typeof translate === 'function' ? translate
+    : (typeof frameworkT === 'function' ? frameworkT : (key) => key);
+
+  const entries = React.useSyncExternalStore(
+    (onChange) => channels.subscribe(onChange),
+    () => channels.getSnapshot(),
+    () => channels.getSnapshot(),
+  );
+  /**
+   * 左栏渠道顺序：用户拖动过就按用户顺序排，没排过的（新装的渠道）排在后面。
+   *
+   * 纯显示偏好（存浏览器），所以拖动只影响这台浏览器看到的顺序——渠道注册时的 `order`
+   * 仍然是所有机器的默认顺序。
+   */
+  const channelOrder = useListOrder(CHANNEL_ORDER_KEY, (entry) => entry?.id);
+  const orderedEntries = React.useMemo(
+    () => orderedItems(entries, channelOrder.order, (entry) => entry?.id),
+    [entries, channelOrder.order],
+  );
+  /**
+   * 正在拖动的渠道：**用 ref 记住"拖的是谁"**，state 只负责高亮。
+   *
+   * 一开始只用 state，结果同一个任务里连着派发 dragstart/drop 时（React 把几次 setState
+   * 批到一起，drop 的闭包里读到的还是 null）顺序不会变——真实浏览器里两次事件分属不同任务，
+   * 所以只在自动化里暴露。用 ref 更稳：互不依赖渲染时机。
+   */
+  const dragChannelRef = React.useRef(null);
+  const [dragChannel, setDragChannel] = React.useState(null);
+  const [dropChannel, setDropChannel] = React.useState(null);
+
+  const [selected, setSelected] = React.useState(null);
+  /**
+   * 当前选中的渠道：用户点过就用他点的那个，否则用**排在最前面的那个**。
+   *
+   * 这里必须用 `orderedEntries`：用注册顺序的 `entries[0]` 时，用户把顺序调成
+   * 「飞书在前、微信在后」，一进设置页却仍然默认打开微信（真机反馈）——
+   * 默认项当然应该跟他自己排的第一项一致。
+   */
+  const activeId = entries.some((entry) => entry.id === selected)
+    ? selected
+    : (orderedEntries[0]?.id ?? null);
+
+  // 切换渠道时回到"机器人列表"，否则会带着上一个渠道的 botId 进错页。
+  const activeEntry = entries.find((entry) => entry.id === activeId) ?? null;
+  const openSettings = (botId) => setView({ kind: 'channel', botId });
+  const backToBots = () => setView({ kind: 'bots', botId: null });
+
+  const EmptyState = chatUi?.components?.EmptyState;
+
+  /** 一级视图：机器人列表。 */
+  function botListView() {
+    if (!activeEntry) return null;
+    return h(BotList, {
+      key: activeEntry.id,
+      channelId: activeEntry.id,
+      label: activeEntry.label,
+      // 渠道能力说明（如「仅私聊」）放右栏标题下：左栏只留"图标 + 渠道名"，形态才整齐。
+      note: activeEntry.capabilities?.note ?? null,
+      // 渠道级设置入口：`setup.label` 有才显示（飞书没有渠道级表单，微信是「扫码接入」）。
+      setup: activeEntry.capabilities?.setup ?? null,
+      connection,
+      chatUi,
+      translate: t,
+      onOpenSettings: openSettings,
+    });
+  }
+
+  /** 二级视图：机器人（或整个渠道）的设置页（返回条由外层给）。 */
+  function channelView() {
+    return h(React.Fragment, null,
+      typeof renderSlot === 'function'
+        ? renderSlot(
+          CHANNEL_PAGE_SLOT,
+          { channelId: activeId, botId: view.botId },
+          { entryKey: activeId },
+        )
+        : h('p', { className: 'dchat-cardDescription' }, t('当前页面不支持渠道子槽。')));
+  }
+
+  /** 二级视图的返回条。 */
+  function backBar() {
+    return h('div', { className: 'dchat-panelBar' },
+      h('button', {
+        type: 'button', className: 'dchat-button', onClick: backToBots,
+      }, t('← 机器人列表')));
+  }
+
+  let body = null;
+  if (entries.length === 0) {
+    body = EmptyState
+      ? h(EmptyState, {
+        title: t('未安装任何聊天软件插件'),
+        description: t('安装渠道插件后，这里会出现对应的聊天软件。'),
+      }, h('ul', { className: 'dchat-list' },
+        h('li', { className: 'dchat-listItem' }, t('已知渠道插件')),
+        ...KNOWN_CHANNEL_PACKAGES.map((name) => h('li', {
+          key: name, className: 'dchat-listItem',
+        }, h('code', { className: 'dchat-code' }, `dsh plugin --profile web add ${name}`)))))
+      : null;
+  } else if (view.kind !== 'bots') {
+    // 进了机器人设置：不再保留左栏渠道列表——这时它没用，还占掉一半宽度。
+    body = h('div', { className: 'dchat-solo' }, backBar(), channelView());
+  } else {
+    body = h('div', { className: 'dchat-layout' },
+      h('nav', { className: 'dchat-rail', role: 'tablist', 'aria-label': t('渠道导航') },
+        orderedEntries.map((entry) => h('button', {
+          key: entry.id,
+          type: 'button',
+          role: 'tab',
+          id: `dchat-tab-${entry.id}`,
+          className: `dchat-channel${dropChannel === entry.id && dragChannel !== entry.id ? ' dchat-dropTarget' : ''}`,
+          'aria-selected': entry.id === activeId,
+          'aria-controls': `dchat-panel-${entry.id}`,
+          onClick: () => {
+            setSelected(entry.id);
+            backToBots();
+          },
+          // 拖动排序：把手是那个 grip（button 自己 draggable 在部分浏览器上不灵，
+          // 而且整行可拖会与"点一下切换渠道"抢手势）。
+          onDragOver: (event) => {
+            const from = dragChannelRef.current;
+            if (!from || from === entry.id) return;
+            event.preventDefault();
+            setDropChannel(entry.id);
+          },
+          onDrop: (event) => {
+            event.preventDefault();
+            const from = dragChannelRef.current;
+            if (from && from !== entry.id) channelOrder.move(orderedEntries, from, entry.id);
+            dragChannelRef.current = null;
+            setDropChannel(null);
+            setDragChannel(null);
+          },
+        },
+        h('span', {
+          className: 'dchat-grip',
+          draggable: true,
+          title: t('拖动可调整顺序'),
+          'aria-hidden': 'true',
+          onDragStart: (event) => {
+            dragChannelRef.current = entry.id;
+            setDragChannel(entry.id);
+            // Firefox 不设 dataTransfer 就不会开始拖。
+            event.dataTransfer?.setData('text/plain', entry.id);
+            if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move';
+          },
+          onDragEnd: () => {
+            dragChannelRef.current = null;
+            setDragChannel(null);
+            setDropChannel(null);
+          },
+        }, '⋮⋮'),
+        h(ChannelMark, { entry }),
+        h('span', { className: 'dchat-channelLabel' },
+          h('strong', null, entry.label()))))),
+      h('main', {
+        className: 'dchat-panel',
+        role: 'tabpanel',
+        id: `dchat-panel-${activeId}`,
+        'aria-labelledby': `dchat-tab-${activeId}`,
+      }, botListView()));
+  }
+
+  return h('section', { className: 'dchat-page', 'aria-label': t('Chat机器人设置') },
+    h('header', { className: 'dchat-header' },
+      h('div', { className: 'dchat-brand' },
+        h('strong', { className: 'dchat-brandName' }, 'DSH-Chat'),
+        h('span', { className: 'dchat-brandHint' }, t('Chat机器人'))),
+      // 右上角入口：版本与更新 / 诊断（展开后是同一块面板，收起时不请求数据）。
+      // 用文字链接形态，避免和 DSH 自己的实心按钮（打开配置文件）平级抢注意力。
+      h('div', { className: 'dchat-headerActions' },
+        h('button', {
+          type: 'button',
+          className: 'dchat-button dchat-buttonLink',
+          'aria-expanded': showDiagnostics,
+          onClick: () => setShowDiagnostics((open) => !open),
+        }, showDiagnostics ? t('收起诊断') : t('诊断')),
+        h('button', {
+          type: 'button',
+          className: 'dchat-button dchat-buttonLink',
+          'aria-expanded': showVersions,
+          onClick: () => setShowVersions((open) => !open),
+        }, showVersions ? t('收起版本与更新') : t('版本与更新')))),
+    showDiagnostics
+      ? h(DiagnosticsPanel, { connection, chatUi, translate: t })
+      : null,
+    showVersions
+      ? h(VersionPanel, { connection, chatUi, translate: t })
+      : null,
+    body);
+}

package/client/session-badges.js

@@ -0,0 +1,263 @@
+/**
+ * 侧边栏会话行的**渠道徽标**：把「飞书 · 标题」里的渠道名前缀换成一枚小图标。
+ *
+ * 为什么要这样：DSH 的会话列表没有可注册的插槽（`sidebar.workspaces` 是整块替换，
+ * 换掉就把搜索/分组/对话框全盖了），所以只能像上游 dsh-im 那样做**纯装饰性**的
+ * DOM 增强——保留标题里的文字前缀（它既是匹配依据，也是降级形态），只给标题元素
+ * 加两个自有的 data 属性，再用一张样式表把前缀隐藏、画上徽标。
+ *
+ * 三条纪律：
+ * 1. **只加属性，不动 React 的文本/子节点/类名**；卸载时逐项还原；
+ * 2. **认结构不认类名**：在行内找"文本以「<渠道名> · 」开头的叶子元素"，
+ *    不依赖产品的 CSS 类名，产品改类名也不会失效；
+ * 3. **图片没加载成功就不替换**（CSP 或字体缺失时保持文字前缀），绝不出现空白行。
+ *
+ * @module dsh-chat/client/session-badges
+ */
+
+import { channelIconUri } from '../shared/channel-rail.mjs';
+
+const STYLE_ID = 'dsh-chat-session-badges';
+const CHANNEL_ATTR = 'data-dsh-chat-channel';
+const TITLE_ATTR = 'data-dsh-chat-title';
+const ROW_SELECTOR = '[role="treeitem"][aria-selected]';
+
+/** 一枚圆角徽标的 data URI（品牌色底 + 白色字）。 */
+export function badgeUri({ text, color }, size = 16) {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" `
+    + `viewBox="0 0 ${size} ${size}"><rect x="0.5" y="0.5" width="${size - 1}" `
+    + `height="${size - 1}" rx="4" fill="${color}"/>`
+    + `<text x="${size / 2}" y="${size / 2 + 3.4}" text-anchor="middle" `
+    + `font-family="-apple-system, BlinkMacSystemFont, 'PingFang SC', sans-serif" `
+    + `font-size="9.5" font-weight="600" fill="#ffffff">${text}</text></svg>`;
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+
+function stylesheet(uris) {
+  const mapping = Object.entries(uris)
+    .map(([channel, uri]) => `[${CHANNEL_ATTR}="${channel}"] { --dchat-session-badge: url("${uri}"); }`)
+    .join('\n');
+  return `
+[${CHANNEL_ATTR}][${TITLE_ATTR}] {
+  position: relative;
+  -webkit-text-fill-color: transparent;
+  text-overflow: clip !important;
+  overflow: hidden;
+}
+[${CHANNEL_ATTR}][${TITLE_ATTR}]::before {
+  content: "";
+  position: absolute;
+  inset-inline-start: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 16px;
+  height: 16px;
+  background: var(--dchat-session-badge) center / contain no-repeat;
+  pointer-events: none;
+}
+[${CHANNEL_ATTR}][${TITLE_ATTR}]::after {
+  content: attr(${TITLE_ATTR}) / "";
+  position: absolute;
+  inset: 0;
+  inset-inline-start: 22px;
+  -webkit-text-fill-color: currentColor;
+  text-indent: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  pointer-events: none;
+}
+${mapping}
+`;
+}
+
+/**
+ * 在一个会话行里找"被打了渠道前缀的标题元素"。
+ *
+ * 只看**叶子元素**、只按文本前缀匹配——不依赖产品的 CSS 类名，产品改样式也不会失效；
+ * 同一行里多个匹配时取最靠后的那个（即最深的标题，不是外层容器）。
+ *
+ * @param row - 会话行元素（任何提供 `querySelectorAll` 的对象）。
+ * @param known - `[[渠道 id, 渠道显示名]]`，只包含徽标就绪的渠道。
+ * @returns `{ element, channel, text }` 或 null；`text` 是去掉前缀后的标题。
+ */
+export function findChannelTitle(row, known) {
+  if (!row || typeof row.querySelectorAll !== 'function' || known.length === 0) return null;
+  let found = null;
+  for (const element of row.querySelectorAll('*')) {
+    if (element.children?.length > 0) continue;
+    const text = element.textContent;
+    if (!text) continue;
+    for (const [channel, label] of known) {
+      if (text.startsWith(`${label} · `)) {
+        found = { element, channel, text: text.slice(label.length + 3).trim() };
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * 安装会话行徽标。
+ *
+ * @param options - { channels, doc, win }。
+ *   `channels` 是渠道 rail（提供 `subscribe`/`getSnapshot`）。
+ * @returns 卸载函数：断开观察、移除样式、还原所有属性。
+ */
+export function installSessionBadges({
+  channels, doc = globalThis.document, win = globalThis.window,
+} = {}) {
+  if (!doc?.body || typeof win?.MutationObserver !== 'function') return () => {};
+  /** 渠道 id → { label, uri }（只放已声明 `sessionBadge` 的渠道）。 */
+  const badges = new Map();
+  /** 图片加载成功的渠道（没加载成功就保留文字前缀）。 */
+  const ready = new Set();
+  /** 被我们改过的元素 → 原始属性值（卸载时还原）。 */
+  const owned = new Map();
+  const queued = new Set();
+  const images = [];
+  let closed = false;
+  let scheduled = false;
+
+  const style = doc.createElement('style');
+  style.id = STYLE_ID;
+  doc.head?.appendChild(style);
+
+  function labels() {
+    return [...badges.values()].filter((entry) => ready.has(entry.channel))
+      .map((entry) => [entry.channel, entry.label]);
+  }
+
+  /** 行内最深的一个"文本以「渠道名 · 」开头"的叶子元素。 */
+  function titleOf(row) {
+    return findChannelTitle(row, labels());
+  }
+
+  function restore(element) {
+    const previous = owned.get(element);
+    if (!previous) return;
+    owned.delete(element);
+    for (const [attribute, value] of previous) {
+      if (value === null) element.removeAttribute(attribute);
+      else element.setAttribute(attribute, value);
+    }
+  }
+
+  function update(row) {
+    const found = row.isConnected ? titleOf(row) : null;
+    for (const marked of row.querySelectorAll(`[${CHANNEL_ATTR}]`)) {
+      if (marked !== found?.element) restore(marked);
+    }
+    if (!found) return;
+    if (!owned.has(found.element)) {
+      owned.set(found.element, [CHANNEL_ATTR, TITLE_ATTR]
+        .map((attribute) => [attribute, found.element.getAttribute(attribute)]));
+    }
+    // React 仍然持有它原来的文本节点与监听器；我们只驱动自己那两个属性的视觉替换。
+    found.element.setAttribute(CHANNEL_ATTR, found.channel);
+    found.element.setAttribute(TITLE_ATTR, found.text);
+  }
+
+  function schedule() {
+    if (closed || scheduled || queued.size === 0) return;
+    scheduled = true;
+    win.queueMicrotask(() => {
+      scheduled = false;
+      if (closed) return;
+      const rows = [...queued];
+      queued.clear();
+      for (const row of rows) {
+        try {
+          update(row);
+        } catch {
+          for (const marked of row.querySelectorAll(`[${CHANNEL_ATTR}]`)) restore(marked);
+        }
+      }
+    });
+  }
+
+  function collect(node, descendants = false) {
+    const element = node?.nodeType === 1 ? node : node?.parentElement;
+    if (!element) return;
+    const row = element.closest(ROW_SELECTOR);
+    if (row) queued.add(row);
+    if (descendants) for (const child of element.querySelectorAll(ROW_SELECTOR)) queued.add(child);
+    if (owned.has(element)) {
+      const owner = element.closest(ROW_SELECTOR);
+      if (owner) queued.add(owner);
+      else restore(element);
+    }
+    schedule();
+  }
+
+  function applyBadges() {
+    if (closed) return;
+    badges.clear();
+    for (const entry of channels?.getSnapshot?.() ?? []) {
+      const badge = entry.sessionBadge;
+      if (!badge || typeof badge.text !== 'string' || !badge.text) continue;
+      // rail 里的 label 是**函数**（支持动态改名），必须调用后再用。
+      const label = typeof entry.label === 'function' ? entry.label() : entry.label;
+      badges.set(entry.id, {
+        channel: entry.id,
+        label: String(label ?? entry.id),
+        // 优先用渠道自己的图标（和设置页左栏同一份）；没给图标才退回字徽标。
+        uri: channelIconUri(entry.icon)
+          ?? badgeUri({ text: badge.text, color: badge.color ?? '#3370ff' }),
+      });
+    }
+    style.textContent = stylesheet(Object.fromEntries(
+      [...badges].map(([id, badge]) => [id, badge.uri]),
+    ));
+    // 图片没加载成功就不替换：宁可留着「飞书 · 」文字，也不要空一块。
+    for (const [id, badge] of badges) {
+      if (ready.has(id)) continue;
+      const image = new win.Image();
+      images.push(image);
+      image.onload = () => {
+        ready.add(id);
+        for (const row of doc.querySelectorAll(ROW_SELECTOR)) queued.add(row);
+        schedule();
+      };
+      image.src = badge.uri;
+    }
+    for (const row of doc.querySelectorAll(ROW_SELECTOR)) queued.add(row);
+    schedule();
+  }
+
+  const observer = new win.MutationObserver((records) => {
+    if (closed) return;
+    for (const record of records) {
+      collect(record.target, record.type === 'attributes');
+      if (record.type !== 'childList') continue;
+      for (const node of record.addedNodes) collect(node, true);
+      for (const node of record.removedNodes) {
+        if (node.nodeType !== 1 || node.isConnected) continue;
+        if (owned.has(node)) restore(node);
+        for (const marked of node.querySelectorAll(`[${CHANNEL_ATTR}]`)) restore(marked);
+      }
+    }
+  });
+  observer.observe(doc.body, {
+    subtree: true,
+    childList: true,
+    characterData: true,
+    attributes: true,
+    attributeFilter: ['class', 'role', 'aria-selected'],
+  });
+
+  const unsubscribe = channels?.subscribe?.(applyBadges);
+  applyBadges();
+
+  return () => {
+    closed = true;
+    observer.disconnect();
+    unsubscribe?.();
+    for (const image of images) {
+      image.onload = null;
+      image.src = '';
+    }
+    for (const element of [...owned.keys()]) restore(element);
+    style.remove();
+  };
+}