figmar/apes-sidebar
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: 公共 API 基座化（v0.12.0，纯增量）— 类型/能力/设置 seam 全面补齐

Browse Source 
- 类型生态：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
2026-08-14 20:44:43 +08:00
parent 288a499c7f
commit 82a69546d2
28 changed files with 1512 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+95 -6
View File
@@ -86,7 +86,16 @@ export function apply(ctx: Context): void {
import type { TabDescriptor, FileViewerDescriptor, BetterSidebarService } from 'dsh-better-sidebar'
```
类型定义在 `lib/types/client/service.d.ts`，通过 `package.json` 的 `./client/service`（别名 `./client/api`）exports 子路径暴露。
类型定义在 `lib/types/client/service.d.ts`，通过 `package.json` 的 `./client/service`（别名 `./client/api`）exports 子路径暴露。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 中，service 声明会拉入它）——纯浏览器侧插件建议走 `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` 也能编译。
---
@@ -131,6 +140,9 @@ interface TabDescriptor {
* 绑定 SidebarPrefs 字段。嵌套设置仅父级启用时显示（v0.11.0 起行控件不限于
* 布尔开关：`type: 'switch' | 'text' | 'number'`，缺省 'switch'；text/number
* 行 blur/Enter 提交，number 行按 min/max 钳制，unit 渲染单位后缀）。
* v0.12.0 起增加两个插件自有扩展（详见 §5 声明式设置）：
* `pluginToggles`（插件自有 key，持久化在 pluginSettings[id]，无需宿主 schema 字段）
* 与 `render`（自定义设置面板，替代行列表）。
*/
settings?: {
toggles?: readonly {
@@ -149,7 +161,48 @@ interface TabDescriptor {
/** 输入框后的单位后缀（如 'px'）。 */
unit?: string
}[]
/** 插件自有设置行（v0.12.0+）：形状同 toggles，但 key 是插件局部的，
* 持久化在 `pluginSettings[<descriptor id>]`——不需要宿主 PrefsSchema 字段。 */
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+）：给出时齿轮弹窗渲染它而非行列表。
* props 含 store/service/prefs、本 descriptor 的 pluginSettings blob、
* updatePluginSetting(key, value) 与 close()。抛错会被吞掉并显示内联错误。 */
render?: (props: {
store: SidebarStore
service: BetterSidebarService
prefs: SidebarPrefs
pluginSettings: Record<string, unknown>
updatePluginSetting: (key: string, value: unknown) => void
close: () => void
}) => ReactNode
}
/**
* 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，绝不打断打开/关闭流程。scope 携带 { sessionId, cwd? }。
*/
onOpen?: (tab: SidebarTab, scope: SessionScope) => void
onActivate?: (tab: SidebarTab, scope: SessionScope) => void
onClose?: (tab: SidebarTab, scope: SessionScope) => void
/** 渲染函数 */
component: (props: TabComponentProps) => ReactNode
}
@@ -214,7 +267,8 @@ ctx.effect(() =>
title: 'Commits',
icon: <CommitIcon />,
order: 70,
available: (state) => hasGitRepo(state), // 返回 false 时 + 菜单显示为 disabled
available: (ctx, scope, state) => hasGitRepo(state), // 三参 (ctx, scope, state)；返回 false 时 + 菜单显示为 disabled
// 注意：available 只影响 + 菜单的 disabled 状态，不会拒绝 openTab（只有设置页的禁用开关会）。
dedupeKey: () => 'my-plugin:commits',
component: ({ scope }) => <CommitsView sessionId={scope.sessionId} />,
})
@@ -257,8 +311,9 @@ 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>
/** fetchStrategy='custom' 时的加载函数；v0.12.0+ 第三参 signal 在 viewer
* 卸载/重匹配时中止（忽略 signal 的 load 也照常工作） */
load?: (path: string, scope: SessionScope, signal?: AbortSignal) => Promise<unknown>
/** 声明式设置（v0.4.1+）：形状同 TabDescriptor.settings */
settings?: { toggles?: readonly { key: string; title: string | (() => string); desc?: string | (() => string) }[] }
/** 渲染函数 */
@@ -384,19 +439,53 @@ interface BetterSidebarService {
* url 可选：落地后把 tab 的 path 预填为 URL（侧边栏浏览器导航种子，
* 通常配合 hostname title；对 createTab 铸造的 tab 同样生效）。
* 被设置禁用的类型是 no-op（console.warn 提示）。
* scope（v0.12.0+）定向到指定 session：给出且非当前 session 时，打开落在
* 该 session 的侧边栏状态里（没有则按 prefs 新建），不切换 UI 的激活 session；
* 缺省或指向当前 session 时行为与之前完全一致。注意：available 不拦截 openTab。
* 内容型打开（带 path/url seed）必须落在视野内：承载落点 pane 的面板
* 折叠时自动展开（右侧面板；落点 pane 在底部树则展开底部面板；窄视口
* 展开合并抽屉）；类型型打开（+ 菜单、agent 终端自动补 tab）不展开。
*/
openTab(seed: { type: string; title?: string; path?: string; diff?: SidebarTab['diff']; id?: string; url?: 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.4.1+）**：每个注册的 tab/viewer 自动出现在 DSH 设置页「侧边卡片」分区的清单里——响应式网格中的**小卡片**（图标 + 标题 + 类型 id + **高亮 = 启用**，勾选徽标钉在卡片最右端，viewer 卡片还显示扩展名），开关持久化到 `SidebarPrefs.tabsEnabled / viewersEnabled`（开放 map，缺省 = 启用）。关闭语义：tab 从 `+` 菜单消失、`openTab` 拒绝新开、子代理自动展开 / agent 终端自动补 tab 等派生流程停止，**已打开的 tab 保留**；viewer 被 `matchFileViewer` 跳过，文件落到下一个匹配。`settings.toggles` 声明的相关设置（如子代理的 `autoOpenSubagent`、终端的 `terminalFontFamily`/`terminalFontSize`）通过卡片右下角的齿轮按钮在**原生弹窗**中编辑——`type: 'switch'` 行是复选框，`type: 'text'`/`'number'` 行是输入框（v0.11.0+）——父级卡片关闭时齿轮隐藏；**key 必须是宿主 PrefsSchema 的字段**（内置键：`autoOpenSubagent` / `agentTerminalTools` / `terminalFontFamily` / `terminalFontSize` / `htmlViewerNoSandbox` / `htmlViewerDefaultUnsafe` / `browserNoSandbox` / `browserInterceptLinks`），外部插件的自定义键会被 settings seam 丢弃。
> **声明式设置（v0.4.1+）**：每个注册的 tab/viewer 自动出现在 DSH 设置页「侧边卡片」分区的清单里——响应式网格中的**小卡片**（图标 + 标题 + 类型 id + **高亮 = 启用**，勾选徽标钉在卡片最右端，viewer 卡片还显示扩展名），开关持久化到 `SidebarPrefs.tabsEnabled / viewersEnabled`（开放 map，缺省 = 启用）。关闭语义：tab 从 `+` 菜单消失、`openTab` 拒绝新开、子代理自动展开 / agent 终端自动补 tab 等派生流程停止，**已打开的 tab 保留**；viewer 被 `matchFileViewer` 跳过，文件落到下一个匹配。`settings.toggles` 声明的相关设置（如子代理的 `autoOpenSubagent`、终端的 `terminalFontFamily`/`terminalFontSize`）通过卡片右下角的齿轮按钮在**原生弹窗**中编辑——`type: 'switch'` 行是复选框，`type: 'text'`/`'number'` 行是输入框（v0.11.0+）——父级卡片关闭时齿轮隐藏；`settings.toggles` 的 **key 必须是宿主 PrefsSchema 的字段**（内置键：`autoOpenSubagent` / `agentTerminalTools` / `terminalFontFamily` / `terminalFontSize` / `htmlViewerNoSandbox` / `htmlViewerDefaultUnsafe` / `browserNoSandbox` / `browserInterceptLinks`）。**v0.12.0 起设置 seam 已开放**：外部插件用 `settings.pluginToggles`（同款行控件，key 插件局部）或 `settings.render`（自定义面板）声明自己的设置，值持久化在 prefs 文档的 `pluginSettings[<descriptor id>]`（开放 map，宿主 schema 已有字段，无需注册）——齿轮弹窗对 tab 与 viewer 都可用（viewer 卡片 v0.12.0 起也有齿轮）。
---