@77-zhike/app-sdk 0.2.0-d7b1.2 → 0.2.0-d7b1.20

package/src/forms/schema.js

@@ -0,0 +1,128 @@
+import { isPlainDate, isDateTime } from './values.js';
+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 => {
+  if (typeof value !== 'string' || !value.trim() || value.length > 300) fail();
+  return value;
+};
+function builder(field, validators = []) {
+  field = freezeFormState(field);
+  const next = (patch, checks = validators) => builder({ ...field, ...patch }, checks);
+  const rule = (key, value, options) => {
+    const messages = { ...field.messages };
+    if (options !== undefined) {
+      if (!options || Object.keys(options).some(key => key !== 'message')) fail();
+      messages[key] = message(options.message);
+    } else delete messages[key];
+    return next({ [field.type === 'array' ? `${key}Items` : field.type === 'string' ? `${key}Length` : key]: value, messages });
+  };
+  const methods = {
+    label(value) { return next({ label: value }); },
+    required(value) { return next({ required: true, messages: { ...field.messages, ...(value === undefined ? {} : { required: message(value) }) } }); },
+    optional() { return next({ required: false }); },
+    custom(validator) {
+      if (typeof validator !== 'function' || validators.length >= 4) fail();
+      return next({}, [...validators, validator]);
+    },
+  };
+  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;
+    else { if (!options || Object.keys(options).some(key => key !== 'message')) fail(); messages.format = message(options.message); }
+    return next({ format, messages });
+  };
+  const result = Object.freeze({ ...field, ...methods });
+  descriptors.set(result, { field, validators });
+  return result;
+}
+export const Forms = Object.freeze({
+  schema(fields) {
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields)) fail();
+    if (Object.values(fields).some(field => !descriptors.has(field))) fail();
+    return Object.freeze({ fields: Object.freeze({ ...fields }) });
+  },
+  ...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 }),
+});
+
+/** 只编译描述与回调；输入规则由 Host 单一校验器执行。 */
+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.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 (!validFieldKey(name)) fail();
+    const descriptor = descriptors.get(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'] : [])];
+    if (Object.keys(field).some(key => !allowed.includes(key)) || (field.required !== undefined && typeof field.required !== 'boolean')) fail();
+    if (field.messages !== undefined) {
+      if (!field.messages || typeof field.messages !== 'object' || Array.isArray(field.messages)
+        || Object.keys(field.messages).some(key => !['required', 'min', 'max', 'format'].includes(key))) fail();
+      Object.values(field.messages).forEach(message);
+    }
+    if (field.type === 'record') recordObjectsForField(field);
+    if (field.type === 'enum') {
+      if (!Array.isArray(field.options) || !field.options.length || field.options.length > 100) fail();
+      const seen = new Set();
+      for (const choice of field.options) {
+        if (!choice || Object.keys(choice).some(key => !['value', 'label', 'description'].includes(key)) || typeof choice.value !== 'string' || !choice.value || choice.value.length > 200 || seen.has(choice.value) || typeof choice.label !== 'string' || choice.label.length > 200) fail();
+        if (choice.description !== undefined && (typeof choice.description !== 'string' || choice.description.length > 300)) fail();
+        seen.add(choice.value);
+      }
+    }
+    const low = field.type === 'string' ? 'minLength' : 'min', high = field.type === 'string' ? 'maxLength' : 'max';
+    const valid = value => field.type === 'string' ? Number.isSafeInteger(value) && value >= 0 && value <= 10000
+      : field.type === 'number' ? typeof value === 'number' && Number.isFinite(value)
+        : field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value);
+    for (const key of [low, high]) if (field[key] !== undefined && (!valid(field[key]) || key === 'maxLength' && field[key] === 0)) fail();
+    const comparable = value => field.type === 'dateTime' ? Date.parse(value) : value;
+    if (field[low] !== undefined && field[high] !== undefined && comparable(field[low]) > comparable(field[high])) fail();
+    if (field.format !== undefined && !['email', 'url'].includes(field.format)) fail();
+    fields[name] = field;
+    if (descriptor?.validators.length) validators[name] = descriptor.validators.map(bindCallback);
+  }
+  const wire = freezeFormState({ fields });
+  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));
+  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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+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;
+  validatingFields?: true | readonly (keyof S['fields'] & string)[];
+  formError?: boolean;
+};
+type Names<S extends FormSchema, T> = T extends true ? keyof FormValues<S> : T extends readonly (infer K)[] ? Extract<K, keyof FormValues<S>> : never;
+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: 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: 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 = { 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

@@ -0,0 +1,82 @@
+import { assertFieldValue, assertErrorTree, assertArrayErrors, normalizeFormValues, formBytes, ARRAY_LIMITS } from './array-contract.js';
+import { assertJsonValue } from '../ui/validation.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();
+};
+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', '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 > 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;
+}
+export function assertFormStateSnapshot(snapshot, formId, fields, selection) {
+  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.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) assertFieldValue(snapshot.values[name], fields[name]);
+  }
+  if (selection.errors !== undefined) {
+    only(snapshot.errors, selectedNames(selection.errors, fields));
+    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));
+    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) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freezeFormState); Object.freeze(value); }
+  return value;
+}
+export function initialFormState(formId, fields, initialValues, selection) {
+  const snapshot = { formId, revision: 1 };
+  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 = {};
+  assertFormStateSnapshot(snapshot, formId, fields, selection);
+  return snapshot;
+}
+export function createWithState({ createElement, Fragment, useMemo, useState, useRef }, formId, schema, initialValues) {
+  function Observer({ selection, children }) {
+    const revision = useRef(0);
+    const [snapshot, setSnapshot] = useState(() => initialFormState(formId, schema.fields, initialValues, selection));
+    const onState = useMemo(() => next => {
+      assertFormStateSnapshot(next, formId, schema.fields, selection);
+      if (next.revision <= revision.current) return;
+      revision.current = next.revision;
+      setSnapshot(freezeFormState(next));
+    }, []);
+    const { formId: _, revision: _revision, ...state } = snapshot;
+    return createElement(Fragment, null,
+      createElement('FormStateObserver', { formId, selection, onState }),
+      children(freezeFormState(state)));
+  }
+  return function WithState({ selection, children }) {
+    assertFormStateSelection(selection, schema.fields);
+    if (typeof children !== 'function') fail();
+    return createElement(Observer, { key: JSON.stringify(selection), selection, children });
+  };
+}

