dsh-panel-control 0.7.1 → 0.8.3

package/docs/bridged-settings-pages.md

@@ -0,0 +1,85 @@
+# 设置页补入口：怎么识别，怎么渲染
+
+## 问题
+
+宿主把「侧栏面板」和「设置页」做成两套注册：
+
+- 面板入口 = `sidebar.panellist` 里的一行图标 + 同 id 的 root 作用域 `main` keyed 条目；
+- 设置页 = `settings.section` 里的一个 id。
+
+多数插件两者都注册。少数只注册 `settings.section`，于是它的页面只能从设置弹窗里翻到——
+侧栏没有入口，也没法被单独选中。设置弹窗的打开状态是宿主私有的，没有公开 API 能直接定位到
+某个 section，所以「点一行就打开那个设置页」只能由本插件自己造一页。
+
+## 识别
+
+宿主的槽条目确实带有 `registrant`，但在当前客户端里它**不能用来区分插件**：client runner 把
+大量插件放在同一个 fiber 里 apply，实测 `account/general/models/plugins/agent-presets` 以及
+`plan-mode`、`bili`、`workspace-control-settings`、`composer-rewind-settings` 这些设置页的
+`registrant` 都是同一个 `tk`，侧栏里大多数行也是 `tk`；只有插件市场是它自己的 `dsh-market`。
+按 registrant 过滤会把所有第三方设置页都当成「已有入口」。
+
+因此改为按**侧栏归属**判断，一个设置页有入口当且仅当满足任一条：
+
+1. 它的 id 等于某个 `sidebar.panellist` 的 id；
+2. 去掉末尾 `-settings` 后的 id 等于某个面板 id（`panel-control-settings` ↔ `panel-control`）；
+3. 某个面板 id 以 `-<id>` 结尾（`market` ↔ `dsh-market`）；
+4. 它的 label 与某个面板 label 相同（`market` / `workspace-control-settings` 都命中）。
+
+内置设置页没有面板，因此单独列一组 id 排除：`account`、`general`、`models`、`agent-presets`、
+`plugins`（`plugins` 同时也有面板，列在这里只是双保险）。剩下的每个 section 补一行，id 为
+`dpc-bridge-<section id>`，order 85（在普通入口之后、本插件之前）。标题取该 section 的 label；
+与已有行撞名时追加 ` · <section id>`。
+
+这套判断不读第三方包内部文件，也不依赖插件白名单；代价是**启发式**：一个第三方设置页若恰好
+与某个面板同名/id 同源，会被当成已有入口；未来新增的内置设置页若不在上面的 id 列表里，会被
+多补一行（此时把它加进 `CORE_SECTION_IDS` 即可）。
+
+## 渲染
+
+桥接面板自己注册同 id 的 `main` keyed 条目，并在该条目上声明一个自有子槽（`dpc-bridge-slot-<section id>`）。
+之所以不直接用 `ctx.slots.renderSlot('settings.section', ...)`：ctx 级 `renderSlot` 只渲染 `root`，
+子槽只能通过「声明了它的那个条目的 props 面」渲染；`settings.section` 由设置壳声明，本插件无权调用。
+因此桥接条目把原 section 的组件以同一份 `inject/store/locale` 重新注册进自有子槽，再通过宿主注入的
+`props.renderSlot(slotName, { close: back }, {})` 渲染它。
+
+这样 section 的 `inject`、`store`、locale `t`、`useStore` 和 error boundary 仍由宿主照常提供；直接调用
+section 组件会缺这些。面板只负责外壳：顶部一条 40px 的栏（「返回对话」+ 来源 section id），
+下面一块随页面滚动的主体。`close` 与设置壳里一样只做「关掉这一页」，这里落回对话
+（`layout.selectPanel(null)`）。
+
+桥接面板不常驻：开关关闭、section 消失、插件卸载时，`dispose()` 成对撤掉 `main` 与
+`sidebar.panellist` 注册；若当时正停在这一页，先 `selectPanel(null)` 回到对话，避免选中一个
+已经不存在的 key。
+
+## 同步
+
+`settings.section`、`sidebar.panellist` 与 locale 任意一处变化都会触发一次同步，120ms 去抖。
+启动时还会按 `[350, 900, 2000, 4200, 8000, 15000]ms` 主动重扫：boot 清单的顺序不是应用顺序，
+排在后面的插件可能在第一次同步之后才注册设置页。`settings.section` 槽声明时会重新建立订阅，
+因为槽声明之前 `subscribe` 观察不到这个注册表。
+
+同步本身只做增删对账，不重建未变化的行；注册成对失败时回滚已注册的那一半。
+
+开关存在 `prefs.bridge`（默认 `true`），在「侧栏布局」卡片里；它和排序、隐藏、分组是正交的：
+补出来的行可以像普通行一样拖动、隐藏、分组，关掉开关才会整体消失。
+
+## 验证
+
+- `npm run check`：`layout-smoke` 断言桥接的常量、持久化字段与自有子槽渲染没有被改掉；
+  `bridge-smoke` 在假 `ctx` 上验证识别、成对注册、开关撤回与返回对话。
+- 刷新插件后看 `~/.dsh/panel-control/host.log`：`bridge-scan` 行记录每次扫描看到的 section 与
+  侧栏条目（`id:registrant`），`kind=bridge` 行记录最终补出的 id。目标 section 在 `sections`
+  里却没进 `ids`，说明它被归属规则当成了已有入口（或 id 不在内置列表里而被排除）；一直不在
+  `sections` 里，是注册时序问题。
+- `bridge-smoke` 里另有一条晚注册用例：先启动、后注册 section，订阅必须把新行补出来。
+- 界面：侧栏应多出对应行；点开后是完整设置页，顶部「返回对话」可退回；设置 → 面板管理里
+  「侧栏布局」应出现开关。
+
+## 边界
+
+- 第三方设置页在设置壳外渲染时，若它依赖弹窗的私有上下文（宽度、滚动容器、`close` 之外的 props），
+  可能和设置弹窗里不完全一致；本插件只保证宿主注入的公开部分齐全。
+- 补出来的行参与自动分类，会被分进 2–4 个组之一；想固定位置就手动拖动或分组。
+- 识别是启发式：设置页 id / label 与面板重合时视为已有入口；新增内置设置页需要加进
+  `CORE_SECTION_IDS`。同一个包注册多个设置页会补多行，这是有意的。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-panel-control",
-  "version": "0.7.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "Manage the global panel navigation at the top of the DSH sidebar: reorder, hide and group every entry, with the layout persisted per installation.",
   "keywords": [
@@ -50,7 +50,7 @@
     "url": "https://github.com/QIUZAIYOU/dsh-panel-control/issues"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node scripts/host-smoke.mjs && node scripts/layout-smoke.mjs",
+    "check": "node --check index.js && node --check client.js && node scripts/host-smoke.mjs && node scripts/layout-smoke.mjs && node scripts/bridge-smoke.mjs",
     "smoke": "node scripts/host-smoke.mjs",
     "doctor": "node scripts/profile-doctor.mjs",
     "enable": "node scripts/enable-local.mjs"

package/scripts/bridge-smoke.mjs

@@ -0,0 +1,324 @@
+// Scratch harness: does the bridge discover settings-only plugins, register the
+// panellist+main pair, avoid plugins that already have a row, and honour the switch?
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+const SRC = readFileSync(new URL('../client.js', import.meta.url), 'utf8');
+
+const stubReact = {
+  createElement: (type, props, ...children) => ({ type, props: { ...(props || {}), children } }),
+  useState: (value) => [value, () => {}],
+  useEffect: () => {},
+  useRef: (value) => ({ current: value }),
+  useMemo: (fn) => fn(),
+  useCallback: (fn) => fn,
+};
+
+const element = () => ({
+  style: {},
+  dataset: {},
+  classList: { add() {}, remove() {}, toggle() {} },
+  setAttribute() {},
+  removeAttribute() {},
+  appendChild() {},
+  remove() {},
+  addEventListener() {},
+  removeEventListener() {},
+  contains() {
+    return false;
+  },
+  querySelector() {
+    return null;
+  },
+  querySelectorAll() {
+    return [];
+  },
+  textContent: '',
+  children: [],
+  childNodes: [],
+});
+
+const document = {
+  readyState: 'loading',
+  head: element(),
+  body: element(),
+  documentElement: element(),
+  title: '',
+  visibilityState: 'visible',
+  createElement: () => element(),
+  createTextNode: () => ({ textContent: '' }),
+  createDocumentFragment: () => element(),
+  querySelector: () => null,
+  querySelectorAll: () => [],
+  getElementById: () => null,
+  addEventListener() {},
+  removeEventListener() {},
+};
+
+function makeWindow(localPrefs) {
+  const memory = new Map();
+  if (localPrefs !== undefined) memory.set('dsh.panel-control.v1', JSON.stringify(localPrefs));
+  const localStorage = {
+    getItem: (key) => (memory.has(key) ? memory.get(key) : null),
+    setItem: (key, value) => memory.set(key, String(value)),
+    removeItem: (key) => memory.delete(key),
+    key: () => null,
+    length: 0,
+  };
+  return {
+    document,
+    localStorage,
+    navigator: { language: 'zh-CN' },
+    location: { reload() {} },
+    CSS: { escape: (value) => String(value) },
+    addEventListener() {},
+    removeEventListener() {},
+    __DSH_BOOT__: {
+      rev: 'test-rev',
+      entries: [],
+      ids: [
+        'plugins',
+        'dsh-market',
+        'panel-control',
+        'dsh-flash-presets',
+        'billion-context',
+        'dshmarket',
+        '@deepseek-ai/dsh-client-ui-settings-general',
+      ],
+    },
+    __ModuleLoader__: { def: null, load(def) { this.def = def; } },
+  };
+}
+
+function section(options, registrant) {
+  return { options, component: () => null, registrant };
+}
+function panelEntry(options, registrant) {
+  return { options, component: () => null, registrant };
+}
+
+function install(ctx, slots) {
+  globalThis.window = ctx;
+  globalThis.document = document;
+  globalThis.localStorage = ctx.localStorage;
+  window.__ModuleLoader__.def = null;
+  vm.runInThisContext(SRC, { filename: 'client.js' });
+  return window.__ModuleLoader__.def.factory((name) => {
+    if (name === 'react') return stubReact;
+    throw new Error('unexpected require: ' + name);
+  });
+}
+
+const calls = { selectPanel: [], renders: [] };
+const layout = {
+  panelInfo: { getSnapshot: () => ({ activePanelId: null }) },
+  selectPanel(id) {
+    calls.selectPanel.push(id);
+  },
+};
+const locale = {
+  getLocale: () => ({ active: 'zh-CN' }),
+  register: () => {},
+  subscribe: () => () => {},
+};
+
+function makeCtx(seedSections = true) {
+  const registries = new Map();
+  const list = (name) => {
+    if (!registries.has(name)) registries.set(name, []);
+    return registries.get(name);
+  };
+  const subscribers = new Map();
+  const notify = (name) => {
+    for (const callback of subscribers.get(name) || []) Promise.resolve().then(callback);
+  };
+  const slotService = {
+    register(options, component) {
+      const record = { options, component, registrant: options.registrant || 'dsh-panel-control' };
+      list(options.name).push(record);
+      notify(options.name);
+      return () => {
+        const all = list(options.name);
+        const at = all.indexOf(record);
+        if (at >= 0) all.splice(at, 1);
+        notify(options.name);
+      };
+    },
+    entriesOfSlot(name) {
+      return list(name).slice();
+    },
+    inject(name, callback) {
+      return callback();
+    },
+    subscribe(name, callback) {
+      if (!subscribers.has(name)) subscribers.set(name, []);
+      subscribers.get(name).push(callback);
+      return () => {};
+    },
+    renderSlot(name, props, opts) {
+      calls.renders.push({ name, props, opts });
+      return stubReact.createElement('div', { 'data-slot': name, 'data-only': opts && opts.only });
+    },
+  };
+  list('sidebar.panellist').push(
+    panelEntry({ name: 'sidebar.panellist', id: 'plugins', order: 0, label: '插件' }, 'tk'),
+  );
+  list('sidebar.panellist').push(
+    panelEntry({ name: 'sidebar.panellist', id: 'dsh-market', order: 1, label: '插件市场' }, 'dsh-market'),
+  );
+  list('sidebar.panellist').push(
+    panelEntry({ name: 'sidebar.panellist', id: 'workspace-control', order: 20, label: '工作区管理' }, 'tk'),
+  );
+  list('settings.section').push(
+    section({ name: 'settings.section', id: 'general', order: 0, label: '通用' }, 'tk'),
+  );
+  list('settings.section').push(
+    section({ name: 'settings.section', id: 'market', order: 40, label: '插件市场' }, 'dsh-market'),
+  );
+  if (seedSections) {
+    list('settings.section').push(
+      section({ name: 'settings.section', id: 'plan-mode', order: 5, label: '计划模式' }, 'tk'),
+    );
+    list('settings.section').push(
+      section({ name: 'settings.section', id: 'bili', order: 100, label: () => '上下文' }, 'tk'),
+    );
+    list('settings.section').push(
+      section({ name: 'settings.section', id: 'workspace-control-settings', order: 30, label: '工作区管理' }, 'tk'),
+    );
+    list('settings.section').push(
+      section({ name: 'settings.section', id: 'composer-rewind-settings', order: 50, label: '输入历史' }, 'tk'),
+    );
+    for (const [id, label] of [
+      ['account', '账户'],
+      ['models', '模型'],
+      ['agent-presets', '智能体预设'],
+    ]) {
+      list('settings.section').push(section({ name: 'settings.section', id, order: 1, label }, 'tk'));
+    }
+  }
+  return {
+    registries,
+    subscribers,
+    ctx: {
+      fiber: { name: 'dsh-panel-control' },
+      get(name) {
+        if (name === 'layout') return layout;
+        if (name === 'locale') return locale;
+        return undefined;
+      },
+      effect(fn) {
+        return fn();
+      },
+      slots: slotService,
+    },
+  };
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function run(localPrefs) {
+  const app = makeCtx();
+  const mod = install(makeWindow(localPrefs), app.registries);
+  mod.apply(app.ctx);
+  await sleep(260);
+  const rows = app.registries.get('sidebar.panellist') || [];
+  const mains = app.registries.get('main') || [];
+  const labelOf = (options) => (typeof options.label === 'function' ? options.label() : options.label);
+  return {
+    ids: rows.map((row) => row.options.id),
+    labels: rows.map((row) => labelOf(row.options)),
+    mains: mains.map((row) => row.options.key),
+    mainRows: mains,
+    rows,
+    registries: app.registries,
+  };
+}
+
+const failures = [];
+const check = (ok, message) => {
+  if (!ok) failures.push(message);
+};
+
+// Boot order is not registration order: a plugin that applies after us adds its
+// settings section later. The subscription installed when the slot is declared
+// must pick that up without a reload.
+async function runLate() {
+  const app = makeCtx(false);
+  const mod = install(makeWindow(undefined), app.registries);
+  mod.apply(app.ctx);
+  await sleep(300);
+  const before = (app.registries.get('sidebar.panellist') || []).map((row) => row.options.id);
+  app.ctx.slots.register(
+    { name: 'settings.section', id: 'plan-mode', order: 5, label: '计划模式', registrant: 'tk' },
+    () => null,
+  );
+  app.ctx.slots.register(
+    { name: 'settings.section', id: 'bili', order: 100, label: () => '上下文', registrant: 'tk' },
+    () => null,
+  );
+  await sleep(420);
+  const after = (app.registries.get('sidebar.panellist') || []).map((row) => row.options.id);
+  return { before, after };
+}
+
+const late = await runLate();
+check(!late.before.some((id) => id.startsWith('dpc-bridge-')), 'bridged a section before it was registered');
+check(
+  late.after.includes('dpc-bridge-plan-mode') && late.after.includes('dpc-bridge-bili'),
+  'late-registered settings sections were not bridged',
+);
+
+const on = await run(undefined);
+check(on.ids.includes('dpc-bridge-plan-mode'), 'missing bridge row for dsh-flash-presets');
+check(on.ids.includes('dpc-bridge-bili'), 'missing bridge row for billion-context');
+check(on.ids.includes('dpc-bridge-composer-rewind-settings'), 'missing bridge row for dsh-composer-rewind');
+check(!on.ids.includes('dpc-bridge-market'), 'bridged dshmarket even though it has a panel');
+check(!on.ids.includes('dpc-bridge-general'), 'bridged a core settings section');
+check(!on.ids.includes('dpc-bridge-account'), 'bridged a core settings section');
+check(!on.ids.includes('dpc-bridge-models'), 'bridged a core settings section');
+check(!on.ids.includes('dpc-bridge-agent-presets'), 'bridged a core settings section');
+check(!on.ids.includes('dpc-bridge-workspace-control-settings'), 'bridged a plugin whose panel id is the section base');
+check(on.mains.includes('dpc-bridge-plan-mode') && on.mains.includes('dpc-bridge-bili'), 'a bridge row has no main entry');
+const planRow = on.rows.find((row) => row.options.id === 'dpc-bridge-plan-mode');
+check(planRow && planRow.options.order === 85, 'bridge rows lost their order');
+check(planRow && planRow.options.label() === '计划模式', 'bridge label is not the section label');
+
+const tree = on.rows.find((row) => row.options.id === 'dpc-bridge-bili').component({ size: 18, active: false });
+check(tree && tree.type === 'svg', 'bridge icon is not an svg');
+
+const off = await run({ version: 2, bridge: false, order: ['plugins', 'dsh-market', 'panel-control'] });
+check(!off.ids.some((id) => id.startsWith('dpc-bridge-')), 'the switch did not remove the bridge rows');
+
+// The settings shell owns `settings.section`, so the ctx-level renderSlot cannot
+// reach it. The bridge declares its own child slot, registers the section
+// component into it, and renders it through the props face the host binds.
+const biliMain = on.mainRows.find((row) => row.options.key === 'dpc-bridge-bili');
+check(Boolean(biliMain), 'no main key for the bridged row');
+const slotName = 'dpc-bridge-slot-bili';
+const declared = biliMain && biliMain.options.children;
+check(Boolean(declared && declared[slotName]), 'the bridge main entry declared no child slot');
+check(declared && declared[slotName] && declared[slotName].kind === 'single', 'the bridge child slot is not single');
+const face = (name, props, opts) => {
+  if (!declared || !declared[name]) throw new Error('slot ' + name + ' is not declared by this entry children');
+  calls.renders.push({ name, props, opts });
+  return stubReact.createElement('div', { 'data-slot': name });
+};
+const view = biliMain ? biliMain.component({ renderSlot: face }) : null;
+const slot = calls.renders.find((render) => render.name === slotName);
+check(Boolean(slot), 'the bridge page did not render its child slot');
+check(slot && typeof slot.props.close === 'function', 'the bridge page gave the section no close');
+check(Boolean(view) && view.type === 'div', 'the bridge page did not render its frame');
+const childEntries = on.registries.get(slotName) || [];
+check(childEntries.length === 1, 'the section component was not re-registered into the bridge slot');
+check(childEntries[0] && typeof childEntries[0].component === 'function', 'the bridge slot has no component');
+if (slot) slot.props.close();
+check(calls.selectPanel.includes(null), 'closing the bridge page did not select the Conversation');
+
+console.log(JSON.stringify({ on: on.ids, onLabels: on.labels, mains: on.mains, off: off.ids, renders: calls.renders.length }, null, 2));
+if (failures.length) {
+  console.error('bridge-smoke: ' + failures.length + ' problem(s)');
+  for (const failure of failures) console.error(' - ' + failure);
+  process.exit(1);
+}
+console.log('bridge-smoke: ok');
+process.exit(0);

package/scripts/layout-smoke.mjs

@@ -27,12 +27,28 @@ for (const marker of [
   'layoutGuard',
   'layoutMaxNone',
   'toggleCollapse',
+  'layoutBridge',
+  'dpc-bridgeBar',
+  'registrantOf',
 ]) {
   expect(client.includes(marker), 'client.js lost ' + marker);
 }
 
+// A bridged row is only as good as the two halves it registers: a keyed main
+// entry the layout can select, and the host-rendered settings section it shows.
+expect(client.includes('BRIDGE_ORDER = 85'), 'bridged rows lost their order slot');
+expect(client.includes('out.bridge = raw.bridge !== false'), 'the bridge switch is not persisted');
+expect(
+  client.includes('BRIDGE_SLOT_PREFIX') &&
+    client.includes('children: { [slotName]: { kind: \'single\', scope: \'root\' } }') &&
+    client.includes('renderSlot(slotName, { close: back }, {})'),
+  'the bridged page no longer renders through its own child slot',
+);
+expect(/\.dpc-bridgeBar\{[^}]*min-height:40px/.test(client), 'the bridge bar lost its 40px row height');
+
 expect(client.includes("const BUILD_STAMP = 'dsh-panel-control/" + pkg.version + "'"), 'BUILD_STAMP and package.json version disagree');
 expect(pkg.scripts && String(pkg.scripts.check).includes('layout-smoke'), 'npm run check no longer runs this gate');
+expect(pkg.scripts && String(pkg.scripts.check).includes('bridge-smoke'), 'npm run check no longer runs the bridge gate');
 expect(/\[data-dpc-list\]\{[^}]*overflow-y:auto/.test(client), 'the panel list is not scrollable');
 expect(/\[data-dpc-list\]\{[^}]*max-height:max\(120px,var\(--dpc-panellist-max,45vh\)\)/.test(client), 'the panel list lost its height cap');
 expect(/\[data-dpc-region\]\{[^}]*min-height/.test(client), 'the region below the list lost its floor');