Hosted Service 使用 Bundle Capability

Bundle Capability 是 Bundle 向自己的 Hosted Service 开放的受控内省与执行入口。它适用于后端需要在某个 Application Runtime 中查看本 Bundle 已安装的资源、读取工作流和定时任务状态，或发起已发布的工作流和 单次定时任务执行。

它不是模块属性，也不是每次编译生成的实例地址。调用方使用稳定的公开 Capability 地址；凭据绑定 environmentKey + bundleId + consumerKey + scopes，每个请求再显式指定目标 applicationRuntimeId。 服务端逐次校验凭据、权限范围和目标 Runtime 的资源归属，因此请求体不接受调用方声明 workspaceId、bundleId 或 userId。

能力边界

Bundle Capability 当前提供：

• 查询当前 Bundle 在指定 Application Runtime 中已验证生效的资源和版本。
• 查询工作流、读取工作流定义、查询实例与执行详情、启动工作流实例。
• 查询定时任务、读取定时任务定义与执行记录、触发一次立即执行。

它不提供工作流或定时任务的创建、编辑、发布、删除，也不授予其他 Bundle 的资源访问权。工作流和定时任务 仍按 Bundle 的版本化源码与安装流程交付；Capability 只操作目标 Runtime 中已经生效的版本。

Hosted 环境绑定自有 Bundle 后，平台签发并加密交付凭据，自动生成配置，负责后续轮换和解绑撤销。 业务后端读取运行时配置即可；生命周期插件的受管接入与 Bundle Capability 分别建立各自的授权关系。

首次接入

使用 Baijimu CLI 0.110.2 或更新版本。确认 Bundle 与 Hosted 环境的工作区、准确 Bundle ID 和环境 ID， 根据实际业务选择权限：

baijimu bundle capability scopes --workspace-id <workspaceId>
baijimu hosted-service bundle-capability --help
baijimu hosted-service bundle-capability bind \
  --workspace-id <workspaceId> \
  --environment-id <environmentId> \
  --bundle-id <bundleId> \
  --scope bundle.resources.read \
  --scope workflow.definition.read \
  --scope workflow.execution.read \
  --scope workflow.execution.create \
  --scope timer.definition.read \
  --scope timer.execution.read \
  --scope timer.execution.create

平台校验调用者对环境和自有 Bundle 的权限。返回结果包含 bindingId、requestId、交付状态和部署 ID， 不会返回 Token。已有同名、不同来源的配置会明确报冲突，修正归属后重试同一请求。

绑定会自动写入 Environment Secret 和变量引用：

已有部署时，平台通过正常部署流程交付新配置；尚未部署的环境在首次正式部署时消费这些配置。 查询交付状态：

baijimu hosted-service bundle-capability list \
  --workspace-id <workspaceId> --environment-id <environmentId>

ACTIVE 表示部署已经消费当前代次，平台已完成该代次确认。PENDING、DEPLOYING 和 FAILED 均不算验收通过。请求超时后使用 CLI 输出的 requestId 重试同一绑定，不重复创建关系；部署失败时先修复 部署错误，通过正式环境部署重试，平台会确认新部署实际消费的代次。不能用占位 Token 或禁用鉴权通过验收。

业务后端必须读取上述运行时变量，向 BAIJIMU_CAPABILITY_API_BASE 下的 Capability 路径发请求。 不要把凭据放进源码、Manifest、浏览器、日志或聊天，也不要在代码中固定某个环境的域名。

查找可调用方法

Bundle HTTP 合同见Bundle Capability 方法参考。 Hosted Service 的提供方能力从Capability 列表查询。 Bundle Capability 通过上述受管绑定交付配置；普通提供方方法发现结果不承担凭据签发。

Scope

不要从这张表推断账号当前一定能申请全部 scope；申请前仍以 baijimu bundle capability scopes --workspace-id <workspaceId> 返回的动态目录为准。

现有 OpenAPI 1.0.0 未完整描述返回值，且启动示例缺少顶层 requestId。 读取定义时请先查当前环境方法合同；旧合同仅保留作历史版本参考。

HTTP 调用合同

公开基础地址读取 BAIJIMU_CAPABILITY_API_BASE。所有操作都是 POST JSON 请求，并携带：

Authorization: Bearer <bundleCapabilityToken>
Content-Type: application/json

每个请求体都必须显式传入 applicationRuntimeId。该值是目标 Application Runtime 的稳定 ID，应来自当前 工作区的权威查询结果或应用自身已经校验的运行上下文；不能用工作区 ID、Bundle ID、展示名称或自行拼接值 替代。Token 不绑定单个 Runtime，同一个 Token 可以在本 Bundle 已验证安装生效的多个 Runtime 间使用， 但服务端会逐次校验 Bundle 身份、授权范围与资源 Owner 的当前事实。

