@77-zhike/app-sdk 0.2.0-d7b1.7 → 0.2.0-d7b1.9

package/src/forms/schema.js

@@ -3,6 +3,8 @@ import { recordObjectsForField } from './record-options.js';
 import { freezeFormState } from './state.js';
 import { createValidationCallback } from './validation.js';
 
+import { validFieldKey, assertArrayCapacity } from './array-contract.js';
+
 const descriptors = new WeakMap();
 const fail = () => { throw new Error('runtime_form_schema_invalid'); };
 const message = value => {
@@ -18,7 +20,7 @@ function builder(field, validators = []) {
       if (!options || Object.keys(options).some(key => key !== 'message')) fail();
       messages[key] = message(options.message);
     } else delete messages[key];
-    return next({ [field.type === 'string' ? `${key}Length` : key]: value, messages });
+    return next({ [field.type === 'array' ? `${key}Items` : field.type === 'string' ? `${key}Length` : key]: value, messages });
   };
   const methods = {
     label(value) { return next({ label: value }); },
@@ -29,10 +31,11 @@ function builder(field, validators = []) {
       return next({}, [...validators, validator]);
     },
   };
-  if (['string', 'number', 'plainDate', 'dateTime'].includes(field.type)) {
+  if (['array', 'string', 'number', 'plainDate', 'dateTime'].includes(field.type)) {
     methods.min = (value, options) => rule('min', value, options);
     methods.max = (value, options) => rule('max', value, options);
   }
+  if (field.type === 'array') { delete methods.required; delete methods.optional; }
   if (field.type === 'string') for (const format of ['email', 'url']) methods[format] = options => {
     const messages = { ...field.messages };
     if (options === undefined) delete messages.format;
@@ -51,6 +54,10 @@ export const Forms = Object.freeze({
   },
   ...Object.fromEntries(['string', 'number', 'boolean', 'plainDate', 'dateTime'].map(type => [type, () => builder({ type })])),
   enum: options => builder({ type: 'enum', options: Array.isArray(options) ? options.map(option => Object.freeze({ ...option })) : options }),
+  array(fields) {
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields) || !Object.keys(fields).length || Object.keys(fields).length > 12 || Object.values(fields).some(field => !descriptors.has(field) || field.type === 'array')) fail();
+    return builder({ type: 'array', minItems: 0, maxItems: 50, item: { type: 'object', fields: { ...fields } } });
+  },
   record: objectSlug => builder({ type: 'record', objectSlug }),
 });
 
