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

package/src/client/index.d.ts

@@ -1,6 +1,13 @@
 import type { ComponentType } from "react";
 import type { AppIconName } from "../ui/index.js";
 
+/** SDK Record 扩展明确开放的产品对象；任务、跟进记录和笔记不属于此合同。 */
+export type RecordExtensionObject =
+  | "accounts"
+  | "contacts"
+  | "opportunities"
+  | `custom_${string}`;
+
 /** Settings 只声明组件，表单状态不代表持久化配置。 */
 export interface SettingsExtensionDefinition {
   key: string;
@@ -14,7 +21,7 @@ export interface RecordActionContext {
   /** 当前记录的公开 ID。 */
   recordId: string;
   /** 当前对象的公开 API slug。 */
-  object: string;
+  object: RecordExtensionObject;
 }
 
 /** 在通用记录详情菜单中贡献一个操作。 */
@@ -27,15 +34,161 @@ export interface RecordActionDefinition {
   /** 统一 SDK 图标目录中的名称。 */
   icon?: AppIconName;
   /** 省略时匹配所有能提供公开身份的记录对象。 */
-  objects?: string | readonly string[];
+  objects?: RecordExtensionObject | readonly RecordExtensionObject[];
   /** 用户触发操作时执行；成功无需返回值。 */
   onTrigger(context: RecordActionContext): void | Promise<void>;
   component?: never;
   handler?: never;
 }
+
+/** 当前对象列表提供的公开对象身份；不包含查询、权限或原生 mutation 身份。 */
+export interface ObjectActionContext {
+  /** 当前对象的公开 API slug。 */
+  object: RecordExtensionObject;
+}
+
+/** 在对象列表右上角菜单中贡献一个操作。 */
+export interface ObjectActionDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "object-action";
+  /** 菜单中展示的操作名称。 */
+  label: string;
+  /** 统一 SDK 图标目录中的名称。 */
+  icon?: AppIconName;
+  /** 省略时匹配所有能提供公开身份的对象列表。 */
+  objects?: RecordExtensionObject | readonly RecordExtensionObject[];
+  /** 用户触发操作时执行；成功无需返回值。 */
+  onTrigger(context: ObjectActionContext): void | Promise<void>;
+  component?: never;
+  handler?: never;
+}
+
+/** 当前显式选择快照；只暴露公开对象和 1..100 个 Record ID。 */
+export interface BulkRecordActionContext {
+  /** 当前对象的公开 API slug。 */
+  object: RecordExtensionObject;
+  /** 点击瞬间冻结的公开 Record ID，保持当前页可见顺序。 */
+  recordIds: readonly string[];
+}
+
+/** 在对象列表选择模式中贡献一个批量操作。 */
+export interface BulkRecordActionDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "bulk-record-action";
+  /** 菜单中展示的操作名称。 */
+  label: string;
+  /** 统一 SDK 图标目录中的名称。 */
+  icon?: AppIconName;
+  /** 省略时匹配所有支持显式多选的公开对象列表。 */
+  objects?: RecordExtensionObject | readonly RecordExtensionObject[];
+  /** 用户触发操作时执行；成功无需返回值。 */
+  onTrigger(context: BulkRecordActionContext): void | Promise<void>;
+  component?: never;
+  handler?: never;
+}
+
+/** Record Page 组件获得的公开记录身份；不能作为服务端授权凭据。 */
+export interface RecordComponentProps {
+  /** 当前对象的公开 API slug。 */
+  readonly object: RecordExtensionObject;
+  /** 当前记录的公开 ID。 */
+  readonly recordId: string;
+}
+
+/** 在记录概览的重点信息卡片容器中贡献一个小卡片 Widget。 */
+export interface RecordWidgetDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "record-widget";
+  /** Widget 标题，trim 后最多 80 个 Unicode code points。 */
+  label: string;
+  /** 省略时匹配客户、联系人、商机和全部自定义对象。 */
+  objects?: readonly RecordExtensionObject[];
+  /** 纯 React Widget 正文，只接收公开记录身份；卡片外框由 Host 提供。 */
+  Widget: ComponentType<RecordComponentProps>;
+  component?: never;
+  handler?: never;
+  onTrigger?: never;
+}
+
+/** 为 Record Page 贡献一个可由布局放入 Section 区域的受管组件。 */
+export interface RecordSectionDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "record-section";
+  /** Section 标题，trim 后最多 80 个 Unicode code points。 */
+  label: string;
+  /** 省略时匹配客户、联系人、商机和全部自定义对象。 */
+  objects?: readonly RecordExtensionObject[];
+  /** 纯 React Section 正文，只接收公开记录身份；标题与外框由 Host 提供。 */
+  Section: ComponentType<RecordComponentProps>;
+  component?: never;
+  handler?: never;
+  onTrigger?: never;
+}
+
+/** 在记录详情的产品 Tab 区域中贡献一个 Tab。 */
+export interface RecordTabDefinition {
+  /** App 内唯一 lowercase kebab-case key。 */
+  key: string;
+  type: "record-tab";
+  /** Tab 标题，trim 后最多 80 个 Unicode code points。 */
+  label: string;
+  /** 省略时匹配客户、联系人、商机和全部自定义对象。 */
+  objects?: readonly RecordExtensionObject[];
+  /** 纯 React Tab component，只接收公开记录身份。 */
+  Tab: ComponentType<RecordComponentProps>;
+  component?: never;
+  handler?: never;
+  onTrigger?: never;
+}
+
+export interface PageProps {
+  /** 当前地址的业务输入，缺省为空对象；不代表记录访问权。 */
+  readonly params: import('./destinations.js').PageParams;
+}
+
+/** Workspace Page 不接收宿主路由或身份；导航只能通过 SDK 能力发起。 */
+export interface PageDefinition {
+  /** Apps 菜单和 Page 标题使用的名称。 */
+  name: string;
+  /** Apps 导航图标，必须来自 SDK 统一图标目录；省略时保留宿主默认图标。 */
+  icon?: AppIconName;
+  /** 有值的 Page 优先按数值排序；缺失时按 slug 稳定排序。 */
+  order?: number;
+  /** Page 自身的产品布局语义，不选择 Dialog、Sheet 或 Sidebar。 */
+  variant: "full" | "centered";
+  /** 缺省可见；只影响 Apps 菜单，不改变页面授权或可访问性。 */
+  showInNavigation?: boolean;
+  /** 默认显示宿主标题栏；false 时由 Page 自行提供标题。移动端仍保留返回导航。 */
+  showHeader?: boolean;
+  /** 缺省 false，按内容自然滚动；true 由宿主提供扣除导航后的确定高度，内部滚动由 Page 布局负责。 */
+  fillHeight?: boolean;
+  /** 纯 React Page component，只接收有界业务参数。 */
+  Page: ComponentType<PageProps>;
+}
+
+export type DefinedPage = Readonly<PageDefinition & { type: "page" }>;
+/** 结果来自同次已校验 Action；身份与导航 owner 由 Host 绑定。 */
+export interface ToolRendererProps<Result = unknown> {
+  readonly result: Result;
+  readonly actionKey: string;
+}
+export interface ToolRendererDefinition<Result = unknown> {
+  key: string;
+  Renderer: ComponentType<ToolRendererProps<Result>>;
+}
+export function defineToolRenderer<Result>(definition: ToolRendererDefinition<Result>): Readonly<ToolRendererDefinition<Result> & { type: 'tool-renderer' }>;
 export type FrontendExtensionDefinition =
   | SettingsExtensionDefinition
