@77-zhike/app-sdk 0.2.0-d7b1.10

package/src/toolchain/transport-tar.js

@@ -0,0 +1,168 @@
+import { ZhikeCliError } from "../errors.js";
+
+export const APP_BUNDLE_TAR_MAX_BYTES = 4 * 1024 * 1024;
+export const APP_BUNDLE_MEMBER_MAX_BYTES = 2 * 1024 * 1024;
+export const APP_BUNDLE_ALLOWED_MEMBERS = Object.freeze([
+  "manifest.json",
+  "client.js",
+  "server.js",
+]);
+
+const BLOCK_SIZE = 512;
+
+export function createTransportTar(
+  entries,
+  { mtime = 0, order = null, uid = 0, gid = 0, mode = 0o644 } = {},
+) {
+  const byName = new Map(entries.map((entry) => [entry.name, entry]));
+  const names = order || entries.map((entry) => entry.name);
+  if (names.length !== entries.length || new Set(names).size !== names.length) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR 成员顺序包含缺失或重复成员");
+  }
+  const chunks = [];
+  for (const name of names) {
+    const entry = byName.get(name);
+    if (!entry || !APP_BUNDLE_ALLOWED_MEMBERS.includes(name)) {
+      throw tarError("zhike_bundle_tar_member_invalid", `TAR 成员不受支持：${name}`);
+    }
+    if (!Buffer.isBuffer(entry.bytes) || entry.bytes.byteLength > APP_BUNDLE_MEMBER_MAX_BYTES) {
+      throw tarError("zhike_bundle_tar_member_too_large", `TAR 成员无效或超限：${name}`);
+    }
+    const header = createHeader({
+      name,
+      size: entry.bytes.byteLength,
+      mtime,
+      uid,
+      gid,
+      mode,
+    });
+    chunks.push(header, entry.bytes);
+    const remainder = entry.bytes.byteLength % BLOCK_SIZE;
+    if (remainder !== 0) chunks.push(Buffer.alloc(BLOCK_SIZE - remainder));
+  }
+  chunks.push(Buffer.alloc(BLOCK_SIZE * 2));
+  const result = Buffer.concat(chunks);
+  if (result.byteLength > APP_BUNDLE_TAR_MAX_BYTES) {
+    throw tarError("zhike_bundle_tar_too_large", "App Bundle TAR 超过一期上限");
+  }
+  return result;
+}
+
+export function parseTransportTar(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.byteLength > APP_BUNDLE_TAR_MAX_BYTES) {
+    throw tarError("zhike_bundle_tar_invalid", "App Bundle TAR 无效或超限");
+  }
+  const entries = new Map();
+  let offset = 0;
+  let zeroBlocks = 0;
+  while (offset + BLOCK_SIZE <= bytes.byteLength) {
+    const header = bytes.subarray(offset, offset + BLOCK_SIZE);
+    offset += BLOCK_SIZE;
+    if (header.every((value) => value === 0)) {
+      zeroBlocks += 1;
+      if (zeroBlocks === 2) break;
+      continue;
+    }
+    if (zeroBlocks > 0) {
+      throw tarError("zhike_bundle_tar_invalid", "TAR 结束块不完整");
+    }
+    assertHeaderChecksum(header);
+    const name = readString(header, 0, 100);
+    const type = readString(header, 156, 1) || "0";
+    const linkName = readString(header, 157, 100);
+    if (
+      !APP_BUNDLE_ALLOWED_MEMBERS.includes(name) ||
+      name.startsWith("/") ||
+      name.includes("..") ||
+      name.includes("\\") ||
+      type !== "0" ||
+      linkName
+    ) {
+      throw tarError("zhike_bundle_tar_member_invalid", "TAR 包含未知路径或 link 成员");
+    }
+    if (entries.has(name)) {
+      throw tarError("zhike_bundle_tar_member_duplicate", `TAR 成员重复：${name}`);
+    }
+    const size = readOctal(header, 124, 12);
+    if (size > APP_BUNDLE_MEMBER_MAX_BYTES || offset + size > bytes.byteLength) {
+      throw tarError("zhike_bundle_tar_member_too_large", `TAR 成员超限：${name}`);
+    }
+    entries.set(name, Buffer.from(bytes.subarray(offset, offset + size)));
+    offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+  }
+  if (zeroBlocks !== 2 || entries.size === 0) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR 缺少成员或标准结束块");
+  }
+  if (bytes.subarray(offset).some((value) => value !== 0)) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR 结束块后包含非零数据");
+  }
+  return entries;
+}
+
+function createHeader({ name, size, mtime, uid, gid, mode }) {
+  const header = Buffer.alloc(BLOCK_SIZE);
+  writeString(header, name, 0, 100);
+  writeOctal(header, mode, 100, 8);
+  writeOctal(header, uid, 108, 8);
+  writeOctal(header, gid, 116, 8);
+  writeOctal(header, size, 124, 12);
+  writeOctal(header, mtime, 136, 12);
+  header.fill(0x20, 148, 156);
+  writeString(header, "0", 156, 1);
+  writeString(header, "ustar", 257, 6);
+  writeString(header, "00", 263, 2);
+  writeOctal(header, checksum(header), 148, 8);
+  return header;
+}
+
+function assertHeaderChecksum(header) {
+  const declared = readOctal(header, 148, 8);
+  const copy = Buffer.from(header);
+  copy.fill(0x20, 148, 156);
+  if (declared !== checksum(copy)) {
+    throw tarError("zhike_bundle_tar_checksum_invalid", "TAR header checksum 无效");
+  }
+}
+
+function checksum(header) {
+  let total = 0;
+  for (const value of header) total += value;
+  return total;
+}
+
+function writeString(buffer, value, offset, length) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.byteLength > length) {
+    throw tarError("zhike_bundle_tar_member_invalid", "TAR 字段超长");
+  }
+  bytes.copy(buffer, offset);
+}
+
+function readString(buffer, offset, length) {
+  const end = buffer.indexOf(0, offset);
+  const boundary = end === -1 || end > offset + length ? offset + length : end;
+  return buffer.subarray(offset, boundary).toString("utf8");
+}
+
+function writeOctal(buffer, value, offset, length) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR 数值字段无效");
+  }
+  const text = value.toString(8).padStart(length - 2, "0");
+  if (text.length > length - 2) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR 数值字段超限");
+  }
+  writeString(buffer, `${text}\0 `, offset, length);
+}
+
+function readOctal(buffer, offset, length) {
+  const text = readString(buffer, offset, length).trim();
+  if (!/^[0-7]+$/.test(text)) {
+    throw tarError("zhike_bundle_tar_invalid", "TAR octal 字段无效");
+  }
+  return Number.parseInt(text, 8);
+}
+
+function tarError(code, message) {
+  return new ZhikeCliError(code, message);
+}

