从零写一个DSH-better-sidebar插件：registerTab到上架的完整教程（附最小代码骨架与避坑清单）

从零写一个DSH-better-sidebar插件registerTab到上架的完整教程附最小代码骨架与避坑清单【免费下载链接】DSH-better-sidebar开放的侧边栏底座支持三方拓展注册新侧边栏页面。内置文件渲染编辑/终端/侧边对话/Git/子代理页面 Open sidebar foundation, supports third-party extensions to register new sidebar pages. Built-in file rendering/editing, terminal, side chat, Git, and sub-agent pages.项目地址: https://gitcode.com/gh_mirrors/ds/DSH-better-sidebarDSH-better-sidebar 是一个开放的侧边栏底座它为 DSH 提供 VSCode 风格的右侧栏内置文件预览编辑、终端、侧边对话、Git、子代理等页面并允许三方插件通过registerTab注册全新的侧边栏页面。本教程带你从零写完第一个 DSH-better-sidebar 插件准备骨架 →registerTab注册页面 → 接入数据 API → 本地挂载验证 → 上架约束与避坑清单全程适用于 v0.19.x。 一分钟理解插件就是「注册 渲染」better-sidebar 从 v0.4.0 起本质上是一个注册表服务你能扩展两类东西新页面tab调用registerTab注册一种侧边栏 tab 类型它出现在侧边栏菜单里用户点击后打开你的 React 页面文件预览器viewer调用registerFileViewer认领一种文件扩展名的渲染用户在侧边栏打开对应文件时走你的组件。内置的 7 个 tabeditor / git / subagent / sidechat / terminal / browser / diff和 6 个文件预览器全部用同一套 API 注册——三方插件与内置功能完全对等内置代码就是最好的参考实现。机制一句话better-sidebar 在apply()开头执行ctx.provide(betterSidebar, service)见 src/client/index.tsx你的插件在inject里声明betterSidebarCordis 保证服务就绪后才激活你注册时机无忧。 服务只存在于浏览器侧client halfhost 半没有ctx.betterSidebar需要读数据时走/sidebar/api/*HTTP 路由。1️⃣ 准备依赖声明三件套声明 peer 依赖避免双实例{ peerDependencies: { deepseek-ai/cordis: ^4.0.1, dsh-better-sidebar: workspace:* }, peerDependenciesMeta: { dsh-better-sidebar: { optional: true } } }必须是peerDependency不是 dependency否则会出现两份实例optional: true保证 better-sidebar 未安装时你的插件照常加载注册代码安全跳过。触发类型合并type-only零运行时耦合import type {} from dsh-better-sidebar // 让 ctx.betterSidebar 出现在 Context 类型上这行 import 编译时被擦除不产生运行时依赖、不触发构建纯度门。类型可以自由共享但绝不能 value-import。版本前提当前版本 v0.19.1需要 DSH0.1.5-rc.1。新能力badge、pluginToggles、urlTarget、fileIcons等请先查ctx.betterSidebar.features再用老版本优雅降级。2️⃣ 最小代码骨架15 行注册你的第一个侧边栏页面完整的 client half 入口骨架如下——注册一个单实例的「Notes」tab// my-plugin/src/client/index.tsx import type {} from dsh-better-sidebar import type { Context } from deepseek-ai/cordis export const inject [betterSidebar] export function apply(ctx: Context): void { ctx.effect(() ctx.betterSidebar.registerTab({ id: my-plugin:notes, // 建议带包前缀避免 id 冲突 title: Notes, icon: NoteIcon /, order: 50, // 菜单排序升序 single: true, // 单实例重复打开聚焦而非新建 component: ({ scope }) NotesView sessionId{scope.sessionId} /, }) ) }两条不可省略的纪律要点原因用ctx.effect(...)包裹注册registerTab返回 disposerfiber 卸载HMR / 禁用插件时自动撤销注册不包 effect下次激活会抛already registered在inject声明依赖Cordis 保证 better-sidebar 先激活注册顺序无关、时机无忧你的页面组件会收到TabComponentPropsscope会话标识请求 API 必带、visible是否当前激活、tab、store等。约定俗成用visible false暂停轮询/订阅内置子代理页就是这个做法。3️⃣ 给页面喂数据调用 /sidebar/api你的组件与内置视图同源同权直接fetch即可响应包裹层是{ value }const res await fetch(/sidebar/api/fs.read, { method: POST, headers: { content-type: application/json }, body: JSON.stringify({ sessionId: scope.sessionId, path }), }) const { value } await res.json()常用方法一览完整清单见 src/client/api.ts方法用途session.cwd会话权威工作目录fs.tree/fs.read/fs.write目录列表 / 读文件文本返回内容二进制返回 head/ 原子写git.status/git.diff/git.log全套 Git 操作settings.get/settings.update侧边栏偏好读写 所有文件路径以会话工作目录为边界越界绝对路径、..解析结果和指向外部的符号链接都会被拒绝别把cwd当成可扩大权限的参数。4️⃣ 可选进阶registerFileViewer 认领文件预览想让.csv这类文件在侧边栏预览再注册一个预览器即可exts声明扩展名、fetchStrategy: customload()自己拉取解析数据、component渲染。要覆盖内置预览器注册同扩展名 更高的priority即可。五种字节策略对照表和匹配算法priority 降序单趟裁决 magic bytes 嗅探详见官方接入指南 docs/external-plugin-guide.md。5️⃣ 挂载验证4 步看到效果~/.dsh/profiles/web/package.json的dependencies加my-plugin: link:你的插件路径~/.dsh/profiles/web/cordis.patch.yml追加一行挂载声明- insert: - id: my-plugin / name: my-plugin在 profile 目录执行pnpm install浏览器硬刷新Cmd/CtrlShiftR。client 半是热加载的无需重启dsh web仅 host 半改动需要重启。插件未加载时已持久化的 tab 会优雅降级成「插件未加载」占位卡不会白屏。6️⃣ 上架市场硬约束 推荐插件目录市场 manifest 硬约束必读计划上架 DSH 插件市场时package.json必须满足由 tests/market-manifest.spec.ts 守护权威规则见 AGENTS.mddependencies/peerDependencies/optionalDependencies一律不得出现cordis按名硬拒optional无效scripts不得包含preinstall/install/postinstall/prepare。进入官方「添加插件」目录DSH 设置页「添加插件」弹窗的数据源是 src/client/plugins-tabs.ts 与 src/client/plugins-viewers.ts——加一条数据即上架目录由 tests/plugin-list.spec.ts 守护。⚠️ 避坑清单发布前过一遍这 6 项#坑规避方式1注册残留下次激活抛already registered永远ctx.effect包裹disposer 交给 fiber 持有2构建纯度门拦截严禁 value-importdsh-better-sidebar只做import type3id 与内置冲突id不可与内置 7 tab / 6 viewer 重复用my-plugin:xxx前缀4host 半读不到数据ctx.betterSidebar只在 clienthost 半走/sidebar/api/*HTTP5文案不跟随语言不依赖内部t()title/description传字符串或() string6面板配色破坏皮肤颜色一律走 DSH 皮肤令牌--dsw-alias-*不硬编码自动兼容全部皮肤 延伸阅读完整接入指南API 全字段 / 匹配算法 / 皮肤契约docs/external-plugin-guide.md服务实现src/client/service.ts内置 tab 注册参考src/client/builtins/tabs.tsx内置预览器参考src/client/builtins/viewers.tsx注册表生命周期测试写自己的测试可参照tests/service.spec.ts逐特性设计文档含实施偏差记录以现状为准docs/plans/【免费下载链接】DSH-better-sidebar开放的侧边栏底座支持三方拓展注册新侧边栏页面。内置文件渲染编辑/终端/侧边对话/Git/子代理页面 Open sidebar foundation, supports third-party extensions to register new sidebar pages. Built-in file rendering/editing, terminal, side chat, Git, and sub-agent pages.项目地址: https://gitcode.com/gh_mirrors/ds/DSH-better-sidebar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考