Bundle 项目清单与对象选择

从领域目录选择对象和精确版本，在 Git 中维护作者清单并预检发布。

每个 Bundle 绑定一个 BUNDLE 项目。根目录 baijimu.bundle.json 记录本次发布选择的对象、版本和权限元数据， Git 负责评审、并发修改和历史追踪。创建对象、冻结对象版本都不会自动改变作者文件或已经安装的版本。

使用 CLI 从当前 Bundle 的目录选择对象；不要根据显示名猜测身份，也不要把版本记录 ID 当作对象身份。平台会根据 Owner 保存的归属和不可变版本生成内部安装引用。

创建清单并纳入模块

baijimu bundle manifest example > baijimu.bundle.json
baijimu bundle manifest catalog <bundle> module --workspace-id <workspaceId>
baijimu bundle manifest include <bundle> module --workspace-id <workspaceId> \
  --file baijimu.bundle.json --name <exactModuleName> --version <moduleVersion>

模块必须先在该 Bundle 内创建不可变版本，参见模块发布。 --name 只用于本次目录选择；写入 Git 的是 Owner 返回的稳定 Module 身份。重名时命令返回候选，使用 --object-id <catalogReturnedModuleId> 明确选择。重命名不会改变已保存的对象身份。

include 会校验全部所选对象的版本、归属及依赖，成功后原子更新本地文件。它不会提交 Git、创建 Bundle 版本或安装资源。

下面是 CLI 生成的作者文件片段。示例中的对象身份用于说明结构，实际使用时应由上述选择命令生成。

{
  "schemaVersion": "2.0.0",
  "definition": {
    "modules": [
      {
        "moduleId": "a054ef60-f64c-47cf-8b63-4dbdd05e5ef1",
        "semanticVersion": "1.3.0"
      }
    ],
    "dependencies": [
      {
        "bundleId": "workspace-core",
        "semanticVersion": "^1.4.35"
      }
    ]
  },
  "requestedPermissions": [],
  "providedPermissions": []
}

公开结构见 Bundle 作者清单 2.0.0。作者清单与内部不可变安装内容使用独立合同；definition 没有嵌套的内容协议版本，也没有通用资源键列表。未知字段会被拒绝。对象身份只传递 Owner 返回的值，不需要翻译成另外一种身份。

可选择的对象

领域对象	CLI 选择类型	文件中的集合	目录返回的领域身份
Module	`module`	`modules`	`moduleId`
Skill	`skill`	`skills`	`skillKey`
Agent	`agent`	`agents`	`agentKey`
Platform Application	`platform-application`	`platformApplications`	`platformAppId`
Workflow	`workflow`	`workflows`	`workflowKey`
Issue Definition	`issue-definition`	`issueDefinitions`	`issueDefinitionId`
Event Trigger	`event-trigger`	`eventTriggers`	`triggerKey`
Timer	`timer`	`timers`	`timerKey`
Permission Definition Set	`permission-definition-set`	`permissionDefinitionSets`	`permissionDefinitionSetId`
Role Template Set	`role-template-set`	`roleTemplateSets`	`roleTemplateSetId`

每个集合项只保存领域身份与 semanticVersion，同一对象只能选择一个精确版本，不接受 latest 或版本范围。 Module、Skill、Platform Application 使用各自专用创建和冻结命令。其余领域对象可通过以下命令管理：

baijimu bundle object create <bundle> <domain> --workspace-id <workspaceId> --definition @definition.json
baijimu bundle object get <bundle> <domain> --workspace-id <workspaceId> --object-id <ownerReturnedId>
baijimu bundle object publish <bundle> <domain> --workspace-id <workspaceId> \
  --object-id <ownerReturnedId> --version <exactVersion>
baijimu bundle manifest include <bundle> <domain> --workspace-id <workspaceId> \
  --file baijimu.bundle.json --object-id <ownerReturnedId> --version <exactVersion>

创建时不提供身份参数。Workflow 使用定义自身的领域 code；其他对象由 Owner 生成稳定身份。更新命令使用 bundle object update、已返回的 --object-id 和 --definition，不能在定义内覆盖归属或身份。

权限相关对象见权限定义开发和角色模板开发。权限定义必须先于引用它的角色模板安装；卸载顺序相反。

校验、提交与发布

baijimu bundle manifest validate @baijimu.bundle.json
baijimu bundle manifest preflight <bundle> --workspace-id <workspaceId> --file baijimu.bundle.json

validate 只做离线结构校验，结果为 STRUCTURE_ONLY，不能证明对象或冻结版本存在。 preflight 读取 Owner 的真实版本和归属，并验证依赖，结果为 OWNER_VERSIONS_AND_DEPENDENCIES。没有找到对象、版本未冻结、归属不符或目录重名时，应按错误检查所选领域对象；不能自行新增身份字段或要求补登记。

审查 Git 差异，提交并推送后，从完整 40 位提交发布：

baijimu bundle version create <bundle> --workspace-id <workspaceId> \
  --version <bundleVersion> --git-commit-id <40-character-commit>

发布从该不可变提交重新读取文件，使用与预检相同的编译和校验逻辑。预检成功不构成未来发布的授权或缓存凭据。平台保存不可变版本与来源提交，不维护第二份可编辑 Manifest。随后通过 Bundle 安装或升级流程使版本生效。

移除某个对象使用：

baijimu bundle manifest exclude <bundle> <domain> --workspace-id <workspaceId> \
  --file baijimu.bundle.json --object-id <savedObjectId>

被生命周期插件授权引用的对象不能直接移除，必须先明确修改插件授权。移除后同样要提交、发布并升级才能影响 Runtime。

依赖和插件

Bundle 依赖保存在 definition.dependencies，只声明 bundleId + semanticVersion 需求。平台先在当前工作区、再在已审核公共市场解析来源；不能直接纳入其他 Bundle 的对象或将它改挂到当前 Bundle。

依赖版本使用 Cargo VersionReq，每个边界必须完整：^1.4.35、~1.4.35、=1.4.35 或 >=1.4.35, <2.0.0。不接受缺段、通配符或循环依赖。依赖提供方升级预览会提示反向兼容性风险。

Type Definition 不属于安装对象，兼容范围单独放在 typeDefinitionDependencies，由类型目录返回的身份建立引用。完整规则见 Type Definition。

lifecyclePlugins 声明已注册插件、精确协议、顺序、失败策略、插件自有配置与属性授权。每条授权使用 object 选择当前清单中的领域对象；不能传入部署地址、平台凭据或扩大到未纳入的对象。插件配置中的 schemaVersion 属于插件自己的配置合同。实际支持的插件和协议以目录为准。

顶层 requestedPermissions、providedPermissions 是随 Git 提交保存的权限元数据，不创建 Runtime 权限点，也不向角色授权。省略或空数组合法；不要自行发明结构并依赖其运行效果。

显式迁移旧作者文件

作者协议 1.0.0 的写入口已关闭。先升级 CLI，再在本地 Git 工作树执行：

baijimu bundle manifest migrate <bundle> --workspace-id <workspaceId> --file baijimu.bundle.json

迁移根据旧文件中已有的精确身份读取 Owner 并验证归属，生成 2.0.0 文件供评审，不改写任何历史 Git 提交或已发布制品。若旧文件误用了显示名，迁移会失败；应先从目录核实正确领域对象，再显式修正选择，不能自动按同名猜测。旧不可变版本仍用于安装、恢复与审计；历史内容的读取能力不代表旧作者写入合同仍然有效。