# @trops/dash-core 中文文档

规范地址：https://npmcn.com/package/%40trops/dash-core/

版本：0\.1\.895
npm 元数据更新时间：2026-11-02T16:39:16.826Z
中文译文更新时间：2026-11-02T18:46:33.191Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40trops/dash-core
原文对照：https://npmcn.com/package/%40trops/dash-core/?lang=original
项目主页：https://github.com/trops/dash-core#readme
源码仓库：https://github.com/trops/dash-core

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

- 包体积（解压后）：39.2 MB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：35 个
- peer 依赖：react ^18\.2\.0，react-dnd ^16\.0\.1，react-dom ^18\.2\.0，prop-types ^15\.8\.1，tailwindcss ^3\.2\.7，@heroicons/react ^2\.0\.16，react-router-dom ^6\.3\.0，@headlessui/react 1\.4，@trops/dash-react \>=1\.0\.83，react-dnd-html5-backend ^16\.0\.1，react-instantsearch-hooks-web ^6\.26\.0
- 首次发布：2026-02-24T19:05:09.711Z
- 最新版本发布：2026-11-02T16:39:16.407Z
- 已发布版本数：851（近 12 个月 851 个）

## 中文简介

Dash仪表板应用程序的核心框架

## 安装

```sh
npm install @trops/dash-core
```

也可以使用：`pnpm add @trops/dash-core`、`yarn add @trops/dash-core`、`bun add @trops/dash-core`

## README

# @trops / dash-core

Dash仪表板应用程序的核心框架。提供所有Dash应用程序使用的小部件系统、提供者体系结构、上下文提供者、布局引擎和Electron主进程层。

## 安装

```bash
npm install @trops/dash-core
```

**同行依赖性:**

```json
{
  "@trops/dash-react": ">=0.1.187",
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}
```

## 两种导出路径

### 渲染器(反应)

与平台无关的UI框架——上下文、钩子、模型、组件、小部件系统。

```javascript
import {
  ComponentManager,
  DashboardPublisher,
  ErrorBoundary,
  // Contexts
  AppContext,
  DashboardContext,
  ThemeWrapper,
  ProviderContext,
  // Hooks
  useDashboard,
  useMcpProvider,
  useWidgetProviders,
  useInstalledWidgets,
  // Models
  DashboardModel,
  LayoutModel,
  ThemeModel,
  // Components
  LayoutBuilder,
  SettingsPanel,
  NavigationBar,
  // Widget
  Widget,
  WidgetFactory,
  ExternalWidget,
} from "@trops/dash-core";
```

### 电子（主工序）

电子应用程序的控制器、IPC处理程序、事件和小部件管道。

```javascript
const {
  // Factory
  createMainApi,
  // Controllers
  providerController,
  mcpController,
  workspaceController,
  themeController,
  registryController,
  // Widget pipeline
  widgetRegistry,
  widgetCompiler,
  dynamicWidgetLoader,
  // Events
  events,
} = require("@trops/dash-core/electron");
```

## 体系结构

```
@trops/dash-core
├── src/                    Renderer layer (ESM + CJS)
│   ├── Api/                IPC API clients
│   ├── Components/         Dashboard, Layout, Settings, Navigation, etc.
│   ├── Context/            React Context providers
│   ├── Models/             Data models (Dashboard, Layout, Theme, etc.)
│   ├── Widget/             Widget, WidgetFactory, ExternalWidget
│   ├── hooks/              useDashboard, useMcpProvider, useWidgetProviders
│   └── utils/              Bundle loader, layout helpers, validation
│
└── electron/               Electron layer (CJS only)
    ├── api/                IPC handlers + createMainApi factory
    ├── controller/         Business logic (providers, MCP, themes, etc.)
    ├── events/             Event definitions
    ├── mcp/                MCP server catalog
    └── utils/              File, color, browser utilities
```

### 渲染层(`src/`）

与平台无关的UI框架。