package/src/toolchain/webhook-response.js

@@ -0,0 +1,50 @@
+// 此函数被嵌入生成的 server.js，不能捕获构建进程变量或依赖 Node API。
+export async function serializeWebhookResponse(response) {
+  const fail = () => { throw new Error("runtime_webhook_response_invalid"); };
+  if (!(response instanceof Response) || response.status < 200 || response.status > 599) fail();
+  const encoder = new TextEncoder();
+  const headers = [];
+  let headerBytes = 0;
+  const omitted = new Set(["content-length", "transfer-encoding", "connection", "keep-alive", "te", "trailer", "upgrade", "proxy-authenticate", "proxy-authorization", "set-cookie"]);
+  const connectionHeaders = new Set((response.headers.get("connection") ?? "").split(",").map(value => value.trim().toLowerCase()));
+  for (const [name, value] of response.headers) {
+    headerBytes += encoder.encode(name + value).byteLength;
+    if (headerBytes > 16384 || encoder.encode(value).byteLength > 4096 || /[\r\n\0]/.test(value)) fail();
+    if (!omitted.has(name) && !connectionHeaders.has(name)) headers.push([name, value]);
+  }
+  if ([...response.headers].length > 64) fail();
+  const encoding = response.headers.get("content-encoding");
+  if (encoding && encoding.trim().toLowerCase() !== "identity") fail();
+  const contentType = response.headers.get("content-type") ?? "";
+  const [mediaType, ...parameters] = contentType.toLowerCase().split(";").map(value => value.trim());
+  if (parameters.some(value => value.startsWith("charset=") && !/^charset=(?:utf-8|"utf-8")$/.test(value))) fail();
+  const chunks = [];
+  let length = 0;
+  const reader = response.body?.getReader();
+  if (reader) {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        length += value.byteLength;
+        if (length > 32768) {
+          // 不等待用户流的 cancel Promise；它可能永远不完成。
+          void reader.cancel().catch(() => {});
+          fail();
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  if (length && ([204, 205, 304].includes(response.status) ||
+      !(mediaType.startsWith("text/") || mediaType === "application/json" || /^application\/[a-z0-9.+-]+\+json$/.test(mediaType)))) fail();
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  let body;
+  try { body = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+  catch { fail(); }
+  return { status: response.status, headers: headers.filter(([name]) => name !== "content-encoding"), body };
+}

package/src/toolchain/workflow-blocks/discovery.js

@@ -0,0 +1,133 @@
+import ts from "typescript";
+
+import { ZhikeCliError } from "../../errors.js";
+import { validateWorkflowStepDefinition } from "../workflow-steps/manifest.js";
+import { validateWorkflowTriggerDefinition } from "../workflow-triggers/manifest.js";
+
+const HANDLERS = Object.freeze({
+  step: Object.freeze({ execute: "defineWorkflowBlockExecute" }),
+  trigger: Object.freeze({
+    activate: "defineWorkflowBlockActivate",
+    trigger: "defineWorkflowBlockTrigger",
+    deactivate: "defineWorkflowBlockDeactivate",
+  }),
+});
+
+function invalid(path, detail) {
+  throw new ZhikeCliError("zhike_workflow_block_invalid", `${path}: ${detail}`);
+}
+
+function literal(node, path) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isArrayLiteralExpression(node)) return node.elements.map(item => literal(item, path));
+  if (ts.isObjectLiteralExpression(node)) {
+    const result = {};
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property) ||
+        !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) {
+        invalid(path, "声明只能包含静态 JSON 属性");
+      }
+      const key = property.name.text;
+      if (Object.hasOwn(result, key)) invalid(path, `重复字段 ${key}`);
+      result[key] = literal(property.initializer, `${path}.${key}`);
+    }
+    return result;
+  }
+  invalid(path, "声明必须是 JSON 字面量，不能读取变量或运行时代码");
+}
+
+function namedImports(sourceFile, moduleName = "@77-zhike/app-sdk/server") {
+  return new Set(sourceFile.statements.flatMap(statement =>
+    ts.isImportDeclaration(statement) && statement.moduleSpecifier.text === moduleName &&
+    statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)
+      ? statement.importClause.namedBindings.elements
+        .filter(item => !item.propertyName).map(item => item.name.text)
+      : []));
+}
+
+function parseDefinition(sourceFile, relativePath) {
+  if (!namedImports(sourceFile).has("defineWorkflowBlock")) {
+    invalid(relativePath, "block.ts 必须直接导入 defineWorkflowBlock");
+  }
+  const exports = sourceFile.statements.filter(statement =>
+    ts.isExportAssignment(statement) && !statement.isExportEquals);
+  if (exports.length !== 1 || !ts.isCallExpression(exports[0].expression)) {
+    invalid(relativePath, "block.ts 必须直接默认导出唯一的 defineWorkflowBlock({...})");
+  }
+  const call = exports[0].expression;
+  if (!ts.isIdentifier(call.expression) || call.expression.text !== "defineWorkflowBlock" ||
+    call.arguments.length !== 1) {
+    invalid(relativePath, "block.ts 必须直接默认导出 defineWorkflowBlock({...})");
+  }
+  return literal(call.arguments[0], relativePath);
+}
+
+function defaultBlockImport(sourceFile, relativePath) {
+  const imports = sourceFile.statements.filter(statement =>
+    ts.isImportDeclaration(statement) && ["./block", "./block.js"].includes(statement.moduleSpecifier.text) &&
+    statement.importClause?.name);
+  if (imports.length !== 1) invalid(relativePath, "处理器必须从 ./block.js 默认导入当前 Block");
+  return imports[0].importClause.name.text;
+}
+
+function validateHandler(sourceFile, relativePath, api) {
+  if (!namedImports(sourceFile).has(api)) {
+    invalid(relativePath, `必须直接导入 ${api}`);
+  }
+  const blockName = defaultBlockImport(sourceFile, relativePath);
+  const exports = sourceFile.statements.filter(statement =>
+    ts.isExportAssignment(statement) && !statement.isExportEquals);
+  if (exports.length !== 1 || !ts.isCallExpression(exports[0].expression)) {
+    invalid(relativePath, `必须直接默认导出 ${api}(block, async (...) => ...)`);
+  }
+  const call = exports[0].expression;
+  if (!ts.isIdentifier(call.expression) || call.expression.text !== api || call.arguments.length !== 2 ||
+    !ts.isIdentifier(call.arguments[0]) || call.arguments[0].text !== blockName ||
+    !(ts.isArrowFunction(call.arguments[1]) || ts.isFunctionExpression(call.arguments[1])) ||
+    !call.arguments[1].modifiers?.some(item => item.kind === ts.SyntaxKind.AsyncKeyword)) {
+    invalid(relativePath, `必须直接默认导出 ${api}(block, async (...) => ...)`);
+  }
+}
+
+export function discoverWorkflowBlock(sourceFile, relativePath, directoryKey, sourceFilesByPath) {
+  const value = parseDefinition(sourceFile, relativePath);
+  if (!["step", "trigger"].includes(value.type)) {
+    invalid(relativePath, 'type 必须是 "step" 或 "trigger"');
+  }
+  const handlers = HANDLERS[value.type];
+  const handlerPaths = {};
+  for (const [name, api] of Object.entries(handlers)) {
+    const handlerPath = `app/blocks/${directoryKey}/${name}.ts`;
+    const handlerSource = sourceFilesByPath.get(handlerPath);
+    if (!handlerSource) invalid(relativePath, `${value.type} Block 缺少 ${name}.ts`);
+    validateHandler(handlerSource, handlerPath, api);
+    handlerPaths[name] = handlerPath;
+  }
+  const unexpected = value.type === "step"
+    ? ["activate", "trigger", "deactivate"].filter(name => sourceFilesByPath.has(`app/blocks/${directoryKey}/${name}.ts`))
+    : ["execute"].filter(name => sourceFilesByPath.has(`app/blocks/${directoryKey}/${name}.ts`));
+  if (unexpected.length > 0) invalid(relativePath, `${value.type} Block 不应包含 ${unexpected.join(", ")}.ts`);
+
+  const { type, ...definition } = value;
+  try {
+    if (type === "step") {
+      const step = validateWorkflowStepDefinition(definition, relativePath, directoryKey);
+      return Object.freeze({ ...step, type, handlerPaths: Object.freeze(handlerPaths) });
+    }
+    const trigger = validateWorkflowTriggerDefinition(definition, relativePath, directoryKey);
+    return Object.freeze({ ...trigger, type, handlerPaths: Object.freeze({
+      activate: handlerPaths.activate,
+      onEvent: handlerPaths.trigger,
+      deactivate: handlerPaths.deactivate,
+    }) });
+  } catch (error) {
+    if (error?.code === "zhike_workflow_step_invalid" || error?.code === "zhike_workflow_trigger_invalid") {
+      invalid(relativePath, error.message);
+    }
+    throw error;
+  }
+}

