# 项目

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

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

## 归属关系

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

## 发布关系

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

## Git main 写入策略

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

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

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

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

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

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

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

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

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

### `DIRECT`：快进直推

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

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

### `PROTECTED`：个人分支合并

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

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

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

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

## 项目版本构建

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

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