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

package/src/cli/local-commands.js

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+import { loadCliConfig } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+
+const metadata = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+export const commandHelp = {
+  help: "help [command] [--json]",
+  version: "version [--json]",
+  doctor: "doctor [--json]",
+  login: "login",
+  init: "init <app-slug>",
+  build: "build",
+  upload: "upload",
+  dev: "dev [--workspace <workspace-id>]",
+};
+
+export function localEnvelope(data, status = "completed") {
+  return { schemaVersion: 1, status, target: null, data,
+    effects: { business: "none", authentication: "none" }, error: null, nextAction: null };
+}
+
+/** 本地诊断不调用认证、网络或项目脚本；依赖仅解析路径，不执行包代码。 */
+export async function runLocalCommand(command, args, { cwd, environment }) {
+  if (command === "help") {
+    if (args.length > 1 || (args.length && !Object.hasOwn(commandHelp, args[0]))) {
+      throw new ZhikeCliError("zhike_help_usage_invalid", "用法：help [command] [--json]");
+    }
+    return localEnvelope({ commands: args.length ? { [args[0]]: commandHelp[args[0]] } : commandHelp,
+      jsonCommands: ["help", "version", "doctor"] });
+  }
+  if (args.length) throw new ZhikeCliError("zhike_arguments_invalid", "当前命令不接受额外参数");
+  if (command === "version") return localEnvelope({ package: metadata.name, version: metadata.version,
+    node: process.version, requiredNode: metadata.engines.node });
+
+  const checks = [];
+  checks.push({ name: "node", ok: Number(process.versions.node.split(".")[0]) >= 20,
+    required: metadata.engines.node, actual: process.version });
+  let config;
+  try {
+    config = loadCliConfig(environment);
+    checks.push({ name: "environment", ok: true, source: "configuration", ...config });
+  } catch (error) {
+    checks.push({ name: "environment", ok: false, code: error.code });
+  }
+  let binding;
+  try {
+    binding = await readProjectBinding(cwd, config?.apiBaseUrl);
+    checks.push({ name: "binding", ok: Boolean(config), appId: binding.appId });
+  } catch (error) {
+    checks.push({ name: "binding", ok: false, code: error.code });
+  }
+  try {
+    const pkg = JSON.parse(await readFile(resolve(cwd, "package.json"), "utf8"));
+    const require = createRequire(resolve(cwd, "package.json"));
+    const dependencies = { ...pkg.dependencies, ...pkg.devDependencies };
+    const sdkDeclared = Boolean(dependencies["@77-zhike/app-sdk"]);
+    checks.push({ name: "sdkDeclaration", ok: sdkDeclared });
+    for (const name of Object.keys(dependencies)) {
+      try {
+        require.resolve(name);
+        checks.push({ name: "dependency", package: name, ok: true });
+      } catch {
+        checks.push({ name: "dependency", package: name, ok: false, code: "dependency_unresolved" });
+      }
+    }
+  } catch {
+    checks.push({ name: "package", ok: false, code: "package_missing_or_invalid" });
+  }
+  checks.push({ name: "secureStore", ok: process.platform === "darwin", platform: process.platform });
+  const result = localEnvelope({ localReady: checks.every((check) => check.ok),
+    authentication: "not_checked", installation: "not_checked", checks });
+  result.target = config ? { environment: config.apiBaseUrl, appId: binding?.appId ?? null } : null;
+  return result;
+}

package/src/cli/project-init.js