package/src/toolchain/workflow-steps/manifest.js

@@ -0,0 +1,99 @@
+import { ZhikeCliError } from "../../errors.js";
+
+const ID = /^[a-z][a-z0-9_-]{0,63}$/;
+const FIELD = /^[a-z][a-zA-Z0-9_]{0,63}$/;
+const DISPLAY = new Set(["title", "description", "examples"]);
+
+function invalid(path, detail) {
+  throw new ZhikeCliError("zhike_workflow_step_invalid", `${path}: ${detail}`);
+}
+
+function object(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(path, "必须是对象");
+  return value;
+}
+
+function exactKeys(value, allowed, path) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) invalid(path, `不支持字段 ${key}`);
+  }
+}
+
+function display(value, path) {
+  for (const key of ["title", "description"]) {
+    if (value[key] !== undefined && (typeof value[key] !== "string" || value[key].length > 300)) {
+      invalid(path, `${key} 无效`);
+    }
+  }
+  if (value.examples !== undefined && (
+    !Array.isArray(value.examples) || value.examples.length > 3 ||
+    value.examples.some(item => !["string", "number", "boolean"].includes(typeof item))
+  )) invalid(path, "examples 无效");
+}
+
+function schema(value, path) {
+  object(value, path);
+  exactKeys(value, new Set(["type", "properties", "required", "additionalProperties", ...DISPLAY]), path);
+  if (value.type !== "object" || value.additionalProperties !== false) invalid(path, "只支持封闭 object schema");
+  object(value.properties, `${path}.properties`);
+  const fields = Object.entries(value.properties);
+  if (fields.length > 32) invalid(path, "字段超过 32 个");
+  const required = value.required ?? [];
+  if (!Array.isArray(required) || new Set(required).size !== required.length ||
+    required.some(key => typeof key !== "string" || !Object.hasOwn(value.properties, key))) {
+    invalid(path, "required 必须引用唯一的已声明字段");
+  }
+  for (const [key, field] of fields) {
+    if (!FIELD.test(key)) invalid(path, `字段名 ${key} 无效`);
+    object(field, `${path}.${key}`);
+    const fieldPath = `${path}.properties.${key}`;
+    const allowed = field.type === "string"
+      ? new Set(["type", "minLength", "enum", ...DISPLAY])
+      : new Set(["type", ...DISPLAY]);
+    exactKeys(field, allowed, fieldPath);
+    if (!["string", "number", "boolean"].includes(field.type)) invalid(fieldPath, "只支持 string/number/boolean");
+    if (field.minLength !== undefined && (!Number.isInteger(field.minLength) || field.minLength < 0 || field.minLength > 1024)) {
+      invalid(fieldPath, "minLength 无效");
+    }
+    if (field.enum !== undefined && (
+      !Array.isArray(field.enum) || field.enum.length < 1 || field.enum.length > 32 ||
+      field.enum.some(item => typeof item !== "string" || item.length > 300) ||
+      new Set(field.enum).size !== field.enum.length
+    )) invalid(fieldPath, "enum 无效");
+    display(field, fieldPath);
+  }
+  display(value, path);
+  if (Buffer.byteLength(JSON.stringify(value), "utf8") > 16 * 1024) invalid(path, "schema 超过 16 KiB");
+  return value;
+}
+
+export function validateWorkflowStepDefinition(value, relativePath, fileKey) {
+  object(value, relativePath);
+  exactKeys(value, new Set(["key", "title", "description", "connection", "configSchema", "outcomes"]), relativePath);
+  if (!ID.test(value.key) || value.key !== fileKey) invalid(relativePath, "Step key 必须与文件名一致");
+  if (typeof value.title !== "string" || value.title.length < 1 || value.title.length > 80) invalid(relativePath, "title 无效");
+  if (value.description !== undefined && (typeof value.description !== "string" || value.description.length > 300)) invalid(relativePath, "description 无效");
+  if (!["workspace", "none"].includes(value.connection)) invalid(relativePath, "connection 无效");
+  schema(value.configSchema, `${relativePath}.configSchema`);
+  if (!Array.isArray(value.outcomes) || value.outcomes.length < 1 || value.outcomes.length > 8) {
+    invalid(relativePath, "outcomes 必须包含 1–8 个静态出口");
+  }
+  const ids = new Set();
+  for (const [index, outcome] of value.outcomes.entries()) {
+    const path = `${relativePath}.outcomes[${index}]`;
+    object(outcome, path);
+    exactKeys(outcome, new Set(["id", "label", "dataSchema"]), path);
+    if (!ID.test(outcome.id) || ["in", "error"].includes(outcome.id) || ids.has(outcome.id)) {
+      invalid(path, "出口 ID 重复、保留或不合法");
+    }
+    ids.add(outcome.id);
+    if (typeof outcome.label !== "string" || outcome.label.length < 1 || outcome.label.length > 80) invalid(path, "label 无效");
+    if (outcome.dataSchema !== null) schema(outcome.dataSchema, `${path}.dataSchema`);
+  }
+  return Object.freeze({
+    ...value,
+    artifact: "server",
+    entry: `steps/${value.key}`,
+    relativePath,
+  });
+}