package/src/forms/validation.d.ts

@@ -0,0 +1,9 @@
+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, unknown>; fields: string[]; includeForm: boolean;
+}
+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'> & { values?: Record<string, unknown> }, fields: Record<string, unknown>): ValidationResponse;

package/src/forms/validation.js

@@ -0,0 +1,81 @@
+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';
+
+export const VALIDATION_TIMEOUT_MS = 10000;
+const fail = () => { throw new Error('runtime_form_validation_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+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 > 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', 'arrayErrors', 'formError']);
+  if (value.formId !== request.formId || value.runId !== request.runId) 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) {
+  only(request, ['formId', 'runId', 'reason', 'values', 'fields', 'includeForm']);
+  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.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)) 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;
+  return async input => {
+    assertRequest(input, formId, fields, validators, validate);
+    if (busy) fail();
+    busy = true;
+    const request = freezeFormState(structuredClone(input));
+    let active = true, timer, position = 0;
+    const fieldErrors = {}, arrayErrors = {};
+    const runField = async () => {
+      while (active && position < request.fields.length) {
+        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(); (field.type === 'array' ? arrayErrors : fieldErrors)[name] = error; break; }
+        }
+      }
+    };
+    try {
+      return await Promise.race([
+        (async () => {
+          await Promise.all([runField(), runField()]);
+          if (!active) return;
+          const result = request.includeForm ? await validate(request.values) : undefined;
+          if (!active) return;
+          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); }),
+      ]);
+    } finally { active = false; busy = false; clearTimeout(timer); }
+  };
+}

package/src/forms/values.d.ts

@@ -0,0 +1,5 @@
+export function isPlainDate(value: unknown): value is string;
+export function isDateTime(value: unknown): value is string;
+export function parseNumberDraft(value: unknown): { value: number | null; error?: string };
+export function instantToLocal(value: string | null): string;
+export function localToInstant(value: string): { value: string | null; error?: string };

package/src/forms/values.js

