Bundle Agent 定义、发布与 Workflow 引用

使用统一 Bundle 资源命令创建和发布 Agent，并以稳定 Resource Locator 供 Workflow agent 节点引用。

Bundle Agent 是由 Agent Config Owner 保存、按严格 SemVer 冻结、随 Bundle 安装到 Runtime 的资源。它负责稳定的系统提示词、工具、Skill、子 Agent、运行时和模型选择；Workflow 的 agent 节点只负责传入本次任务的 message、声明结构化 result，以及配置持久化等待的 executionPolicy。

baijimu agent 只管理会话和消息。Agent 资源的创建、完整更新和发布统一使用 baijimu bundle resource，并不是通过会话命令创建。

机器可读合同

Agent Definition Schema 描述 --definition 文件，不包含资源身份和响应 envelope。workspaceId、bundleId 和 agentKey 由 CLI 参数及资源 Owner 注入，definition 中出现这些字段会被拒绝；版本号只在发布命令和 Manifest 中出现。

定义边界

配置	所属层	规则
`configName`、`systemPrompt`、工具、Skill、子 Agent	Agent Definition	随不可变 Agent 版本冻结。
`runtimeId`、`runtimeVersionId`	Agent Definition	从当前 Agent Runtime 目录选择，不得把示例值、旧环境 ID 或部署事实复制到其他环境。
`modelName`	Agent Definition	Runtime 可选择的模型名，可继承或显式覆盖。
provider 路由	llm-gateway	不属于 Agent Definition；`modelProvider` 不进入 1.0.0 definition。
`message`、`result`、`executionPolicy`	Workflow `agent` 节点	表达一次工作流任务、结构化结果和等待策略。
`workspaceId`、`userId`、`sessionId`	受信运行时上下文	不能由 Agent 或 Workflow 作者伪造。

personaPrompt、dockerImage、apiKeyId、inheritCcSystemPrompt 和 promptConfig.stages 已退出公开合同。系统提示词使用 systemPrompt 或 promptConfig.sections；镜像由 runtimeId / runtimeVersionId 对应的 Agent Runtime 版本解析；模型凭证由目标工作区的凭证体系按请求身份解析，不能冻结进 Agent definition。

environmentVariables 和 mcpServersConfig.*.env 只能保存非敏感配置。字段名包含 API_KEY、APIKEY、ACCESS_KEY、SECRET、TOKEN、PASSWORD、PRIVATE_KEY 或 CREDENTIAL 的内联变量会在发布时失败；密钥应使用目标工作区的模型凭证、Connector 或密钥绑定。

创建和更新草稿

先从目标环境的 Agent Runtime 目录选择可用 Runtime、Runtime Version 和 modelName，再准备 agent.json。这些是目录数据，不应作为固定名单写入代码或文档。可先使用公开示例作为结构起点，但必须替换其中的模型占位文本，并按目标环境补充实际选择。

baijimu bundle resource create --workspace-id <workspaceId> <bundle> AGENT <agentKey> \
  --definition @agent.json --json

baijimu bundle resource update --workspace-id <workspaceId> <bundle> AGENT <agentKey> \
  --definition @agent.json --json

update 是完整定义更新，不是局部 patch。agentKey 是 Bundle 内稳定资源 Key；重命名或移动到其他 Bundle 必须创建新资源。子 Agent 应使用同一 Bundle 中稳定的 agentKey，发布前目标子 Agent 必须已经冻结为不可变版本。Skill 引用也会在发布时解析成可移植的 Bundle Skill 版本引用。

发布不可变 Agent 版本

baijimu bundle resource publish --workspace-id <workspaceId> <bundle> AGENT <agentKey> <semanticVersion> --json

发布会把当前草稿冻结为不可变快照，并校验资源归属、严格 SemVer、子 Agent、Skill 和内联密钥。发布结果中的 Agent 版本归 Agent Config Owner；Bundle Manifest 只引用它，不复制 definition。

写入 Bundle Manifest

baijimu bundle manifest resource add @baijimu.bundle.json --resource-type AGENT \
  --resource-key <agentKey> --version <semanticVersion>

baijimu bundle manifest validate @baijimu.bundle.json

Manifest 中的引用是：

{
  "resourceType": "AGENT",
  "resourceKey": "operations-analyst",
  "semanticVersion": "1.0.0"
}

Bundle 版本发布后，Runtime 根据安装台账把这个资源版本物化成当前工作区可执行的 Agent。Workflow 使用 baijimu/example-operations/AGENT/operations-analyst 形式的 Bundle Resource Locator 引用安装后的资源，不引用 Agent 数据库 ID、会话 ID、某台主机或可变“最新版”。

在 Workflow 中调用

{
  "type": "agent",
  "id": "analyze_operations",
  "agentResourceLocator": "baijimu/example-operations/AGENT/operations-analyst",
  "message": "请基于 {{context.analysisInput}} 完成分析、给出建议并生成报告。",
  "result": {
    "path": "analysisReport",
    "type": {
      "@type": "DataType",
      "type": "object"
    }
  },
  "executionPolicy": {
    "completionTimeoutSecs": 600
  }
}

agentResourceLocator 必须能由当前 Runtime 的有效 Bundle 安装唯一解析。Agent 会话结束后，worker 按 result.type 校验最终结构并写入 context.analysisReport，后续节点或 end 直接消费该路径。旧字段 promptTemplate、outputFormat、projectIdPath、workspaceIdPath、userIdPath、sessionIdTemplate 和节点级 timeoutSecs 不属于 Workflow 5.0.0，会被 Schema 和引擎拒绝。