| 模块 | 关键文件 | 目的 |
| --- | --- | --- |
| **ComponentManager** | `ComponentManager.js` | 小部件/工作区注册，配置解析 |
| **上下文** | `Context/` | AppContext, DashboardContext, ThemeWrapper, ProviderContext, WidgetContext, WorkspaceContext |
| **钩子** | `hooks/` | useDashboard, useMcpProvider, useWidgetProviders, useInstalledWidgets, useWidgetEvents, userregistrysearch |
| **模型** | `Models/` | DashboardModel、LayoutModel、ThemeModel、ComponentConfigModel、SettingsModel等。 |
| **Api** | `Api/` | DashboardApi, ElectronDashboardApi (typed), WidgetApi, ThemeApi, MockDashboardApi |
| **组件** | `Components/` | 仪表板，布局，设置，导航，主题，提供程序，菜单，工作空间 |
| **小部件** | `Widget/` | Widget, WidgetFactory, ExternalWidget |
| **跑龙套** | `utils/` | widgetBundleLoader, layout, validation, mcpUtils, dragTypes, resolveIcon, themeGenerator, DynamicWidgetLoader, widgeregistry, plugin-loader |

### 电子层(`electron/`）

主流程控制器、api和小部件管道。

| 模块 | 关键文件 | 目的 |
| --- | --- | --- |
| **控制器** | `controller/` | providerController, mcpController, workspaceController, themeController, settingsController, layoutController, dataController, registryController, secureStoreController, dialogController, algolicontroller, openaiController, menuItemsController, pluginController |
| **api** | `api/` | 每个控制器的IPC处理程序+ `mainApi.js` (createMainApi工厂) |
| **事件** | `events/` | 每个模块的事件通道定义 |
| **小部件管道** | `widgetRegistry.js`， `widgetCompiler.js`， `dynamicWidgetLoader.js` | 安装、编译（esbuild）和加载外部小部件 |
| **MCP** | `mcp/mcpServerCatalog.json` | MCP服务器定义（传输、命令、参数、环境映射） |

### 目录结构

```
dash-core/
├── src/                            # Renderer layer
│   ├── Api/
│   ├── ComponentManager.js
│   ├── Components/
│   │   ├── Dashboard/
│   │   ├── Layout/                  # LayoutBuilder, LayoutContainer, LayoutGridContainer
│   │   ├── Navigation/
│   │   ├── Settings/
│   │   ├── Theme/
│   │   ├── Provider/
│   │   ├── Menu/
│   │   └── Workspace/
│   ├── Context/
│   ├── DashboardPublisher.js
│   ├── ErrorBoundary.js
│   ├── Models/
│   ├── Widget/
│   ├── hooks/
│   └── utils/
├── electron/                        # Electron layer
│   ├── api/
│   │   └── mainApi.js               # createMainApi factory
│   ├── controller/
│   ├── events/
│   ├── mcp/
│   │   └── mcpServerCatalog.json
│   ├── utils/
│   ├── widgetRegistry.js
│   ├── widgetCompiler.js
│   └── dynamicWidgetLoader.js
├── dist/                            # Build output — never edit manually
│   ├── index.js                     # Renderer CJS
│   ├── index.esm.js                 # Renderer ESM
│   └── electron/
│       └── index.js                 # Electron CJS
├── docs/                            # Documentation
│   ├── requirements/                # PRDs and feature specs
│   │   └── prd/                     # Product Requirements Documents
│   └── *.md                         # Technical docs
├── .github/workflows/
│   └── release-package.yml          # Auto-publish on push to master
├── package.json
├── rollup.config.renderer.mjs
├── rollup.config.electron.mjs
├── babel.config.json
└── tsconfig.json
```

## 关键模式

### createMainApi工厂

模板应用使用 `createMainApi(extensions)` 将核心api与自定义api结合起来：

```javascript
const { createMainApi } = require("@trops/dash-core/electron");

const api = createMainApi({
  myCustomApi: require("./myCustomApi"),
});
```