@@ -0,0 +1,38 @@
+/** 平台值格式，不包含业务字段规则或缺省时区。 */
+export function isPlainDate(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  return year > 0 && date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export function isDateTime(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+  return Boolean(match && isPlainDate(match[1]) && +match[2] < 24 && +match[3] < 60 && +(match[4] ?? 0) < 60 && Number.isFinite(Date.parse(value)));
+}
+export function parseNumberDraft(value) {
+  if (value === null || value === '') return { value: null };
+  if (typeof value === 'number') return Number.isFinite(value) ? { value } : { value: null, error: '请输入有效数字' };
+  if (typeof value !== 'string' || value.length > 512 || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return { value: null, error: '请输入有效数字' };
+  const number = Number(value);
+  return Number.isFinite(number) ? { value: number } : { value: null, error: '请输入有效数字' };
+}
+const pad = value => String(value).padStart(2, '0');
+export function instantToLocal(value) {
+  if (!value) return '';
+  if (!isDateTime(value)) return value;
+  const date = new Date(value);
+  return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function localToInstant(value) {
+  if (!value) return { value: null };
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})$/.exec(value);
+  if (!match || !isPlainDate(match[1]) || +match[2] > 23 || +match[3] > 59) return { value: null, error: '请输入有效日期时间' };
+  const wall = new Date(value);
+  const utc = new Date(value + ':00.000Z').getTime();
+  const offsets = new Set([-36, 0, 36].map(hours => new Date(wall.getTime() + hours * 3600000).getTimezoneOffset()));
+  const candidates = [...offsets].map(offset => new Date(utc + offset * 60000).toISOString()).filter(instant => instantToLocal(instant) === value);
+  if (candidates.length !== 1) return { value: null, error: '该本地时间不存在或有歧义，请选择其他时间' };
+  return { value: candidates[0] };
+}

package/src/jsx-dev-runtime.d.ts

@@ -0,0 +1,2 @@
+export { jsxDEV, Fragment } from "react/jsx-dev-runtime";
+export { JSX } from "./ui/jsx.generated.js";

package/src/jsx-dev-runtime.js

@@ -0,0 +1 @@
+export { jsxDEV, Fragment } from "react/jsx-dev-runtime";

package/src/jsx-runtime.d.ts

@@ -0,0 +1,2 @@
+export { jsx, jsxs, Fragment } from "react/jsx-runtime";
+export { JSX } from "./ui/jsx.generated.js";

package/src/jsx-runtime.js

@@ -0,0 +1 @@
+export { jsx, jsxs, Fragment } from "react/jsx-runtime";

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

@@ -0,0 +1,62 @@
+/** 静态信息进入不可变 Manifest；工具集合由同目录 .tools.ts 唯一决定。 */
+export interface AppAgentDefinition {
+  key: string;
+  name: string;
+  /** App 提供的系统提示词，最多 16KiB UTF-8，不交付 Client Worker。 */
+  systemPrompt: string;
+  /** 引用同 App 独立 Action 的 key，Schema/execute 只维护一份。 */
+  actionRefs?: readonly string[];
+  aiExposure?: AppExpertExposure;
+}
+export type ToolSchema = Readonly<Record<string, unknown>>;
+export interface AppToolDefinition<Input, Output> {
+  key: string;
+  name: string;
+  description: string;
+  /** 有界 JSON Schema；平台在模型调用和结果交付时再次严格验证。 */
+  inputSchema: ToolSchema;
+  outputSchema: ToolSchema;
+  /** 默认 none；output 只允许成功且通过校验的结果进入实时 callback。 */
+  clientResult?: 'none' | 'output';
+  /** 缺省私有；公开查询声明不代替执行授权。 */
+  aiExposure?: AppActionExposure;
+  /** 同 App 静态 Tool Renderer；展示不授予服务端执行或业务写入权限。 */
+  toolRenderer?: { key: string; showByDefault: boolean;
+    /** 成功结果中的标量身份路径（最多四段）；同轮同安装/Action/Renderer/身份仅展示一次。仅控制展示，不跳过取数或授权。 */
+    dedupeBy?: string;
+  };
+  /** 仅在所属安装的服务端执行环境运行，凭据沿用现有 Server SDK。 */
+  execute(input: Input): Output | Promise<Output>;
+}
+export function defineAgent(definition: AppAgentDefinition): Readonly<AppAgentDefinition>;
+export function defineTool<Input = Record<string, unknown>, Output = unknown>(definition: AppToolDefinition<Input, Output>): Readonly<AppToolDefinition<Input, Output>>;
+
+export interface AppActionExposure {
+  effect: 'query';
+  /** 公开 object 标识；只用于说明适用对象，不授予权限。 */
+  subjectTypes: readonly string[];
+  usage: string;
+  limitations: string;
+  /** 已有 inputSchema 中接收 {object, recordId} 的字段；由 Host 绑定。 */
+  subjectInput?: string;
+}
+export interface AppExpertExposure {
+  subjectTypes: readonly string[];
+  usage: string;
+  limitations: string;
+  outputSchema: ToolSchema;
+  /** 只允许显式开放的原私有工具子集；独立能力沿 actionRefs。 */
+  toolKeys?: readonly string[];
+}
+interface AppDataCapabilityBase {
+  key: string;
+  name: string;
+  description: string;
+  subjectTypes: readonly string[];
+  usage: string;
+}
+export type AppDataCapabilityDefinition = AppDataCapabilityBase & (
+  { kind: 'live'; actionRef: string; sourceBinding?: never } |
+  { kind: 'published'; sourceBinding: string; actionRef?: never }
+);
+export function defineDataCapability<T extends AppDataCapabilityDefinition>(definition: T): Readonly<T>;

package/src/server/agents/index.js

@@ -0,0 +1,40 @@
+import { assertDataCapability } from '../../toolchain/ai-capabilities.js';
+import { assertAiExposure } from '../../toolchain/agents/exposure.js';
+import { assertToolRendererReference } from '../../toolchain/agents/manifest.js';
+const KEY = /^[a-z][a-z0-9-]{0,63}$/;
+
+function fields(value, required, optional = []) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      required.some(key => !Object.hasOwn(value, key)) ||
+      Object.keys(value).some(key => ![...required, ...optional].includes(key))) {
+    throw new TypeError("agent_definition_invalid");
+  }
+  if (typeof value.key !== "string" || value.key.trim() !== value.key || !KEY.test(value.key) || typeof value.name !== "string" ||
+      !value.name.trim() || value.name.length > 80) throw new TypeError("agent_definition_invalid");
+}
+
+export function defineAgent(definition) {
+  fields(definition, ["key", "name", "systemPrompt"], ["actionRefs", "aiExposure"]);
+  if (typeof definition.systemPrompt !== "string" || !definition.systemPrompt.trim() ||
+      new TextEncoder().encode(definition.systemPrompt).length > 16384) {
+    throw new TypeError("agent_definition_invalid");
+  }
+  return Object.freeze({ ...definition });
+}
+
+export function defineTool(definition) {
+  fields(definition, ["key", "name", "description", "inputSchema", "outputSchema", "execute"], ["clientResult", "aiExposure", "toolRenderer"]);
+  if (typeof definition.execute !== "function" || typeof definition.description !== "string" ||
+      !definition.description.trim() || definition.description.length > 1200 ||
+      ![undefined, "none", "output"].includes(definition.clientResult)) {
+    throw new TypeError("agent_tool_definition_invalid");
+  }
+  if (definition.aiExposure !== undefined) assertAiExposure(definition.aiExposure, definition.inputSchema);
+  if (definition.toolRenderer !== undefined) assertToolRendererReference(definition.toolRenderer);
+  return Object.freeze({ ...definition, clientResult: definition.clientResult ?? "none" });
+}
+
+export function defineDataCapability(definition) {
+  assertDataCapability(definition);
+  return Object.freeze({ ...definition });
+}

