Hype Dash

Hype Dash

](https://www.npmjs.com/package/@hypelab/hype-dash) ](https://www.npmjs.com/package/@hypelab/hype-dash)   ](https://github.com/hypelab/hype-dash/stargazers) ](https://github.com/hypelab/hype-dash/issues) ](https://nodejs.org) ](https://bundlephobia.com/package/@hypelab/hype-dash)  

生产就绪的TypeScript SDK，用于通过REST API创建和管理Lark/Feishu仪表板，并支持模型上下文协议（MCP）服务器。

特性

• 类型安全：完全支持TypeScript，具有全面的类型定义
• 流利的API：用于创建仪表板块的直观构建器模式
• 7块类型：图表、指标、视图、文本、列表、标签页和过滤器
• MCP服务器：通过模型上下文协议集成本地Claude代码
• 生产就绪：错误处理、重试、日志记录和验证
• 批量操作：一次有效地创建多个块
• 2025仪表板功能：Lark仪表板的最新功能
• 开发包：用于Lark Base数据管理的全面Python SDK

安装

Types/JavaScript

npm install @hypelab/hype-dash

python

cd python
pip install -r requirements.txt

看 Python SDK文档 了解详细的设置和使用方法。

快速开始

基本用法

import { LarkDashboardClient, ChartBlockBuilder, AggregationType } from '@hypelab/hype-dash';

const client = new LarkDashboardClient({
  apiKey: process.env.LARK_API_KEY!,
  region: 'sg', // 'sg' | 'cn' | 'us'
  logging: true,
});

// Create a dashboard
const dashboardId = await client.createDashboard({
  name: 'Sales Dashboard',
  appToken: 'YOUR_APP_TOKEN',
});

// Add a bar chart
const chartBlock = ChartBlockBuilder.bar()
  .dataSource('YOUR_APP_TOKEN', 'YOUR_TABLE_ID')
  .xAxis({ fieldName: 'Category' })
  .yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
  .title('Revenue by Category')
  .colors(['#3b82f6', '#10b981', '#f59e0b'])
  .build();

await client.addBlock('YOUR_APP_TOKEN', dashboardId, chartBlock);

可用块类型

1.图表块

import { ChartBlockBuilder, ChartType, AggregationType } from '@hypelab/hype-dash';

// Bar Chart
const barChart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .xAxis({ fieldName: 'Month' })
  .yAxis([
    { fieldName: 'Sales', aggregation: AggregationType.SUM, label: 'Total Sales' },
    { fieldName: 'Orders', aggregation: AggregationType.COUNT, label: 'Order Count' }
  ])
  .title('Monthly Sales Performance')
  .showLegend(true)
  .build();

// Line Chart
const lineChart = ChartBlockBuilder.line()
  .dataSource(appToken, tableId)
  .xAxis({ fieldName: 'Date' })
  .yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
  .build();

// Pie Chart
const pieChart = ChartBlockBuilder.pie()
  .dataSource(appToken, tableId)
  .series({ fieldName: 'Category' })
  .yAxis([{ fieldName: 'Amount', aggregation: AggregationType.SUM }])
  .build();

2.指标块

import { MetricsBlockBuilder, AggregationType } from '@hypelab/hype-dash';

const metrics = new MetricsBlockBuilder()
  .dataSource(appToken, tableId)
  .fieldName('Revenue')
  .aggregation(AggregationType.SUM)
  .title('Total Revenue')
  .prefix('$')
  .decimals(2)
  .trendComparison(30, 'days')
  .build();

3.视图块

import { ViewBlockBuilder, ViewType } from '@hypelab/hype-dash';

const tableView = ViewBlockBuilder.table()
  .dataSource(appToken, tableId, viewId)
  .title('Customer List')
  .showToolbar(true)
  .height(400)
  .build();

const kanbanView = ViewBlockBuilder.kanban()
  .dataSource(appToken, tableId, viewId)
  .build();

4.文本块

import { TextBlockBuilder } from '@hypelab/hype-dash';

const heading = new TextBlockBuilder()
  .heading('Dashboard Overview')
  .alignment('center')
  .build();

const paragraph = new TextBlockBuilder()
  .paragraph('Welcome to the sales dashboard.')
  .build();

MCP服务器使用情况

SDK包括一个用于Claude Code集成的模型上下文协议服务器。

设置

添加到您的 ~/.claude.json 或克劳德代码配置：

{
  "mcpServers": {
    "hype-dash": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hypelab/hype-dash"],
      "env": {
        "LARK_API_KEY": "your-api-key-here",
        "LARK_REGION": "sg"
      }
    }
  }
}

可用的MCP工具

• create_dashboard -创建新仪表板
• create_chart_block -添加图表可视化
• create_metrics_block -添加KPI指标
• create_view_block -添加表格/看板视图
• create_text_block -添加文本内容
• list_dashboards -列出所有仪表板
• delete_dashboard -删除仪表板

使用Claude代码

Create a sales dashboard with:
- Bar chart showing revenue by month
- KPI card for total revenue
- Table view of recent orders

Claude将使用MCP工具自动创建仪表板。

开发包

该项目包括一个用于管理Lark Base数据的全面Python SDK。这使您能够：

