示例：查询工作区成员

本例演示一个随业务 Bundle 安装的平台应用，如何调用 workspace-core 提供的工作区成员列表。 它使用平台已经发布的模块合同，不直接请求 lowcode 内部接口，也不把 Runtime businessId 写进应用。

已发布能力

本例核对的 workspace-core Bundle 版本为 10.2.0，其中包含：

listWorkspaceMembers 查询认证工作区中的成员。它的 workspaceId 来自安装后由平台管理的模块属性， 调用用户 userId 来自经过 App Gateway 验证的调用上下文。因此前端不得提交 workspaceId、userId、 模块 token 或内部 /gateway-module 地址。

这些版本值用于说明本例核对过的合同。开发或升级应用时，仍应读取目标工作区当前 Runtime 的 methodDefinition，并让 Bundle 依赖解析器选择满足版本要求的已发布 workspace-core 版本。

第一步：声明 Bundle 依赖

业务 Bundle 的 baijimu.bundle.json 必须声明对 workspace-core 的依赖。这里只展示相关字段：

{
  "definition": {
    "dependencies": [
      {
        "bundleId": "workspace-core",
        "semanticVersion": "^10.2.0"
      }
    ]
  }
}

依赖负责把 workspace-core 纳入安装依赖图，并不直接授予前端方法权限。目标工作区必须能够从当前 工作区或公共市场解析满足该版本要求的不可变 Bundle 版本。

如果项目还依赖其他 Bundle，应保留它们；不要用这段局部示例覆盖完整 dependencies。

第二步：用 领域引用 声明应用方法

workspace-core 是平台稳定 Bundle，本例明确依赖它的 2108 Module，不需要为这项固定依赖额外发明 interface。在平台应用项目的 baijimu.platform-application.json 中直接使用 Module 领域引用：

{
  "schemaVersion": "3.0.0",
  "entry": {
    "urlTemplate": "/index.html",
    "type": "ENVIRONMENT_HOSTED_APP",
    "openMode": "CURRENT"
  },
  "methodDefinitions": [
    {
      "target": {
        "type": "module",
        "bundleId": "workspace-core",
        "moduleId": "2108"
      },
      "methods": [
        "listWorkspaceMembers"
      ]
    }
  ],
  "manifest": {}
}

这是一个可直接校验的完整最小配置；实际项目可以继续增加配置 Schema、卡片和工作流等字段。

不要在 methodDefinitions 中填写安装后出现的 m-baijimu-* businessId。 安装器会根据依赖图把模块领域引用解析到当前 Application Runtime 的实际服务，并把解析结果保存在安装态。

只有当应用依赖的是“可以由不同 Module 实现的逻辑能力”时，才使用 {"type":"interface","name":"..."}，并在 manifest.interfaceBindings 中选择实现。interface 是替换点， 不是调用 Runtime 方法的强制中间层。

第三步：创建并安装完整版本链

能力声明是不可变平台应用版本合同的一部分。首次增加该调用时，需要依次完成：

1. 更新项目根目录 package.json 版本并提交主线；先使用 project version create --git-commit-id 固定提交并完成构建，再使用 platform-app version create --git-commit-id 传入同一提交创建不可变 Platform Application 版本。
2. 在业务 Bundle 的 baijimu.bundle.json 中锁定该 Platform Application 版本，同时保留 workspace-core 依赖。
3. 提交 Bundle 项目，并从精确 Git commit 创建新的 Bundle 版本。
4. 在目标工作区安装或升级业务 Bundle，检查安装计划已经解析 workspace-core 依赖和目标 Module。

只修改前端源码或在浏览器中改请求不能扩大已有不可变版本的能力范围。新增方法后没有创建并升级完整版本链， App Gateway 会拒绝未声明的方法。

第四步：在前端调用

应用启动时创建标准客户端并完成授权：

import { createPlatformApplicationClientFromHostedConfiguration } from "@baijimu/platform-application-sdk";

const client = await createPlatformApplicationClientFromHostedConfiguration(applicationDefinition.id);

await client.bootstrap();

业务组件使用与声明完全一致的结构化 target 和方法名调用：

const members = await client.call(
  {
    type: "module",
    bundleId: "workspace-core",
    moduleId: "2108",
  },
  "listWorkspaceMembers",
  {},
);

第三个参数必须是 JSON 空对象，因为当前方法没有业务参数。SDK 会取得本次安装的 installId 和 appClientToken，并发送逐方法请求：

POST {appGatewayApiBase}/workspace-runtime/apps/{installId}/invoke
Authorization: Bearer {appClientToken}
Content-Type: application/json

{
  "target": {
    "type": "module",
    "bundleId": "workspace-core",
    "moduleId": "2108"
  },
  "method": "listWorkspaceMembers",
  "params": {}
}

client.call() 解析统一 CModel 响应并返回成功结果的 data。当前发布方法的返回类型只声明为通用对象， 没有为成员字段发布闭合 Schema；前端在建立静态类型或依赖具体字段前，必须以目标工作区当前 Runtime 的 methodDefinition 为准，不能把本文中的演示字段当成独立合同。

调用时发生了什么

业务页面
  -> 标准 SDK 携带 installId 和 appClientToken
  -> App Gateway 校验应用安装、当前用户和 methodDefinitions
  -> 安装态把 workspace-core/MODULE/2108 解析到当前 Runtime businessId
  -> Runtime 调用 listWorkspaceMembers
  -> 模块注入可信 workspaceId 和调用用户 userId
  -> 工作区成员服务返回当前工作区成员

调用方不能借此读取其他工作区成员。页面即使伪造 workspaceId 或 userId 字段，也不会改变平台验证后的 工作区与调用身份。

验证目标工作区合同

发布或联调前，先从目标工作区的 Runtime 服务目录发现实际服务，再读取方法定义。businessId 仅用于 开发验证，不能进入平台应用源码或版本声明：

baijimu runtime services list \
  --workspace-id <workspaceId> \
  --keyword '工作区管理'

baijimu runtime service get \
  --workspace-id <workspaceId> \
  <businessId> \
  --method listWorkspaceMembers

baijimu runtime service call \
  --workspace-id <workspaceId> \
  <businessId> \
  listWorkspaceMembers \
  --params '{}'

最后还要从已经安装的真实平台应用入口完成一次浏览器调用，确认以下边界：

• 已声明且已安装的方法能够返回当前工作区成员。
• 删除 methodDefinitions 声明后，App Gateway 拒绝调用。
• 依赖未安装或 领域引用 未解析时明确失败，不回退到内部 HTTP API。
• 当前用户没有相应工作区权限时明确失败。
• 页面没有保存 Runtime businessId、模块 token、workspaceId 或 userId 身份字段。

通用调用协议与错误处理继续参见调用模块方法， Bundle 依赖格式参见Bundle 项目清单与资源边界。