package/src/server/index.d.ts

@@ -1,7 +1,26 @@
+export { defineAgent, defineTool, defineDataCapability, type AppAgentDefinition, type AppToolDefinition, type ToolSchema } from "./agents/index.js";
 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;
+/** 认证页面 Function 的当前成员短期 OpenAPI Token；未申请 User scopes 或后台入口为 undefined。 */
+export const ZHIKE_CURRENT_USER_TOKEN: string | undefined;
 
 /** 由调用方选择稳定操作身份；SDK 不生成 Key 或自动重试。 */
 export interface IdempotencyOptions { idempotencyKey?: string }
@@ -206,21 +225,55 @@ 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>;
 
+/** 当前 Server Function 调用者在当前 Workspace 内的成员快照。 */
+export interface CurrentUser {
+  /** Workspace 成员 ID；不是平台全局 User ID。 */
+  workspaceMemberId: string;
+  /** 当前 Workspace 中的显示名称。 */
+  displayName: string;
+  /** 当前 Workspace 中的主邮箱。 */
+  primaryEmailAddress: string | null;
+  /** 当前平台用户头像；未绑定平台用户时为空。 */
+  avatarUrl: string | null;
+}
+
+/** 同步读取当前调用者；Lifecycle、Webhook 等无人触发入口会抛出 current_user_unavailable。 */
+export function getCurrentUser(): Readonly<CurrentUser>;
+
 /** Server Function 的一期函数合同。 */
 export type ServerFunction<TArgs extends JsonValue[] = JsonValue[], TResult extends JsonValue = JsonValue> =
   (...args: TArgs) => Promise<TResult>;
@@ -266,3 +319,5 @@ export interface WebhookContext {
   /** 从 1 开始的业务尝试序号。 */
   readonly attemptNumber: number;
 }
+
+export type { AppActionExposure, AppExpertExposure, AppDataCapabilityDefinition } from "./agents/index.js";