### 供应商系统

从 `AppContext.providers`， **不** `DashboardContext.providers`。这是由于组件树排序——DashboardWrapper在提供商加载之前呈现。

### 文本导入规则

总进口 `ThemeContext` 从 `@trops/dash-react` 为了避免双重上下文实例：

```javascript
// CORRECT
import { ThemeContext } from "@trops/dash-react";

// WRONG — creates separate context
import { ThemeContext } from "./Context/ThemeContext";
```

### MCP提供商生命周期

1.  小部件安装-> `useMcpProvider("slack")` 钩运行
2.  钩子从 `AppContext.providers` (与 `mcpConfig` 和凭证)
3.  调用 `dashApi.mcpStartServer()` —> ipc—> `mcpController` 生成工作室子进程
4.  服务器返回可用的工具->钩子过滤器 `allowedTools` 如果指定了
5.  小部件调用 `callTool("send_message", args)` ->每次呼叫超时30秒
6.  卸载时，钩子调用 `mcpStopServer()` 清理子进程

### ComponentManager

-   `registerContainerTypes(LayoutContainer, LayoutGridContainer)` ——auto-called on import
-   `registerWidget(config, name)` / `config(name)` 用于部件CRUD
-   `_sourcePackage` 在外部小部件配置上设置的字段 `registerBundleConfigs`
-   `loadWidgetComponents` 来丰富注册表项 `.dash.js` 元数据

### 小部件包加载

-   `widgetBundleLoader.js` 来计算CJS包 `new Function()` +需要垫片
-   **关键:** MODULE\_MAP必须包含 `@trops/dash-core` 所以外部小部件共享ComponentManager单例
-   `extractWidgetConfigs` 需要 `typeof entry.component === "function"`

### 布局系统

-   **网格路径vs非网格路径**：网格单元使用 `layout.find()` 它返回未经LayoutModel处理的原始项。
-   **LayoutModel**:刷新 `eventHandlers`/`events` 从 `ComponentManager.config()` ——在编辑模式中保持配置字段最新的关键。

## 关键文件

| 文件 | 目的 |
| --- | --- |
| `src/index.js` | 主渲染器导出+自动注册 |
| `electron/index.js` | 主电子输出 |
| `electron/api/mainApi.js` | `createMainApi(extensions)` 工厂 |
| `src/ComponentManager.js` | 挂件注册系统 |
| `src/Context/ThemeWrapper.js` | 主题提供程序（从@trops/dash-react导入ThemeContext） |
| `src/Context/DashboardWrapper.js` | 仪表板上下文+提供程序传递 |
| `src/hooks/useMcpProvider.js` | MCP服务器连接和工具调用 |
| `src/hooks/useWidgetProviders.js` | 小部件提供程序解析 |
| `src/hooks/useInstalledWidgets.js` | 合并内置和安装的小部件 |
| `src/utils/widgetBundleLoader.js` | 渲染器中的CJS包计算 |
| `src/Models/LayoutModel.js` | 布局处理，从ComponentManager中刷新事件 |
| `src/Models/ComponentConfigModel.js` | 使用默认值规范小部件配置 |
| `electron/controller/providerController.js` | 提供者CRUD +加密 |
| `electron/controller/mcpController.js` | MCP服务器spawn/stop/call |
| `electron/widgetRegistry.js` | 小部件安装/卸载持久性 |
| `electron/widgetCompiler.js` | Esbuild编译管道 |
| `electron/mcp/mcpServerCatalog.json` | MCP服务器定义 |

## 文档