• 同步外部数据：从TikTok广告、数据库、API等导入数据。
• 批量操作：高效创建/更新数千条记录
• 数据转换：加载前转换和验证数据
• 自动仪表板更新：仪表板自动反映数据更改

快速示例

from lark_client import LarkBaseClient, LarkConfig
from data_manager import DataManager

# Initialize client
config = LarkConfig(
    app_id=os.getenv('LARK_APP_ID'),
    app_secret=os.getenv('LARK_APP_SECRET')
)
client = LarkBaseClient(config)
data_manager = DataManager(client)

# Sync TikTok campaign data
tiktok_data = fetch_tiktok_campaigns()  # Your data source
result = data_manager.batch_upsert_records(
    app_token='YOUR_APP_TOKEN',
    table_id='YOUR_TABLE_ID',
    records=tiktok_data,
    key_field='campaign_id'
)

print(f"Synced {result['total']} campaigns")
# Your dashboards now show updated data automatically!

Python SDK功能

• 表、字段和记录的完整CRUD操作
• 具有自动分页功能的批处理操作
• 数据验证和转换实用程序
• 带有时间戳跟踪的增量同步
• 外部数据源的现场映射
• 速率限制和错误处理
• 综合录井

看 Python SDK文档 完整的指南。

工作流程：Python+TypeScript

1. python：管理数据（创建表、同步外部源、批量更新）
2. TypeScript：创建漂亮的仪表板来可视化数据
3. 自动：数据更改时仪表板会自动更新

# 1. Python: Sync data
data_manager.batch_upsert_records(...)

// 2. TypeScript: Create dashboard
const chart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .build();

配置

客户端选项

const client = new LarkDashboardClient({
  apiKey: string;          // Required: Lark API key
  region?: 'sg' | 'cn' | 'us';  // Default: 'sg'
  apiUrl?: string;         // Optional: Custom API URL
  logging?: boolean;       // Default: false
  timeout?: number;        // Default: 30000ms
  maxRetries?: number;     // Default: 3
  retryDelay?: number;     // Default: 1000ms
});

环境变量

LARK_API_KEY=your-api-key
LARK_REGION=sg
LARK_LOGGING=true

高级功能

批量操作

const blocks = [
  ChartBlockBuilder.bar().dataSource(appToken, tableId).build(),
  MetricsBlockBuilder.sum('Revenue').dataSource(appToken, tableId).build(),
  ViewBlockBuilder.table().dataSource(appToken, tableId, viewId).build(),
];

const results = await client.batchCreateBlocks(appToken, blocks);

过滤

import { FilterOperator, FilterConjunction } from '@hypelab/hype-dash';

const chart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .filters(FilterConjunction.AND, [
    { fieldName: 'Status', operator: FilterOperator.IS, value: 'Active' },
    { fieldName: 'Revenue', operator: FilterOperator.GT, value: 1000 }
  ])
  .build();

错误处理

import { ValidationError } from '@hypelab/hype-dash';

try {
  await client.addBlock(appToken, dashboardId, block);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else {
    console.error('API error:', error);
  }
}

api参考

大型仪表板客户端

• createDashboard(dashboard: Dashboard): Promise
• addBlock(appToken: string, dashboardId: string, block: DashboardBlock): Promise
• updateBlock(appToken: string, blockId: string, block: Partial): Promise
• deleteBlock(appToken: string, blockId: string): Promise
• listBlocks(appToken: string): Promise
• batchCreateBlocks(appToken: string, blocks: DashboardBlock[]): Promise

生成器

• ChartBlockBuilder -创建图表可视化
• MetricsBlockBuilder -创建KPI指标
• ViewBlockBuilder -创建数据视图
• TextBlockBuilder -创建文本块
• ListBlockBuilder -创建列表块（2025）
• TabPageBlockBuilder -创建标签页（2025）

例子

请参阅 /examples 完整示例目录：

• basic-dashboard.ts -简单的仪表板创建
• complete-dashboard.ts -功能齐全的仪表板
• multi-source-dashboard.ts -多个数据源
• realtime-dashboard.ts -实时数据更新

TypeScript支持

SDK是用TypeScript编写的，提供了全面的类型定义：

import type {
  DashboardBlock,
  ChartConfig,
  MetricsConfig,
  ViewConfig,
  ChartType,
  ViewType,
  AggregationType,
} from '@hypelab/hype-dash';

需求

Types/JavaScript

• Node.js>=16.0.0
• TypeScript>=5.0.0（适用于TypeScript项目）

python

• Python>=3.8
• 看 python/requirements.txt 对于依赖关系

故障排除

常见问题

身份验证错误

• 验证LAR_API_KEY是否正确
• 检查Lark管理控制台中的API密钥权限
• 确保区域与您的Lark工作区匹配（“sg”、“cn”或“us”）

网络错误

• 检查防火墙设置
• 验证Lark API的网络连接
• 尝试在客户端配置中增加超时时间

验证错误

• 确保提供必填字段
• 检查数据类型是否符合API预期
• 验证Lark表中是否存在字段名

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• GitHub问题：https://github.com/hypelab/hype-dash/issues
• 电子邮件：dev@hypelab.com

更新日志

看 更改日志.md 查看版本历史和更新。