# dsh-plugin-core 中文文档

规范地址：https://npmcn.com/package/dsh-plugin-core/

版本：0\.22\.1
npm 元数据更新时间：2026-11-03T11:57:18.599Z
中文译文更新时间：2026-11-03T13:39:19.657Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-plugin-core
原文对照：https://npmcn.com/package/dsh-plugin-core/?lang=original
项目主页：https://github.com/cq-guojia/dsh-plugin-core
源码仓库：https://github.com/cq-guojia/dsh-plugin-core

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，658 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.5
- 运行依赖：15 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-10-18T23:40:09.602Z
- 最新版本发布：2026-11-03T11:57:18.236Z
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

DSH插件的共享基础：设计令牌、UI控件、utils、工作空间资源管理器、会话预览

## 安装

```sh
npm install dsh-plugin-core
```

也可以使用：`pnpm add dsh-plugin-core`、`yarn add dsh-plugin-core`、`bun add dsh-plugin-core`

## README

# dsh-plugin-core

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

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

## 先看效果：装上预览插件

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

```bash
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，预览的永远是当前这份代码。

## 用这个包写插件

```bash
pnpm add dsh-plugin-core
```

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

```ts
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` 会让打包器无法摇树，这一份收益会静默归零。

## 子包

| 引入路径 | 装什么 |
| --- | --- |
| `dsh-plugin-core/design` | token 变量表（含深色段）+ `createStyleKit` 注入器工厂 + 主题判据（零 React） |
| `dsh-plugin-core/ui` | 控件：Button / Input 家族 / Textarea / Checkbox / Segmented / Select / Picker / ModelPicker / DateTimePicker / Modal / toast / 空态 / 错误边界 / Loading … |
| `dsh-plugin-core/utils` | 纯方法：日期 / 字符串 / 字节 / 时间区间 / HTTP 取数 + 内置中英多语言 |
| `dsh-plugin-core/explorer` | 工作区浏览：`openFilePreview` / `pickWorkspaceFile` / `FileBrowser` 面板 |
| `dsh-plugin-core/explorer/preview` | 文件预览体（md / 代码高亮 / HTML / PDF / Office / 图片） |
| `dsh-plugin-core/session` | 会话预览（承载可换：弹窗 / 侧栏 / 整页） |

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

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

## 几条硬规矩

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

## 多语言

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

## 文档

| 我想… | 看哪 |
| --- | --- |
| 用这个包写插件 | [`docs/help/index.md`](https://npmcn.com/package/dsh-plugin-core/docs/help/index.md) |
| 从零接入一个插件 | [`docs/help/integration.md`](https://npmcn.com/package/dsh-plugin-core/docs/help/integration.md) |
| 查为什么这么设计 | [`docs/requirements.md`](https://npmcn.com/package/dsh-plugin-core/docs/requirements.md) |
| 改这个仓库本身 | `AGENTS.md` → [`docs/README.md`](https://npmcn.com/package/dsh-plugin-core/docs/README.md) |

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

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

本地改了 core 想看效果：

```bash
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 同时发两个包：

```bash
# 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 | 谁在发 | 发到哪 |
| --- | --- | --- |
| `v0.3.0` | `.github/workflows/publish.yml` | `dsh-plugin-core` |
| 同上 | `.github/workflows/demo-publish.yml` | `dsh-plugin-core-demo` |

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

## 常见问题

### dsh-plugin-core 是什么？

DSH插件的共享基础：设计令牌、UI控件、utils、工作空间资源管理器、会话预览

### 如何安装 dsh-plugin-core？

在项目目录运行 npm install dsh-plugin-core，或使用 pnpm add / yarn add / bun add。

### dsh-plugin-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### dsh-plugin-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-plugin-core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.5。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dsh-plugin-core 可以商用吗？

dsh-plugin-core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-plugin-core 还在维护吗？

最新版本 0\.22\.1 发布于 2026/11/03（今天）；至今共发布 63 个版本，其中过去 12 个月发布了 63 个；首次发布于 2026/10/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。