@tx5dr/contracts 1.7.12 → 2.0.0

package/src/schema/plugin.schema.ts

@@ -17,6 +17,11 @@ export const PluginTypeSchema = z.enum(['strategy', 'utility']);
  */
 export type PluginType = z.infer<typeof PluginTypeSchema>;
 
+export const StrategyFeaturesSchema = z.object({
+  targetQueue: z.literal(1).optional(),
+}).optional();
+export type StrategyFeatures = z.infer<typeof StrategyFeaturesSchema>;
+
 /**
  * Runtime instance scope for a plugin.
  *
@@ -38,10 +43,16 @@ export type PluginInstanceScope = z.infer<typeof PluginInstanceScopeSchema>;
  */
 export const PluginPermissionSchema = z.enum([
   'network',
+  'plugin:event-bus',
   'host:hamlib',
+  'operator:transmit-control',
   'radio:read',
   'radio:control',
+  'radio:tuner-control',
   'radio:power',
+  'logbook:read',
+  'logbook:write',
+  'logbook:sync',
   'settings:ft8',
   'settings:decode-windows',
   'settings:realtime',
@@ -74,7 +85,17 @@ export type PluginPanelComponent = z.infer<typeof PluginPanelComponentSchema>;
  * These values control both validation expectations and default frontend
  * rendering in plugin settings UIs.
  */
-export const PluginSettingTypeSchema = z.enum(['boolean', 'number', 'string', 'string[]', 'object[]', 'keyedStringArrays', 'info']);
+export const PluginSettingTypeSchema = z.enum([
+  'boolean',
+  'number',
+  'string',
+  'string[]',
+  'object[]',
+  'keyedStringArrays',
+  'keyedObjectArrays',
+  'keyedObjects',
+  'info',
+]);
 
 /**
  * Supported generated-form field types for plugin settings.
@@ -94,6 +115,11 @@ export const PluginSettingOptionSchema = z.object({
  */
 export type PluginSettingOption = z.infer<typeof PluginSettingOptionSchema>;
 
+/**
+ * Field descriptor used for each item in an `object[]` or `keyedObjectArrays`
+ * setting editor. `key` becomes the object property; `type` controls the Host
+ * input; `required` and `default` are applied per item.
+ */
 export const PluginObjectArrayFieldSchema = z.object({
   key: z.string(),
   type: z.enum(['string', 'number', 'boolean']).optional().default('string'),
@@ -101,9 +127,14 @@ export const PluginObjectArrayFieldSchema = z.object({
   description: z.string().optional(),
   placeholder: z.string().optional(),
   required: z.boolean().optional(),
+  default: z.unknown().optional(),
 });
 export type PluginObjectArrayField = z.infer<typeof PluginObjectArrayFieldSchema>;
 
+/**
+ * Fixed key exposed by keyed setting editors. `key` is persisted in the value;
+ * `label` and `description` are literal text or plugin locale keys.
+ */
 export const PluginKeyedStringArrayKeySchema = z.object({
   key: z.string(),
   label: z.string(),
@@ -111,10 +142,18 @@ export const PluginKeyedStringArrayKeySchema = z.object({
 });
 export type PluginKeyedStringArrayKey = z.infer<typeof PluginKeyedStringArrayKeySchema>;
 
+/**
+ * Declarative condition evaluated against values in the same settings form.
+ * A leaf compares one `setting` with `equals` or `notEquals`; `allOf` requires
+ * every nested condition and `anyOf` requires at least one. Nested groups may
+ * be combined recursively.
+ */
 export interface PluginSettingCondition {
   /** Single setting key to compare. Preserves the original condition shape. */
   setting?: string;
+  /** Match when the referenced value is strictly equal to this value. */
   equals?: unknown;
+  /** Match when the referenced value is not strictly equal to this value. */
   notEquals?: unknown;
   /** All nested conditions must match. */
   allOf?: PluginSettingCondition[];
@@ -130,6 +169,7 @@ export const PluginSettingConditionSchema: z.ZodType<PluginSettingCondition> = z
   anyOf: z.array(PluginSettingConditionSchema).optional(),
 }));
 
+/** Description override selected when its condition matches. */
 export const PluginSettingConditionalDescriptionSchema = z.object({
   when: PluginSettingConditionSchema,
   description: z.string(),
@@ -156,6 +196,17 @@ export type PluginSettingScope = z.infer<typeof PluginSettingScopeSchema>;
  *
  * The host uses this schema to generate configuration forms, validate updates
  * and resolve default values before injecting them into `ctx.config`.
+ *
+ * Collection defaults must match the selected renderer:
+ * - `string[]` -> `string[]`
+ * - `object[]` -> `Array<Record<string, unknown>>` described by `itemFields`
+ * - `keyedStringArrays` -> `Record<string, string[]>`
+ * - `keyedObjectArrays` -> `Record<string, Array<Record<string, unknown>>>`
+ * - `keyedObjects` -> `Record<string, Record<string, unknown>>`
+ *
+ * Keyed editors use `keys` for their fixed outer keys; object-based editors use
+ * `itemFields` for the nested shape. `info` is display-only and cannot be used
+ * by `quickSettings`.
  */
 export const PluginSettingDescriptorSchema = z.object({
   type: PluginSettingTypeSchema,
@@ -167,7 +218,7 @@ export const PluginSettingDescriptorSchema = z.object({
   options: z.array(PluginSettingOptionSchema).optional(),
   /** Field schema used by generated editors for `object[]` settings. */
   itemFields: z.array(PluginObjectArrayFieldSchema).optional(),
-  /** Fixed key list used by generated editors for `keyedStringArrays` settings. */
+  /** Fixed key list used by generated keyed setting editors. */
   keys: z.array(PluginKeyedStringArrayKeySchema).optional(),
   /** Conditionally show the field based on another setting in the same form. */
   visibleWhen: PluginSettingConditionSchema.optional(),
@@ -231,6 +282,7 @@ export type PluginQuickSetting = z.infer<typeof PluginQuickSettingSchema>;
  * about plugin roles without hard-coding specific plugin names.
  */
 export const PluginCapabilitySchema = z.enum([
+  'auto_call_control',
   'auto_call_candidate',
   'auto_call_execution',
 ]);
@@ -354,6 +406,10 @@ export const PluginPanelDescriptorSchema = z.object({
  */
 export type PluginPanelDescriptor = z.infer<typeof PluginPanelDescriptorSchema>;
 
+/**
+ * Plugin instance that owns a runtime panel contribution: the single global
+ * instance or one explicitly identified operator instance.
+ */
 export const PluginUIPanelContributionTargetSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('global') }),
   z.object({ kind: z.literal('operator'), operatorId: z.string() }),
@@ -455,9 +511,11 @@ export type PluginStorageConfig = z.infer<typeof PluginStorageConfigSchema>;
  * host can expose to management UI and diagnostics.
  */
 export const PluginManifestSchema = z.object({
+  apiVersion: z.literal(2).optional(),
   name: z.string(),
   version: z.string(),
   type: PluginTypeSchema,
+  strategyFeatures: StrategyFeaturesSchema,
   instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
   description: z.string().optional(),
   permissions: z.array(PluginPermissionSchema).optional(),
@@ -503,6 +561,7 @@ export type PluginLocales = z.infer<typeof PluginLocalesSchema>;
 export const PluginStatusSchema = z.object({
   name: z.string(),
   type: PluginTypeSchema,
+  strategyFeatures: StrategyFeaturesSchema,
   instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
   version: z.string(),
   description: z.string().optional(),
@@ -521,6 +580,8 @@ export const PluginStatusSchema = z.object({
   panels: z.array(PluginPanelDescriptorSchema).optional(),
   permissions: z.array(PluginPermissionSchema).optional(),
   capabilities: z.array(PluginCapabilitySchema).optional(),
+  autoCallEnabledOperatorIds: z.array(z.string()).optional(),
+  pausedOperatorIds: z.array(z.string()).optional(),
   ui: PluginUIConfigSchema.optional(),
   locales: PluginLocalesSchema.optional(),
   source: PluginSourceSchema.optional(),
@@ -620,6 +681,8 @@ export const PluginMarketCatalogEntrySchema = z.object({
   name: z.string(),
   title: z.string(),
   description: z.string(),
+  readmeMarkdown: z.string().max(100 * 1024).optional(),
+  readmeSourceUrl: z.string().url().optional(),
   locales: PluginLocalesSchema.optional(),
   latestVersion: z.string(),
   minHostVersion: z.string(),
@@ -686,6 +749,8 @@ export const PluginsConfigSchema = z.object({
     z.string(),
     z.record(z.string(), z.record(z.string(), z.unknown()))
   ).optional().default({}),
+  /** 每操作员暂停的 transmit-control 插件：operatorId → pluginName[] */
+  operatorPluginPauses: z.record(z.string(), z.array(z.string())).optional().default({}),
 });
 export type PluginsConfig = z.infer<typeof PluginsConfigSchema>;
 

package/src/schema/pskreporter.schema.ts

@@ -16,9 +16,7 @@ export const PSKReporterStatsSchema = z.object({
   consecutiveFailures: z.number().default(0),
 });
 
-/**
- * PSKReporter 配置 Schema
- */
+/** PSK Reporter publishing identity, antenna metadata, interval and counters. */
 export const PSKReporterConfigSchema = z.object({
   /** 是否启用 PSKReporter 上报 */
   enabled: z.boolean().default(false),

package/src/schema/qso.schema.ts

@@ -91,6 +91,13 @@ export const QslSimpleStatusSchema = z.enum(['Y', 'N']).optional();
  * - DXCC enrichment and review metadata;
  * - LoTW / QRZ confirmation state;
  * - station-location metadata used when exporting ADIF-like records.
+ *
+ * `frequency` is the RF frequency in hertz; `startTime`/`endTime` and QSL dates
+ * are Unix epoch milliseconds. `mode` is the ADIF main mode and `submode` is the
+ * optional ADIF submode. `messageHistory` contains the raw digital-mode exchange.
+ * Sync providers update the service-specific LoTW/QRZ fields using ADIF status
+ * codes (`Y`, `N`, `R`, `Q`, `I`, and received-only `V`) rather than a generic
+ * `qslStatus` field.
  */
 export const QSORecordSchema = z.object({
   id: z.string(),

package/src/schema/radio-capability.schema.ts

@@ -36,9 +36,7 @@ export type CapabilityUpdateMode = z.infer<typeof CapabilityUpdateModeSchema>;
 export const CapabilityOptionValueSchema = z.union([z.string(), z.number()]);
 export type CapabilityOptionValue = z.infer<typeof CapabilityOptionValueSchema>;
 
-/**
- * 运行时能力值。
- */
+/** Runtime value carried by a radio capability state. */
 export const CapabilityValueSchema = z.union([z.boolean(), z.number(), z.string()]);
 export type CapabilityValue = z.infer<typeof CapabilityValueSchema>;
 
@@ -84,10 +82,7 @@ export const CapabilityDisplaySchema = z.object({
 });
 export type CapabilityDisplay = z.infer<typeof CapabilityDisplaySchema>;
 
-/**
- * 能力描述符
- * 由服务端在运行时下发，作为当前连接会话的真源。
- */
+/** Host-provided descriptor that defines one capability for the current session. */
 export const CapabilityDescriptorSchema = z.object({
   /** 全局唯一能力 ID，如 'tuner_switch', 'rf_power', 'lock_mode' */
   id: z.string(),
@@ -165,10 +160,7 @@ export const CapabilityDescriptorSchema = z.object({
 
 export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptorSchema>;
 
-/**
- * 能力运行时状态
- * 动态数据，通过 WebSocket 实时同步到前端。
- */
+/** Dynamic support, availability and value state for one capability. */
 export const CapabilityStateSchema = z.object({
   /** 能力 ID，与 CapabilityDescriptor.id 对应 */
   id: z.string(),
@@ -209,9 +201,7 @@ export const CapabilityStateSchema = z.object({
 
 export type CapabilityState = z.infer<typeof CapabilityStateSchema>;
 
-/**
- * 能力列表快照（radioCapabilityList WS 消息 / REST 响应的 data 部分）
- */
+/** Complete descriptor/state snapshot returned by radio capability APIs. */
 export const CapabilityListSchema = z.object({
   descriptors: z.array(CapabilityDescriptorSchema),
   capabilities: z.array(CapabilityStateSchema),
@@ -220,7 +210,8 @@ export const CapabilityListSchema = z.object({
 export type CapabilityList = z.infer<typeof CapabilityListSchema>;
 
 /**
- * 写命令负载（writeRadioCapability WS 命令的 data 部分）
+ * Legacy WebSocket payload for writing a generic radio capability.
+ * Plugin API v2 uses explicit radio/tuner command ports instead.
  */
 export const WriteCapabilityPayloadSchema = z.object({
   /** 能力 ID */
@@ -284,6 +275,7 @@ export const CAPABILITY_IDS = [
   'agc_mode',
   'preamp',
   'attenuator',
+  'radio_mode',
   'mode_bandwidth',
   'split_enabled',
   'vfo_select',

package/src/schema/radio-power-support.ts

@@ -111,6 +111,9 @@ export function decidePowerSupport(
       // ICOM WLAN 的 CI-V-over-UDP 通道在电台关机后无法维持；即便已连接
       // 发送 powerstat(off) 也不能可靠恢复。整体不暴露电源控制。
       return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
+    case 'tci':
+      // TCI/ExpertSDR does not expose a safe physical power-on path here.
+      return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
     case 'serial': {
       if (!rigInfo) {
         return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };

package/src/schema/radio-power.schema.ts

@@ -37,7 +37,9 @@ export const RadioPowerStageSchema = z.enum([
 export type RadioPowerStage = z.infer<typeof RadioPowerStageSchema>;
 
 /**
- * WS event payload: server → client.
+ * Last known power transition state exposed through WebSocket events and
+ * `ctx.radioPower.getState()`. `state` is the controller's high-level state;
+ * `stage` is finer progress; errors use a localized key plus diagnostic detail.
  */
 export const RadioPowerStateEventSchema = z.object({
   profileId: z.string().optional(),
@@ -51,12 +53,17 @@ export const RadioPowerStateEventSchema = z.object({
 export type RadioPowerStateEvent = z.infer<typeof RadioPowerStateEventSchema>;
 
 /**
- * REST request body: POST /api/radio/power
+ * Power targets accepted by Host commands. `on`/`off` control physical power;
+ * `standby`/`operate` switch a responding radio between controller states.
  */
-/** Allowed physical radio target states for a power request. */
 export const RadioPowerTargetSchema = z.enum(['on', 'off', 'standby', 'operate']);
 export type RadioPowerTarget = z.infer<typeof RadioPowerTargetSchema>;
 
+/**
+ * Request to transition one radio profile to a physical/controller power state.
+ * `profileId` selects the profile, `state` is the requested target, and
+ * `autoEngine` controls whether TX-5DR starts after a successful power-on.
+ */
 export const RadioPowerRequestSchema = z.object({
   profileId: z.string().min(1),
   /** Physical radio power target. This is not the TX-5DR software engine state. */
@@ -66,9 +73,7 @@ export const RadioPowerRequestSchema = z.object({
 });
 export type RadioPowerRequest = z.infer<typeof RadioPowerRequestSchema>;
 
-/**
- * REST response: POST /api/radio/power
- */
+/** Result returned by the REST endpoint and `ctx.radioPowerCommands.submit()`. */
 export const RadioPowerResponseSchema = z.object({
   success: z.boolean(),
   target: RadioPowerTargetSchema,
@@ -77,8 +82,10 @@ export const RadioPowerResponseSchema = z.object({
 export type RadioPowerResponse = z.infer<typeof RadioPowerResponseSchema>;
 
 /**
- * REST response: GET /api/radio/power/support?profileId=xxx
- * The server resolves mfgName/modelName internally via HamLib.getSupportedRigs().
+ * Power operations supported by one radio profile, returned by REST and
+ * `ctx.radioPower.getSupport()`. `reason` explains why wake is unavailable;
+ * `supportedStates` lists connected-state transitions the Host may accept.
+ * The Host resolves manufacturer/model names through Hamlib.
  */
 export const RadioPowerSupportInfoSchema = z.object({
   profileId: z.string(),

package/src/schema/radio.schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { CWKeyActiveLevelSchema } from './cw-keyer.schema.js';
 
 /**
  * 中继差频方向
@@ -10,9 +11,7 @@ export const RepeaterShiftSchema = z.enum(['none', 'minus', 'plus']);
  */
 export const ToneSquelchModeSchema = z.enum(['none', 'ctcss', 'dcs']);
 
-/**
- * 预设频率Schema
- */
+/** Saved dial-frequency preset with band, digital mode and radio modulation. */
 export const PresetFrequencySchema = z.object({
   band: z.string(),
   mode: z.string(), // 协议模式，如 FT8, FT4
@@ -192,11 +191,26 @@ export const IcomWlanConfigSchema = z.object({
   dataMode: z.boolean().optional().default(true),
 });
 
+
+/**
+ * TCI / SunSDR 连接配置Schema
+ */
+export const TciConfigSchema = z.object({
+  host: z.string().default('127.0.0.1'),
+  port: z.number().int().min(1).max(65535).default(40001),
+  receiver: z.number().int().min(0).default(0),
+  trx: z.number().int().min(0).default(0),
+  vfo: z.number().int().min(0).default(0),
+  audioEnabled: z.boolean().optional().default(true),
+  audioSampleRate: z.number().int().min(8000).max(48000).optional().default(12000),
+});
+
 /**
  * 串口连接配置Schema
  */
 export const SerialConnectionConfigSchema = z.object({
   path: z.string(),
+  serialNumber: z.string().optional(),
   rigModel: z.number().int(),
   serialConfig: SerialConfigSchema.optional(),
   backendConfig: HamlibBackendConfigSchema.optional(),
@@ -206,6 +220,15 @@ export const HamlibSpectrumConfigSchema = z.object({
   speed: z.number().int().min(0).max(255).optional(),
 });
 
+/**
+ * FT8/FT4 数字模式切换频率时的电台 CAT 模式偏好。
+ *
+ * - none: 只切换频率，不主动设置电台模式
+ * - usb: 设置普通 USB
+ * - usb-data: 设置 USB-DATA / PKTUSB 类数据模式
+ */
+export const DigitalModeRadioModePreferenceSchema = z.enum(['none', 'usb', 'usb-data']);
+
 /**
  * PTT (Push-to-Talk) 方法Schema
  *
@@ -216,6 +239,15 @@ export const HamlibSpectrumConfigSchema = z.object({
  */
 export const PttMethodSchema = z.enum(['cat', 'vox', 'dtr', 'rts']);
 
+/**
+ * 虚拟频差（Virtual Frequency Offset / "Fake It" Split）配置Schema
+ * 目标音频频率与滞回区间目前由服务端常量控制（~1500Hz），此处仅暴露开关，预留扩展位。
+ */
+export const FakeFrequencyConfigSchema = z.object({
+  enabled: z.boolean(),
+});
+export type FakeFrequencyConfig = z.infer<typeof FakeFrequencyConfigSchema>;
+
 /**
  * Hamlib配置Schema - 嵌套对象结构
  *
@@ -226,7 +258,7 @@ export const PttMethodSchema = z.enum(['cat', 'vox', 'dtr', 'rts']);
  * - 根据 type 字段读取对应的配置对象
  */
 export const HamlibConfigSchema = z.object({
-  type: z.enum(['none', 'network', 'serial', 'icom-wlan']),
+  type: z.enum(['none', 'network', 'serial', 'icom-wlan', 'tci']),
 
   // 网络模式配置
   network: NetworkConfigSchema.optional(),
@@ -234,17 +266,29 @@ export const HamlibConfigSchema = z.object({
   // ICOM WLAN 模式配置
   icomWlan: IcomWlanConfigSchema.optional(),
 
+  // TCI / SunSDR 模式配置
+  tci: TciConfigSchema.optional(),
+
   // 串口模式配置
   serial: SerialConnectionConfigSchema.optional(),
 
   // Hamlib 频谱配置（当前仅用于官方频谱流 speed）
   spectrum: HamlibSpectrumConfigSchema.optional(),
 
+  // FT8/FT4 切换频率时是否主动设置电台 CAT 模式；未设置时按 none 处理
+  digitalModeRadioMode: DigitalModeRadioModePreferenceSchema.optional(),
+
   // 发射时序补偿（毫秒）- 用于补偿电台和网络的处理延迟
   // 正值表示提前发射，负值表示延后发射
   // 范围限制：-1000~1000ms，适用于各种网络和设备延迟场景
   transmitCompensationMs: z.number().int().min(-1000).max(1000).optional(),
 
+  // 虚拟频差（Virtual Frequency Offset / WSJT-X "Fake It" Split）
+  // 启用后，发射时临时反向平移电台 dial 频率，使送进电台的音频载波保持在甜区(~1500Hz)，
+  // 而打到空中的实际 RF 位置与用户设定的发射频点完全一致。
+  // 用于规避部分电台在音频频率过高/过低时发射功率衰减的问题；对用户透明（接收 dial、TX 标记不变）。
+  fakeFrequency: FakeFrequencyConfigSchema.optional(),
+
   // PTT 方法（默认 'cat'，即 Hamlib RIG 类型）
   // 仅对 network 和 serial 连接类型有效，icom-wlan 固定使用 CI-V PTT
   pttMethod: PttMethodSchema.optional(),
@@ -258,6 +302,9 @@ export const HamlibConfigSchema = z.object({
 
   // CW 键控引脚类型（dtr 或 rts）
   cwKeyMethod: z.enum(['dtr', 'rts']).optional(),
+
+  // CW 键控有效电平（默认 high，即高电平按下；部分接口为低电平按下）
+  cwKeyActiveLevel: CWKeyActiveLevelSchema.optional(),
 });
 
 /**
@@ -303,7 +350,7 @@ export const RadioInfoSchema = z.object({
   /** Hamlib 电台型号 ID (serial/network 模式使用，icom-wlan 模式可选) */
   rigModel: z.number().optional(),
   /** 连接类型 */
-  connectionType: z.enum(['serial', 'network', 'icom-wlan']),
+  connectionType: z.enum(['serial', 'network', 'icom-wlan', 'tci']),
   /** 固件版本 (如果可获取) */
   firmwareVersion: z.string().optional(),
   /** 序列号 (如果可获取) */
@@ -315,6 +362,7 @@ export const RadioInfoSchema = z.object({
  */
 export const SerialPortSchema = z.object({
   path: z.string(),
+  friendlyName: z.string().optional(),
   manufacturer: z.string().optional(),
   serialNumber: z.string().optional(),
   pnpId: z.string().optional(),
@@ -461,8 +509,10 @@ export type HamlibConfigFieldType = z.infer<typeof HamlibConfigFieldTypeSchema>;
 export type HamlibConfigField = z.infer<typeof HamlibConfigFieldSchema>;
 export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
 export type IcomWlanConfig = z.infer<typeof IcomWlanConfigSchema>;
+export type TciConfig = z.infer<typeof TciConfigSchema>;
 export type SerialConnectionConfig = z.infer<typeof SerialConnectionConfigSchema>;
 export type HamlibSpectrumConfig = z.infer<typeof HamlibSpectrumConfigSchema>;
+export type DigitalModeRadioModePreference = z.infer<typeof DigitalModeRadioModePreferenceSchema>;
 export type PttMethod = z.infer<typeof PttMethodSchema>;
 export type HamlibConfig = z.infer<typeof HamlibConfigSchema>;
 export type RadioConfigResponse = z.infer<typeof RadioConfigResponseSchema>;

package/src/schema/realtime.schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export const RealtimeScopeSchema = z.enum(['radio', 'openwebrx-preview']);
 export type RealtimeScope = z.infer<typeof RealtimeScopeSchema>;
 
-export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat']);
+export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat', 'android-native']);
 export type RealtimeTransportKind = z.infer<typeof RealtimeTransportKindSchema>;
 
 export const RealtimeSessionDirectionSchema = z.enum(['recv', 'send']);
@@ -307,6 +307,13 @@ export const RealtimeSessionResponseSchema = z.object({
 
 export type RealtimeSessionResponse = z.infer<typeof RealtimeSessionResponseSchema>;
 
+/**
+ * Persisted realtime-audio transport preferences.
+ *
+ * `transportPolicy` selects automatic or explicit transport behavior. The
+ * optional public host/UDP port advertise an RTC data-audio endpoint to remote
+ * clients; null/omitted values disable that public candidate.
+ */
 export const RealtimeSettingsSchema = z.object({
   transportPolicy: RealtimeTransportPolicySchema.optional(),
   rtcDataAudioPublicHost: RtcDataAudioPublicHostSchema.optional(),
@@ -333,6 +340,7 @@ export const RealtimeSettingsRuntimeSchema = z.object({
 
 export type RealtimeSettingsRuntime = z.infer<typeof RealtimeSettingsRuntimeSchema>;
 
+/** Realtime settings plus the Host's current resolved runtime projection. */
 export const RealtimeSettingsResponseDataSchema = RealtimeSettingsSchema.extend({
   runtime: RealtimeSettingsRuntimeSchema.optional(),
 });

package/src/schema/slot-info.schema.ts

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { DxccStatusSchema, SubdivisionConfidenceSchema } from './qso.schema.js';
 
+/** Number of non-empty slot packs retained for live FT8/FT4 message history. */
+export const SLOT_PACK_HISTORY_LIMIT = 1000;
+
 /**
  * Frequency context captured when a slot pack is created.
  * Fields are optional so older persisted slot packs remain valid.
@@ -16,11 +19,12 @@ export const SlotPackFrequencyContextSchema = z.object({
 export type SlotPackFrequencyContext = z.infer<typeof SlotPackFrequencyContextSchema>;
 
 /**
- * 时隙周期（偶数奇数）
- */
-
-/**
- * 时隙信息
+ * Timing and identity of one FT8/FT4 receive or transmit slot.
+ *
+ * `startMs` is the calibrated Unix epoch start in milliseconds; `phaseMs` is
+ * elapsed time inside the slot; `driftMs` is the clock correction; `cycleNumber`
+ * is the absolute slot index (use modulo two for even/odd); and `utcSeconds` is
+ * the integer epoch-second form used for display and logs.
  */
 export const SlotInfoSchema = z.object({
   /** 时隙唯一标识符 */
@@ -41,9 +45,7 @@ export const SlotInfoSchema = z.object({
 
 export type SlotInfo = z.infer<typeof SlotInfoSchema>;
 
-/**
- * 基于日志本的消息分析结果
- */
+/** Logbook-derived enrichment attached to a decoded message when available. */
 export const LogbookAnalysisSchema = z.object({
   /** 是否为新呼号（之前没有通联过） */
   isNewCallsign: z.boolean().optional(),
@@ -76,7 +78,9 @@ export const LogbookAnalysisSchema = z.object({
 export type LogbookAnalysis = z.infer<typeof LogbookAnalysisSchema>;
 
 /**
- * FT8 帧数据
+ * Original decoder frame with RF metrics and unparsed message text.
+ * `snr` is dB, `freq` is audio offset in hertz, `dt` is seconds, and
+ * `confidence` is normalized to 0..1.
  */
 export const FrameMessageSchema = z.object({
   /** 信号强度 (dB) */
@@ -157,7 +161,9 @@ export const DecodeResultSchema = z.object({
 export type DecodeResult = z.infer<typeof DecodeResultSchema>;
 
 /**
- * 时隙封装信息（去重和多次解码取优）
+ * Deduplicated best-frame collection for one slot, including decode statistics,
+ * history and the dial-frequency context captured when the slot began.
+ * `startMs`, `endMs` and history timestamps use Unix epoch milliseconds.
  */
 export const SlotPackSchema = z.object({
   /** 时隙ID */

package/src/schema/station-info.schema.ts

@@ -16,6 +16,11 @@ export const StationQthSchema = z.object({
   longitude: z.number().min(-180).max(180).optional(),
 });
 
+/**
+ * Public station profile shown to clients and exposed through plugin settings.
+ * It contains optional display identity, callsign, Markdown description and QTH
+ * coordinates/grid; it never contains authentication or radio credentials.
+ */
 export const StationInfoSchema = z.object({
   /** Station display name, e.g. "BG7XXX Remote Station" */
   name: z.string().max(100).optional(),

package/src/schema/system.schema.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { RemoteAccessPresetSchema } from './auth.schema.js';
+import { PluginDistributionSchema } from './plugin.schema.js';
 
 // ===== 网络信息 =====
 
@@ -13,10 +15,35 @@ export const NetworkInfoSchema = z.object({
   addresses: z.array(NetworkAddressSchema),
   hostname: z.string(),
   webPort: z.number(),
+  exposure: RemoteAccessPresetSchema.default('lan'),
+  listenHost: z.string().default('0.0.0.0'),
+  runtimeManagement: z.enum(['electron', 'external']).default('external'),
+  distribution: PluginDistributionSchema.default('generic-server'),
+  supportsLocalOnly: z.boolean().default(false),
+  supportedPresets: z.array(RemoteAccessPresetSchema).min(1).default(['lan', 'public']),
+  activeConnections: z.number().int().nonnegative().default(0),
+  maxConnections: z.number().int().positive().default(32),
 });
 
 export type NetworkInfo = z.infer<typeof NetworkInfoSchema>;
 
+// ===== 日志设置 =====
+
+export const SystemLogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+export type SystemLogLevel = z.infer<typeof SystemLogLevelSchema>;
+
+export const SystemLoggingSettingsSchema = z.object({
+  level: SystemLogLevelSchema.optional(),
+  effectiveLevel: SystemLogLevelSchema,
+  logsDir: z.string(),
+});
+export type SystemLoggingSettings = z.infer<typeof SystemLoggingSettingsSchema>;
+
+export const UpdateSystemLoggingSettingsSchema = z.object({
+  level: SystemLogLevelSchema,
+});
+export type UpdateSystemLoggingSettingsRequest = z.infer<typeof UpdateSystemLoggingSettingsSchema>;
+
 // ===== 时钟状态 =====
 
 export const ClockSyncStateSchema = z.enum(['synced', 'stale', 'never', 'failed']);
@@ -115,12 +142,14 @@ const NtpServerArraySchema = z.array(NtpServerHostSchema).min(1).superRefine((se
   }
 });
 
+/** Active NTP server list together with the Host-provided default list. */
 export const NtpServerListSettingsSchema = z.object({
   servers: NtpServerArraySchema,
   defaultServers: NtpServerArraySchema,
 });
 export type NtpServerListSettings = z.infer<typeof NtpServerListSettingsSchema>;
 
+/** Complete replacement list accepted by `ctx.settings.ntp.update()`. */
 export const UpdateNtpServerListRequestSchema = z.object({
   servers: NtpServerArraySchema,
 });