@@ -58,13 +65,26 @@ export const Forms = Object.freeze({
 export function compileForm(options, formId, bindCallback = callback => callback) {
   const { schema, validate, validationMode = 'onBlur' } = options;
   if (!schema || !schema.fields || typeof schema.fields !== 'object' || Array.isArray(schema.fields) || Object.keys(schema).some(key => key !== 'fields')
-    || Object.keys(schema.fields).length > 30 || !['onBlur', 'onChange', 'onSubmit'].includes(validationMode)
+    || Object.values(schema.fields).filter(field => field.type !== 'array').length > 30 || Object.values(schema.fields).filter(field => field.type === 'array').length > 3 || !['onBlur', 'onChange', 'onSubmit'].includes(validationMode)
     || (validate !== undefined && typeof validate !== 'function')) fail();
   const fields = {}, validators = {};
   for (const [name, input] of Object.entries(schema.fields)) {
-    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(name) || ['constructor', 'prototype'].includes(name)) fail();
+    if (!validFieldKey(name)) fail();
     const descriptor = descriptors.get(input);
-    const field = structuredClone(descriptor?.field ?? input);
+    const source = descriptor?.field ?? input;
+    if (source?.type === 'array') {
+      if (Object.keys(source).some(key => !['type', 'label', 'minItems', 'maxItems', 'item', 'messages'].includes(key)) || typeof source.label !== 'string' || !source.label.trim() || source.label.length > 200
+        || !Number.isSafeInteger(source.minItems) || source.minItems < 0 || !Number.isSafeInteger(source.maxItems) || source.maxItems < 1 || source.maxItems > 50 || source.minItems > source.maxItems
+        || source.item?.type !== 'object' || Object.keys(source.item).some(key => !['type', 'fields'].includes(key)) || !source.item.fields || Object.values(source.item.fields).some(field => field.type === 'array')
+        || !Object.keys(source.item.fields).length || Object.keys(source.item.fields).length > 12) fail();
+      const child = compileForm({ schema: { fields: source.item.fields } }, formId, bindCallback);
+      fields[name] = { ...source, item: { type: 'object', fields: child.schema.fields } };
+      if (source.messages) { if (Object.keys(source.messages).some(key => !['min', 'max'].includes(key))) fail(); Object.values(source.messages).forEach(message); }
+      for (const [key, checks] of Object.entries(child.validators)) validators[`${name}[*].${key}`] = checks;
+      if (descriptor?.validators.length) validators[name] = descriptor.validators.map(bindCallback);
+      continue;
+    }
+    const field = structuredClone(source);
     if (!field || !['string', 'boolean', 'enum', 'number', 'plainDate', 'dateTime', 'record'].includes(field.type)
       || typeof field.label !== 'string' || descriptor && !field.label.trim() || field.label.length > 200) fail();
     const allowed = ['type', 'label', 'required', 'messages', ...(field.type === 'string' ? ['minLength', 'maxLength', 'format'] : field.type === 'enum' ? ['options'] : field.type === 'record' ? ['objectSlug', 'objects'] : ['number', 'plainDate', 'dateTime'].includes(field.type) ? ['min', 'max'] : [])];
@@ -99,7 +119,10 @@ export function compileForm(options, formId, bindCallback = callback => callback
   const validation = { fields: Object.keys(validators), form: Boolean(validate), mode: validationMode };
   const remote = Boolean(validation.fields.length || validate);
   const configured = remote || options.validationMode !== undefined || Object.values(schema.fields).some(field => descriptors.has(field));
-  return { schema: wire, ...(configured ? { validation } : {}), ...(remote ? {
+  if (options.initialValues !== undefined) assertArrayCapacity(fields, options.initialValues);
+  const result = { schema: wire, ...(configured ? { validation } : {}), ...(remote ? {
     onValidate: createValidationCallback(formId, fields, validators, validate ? bindCallback(validate) : undefined),
   } : {}) };
+  Object.defineProperty(result, 'validators', { value: validators });
+  return result;
 }

package/src/forms/state.d.ts

@@ -1,7 +1,8 @@
 import type { ReactNode } from 'react';
-import type { FormSchema, FormValues } from './schema.js';
+import type { FormSchema, FormValues, FormFieldErrors, FormArrayErrors } from './schema.js';
 export type FormStateSelection<S extends FormSchema> = {
   values?: true | readonly (keyof S['fields'] & string)[];
+  arrayErrors?: true | readonly (keyof FormArrayErrors<S> & string)[];
   errors?: true | readonly (keyof S['fields'] & string)[];
   submitting?: boolean;
   validating?: boolean;
@@ -12,17 +13,18 @@ type Names<S extends FormSchema, T> = T extends true ? keyof FormValues<S> : T e
 type ReadonlyValue<T> = T extends object ? { readonly [K in keyof T]: ReadonlyValue<T[K]> } : T;
 export type SelectedFormState<S extends FormSchema, Selection extends FormStateSelection<S>> =
   (Selection extends { values: infer T } ? { readonly values: ReadonlyValue<Pick<FormValues<S>, Names<S, T>>> } : {})
-  & (Selection extends { errors: infer T } ? { readonly errors: Readonly<Partial<Record<Names<S, T>, string>>> } : {})
+  & (Selection extends { errors: infer T } ? { readonly errors: ReadonlyValue<Pick<FormFieldErrors<S>, Names<S, T>>> } : {})
+  & (Selection extends { arrayErrors: infer T } ? { readonly arrayErrors: Readonly<Pick<FormArrayErrors<S>, Extract<Names<S, T>, keyof FormArrayErrors<S>>>> } : {})
   & (Selection extends { submitting: true } ? { readonly submitting: boolean } : {})
   & (Selection extends { validating: true } ? { readonly validating: boolean } : {})
   & (Selection extends { formError: true } ? { readonly formError: string | null } : {})
-  & (Selection extends { validatingFields: infer T } ? { readonly validatingFields: Readonly<Partial<Record<Names<S, T>, boolean>>> } : {});
+  & (Selection extends { validatingFields: infer T } ? { readonly validatingFields: ReadonlyValue<Pick<FormFieldErrors<S, boolean>, Names<S, T>>> } : {});
 export type WithStateComponent<S extends FormSchema> = <const Selection extends FormStateSelection<S>>(props: {
   selection: Selection;
   children: (state: SelectedFormState<S, Selection>) => ReactNode;
 }) => ReactNode;
 
-export type StateSelection = { values?: true | readonly string[]; errors?: true | readonly string[]; submitting?: boolean; validating?: boolean; validatingFields?: true | readonly string[]; formError?: boolean };
+export type StateSelection = { arrayErrors?: true | readonly string[]; values?: true | readonly string[]; errors?: true | readonly string[]; submitting?: boolean; validating?: boolean; validatingFields?: true | readonly string[]; formError?: boolean };
 export function selectedNames(selection: true | readonly string[] | undefined, fields: Record<string, unknown>): string[];
 export function assertFormStateSelection(selection: unknown, fields: Record<string, unknown>): StateSelection;
 export function assertFormStateSnapshot(snapshot: unknown, formId: string, fields: Record<string, unknown>, selection: StateSelection): unknown;

package/src/forms/state.js

@@ -1,6 +1,5 @@
+import { assertFieldValue, assertErrorTree, assertArrayErrors, normalizeFormValues, formBytes, ARRAY_LIMITS } from './array-contract.js';
 import { assertJsonValue } from '../ui/validation.js';
-import { isDateTime, isPlainDate } from './values.js';
-import { assertRecordRef, recordObjectsForField } from './record-options.js';
 const fail = () => { throw new Error('runtime_form_state_invalid'); };
 const only = (value, keys) => {
   if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
@@ -9,47 +8,40 @@ export function selectedNames(selection, fields) {
   return selection === true ? Object.keys(fields) : Array.isArray(selection) ? selection : [];
 }
 export function assertFormStateSelection(selection, fields) {
-  only(selection, ['values', 'errors', 'submitting', 'validating', 'validatingFields', 'formError']);
-  for (const kind of ['values', 'errors', 'validatingFields']) {
+  only(selection, ['values', 'errors', 'submitting', 'validating', 'validatingFields', 'arrayErrors', 'formError']);
+  for (const kind of ['values', 'errors', 'validatingFields', 'arrayErrors']) {
     const names = selection[kind];
     if (names === undefined || names === true) continue;
-    if (!Array.isArray(names) || names.length > 30 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))) fail();
+    if (!Array.isArray(names) || names.length > 33 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))) fail();
+    if (kind === 'arrayErrors' && names.some(name => fields[name].type !== 'array')) fail();
   }
   for (const key of ['submitting', 'validating', 'formError']) if (selection[key] !== undefined && typeof selection[key] !== 'boolean') fail();
   return selection;
 }
-function assertValue(value, field) {
-  switch (field.type) {
-    case 'boolean': if (typeof value !== 'boolean') fail(); break;
-    case 'number': if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); break;
-    case 'plainDate': if (value !== null && !isPlainDate(value)) fail(); break;
-    case 'dateTime': if (value !== null && !isDateTime(value)) fail(); break;
-    case 'record': if (value !== null) assertRecordRef(value, recordObjectsForField(field)); break;
-    default: if (typeof value !== 'string' || value.length > 10000) fail();
-  }
-}
 export function assertFormStateSnapshot(snapshot, formId, fields, selection) {
-  assertJsonValue(snapshot);
+  assertJsonValue(snapshot, Object.values(fields).some(field => field.type === 'array') ? { maxBytes: ARRAY_LIMITS.messageBytes, maxEntries: 4096 } : undefined);
   assertFormStateSelection(selection, fields);
-  const keys = ['formId', 'revision', ...(selection.values !== undefined ? ['values'] : []), ...(selection.errors !== undefined ? ['errors'] : []), ...['submitting', 'validating', 'formError'].filter(key => selection[key]), ...(selection.validatingFields !== undefined ? ['validatingFields'] : [])];
+  const keys = ['formId', 'revision', ...(selection.values !== undefined ? ['values'] : []), ...(selection.errors !== undefined ? ['errors'] : []), ...['submitting', 'validating', 'formError'].filter(key => selection[key]), ...(selection.arrayErrors !== undefined ? ['arrayErrors'] : []), ...(selection.validatingFields !== undefined ? ['validatingFields'] : [])];
   only(snapshot, keys);
   if (Object.keys(snapshot).length !== keys.length || snapshot.formId !== formId || !Number.isSafeInteger(snapshot.revision) || snapshot.revision < 1) fail();
   if (selection.values !== undefined) {
     const names = selectedNames(selection.values, fields);
     only(snapshot.values, names);
     if (Object.keys(snapshot.values).length !== names.length) fail();
-    for (const name of names) assertValue(snapshot.values[name], fields[name]);
+    for (const name of names) assertFieldValue(snapshot.values[name], fields[name]);
   }
   if (selection.errors !== undefined) {
     only(snapshot.errors, selectedNames(selection.errors, fields));
-    for (const value of Object.values(snapshot.errors)) if (typeof value !== 'string' || !value || value.length > 4096) fail();
+    assertErrorTree(snapshot.errors, fields, snapshot.values);
   }
   for (const key of ['submitting', 'validating']) if (selection[key] && typeof snapshot[key] !== 'boolean') fail();
   if (selection.formError && snapshot.formError !== null && (typeof snapshot.formError !== 'string' || !snapshot.formError || snapshot.formError.length > 4096)) fail();
   if (selection.validatingFields !== undefined) {
     only(snapshot.validatingFields, selectedNames(selection.validatingFields, fields));
-    if (Object.values(snapshot.validatingFields).some(value => typeof value !== 'boolean')) fail();
+    assertErrorTree(snapshot.validatingFields, fields, snapshot.values, true);
   }
+  if (selection.arrayErrors !== undefined) { only(snapshot.arrayErrors, selectedNames(selection.arrayErrors, fields)); assertArrayErrors(snapshot.arrayErrors, fields); }
+  if (Object.values(fields).some(field => field.type === 'array') && formBytes(snapshot) > ARRAY_LIMITS.messageBytes) fail();
   return snapshot;
 }
 export function freezeFormState(value) {
@@ -58,11 +50,9 @@ export function freezeFormState(value) {
 }
 export function initialFormState(formId, fields, initialValues, selection) {
   const snapshot = { formId, revision: 1 };
-  if (selection.values !== undefined) snapshot.values = Object.fromEntries(selectedNames(selection.values, fields).map(name => {
-    const value = initialValues[name];
-    return [name, fields[name].type === 'dateTime' && value ? new Date(value).toISOString() : value && typeof value === 'object' ? { ...value } : value];
-  }));
+  if (selection.values !== undefined) { const values = normalizeFormValues(fields, initialValues); snapshot.values = Object.fromEntries(selectedNames(selection.values, fields).map(name => [name, values[name]])); }
   if (selection.errors !== undefined) snapshot.errors = {};
+  if (selection.arrayErrors !== undefined) snapshot.arrayErrors = {};
   for (const key of ['submitting', 'validating']) if (selection[key]) snapshot[key] = false;
   if (selection.formError) snapshot.formError = null;
   if (selection.validatingFields !== undefined) snapshot.validatingFields = {};

package/src/forms/validation.d.ts

@@ -2,8 +2,8 @@ export const VALIDATION_TIMEOUT_MS: 10000;
 export interface ValidationMetadata { fields: string[]; form: boolean; mode: 'onBlur' | 'onChange' | 'onSubmit'; }
 export interface ValidationRequest {
   formId: string; runId: number; reason: 'blur' | 'change' | 'submit';
-  values: Record<string, string | boolean | number | import("./record-options.js").RecordRef | null>; fields: string[]; includeForm: boolean;
+  values: Record<string, unknown>; fields: string[]; includeForm: boolean;
 }
-export interface ValidationResponse { formId: string; runId: number; fieldErrors: Record<string, string>; formError?: string; }
+export interface ValidationResponse { formId: string; runId: number; fieldErrors: Record<string, string | (Record<string, string> | null)[]>; arrayErrors?: Record<string, string>; formError?: string; }
 export function assertValidationMetadata(value: unknown, fields: Record<string, unknown>): ValidationMetadata;
-export function assertValidationResponse(value: unknown, request: Pick<ValidationRequest, 'formId' | 'runId'>, fields: Record<string, unknown>): ValidationResponse;
+export function assertValidationResponse(value: unknown, request: Pick<ValidationRequest, 'formId' | 'runId'> & { values?: Record<string, unknown> }, fields: Record<string, unknown>): ValidationResponse;

package/src/forms/validation.js

@@ -1,3 +1,4 @@
+import { assertFieldValue, assertArrayCapacity, assertErrorTree, assertArrayErrors, fieldAtPath, valueAtPath, rulePath, flattenErrors, nestErrors, formBytes, ARRAY_LIMITS } from './array-contract.js';
 import { freezeFormState } from './state.js';
 import { isDateTime, isPlainDate } from './values.js';
 import { assertRecordRef, recordObjectsForField } from './record-options.js';
@@ -10,16 +11,18 @@ const only = (value, keys) => {
 const validMessage = value => typeof value === 'string' && value.trim() && value.length <= 300;
 export function assertValidationMetadata(value, fields) {
   only(value, ['fields', 'form', 'mode']);
-  if (!Array.isArray(value.fields) || value.fields.length > 30 || new Set(value.fields).size !== value.fields.length
-    || value.fields.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))
+  if (!Array.isArray(value.fields) || value.fields.length > 69 || new Set(value.fields).size !== value.fields.length
+    || value.fields.some(name => { try { fieldAtPath(fields, typeof name === 'string' ? name.replace('[*]', '[0]') : name); return false; } catch { return true; } })
     || typeof value.form !== 'boolean' || !['onBlur', 'onChange', 'onSubmit'].includes(value.mode)) fail();
   return value;
 }
 export function assertValidationResponse(value, request, fields) {
-  only(value, ['formId', 'runId', 'fieldErrors', 'formError']);
+  only(value, ['formId', 'runId', 'fieldErrors', 'arrayErrors', 'formError']);
   if (value.formId !== request.formId || value.runId !== request.runId) fail();
-  only(value.fieldErrors, Object.keys(fields));
-  if (Object.values(value.fieldErrors).some(error => !validMessage(error)) || value.formError !== undefined && !validMessage(value.formError)) fail();
+  assertErrorTree(value.fieldErrors, fields, request.values, false, 300);
+  if (value.arrayErrors !== undefined) assertArrayErrors(value.arrayErrors, fields, 300);
+  if (value.formError !== undefined && !validMessage(value.formError)) fail();
+  if (Object.values(fields).some(field => field.type === 'array') && formBytes({ ...value, values: request.values }) > ARRAY_LIMITS.messageBytes - 32768) fail();
   return value;
 }
 function assertRequest(request, formId, fields, validators, validate) {
@@ -27,17 +30,12 @@ function assertRequest(request, formId, fields, validators, validate) {
   if (request.formId !== formId || !Number.isSafeInteger(request.runId) || request.runId < 1
     || !['blur', 'change', 'submit'].includes(request.reason) || typeof request.includeForm !== 'boolean'
     || request.includeForm && !validate || !Array.isArray(request.fields) || new Set(request.fields).size !== request.fields.length
-    || request.fields.some(name => !Object.hasOwn(validators, name))) fail();
+    || request.fields.length > 303 || request.fields.some(name => !Object.hasOwn(validators, rulePath(name)))) fail();
   only(request.values, Object.keys(fields));
   if (Object.keys(request.values).length !== Object.keys(fields).length) fail();
-  for (const [name, field] of Object.entries(fields)) {
-    const value = request.values[name];
-    if (field.type === 'boolean') { if (typeof value !== 'boolean') fail(); }
-    else if (field.type === 'record') { if (value !== null) assertRecordRef(value, recordObjectsForField(field)); }
-    else if (field.type === 'number') { if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); }
-    else if (['plainDate', 'dateTime'].includes(field.type)) { if (value !== null && !(field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value))) fail(); }
-    else if (typeof value !== 'string' || value.length > 10000) fail();
-  }
+  for (const [name, field] of Object.entries(fields)) assertFieldValue(request.values[name], field);
+  assertArrayCapacity(fields, request.values);
+  for (const path of request.fields) if (valueAtPath(request.values, path) === undefined) fail();
 }
 export function createValidationCallback(formId, fields, validators, validate) {
   let busy = false;
@@ -47,16 +45,16 @@ export function createValidationCallback(formId, fields, validators, validate) {
     busy = true;
     const request = freezeFormState(structuredClone(input));
     let active = true, timer, position = 0;
-    const fieldErrors = {};
+    const fieldErrors = {}, arrayErrors = {};
     const runField = async () => {
       while (active && position < request.fields.length) {
-        const name = request.fields[position++], value = request.values[name];
-        if (!fields[name].required && (value === '' || value === null)) continue;
-        for (const validator of validators[name]) {
+        const name = request.fields[position++], value = valueAtPath(request.values, name), field = fieldAtPath(fields, name);
+        if (!field.required && (value === '' || value === null)) continue;
+        for (const validator of validators[rulePath(name)]) {
           if (!active) return;
           const error = await validator(value);
           if (!active) return;
-          if (error !== undefined) { if (!validMessage(error)) fail(); fieldErrors[name] = error; break; }
+          if (error !== undefined) { if (!validMessage(error)) fail(); (field.type === 'array' ? arrayErrors : fieldErrors)[name] = error; break; }
         }
       }
     };
@@ -67,13 +65,13 @@ export function createValidationCallback(formId, fields, validators, validate) {
           if (!active) return;
           const result = request.includeForm ? await validate(request.values) : undefined;
           if (!active) return;
-          if (result !== undefined) { only(result, ['fieldErrors', 'formError']); }
-          // 字段 custom 错误优先于跨字段错误。
-          const response = { formId, runId: request.runId, fieldErrors: { ...result?.fieldErrors, ...fieldErrors }, ...(result?.formError === undefined ? {} : { formError: result.formError }) };
-          if (result?.fieldErrors !== undefined) {
-            only(result.fieldErrors, Object.keys(fields));
-            if (Object.values(result.fieldErrors).some(error => !validMessage(error))) fail();
-          }
+          if (result !== undefined) { only(result, ['fieldErrors', 'arrayErrors', 'formError']); }
+          if (result?.fieldErrors !== undefined) assertErrorTree(result.fieldErrors, fields, request.values, false, 300);
+          if (result?.arrayErrors !== undefined) assertArrayErrors(result.arrayErrors, fields, 300);
+          // 每个叶子合并，不能用整行覆盖同一行其他字段的跨字段错误。
+          const arrays = { ...result?.arrayErrors, ...arrayErrors };
+          const response = { formId, runId: request.runId, fieldErrors: nestErrors({ ...flattenErrors(result?.fieldErrors), ...fieldErrors }),
+            ...(Object.keys(arrays).length ? { arrayErrors: arrays } : {}), ...(result?.formError === undefined ? {} : { formError: result.formError }) };
           return assertValidationResponse(response, request, fields);
         })(),
         new Promise((_, reject) => { timer = setTimeout(() => { active = false; reject(new Error('runtime_form_validation_timeout')); }, VALIDATION_TIMEOUT_MS); }),

package/src/server/index.d.ts

@@ -1,4 +1,20 @@
 import type { JsonValue } from "../index.js";
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export type { WorkflowObjectSchema, WorkflowScalarSchema, WorkflowStepDefinition, WorkflowStepOutcome, WorkflowStepResult, WorkflowSchemaValue } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export type { WorkflowTriggerDefinition, WorkflowTriggerOutcome, WorkflowTriggerEventResult } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
+export type {
+  WorkflowBlockDefinition,
+  WorkflowStepBlockDefinition,
+  WorkflowTriggerBlockDefinition,
+} from "./workflow-blocks/index.js";
 
 /** 当前执行的 App API Token；由可信 Runtime Module 在服务端模块求值前注入。 */
 export const ZHIKE_API_TOKEN: string;
@@ -206,18 +222,37 @@ export interface WorkspaceWebhookBody {
   events: WorkspaceWebhookEvent[];
 }
 
-/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
-export interface WorkspaceConnection {
+interface WorkspaceConnectionBase {
   /** 当前 Workspace Connection 的稳定 ID。 */
   id: string;
   /** 当前 Connect/Reconnect generation 的非敏感稳定表示。 */
   generation: string;
-  /** 当前凭据类型。 */
-  type: "secret" | "oauth2";
-  /** Secret 或当前 OAuth access token，仅存在于本次服务端执行内存。 */
+  /** Secret 或当前 OAuth/OIDC access token，仅存在于本次服务端执行内存。 */
   value: string;
 }
 
+/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
+export type WorkspaceConnection = WorkspaceConnectionBase & (
+  | {
+    type: "secret";
+    protocol: "secret";
+  }
+  | {
+    type: "oauth2";
+    protocol: "oauth2";
+    /** OAuth 2.0 access token；等同 value。 */
+    accessToken: string;
+  }
+  | {
+    type: "oauth2";
+    protocol: "oidc";
+    /** OIDC access token；等同 value。 */
+    accessToken: string;
+    /** OIDC ID token；仅存在于当前服务端执行内存。 */
+    idToken: string;
+  }
+);
+
 /** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
 export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
 

package/src/server/index.js

@@ -1,4 +1,13 @@
 const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
 const LIFECYCLE_EVENT_MARKER = Symbol.for("zhike.lifecycle-event.v1");
 const WEBHOOK_HANDLER_MARKER = Symbol.for("zhike.webhook-handler.v1");
 const WORKSPACE_CONNECTION_EVENTS = new Set([
@@ -145,11 +154,23 @@ export function getWorkspaceConnection() {
     error.code = code;
     throw error;
   }
+  if (connection.protocol === "oidc" && (typeof connection.idToken !== "string" || !connection.idToken)) {
+    const error = new Error("connection_credential_unavailable");
+    error.code = "connection_credential_unavailable";
+    throw error;
+  }
+  const protocol = connection.type === "secret"
+    ? "secret"
+    : (connection.protocol === "oidc" && typeof connection.idToken === "string" && connection.idToken
+      ? "oidc" : "oauth2");
   return Object.freeze({
     id: connection.id,
     generation: connection.generation,
     type: connection.type,
+    protocol,
     value: connection.value,
+    ...(connection.type === "oauth2" ? { accessToken: connection.value } : {}),
+    ...(protocol === "oidc" ? { idToken: connection.idToken } : {}),
   });
 }
 

package/src/server/steps/index.d.ts

@@ -0,0 +1,71 @@
+export type WorkflowScalarSchema =
+  | { readonly type: "string"; readonly minLength?: number; readonly enum?: readonly string[]; readonly title?: string; readonly description?: string; readonly examples?: readonly string[] }
+  | { readonly type: "number"; readonly title?: string; readonly description?: string; readonly examples?: readonly number[] }
+  | { readonly type: "boolean"; readonly title?: string; readonly description?: string; readonly examples?: readonly boolean[] };
+
+export interface WorkflowObjectSchema {
+  readonly type: "object";
+  readonly properties: Readonly<Record<string, WorkflowScalarSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties: false;
+  readonly title?: string;
+  readonly description?: string;
+  readonly examples?: readonly (string | number | boolean)[];
+}
+
+export interface WorkflowStepOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema | null;
+}
+
+export interface WorkflowStepDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type ScalarValue<S> = S extends { readonly enum: readonly (infer E)[] } ? E
+  : S extends { readonly type: "string" } ? string
+  : S extends { readonly type: "number" } ? number
+  : S extends { readonly type: "boolean" } ? boolean
+  : never;
+
+type RequiredNames<S extends WorkflowObjectSchema> = S["required"] extends readonly string[]
+  ? S["required"][number] : never;
+
+export type WorkflowSchemaValue<S extends WorkflowObjectSchema> = {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? K : never]-?: ScalarValue<S["properties"][K]>;
+} & {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? never : K]?: ScalarValue<S["properties"][K]>;
+};
+
+type OutcomeResult<O extends WorkflowStepOutcome> = O extends WorkflowStepOutcome
+  ? O["dataSchema"] extends WorkflowObjectSchema
+    ? { readonly outcome: O["id"]; readonly data: WorkflowSchemaValue<O["dataSchema"]> }
+    : { readonly outcome: O["id"]; readonly data: null }
+  : never;
+
+export type WorkflowStepResult<Outcomes extends readonly WorkflowStepOutcome[]> =
+  OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowStep<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepDefinition<Config, Outcomes>): WorkflowStepDefinition<Config, Outcomes>;
+
+export function defineWorkflowStepExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  step: WorkflowStepDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+  WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>;

package/src/server/steps/index.js

@@ -0,0 +1,15 @@
+const STEP_MARKER = Symbol.for("zhike.workflow-step.v1");
+
+export function defineWorkflowStep(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError("workflow_step_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [STEP_MARKER]: true });
+}
+
+export function defineWorkflowStepExecute(step, execute) {
+  if (!step?.[STEP_MARKER] || typeof execute !== "function") {
+    throw new TypeError("workflow_step_execute_invalid");
+  }
+  return execute;
+}

package/src/server/triggers/index.d.ts

@@ -0,0 +1,68 @@
+import type { WorkflowObjectSchema, WorkflowSchemaValue } from "../steps/index.js";
+
+export interface WorkflowTriggerOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema;
+}
+
+export interface WorkflowTriggerDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly requestHeaders?: readonly string[];
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type OutcomeResult<O extends WorkflowTriggerOutcome> = O extends WorkflowTriggerOutcome
+  ? {
+      readonly type: "outcome";
+      readonly id: O["id"];
+      readonly eventKey: string;
+      readonly data: WorkflowSchemaValue<O["dataSchema"]>;
+    }
+  : never;
+
+export type WorkflowTriggerEventResult<Outcomes extends readonly WorkflowTriggerOutcome[]> =
+  | { readonly type: "no-op" }
+  | { readonly type: "error"; readonly code: "invalid_signature"; readonly retryable: false }
+  | OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowTrigger<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerDefinition<Config, Outcomes>): WorkflowTriggerDefinition<Config, Outcomes>;
+
+export function defineWorkflowTriggerActivate<Config extends WorkflowObjectSchema>(
+  trigger: WorkflowTriggerDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowTriggerOnEvent<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  trigger: WorkflowTriggerDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowTriggerDeactivate(
+  trigger: WorkflowTriggerDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/triggers/index.js

@@ -0,0 +1,27 @@
+const TRIGGER_MARKER = Symbol.for("zhike.workflow-trigger.v1");
+
+export function defineWorkflowTrigger(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("workflow_trigger_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [TRIGGER_MARKER]: true });
+}
+
+function bindTriggerHandler(trigger, handler, kind) {
+  if (!trigger?.[TRIGGER_MARKER] || typeof handler !== "function") {
+    throw new TypeError(`workflow_trigger_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowTriggerActivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "activate");
+}
+
+export function defineWorkflowTriggerOnEvent(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "on_event");
+}
+
+export function defineWorkflowTriggerDeactivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "deactivate");
+}