@tx5dr/contracts 1.2.0

package/src/schema/plugin.schema.ts

@@ -0,0 +1,503 @@
+import { z } from 'zod';
+
+// ===== 核心枚举 =====
+
+/**
+ * High-level plugin category.
+ *
+ * - `strategy`: owns the operator's automation runtime and is mutually
+ *   exclusive per operator.
+ * - `utility`: composes with other utility plugins to filter, score, monitor or
+ *   augment UI.
+ */
+export const PluginTypeSchema = z.enum(['strategy', 'utility']);
+
+/**
+ * High-level plugin category used by manifests and runtime status objects.
+ */
+export type PluginType = z.infer<typeof PluginTypeSchema>;
+
+/**
+ * Runtime instance scope for a plugin.
+ *
+ * - `operator`: the host creates one instance per operator.
+ * - `global`: the host creates a single shared instance for the whole station.
+ */
+export const PluginInstanceScopeSchema = z.enum(['operator', 'global']);
+
+/**
+ * Runtime instance scope for a plugin.
+ */
+export type PluginInstanceScope = z.infer<typeof PluginInstanceScopeSchema>;
+
+/**
+ * Explicit permission declarations requested by a plugin.
+ *
+ * Permissions let the host gate sensitive capabilities behind manifest-level
+ * intent. Plugins should request the smallest possible set.
+ */
+export const PluginPermissionSchema = z.enum(['network']);
+
+/**
+ * Explicit permission declarations requested by a plugin.
+ */
+export type PluginPermission = z.infer<typeof PluginPermissionSchema>;
+
+/**
+ * Built-in frontend renderer kinds supported by declarative plugin panels.
+ */
+export const PluginPanelComponentSchema = z.enum(['table', 'key-value', 'chart', 'log', 'iframe']);
+
+/**
+ * Built-in frontend renderer kinds supported by declarative plugin panels.
+ */
+export type PluginPanelComponent = z.infer<typeof PluginPanelComponentSchema>;
+
+// ===== 设置声明 =====
+
+/**
+ * Supported generated-form field types for plugin settings.
+ *
+ * These values control both validation expectations and default frontend
+ * rendering in plugin settings UIs.
+ */
+export const PluginSettingTypeSchema = z.enum(['boolean', 'number', 'string', 'string[]', 'info']);
+
+/**
+ * Supported generated-form field types for plugin settings.
+ */
+export type PluginSettingType = z.infer<typeof PluginSettingTypeSchema>;
+
+/**
+ * Label/value pair used by select-like plugin settings.
+ */
+export const PluginSettingOptionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+
+/**
+ * Label/value pair used by select-like plugin settings.
+ */
+export type PluginSettingOption = z.infer<typeof PluginSettingOptionSchema>;
+
+/**
+ * Persistence and UI scope for a plugin setting.
+ *
+ * - `global`: shared by the whole station and typically edited in plugin
+ *   management views.
+ * - `operator`: isolated per operator and typically edited in operator-specific
+ *   automation settings.
+ */
+export const PluginSettingScopeSchema = z.enum(['global', 'operator']);
+
+/**
+ * Persistence and UI scope for a plugin setting.
+ */
+export type PluginSettingScope = z.infer<typeof PluginSettingScopeSchema>;
+
+/**
+ * Declarative description of a persisted plugin setting.
+ *
+ * The host uses this schema to generate configuration forms, validate updates
+ * and resolve default values before injecting them into `ctx.config`.
+ */
+export const PluginSettingDescriptorSchema = z.object({
+  type: PluginSettingTypeSchema,
+  default: z.unknown(),
+  label: z.string(),
+  description: z.string().optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  options: z.array(PluginSettingOptionSchema).optional(),
+  /** 设置作用域：global（所有操作员共享）或 operator（每操作员独立），默认 global */
+  scope: PluginSettingScopeSchema.optional().default('global'),
+});
+
+/**
+ * Declarative description of a persisted plugin setting.
+ *
+ * `default` is the resolved fallback value, `label`/`description` power the UI,
+ * `min` and `max` constrain numeric fields, `options` enumerates valid choices
+ * for select-like inputs, and `scope` controls whether the value is shared or
+ * operator-specific.
+ */
+export type PluginSettingDescriptor = z.infer<typeof PluginSettingDescriptorSchema>;
+
+// ===== 快捷操作 =====
+
+/**
+ * Declarative quick-action button shown in operator-facing plugin UI.
+ *
+ * Quick actions are intended for one-shot commands and are dispatched through
+ * the plugin user-action channel when clicked.
+ */
+export const PluginQuickActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  icon: z.string().optional(),
+});
+
+/**
+ * Declarative quick-action button shown in operator-facing plugin UI.
+ */
+export type PluginQuickAction = z.infer<typeof PluginQuickActionSchema>;
+
+/**
+ * Shortcut reference to an operator-scope setting that should be surfaced in a
+ * compact quick-settings panel.
+ */
+export const PluginQuickSettingSchema = z.object({
+  settingKey: z.string(),
+});
+
+/**
+ * Shortcut reference to an operator-scope setting that should be surfaced in a
+ * compact quick-settings panel.
+ */
+export type PluginQuickSetting = z.infer<typeof PluginQuickSettingSchema>;
+
+// ===== 能力标签 =====
+
+/**
+ * Host-derived capability tags exposed to the frontend.
+ *
+ * These tags are computed from the plugin definition so the UI can reason
+ * about plugin roles without hard-coding specific plugin names.
+ */
+export const PluginCapabilitySchema = z.enum([
+  'auto_call_candidate',
+  'auto_call_execution',
+]);
+
+/**
+ * Host-derived capability tags exposed to the frontend.
+ */
+export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
+
+// ===== 面板 =====
+
+/**
+ * Rendering slot that determines where a panel appears in the UI.
+ *
+ * - `operator`: shown in the expanded operator card's live-panel area (default).
+ * - `automation`: shown inside the top-right automation quick-action popover.
+ */
+export const PluginPanelSlotSchema = z.enum(['operator', 'automation']);
+
+/**
+ * Rendering slot that determines where a panel appears in the UI.
+ */
+export type PluginPanelSlot = z.infer<typeof PluginPanelSlotSchema>;
+
+/**
+ * Preferred width hint for plugin-owned panels.
+ *
+ * Hosts may interpret this hint differently per slot. Today the operator-card
+ * host treats `full` as "span the full row on desktop", while automation
+ * popover hosts may choose to ignore it.
+ */
+export const PluginPanelWidthSchema = z.enum(['half', 'full']);
+
+/**
+ * Preferred width hint for plugin-owned panels.
+ */
+export type PluginPanelWidth = z.infer<typeof PluginPanelWidthSchema>;
+
+/**
+ * Declarative definition of a plugin-owned panel in the frontend.
+ *
+ * Panels are passive containers rendered by the host. A plugin sends data into
+ * them through `ctx.ui.send(panelId, data)`. When `component` is `'iframe'`,
+ * the panel renders a custom UI page inside a sandboxed iframe instead.
+ */
+export const PluginPanelDescriptorSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  component: PluginPanelComponentSchema,
+  /** Required when `component` is `'iframe'`. References a page id from `ui.pages`. */
+  pageId: z.string().optional(),
+  /** Where the panel renders. Defaults to `'operator'` (operator card live-panel area). */
+  slot: PluginPanelSlotSchema.optional(),
+  /** Preferred width hint. Defaults to `'half'`. */
+  width: PluginPanelWidthSchema.optional(),
+});
+
+/**
+ * Declarative definition of a plugin-owned panel in the frontend.
+ */
+export type PluginPanelDescriptor = z.infer<typeof PluginPanelDescriptorSchema>;
+
+// ===== 自定义 UI 页面 =====
+
+/**
+ * Declarative descriptor for a custom UI page served from a plugin's static
+ * file directory and rendered inside an iframe by the host.
+ *
+ * Pages are registered in `PluginDefinition.ui.pages` and can be consumed by
+ * any host component via `<PluginIframeHost pluginName={...} pageId={...} />`.
+ */
+export const PluginUIPageDescriptorSchema = z.object({
+  /** Unique page identifier within the plugin (e.g. 'settings', 'dashboard'). */
+  id: z.string(),
+  /** Display title (i18n key or literal text). */
+  title: z.string(),
+  /** Entry HTML file path relative to the UI directory (e.g. 'settings.html'). */
+  entry: z.string(),
+  /** Optional icon identifier. */
+  icon: z.string().optional(),
+  /** Who may access this page through the host iframe bridge. Defaults to admin. */
+  accessScope: z.enum(['admin', 'operator']).optional().default('admin'),
+  /** Optional resource binding enforced by the host for iframe invoke requests. */
+  resourceBinding: z.enum(['none', 'callsign', 'operator']).optional().default('none'),
+});
+
+/**
+ * Declarative descriptor for a custom UI page served from a plugin's static
+ * file directory.
+ */
+export type PluginUIPageDescriptor = z.infer<typeof PluginUIPageDescriptorSchema>;
+
+/**
+ * Declares that a plugin provides custom UI pages hosted in an iframe.
+ */
+export const PluginUIConfigSchema = z.object({
+  /** Static file directory relative to the plugin root (default: 'ui'). */
+  dir: z.string().optional().default('ui'),
+  /** Registered custom UI pages. */
+  pages: z.array(PluginUIPageDescriptorSchema).optional().default([]),
+});
+
+/**
+ * Declares that a plugin provides custom UI pages hosted in an iframe.
+ */
+export type PluginUIConfig = z.infer<typeof PluginUIConfigSchema>;
+
+// ===== 存储配置 =====
+
+/**
+ * Storage scope requested by a plugin.
+ */
+export const PluginStorageScopeSchema = z.enum(['global', 'operator']);
+
+/**
+ * Storage scope requested by a plugin.
+ */
+export type PluginStorageScope = z.infer<typeof PluginStorageScopeSchema>;
+
+/**
+ * Declares which persistent storage scopes the host should provision.
+ */
+export const PluginStorageConfigSchema = z.object({
+  scopes: z.array(PluginStorageScopeSchema),
+});
+
+/**
+ * Declares which persistent storage scopes the host should provision.
+ */
+export type PluginStorageConfig = z.infer<typeof PluginStorageConfigSchema>;
+
+// ===== 插件清单 =====
+
+/**
+ * Normalized manifest describing a plugin's static metadata and declarations.
+ *
+ * This is effectively the serializable subset of a plugin definition that the
+ * host can expose to management UI and diagnostics.
+ */
+export const PluginManifestSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  type: PluginTypeSchema,
+  instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
+  description: z.string().optional(),
+  permissions: z.array(PluginPermissionSchema).optional(),
+  settings: z.record(z.string(), PluginSettingDescriptorSchema).optional(),
+  quickActions: z.array(PluginQuickActionSchema).optional(),
+  quickSettings: z.array(PluginQuickSettingSchema).optional(),
+  panels: z.array(PluginPanelDescriptorSchema).optional(),
+  storage: PluginStorageConfigSchema.optional(),
+  ui: PluginUIConfigSchema.optional(),
+});
+
+/**
+ * Normalized manifest describing a plugin's static metadata and declarations.
+ */
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;
+
+// ===== 运行时状态（推送给前端） =====
+
+/**
+ * Runtime-facing plugin status snapshot exposed to the frontend.
+ *
+ * This extends the static manifest with host state such as whether the plugin
+ * is loaded, enabled, auto-disabled or currently assigned to operators.
+ */
+export const PluginStatusSchema = z.object({
+  name: z.string(),
+  type: PluginTypeSchema,
+  instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
+  version: z.string(),
+  description: z.string().optional(),
+  isBuiltIn: z.boolean(),
+  loaded: z.boolean().default(true),
+  enabled: z.boolean(),
+  /** 是否被自动禁用（连续错误达到阈值） */
+  autoDisabled: z.boolean().optional().default(false),
+  errorCount: z.number(),
+  lastError: z.string().optional(),
+  /** 仅对 strategy 插件有意义：当前被哪些 operator 选中 */
+  assignedOperatorIds: z.array(z.string()).optional(),
+  settings: z.record(z.string(), PluginSettingDescriptorSchema).optional(),
+  quickActions: z.array(PluginQuickActionSchema).optional(),
+  quickSettings: z.array(PluginQuickSettingSchema).optional(),
+  panels: z.array(PluginPanelDescriptorSchema).optional(),
+  permissions: z.array(PluginPermissionSchema).optional(),
+  capabilities: z.array(PluginCapabilitySchema).optional(),
+  ui: PluginUIConfigSchema.optional(),
+  locales: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+});
+
+/**
+ * Runtime-facing plugin status snapshot exposed to the frontend.
+ */
+export type PluginStatus = z.infer<typeof PluginStatusSchema>;
+
+export const PluginSystemStateSchema = z.enum(['ready', 'reloading', 'error']);
+export type PluginSystemState = z.infer<typeof PluginSystemStateSchema>;
+
+export const PluginSystemSnapshotSchema = z.object({
+  state: PluginSystemStateSchema,
+  generation: z.number().int().nonnegative(),
+  plugins: z.array(PluginStatusSchema),
+  lastError: z.string().optional(),
+});
+export type PluginSystemSnapshot = z.infer<typeof PluginSystemSnapshotSchema>;
+
+// ===== 插件宿主运行时信息 =====
+
+export const PluginDistributionSchema = z.enum([
+  'electron',
+  'docker',
+  'linux-service',
+  'generic-server',
+  'web-dev',
+]);
+export type PluginDistribution = z.infer<typeof PluginDistributionSchema>;
+
+export const PluginRuntimeInfoSchema = z.object({
+  pluginDir: z.string(),
+  pluginDataDir: z.string(),
+  dataDir: z.string(),
+  configDir: z.string(),
+  logsDir: z.string(),
+  cacheDir: z.string(),
+  distribution: PluginDistributionSchema,
+  hostPluginDirHint: z.string().optional(),
+});
+export type PluginRuntimeInfo = z.infer<typeof PluginRuntimeInfoSchema>;
+
+// ===== 持久化配置（存入 config.json） =====
+
+/**
+ * 单个插件的持久化配置
+ */
+export const PluginConfigEntrySchema = z.object({
+  enabled: z.boolean(),
+  settings: z.record(z.string(), z.unknown()),
+});
+export type PluginConfigEntry = z.infer<typeof PluginConfigEntrySchema>;
+
+/**
+ * 所有插件的持久化配置
+ */
+export const PluginsConfigSchema = z.object({
+  /** 全局插件配置（enabled 状态 + global scope settings） */
+  configs: z.record(z.string(), PluginConfigEntrySchema).optional().default({}),
+  /** 每操作员的策略插件选择 */
+  operatorStrategies: z.record(z.string(), z.string()).optional().default({}),
+  /** 每操作员的 operator scope plugin settings：operatorId → pluginName → settings */
+  operatorSettings: z.record(
+    z.string(),
+    z.record(z.string(), z.record(z.string(), z.unknown()))
+  ).optional().default({}),
+});
+export type PluginsConfig = z.infer<typeof PluginsConfigSchema>;
+
+// ===== WebSocket 数据载荷 =====
+
+/**
+ * 插件数据推送载荷（ctx.ui.send() 发送到前端）
+ */
+export const PluginDataPayloadSchema = z.object({
+  pluginName: z.string(),
+  operatorId: z.string(),
+  panelId: z.string(),
+  data: z.unknown(),
+});
+export type PluginDataPayload = z.infer<typeof PluginDataPayloadSchema>;
+
+/**
+ * 插件日志条目
+ */
+export const PluginLogEntrySchema = z.object({
+  pluginName: z.string(),
+  level: z.enum(['debug', 'info', 'warn', 'error']),
+  message: z.string(),
+  data: z.unknown().optional(),
+  timestamp: z.number(),
+});
+export type PluginLogEntry = z.infer<typeof PluginLogEntrySchema>;
+
+export const PluginRuntimeLogStageSchema = z.enum([
+  'scan',
+  'load',
+  'validate',
+  'reload',
+  'activate',
+]);
+export type PluginRuntimeLogStage = z.infer<typeof PluginRuntimeLogStageSchema>;
+
+/**
+ * 宿主级插件运行日志条目
+ */
+export const PluginRuntimeLogEntrySchema = z.object({
+  source: z.literal('system'),
+  stage: PluginRuntimeLogStageSchema,
+  level: z.enum(['debug', 'info', 'warn', 'error']),
+  message: z.string(),
+  timestamp: z.number(),
+  pluginName: z.string().optional(),
+  directoryName: z.string().optional(),
+  details: z.unknown().optional(),
+});
+export type PluginRuntimeLogEntry = z.infer<typeof PluginRuntimeLogEntrySchema>;
+
+/**
+ * 宿主级插件运行日志历史响应载荷
+ */
+export const PluginRuntimeLogHistoryPayloadSchema = z.object({
+  entries: z.array(PluginRuntimeLogEntrySchema),
+});
+export type PluginRuntimeLogHistoryPayload = z.infer<typeof PluginRuntimeLogHistoryPayloadSchema>;
+
+/**
+ * 插件用户操作载荷（前端 → 后端）
+ */
+export const PluginUserActionPayloadSchema = z.object({
+  pluginName: z.string(),
+  actionId: z.string(),
+  operatorId: z.string().optional(),
+  payload: z.unknown().optional(),
+});
+export type PluginUserActionPayload = z.infer<typeof PluginUserActionPayloadSchema>;
+
+/**
+ * 操作员维度的插件设置更新载荷
+ */
+export const PluginOperatorSettingsPayloadSchema = z.object({
+  pluginName: z.string(),
+  operatorId: z.string(),
+  settings: z.record(z.string(), z.unknown()),
+});
+export type PluginOperatorSettingsPayload = z.infer<typeof PluginOperatorSettingsPayloadSchema>;

