项目 | 百积木文档

项目用于管理一个应用相关的网站、服务、智能体和发布配置。

项目把一个业务应用需要的内容放在一起，包括页面、后端服务、模块依赖、智能体、定时任务和发布记录。

归属关系

每个项目属于一个工作区。同一个工作区可以创建多个项目，例如官网、CRM、客户助理和内部审批系统。

发布关系

项目中的页面、接口和智能体需要通过运行时预览和发布。发布后，用户通过正式域名或渠道入口访问项目内容。

Git main 写入策略

项目 Git 权限和 main 写入策略是两个独立判断：成员必须先拥有工作区及项目的 Git 写权限；通过权限校验后，平台再按项目当前策略决定是否允许直接更新 main。把成员加入工作区或项目，并不意味着项目一定允许直推 main。

策略	适用场景	有 Git 写权限的成员如何更新 `main`
`DIRECT`（默认）	新手、个人项目和低协作成本团队。	在本地 `main` 提交后，以快进方式直接推送远端 `main`。
`PROTECTED`	已启用代码评审或希望显式控制合入步骤的团队。	推送 `codex/<userId>/<branch>` 个人分支，再通过平台原子合并更新 `main`。

两种策略都会拒绝删除 main、强推和非快进覆盖。DIRECT 只是省去个人分支与合并步骤，不会允许改写已经发布的提交历史。

操作项目 Git 前，开发者和 AI Agent 都必须先读取项目的实际策略，不得根据成员角色、其他项目或历史默认值猜测：

baijimu workspace project branch-policy get <projectId> \
  --workspace-id <workspaceId>

工作区管理员或项目所有者可以显式切换策略：

baijimu workspace project branch-policy set <projectId> \
  --workspace-id <workspaceId> \
  --mode direct

baijimu workspace project branch-policy set <projectId> \
  --workspace-id <workspaceId> \
  --mode protected

精确参数以本机 baijimu project branch-policy --help 为准。如果本机 CLI 没有该命令，应先升级 CLI 或读取该版本的固定文档，不能猜测项目策略。

`DIRECT`：快进直推

git switch main
git pull --ff-only origin main
git push origin main

如果推送因为远端已有新提交而被拒绝，应先同步和整理本地提交，再重新执行快进推送；禁止用强推覆盖其他人的提交。

`PROTECTED`：个人分支合并

git push origin <sourceBranch>
baijimu workspace project branches <projectId> --workspace-id <workspaceId>
baijimu workspace project merge <projectId> <sourceBranch> \
  --workspace-id <workspaceId> \
  --expected-main <mainCommit>

PROTECTED 不要求由另一位成员代为合并：只要用户具有相应项目 Git 写权限，就可以合并自己的个人分支。平台仍会校验目标 main 是否与 --expected-main 一致，避免并发覆盖。

如何判断 403

先区分失败发生在哪一层。工作区或项目访问校验失败，说明成员关系或项目权限仍不成立；身份与 Git 写权限已经通过、但 main 策略为 PROTECTED 时，直推被拒绝是分支策略生效，应改走个人分支合并，不能继续重复加成员。

分支策略只控制项目 Git 源码如何进入 main。合并或直推成功不等于已经构建、部署或发布；运行中的 Artifact 和 Deployment 仍由对应发布流程更新。

没有 CLI 时通过 HTTP 提交文件

只有 HTTP 工具的 AI 和外部系统也可以修改项目源码，无需安装 Git 或百积木 CLI。先读取仓库与分支，取得当前分支完整的 commit ID 和实际写入策略，再一次提交文件变更。

使用平台授权的用户身份调用 Partner API 时，从当前环境的平台 API origin 请求下列路径。调用凭据由所属环境的授权接入方提供：

操作	方法与路径
读取仓库、主线 HEAD 和分支策略	`GET /partner/v1/project-git-service/api/workspaces/{workspaceId}/projects/{projectId}/git/repository`
读取分支及其当前 commit	`GET /partner/v1/project-git-service/api/workspaces/{workspaceId}/projects/{projectId}/git/branches`
批量修改文件并创建一个 commit	`POST /partner/v1/project-git-service/api/workspaces/{workspaceId}/projects/{projectId}/git/commits`
合并自己的个人分支	`POST /partner/v1/project-git-service/api/workspaces/{workspaceId}/projects/{projectId}/git/merge`

提交使用 Content-Type: application/json，请求结构如下；把示例中的占位符替换为实际分支与完整 commit ID：

{
  "contractVersion": "1.0.0",
  "branch": "main",
  "expectedCommitId": "<完整的当前分支 commit ID>",
  "message": "更新页面和图片",
  "changes": [
    { "operation": "upsert", "path": "src/index.html", "content": "<h1>你好</h1>\n" },
    { "operation": "upsert", "path": "assets/data.bin", "content": "AP8BAg==", "encoding": "base64" },
    { "operation": "delete", "path": "src/obsolete.txt" }
  ]
}

upsert 创建或替换一个文件，delete 删除一个已存在文件；重命名通过同批删除旧路径、写入新路径完成。
encoding 省略时为 utf8，二进制文件使用标准 base64。executable 可选，省略时保留已有文件模式，新文件默认不可执行。
每批 1–100 个不同文件，解码后的内容合计不超过 4 MiB，JSON 请求体不超过 32 MiB。路径是仓库相对路径，不接受目录替换、符号链接、子模块、.git 或越界路径。
一批变更只产生一个 commit。非法文件、无内容变化或预期 HEAD 过期会失败，分支不变；不会部分提交、强推或自动改为别的分支。
DIRECT 可以更新 main；PROTECTED 应提交到仓库响应 branchPolicy.writablePrefix 下的个人分支。首次创建个人分支时，expectedCommitId 必须是当前主线 HEAD；后续提交使用该个人分支 HEAD。

成功响应的 data 包含 contractVersion、projectId、branch、previousCommitId、gitCommitId 和 auditId。按 CModel 错误模型检查字符串 errorCode，不能仅凭 HTTP 200 判断成功。PROJECT_GIT_CONFLICT 表示需要重新读取并审阅最新源码。请求超时或响应丢失时，先读取目标分支确认实际 HEAD；错误提示 Git 已写入但元数据完成失败时，同样先按返回的 commit 与 audit 线索核实，不盲目重试。

受保护项目提交个人分支后，调用上表的 merge，请求为：

{
  "sourceBranch": "<自己的个人分支>",
  "expectedMain": "<当前主线完整 commit ID>",
  "message": "合并已审阅的修改"
}

使用现有 Agent 执行 key 的 AI，在同一平台 API origin 下使用 /api/agent-git/v1/projects/{projectId}.git/，对应的 repository、branches、commits 和 merge 操作与上述方法、提交与合并请求相同；按 Agent Git 入口的 Basic 认证携带 key。Git 服务同时校验签名 Agent 身份、当前 Git Grant 和项目权限；只读 Grant 不能提交或合并。用户与 Agent 凭据分别使用各自入口，不向调用方提供平台内部用户声明或管理员凭据。

这些接口只更新项目 Git，成功后仍需按项目的正式构建、发布和部署流程交付。

项目版本构建

React 静态网站、平台应用前端和 Rust 后端按项目与严格 SemVer 版本构建。版本须与源码根目录 package.json.version 或 Cargo.toml 的 package.version 完全一致。

平台首次校验主线源码并固定该版本的来源。构建失败、取消或主线更新都不会改变绑定；原源码可按原版本重试，代码修改必须使用新版本。部署和回滚选择已构建成功的版本，平台复用现有制品。Git SHA 保留为诊断信息，开发者和 AI 不需要提交它来发起构建。

项目