package/src/toolchain/workflow-triggers/manifest.js

@@ -0,0 +1,47 @@
+import { ZhikeCliError } from "../../errors.js";
+import { validateWorkflowStepDefinition } from "../workflow-steps/manifest.js";
+
+const HEADER = /^[a-z][a-z0-9-]{0,63}$/;
+const BLOCKED_HEADERS = new Set(["authorization", "cookie", "set-cookie", "host", "content-length"]);
+
+function invalid(path, detail) {
+  throw new ZhikeCliError("zhike_workflow_trigger_invalid", `${path}: ${detail}`);
+}
+
+export function validateWorkflowTriggerDefinition(value, relativePath, fileKey) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+    Object.keys(value).some(key => !["key", "title", "description", "connection", "requestHeaders", "configSchema", "outcomes"].includes(key))) {
+    invalid(relativePath, "Trigger 声明字段无效");
+  }
+  let common;
+  try {
+    const { requestHeaders, ...stepShape } = value;
+    common = validateWorkflowStepDefinition(stepShape, relativePath, fileKey);
+  } catch (error) {
+    invalid(relativePath, error.message || "schema 无效");
+  }
+  if (value.outcomes.some(outcome => outcome.dataSchema === null)) {
+    invalid(relativePath, "Trigger 的每个出口必须声明数据 schema");
+  }
+  const requestHeaders = value.requestHeaders ?? [];
+  if (!Array.isArray(requestHeaders) || requestHeaders.length > 16 ||
+    requestHeaders.some(name => typeof name !== "string" || !HEADER.test(name) ||
+      BLOCKED_HEADERS.has(name) || name.startsWith("x-forwarded-") || name.startsWith("proxy-")) ||
+    new Set(requestHeaders).size !== requestHeaders.length) {
+    invalid(relativePath, "requestHeaders 必须是至多 16 个唯一的安全小写名称");
+  }
+  return Object.freeze({
+    key: common.key, title: common.title,
+    ...(common.description === undefined ? {} : { description: common.description }),
+    connection: common.connection,
+    configSchema: common.configSchema,
+    outcomes: common.outcomes,
+    requestHeaders: Object.freeze([...requestHeaders]),
+    entries: Object.freeze({
+      activate: `triggers/${common.key}/activate`,
+      onEvent: `triggers/${common.key}/onEvent`,
+      deactivate: `triggers/${common.key}/deactivate`,
+    }),
+    relativePath,
+  });
+}

