@trops / dash-core

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

安装

npm install @trops/dash-core

同行依赖性:

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

两种导出路径

渲染器(反应)

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

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处理程序、事件和小部件管道。

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框架。

电子层(electron/）

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

目录结构

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结合起来：

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

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

供应商系统

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

文本导入规则

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

// 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() ——在编辑模式中保持配置字段最新的关键。

关键文件

文档

看到 文档/ INDEX.md 完整的文档索引：

• 小部件系统 -架构，自动注册，热加载
• Widget API ——管理方法参考
• 小部件开发 ——创建和测试小部件
• 小部件注册表 ——包装与配送
• 提供者架构 ——三层存储模式
• 小部件提供程序配置 ——在小部件中配置提供者
• 测试 -提供程序和小部件测试指南
• 产品需求 ——prd和功能规格

相关的包

开发

# 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.

构建输出验证

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

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)是来源。

许可证

麻省理工学院