dsh-plugin-core

DSH（DeepSeek Harness）插件共享底座：把跨插件复用的样式、控件、通用方法、工作区浏览、会话预览收敛到一处，写新插件时按文档 npm i 引用，不再一个个仓库抄。

服务对象：以后要写的每一个 DSH 插件（不只是现有的几个）。

先看效果：装上预览插件

最快的方式——直接把预览插件装进 DSH 宿主，看真实渲染（明暗、token 全部跟随宿主，不走任何独立网页）：

dsh plugin --profile web add dsh-plugin-core-demo

装好后：插件列表 → 找到 dsh-plugin-core-demo → 进插件详情页就有「组件预览」入口，点开即整页预览；详情页下方还有配置区（侧栏入口开关、查看 demo、访问 GitHub）。

预览插件是仓库里的独立包 packages/demo/（包名 dsh-plugin-core-demo）。它把 core 的构建产物打进自己的 bundle，自包含、不需要 core 先发 npm，预览的永远是当前这份代码。

用这个包写插件

pnpm add dsh-plugin-core

（npm 也行；推荐 pnpm。）包里带预编译 dist——宿主以 git/npm 装插件不跑构建脚本，产物必须随包发布。react 是 optional peer：只用 utils / design 的插件不必装。

import { createStyleKit } from 'dsh-plugin-core/design'
import { Button, setStyleKit } from 'dsh-plugin-core/ui'

setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' })) // 1) 领本插件专属样式设施（id 按插件唯一）
const view = <Button variant="primary" onClick={save}>保存</Button> // 2) 直接用控件，样式它自己带

为什么必须先 setStyleKit：样式只能以字符串在运行时注入 <style>（客户端产物是 JS 闭包，.css 不加载）。固定 style id 在多插件同页时会互相覆盖，所以做成工厂，每个插件领一套自己的；变量前缀统一 dshpc，不再按插件区分。

样式是按需的：每个控件只带自己那份 CSS，首次渲染时自注入（幂等）——用不到的控件，其 CSS 不会被打进你的包（实测：只用 Button 时样式文本从 71.7 KB 降到 9.4 KB）。因此请用具名导入（import { Button } from 'dsh-plugin-core/ui'）：写成 import * as core from … 或 CJS require 会让打包器无法摇树，这一份收益会静默归零。

子包

依赖方向单向：design ← ui ← explorer / session，utils 谁也不依赖。

立包判据：有实质内容、会持续长大的功能模块才独立成包；只是一个控件就进 ui。

几条硬规矩

• 不传整个 ctx：只传需要的那一小块能力，宿主 breaking 时改的是插件「取出」的一行。
• 明暗判据是 body[data-ds-dark-theme]，不是 prefers-color-scheme。
• 多语言：核心自带中英（setLocale('zh' | 'en') 切换），插件自己界面的文案由插件自己管。
• 数据调用方给：选工作区 / 选文件 / 会话预览的数据要跨 host↔client 边界，组件取不到。

多语言

import { setLocale } from 'dsh-plugin-core/utils'
setLocale('en') // 默认中文

文档

组件预览插件（packages/demo/）

库本身是纯库：只有六个子路径导出，没有 main、没有 dsh 字段、零运行时依赖。预览用的插件是仓库里的独立 npm 包 packages/demo/（包名 dsh-plugin-core-demo）。

本地改了 core 想看效果：

pnpm run build        # 先构建库
pnpm run build:demo   # 构建预览插件 → packages/demo/dist/{index.js,client.js}
dsh plugin --profile web add dsh-plugin-core-demo   # 本地路径安装即预览当前代码

旧版「双击 HTML 的独立预览站」（demo-dist/ + demo:build + GitHub Pages）已废弃删除：它不走宿主，与 harness 脱节。explorer / session 的宿主数据仍是 mock 的（packages/demo/src/mock.ts）。

发布（打 tag 即发布）

核心与 demo 共用同一个版本号，一个 tag 同时发两个包：

# 1. 两个 package.json 的 version 改成同一个号
# 2. 构建 + 提交（dist/ 必须入库）
pnpm run build && pnpm run build:demo
git add -A && git commit -m "发布 0.3.0" && git push
# 3. 打 tag 即触发 GitHub Actions 自动发布
git tag v0.3.0 && git push origin v0.3.0

硬规则：tag vX.Y.Z == 根 package.json 的 version == packages/demo/package.json 的 version，三者不一致时 workflow 直接失败。没有 demo-v* 这种独立 tag。 一次性前置：npm 网页 Settings → Trusted Publisher 勾上 npm publish。