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

package/README.md

@@ -25,3 +25,195 @@ zhike logs --workspace <workspace-id> --since 1d --level error --keyword timeout
 - 服务端需要部署支持 `/api/developer/cli/apps/{app_id}/logs` 的 Developer Server；旧服务端不会自动回退到 Web 凭据或实时订阅。
 
 `zhike dev` 的实时订阅仍是独立用途，七天断线补读窗口不代表历史查询可超过三天。
+
+## Object Action 与 Bulk Record Action
+
+对象列表上的两类 Action 仍使用 `src/app/extensions/<key>/extension.tsx`：
+
+```tsx
+import { defineFrontendExtension, showToast } from '@77-zhike/app-sdk/client'
+
+export default defineFrontendExtension({
+  key: 'sync-selected-customers',
+  type: 'bulk-record-action',
+  label: '同步选中客户',
+  objects: ['accounts'],
+  async onTrigger({ object, recordIds }) {
+    await syncCustomers({ object, recordIds: [...recordIds] })
+    await showToast({ message: `已提交 ${recordIds.length} 条客户`, tone: 'success' })
+  },
+})
+```
+
+- `object-action` 显示在列表右上角对象操作菜单，只接收 `{ object }`。
+- `bulk-record-action` 只在产品列表允许当前页显式多选时出现，接收 `{ object, recordIds }`；`recordIds` 为点击瞬间按当前页顺序冻结的 1～100 个公开 ID。
+- `objects` 只允许 `accounts`、`contacts`、`opportunities` 和公开的 `custom_*` slug。任务、跟进记录、笔记不是 SDK Record Surface，不能用于 `record-action`、`object-action` 或 `bulk-record-action`。SDK 不暴露查询、权限、revision、内部 definition ID、系统 mutation 或产品 Action slot。
+- Web/H5 使用同一产品目录和执行合同，但分别渲染菜单、Dialog/Sheet 与选择交互。没有可执行 Bulk Action 时不会出现空选择入口。
+- Action 发现不会启动 Worker；点击后才校验当前 Installation 并 Lazy 执行。Action 本期不能调用 `navigate()`。
+- Destination 的可导航对象与 Record 扩展白名单是两个独立合同；某类产品对象可以被打开，不代表 App 可以向它注册 Record Action。
+
+## Record Widget、Record Section 与 Record Tab
+
+记录页面组件继续使用 `src/app/extensions/<key>/extension.tsx`。Widget 由管理员加入卡片区；Record Section 进入统一 Section 目录，当前列表式设置默认将新 placement 加入 Overview；Tab 安装后进入产品 Tab 目录。三者都只接收平台签发的公开记录身份：
+
+```tsx
+import {
+  defineFrontendExtension,
+  type RecordComponentProps,
+} from '@77-zhike/app-sdk/client'
+import { Badge, Widget } from '@77-zhike/app-sdk/ui'
+
+function HealthWidget({ object, recordId }: RecordComponentProps) {
+  return (
+    <Widget.TextWidget onTrigger={() => openHealthDetails({ object, recordId })}>
+      <Widget.Title>客户健康度</Widget.Title>
+      <Widget.Text.Primary>92</Widget.Text.Primary>
+      <Widget.Text.Secondary>{`记录：${recordId}`}</Widget.Text.Secondary>
+      <Widget.Decoration>
+        <Badge tone="success">正常</Badge>
+      </Widget.Decoration>
+    </Widget.TextWidget>
+  )
+}
+
+export default defineFrontendExtension({
+  key: 'customer-health',
+  type: 'record-widget',
+  label: '客户健康度',
+  objects: ['accounts'],
+  Widget: HealthWidget,
+})
+```
+
+Record Section 使用同一声明形态，把 `type` 改为 `record-section` 并以 `Section` 提供组件；它按 final plan 在 placement 指定的 Section 区域渲染。`recordDetails.supportingSections` 与 `overview.sections` 只是位置，共用同一 capability 和 View。Record Tab 则使用 `record-tab` 和 `Tab`。`objects` 省略时适用于客户、联系人、商机和全部自定义对象；具体 `custom_*` 只匹配同名公开对象。任务、跟进记录和笔记不是 SDK Record Surface。
+
+```tsx
+import {
+  defineFrontendExtension,
+  type RecordComponentProps,
+} from '@77-zhike/app-sdk/client'
+import { Button, Stack, TextBlock } from '@77-zhike/app-sdk/ui'
+
+function BusinessSummary({ object, recordId }: RecordComponentProps) {
+  return (
+    <Stack gap="medium">
+      <TextBlock>当前记录：{`${object} / ${recordId}`}</TextBlock>
+      <Button onClick={() => refreshSummary({ object, recordId })}>刷新摘要</Button>
+    </Stack>
+  )
+}
+
+export default defineFrontendExtension({
+  key: 'business-summary',
+  type: 'record-section',
+  label: '经营摘要',
+  objects: ['accounts', 'opportunities'],
+  Section: BusinessSummary,
+})
+```
+
+`record-widget` 表示 Overview 顶部卡片。唯一根节点必须是 `Widget.TextWidget`，首次数据尚未就绪时可以返回 `Widget.Loading`。`Widget.Title`、`Widget.Text.Primary`、`Widget.Text.Secondary` 与可选的 `Widget.Decoration` 只描述卡片语义；其中 Decoration 只接受 `Badge` 或 `StatusBadge`。Web/H5 Host 使用各自 `components/ui` 实现外框、间距、字体、可信归属与 loading/error，App 不要在根节点再次套 `Card` 或自行模拟卡片样式。产品原生重点字段也复用同一套 Overview Widget 原子组件，因此 App 与产品卡片在同一端保持一致。
+
+`Widget.TextWidget.onTrigger` 用于整卡点击，Host 会提供 pending 单飞与失败反馈；发现和渲染本身不会触发该回调。未提供 `Widget.Title` 时，Host 使用 capability label 作为受信回退标题。全宽内容必须使用 `record-section`，不能复用 `record-widget`。
+
+- 产品只保存稳定 capability placement，不保存 App 版本或 Worker 身份；升级、卸载后重装仍可恢复原布局。Widget、Section、Tab 分别进入固定共享贡献点，不为每个组件创建新贡献点。
+- Web/H5 使用同一份布局和 `{ object, recordId }`，但分别渲染适合当前宿主的 UI。H5 不支持的 Forms/`LookupCell` 只让当前 Widget/Section/Tab 进入 `unsupported`，不会拖垮详情或同 App 的其他组件。
+- Widget/Section/Tab 标签和设置候选的发现不启动 Worker；可见 Widget/Section 或当前选中 Tab 才挂载 App View。Section 挂载后可自行初始化查询，Host 不提供数据预取合同。Server Function 仍必须由用户在已挂载组件中显式触发。
+- App 不能声明 capability ID、布局位置、排序 tier、产品 route、`viewName`、Workspace/Installation 身份或 Native availability metadata。
+- 当前 Record Page 三类组件不开放命令式 `navigate()`；详情 Tab 的 URL 与刷新恢复由产品 Host 统一管理。
+
+## Workspace Page
+
+Page 源码放在 `src/app/pages/<slug>/page.tsx`。一级目录名就是稳定 slug；Page 只声明名称、排序、布局和纯 React 组件，不接收 Router、Workspace、鉴权 token 或宿主 props。
+
+```tsx
+import {
+  definePage,
+  Destinations,
+} from '@77-zhike/app-sdk/client'
+import {
+  Card,
+  Link,
+  Stack,
+  TextBlock,
+} from '@77-zhike/app-sdk/ui'
+
+function QueuePage() {
+  return (
+    <Stack gap="large">
+      <Card title="任务队列">
+        <TextBlock>当前没有待处理任务。</TextBlock>
+      </Card>
+      <Link destination={Destinations.appPage('overview')}>
+        返回总览
+      </Link>
+    </Stack>
+  )
+}
+
+export default definePage({
+  name: '任务队列',
+  order: 20,
+  variant: 'centered',
+  Page: QueuePage,
+})
+```
+
+同一 App 内，有 `order` 的 Page 排在前面并按 `order + slug` 稳定排序；未声明 `order` 的 Page 排在后面并按 slug 排序。`name` trim 后长度为 1～80 个 Unicode code points。`variant: 'full' | 'centered'` 只表达布局语义，Desktop 与 H5 分别决定具体页面壳。
+
+Page UI 必须使用 `@77-zhike/app-sdk/ui` 和 `@77-zhike/app-sdk/forms` 的公开组件，不能依赖 DOM、React Router 或自行复制产品控件。当前 Desktop 支持 Components 与 Forms；H5 支持 TextBlock、布局、反馈、Button、Tabs、Table、Card、Grid、EmptyState、Link 等 portable Components，并支持 Forms，暂不支持 `LookupCell`。含有不支持能力的 Page 在 H5 会整体显示“不支持”，不会静默丢节点或部分提交。
+
+导航只提交结构化 Destination：
+
+- `Destinations.appPage(slug)` 打开当前 App 的另一个 Page。
+- `Destinations.record({ object, recordId })` 支持 `accounts`、`contacts`、`opportunities`、`tasks`、`activities` 和当前 Workspace 可见的 `custom_*` 公开 API slug。
+- `Link` 保留普通链接、复制地址和新标签行为；普通点击仍会在跳转前重验当前 Page 身份。
+- `navigate()` 当前只允许从已挂载的 Page 调用，三类 Action 都不具备该能力。
+
+目录展示不会启动 Worker。首次打开 Page 时，宿主才会下载并校验 Manifest/Bundle、启动 Installation Worker；因此“Apps 菜单可见”不等于代码已经验证可运行。页面数据读写仍应通过受控 Server Function 完成。
+
+## 当前 Workspace 用户
+
+Client 与用户触发的 Server Function 都可以同步读取当前 Workspace 成员：
+
+```tsx
+import { getCurrentUser } from '@77-zhike/app-sdk/client'
+
+const currentUser = getCurrentUser()
+// currentUser.workspaceMemberId 是 Workspace 成员 ID，不是平台全局 User ID。
+```
+
+```ts
+import { getCurrentUser } from '@77-zhike/app-sdk/server'
+
+export default async function readForCurrentMember() {
+  const currentUser = getCurrentUser()
+  return { workspaceMemberId: currentUser.workspaceMemberId }
+}
+```
+
+返回值只包含 `workspaceMemberId`、`displayName`、`primaryEmailAddress`、`avatarUrl`，且为只读快照。它不包含 Token、角色、权限集合或平台全局 User ID；App 仍须通过 Server Function 与公开 API 完成数据授权，不能用该快照自行推断权限。Lifecycle、Webhook 等无人触发入口没有当前用户，调用时抛出 `current_user_unavailable`；不得回退到管理员、安装者或 Connection 所有者。
+
+## 基础UI组件扩展
+
+新增Avatar、DescriptionList、Divider、Json、ExternalLink、StatusBadge、TextBlock与Typography，补齐Banner动作、Badge颜色、Card呈现、Grid容器模式、EmptyState操作编排和Table.HeaderCell。原flat exports与默认调用保留，复合写法使用同一节点。
+
+Desktop注册42项，H5注册41项（不含LookupCell），其中包括 `Widget.TextWidget`、`Widget.Title`、`Widget.Text.Primary`、`Widget.Text.Secondary`、`Widget.Loading` 与 `Widget.Decoration` 六个 Widget 语义节点。Link仍仅限Page；H5支持Forms，仍不开放Settings入口。新包要求`remote-react.v3`，发布前必须先部署对应Host及Bundle准入合同。
+
+新增组件的日常验证：修改Core `components/contracts.mjs`后执行`npm run generate:components --workspace @77-zhike/app-sdk`和`npm run check:components --workspace @77-zhike/app-sdk`，同步双端manifest与adapter。App项目运行`zhike dev --workspace <workspace-id>`，从对应Workspace的Apps入口打开Page；Desktop Settings仅验证其允许的子集。
+
+仓库内还提供无业务数据库的独立组件预览，命令和证据边界见`integration-app-runtime/verification/fixtures/ui-parity/README.md`。该预览不替代真实安装、权限与Server Function验证。
+
+## 表单组件
+
+Desktop 与 H5 均支持 17 个可视 Forms 节点，以及只读 `WithState`。文本、多行、数字、日期、时间、选择、分组等输入复用各端基础 UI；Host 继续持有 RHF 状态，组件选择不会自动保存。数字空值为 null，日期为 YYYY-MM-DD，日期时间提交为带时区 ISO；旧 string/boolean/enum 语义保留。
+
+`RecordCombobox` 默认只需在 schema 声明单个 `objectSlug`（或 `Forms.record(objectSlug)`），由 Host 使用当前安装的 Records Read 权限读取公开记录，保存值是 `{ objectSlug, recordId }`。空词沿用 Query 分页，非空词使用最多 25 条、无分页的 Record Search，已选值独立 Get。自定义数据源才提供 `RecordOptionsProvider.search/getOption` 并可自行分页；业务有效性及显式保存仍由消费方负责。`WithState` 仅订阅指定的 values/errors/submitting，不提供状态修改或程序化提交。
+
+可复制的非 CRM 示例与真实 tarball/Worker/SF/Settings/PostgreSQL 验证入口见 `integration-app-runtime/verification/fixtures/forms-parity/README.md`。当前尚未发布，所有新增 Forms 能力并入 remote-react.v3，ABI=2 不变；沿用 v1/v2 合同校验。SDK 与双端 Host 应整体交付，不引入新的版本分叉。
+
+## Dialog
+
+通过 `showDialog({ title, Dialog })` 打开临时界面；内容组件接收 `hideDialog()`。Desktop 复用 Dialog，H5 复用 Sheet，继续组合已有 UI/Form。当前不提供 DialogList、嵌套 Dialog 或固定 Footer，按钮直接放在正文中。
+
+从 Page/Settings 事件或 Record Action 调用。普通关闭完成 Promise；身份失效或打开失败拒绝。Action 正常返回后已受理 Dialog 可继续使用；保存必须由 App 显式调用 Server Function。Dialog 内不提供 Page 导航身份。详见开发者文档 `app-sdk/dialogs/show-dialog`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.6",
+  "version": "0.2.0-d7b1.7",
   "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
   "type": "module",
   "engines": {

package/src/cli/project-init.js

@@ -157,6 +157,7 @@ export async function scaffoldProject({ targetDirectory, binding }) {
         {
           compilerOptions: {
             lib: ["ES2022", "DOM"],
+            jsx: "react-jsx",
             module: "ESNext",
             moduleResolution: "Bundler",
             noEmit: true,

package/src/client/destinations.d.ts

@@ -0,0 +1,25 @@
+/** 有界字符串业务参数；不包含宿主身份，不授予记录访问权。 */
+export type PageParams = Readonly<Record<string, string>>;
+
+export interface AppPageDestination {
+  readonly kind: 'app-page';
+  /** 当前 App 内的 Page slug。 */
+  readonly pageSlug: string;
+  readonly params?: PageParams;
+}
+
+export interface RecordDestination {
+  readonly kind: 'record';
+  /** 标准对象复数 slug，或当前 Workspace 可见的 custom_* 公开 API slug。 */
+  readonly object: string;
+  readonly recordId: string;
+}
+
+export type AppDestination = AppPageDestination | RecordDestination;
+
+export function assertAppDestination(value: unknown): Readonly<AppDestination>;
+export function assertPageParams(value: unknown): PageParams;
+export const Destinations: Readonly<{
+  appPage(pageSlug: string, options?: { params?: PageParams }): Readonly<AppPageDestination>;
+  record(input: { object: string; recordId: string }): Readonly<RecordDestination>;
+}>;

package/src/client/destinations.js

@@ -0,0 +1,70 @@
+const PAGE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const OBJECT_SLUG = /^[a-z][a-z0-9_]{0,99}$/;
+const STANDARD_RECORD_OBJECTS = new Set([
+  'accounts',
+  'contacts',
+  'opportunities',
+  'tasks',
+  'activities',
+]);
+
+const fail = () => { throw new TypeError('runtime_destination_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+
+/** 参数是地址中的不可信业务输入，不承载宿主身份或授权。 */
+export function assertPageParams(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Object.keys(value).sort();
+  if (keys.length > 16) fail();
+  const entries = keys.map(key => {
+    const item = value[key];
+    if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key)
+      || ['__proto__', 'prototype', 'constructor'].includes(key)
+      || typeof item !== 'string' || [...item].length > 512
+      || /[\p{Cc}\p{Cs}]/u.test(item)) fail();
+    return [key, item];
+  });
+  const params = Object.fromEntries(entries);
+  if (new TextEncoder().encode(JSON.stringify(params)).byteLength > 2048) fail();
+  return Object.freeze(params);
+}
+
+export function assertAppDestination(value) {
+  only(value, value?.kind === 'app-page' ? ['kind', 'pageSlug', 'params'] : value?.kind === 'record'
+    ? ['kind', 'object', 'recordId'] : []);
+  if (value.kind === 'app-page') {
+    if (typeof value.pageSlug !== 'string' || value.pageSlug.length > 64 || !PAGE_SLUG.test(value.pageSlug)) fail();
+    const params = value.params === undefined ? undefined : assertPageParams(value.params);
+    return Object.freeze({ kind: 'app-page', pageSlug: value.pageSlug,
+      ...(params && Object.keys(params).length ? { params } : {}),
+    });
+  }
+  if (value.kind === 'record') {
+    const custom = typeof value.object === 'string' && value.object.startsWith('custom_');
+    if (
+      typeof value.object !== 'string'
+      || !OBJECT_SLUG.test(value.object)
+      || (!STANDARD_RECORD_OBJECTS.has(value.object) && !custom)
+      || typeof value.recordId !== 'string'
+      || value.recordId.length < 1
+      || value.recordId.length > 160
+    ) fail();
+    return Object.freeze({ kind: 'record', object: value.object, recordId: value.recordId });
+  }
+  fail();
+}
+
+export const Destinations = Object.freeze({
+  appPage(pageSlug, options) {
+    if (options !== undefined) only(options, ['params']);
+    return assertAppDestination({ kind: 'app-page', pageSlug, ...(options?.params === undefined ? {} : { params: options.params }) });
+  },
+  record(input) {
+    only(input, ['object', 'recordId']);
+    return assertAppDestination({ kind: 'record', object: input.object, recordId: input.recordId });
+  },
+});

package/src/client/external-url.js

@@ -0,0 +1,9 @@
+/** SDK 与 Host 重复验证同一有界 HTTPS 合同，不接受浏览器自动纠正的危险写法。 */
+export function assertExternalUrl(value) {
+  if (typeof value !== 'string' || !value.length || value.length > 2048 || value !== value.trim()
+    || /[\p{Cc}\\]/u.test(value) || !/^https:\/\//i.test(value)) throw new Error('runtime_external_url_invalid');
+  let url;
+  try { url = new URL(value); } catch { throw new Error('runtime_external_url_invalid'); }
+  if (url.protocol !== 'https:' || !url.hostname || url.username || url.password) throw new Error('runtime_external_url_invalid');
+  return url.href;
+}

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,145 @@ 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;
+  /** 有值的 Page 优先按数值排序；缺失时按 slug 稳定排序。 */
+  order?: number;
+  /** Page 自身的产品布局语义，不选择 Dialog、Sheet 或 Sidebar。 */
+  variant: "full" | "centered";
+  /** 缺省可见；只影响 Apps 菜单，不改变页面授权或可访问性。 */
+  showInNavigation?: boolean;
+  /** 纯 React Page component，只接收有界业务参数。 */
+  Page: ComponentType<PageProps>;
+}
+
+export type DefinedPage = Readonly<PageDefinition & { type: "page" }>;
 export type FrontendExtensionDefinition =
   | SettingsExtensionDefinition
-  | RecordActionDefinition;
+  | RecordActionDefinition
+  | ObjectActionDefinition
+  | BulkRecordActionDefinition
+  | RecordWidgetDefinition
+  | RecordSectionDefinition
+  | RecordTabDefinition;
 
 export function defineFrontendExtension(
   definition: SettingsExtensionDefinition,
@@ -43,15 +180,61 @@ 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;
+  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>;

package/src/client/index.js

@@ -1,23 +1,65 @@
 import { frontendPoint } from './points.generated.js';
+export { Destinations } from './destinations.js';
 const FRONTEND_EXTENSION_MARKER = Symbol.for("zhike.frontend-extension.v1");
+const PAGE_VARIANTS = new Set(["full", "centered"]);
 
 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", "order", "variant", "showInNavigation"]);
+  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.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.showInNavigation !== undefined && typeof definition.showInNavigation !== 'boolean') {
+    throw new TypeError('Page showInNavigation 必须是布尔值');
+  }
+  return Object.freeze({
+    Page: definition.Page,
+    name,
+    ...(definition.order === undefined ? {} : { order: definition.order }),
+    type: "page",
+    variant: definition.variant,
+    ...(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'); }

package/src/client/interactions.d.ts

@@ -1,10 +1,14 @@
+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 interface OpenExternalUrlOptions { url: string }
-export type HostInteraction = {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
-export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions | OpenExternalUrlOptions>;
-export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions | OpenExternalUrlOptions) => Promise<unknown>): {
+export interface NavigateOptions { destination: import('./destinations.js').AppDestination }
+export type HostInteraction = {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<ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions>;
+export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions) => Promise<unknown>): {
   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>;
 };