-  | RecordActionDefinition;
+  | RecordActionDefinition
+  | ObjectActionDefinition
+  | BulkRecordActionDefinition
+  | RecordWidgetDefinition
+  | RecordSectionDefinition
+  | RecordTabDefinition;
 
 export function defineFrontendExtension(
   definition: SettingsExtensionDefinition,
@@ -43,10 +196,79 @@ export function defineFrontendExtension(
 export function defineFrontendExtension(
   definition: RecordActionDefinition,
 ): Readonly<RecordActionDefinition>;
+export function defineFrontendExtension(
+  definition: ObjectActionDefinition,
+): Readonly<ObjectActionDefinition>;
+export function defineFrontendExtension(
+  definition: BulkRecordActionDefinition,
+): Readonly<BulkRecordActionDefinition>;
+export function defineFrontendExtension(
+  definition: RecordWidgetDefinition,
+): Readonly<RecordWidgetDefinition>;
+export function defineFrontendExtension(
+  definition: RecordSectionDefinition,
+): Readonly<RecordSectionDefinition>;
+export function defineFrontendExtension(
+  definition: RecordTabDefinition,
+): Readonly<RecordTabDefinition>;
+
+/** 声明一个由约定目录提供 slug 的 Workspace Page。 */
+export function definePage(definition: PageDefinition): DefinedPage;
 
 export type { AppIconName } from "../ui/index.js";
+export { Destinations } from './destinations.js';
+export type { AppDestination, AppPageDestination, RecordDestination, PageParams } from './destinations.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>;
+/** Page view 可用；RecordAction invocation 仅可打开同 App Page。Dialog 不可直接导航。 */
+export function navigate(destination: import('./destinations.js').AppDestination): Promise<void>;
+
+export interface DialogProps {
+  /** 只关闭当前 Dialog；重复调用无效果，不代表保存或回滚。 */
+  hideDialog(): void;
+}
+export interface DialogOptions {
+  /** 宿主固定标题，去空白后 1～200 字符。 */
+  title: string;
+  /** 默认保持原宽度；wide 为宽版，content 按内容固有宽度展开并受视口约束。Mobile 均为全屏 Sheet。 */
+  size?: 'default' | 'wide' | 'content';
+  Dialog: ComponentType<DialogProps>;
+}
+/** 从有效 Action/UI 回调打开；普通关闭完成，失效/失败拒绝，不支持嵌套。 */
+export function showDialog(options: DialogOptions): Promise<void>;
+/**
+ * 由 Web Host 在新页签打开绝对 HTTPS URL；不返回窗口或远端加载状态。
+ * @platform Web
+ */
+export function openExternalUrl(url: string): Promise<void>;
+
+/** 当前用户在当前 Workspace 内的成员快照。 */
+export interface CurrentUser {
+  /** Workspace 成员 ID；不是平台全局 User ID。 */
+  workspaceMemberId: string;
+  displayName: string;
+  primaryEmailAddress: string | null;
+  avatarUrl: string | null;
+}
+
+/** 同步读取当前前端 Workspace 会话的成员快照。 */
+export function getCurrentUser(): Readonly<CurrentUser>;
+
+export type { AnalysisRequest } from './analysis.js';
+/** 当前打开页面成员的获权分析；仅 App Page 可用，不获取登录凭据。 */
+export function queryAnalysis(request: import('./analysis.js').AnalysisRequest): Promise<import('../ui/index.js').JsonValue>;
+export type { OpenAssistantOptions } from './interactions.js';
+/** 打开侧边助手；首次发言才调用模型，context 仅作为新会话初始背景。 */
+export function openAssistant(options: import('./interactions.js').OpenAssistantOptions): Promise<void>;
+
+export type { RestrictedInputSchema, PreparePdfTemplateInput, OpenPdfDocumentInput, PreparedPdfTemplate, OpenPdfDocumentResult } from './documents.js';
+/** Desktop制作；取消返回null。缺能力或旧Host返回runtime_document_unsupported。 */
+export function preparePdfTemplate(input: import('./documents.js').PreparePdfTemplateInput): Promise<import('./documents.js').PreparedPdfTemplate | null>;
+/** Desktop/H5认证文件交付；started只表示已交浏览器，不证明磁盘保存。 */
+export function openPdfDocument(input: import('./documents.js').OpenPdfDocumentInput): Promise<import('./documents.js').OpenPdfDocumentResult>;
+
+/** 以当前成员权限打开稳定报告产物；宿主控制预览，不执行App提供的HTML。 */
+export function openArtifact(input: import('./interactions.js').OpenArtifactOptions): Promise<void>;

package/src/client/index.js

@@ -1,22 +1,94 @@
 import { frontendPoint } from './points.generated.js';
+import { sdkIconNames } from '../ui/icons.generated.js';
+export { Destinations } from './destinations.js';
 const FRONTEND_EXTENSION_MARKER = Symbol.for("zhike.frontend-extension.v1");
+const PAGE_VARIANTS = new Set(["full", "centered"]);
+const PAGE_ICONS = new Set(sdkIconNames);
+
+export function defineToolRenderer(definition) {
+  if (!definition || typeof definition !== 'object' || Array.isArray(definition)
+    || Object.keys(definition).some(key => !['key', 'Renderer'].includes(key))
+    || typeof definition.key !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(definition.key)
+    || typeof definition.Renderer !== 'function') throw new TypeError('tool_renderer_definition_invalid');
+  return Object.freeze({ ...definition, type: 'tool-renderer' });
+}
 
 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) {
+  if (!point || definition.type === "page") {
     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"])];
+  const property = point.kind === "view" ? (point.componentName || "component") : (point.callbackName || "handler");
+  const forbidden = point.kind === "view"
+    ? ["component", "Widget", "Section", "Tab", "Page", "handler", "onTrigger"].filter(name => name !== property)
+    : ["component", "Widget", "Section", "Tab", "Page", ...(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 });
 }
 
+export function definePage(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("Page definition 必须是对象");
+  }
+  const keys = Object.keys(definition).sort();
+  const allowed = new Set(["Page", "name", "icon", "order", "variant", "showInNavigation", "showHeader", "fillHeight"]);
+  if (keys.some(key => !allowed.has(key))) {
+    throw new TypeError("Page definition 包含不支持的字段");
+  }
+  const name = typeof definition.name === "string" ? definition.name.trim() : "";
+  if ([...name].length === 0 || [...name].length > 80 || /\p{Cc}/u.test(name)) {
+    throw new TypeError("Page name 必须是 1～80 个非控制字符");
+  }
+  if (!PAGE_VARIANTS.has(definition.variant)) {
+    throw new TypeError("Page variant 必须是 full 或 centered");
+  }
+  if (definition.icon !== undefined && !PAGE_ICONS.has(definition.icon)) {
+    throw new TypeError('Page icon 必须来自 SDK 统一图标目录');
+  }
+  if (definition.order !== undefined && !Number.isSafeInteger(definition.order)) {
+    throw new TypeError("Page order 必须是安全整数");
+  }
+  if (typeof definition.Page !== "function") {
+    throw new TypeError("Page definition 必须提供 React Page component");
+  }
+  if (definition.fillHeight !== undefined && typeof definition.fillHeight !== 'boolean') {
+    throw new TypeError('Page fillHeight 必须是布尔值');
+  }
+  if (definition.showHeader !== undefined && typeof definition.showHeader !== 'boolean') {
+    throw new TypeError('Page showHeader 必须是布尔值');
+  }
+  if (definition.showInNavigation !== undefined && typeof definition.showInNavigation !== 'boolean') {
+    throw new TypeError('Page showInNavigation 必须是布尔值');
+  }
+  return Object.freeze({
+    Page: definition.Page,
+    name,
+    ...(definition.icon === undefined ? {} : { icon: definition.icon }),
+    ...(definition.order === undefined ? {} : { order: definition.order }),
+    type: "page",
+    variant: definition.variant,
+    ...(definition.showHeader === undefined ? {} : { showHeader: definition.showHeader }),
+    ...(definition.fillHeight === undefined ? {} : { fillHeight: definition.fillHeight }),
+    ...(definition.showInNavigation === undefined ? {} : { showInNavigation: definition.showInNavigation }),
+  });
+}
+
 // 受管 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')); }
+export function navigate() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function showDialog() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function openExternalUrl() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function getCurrentUser() { throw new Error('current_user_unavailable'); }
+
+export function queryAnalysis() { return Promise.reject(new Error('runtime_analysis_unavailable')); }
+export function openAssistant() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function preparePdfTemplate() { return Promise.reject(new Error('runtime_document_unsupported')); }
+export function openPdfDocument() { return Promise.reject(new Error('runtime_document_unsupported')); }
+
+export function openArtifact() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }

