@tx5dr/contracts 2.0.0 → 2.5.0

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

@@ -0,0 +1,342 @@
+import { z } from 'zod';
+
+export const ImageFamilySchema = z.enum(['sstv', 'fax']);
+export type ImageFamily = z.infer<typeof ImageFamilySchema>;
+
+export const ImagePixelFormatSchema = z.enum(['rgb8', 'gray8']);
+export type ImagePixelFormat = z.infer<typeof ImagePixelFormatSchema>;
+
+export const ImageSstvReceiveProfileSchema = z.discriminatedUnion('strategy', [
+  z.object({ family: z.literal('sstv'), strategy: z.literal('auto') }),
+  z.object({ family: z.literal('sstv'), strategy: z.literal('manual'), mode: z.string().min(1) }),
+]);
+export type ImageSstvReceiveProfile = z.infer<typeof ImageSstvReceiveProfileSchema>;
+
+export const ImageFaxReceiveProfileSchema = z.discriminatedUnion('strategy', [
+  z.object({ family: z.literal('fax'), strategy: z.literal('auto') }),
+  z.object({
+    family: z.literal('fax'), strategy: z.literal('manual'),
+    ioc: z.enum(['ioc288', 'ioc576']), lpm: z.number().int().positive(),
+    modulation: z.enum(['fm', 'am']), centerHz: z.number().positive(),
+    deviationHz: z.number().positive(),
+  }),
+]);
+export type ImageFaxReceiveProfile = z.infer<typeof ImageFaxReceiveProfileSchema>;
+
+export const ImageReceiveProfileSchema = z.union([
+  ImageSstvReceiveProfileSchema,
+  ImageFaxReceiveProfileSchema,
+]);
+export type ImageReceiveProfile = z.infer<typeof ImageReceiveProfileSchema>;
+
+export const ImageSstvModeInfoSchema = z.object({
+  mode: z.string(), name: z.string(), visCode: z.number().int().nonnegative(),
+  width: z.number().int().positive(), height: z.number().int().positive(),
+  colorLayout: z.enum(['monochrome', 'rgb', 'yuv']),
+  scanLayout: z.enum(['monochrome', 'martin', 'scottie', 'robot', 'pd', 'wraase', 'pasokon']),
+  lineSeconds: z.number().positive(), rowsPerLine: z.number().int().positive(),
+  status: z.enum(['canonical', 'compatibility']),
+});
+export type ImageSstvModeInfo = z.infer<typeof ImageSstvModeInfoSchema>;
+
+export const ImageRadioCapabilitySchema = z.object({
+  available: z.boolean(),
+  reason: z.string().optional(),
+  sstv: z.object({ rx: z.literal(true), tx: z.literal(true) }),
+  fax: z.object({ rx: z.literal(true), tx: z.literal(false) }),
+});
+export type ImageRadioCapability = z.infer<typeof ImageRadioCapabilitySchema>;
+
+export const ImageRadioServiceStateSchema = z.enum(['stopped', 'starting', 'ready', 'degraded', 'unavailable']);
+export const ImageRxStateSchema = z.enum(['off', 'searching', 'acquiring', 'receiving', 'completed', 'aborted', 'error']);
+export const SstvTxPhaseSchema = z.enum([
+  'idle', 'preparing', 'waiting_for_lease', 'keying', 'on_air', 'draining',
+  'completed', 'cancelled', 'error', 'ptt_unknown',
+]);
+export const SstvStationIdModeSchema = z.enum(['fsk', 'cw', 'none']);
+export type SstvStationIdMode = z.infer<typeof SstvStationIdModeSchema>;
+export const SstvTxEnvelopeSelectionSchema = z.object({
+  enhancedPreamble: z.boolean().default(true),
+  stationIdMode: SstvStationIdModeSchema.default('fsk'),
+});
+export type SstvTxEnvelopeSelection = z.infer<typeof SstvTxEnvelopeSelectionSchema>;
+export const SstvTxEnvelopeSnapshotSchema = SstvTxEnvelopeSelectionSchema.extend({
+  callsign: z.string().optional(),
+  postImageGapMs: z.literal(500),
+  endGuardMs: z.literal(300),
+  cwWpm: z.literal(20),
+  cwToneHz: z.literal(800),
+});
+export type SstvTxEnvelopeSnapshot = z.infer<typeof SstvTxEnvelopeSnapshotSchema>;
+export const SstvTxPreferencesSchema = SstvTxEnvelopeSelectionSchema.extend({
+  operatorId: z.string().min(1),
+  updatedAt: z.number(),
+});
+export type SstvTxPreferences = z.infer<typeof SstvTxPreferencesSchema>;
+
+export const ImageSessionSummarySchema = z.object({
+  sessionId: z.string(),
+  family: ImageFamilySchema,
+  generation: z.number().int().nonnegative(),
+  revision: z.number().int().nonnegative(),
+  codecMode: z.string().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  receivedLines: z.number().int().nonnegative().default(0),
+  firstAvailableLine: z.number().int().nonnegative().default(0),
+  startedAt: z.number(),
+});
+export type ImageSessionSummary = z.infer<typeof ImageSessionSummarySchema>;
+
+export const SstvTxStatusSchema = z.object({
+  phase: SstvTxPhaseSchema,
+  sessionId: z.string().optional(),
+  requestId: z.string().optional(),
+  operatorId: z.string().optional(),
+  artifactId: z.string().optional(),
+  historyId: z.string().optional(),
+  mode: z.string().optional(),
+  encoderStage: z.enum(['preamble', 'vis', 'raster', 'stationId', 'guard', 'finished']).optional(),
+  envelope: SstvTxEnvelopeSnapshotSchema.optional(),
+  revision: z.number().int().nonnegative().default(0),
+  samplesEmitted: z.number().int().nonnegative().default(0),
+  estimatedTotalSamples: z.number().int().nonnegative().default(0),
+  currentRow: z.number().int().nonnegative().optional(),
+  startedAt: z.number().optional(),
+  errorCode: z.string().optional(),
+});
+export type SstvTxStatus = z.infer<typeof SstvTxStatusSchema>;
+
+export const ImageRadioStatusSchema = z.object({
+  serviceState: ImageRadioServiceStateSchema,
+  family: ImageFamilySchema.nullable(),
+  receiveProfile: ImageReceiveProfileSchema.nullable(),
+  rxState: ImageRxStateSchema,
+  rxCaptureActive: z.boolean().default(false),
+  capability: ImageRadioCapabilitySchema,
+  currentSession: ImageSessionSummarySchema.nullable(),
+  tx: SstvTxStatusSchema,
+  nativeQueuedSamples: z.number().int().nonnegative().default(0),
+  jsBacklogSamples: z.number().int().nonnegative().default(0),
+  discontinuities: z.number().int().nonnegative().default(0),
+  updatedAt: z.number(),
+});
+export type ImageRadioStatus = z.infer<typeof ImageRadioStatusSchema>;
+
+export const ImageRowPatchSchema = z.object({
+  rowIndex: z.number().int().nonnegative(),
+  width: z.number().int().positive(),
+  rowRevision: z.number().int().nonnegative(),
+  completeness: z.enum(['provisional', 'final']).optional(),
+  dataBase64: z.string(),
+});
+
+export const ImagePaperBoundaryKindSchema = z.enum([
+  'initial', 'vis', 'syncTiming', 'aptPhasing', 'protocolEnd',
+  'manualMode', 'discontinuity', 'reset', 'truncated', 'protocolObserved',
+  'localTxStart', 'localTxEnd',
+]);
+export type ImagePaperBoundaryKind = z.infer<typeof ImagePaperBoundaryKindSchema>;
+export const ImagePaperSourceSchema = z.enum(['rx', 'localTx']);
+export type ImagePaperSource = z.infer<typeof ImagePaperSourceSchema>;
+
+export const ImagePaperBoundarySchema = z.object({
+  boundaryId: z.string(), lineIndex: z.number().int().nonnegative(),
+  kind: ImagePaperBoundaryKindSchema, trusted: z.boolean(),
+  codecMode: z.string(), width: z.number().int().positive(),
+  pixelFormat: ImagePixelFormatSchema, timestamp: z.number(),
+  detection: z.string().optional(), nominalHeight: z.number().int().positive().optional(),
+  source: ImagePaperSourceSchema.optional(),
+  txSessionId: z.string().optional(),
+  txOutcome: z.enum(['completed', 'interrupted']).optional(),
+});
+export type ImagePaperBoundary = z.infer<typeof ImagePaperBoundarySchema>;
+
+export const ImageFaxCalibrationPointSchema = z.object({
+  revision: z.number().int().nonnegative(),
+  referenceLine: z.number().int().nonnegative(),
+  phasePixels: z.number().finite(),
+  clockPpm: z.number().finite(),
+  confidence: z.number().min(0).max(1),
+  source: z.enum(['nominal', 'phasing', 'imageContent', 'manual']),
+  status: z.enum(['nominal', 'acquiring', 'locked', 'tracking', 'degraded']),
+});
+export type ImageFaxCalibrationPoint = z.infer<typeof ImageFaxCalibrationPointSchema>;
+
+export const ImageFaxCalibrationSchema = z.object({
+  boundaryId: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+  autoEnabled: z.boolean(),
+  autoPoints: z.array(ImageFaxCalibrationPointSchema).max(256),
+  manualPhasePixels: z.number().finite(),
+  manualClockPpm: z.number().finite(),
+  updatedAt: z.number(),
+});
+export type ImageFaxCalibration = z.infer<typeof ImageFaxCalibrationSchema>;
+
+export const ImageRxEventSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('paperStarted'), session: ImageSessionSummarySchema, pixelFormat: ImagePixelFormatSchema }),
+  z.object({ type: z.literal('boundary'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), boundary: ImagePaperBoundarySchema }),
+  z.object({ type: z.literal('faxCalibration'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), calibration: ImageFaxCalibrationSchema }),
+  z.object({ type: z.literal('signalDetected'), family: ImageFamilySchema, confidence: z.number().min(0).max(1), candidates: z.array(z.string()), timestamp: z.number() }),
+  z.object({ type: z.literal('imageStarted'), session: ImageSessionSummarySchema, pixelFormat: ImagePixelFormatSchema, detection: z.string().optional(), confidence: z.number().min(0).max(1).optional() }),
+  z.object({ type: z.literal('rows'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), pixelFormat: ImagePixelFormatSchema, rows: z.array(ImageRowPatchSchema).min(1).max(8) }),
+  z.object({ type: z.literal('imageCompleted'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), artifactId: z.string(), previewUrl: z.string(), partial: z.boolean() }),
+  z.object({ type: z.literal('imageAborted'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), reason: z.string(), lastRow: z.number().int().nonnegative().optional(), temporary: z.boolean() }),
+  z.object({ type: z.literal('snapshotRequired'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), snapshotUrl: z.string() }),
+  z.object({ type: z.literal('captureSaved'), sessionId: z.string(), generation: z.number().int().nonnegative(), revision: z.number().int().nonnegative(), artifactId: z.string(), previewUrl: z.string(), saveReason: z.enum(['manual', 'protocolEnd']), complete: z.boolean(), startLine: z.number().int().nonnegative(), endLine: z.number().int().positive() }),
+]);
+export type ImageRxEvent = z.infer<typeof ImageRxEventSchema>;
+
+export const ImageArtifactSchema = z.object({
+  id: z.string(),
+  family: ImageFamilySchema,
+  direction: z.enum(['rx', 'tx']),
+  operatorId: z.string().optional(),
+  codecMode: z.string(),
+  pixelFormat: ImagePixelFormatSchema,
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  frequency: z.number().positive(),
+  radioMode: z.string().optional(),
+  complete: z.boolean(),
+  saveReason: z.enum(['manual', 'protocolEnd']).optional(),
+  captureStartedAt: z.number().optional(),
+  captureEndedAt: z.number().optional(),
+  truncated: z.boolean().default(false),
+  pinned: z.boolean().default(false),
+  qsoId: z.string().optional(),
+  contentHash: z.string(),
+  createdAt: z.number(),
+  imageUrl: z.string(),
+  faxCalibration: ImageFaxCalibrationSchema.optional(),
+});
+export type ImageArtifact = z.infer<typeof ImageArtifactSchema>;
+
+const ImageHistoryRecordBaseSchema = z.object({
+  id: z.string(),
+  artifactId: z.string(),
+  family: ImageFamilySchema,
+  operatorId: z.string().optional(),
+  occurredAt: z.number(),
+  qsoId: z.string().optional(),
+});
+
+export const ImageHistoryRecordSchema = z.discriminatedUnion('direction', [
+  ImageHistoryRecordBaseSchema.extend({
+    direction: z.literal('rx'),
+    saveReason: z.enum(['manual', 'protocolEnd']),
+    complete: z.boolean(),
+    truncated: z.boolean().default(false),
+  }),
+  ImageHistoryRecordBaseSchema.extend({
+    direction: z.literal('tx'),
+    operatorId: z.string().min(1),
+    sessionId: z.string().min(1),
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    outcome: z.enum(['transmitting', 'completed', 'interrupted']),
+    errorCode: z.string().optional(),
+    envelope: SstvTxEnvelopeSnapshotSchema.optional(),
+    sampleRate: z.number().int().positive().optional(),
+    estimatedTotalSamples: z.number().int().nonnegative().optional(),
+  }),
+]);
+export type ImageHistoryRecord = z.infer<typeof ImageHistoryRecordSchema>;
+
+export const ImageHistoryEntrySchema = z.object({
+  record: ImageHistoryRecordSchema,
+  artifact: ImageArtifactSchema,
+});
+export type ImageHistoryEntry = z.infer<typeof ImageHistoryEntrySchema>;
+
+export const ImageTemplateTextLayerSchema = z.object({
+  id: z.string().min(1).max(64),
+  text: z.string().max(256),
+  x: z.number().min(-2).max(2),
+  y: z.number().min(-2).max(2),
+  width: z.number().positive().max(4),
+  height: z.number().positive().max(4),
+  fontSize: z.number().positive().max(1),
+  color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+  strokeColor: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+  strokeWidth: z.number().min(0).max(0.5).default(0.12),
+  align: z.enum(['left', 'center', 'right']).default('center'),
+  rotation: z.number().min(-180).max(180).default(0),
+});
+export type ImageTemplateTextLayer = z.infer<typeof ImageTemplateTextLayerSchema>;
+
+export const ImageTemplateSchema = z.object({
+  id: z.string(),
+  operatorId: z.string().optional(),
+  name: z.string().min(1).max(80),
+  builtIn: z.boolean().default(false),
+  backgroundArtifactId: z.string().optional(),
+  layers: z.array(ImageTemplateTextLayerSchema).max(16),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+export type ImageTemplate = z.infer<typeof ImageTemplateSchema>;
+
+export const ImageComposerBackgroundSchema = z.object({
+  operatorId: z.string().min(1),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  updatedAt: z.number(),
+  imageUrl: z.string(),
+});
+export type ImageComposerBackground = z.infer<typeof ImageComposerBackgroundSchema>;
+
+export const ImageRxSubscriptionSchema = z.object({ enabled: z.boolean() });
+export const SstvTxStartCommandSchema = z.object({
+  requestId: z.string().min(1).max(128),
+  operatorId: z.string().min(1),
+  artifactId: z.string().min(1),
+  mode: z.string().min(1),
+  expectedFrequency: z.number().positive(),
+  interruptActiveCapture: z.boolean().optional(),
+  envelope: SstvTxEnvelopeSelectionSchema.default({ enhancedPreamble: true, stationIdMode: 'fsk' }),
+});
+export type SstvTxStartCommand = z.infer<typeof SstvTxStartCommandSchema>;
+export const SstvTxCancelCommandSchema = z.object({
+  requestId: z.string().min(1).max(128),
+  operatorId: z.string().min(1),
+  sessionId: z.string().min(1),
+  expectedRevision: z.number().int().nonnegative(),
+});
+export type SstvTxCancelCommand = z.infer<typeof SstvTxCancelCommandSchema>;
+export const SstvTxCommandResultSchema = z.object({
+  requestId: z.string(),
+  accepted: z.boolean(),
+  sessionId: z.string().optional(),
+  errorCode: z.string().optional(),
+});
+export type SstvTxCommandResult = z.infer<typeof SstvTxCommandResultSchema>;
+
+export const ImagePaperSaveCommandSchema = z.object({
+  requestId: z.string().min(1).max(128),
+  operatorId: z.string().min(1),
+  expectedRevision: z.number().int().nonnegative(),
+});
+export type ImagePaperSaveCommand = z.infer<typeof ImagePaperSaveCommandSchema>;
+
+const FaxCalibrationCommandBaseSchema = z.object({
+  requestId: z.string().min(1).max(128),
+  operatorId: z.string().min(1),
+  sessionId: z.string().min(1),
+  boundaryId: z.string().min(1),
+  expectedRevision: z.number().int().nonnegative(),
+});
+export const FaxCalibrationSetCommandSchema = FaxCalibrationCommandBaseSchema.extend({
+  autoEnabled: z.boolean(),
+  phasePixels: z.number().finite(),
+  clockPpm: z.number().finite().min(-5000).max(5000),
+});
+export type FaxCalibrationSetCommand = z.infer<typeof FaxCalibrationSetCommandSchema>;
+export const FaxCalibrationResetCommandSchema = FaxCalibrationCommandBaseSchema;
+export type FaxCalibrationResetCommand = z.infer<typeof FaxCalibrationResetCommandSchema>;
+export const FaxCalibrationCommandResultSchema = z.object({
+  requestId: z.string(), accepted: z.boolean(),
+  calibration: ImageFaxCalibrationSchema.optional(), errorCode: z.string().optional(),
+});
+export type FaxCalibrationCommandResult = z.infer<typeof FaxCalibrationCommandResultSchema>;

package/src/schema/logbook.schema.ts

@@ -12,6 +12,7 @@ export const LOGBOOK_OPERATION_ERROR_CODES = [
   'LOGBOOK_BACKUP_UNAVAILABLE',
   'LOGBOOK_BACKUP_CHANGED',
   'LOGBOOK_MAINTENANCE',
+  'LOGBOOK_REVISION_CONFLICT',
   'LOGBOOK_REVISION_MISMATCH',
   'LOGBOOK_RESTORE_PRECONDITION_FAILED',
   'LOGBOOK_PRECONDITION_REQUIRED',

package/src/schema/mode.schema.ts

@@ -69,6 +69,22 @@ export const MODES = {
     transmitTiming: 0,
     encodeAdvance: 0,
   } as ModeDescriptor,
+  SSTV: {
+    name: 'SSTV',
+    slotMs: 0,
+    toleranceMs: 0,
+    windowTiming: [],
+    transmitTiming: 0,
+    encodeAdvance: 0,
+  } as ModeDescriptor,
+  FAX: {
+    name: 'FAX',
+    slotMs: 0,
+    toleranceMs: 0,
+    windowTiming: [],
+    transmitTiming: 0,
+    encodeAdvance: 0,
+  } as ModeDescriptor,
 } as const;
 
 /**

package/src/schema/operator.schema.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ModeDescriptorSchema } from './mode.schema.js';
 import { sanitizeCallsignInput } from '../utils/callsign.js';
 import { sanitizeGridInput } from '../utils/grid.js';
+import { StrategyRuntimeSnapshotSchema } from './websocket.schema.js';
 
 const OperatorCallsignSchema = z
   .string()
@@ -20,6 +21,7 @@ export const RadioOperatorConfigSchema = z.object({
   myCallsign: OperatorCallsignSchema,
   myGrid: OperatorGridSchema.optional(),
   frequency: z.number().min(0).max(1000000000, '频率必须在0-1GHz之间').default(1000), // 音频偏移频率（Hz），默认1000Hz，创建时自动分配不重复值
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
   transmitCycles: z.array(z.number().min(0).max(1)).default([0]), // 0=偶数周期，1=奇数周期
   mode: ModeDescriptorSchema.optional(),
   logBookId: z.string().optional(), // 连接的日志本ID，如果未指定则使用默认日志本
@@ -67,6 +69,7 @@ export const RadioOperatorStatusResponseSchema = z.object({
     context: z.object({
       myCall: z.string(),
       myGrid: z.string(),
+      targetCalls: z.array(z.string()).optional(),
       targetCall: z.string(),
       targetGrid: z.string().optional(),
       frequency: z.number().optional(),
@@ -78,25 +81,7 @@ export const RadioOperatorStatusResponseSchema = z.object({
       state: z.string(),
       availableSlots: z.array(z.string()),
     }),
-    runtime: z.object({
-      currentState: z.string(),
-      slots: z.object({
-        TX1: z.string().optional(),
-        TX2: z.string().optional(),
-        TX3: z.string().optional(),
-        TX4: z.string().optional(),
-        TX5: z.string().optional(),
-        TX6: z.string().optional(),
-      }).optional(),
-      context: z.object({
-        targetCallsign: z.string().optional(),
-        targetGrid: z.string().optional(),
-        reportSent: z.number().optional(),
-        reportReceived: z.number().optional(),
-        actualFrequency: z.number().optional(),
-      }).optional(),
-      availableSlots: z.array(z.string()).optional(),
-    }).optional(),
+    runtime: StrategyRuntimeSnapshotSchema.optional(),
     slots: z.object({
       TX1: z.string().optional(),
       TX2: z.string().optional(),

package/src/schema/plugin.schema.ts

@@ -19,6 +19,11 @@ export type PluginType = z.infer<typeof PluginTypeSchema>;
 
 export const StrategyFeaturesSchema = z.object({
   targetQueue: z.literal(1).optional(),
+  parallelTargetQueue: z.literal(1).optional(),
+  queueActivation: z.enum(['immediate', 'operator-toggle']).optional(),
+  manualInitiation: z.literal(1).optional(),
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
+  maxSimultaneousSignals: z.number().int().min(1).max(5).optional(),
 }).optional();
 export type StrategyFeatures = z.infer<typeof StrategyFeaturesSchema>;
 
@@ -52,6 +57,7 @@ export const PluginPermissionSchema = z.enum([
   'radio:power',
   'logbook:read',
   'logbook:write',
+  'logbook:session',
   'logbook:sync',
   'settings:ft8',
   'settings:decode-windows',
@@ -299,6 +305,7 @@ export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
  *
  * - `operator`: shown in the expanded operator card's live-panel area (default).
  * - `automation`: shown inside the top-right automation quick-action popover.
+ * - `operator-action`: shown beside the built-in logbook action on an operator card.
  * - `main-right`: shown in the optional main layout plugin pane on the far right.
  * - `voice-left-top`: shown above the voice frequency control card.
  * - `voice-right-top`: shown in the tabbed top area of the voice right panel.
@@ -308,6 +315,7 @@ export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
 export const PluginPanelSlotSchema = z.enum([
   'operator',
   'automation',
+  'operator-action',
   'main-right',
   'voice-left-top',
   'voice-right-top',
@@ -336,12 +344,15 @@ export const PluginPanelWidthSchema = z.enum(['half', 'full']);
 export type PluginPanelWidth = z.infer<typeof PluginPanelWidthSchema>;
 
 /**
- * How an iframe panel is opened when rendered as a toolbar entry.
+ * How an iframe panel is opened when rendered as an action entry.
+ *
+ * `page` opens the referenced custom UI in the host's standalone plugin-page
+ * route instead of embedding it in the radio workspace.
  */
-export const PluginPanelOpenModeSchema = z.enum(['popover', 'modal']);
+export const PluginPanelOpenModeSchema = z.enum(['popover', 'modal', 'page']);
 
 /**
- * How an iframe panel is opened when rendered as a toolbar entry.
+ * How an iframe panel is opened when rendered as an action entry.
  */
 export type PluginPanelOpenMode = z.infer<typeof PluginPanelOpenModeSchema>;
 
@@ -382,21 +393,28 @@ export const PluginPanelDescriptorSchema = z.object({
   /** Optional controlled UI size hint for toolbar popovers/modals. */
   uiSize: PluginPanelUISizeSchema.optional(),
 }).superRefine((panel, ctx) => {
-  if (panel.slot !== 'radio-control-toolbar') {
+  if (panel.slot !== 'radio-control-toolbar' && panel.slot !== 'operator-action') {
     return;
   }
   if (panel.component !== 'iframe') {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       path: ['component'],
-      message: 'radio-control-toolbar panels must use iframe component',
+      message: `${panel.slot} panels must use iframe component`,
     });
   }
   if (!panel.pageId) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       path: ['pageId'],
-      message: 'radio-control-toolbar panels must declare pageId',
+      message: `${panel.slot} panels must declare pageId`,
+    });
+  }
+  if (panel.slot === 'operator-action' && panel.openMode !== 'page') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['openMode'],
+      message: 'operator-action panels must use page openMode',
     });
   }
 });
