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。

scripts/check-consumer-types.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Consumer-facing type surface check: build a tiny standalone consumer that
+# imports `dsh-better-sidebar/client/service` WITHOUT @types/node and with
+# skipLibCheck: false, then type-check it with the repo's tsc.
+#
+# This is the exact scenario the v0.12.0 API work cares about: the shipped
+# declaration graph (service.d.ts -> context-types.d.ts -> state/api) must
+# resolve and type-check for a browser-only plugin author. Run AFTER
+# `pnpm build` (the check reads lib/types).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+mkdir -p "$WORK/node_modules"
+ln -s "$(pwd)" "$WORK/node_modules/dsh-better-sidebar"
+
+cat > "$WORK/check.ts" <<'EOF'
+import type {} from 'dsh-better-sidebar/client/service'
+import type {
+  BetterSidebarService, FileViewerDescriptor, OpenTabSeed, SidebarSettingsRenderProps,
+  TabComponentProps, TabDescriptor,
+} from 'dsh-better-sidebar/client/service'
+import type { SessionScope, SidebarSnapshot, SidebarState, SidebarStore, SidebarTab } from 'dsh-better-sidebar/client/service'
+import type { SidebarPrefs } from 'dsh-better-sidebar/client/service'
+
+declare const ctx: { betterSidebar: BetterSidebarService }
+const tab: TabDescriptor = {
+  id: 'x:tab',
+  title: 'X',
+  single: true,
+  badge: (_ctx, _scope, state: SidebarState) => state.expanded.length,
+  onOpen: (_tab: SidebarTab, _scope: SessionScope) => {},
+  onClose: (_tab: SidebarTab, _scope: SessionScope) => {},
+  createTab: (state: SidebarState) => ({ tab: { id: 'x:1', type: 'x:tab', title: 'X', meta: {} } }),
+  settings: {
+    toggles: [{ key: 'autoOpenSubagent', title: 'A' }],
+    pluginToggles: [{ key: 'k', title: 'K', type: 'number', min: 0, max: 9 }],
+    render: (props: SidebarSettingsRenderProps) => { props.updatePluginSetting('a', 1); return null },
+  },
+  component: (props: TabComponentProps) => null,
+}
+ctx.betterSidebar.registerTab(tab)
+const viewer: FileViewerDescriptor = {
+  id: 'x:csv', exts: ['csv'], fetchStrategy: 'custom',
+  load: (_path, _scope, signal?: AbortSignal) => { void signal; return Promise.resolve([]) },
+  component: () => null,
+}
+ctx.betterSidebar.registerFileViewer(viewer)
+const seed: OpenTabSeed = { type: 'x:tab', title: 'X', meta: { a: 1 } }
+ctx.betterSidebar.openTab(seed, { sessionId: 's1' })
+ctx.betterSidebar.openFile({ sessionId: 's1' }, '/p/a.csv')
+ctx.betterSidebar.updateTab('t', { meta: { b: 2 } })
+const snap: SidebarSnapshot = ctx.betterSidebar.getSnapshot()
+const prefs: SidebarPrefs = snap.prefs
+const store: SidebarStore = null as unknown as SidebarStore
+void prefs; void store; void ctx.betterSidebar.version; void ctx.betterSidebar.features
+EOF
+
+cat > "$WORK/tsconfig.json" <<'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2023", "module": "esnext", "moduleResolution": "bundler",
+    "strict": true, "noEmit": true, "skipLibCheck": false, "types": [],
+    "jsx": "react-jsx", "lib": ["ES2023", "DOM"]
+  },
+  "include": ["check.ts"]
+}
+EOF
+
+echo "[check-consumer-types] type-checking a browser-only consumer (no @types/node)..."
+echo "[check-consumer-types]   pass 1: skipLibCheck: true (the realistic consumer experience) — must be fully clean"
+./node_modules/.bin/tsc -p "$WORK/tsconfig.json" --skipLibCheck true
+echo "[check-consumer-types]   pass 2: skipLibCheck: false — OUR declaration surface (lib/types/**) must be clean"
+echo "[check-consumer-types]   (upstream cordis/cosmokit declaration noise is filtered out; it predates this plugin)"
+set +e
+./node_modules/.bin/tsc -p "$WORK/tsconfig.json" --skipLibCheck false > "$WORK/strict.log" 2>&1
+STATUS=$?
+set -e
+# Fail only on errors that mention OUR package / declarations / the fixture.
+if grep -E "dsh-better-sidebar|lib/types|check\.ts" "$WORK/strict.log" | grep -v "node_modules/cordis\|node_modules/cosmokit"; then
+  echo "[check-consumer-types] FAIL: errors in the dsh-better-sidebar declaration surface:" >&2
+  grep -E "dsh-better-sidebar|lib/types|check\.ts" "$WORK/strict.log" >&2
+  exit 1
+fi
+if [ "$STATUS" -ne 0 ]; then
+  echo "[check-consumer-types] pass 2 note: strict mode only reports upstream declaration noise:"
+  grep -v "dsh-better-sidebar\|lib/types\|check\.ts" "$WORK/strict.log" | head -5
+fi
+echo "[check-consumer-types] OK: the client/service declaration surface is node-free and self-contained."
+