Bundle 修改与发布工作流

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

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

1. 固定 CLI 与文档版本

baijimu --version
baijimu --help
baijimu bundle --help

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

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

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 源契约：所有可修改源码的生产者都直接写 snake_case；历史驼峰只允许在读取边界转换。不能因为存在兼容读取就继续生产旧字段，也不能把 module.json 或方法外层协议机械改名。

4. 提交并创建模块版本

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 中引用精确模块语义版本和其他资源版本，提交并推送，然后从精确提交创建版本：

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. 审核与公共市场

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

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 和有效授权：

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

最终验证至少包括：

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

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