package/src/ui/components.generated.js

@@ -0,0 +1,5 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+export const componentTypes = Object.freeze(["NativeDOM","Icon","Stack","SplitLayout","SplitLayoutMain","SplitLayoutAside","SplitLayoutActions","Section","Banner","Badge","LoadingState","Skeleton","Card","Grid","EmptyState","ZhikeLink","Button","SearchInput","FilterSelect","Switch","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell","Avatar","DescriptionList","DescriptionListItem","DescriptionListMenu","DescriptionListMenuItem","Divider","Chart","DashboardSurface","DashboardLayout","DashboardPanel","MetricReadout","AnalysisView","Json","Link","StatusBadge","TextBlock","TypographyTitle","TypographyBody","TypographyCaption","TableHeaderCell","WidgetTextWidget","WidgetTitle","WidgetTextPrimary","WidgetTextSecondary","WidgetLoading","WidgetDecoration"]);
+export const publicComponentNames = Object.freeze(["NativeDOM","Icon","Stack","SplitLayout","SplitLayoutMain","SplitLayoutAside","SplitLayoutActions","Section","Banner","Badge","LoadingState","Skeleton","Card","Grid","EmptyState","ZhikeLink","Button","SearchInput","FilterSelect","Switch","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell","Avatar","DescriptionList","DescriptionListItem","DescriptionListMenu","DescriptionListMenuItem","Divider","Chart","DashboardSurface","DashboardLayout","DashboardPanel","MetricReadout","AnalysisView","Json","Link","StatusBadge","TextBlock","TypographyTitle","TypographyBody","TypographyCaption","TableHeaderCell","WidgetTextWidget","WidgetTitle","WidgetTextPrimary","WidgetTextSecondary","WidgetLoading","WidgetDecoration"]);
+export const legacyComponentTypes = Object.freeze(["NativeDOM","Text","Icon","Stack","SplitLayout","SplitLayoutMain","SplitLayoutAside","SplitLayoutActions","Section","Banner","Badge","LoadingState","Skeleton","Card","Grid","EmptyState","ZhikeLink","Button","SearchInput","FilterSelect","Switch","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell","Avatar","DescriptionList","DescriptionListItem","DescriptionListMenu","DescriptionListMenuItem","Divider","Chart","DashboardSurface","DashboardLayout","DashboardPanel","MetricReadout","AnalysisView","Json","Link","StatusBadge","TextBlock","TypographyTitle","TypographyBody","TypographyCaption","TableHeaderCell","WidgetTextWidget","WidgetTitle","WidgetTextPrimary","WidgetTextSecondary","WidgetLoading","WidgetDecoration"]);
+export const badgeColors = Object.freeze(["amber","blue","cyan","green","grey","lavender","lime","orange","pink","purple","red","yellow"]);