package/src/schema/process-monitor.schema.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+export const ProcessMemorySchema = z.object({
+  heapUsed: z.number(),
+  heapTotal: z.number(),
+  rss: z.number(),
+  external: z.number(),
+  arrayBuffers: z.number(),
+});
+
+export const ProcessCpuSchema = z.object({
+  user: z.number(),
+  system: z.number(),
+  total: z.number(),
+});
+
+export const EventLoopDelaySchema = z.object({
+  mean: z.number(),
+  p50: z.number(),
+  p99: z.number(),
+});
+
+export const ProcessSnapshotSchema = z.object({
+  timestamp: z.number(),
+  uptimeSeconds: z.number(),
+  memory: ProcessMemorySchema,
+  cpu: ProcessCpuSchema,
+  eventLoop: EventLoopDelaySchema,
+});
+
+export const ProcessSnapshotHistorySchema = z.object({
+  snapshots: z.array(ProcessSnapshotSchema),
+  intervalMs: z.number(),
+  maxHistory: z.number(),
+});
+
+export type ProcessMemory = z.infer<typeof ProcessMemorySchema>;
+export type ProcessCpu = z.infer<typeof ProcessCpuSchema>;
+export type EventLoopDelay = z.infer<typeof EventLoopDelaySchema>;
+export type ProcessSnapshot = z.infer<typeof ProcessSnapshotSchema>;
+export type ProcessSnapshotHistory = z.infer<typeof ProcessSnapshotHistorySchema>;