@@ -0,0 +1,371 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  access,
+  mkdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+import { TOOLING_VERSION } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { serializeProjectBinding } from "../project-binding.js";
+
+export async function initializeProject({
+  targetDirectory,
+  appSlug,
+  apiBaseUrl,
+  authenticatedApi,
+  scaffold = scaffoldProject,
+}) {
+  validateAppSlug(appSlug);
+  const target = resolve(targetDirectory);
+  await assertEmptyTarget(target);
+
+  const organizations = await authenticatedApi.listOrganizations();
+  if (!Array.isArray(organizations) || organizations.length !== 1) {
+    throw new ZhikeCliError(
+      "zhike_developer_organization_unavailable",
+      organizations?.length === 0
+        ? "请先在 Developer Console 激活开发者组织"
+        : "当前账号存在多个开发者组织，D2-2 暂不支持隐式选择",
+    );
+  }
+  const organization = organizations[0];
+  let app = await authenticatedApi.getAppBySlug(organization.id, appSlug);
+  let created = false;
+  if (!app) {
+    app = await authenticatedApi.createApp(organization.id, {
+      name: displayNameFromSlug(appSlug),
+      slug: appSlug,
+      idempotencyKey: createInitIdempotencyKey({
+        apiBaseUrl,
+        organizationId: organization.id,
+        appSlug,
+      }),
+    });
+    created = true;
+  }
+  const binding = {
+    schemaVersion: 1,
+    platformEnvironment: apiBaseUrl,
+    appId: app.id,
+    organizationId: organization.id,
+    appSlug: app.slug,
+  };
+  await scaffold({ targetDirectory: target, binding });
+  return { app, organization, binding, created, targetDirectory: target };
+}
+
+export async function assertEmptyTarget(targetDirectory) {
+  try {
+    await stat(targetDirectory);
+    throw new ZhikeCliError(
+      "zhike_target_exists",
+      `目标路径已存在：${basename(targetDirectory)}`,
+    );
+  } catch (error) {
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    if (error?.code !== "ENOENT") {
+      throw new ZhikeCliError(
+        "zhike_target_check_failed",
+        "无法检查项目目标路径",
+        { cause: error },
+      );
+    }
+  }
+  try {
+    await access(dirname(targetDirectory), constants.W_OK);
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_target_parent_not_writable",
+      "项目目标路径的父目录不可写",
+      { cause: error },
+    );
+  }
+}
+
+export async function scaffoldProject({ targetDirectory, binding }) {
+  const temporaryDirectory = `${targetDirectory}.zhike-tmp-${randomBytes(6).toString("hex")}`;
+  try {
+    await mkdir(resolve(temporaryDirectory, ".zhike"), { recursive: true });
+    await mkdir(
+      resolve(temporaryDirectory, "src", "app", "extensions", "customer-action"),
+      { recursive: true },
+    );
+    await mkdir(resolve(temporaryDirectory, "src", "app", "webhooks"), {
+      recursive: true,
+    });
+    await mkdir(resolve(temporaryDirectory, "src", "app", "events"), {
+      recursive: true,
+    });
+    await mkdir(resolve(temporaryDirectory, "src", "server", "functions"), {
+      recursive: true,
+    });
+    await writeFile(
+      resolve(temporaryDirectory, ".zhike", "project.json"),
+      serializeProjectBinding(binding),
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, "package.json"),
+      `${JSON.stringify(
+        {
+          name: binding.appSlug,
+          private: true,
+          version: "0.0.0",
+          type: "module",
+          scripts: {
+            zhike: "zhike",
+            build: "zhike build",
+            dev: "zhike dev",
+            upload: "zhike upload",
+            "validate:mock": "zhike experimental validate-bundle",
+          },
+          devDependencies: {
+            "@77-zhike/app-sdk": TOOLING_VERSION,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "events",
+        "app-installed.event.ts",
+      ),
+      `import { createWebhookHandler, ZHIKE_API_TOKEN, kv } from "@77-zhike/app-sdk/server";
+
+export default async function appInstalled() {
+  const handler = await createWebhookHandler({ fileName: "qiqi-customer" });
+  const existing = await fetch("https://api-clm.77hub.com/v1/webhooks", {
+    headers: { authorization: \`Bearer \${ZHIKE_API_TOKEN}\` },
+  });
+  if (!existing.ok) throw new Error("webhook_list_failed");
+  const { items } = await existing.json() as { items: Array<{ subscriptions: Array<{ eventType: string }> }> };
+  const requiredEventTypes = ["record.created", "activity.updated"];
+  if (items.some((item) => requiredEventTypes.every((eventType) =>
+    item.subscriptions.some((subscription) => subscription.eventType === eventType)
+  ))) return;
+
+  const response = await fetch("https://api-clm.77hub.com/v1/webhooks", {
+    method: "POST",
+    headers: {
+      authorization: \`Bearer \${ZHIKE_API_TOKEN}\`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      targetUrl: handler.url,
+      subscriptions: [{
+        eventType: "record.created",
+        filter: { field: "id.objectSlug", operator: "equals", value: "accounts" },
+      }, {
+        eventType: "activity.updated",
+        filter: null,
+      }],
+    }),
+  });
+  if (!response.ok) throw new Error("webhook_create_failed");
+  const created = await response.json() as { webhook: { id: string }; secret: string };
+  await kv.set(
+    \`webhook:\${created.webhook.id}\`,
+    JSON.stringify({ webhookId: created.webhook.id, secret: created.secret }),
+  );
+}
+`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "events",
+        "app-uninstalled.event.ts",
+      ),
+      `import { deleteWebhookHandler, listWebhookHandlers, ZHIKE_API_TOKEN, kv } from "@77-zhike/app-sdk/server";\n\nexport default async function appUninstalled() {\n  const response = await fetch("https://api-clm.77hub.com/v1/webhooks", {\n    headers: { authorization: \`Bearer \${ZHIKE_API_TOKEN}\` },\n  });\n  if (!response.ok) throw new Error("webhook_list_failed");\n  const { items } = await response.json() as { items: Array<{ id: string }> };\n  for (const webhook of items) {\n    const deleted = await fetch(\`https://api-clm.77hub.com/v1/webhooks/\${webhook.id}\`, {\n      method: "DELETE",\n      headers: { authorization: \`Bearer \${ZHIKE_API_TOKEN}\` },\n    });\n    if (deleted.status !== 204 && deleted.status !== 404) throw new Error("webhook_delete_failed");\n    await kv.delete(\`webhook:\${webhook.id}\`);\n  }\n  for (const handler of await listWebhookHandlers()) {\n    await deleteWebhookHandler(handler.id);\n  }\n}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "events",
+        "connection-added.event.ts",
+      ),
+      `import { kv } from "@77-zhike/app-sdk/server";\nimport type { ConnectionAddedParams } from "@77-zhike/app-sdk/server";\n\nexport default async function connectionAdded({ connection }: ConnectionAddedParams) {\n  const stateKey = \`connection:\${connection.id}:\${connection.generation}:initialized\`;\n  if (await kv.get(stateKey)) return;\n  // 在这里调用外部 OpenAPI 创建订阅，再持久化供应商返回的引用。\n  await kv.set(stateKey, "initialized");\n}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "events",
+        "connection-removed.event.ts",
+      ),
+      `import { kv } from "@77-zhike/app-sdk/server";\nimport type { ConnectionRemovedParams } from "@77-zhike/app-sdk/server";\n\nexport default async function connectionRemoved({ connection }: ConnectionRemovedParams) {\n  const stateKey = \`connection:\${connection.id}:\${connection.generation}:initialized\`;\n  // 在这里读取供应商引用并调用外部 OpenAPI 删除订阅。\n  await kv.delete(stateKey);\n}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "extensions",
+        "customer-action",
+        "extension.tsx",
+      ),
+      `import { defineFrontendExtension } from "@77-zhike/app-sdk/client";\nimport createFollowUpTask from "../../../server/functions/create-follow-up-task.server";\n\nexport default defineFrontendExtension({\n  key: "customer-action",\n  type: "record-action",\n  label: "创建跟进任务",\n  icon: "refresh-cw",\n  objects: "accounts",\n  async onTrigger({ recordId }: { recordId: string }) {\n    await createFollowUpTask({ customerId: recordId });\n  },\n});\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "server",
+        "functions",
+        "create-follow-up-task.server.ts",
+      ),
+      `import { ZHIKE_API_TOKEN } from "@77-zhike/app-sdk/server";
+
+export default async function(input: { customerId: string }) {
+  const response = await fetch("https://api-clm.77hub.com/v1/tasks", {
+    method: "POST",
+    headers: {
+      authorization: \`Bearer \${ZHIKE_API_TOKEN}\`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      title: "跟进客户",
+      relatedRecords: [{ objectSlug: "accounts", recordId: input.customerId }],
+    }),
+  });
+  if (!response.ok) throw new Error("task_create_failed");
+  const task = await response.json() as { id: { taskId: string } };
+  return { taskId: task.id.taskId };
+}
+`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(
+        temporaryDirectory,
+        "src",
+        "app",
+        "webhooks",
+        "qiqi-customer.webhook.ts",
+      ),
+      `import { ZHIKE_API_TOKEN, kv } from "@77-zhike/app-sdk/server";
+import type { WorkspaceWebhookBody } from "@77-zhike/app-sdk/server";
+
+export default async function qiqiCustomer(request: Request) {
+  const idempotencyKey = request.headers.get("idempotency-key");
+  if (!idempotencyKey) throw new Error("webhook_idempotency_key_missing");
+  if (await kv.get(\`delivery:\${idempotencyKey}\`)) {
+    return new Response(null, { status: 200 });
+  }
+
+  const { events } = await request.json() as WorkspaceWebhookBody;
+  for (const event of events) {
+    if (event.eventType === "activity.updated") {
+      const response = await fetch(
+        \`https://api-clm.77hub.com/v1/activities/\${encodeURIComponent(event.id.activityId)}\`,
+        { headers: { authorization: \`Bearer \${ZHIKE_API_TOKEN}\` } },
+      );
+      if (!response.ok) throw new Error("activity_read_failed");
+      const activity = await response.json();
+      console.log("[qiqi-customer] current activity", activity);
+      continue;
+    }
+    if (event.eventType !== "record.created" || event.id.objectSlug !== "accounts") continue;
+    const response = await fetch(
+      \`https://api-clm.77hub.com/v1/objects/\${event.id.objectSlug}/records/\${event.id.recordId}\`,
+      { headers: { authorization: \`Bearer \${ZHIKE_API_TOKEN}\` } },
+    );
+    if (!response.ok) throw new Error("record_read_failed");
+    const record = await response.json();
+    console.log("[qiqi-customer] current record values", record.values);
+  }
+
+  await kv.set(\`delivery:\${idempotencyKey}\`, "completed", { ttlInSeconds: 172800 });
+  return new Response(null, { status: 200 });
+}
+`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, "tsconfig.json"),
+      `${JSON.stringify(
+        {
+          compilerOptions: {
+            lib: ["ES2022", "DOM"],
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            noEmit: true,
+            strict: true,
+            target: "ES2022",
+          },
+          include: ["src"],
+        },
+        null,
+        2,
+      )}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, ".gitignore"),
+      "dist/\n.zhike/development.json\n",
+      { flag: "wx" },
+    );
+    await rename(temporaryDirectory, targetDirectory);
+  } catch (error) {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    throw new ZhikeCliError(
+      "zhike_scaffold_failed",
+      "App 已确认，但本地项目生成失败；修复文件系统问题后可安全重试",
+      { cause: error, retryable: true },
+    );
+  }
+}
+
+export function createInitIdempotencyKey({
+  apiBaseUrl,
+  organizationId,
+  appSlug,
+}) {
+  return `init-${createHash("sha256")
+    .update(`${apiBaseUrl}\n${organizationId}\n${appSlug}`, "utf8")
+    .digest("hex")}`;
+}
+
+export function displayNameFromSlug(slug) {
+  return slug
+    .split("-")
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+export function validateAppSlug(value) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value || "") || value.length > 100) {
+    throw new ZhikeCliError(
+      "zhike_app_slug_invalid",
+      "App slug 只能包含小写字母、数字和中划线",
+    );
+  }
+  return value;
+}

package/src/cli/upload-bundle.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+import { buildAppBundle } from "../toolchain/real-build.js";
+
+export async function uploadAppBundle({
+  projectDirectory,
+  apiBaseUrl,
+  authenticatedApi,
+  maxAttempts = 2,
+  expectedScopeRevision,
+}) {
+  const bundle = await buildAppBundle({
+    projectDirectory,
+    expectedEnvironment: apiBaseUrl,
+    writeToDist: true,
+    development: true,
+  });
+  const binding = await readProjectBinding(projectDirectory, apiBaseUrl);
+  const idempotencyKey = `bundle-${randomUUID()}`;
+  let attempt = 0;
+  let upload = null;
+  while (attempt < maxAttempts) {
+    attempt += 1;
+    try {
+      upload = await authenticatedApi.uploadBundle(
+        binding.appId,
+        bundle,
+        idempotencyKey,
+      );
+      break;
+    } catch (error) {
+      if (!error?.retryable || attempt >= maxAttempts) throw error;
+    }
+  }
+  if (!upload || upload.status !== "accepted" || !upload.app_bundle_id) {
+    throw new ZhikeCliError(
+      "zhike_bundle_acceptance_invalid",
+      "Developer Server 未返回可激活的 App Bundle",
+    );
+  }
+
+  let developmentManifest = null;
+  let manifestAttempts = 0;
+  while (manifestAttempts < maxAttempts) {
+    manifestAttempts += 1;
+    try {
+      developmentManifest = await authenticatedApi.updateDevelopmentManifest(
+        binding.appId, upload.app_bundle_id, expectedScopeRevision,
+      );
+      break;
+    } catch (error) {
+      if (error?.retryable && manifestAttempts < maxAttempts) continue;
+      const partial = new ZhikeCliError(
+        "zhike_bundle_accepted_manifest_update_failed",
+        `Bundle ${upload.id} 已受理，但当前 Development Manifest 更新失败：${error.message}`,
+        { cause: error, retryable: error.retryable ?? false },
+      );
+      partial.acceptedUploadId = upload.id;
+      partial.acceptedAppBundleId = upload.app_bundle_id;
+      throw partial;
+    }
+  }
+  return {
+    artifact: bundle,
+    binding,
+    upload,
+    developmentManifest,
+    attempts: attempt,
+    manifestAttempts,
+  };
+}

package/src/cli/validate-bundle.js

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+
+import { readProjectBinding } from "../project-binding.js";
+import { buildMockArtifact } from "../toolchain/index.js";
+
+export async function validateBundleUpload({
+  projectDirectory,
+  apiBaseUrl,
+  authenticatedApi,
+  maxAttempts = 2,
+}) {
+  const artifact = await buildMockArtifact({
+    projectDirectory,
+    expectedEnvironment: apiBaseUrl,
+    writeToDist: true,
+  });
+  const binding = await readProjectBinding(projectDirectory, apiBaseUrl);
+  const idempotencyKey = `validate-${randomUUID()}`;
+  let attempt = 0;
+  while (attempt < maxAttempts) {
+    attempt += 1;
+    try {
+      const upload = await authenticatedApi.uploadBundle(
+        binding.appId,
+        artifact,
+        idempotencyKey,
+      );
+      return { artifact, binding, upload, attempts: attempt };
+    } catch (error) {
+      if (!error?.retryable || attempt >= maxAttempts) {
+        throw error;
+      }
+    }
+  }
+  throw new Error("unreachable");
+}

package/src/client/index.d.ts

@@ -0,0 +1,52 @@
+import type { ComponentType } from "react";
+import type { AppIconName } from "../ui/index.js";
+
+/** Settings 只声明组件，表单状态不代表持久化配置。 */
+export interface SettingsExtensionDefinition {
+  key: string;
+  type: "settings";
+  component: ComponentType;
+  handler?: never;
+}
+
+/** 当前对象详情提供的公开记录身份；不能作为服务端授权凭据。 */
+export interface RecordActionContext {
+  /** 当前记录的公开 ID。 */
+  recordId: string;
+  /** 当前对象的公开 API slug。 */
+  object: string;
+}
+
+/** 在通用记录详情菜单中贡献一个操作。 */
+export interface RecordActionDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "record-action";
+  /** 菜单中展示的操作名称。 */
+  label: string;
+  /** 统一 SDK 图标目录中的名称。 */
+  icon?: AppIconName;
+  /** 省略时匹配所有能提供公开身份的记录对象。 */
+  objects?: string | readonly string[];
+  /** 用户触发操作时执行；成功无需返回值。 */
+  onTrigger(context: RecordActionContext): void | Promise<void>;
+  component?: never;
+  handler?: never;
+}
+export type FrontendExtensionDefinition =
+  | SettingsExtensionDefinition
+  | RecordActionDefinition;
+
+export function defineFrontendExtension(
+  definition: SettingsExtensionDefinition,
+): Readonly<SettingsExtensionDefinition>;
+export function defineFrontendExtension(
+  definition: RecordActionDefinition,
+): Readonly<RecordActionDefinition>;
+
+export type { AppIconName } from "../ui/index.js";
+export type { ToastOptions, ConfirmOptions } from './interactions.js';
+/** 受管结果提示；不接收 HTML，回调完成后可继续显示，Workspace 会话结束时清理。 */
+export function showToast(options: import('./interactions.js').ToastOptions): Promise<void>;
+/** 用户取消返回 false；所属页面关闭时拒绝，不能当作确认。 */
+export function confirm(options: import('./interactions.js').ConfirmOptions): Promise<boolean>;

package/src/client/index.js

@@ -0,0 +1,22 @@
+import { frontendPoint } from './points.generated.js';
+const FRONTEND_EXTENSION_MARKER = Symbol.for("zhike.frontend-extension.v1");
+
+export function defineFrontendExtension(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("Frontend Extension definition 必须是对象");
+  }
+  const point = frontendPoint(definition.type);
+  if (!point) {
+    throw new TypeError("Frontend Extension type 不受支持");
+  }
+  const property = point.kind === "view" ? "component" : (point.callbackName || "handler");
+  const forbidden = point.kind === "view" ? ["handler", "onTrigger"] : ["component", ...(property === "handler" ? ["onTrigger"] : ["handler"])];
+  if (typeof definition[property] !== "function" || forbidden.some(name => name in definition)) {
+    throw new TypeError(`Frontend Extension 必须只提供 ${property} 函数`);
+  }
+  return Object.freeze({ ...definition, [FRONTEND_EXTENSION_MARKER]: true });
+}
+
+// 受管 Guest 注入实际请求出口；脱离前端运行环境不能调用产品交互。
+export function showToast() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function confirm() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }

package/src/client/interactions.d.ts

@@ -0,0 +1,8 @@
+export interface ToastOptions { message: string; tone?: 'info' | 'success' | 'error' }
+export interface ConfirmOptions { title: string; description?: string; confirmLabel?: string; cancelLabel?: string }
+export type HostInteraction = {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions};
+export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions>;
+export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions) => Promise<unknown>): {
+  showToast(input: ToastOptions): Promise<void>;
+  confirm(input: ConfirmOptions): Promise<boolean>;
+};

package/src/client/interactions.js

@@ -0,0 +1,23 @@
+const fail = () => { throw new Error('runtime_interaction_invalid'); };
+const text = (value, max, required = false) => value === undefined ? !required : typeof value === 'string' && value.length <= max && (!required || value.length > 0);
+export function assertHostInteraction(operation, input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
+  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : [];
+  if (!allowed.length || Object.keys(input).some(key=>!allowed.includes(key))) fail();
+  if (operation === 'showToast') {
+    if (!text(input.message,500,true) || (input.tone !== undefined && !['info','success','error'].includes(input.tone))) fail();
+  } else if (!text(input.title,200,true) || !text(input.description,2000) || !text(input.confirmLabel,60) || !text(input.cancelLabel,60)) fail();
+  return Object.freeze(Object.fromEntries(Object.entries(input).filter(([,value])=>value!==undefined)));
+}
+export function createClientInteractions(invoke) {
+  return Object.freeze({
+    showToast(input) {
+      const request = assertHostInteraction('showToast',input);
+      return invoke('showToast',request).then(value=>{if(value!==null)fail();});
+    },
+    confirm(input) {
+      const request = assertHostInteraction('confirm',input);
+      return invoke('confirm',request).then(value=>{if(typeof value!=='boolean')fail();return value;});
+    },
+  });
+}