feat: 公共 API 基座化（v0.12.0，纯增量）— 类型/能力/设置 seam 全面补齐
- 类型生态：service 模块 re-export SidebarTab/SidebarState/SidebarStore/ SidebarSnapshot/SidebarDiffRef/TabType/SessionScope/SidebarPrefs 等公共 状态词汇（此前 TS2459 无法命名）；context-types 去 Node 依赖（结构镜像 SidebarHttpRequest/Response/UpgradeSocket/Head），client 可达声明图零 node:* 引用，外部消费者无 @types/node + skipLibCheck:false 可编译 （scripts/check-consumer-types.sh 守护） - 服务能力：version/features 版本与能力探测（单调只增）、getSnapshot/ subscribeState 状态订阅、updateTab（title/path/meta）、activateTab、 openFile（路径派生 id 与内置拦截一致）、openTab(seed, scope?) 定向到 指定 session（store.reduceFor 不扰动 UI） - TabDescriptor：badge 角标（99+ 封顶，抛错吞掉）、onOpen/onActivate/ onClose 生命周期回调（service 路径派发，dedupe 聚焦触发 onActivate 而非 onOpen，抛错不打断流程）；SidebarTab.meta JSON 可序列化跨刷新 持久化（sanitize 宽松保留） - 设置 seam 开放：PrefsSchema 增 pluginSettings 开放嵌套 map（z.dict）， settings.pluginToggles（插件自有行，同 switch/text/number 控件）与 settings.render（自定义面板，含 store/service/prefs/updatePluginSetting/ close props）；viewer 卡片 v0.12.0 起也有齿轮设置弹窗 - FileViewerDescriptor.load 增第三参 AbortSignal（EditorHost 生命周期中止） - UI 接线：tab 激活/关闭改走 service（跨树激活修复 + 回调触发）、+ 菜单 传 scope、TabBar badge pill 渲染；active-session scope 走原 reduce 路径 保证 notify - 测试 +23：生命周期/定向打开/updateTab/activateTab/openFile/meta 持久化/ reduceFor/能力常量（与 package.json 锁步）、consumer-types.ts 编译门、 api-surface.spec.ts（client 图零 node 依赖守护）；既有 430 测试全绿 - 文档：AGENTS.md 修 available 三参示例并补全部新 API；external-plugin- guide.md 刷新至 v0.12.0（7 tab + 9 viewer、设置 seam 开放、类型导入 路径建议）；README×2 服务化小节同步 未发版 npm（用户决定）；分支 feat/plugin-api-v012。
This commit is contained in:
Menghuan1918
+175
-24
@@ -2,8 +2,8 @@
|
||||
|
||||
> 面向 **消费插件开发者**：如何让你的插件向 better-sidebar 注册新的侧边栏页面（tab）和文件类型预览器。
|
||||
>
|
||||
> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置部分需要 **v0.4.1+**。当前版本 v0.4.3。
|
||||
> 权威代码：`src/client/service.ts`（服务实现）、`src/client/builtins/`（内置 6 tab + 8 viewer 参考实现）、`lib/types/client/service.d.ts`（类型声明）。
|
||||
> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置 **v0.4.1+**；text/number 设置行 **v0.11.0+**；本文档其余新 API（badge/生命周期/定向打开/插件设置/版本探测等）**v0.12.0+**。当前版本 v0.12.0。
|
||||
> 权威代码：`src/client/service.ts`（服务实现）、`src/client/builtins/`（内置 7 tab + 9 viewer 参考实现）、`lib/types/client/service.d.ts`（类型声明）。
|
||||
|
||||
---
|
||||
|
||||
@@ -14,7 +14,7 @@ better-sidebar 从 v0.4.0 起把自己改造成一个**注册表服务**：
|
||||
- **新页面（tab）**：注册一种新的侧边栏 tab 类型，出现在侧边栏 `+` 菜单里，用户点击后在自己的分栏里打开你的 React 页面；
|
||||
- **文件预览器（file viewer）**：注册一种文件类型预览器，让用户在侧边栏打开文件时走你的渲染组件（覆盖或补充内置的 image/pdf/code 等）。
|
||||
|
||||
内置的 6 个 tab（explorer / git / subagent / terminal / editor / diff）和 8 个 viewer（image / pdf / docx / xlsx / pptx / markdown / code / binary-download）**自己也是通过同一套 API 注册的**（吃自己的狗粮），所以外部插件的能力与内置功能完全对等。
|
||||
内置的 7 个 tab（explorer / git / subagent / terminal / browser / editor / diff）和 9 个 viewer（image / pdf / docx / xlsx / pptx / markdown / html / code / binary-download）**自己也是通过同一套 API 注册的**（吃自己的狗粮），所以外部插件的能力与内置功能完全对等。
|
||||
|
||||
关键机制一句话：better-sidebar 的 client half 在 `apply()` 开头执行 `ctx.provide('betterSidebar', service)`（`src/client/index.tsx`），消费插件在 `inject` 里声明 `'betterSidebar'`，Cordis 保证服务就绪后才激活你的插件，然后你调用 `ctx.betterSidebar.registerTab(...)` / `registerFileViewer(...)` 完成注册，返回的 disposer 由 Cordis fiber 在卸载（HMR / 禁用）时自动调用。
|
||||
|
||||
@@ -69,6 +69,17 @@ import type {
|
||||
import type { TabDescriptor } from 'dsh-better-sidebar/client/service' // 别名 ./client/api
|
||||
```
|
||||
|
||||
v0.12.0 起，服务模块还 re-export 了完整的状态词汇表，消费者可以直接命名（不再只能靠推断）：
|
||||
|
||||
```ts
|
||||
import type {
|
||||
SidebarTab, SidebarState, SidebarStore, SidebarSnapshot, SidebarDiffRef, TabType,
|
||||
SessionScope, SidebarPrefs, OpenTabSeed, SidebarSettingsRenderProps,
|
||||
} from 'dsh-better-sidebar/client/service'
|
||||
```
|
||||
|
||||
> 💡 **类型合并触发路径**：`import type {} from 'dsh-better-sidebar/client/service'` 同样会加载 `Context` 的 augmentation（`declare module 'cordis'` 在 context-types.d.ts 中）——**纯浏览器侧插件建议走 `client/service` 路径**，避免拉进宿主半的 Node 类型图（主入口 `dsh-better-sidebar` 的声明面含宿主代码；宿主消费者本就处于 Node 环境则无所谓）。client 可达声明图（`client/*` + context-types + html-route + prefs-shared）自 v0.12.0 起**零 Node 依赖**（`scripts/check-consumer-types.sh` 守护），没有 `@types/node`、`skipLibCheck: false` 也能编译。
|
||||
|
||||
---
|
||||
|
||||
## 3. 最小骨架（client half）
|
||||
@@ -149,18 +160,73 @@ interface TabDescriptor {
|
||||
*/
|
||||
createTab?: (state: SidebarState) => { tab: SidebarTab; patch?: Partial<SidebarState> } | null
|
||||
/**
|
||||
* 声明式设置（v0.4.1+）：见 §7。
|
||||
* 声明式设置（v0.4.1+）：见 §8。v0.12.0 起增加 `pluginToggles`（插件自有
|
||||
* 设置行，key 无需宿主 schema 字段）与 `render`（自定义设置面板）。
|
||||
*/
|
||||
settings?: {
|
||||
toggles?: readonly {
|
||||
key: string
|
||||
title: string | (() => string)
|
||||
desc?: string | (() => string)
|
||||
}[]
|
||||
}
|
||||
settings?: SidebarSettingsDeclaration
|
||||
/**
|
||||
* tab 角标（v0.12.0+）：tab 图标旁的小圆角 pill。number 渲染计数（99+ 封顶），
|
||||
* string 原样文本，null/undefined 不显示。每次 tab 栏渲染都会调用——保持廉价；
|
||||
* 抛错会被吞掉（不显示角标，不影响渲染）。
|
||||
*/
|
||||
badge?: (ctx: Context, scope: SessionScope, state: SidebarState) => string | number | null | undefined
|
||||
/**
|
||||
* 生命周期回调（v0.12.0+），只由 SERVICE 路径触发：
|
||||
* - onOpen：openTab 真正**新建** tab 后（dedupe/id 安全网聚焦不算打开）；
|
||||
* - onActivate：tab 被聚焦时（dedupe 聚焦、id 安全网聚焦、tab 栏点击激活）；
|
||||
* - onClose：closeTab 关闭 tab 后。
|
||||
* 内置专属流程（diff 拆分放置、agent 终端 reconcile）直接改 state，不触发
|
||||
* 回调——但它们只作用于内置类型（diff/terminal），外部插件的 tab 永远走
|
||||
* service 路径。回调抛错只 console.error，绝不打断打开/关闭流程。
|
||||
*/
|
||||
onOpen?: (tab: SidebarTab, scope: SessionScope) => void
|
||||
onActivate?: (tab: SidebarTab, scope: SessionScope) => void
|
||||
onClose?: (tab: SidebarTab, scope: SessionScope) => void
|
||||
/** 渲染函数 */
|
||||
component: (props: TabComponentProps) => ReactNode
|
||||
}
|
||||
|
||||
/** 声明式设置声明（v0.12.0 完整形状；行控件见 §8）。 */
|
||||
interface SidebarSettingsDeclaration {
|
||||
/** 宿主 prefs 字段行（key 必须是宿主 PrefsSchema 的字段）。 */
|
||||
toggles?: readonly {
|
||||
key: string
|
||||
title: string | (() => string)
|
||||
desc?: string | (() => string)
|
||||
type?: 'switch' | 'text' | 'number' // v0.11.0+；缺省 'switch'
|
||||
min?: number
|
||||
max?: number
|
||||
placeholder?: string
|
||||
unit?: string
|
||||
}[]
|
||||
/** 插件自有设置行（v0.12.0+）：形状同 toggles，key 插件局部，
|
||||
* 持久化在 pluginSettings[<descriptor id>]，无需宿主 schema 字段。 */
|
||||
pluginToggles?: readonly {
|
||||
key: string
|
||||
title: string | (() => string)
|
||||
desc?: string | (() => string)
|
||||
type?: 'switch' | 'text' | 'number'
|
||||
min?: number
|
||||
max?: number
|
||||
placeholder?: string
|
||||
unit?: string
|
||||
}[]
|
||||
/** 自定义设置面板（v0.12.0+）：给出时齿轮弹窗渲染它而非行列表。 */
|
||||
render?: (props: SidebarSettingsRenderProps) => ReactNode
|
||||
}
|
||||
|
||||
/** settings.render 收到的 props（v0.12.0+）。 */
|
||||
interface SidebarSettingsRenderProps {
|
||||
store: SidebarStore
|
||||
service: BetterSidebarService
|
||||
prefs: SidebarPrefs
|
||||
/** 本 descriptor 自己的持久化设置 blob（pluginSettings[id]）。 */
|
||||
pluginSettings: Record<string, unknown>
|
||||
/** 持久化一条本 descriptor 的插件设置（值须 JSON 可序列化）。 */
|
||||
updatePluginSetting(key: string, value: unknown): void
|
||||
/** 关闭设置弹窗。 */
|
||||
close(): void
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 `TabComponentProps`（你的页面组件收到的 props）
|
||||
@@ -263,6 +329,7 @@ ctx.effect(() =>
|
||||
| `git` | 20 | 是 | 否 | Git 面板 |
|
||||
| `subagent` | 30 | 是 | 否 | 子代理拓扑 |
|
||||
| `terminal` | 40 | 否（createTab 自增） | 否 | 终端（配额 3） |
|
||||
| `browser` | 50 | 否（createTab 铸造 browser:`<n>`，nextBrowser 自增） | 否 | 内嵌网页浏览器（沙箱 iframe；可设置关闭沙箱） |
|
||||
| `diff` | -1 | 否（按 id 去重） | 是 | 差异查看（由 GitView 触发） |
|
||||
|
||||
你的 `id` 不可与上述重复，否则 `registerTab` 抛 `"tab type \"X\" already registered"`。
|
||||
@@ -289,10 +356,12 @@ interface FileViewerDescriptor {
|
||||
fetchStrategy: 'none' | 'fsRead' | 'mediaUrl' | 'custom' | 'binary-download'
|
||||
/** 内容嗅探（覆盖 exts）：head 字节可用时，第一个 detect 返回 true 的 viewer 命中 */
|
||||
detect?: (path: string, head: Uint8Array) => boolean
|
||||
/** fetchStrategy='custom' 时的加载函数 */
|
||||
load?: (path: string, scope: SessionScope) => Promise<unknown>
|
||||
/** 声明式设置（v0.4.1+）：形状同 TabDescriptor.settings */
|
||||
settings?: { toggles?: readonly { key: string; title: string | (() => string); desc?: string | (() => string) }[] }
|
||||
/** fetchStrategy='custom' 时的加载函数；v0.12.0+ 第三参 signal 在 viewer
|
||||
* 卸载/重匹配时中止（忽略 signal 的 load 也照常工作） */
|
||||
load?: (path: string, scope: SessionScope, signal?: AbortSignal) => Promise<unknown>
|
||||
/** 声明式设置（v0.4.1+）：形状同 TabDescriptor.settings（v0.12.0 起 viewer
|
||||
* 卡片也有齿轮按钮，pluginToggles/render 同样可用） */
|
||||
settings?: SidebarSettingsDeclaration
|
||||
/** 渲染函数 */
|
||||
component: (props: FileViewerProps) => ReactNode
|
||||
}
|
||||
@@ -336,7 +405,7 @@ interface FileViewerProps {
|
||||
|
||||
> **head 字节从哪来**：第一次匹配（纯扩展名）没有 head。`fsRead` 策略读取后若文件为二进制，host 的 `fs.read` 响应会带 `head` 字段（base64，前 4KB，`src/index.ts` 的 `READ_HEAD_LIMIT`），编辑器会用它对 `detect` viewer **重匹配一次**——所以 detect 型 viewer 的实际触发场景是"扩展名匹配落空/二进制文件"。文本文件的 detect 嗅探不在内置流程内（用 `exts` 或 `custom` 策略替代）。
|
||||
|
||||
> **内置 viewer**（不可重复注册，全部 8 个）：image(0) / pdf(0) / docx(0) / xlsx(0) / pptx(0) / markdown(0, fsRead) / code(-100, catch-all, fsRead) / binary-download(-50, exts doc/xls/ppt + NUL detect)。
|
||||
> **内置 viewer**（不可重复注册，全部 9 个）：image(0) / pdf(0) / docx(0) / xlsx(0) / pptx(0) / markdown(0, fsRead) / html(0, fsRead, 沙箱 iframe 预览) / code(-100, catch-all, fsRead) / binary-download(-50, exts doc/xls/ppt + NUL detect)。
|
||||
> code 是兜底 viewer：任何其他 viewer 未认领的文件都会落到 code（CodeMirror 文本编辑）；二进制文件经 head 重匹配被 binary-download 的 NUL detect 认领（下载按钮）。外部 viewer 注册同扩展名 + 更高 priority 即可覆盖。
|
||||
|
||||
### 5.5 注册示例
|
||||
@@ -453,14 +522,75 @@ interface BetterSidebarService {
|
||||
* 打开一个 tab（+ 菜单和外部触发都用它；走 descriptor.dedupeKey 去重）。
|
||||
* title 可选：给出时优先于 descriptor.title（editor 显示文件名）；
|
||||
* 有 createTab 的 descriptor（terminal）会忽略 title/path/id。
|
||||
* url 可选：落地后把 tab 的 path 预填为 URL（侧边栏浏览器导航种子）。
|
||||
* 被设置禁用的类型是 no-op（console.warn 提示）。
|
||||
* scope（v0.12.0+）定向到指定 session：给出且非当前 session 时，打开落在
|
||||
* 该 session 的侧边栏状态里（没有则按 prefs 新建），不切换 UI 的激活 session；
|
||||
* 缺省或指向当前 session 时行为与之前完全一致。注意：available 不拦截 openTab。
|
||||
* 内容型打开（带 path/url seed）自动展开承载面板，保证落点可见。
|
||||
*/
|
||||
openTab(seed: { type: string; title?: string; path?: string; diff?: SidebarTab['diff']; id?: string }): void
|
||||
openTab(seed: OpenTabSeed, scope?: SessionScope): void
|
||||
/** 关闭一个 tab */
|
||||
closeTab(tabId: string): void
|
||||
/** 订阅注册表变化（register/dispose 时触发） */
|
||||
subscribe(listener: () => void): () => void
|
||||
// ── v0.12.0+ ──────────────────────────────────────────────────────────
|
||||
/** 插件版本（如 '0.12.0'；与 package.json 同步，测试守护） */
|
||||
readonly version: string
|
||||
/** 单调能力清单（只增不删）：'badge' | 'tabLifecycle' | 'updateTab' |
|
||||
* 'openFile' | 'targetedOpen' | 'stateSubscription' | 'tabMeta' |
|
||||
* 'pluginSettings'——用 `features.includes('xxx')` 按能力 gate。 */
|
||||
readonly features: readonly string[]
|
||||
/** 当前快照：激活 sessionId + 其状态（面板几何/打开的 tabs/展开集）+ prefs。
|
||||
* session 未激活时 state/sessionId 为 undefined。 */
|
||||
getSnapshot(): SidebarSnapshot
|
||||
/** 订阅快照变化（会话切换/状态变更/prefs 写入）；返回 disposer */
|
||||
subscribeState(listener: () => void): () => void
|
||||
/** 更新一个已打开 tab 的显示字段（title/path/meta）；tab 不存在时 no-op */
|
||||
updateTab(tabId: string, patch: { title?: string; path?: string; meta?: unknown }): void
|
||||
/** 激活一个已打开的 tab（tab 栏点击路径；触发 descriptor.onActivate） */
|
||||
activateTab(tabId: string): void
|
||||
/** 在 scope.sessionId 的侧边栏编辑器打开一个文件（title 缺省为文件名；
|
||||
* id 按路径派生，与内置 open-path 拦截一致，不同文件可并排打开） */
|
||||
openFile(scope: SessionScope, path: string, title?: string): void
|
||||
}
|
||||
|
||||
/** openTab 的 seed（v0.12.0 起导出命名类型）。 */
|
||||
interface OpenTabSeed {
|
||||
type: string
|
||||
title?: string
|
||||
path?: string
|
||||
diff?: SidebarTab['diff']
|
||||
id?: string
|
||||
url?: string
|
||||
/** JSON 可序列化的自定义状态，随 tab 持久化（刷新后原样恢复） */
|
||||
meta?: unknown
|
||||
}
|
||||
```
|
||||
|
||||
**版本与能力探测**（v0.12.0+）：消费插件先查能力再使用新 API，老版本（或旧 DSH）下优雅降级：
|
||||
|
||||
```ts
|
||||
if (ctx.betterSidebar.features.includes('badge')) {
|
||||
// 使用 TabDescriptor.badge
|
||||
}
|
||||
if (ctx.betterSidebar.version >= '0.12.0') { /* 字符串比较即可：minor 只增 */ }
|
||||
```
|
||||
|
||||
**生命周期示例**（v0.12.0+）：打开时启动资源、关闭时释放——组件卸载 ≠ tab 关闭（会话切换也会卸载），所以释放资源要用 `onClose`：
|
||||
|
||||
```ts
|
||||
ctx.effect(() =>
|
||||
ctx.betterSidebar.registerTab({
|
||||
id: 'my-plugin:db',
|
||||
title: 'Database',
|
||||
single: true,
|
||||
badge: (_ctx, _scope, state) => /* 比如打开的连接数，每次 tab 栏渲染调用，保持廉价 */,
|
||||
onOpen: (tab, scope) => { startWatcher(scope.sessionId) },
|
||||
onClose: (tab, scope) => { stopWatcher(scope.sessionId) },
|
||||
component: ({ scope }) => <DbView sessionId={scope.sessionId} />,
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -472,7 +602,9 @@ interface BetterSidebarService {
|
||||
- 展示：小卡片网格（图标 + 标题 + 类型 id），**高亮 = 启用**，勾选徽标钉在卡片最右端；viewer 卡片额外显示扩展名。
|
||||
- 持久化：开关写入 `SidebarPrefs.tabsEnabled / viewersEnabled`（开放 map，**缺省 = 启用**，显式 `false` 才禁用）。
|
||||
- 关闭语义：tab 从 `+` 菜单消失、`openTab` 拒绝新开（`console.warn`）、派生流程（子代理自动展开、agent 终端自动补 tab）停止，**已打开的 tab 保留**；viewer 被 `matchFileViewer` 跳过，文件落到下一个匹配。
|
||||
- `settings.toggles`（可选）：在卡片行下追加**嵌套开关**（仅父级启用时显示），绑定 `SidebarPrefs` 字段；通过卡片右下角齿轮按钮在原生弹窗中编辑（复选框行）。内置示例：subagent tab 的 `autoOpenSubagent`、terminal tab 的 `agentTerminalTools`。
|
||||
- `settings.toggles`（可选）：在卡片行下追加**嵌套设置行**（仅父级启用时显示），绑定 `SidebarPrefs` 字段；通过卡片右下角齿轮按钮在原生弹窗中编辑。行控件 v0.11.0 起不限于布尔：`type: 'switch' | 'text' | 'number'`（缺省 'switch'；text/number 行 blur/Enter 提交，number 行按 min/max 钳制，unit 渲染单位后缀）。内置示例：subagent tab 的 `autoOpenSubagent`、terminal tab 的 `agentTerminalTools` + 自定义字体行。
|
||||
- `settings.pluginToggles`（可选，v0.12.0+）：**插件自有设置行**，行控件与 toggles 相同，但 key 是插件局部的——持久化在 prefs 文档的 `pluginSettings[<descriptor id>]`（开放 map，无需宿主 schema 字段）。tab 与 viewer 都可用（v0.12.0 起 viewer 卡片也有齿轮按钮）。
|
||||
- `settings.render`（可选，v0.12.0+）：**自定义设置面板**——给出时齿轮弹窗渲染它而非行列表。props 含 store/service/prefs、本 descriptor 的 `pluginSettings` blob、`updatePluginSetting(key, value)` 与 `close()`；抛错会被吞掉并显示内联错误。
|
||||
|
||||
```ts
|
||||
ctx.effect(() =>
|
||||
@@ -481,18 +613,36 @@ ctx.effect(() =>
|
||||
title: 'Database',
|
||||
order: 50,
|
||||
settings: {
|
||||
// 宿主 prefs 字段行：key 必须是宿主 PrefsSchema 的字段（仅此限制）
|
||||
toggles: [{
|
||||
key: 'myPluginAutoConnect', // ⚠️ 必须是宿主 PrefsSchema 的字段，见下
|
||||
title: 'Auto connect',
|
||||
desc: 'Connect on open',
|
||||
key: 'autoOpenSubagent', // 宿主内置键
|
||||
title: 'Auto-open',
|
||||
desc: 'Open when a subagent appears',
|
||||
}],
|
||||
// 插件自有设置行：key 插件局部，持久化在 pluginSettings['my-plugin:db']
|
||||
pluginToggles: [{
|
||||
key: 'pageSize',
|
||||
title: 'Page size',
|
||||
type: 'number',
|
||||
min: 1,
|
||||
max: 100,
|
||||
unit: 'rows',
|
||||
}],
|
||||
// 或完全自定义面板（给定时代替行列表）
|
||||
render: ({ store, service, prefs, pluginSettings, updatePluginSetting, close }) => (
|
||||
<MySettingsPanel
|
||||
values={pluginSettings}
|
||||
onChange={(key, value) => { updatePluginSetting(key, value) }}
|
||||
onDone={close}
|
||||
/>
|
||||
),
|
||||
},
|
||||
component: ({ scope }) => <DbView sessionId={scope.sessionId} />,
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
> ⚠️ **key 必须是宿主 PrefsSchema 的字段**（内置键：`autoOpenSubagent` / `agentTerminalTools`）。外部插件的自定义键会被 settings seam 丢弃——当前版本嵌套开关只支持宿主预置的布尔偏好；想给用户暴露你自己的设置，走 DSH 自己的 settings 服务（`ctx.settings`），不要依赖这里的 `toggles`。
|
||||
> ⚠️ **`toggles` 的 key 必须是宿主 PrefsSchema 的字段**（内置键：`autoOpenSubagent` / `agentTerminalTools` / `terminalFontFamily` / `terminalFontSize` / `htmlViewerNoSandbox` / `htmlViewerDefaultUnsafe` / `browserNoSandbox` / `browserInterceptLinks`）。**v0.12.0 起设置 seam 已开放**：你自己的设置走 `pluginToggles`（声明式行）或 `render`（自定义面板），值持久化在 `pluginSettings[id]`——不再需要宿主 schema 字段，也不再被 seam 丢弃。值须 JSON 可序列化（行控件只产出 string/number/boolean；自定义面板自行负责）。
|
||||
|
||||
---
|
||||
|
||||
@@ -516,6 +666,7 @@ ctx.effect(() =>
|
||||
| **portal 限制** | 整面板 slot 由 ui-layout 独占，外部 tab 只能进入 better-sidebar 的 portal 内部，无法全屏替换整个面板 |
|
||||
| **id 冲突** | `registerTab` / `registerFileViewer` 对重复 id 抛错；建议用包前缀（`my-plugin:xxx`） |
|
||||
| **不要 value-import `dsh-better-sidebar`** | 即使是 `./client/service` 子路径，运行时落点也是 client bundle；只做 type-only import |
|
||||
| **client 声明图零 Node 依赖（v0.12.0+）** | `dsh-better-sidebar/client/service` 的可达声明面（含 `Context`）不引用 `node:*` / `Buffer`——纯浏览器侧插件无需 `@types/node`，`skipLibCheck: false` 也能编译（`scripts/check-consumer-types.sh` 守护；主入口含宿主声明，宿主消费者本就处于 Node 环境） |
|
||||
|
||||
---
|
||||
|
||||
@@ -606,13 +757,13 @@ function parseCsv(text: string): string[][] { /* ... */ }
|
||||
|
||||
better-sidebar 的内置 tab 和 viewer 就是参考实现（"吃狗粮"）：
|
||||
|
||||
- **`src/client/builtins/`**：6 个内置 tab（tabs.tsx）+ 8 个内置 viewer（viewers.tsx）的注册代码 + 聚合与 disposer 生命周期（index.ts）
|
||||
- **`src/client/builtins/`**：7 个内置 tab（tabs.tsx）+ 9 个内置 viewer（viewers.tsx）的注册代码 + 聚合与 disposer 生命周期（index.ts）
|
||||
- **`src/client/service.ts`**：`BetterSidebarService` 接口 + `createBetterSidebarService` 工厂实现（含匹配算法、dedupe、createTab、启用态 gating）
|
||||
- **`src/client/Sidebar.tsx`**：`TabContent` 分发（查 `getTab` → 调 descriptor.component；未注册 → `<OrphanedTab/>`）、`+` 菜单构建（order 排序 + available disabled + 禁用过滤）
|
||||
- **`src/client/SideCardSection.tsx`**：声明式设置页（注册表驱动清单 + `settings.toggles` 嵌套开关 + 开关持久化）
|
||||
- **`src/client/api.ts`**：`/sidebar` API 的封装（复制其 fetch 模式到你的插件）
|
||||
- **`tests/service.spec.ts`**：注册表生命周期 / 匹配算法 / dedupe / createTab / 启用态 gating 测试
|
||||
- **`tests/builtins.spec.ts`**：内置注册清单断言（6 tab + 8 viewer + 声明式元数据）
|
||||
- **`tests/builtins.spec.ts`**：内置注册清单断言（7 tab + 9 viewer + 声明式元数据）
|
||||
- **`docs/plans/2026-08-11-service-registry-design.md`** / **`docs/plans/2026-08-11-declarative-sidebar-settings-design.md`**：设计文档（§17 含实施偏差记录，以现状为准）
|
||||
|
||||
调试时直接读这些文件即可看到所有 API 的真实用法。
|
||||
|
||||
Reference in New Issue
Block a user