Hosted Service 使用 Bundle Capability

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

它不是模块属性，也不是每次编译生成的实例地址。调用方使用稳定的公开 Capability 地址；凭据绑定 environmentKey + bundleId + consumerKey + scopes，每个请求再显式指定目标 applicationRuntimeId。 服务端会在每次请求中确认该 Bundle 确实在目标 Runtime 中处于已验证生效态，因此请求体不接受调用方声明 workspaceId、bundleId 或 userId。

能力边界

Bundle Capability 当前提供：

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

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

这套入口与 Runtime 模块调用协议相互独立。Hosted Service 不需要伪装成模块实例，也不应把 Capability Token 放进模块属性、Bundle Manifest、Artifact 或源码。Token 明文只在签发时返回一次，应写入目标 Hosted Service Environment Secret，并通过正常部署或重启流程交付给业务进程。

查找可调用方法

Bundle HTTP 合同见Bundle Capability 方法参考。 Hosted Service 的提供方能力请从Capability 列表开始查询。 两者的凭据、路径和返回合同不能混用。

申请客户端与 Token

只有对目标工作区有管理权限、且拥有目标 Bundle 的调用方才能通过 CLI 管理 Capability Client 和 Token。 先从当前 CLI 读取准确命令：

baijimu bundle capability --help
baijimu bundle capability scopes --help
baijimu bundle capability client --help
baijimu bundle capability token --help

列出平台当前允许申请的 scope：

baijimu bundle capability scopes --workspace-id <workspaceId>

为 Hosted Service 建立稳定 consumer。<bundle> 必须是自有 Bundle 的精确名称或 bundleId， consumerKey 用于审计、轮换和整体停用，不要使用部署生成的临时 ID：

baijimu bundle capability client create <bundle> \
  --workspace-id <workspaceId> \
  --consumer-key <consumerKey> \
  --name <displayName>

按最小权限签发 Token；需要多个 scope 时重复 --scope：

baijimu bundle capability token issue <bundle> <clientKey> \
  --workspace-id <workspaceId> \
  --name <tokenName> \
  --scope bundle.resources.read \
  --scope workflow.definition.read \
  --scope workflow.execution.read

Token 明文只在这次响应中出现。保存后只使用 tokenKey 查询和吊销，不要把 Token 明文放进命令参数、日志、 聊天消息或 Git：

写入 Hosted Service Environment Secret 时，只保存签发响应中 data.secret 的原始字符串值。Token 是不透明 凭据，调用方不得依赖或校验某个固定前缀；Secret 中也不得包含 Bearer 认证方案、引号、整段 JSON 响应或 仅用于识别的 tokenPrefix。Bearer 属于 HTTP Authorization Header，由 HTTP 客户端在发起请求时添加 一次，不是 Secret 值的一部分。

baijimu bundle capability token list <bundle> <clientKey> \
  --workspace-id <workspaceId>

baijimu bundle capability token revoke <bundle> <tokenKey> \
  --workspace-id <workspaceId>

完整参数、启停 Client、有效期和生效时间以本机对应子命令的 --help 为准。

Scope

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

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

HTTP 调用合同

公开基础地址为 https://api.baijimu.com。所有操作都是 POST JSON 请求，并携带：

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

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

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

Resource Locator

resourceLocator 是 Bundle 安装账本返回的稳定资源身份。调用工作流或定时任务接口前，先通过 Bundle 资源查询取得 Locator，再原样传回；不要根据 Bundle 名、资源名或历史 ID 自行构造。

可选 resourceType 使用以下登记值：

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

查询工作流资源：

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

启动工作流

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

curl --fail-with-body 'https://api.baijimu.com/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 'https://api.baijimu.com/capability/bundle-timer/timers/executions/trigger' \
  --header 'Authorization: Bearer <bundleCapabilityToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationRuntimeId": "<applicationRuntimeId>",
    "resourceLocator": "<resourceLocator>"
  }'

生命周期与失败处理

• 为每个稳定用途创建独立 Client，并只签发所需 scope；不同后端或自动化用途不要共用 Token。
• 轮换时先签发新 Token、更新 Environment Secret 并完成部署验证，再按 tokenKey 吊销旧 Token。
• Client 被停用、Token 被吊销或过期后，请求立即失败；不要在应用中缓存“曾经授权成功”的结果。
• Bundle 所有权变化、退出可申请状态，或目标 Runtime 中安装不再处于已验证生效态时，请求失败关闭。
• 404 不等于可以换一个 Bundle 或猜 Locator；应回查目标 Runtime 的 Bundle 安装与资源查询结果。
• 403 应检查 Token 状态、Client 状态和精确 scope，不要把管理 CLI 的账号凭据改作服务 Token。

机器可读合同

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