package/src/client/interactions.d.ts

@@ -1,8 +1,28 @@
+export interface OpenArtifactOptions {
+  /** 私有报告的稳定ID；不承载身份或授予读取权限。 */
+  artifactId: string;
+}
+export interface OpenAssistantOptions {
+  /** App 内的场景名；同 App/场景跨页面续聊，Host 自动拼接 App 前缀。 */
+  scenario: string;
+  /** 新对话的初始业务背景，建议使用 Markdown，最多 32 KiB UTF-8；重开不会覆盖已有背景。 */
+  context: string;
+  /** 助手面板标题，1～200字符；省略时显示“智客”，不参与会话定位。 */
+  title?: string;
+}
+export interface OpenExternalOptions { href: string }
 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>): {
+export interface OpenExternalUrlOptions { url: string }
+export interface NavigateOptions { destination: import('./destinations.js').AppDestination }
+export type HostInteraction = {operation:'openArtifact';input:OpenArtifactOptions} | {operation:'preparePdfTemplate';input:import('./documents.js').PreparePdfTemplateInput} | {operation:'openPdfDocument';input:import('./documents.js').OpenPdfDocumentInput} | {operation:'openAssistant';input:OpenAssistantOptions} | {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'navigate';input:NavigateOptions} | {operation:'openExternal';input:OpenExternalOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
+export function assertHostInteraction(operation: unknown, input: unknown): Readonly<OpenArtifactOptions | ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions>;
+export function createClientInteractions(invoke: (operation: string, input: OpenArtifactOptions | ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions) => Promise<unknown>): {
+  openArtifact(input: OpenArtifactOptions): Promise<void>;
+  openAssistant(input: OpenAssistantOptions): Promise<void>;
   showToast(input: ToastOptions): Promise<void>;
   confirm(input: ConfirmOptions): Promise<boolean>;
+  openExternalUrl(url: string): Promise<void>;
+  openExternal(href: string): Promise<boolean>;
+  navigate(destination: import('./destinations.js').AppDestination): Promise<void>;
 };

package/src/client/interactions.js

@@ -1,16 +1,54 @@
+import { assertDocumentInput } from './documents.js';
+import { assertExternalUrl } from './external-url.js';
+import { assertAppDestination } from './destinations.js';
+
 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);
+const externalUrl = value => {
+  if (!text(value,8192,true) || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'https:' && parsed.hostname.length > 0 && !parsed.username && !parsed.password;
+  } catch { return false; }
+};
 export function assertHostInteraction(operation, input) {
+  if (operation === 'openArtifact') {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 1
+      || typeof input.artifactId !== 'string' || !/^[A-Za-z0-9]{26}$/.test(input.artifactId)) fail();
+    return Object.freeze({ artifactId: input.artifactId });
+  }
+  if (['preparePdfTemplate', 'openPdfDocument'].includes(operation)) return assertDocumentInput(operation, input);
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
-  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : [];
+  const allowed = operation === 'openAssistant' ? ['scenario','context','title'] : operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'navigate' ? ['destination'] : operation === 'openExternal' ? ['href'] : operation === 'openExternalUrl' ? ['url'] : [];
   if (!allowed.length || Object.keys(input).some(key=>!allowed.includes(key))) fail();
-  if (operation === 'showToast') {
+  if (operation === 'openAssistant') {
+    if (typeof input.scenario !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.scenario)
+      || typeof input.context !== 'string' || !input.context.trim()
+      || new TextEncoder().encode(input.context).byteLength > 32768
+      || !text(input.title,200) || (input.title !== undefined && !input.title.trim())) fail();
+  } else 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();
+  } else if (operation === 'confirm') {
+    if (!text(input.title,200,true) || !text(input.description,2000) || !text(input.confirmLabel,60) || !text(input.cancelLabel,60)) fail();
+  } else if (operation === 'openExternalUrl') {
+    if (!externalUrl(input.url)) fail();
+  } else if (operation === 'openExternal') {
+    try { return Object.freeze({ href: assertExternalUrl(input.href) }); } catch { fail(); }
+  } else {
+    try { assertAppDestination(input.destination); } catch { fail(); }
+  }
   return Object.freeze(Object.fromEntries(Object.entries(input).filter(([,value])=>value!==undefined)));
 }
 export function createClientInteractions(invoke) {
   return Object.freeze({
+    openArtifact(input) {
+      const request = assertHostInteraction('openArtifact',input);
+      return invoke('openArtifact',request).then(value=>{if(value!==null)fail();});
+    },
+    openAssistant(input) {
+      const request = assertHostInteraction('openAssistant',input);
+      return invoke('openAssistant',request).then(value=>{if(value!==null)fail();});
+    },
     showToast(input) {
       const request = assertHostInteraction('showToast',input);
       return invoke('showToast',request).then(value=>{if(value!==null)fail();});
@@ -19,5 +57,17 @@ export function createClientInteractions(invoke) {
       const request = assertHostInteraction('confirm',input);
       return invoke('confirm',request).then(value=>{if(typeof value!=='boolean')fail();return value;});
     },
+    openExternalUrl(url) {
+      const request = assertHostInteraction('openExternalUrl',{url});
+      return invoke('openExternalUrl',request).then(value=>{if(value!==null)fail();});
+    },
+    openExternal(href) {
+      const request = assertHostInteraction('openExternal', {href});
+      return invoke('openExternal',request).then(value=>{if(typeof value!=='boolean')fail();return value;});
+    },
+    navigate(destination) {
+      const request = assertHostInteraction('navigate',{destination});
+      return invoke('navigate',request).then(value=>{if(value!==null)fail();});
+    },
   });
 }

package/src/client/points.generated.js

@@ -14,6 +14,62 @@ export const frontendPoints = Object.freeze([
     "definitionName": "RecordActionDefinition",
     "callbackName": "onTrigger",
     "maxPerApp": 100
+  },
+  {
+    "key": "app.object-actions",
+    "kind": "action",
+    "legacyType": "object-action",
+    "definitionName": "ObjectActionDefinition",
+    "callbackName": "onTrigger",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.bulk-record-actions",
+    "kind": "action",
+    "legacyType": "bulk-record-action",
+    "definitionName": "BulkRecordActionDefinition",
+    "callbackName": "onTrigger",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-page-widgets",
+    "kind": "view",
+    "legacyType": "record-widget",
+    "definitionName": "RecordWidgetDefinition",
+    "componentName": "Widget",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-sections",
+    "kind": "view",
+    "legacyType": "record-section",
+    "definitionName": "RecordSectionDefinition",
+    "componentName": "Section",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.record-page-tabs",
+    "kind": "view",
+    "legacyType": "record-tab",
+    "definitionName": "RecordTabDefinition",
+    "componentName": "Tab",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.workspace-pages",
+    "kind": "view",
+    "legacyType": "page",
+    "definitionName": "PageDefinition",
+    "componentName": "Page",
+    "maxPerApp": 100
+  },
+  {
+    "key": "app.tool-renderers",
+    "kind": "view",
+    "legacyType": "tool-renderer",
+    "definitionName": "ToolRendererDefinition",
+    "componentName": "Renderer",
+    "maxPerApp": 64
   }
 ].map(Object.freeze));
 export const frontendPoint = type => frontendPoints.find(point => point.legacyType === type);