看到 [文档/ INDEX.md](https://npmcn.com/package/%40trops/dash-core/docs/INDEX.md) 完整的文档索引：

-   [小部件系统](https://npmcn.com/package/%40trops/dash-core/docs/WIDGET_SYSTEM.md) -架构，自动注册，热加载
-   [Widget API](https://npmcn.com/package/%40trops/dash-core/docs/WIDGET_API.md) ——管理方法参考
-   [小部件开发](https://npmcn.com/package/%40trops/dash-core/docs/WIDGET_DEVELOPMENT.md) ——创建和测试小部件
-   [小部件注册表](https://npmcn.com/package/%40trops/dash-core/docs/WIDGET_REGISTRY.md) ——包装与配送
-   [提供者架构](https://npmcn.com/package/%40trops/dash-core/docs/PROVIDER_ARCHITECTURE.md) ——三层存储模式
-   [小部件提供程序配置](https://npmcn.com/package/%40trops/dash-core/docs/WIDGET_PROVIDER_CONFIGURATION.md) ——在小部件中配置提供者
-   [测试](https://npmcn.com/package/%40trops/dash-core/docs/TESTING.md) -提供程序和小部件测试指南
-   [产品需求](https://npmcn.com/package/%40trops/dash-core/docs/requirements/README.md) ——prd和功能规格

## 相关的包

| 包 | 目的 | 位置 |
| --- | --- | --- |
| `@trops/dash-react` | UI组件库 | [dash-react](https://github.com/trops/dash-react) |
| `dash-electron` | 电子应用模板 | [dash-electron](https://github.com/trops/dash-electron) |

## 开发

```bash
# Build both layers
npm run build

# Build renderer only
npm run build:renderer

# Build electron only
npm run build:electron

# Format code
npm run prettify
```

发布是通过GitHub动作自动推送到 `master`.

### 构建输出验证

在任何构建之后，始终验证所有三个输出文件都存在：

```bash
ls dist/index.js dist/index.esm.js dist/electron/index.js
```

退出0但产生不完整输出的构建是无声失败。

### 汇总配置

**渲染器** （`rollup.config.renderer.mjs`):

-   输入： `src/index.js`
-   输出：CJS (`dist/index.js`\+ esm (`dist/index.esm.js`）
-   外部：react， react-dom, @trops/dash-react, @ fortawsome /\*, @babel/runtime

**电子** （`rollup.config.electron.mjs`):

-   输入： `electron/index.js`
-   输出：仅CJS (`dist/electron/index.js`）
-   外部：electron， Node builgins, esbuild, @ anthropicai /sdk, @modelcontextprotocol/sdk, algoliassearch， openai等。

## 故障排除

**构建退出0，但dist文件丢失：** 无声的累积失败——检查未解析的导入或循环依赖项。

**`dist/electron/index.js` 构建后缺失：** 电子卷积配置可能悄无声息地失败。运行 `npm run build:electron` 孤独就是孤立。

**消费者应用程序在修改后崩溃：** 修复dash-core的根本原因，不要修改dash-electron作为变通办法。

**消费者中的econtext没有更新：** 验证econtext是否从 `@trops/dash-react` 无处不在。

**MCP工具没有出现在小部件中：** 检查 `AppContext.providers` (不 `DashboardContext.providers`)是来源。

## 许可证

麻省理工学院

## 常见问题

### @trops/dash-core 是什么？

Dash仪表板应用程序的核心框架

### 如何安装 @trops/dash-core？

在项目目录运行 npm install @trops/dash-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、react-dnd（^16\.0\.1）、react-dom（^18\.2\.0）、prop-types（^15\.8\.1）、tailwindcss（^3\.2\.7）、@heroicons/react（^2\.0\.16）、react-router-dom（^6\.3\.0）、@headlessui/react（1\.4）、@trops/dash-react（\>=1\.0\.83）、react-dnd-html5-backend（^16\.0\.1）、react-instantsearch-hooks-web（^6\.26\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 dash-scan-manifest，可以用 npx dash-scan-manifest 直接运行。

### @trops/dash-core 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/trops\_\_dash-core 是否存在。

### @trops/dash-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @trops/dash-core 可以商用吗？

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

### @trops/dash-core 还在维护吗？

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