package/src/ui/events.d.ts

@@ -0,0 +1,10 @@
+/** Host 提取的 JSON 参数，不包含 DOM 节点或同步取消方法。 */
+export interface AppKeyboardEvent {
+  key: string;
+  code: string;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  repeat: boolean;
+}

package/src/ui/factory.js

@@ -0,0 +1,70 @@
+import { componentTypes, legacyComponentTypes } from './components.generated.js';
+import { useNormalizedOptions } from '../forms/normalize-options.js';
+import { assertExternalUrl } from '../client/external-url.js';
+import { assertBannerActions, assertJsonValue, assertChartData, assertChartSelection, assertAnalysisViewData } from './validation.js';
+import { assertNativeStyles } from './native-dom.js';
+
+export function createUiComponents(React, { legacy = false, useOwner = () => null, openExternal = () => Promise.reject(new Error('runtime_host_interaction_unavailable')) } = {}) {
+  const TabValue = React.createContext(null);
+  const components = Object.fromEntries((legacy ? legacyComponentTypes : componentTypes).map(type => [type, function RemoteComponent(props) {
+    if (type === 'NativeDOM' && props.styles !== undefined) assertNativeStyles(props.styles);
+    if (!legacy && type === 'TextBlock') return React.createElement(type, { ...props, align: props.align ?? 'left' });
+    if (!legacy && type === 'Badge' && props.tone !== undefined) throw new Error('Badge.tone 已移除，请使用 StatusBadge');
+    if (type === 'Avatar') {
+      const { src, ...rest } = props;
+      return React.createElement(type, { ...rest, ...(src == null ? {} : { src: assertExternalUrl(src) }) });
+    }
+    if (type === 'AnalysisView') { assertAnalysisViewData(props.asset, props.result); return React.createElement(type, props); }
+    if (type === 'Chart') { assertChartData(props.data); assertChartSelection(props); return React.createElement(type, props); }
+    if (type === 'Json') {
+      assertJsonValue(props.data);
+      return React.createElement(type, props);
+    }
+    if (type === 'Banner') {
+      const { actions, onAction, ...rest } = props;
+      if (onAction !== undefined || (actions !== undefined && !Array.isArray(actions))) throw new Error('runtime_ui_contract_invalid');
+      if (!actions?.length) return React.createElement(type, rest);
+      // 显式复制 metadata 和 handler；调用期间 App 原地修改数组不能重定向旧动作。
+      const data = actions.map(action => ({ label: action.label, variant: action.variant }));
+      const handlers = actions.map(action => action.onTrigger);
+      assertBannerActions(data);
+      if (handlers.some(handler => typeof handler !== 'function')) throw new Error('runtime_ui_contract_invalid');
+      return React.createElement(type, { ...rest, actions: data, onAction(index) {
+        if (!Number.isSafeInteger(index) || index < 0 || index >= handlers.length) throw new Error('runtime_ui_contract_invalid');
+        return handlers[index]();
+      } });
+    }
+    if (type === 'Link') {
+      const owner = useOwner();
+      const { href: input, onOpen, ...rest } = props;
+      if (onOpen !== undefined) throw new Error('runtime_ui_contract_invalid');
+      const href = assertExternalUrl(input);
+      return React.createElement(type, { ...rest, href, onOpen: () => openExternal(owner, href) });
+    }
+    if (type === 'Tabs') return React.createElement(TabValue.Provider, { value: props.value }, React.createElement(type, props));
+    if (type === 'TabsContent') {
+      const value = React.useContext(TabValue);
+      return value === props.value ? React.createElement(type, props) : null;
+    }
+    if (type === 'LookupCell') {
+      const { options, value, onCommit, ...rest } = props;
+      const normalized = useNormalizedOptions(React, options);
+      return React.createElement(type, { ...rest, ...normalized, value: value ?? '', onCommit });
+    }
+    return React.createElement(type, props);
+  }]));
+  Object.assign(components.DescriptionList, { Item: components.DescriptionListItem, Menu: components.DescriptionListMenu });
+  components.DescriptionListMenu.Item = components.DescriptionListMenuItem;
+  Object.assign(components.Table, { Header: components.TableHeader, HeaderCell: components.TableHeaderCell, Body: components.TableBody, Row: components.TableRow, Cell: components.TableCell });
+  Object.assign(components.TableCell, { Avatar: components.Avatar, Badge: components.Badge });
+  Object.assign(components.SplitLayout, { Main: components.SplitLayoutMain, Aside: components.SplitLayoutAside, Actions: components.SplitLayoutActions });
+  components.Typography = Object.freeze({ Title: components.TypographyTitle, Body: components.TypographyBody, Caption: components.TypographyCaption });
+  components.Widget = Object.freeze({
+    TextWidget: components.WidgetTextWidget,
+    Title: components.WidgetTitle,
+    Text: Object.freeze({ Primary: components.WidgetTextPrimary, Secondary: components.WidgetTextSecondary }),
+    Loading: components.WidgetLoading,
+    Decoration: components.WidgetDecoration,
+  });
+  return components;
+}