package/src/config.js

@@ -3,6 +3,9 @@ import { readFileSync } from "node:fs";
 import { ZhikeCliError } from "./errors.js";
 
 export const CLI_CLIENT_ID = "zhike-cli";
+export const DEFAULT_DEVELOPER_API_URL = "https://build-clm.77hub.com";
+export const DEFAULT_DEVELOPER_CONSOLE_URL = "https://build-clm.77hub.com";
+export const DEFAULT_WORKSPACE_APP_URL = "https://app-clm.77hub.com";
 const metadata = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 );
@@ -38,26 +41,27 @@ export function normalizeOrigin(value, fieldName) {
 }
 
 export function loadCliConfig(environment = process.env) {
-  const missing = CLI_ORIGIN_VARIABLES.filter(
-    (name) => typeof environment[name] !== "string" || !environment[name].trim(),
+  const provided = CLI_ORIGIN_VARIABLES.filter(
+    (name) => typeof environment[name] === "string" && environment[name].trim(),
   );
-  if (missing.length) {
+  if (provided.length > 0 && provided.length < CLI_ORIGIN_VARIABLES.length) {
+    const missing = CLI_ORIGIN_VARIABLES.filter((name) => !provided.includes(name));
     throw new ZhikeCliError(
       "zhike_environment_required",
-      `缺少 CLI 环境变量：${missing.join(", ")}`,
+      `覆盖平台环境时必须同时提供：${missing.join(", ")}`,
     );
   }
   return {
     apiBaseUrl: normalizeOrigin(
-      environment.ZHIKE_DEVELOPER_API_URL,
+      environment.ZHIKE_DEVELOPER_API_URL || DEFAULT_DEVELOPER_API_URL,
       "ZHIKE_DEVELOPER_API_URL",
     ),
     consoleBaseUrl: normalizeOrigin(
-      environment.ZHIKE_DEVELOPER_CONSOLE_URL,
+      environment.ZHIKE_DEVELOPER_CONSOLE_URL || DEFAULT_DEVELOPER_CONSOLE_URL,
       "ZHIKE_DEVELOPER_CONSOLE_URL",
     ),
     workspaceBaseUrl: normalizeOrigin(
-      environment.ZHIKE_WORKSPACE_APP_URL,
+      environment.ZHIKE_WORKSPACE_APP_URL || DEFAULT_WORKSPACE_APP_URL,
       "ZHIKE_WORKSPACE_APP_URL",
     ),
   };

package/src/forms/array-contract.d.ts

@@ -0,0 +1,32 @@
+export const ARRAY_LIMITS: Readonly<{ arrays: number; rowFields: number; rows: number; instances: number; valueBytes: number; messageBytes: number }>;
+export function validFieldKey(key: unknown): boolean;
+export function formBytes(value: unknown): number;
+export function formObject(value: unknown, keys: string[]): void;
+export interface FieldAddress { field: string; array?: string; index?: number }
+export interface ArrayBinding { name: string; rowKey: string; formInstanceId: string; structureRevision: number }
+export type ArrayAction = { kind: 'append'; value: Record<string, unknown> } | { kind: 'insertBefore'; beforeKey: string; value: Record<string, unknown> } | { kind: 'remove'; rowKey: string } | { kind: 'move'; rowKey: string; before: string | null };
+export interface ArrayOperation { formId: string; formInstanceId: string; arrayName: string; baseStructureRevision: number; action: ArrayAction }
+export interface ArraySnapshot {
+  formId: string; name: string; formInstanceId: string; revision: number; structureRevision: number;
+  rows: { key: string; index: number; value: Record<string, unknown>; errors: Record<string, string>; validatingFields: Record<string, boolean> }[];
+  submitting: boolean; canAppend: boolean; error: string | null;
+}
+export type ErrorTree<T = string> = Record<string, T | (Record<string, T> | null)[]>;
+export function parseFieldPath(path: string): FieldAddress;
+export function fieldAtPath<F>(fields: Record<string, F>, path: string): F;
+export function valueAtPath(values: Record<string, unknown>, path: string): unknown;
+export function setPathValue(values: Record<string, unknown>, path: string, value: unknown): void;
+export function rulePath(path: string): string;
+export function leafPaths(fields: Record<string, unknown>, values: Record<string, unknown>): string[];
+export function rhfPath(path: string): string;
+export function publicPath(path: string): string;
+export function assertFieldValue(value: unknown, field: unknown, draft?: boolean): void;
+export function assertArrayCapacity(fields: Record<string, unknown>, values: Record<string, unknown>, draft?: boolean): void;
+export function normalizeFormValues<T extends Record<string, unknown>>(fields: Record<string, unknown>, raw: T): T;
+export function assertErrorTree(tree: unknown, fields: Record<string, unknown>, values?: Record<string, unknown>, boolean?: boolean, maxText?: number): void;
+export function assertArrayErrors(errors: unknown, fields: Record<string, unknown>, maxText?: number): void;
+export function flattenErrors<T = string>(tree?: ErrorTree<T>): Record<string, T>;
+export function nestErrors<T = string>(flat: Record<string, T>): ErrorTree<T>;
+export function assertArrayBinding(binding: unknown): ArrayBinding;
+export function assertArrayOperation(input: unknown): ArrayOperation;
+export function assertArraySnapshot(snapshot: unknown, formId: string, name: string, fields: Record<string, unknown>): ArraySnapshot;