@@ -504,6 +522,11 @@ export type PluginStorageConfig = z.infer<typeof PluginStorageConfigSchema>;
 
 // ===== 插件清单 =====
 
+const SemanticVersionSchema = z.string().regex(
+  /^v?(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/,
+  'must be a semantic version',
+);
+
 /**
  * Normalized manifest describing a plugin's static metadata and declarations.
  *
@@ -514,6 +537,7 @@ export const PluginManifestSchema = z.object({
   apiVersion: z.literal(2).optional(),
   name: z.string(),
   version: z.string(),
+  minPluginApiVersion: SemanticVersionSchema.optional(),
   type: PluginTypeSchema,
   strategyFeatures: StrategyFeaturesSchema,
   instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
@@ -647,6 +671,8 @@ export const PluginDistributionSchema = z.enum([
 export type PluginDistribution = z.infer<typeof PluginDistributionSchema>;
 
 export const PluginRuntimeInfoSchema = z.object({
+  hostVersion: z.string(),
+  pluginApiVersion: SemanticVersionSchema,
   pluginDir: z.string(),
   pluginDataDir: z.string(),
   dataDir: z.string(),
@@ -677,7 +703,7 @@ export const PluginMarketScreenshotSchema = z.object({
 });
 export type PluginMarketScreenshot = z.infer<typeof PluginMarketScreenshotSchema>;
 
-export const PluginMarketCatalogEntrySchema = z.object({
+const PluginMarketCatalogEntryInputSchema = z.object({
   name: z.string(),
   title: z.string(),
   description: z.string(),
@@ -685,7 +711,9 @@ export const PluginMarketCatalogEntrySchema = z.object({
   readmeSourceUrl: z.string().url().optional(),
   locales: PluginLocalesSchema.optional(),
   latestVersion: z.string(),
-  minHostVersion: z.string(),
+  minPluginApiVersion: SemanticVersionSchema.optional(),
+  /** Catalog schema v1 compatibility alias; normalized on read. */
+  minHostVersion: SemanticVersionSchema.optional(),
   author: z.string().optional(),
   license: z.string().optional(),
   repository: z.string().url().optional(),
@@ -698,15 +726,93 @@ export const PluginMarketCatalogEntrySchema = z.object({
   sha256: z.string().regex(/^[a-f0-9]{64}$/i),
   size: z.number().int().nonnegative(),
   publishedAt: z.string(),
+  artifactManifestVersion: z.literal(1).optional(),
+}).superRefine((value, context) => {
+  if (!value.minPluginApiVersion && !value.minHostVersion) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['minPluginApiVersion'],
+      message: 'minPluginApiVersion is required',
+    });
+  }
+  if (value.minPluginApiVersion && value.minHostVersion
+      && value.minPluginApiVersion !== value.minHostVersion) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['minPluginApiVersion'],
+      message: 'minPluginApiVersion conflicts with legacy minHostVersion',
+    });
+  }
+});
+
+export const PluginMarketCatalogEntrySchema = PluginMarketCatalogEntryInputSchema.transform((value) => {
+  const { minHostVersion: _legacyMinimum, ...entry } = value;
+  return {
+    ...entry,
+    minPluginApiVersion: value.minPluginApiVersion ?? value.minHostVersion!,
+  };
 });
 export type PluginMarketCatalogEntry = z.infer<typeof PluginMarketCatalogEntrySchema>;
 