package/src/schema/pskreporter.schema.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+
+/**
+ * PSKReporter 统计信息 Schema
+ */
+export const PSKReporterStatsSchema = z.object({
+  /** 最后成功上报时间 (Unix毫秒) */
+  lastReportTime: z.number().optional(),
+  /** 今日上报数量 */
+  todayReportCount: z.number().default(0),
+  /** 总上报数量 */
+  totalReportCount: z.number().default(0),
+  /** 最后错误信息 */
+  lastError: z.string().optional(),
+  /** 连续失败次数 */
+  consecutiveFailures: z.number().default(0),
+});
+
+/**
+ * PSKReporter 配置 Schema
+ */
+export const PSKReporterConfigSchema = z.object({
+  /** 是否启用 PSKReporter 上报 */
+  enabled: z.boolean().default(false),
+
+  /** 接收电台呼号 (可选，留空时使用第一个操作员的呼号) */
+  receiverCallsign: z.string().default(''),
+
+  /** 接收电台网格 (可选，留空时使用第一个操作员的网格) */
+  receiverLocator: z.string().default(''),
+
+  /** 解码软件名称 (自动填充) */
+  decodingSoftware: z.string().default('TX-5DR'),
+
+  /** 天线信息 (可选，会显示在 PSKReporter 地图上) */
+  antennaInformation: z.string().max(64, '天线信息不能超过64字符').default(''),
+
+  /** 上报间隔（秒），最小10秒，最大60秒，默认30秒 */
+  reportIntervalSeconds: z.number().min(10).max(60).default(30),
+
+  /** 是否使用测试服务器（仅用于开发调试） */
+  useTestServer: z.boolean().default(false),
+
+  /** 上报统计 */
+  stats: PSKReporterStatsSchema.default({}),
+});
+
+/**
+ * PSKReporter 上报记录 Schema (用于收集待上报数据)
+ */
+export const PSKReporterSpotSchema = z.object({
+  /** 发送电台呼号 (必填) */
+  senderCallsign: z.string(),
+
+  /** 频率 (Hz，可选) */
+  frequency: z.number().optional(),
+
+  /** 模式 (FT8, FT4 等) */
+  mode: z.string(),
+
+  /** 信噪比 (可选) */
+  snr: z.number().optional(),
+
+  /** 接收时间戳 (Unix 秒) */
+  flowStartSeconds: z.number(),
+
+  /** 发送电台网格 (可选，从消息中解析) */
+  senderLocator: z.string().optional(),
+
+  /** 信息源 (1 = automatic) */
+  informationSource: z.number().default(1),
+});
+
+/**
+ * PSKReporter 上报状态 Schema
+ */
+export const PSKReporterStatusSchema = z.object({
+  /** 是否已启用 */
+  enabled: z.boolean(),
+  /** 是否配置有效 */
+  configValid: z.boolean(),
+  /** 当前使用的呼号 */
+  activeCallsign: z.string().optional(),
+  /** 当前使用的网格 */
+  activeLocator: z.string().optional(),
+  /** 待上报记录数 */
+  pendingSpots: z.number(),
+  /** 最后上报时间 (Unix毫秒) */
+  lastReportTime: z.number().optional(),
+  /** 距离下次上报秒数 */
+  nextReportIn: z.number().optional(),
+  /** 是否正在上报 */
+  isReporting: z.boolean(),
+  /** 最后错误 */
+  lastError: z.string().optional(),
+});
+
+// 类型导出
+export type PSKReporterStats = z.infer<typeof PSKReporterStatsSchema>;
+export type PSKReporterConfig = z.infer<typeof PSKReporterConfigSchema>;
+export type PSKReporterSpot = z.infer<typeof PSKReporterSpotSchema>;
+export type PSKReporterStatus = z.infer<typeof PSKReporterStatusSchema>;