# Bundle 修改与发布工作流

按版本固定文档完成 Bundle-first 源码修改、审核、发布、安装和验证。

本页定义修改百积木 Bundle、模块源码和项目文件时的统一执行流程，适用于人工操作、Manager、
命令行工具、代码生成器和其他自动化。它不授予额外权限，也不替代发布者与审核者分离；所有操作
只能使用当前用户已经获得的工作区和市场权限。

## 1. 固定 CLI 与文档版本

```bash
baijimu --version
baijimu --help
baijimu bundle --help
```

从顶层帮助进入本次任务需要的命令组，并逐级读取到目标子命令的 `--help`。不要导出完整命令树，
也不要用其他 CLI 版本、搜索结果或历史机器快照猜测参数。执行每个写命令前再次读取对应帮助。

需要动态资源或执行写操作时先验证登录：

```bash
baijimu auth status --verify
```

认证、工作区权限或发布权限缺失时，保留错误并请求用户完成授权，不能编辑认证文件、复用
其他用户凭据或直接修改服务器状态。

## 2. 解析目标并读取源事实

使用 CLI 列表、查询和命令自身的名称解析能力，把工作区、项目、Bundle、模块和版本解析为
唯一稳定 ID。零匹配或多匹配时停止。不得把示例值、缓存值或模糊搜索的第一项当作目标。

读取项目文件、Git 状态、`baijimu.bundle.json`、当前版本和安装状态，明确本次变更属于：

- `module.json` 或 `methods/*.json` 的源码修改；
- Bundle 项目清单中精确资源版本或权限的更新；
- 已有 Bundle 的安装或升级。

模块源码项目可以独立存在，但模块定义和版本必须归属 Bundle。不要创建平行的独立模块审核、
市场或安装链路。

## 3. 修改规范源

通过 `baijimu project checkout` 检出 canonical Git 仓库，在检出目录中使用标准 Git 命令
修改、检查和提交。`baijimu project file` 只用于读取项目快照。

Bundle 项目的根目录文件固定为 `baijimu.bundle.json`。平台不接受 `bundle update --manifest`
或独立权限上传；所有作者和 AI 智能体都通过 Git 提交修改同一源文件，并遵守项目分支策略。

HTTP 方法必须遵循 [HTTP methodBody 源契约](/development/bundle-development/module-development/http-method-body/)：
所有可修改源码的生产者都直接写 snake\_case；历史驼峰只允许在读取边界转换。不能因为存在
兼容读取就继续生产旧字段，也不能把 `module.json` 或方法外层协议机械改名。

## 4. 提交并创建模块版本

```bash
baijimu project checkout <projectId> --workspace-id <workspaceId> --directory <directory>
cd <directory>
git status --short
git diff -- <path>
git add -- <path>
git commit -m '<message>'
git push
commitId="$(git rev-parse HEAD)"

baijimu bundle module version create <workspace> <bundle> <projectId> \
  --module-id <moduleId> \
  --version <semanticVersion> \
  --commit-id <commitId>
```

提交前确认差异只包含授权范围内的文件。使用 `git rev-parse HEAD` 返回的完整 `commitId` 创建不可变模块版本，
不得用分支名、未提交工作区或旧提交代替。完成后回查模块版本的 Git 提交、定义和安装 Artifact。

## 5. 创建不可变 Bundle 版本

在 `baijimu.bundle.json` 中引用精确模块语义版本和其他资源版本，提交并推送，然后从精确提交创建版本：

```bash
git add baijimu.bundle.json
git commit -m '<message>'
git push
commitId="$(git rev-parse HEAD)"

baijimu bundle version create <bundle> --workspace-id <workspace> \
  --version <bundleVersion> --git-commit-id <commitId>
```

创建后记录返回的 Bundle 版本 ID、来源项目 ID 和提交 ID，并回查版本内容。源码提交、模块版本创建
和 Bundle 版本创建是三个不同事实；任一步成功都不能代替后续步骤。多人或多个智能体并行修改时，
通过分支、合并和 `expected-main` 处理冲突，不在 Bundle Service 中做最后写入覆盖。

## 6. 审核与公共市场

公开分发时，把已创建的精确版本直接提交公共市场审核。版本创建和安装都不会自动提交审核，
也不要求先通过另一层工作区审核：

```bash
baijimu bundle market publish <bundle> --workspace-id <workspace> \
  --version-id <bundleVersionId> --request-id <uuid>

baijimu bundle review list --workspace-id <workspace>
baijimu bundle review history <bundleVersionId> --workspace-id <workspace>
```

同一次提交重试复用非空 UUID `requestId`，新的审核申请使用新 UUID。市场完成提交准备后才创建
`SUBMIT` 记录并进入 `PENDING_REVIEW`。只有 `PREPARE` 表示准备未完成；尚未提交或请求在
创建申请前失败时，审核历史为空。
`bundle review` 查询公共市场审核记录，没有独立的工作区审批动作。
发布者与审核者的权限边界由平台执行，不得自行批准、伪造状态或绕过审核。

“Bundle 版本已创建”“已提交市场审核”和“公共市场已发布”必须分别回查。
市场审核未完成时不能报告已上架。参数错误应返回符合 CModel 的错误码和具体原因；
出现裸 HTTP 422 时，保留脱敏命令、CLI 版本、requestId 和错误信息反馈平台。

市场状态与精确版本的直接分发状态独立。需要向指定客户工作区交付但不进入市场时，将版本设为
`TARGETED` 并逐个授权目标工作区；需要允许任意工作区直装时使用 `PUBLIC_DIRECT`。两者都不获得
市场审核背书。任何 `PUBLISHED` 版本都可以直接提交市场审核，不要求先公开直装。

## 7. 安装、升级与端到端验证

市场安装继续使用市场解析；直接交付必须使用发布方提供的稳定 `bundleId`、精确版本 ID 和有效授权：

```bash
baijimu bundle install <workspace> <bundle>
baijimu bundle install <workspace> <bundleId> --version-id <bundleVersionId> --confirm-unverified
baijimu bundle upgrade <workspace> <bundle> --version-id <bundleVersionId> --confirm-unverified
baijimu bundle resources <workspace> <bundle>
```

`--confirm-unverified` 只能表示目标工作区管理员已经核对完整依赖计划中的发布者、资源和权限，不能绕过源工作区授权。
版本没有定向授权、没有公开直装且没有有效市场记录时必须失败关闭。

最终验证至少包括：

1. 安装记录引用目标 Bundle 版本，所有物化资源状态成功。
2. Runtime 只安装一个预期模块版本，服务目录出现预期业务 ID 和方法列表。
3. 使用运行时方法定义构造真实调用；业务参数只放入参数对象，无参数时显式使用 `{}`。
4. HTTP 方法 Artifact 只含规范 snake\_case `methodBody` 字段，调用结果符合返回和错误契约。
5. 平台应用、工作流和生命周期资源按 Manifest 可见，升级没有覆盖用户配置或重复创建外部资源。
6. Operation 审计包含目标管理员对未经过市场验证的直接分发版本的明确确认。

只有目标操作成功且状态源与端到端调用一致时才能报告完成。报告中包含稳定 ID、版本、提交、
审核/市场状态和验证证据；仍缺少的认证、权限或人工审核必须单独列出。

安装或升级失败并保留活动操作时，参见 [Bundle 失败恢复与回滚](/development/bundle-development/recovery/)。
恢复与回滚均须先预览；发布修复版本不会自动解除旧操作占用。