-export const PluginMarketCatalogSchema = z.object({
-  schemaVersion: z.number().int().positive(),
-  generatedAt: z.string(),
-  channel: PluginMarketChannelSchema,
-  plugins: z.array(PluginMarketCatalogEntrySchema),
+const PluginMarketCatalogV2EntrySchema = PluginMarketCatalogEntryInputSchema.superRefine(
+  (value, context) => {
+    if (!value.minPluginApiVersion) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['minPluginApiVersion'],
+        message: 'catalog schema v2 requires minPluginApiVersion',
+      });
+    }
+    if (value.minHostVersion) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['minHostVersion'],
+        message: 'catalog schema v2 does not support legacy minHostVersion',
+      });
+    }
+    if (value.artifactManifestVersion !== 1) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['artifactManifestVersion'],
+        message: 'catalog schema v2 requires artifactManifestVersion 1',
+      });
+    }
+  },
+).transform((value) => {
+  const { minHostVersion: _legacyMinimum, ...entry } = value;
+  return {
+    ...entry,
+    minPluginApiVersion: value.minPluginApiVersion!,
+  };
+});
+
+export const PluginArtifactManifestSchema = z.object({
+  schemaVersion: z.literal(1),
+  name: z.string(),
+  version: z.string(),
+  minPluginApiVersion: SemanticVersionSchema,
+  apiVersion: z.literal(2).optional(),
+  type: PluginTypeSchema,
+  instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
+  permissions: z.array(PluginPermissionSchema).optional().default([]),
+  strategyFeatures: StrategyFeaturesSchema,
 });
+export type PluginArtifactManifest = z.infer<typeof PluginArtifactManifestSchema>;
+
+export const PluginMarketCatalogSchema = z.discriminatedUnion('schemaVersion', [
+  z.object({
+    schemaVersion: z.literal(1),
+    generatedAt: z.string(),
+    channel: PluginMarketChannelSchema,
+    plugins: z.array(PluginMarketCatalogEntrySchema),
+  }),
+  z.object({
+    schemaVersion: z.literal(2),
+    generatedAt: z.string(),
+    channel: PluginMarketChannelSchema,
+    plugins: z.array(PluginMarketCatalogV2EntrySchema),
+  }),
+]);
 export type PluginMarketCatalog = z.infer<typeof PluginMarketCatalogSchema>;
 
 export const PluginMarketCatalogResponseSchema = z.object({