所有响应使用平台统一 CModel：errorCode 为 0 表示成功，业务结果位于 data；非零错误必须按失败处理， 不能只依据 HTTP 2xx 判断成功。

Resource Locator

resourceLocator 是资源 Owner 返回的完整资源身份。调用工作流或定时任务接口前，通过 Bundle 当前资源查询取得实际存在资源的 Locator，再原样传回；安装账和历史操作回执不能证明当前资源存在。不要根据 Bundle 名、资源名或历史 ID 自行构造。

可选 resourceType 使用以下登记值：

MODULE、SKILL、AGENT、PLATFORM_APPLICATION、WORKFLOW、ISSUE_DEFINITION、 EVENT_TRIGGER、TIMER、PERMISSION、ROLE（需目标环境登记并启用）。

查询工作流资源：

curl --fail-with-body "${BAIJIMU_CAPABILITY_API_BASE}/capability/bundle-runtime/bundle/resources/query" \
  --header 'Authorization: Bearer <bundleCapabilityToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationRuntimeId": "<applicationRuntimeId>",
    "resourceType": "WORKFLOW"
  }'

启动工作流

先查询 Bundle 的当前 WORKFLOW 资源并取得 Owner 返回的 resourceLocator，再启动已安装定义。 工作流定义查询返回 WorkflowDefinition，编码是 code，不返回 definitionCode 或 resourceLocator。 启动请求的 requestId 必须放在顶层，metadata.requestId 不能替代：

curl --fail-with-body "${BAIJIMU_CAPABILITY_API_BASE}/capability/bundle-workflow/workflows/instances/start" \
  --header 'Authorization: Bearer <bundleCapabilityToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationRuntimeId": "<applicationRuntimeId>",
    "resourceLocator": "<resourceLocator>",
    "requestId": "<requestId>",
    "input": {
      "source": "hosted-service"
    }
  }'

input 和 metadata 都是可选对象。业务字段必须符合目标工作流自己的输入合同。

触发定时任务

Capability 只允许对已安装 Timer 触发一次执行，不修改原有 CRON、EVERY 或 AT 定义：

curl --fail-with-body "${BAIJIMU_CAPABILITY_API_BASE}/capability/bundle-timer/timers/executions/trigger" \
  --header 'Authorization: Bearer <bundleCapabilityToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationRuntimeId": "<applicationRuntimeId>",
    "resourceLocator": "<resourceLocator>"
  }'

生命周期与失败处理

平台在凭据到期前准备新代次，部署确认后撤销旧代次。可主动要求轮换：

baijimu hosted-service bundle-capability rotate \
  --workspace-id <workspaceId> --environment-id <environmentId> --binding-id <bindingId>

解除关系使用 unbind，平台撤销全部代次并移除本关系拥有的配置。环境退役也会执行撤销。 Hosted 项目转移前完成解绑，由新所有者重新授权。Bundle 所有权变化或退役会撤销原授权。

baijimu hosted-service bundle-capability unbind \
  --workspace-id <workspaceId> --environment-id <environmentId> --binding-id <bindingId>

轮换或解绑请求超时，复用同一 --request-id 重试。撤销后不能恢复旧凭据。 403 检查受管关系、精确 scope 和目标运行时授权；404 回查资源 Owner 的当前资源及 Locator。

完整验收

1. 确认受管交付状态为 ACTIVE，记录部署 ID 和代次，检查业务健康接口。
2. 从目标 Application Runtime 的资源 Owner 查询 Bundle 当前 Workflow 与 Timer，保留完整 Locator 和版本。 没有这些资源时，先通过各自源码、版本、Bundle 发布及安装流程交付，不能把空列表算通过。
3. 通过业务后端启动真实 Workflow，回读实例和执行记录，核对最终状态与预期业务结果。
4. 触发一次 Timer，回读本次执行记录及其下游动作；再观察一次真实调度到期产生的执行，核对时区与计划时间。 手动触发成功不等于定时调度通过。
5. 主动轮换，核对新部署和新代次仍可执行；在隔离验收环境验证旧代次失效、解绑后受保护请求被拒绝。
6. 保存请求 ID、运行时、资源版本、部署及执行记录，不保存 Token。前端展示、生命周期回调和真实业务数据 分别验收，健康检查成功不能代替完整链路结果。

机器可读合同

AI 客户端和代码生成器应读取版本化 Bundle Capability OpenAPI 2.0.0。该合同列出全部公开路径、 请求字段、scope 和示例；当前页面说明生命周期与安全边界。若本机 CLI 帮助、机器合同和运行态结果不一致， 停止调用并保留实际版本与响应，不要自行增加兼容分支。