# Bundle 项目清单与对象选择

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

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

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

## 创建清单并纳入模块

```bash
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 内创建不可变版本，参见[模块发布](/development/bundle-development/module-development/publish-and-install/)。
`--name` 只用于本次目录选择；写入 Git 的是 Owner 返回的稳定 Module 身份。重名时命令返回候选，使用
`--object-id <catalogReturnedModuleId>` 明确选择。重命名不会改变已保存的对象身份。

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

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

```json
{
  "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](/contracts/bundle-project-manifest/2.0.0/schema.json)。
作者清单与内部不可变安装内容使用独立合同；`definition` 没有嵌套的内容协议版本，也没有通用资源键列表。
未知字段会被拒绝。对象身份只传递 Owner 返回的值，不需要翻译成另外一种身份。

## 可选择的对象

| 领域对象                                                                        | CLI 选择类型                    | 文件中的集合                     | 目录返回的领域身份                   |
| --------------------------------------------------------------------------- | --------------------------- | -------------------------- | --------------------------- |
| Module                                                                      | `module`                    | `modules`                  | `moduleId`                  |
| [Skill](/development/bundle-development/skill-development/)                 | `skill`                     | `skills`                   | `skillKey`                  |
| [Agent](/development/bundle-development/agent-development/)                 | `agent`                     | `agents`                   | `agentKey`                  |
| Platform Application                                                        | `platform-application`      | `platformApplications`     | `platformAppId`             |
| Workflow                                                                    | `workflow`                  | `workflows`                | `workflowKey`               |
| Issue Definition                                                            | `issue-definition`          | `issueDefinitions`         | `issueDefinitionId`         |
| [Event Trigger](/development/bundle-development/event-trigger-development/) | `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 使用各自专用创建和冻结命令。其余领域对象可通过以下命令管理：

```bash
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`，不能在定义内覆盖归属或身份。

权限相关对象见[权限定义开发](/development/bundle-development/permission-definition-development/)和
[角色模板开发](/development/bundle-development/role-template-development/)。权限定义必须先于引用它的角色模板安装；卸载顺序相反。

## 校验、提交与发布

```bash
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 位提交发布：

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

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

移除某个对象使用：

```bash
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](/development/bundle-development/type-definition-development/)。

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

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

## 显式迁移旧作者文件

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

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

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