easyai
fac6ec95da
补充本地验证证据要求，明确经用户授权可合并 PR 或直接更新 main，并禁止等待或伪造已经取消的 CI 状态。\n\n同时继续隔离 Git 变更授权与 publish、deploy 两阶段生产授权。\n\n验证：tests/release/manual-release-test.sh
70 lines
4.4 KiB
Markdown
70 lines
4.4 KiB
Markdown
# EasyAI AI Gateway 智能体协作规则
|
||
|
||
本文件是本仓库内 AI 编码智能体的项目级执行约束。开始工作前必须先阅读本文件，并以实际代码、测试和运行结果作为结论依据。
|
||
|
||
## 协作语言
|
||
|
||
1. 面向用户的回复、进度更新、验收报告、代码审查意见、Issue、PR 标题和 PR 描述默认使用中文。
|
||
2. Git 提交信息使用 `<type>(<scope>): <中文摘要>` 格式，`scope` 可省略。
|
||
3. `type` 使用小写英文，可选值为 `feat`、`fix`、`docs`、`test`、`refactor`、`perf`、`build`、`ci`、`chore`、`revert`。
|
||
4. 提交摘要和正文必须使用中文；专有名词、协议名称、命令、路径、代码标识符和第三方原始错误可保留原文。
|
||
5. 摘要应简洁明确，末尾不加句号，不得使用“更新代码”“修复问题”等无法说明意图的模糊描述。
|
||
6. 非简单变更应在提交正文中用中文说明原因、影响、风险和验证结果。
|
||
|
||
## 仓库边界
|
||
|
||
1. 后端位于 `apps/api`，前端位于 `apps/web`，共享 TypeScript 契约位于 `packages/contracts`。
|
||
2. 修改 HTTP 接口、请求或响应类型后，必须执行 `pnpm openapi` 并提交匹配的 OpenAPI 产物。
|
||
3. 数据库迁移只能新增，禁止修改或删除已经进入 Git 历史的迁移；发布前必须相对当前线上 SHA 执行迁移安全检查。
|
||
4. 不得把 `.env`、密码、Secret、Token、授权码、私钥或生产凭据提交到 Git、日志、测试输出、release manifest 或验收证据中。
|
||
5. 当前工作区存在用户改动时必须保留，不得覆盖、清理、重置或混入当前任务提交；需要隔离时使用独立分支、克隆或 worktree。
|
||
|
||
## 验证要求
|
||
|
||
根据改动范围执行最小充分验证。修改 Shell 脚本后必须执行 `bash -n` 和 ShellCheck；修改 Go 文件后必须确认 `gofmt -l` 没有输出。
|
||
|
||
本地发布的快速强制门禁由 `scripts/publish-release-images.sh` 固定执行：
|
||
|
||
```bash
|
||
cd apps/api && env -u AI_GATEWAY_TEST_DATABASE_URL go test ./... -count=1
|
||
node scripts/ci-validate-migrations.mjs <当前线上完整 Git SHA>
|
||
```
|
||
|
||
完整测试、审计和镜像扫描不再由 Gitea 自动运行。需要合并大范围重构、准备安全审计或人工要求完整验证时执行：
|
||
|
||
```bash
|
||
cd apps/api && go vet ./... && go test ./... && govulncheck ./...
|
||
pnpm install --frozen-lockfile
|
||
pnpm lint
|
||
pnpm test
|
||
pnpm build
|
||
pnpm audit --audit-level high
|
||
docker compose -f docker-compose.yml config --quiet
|
||
./tests/ci/migrations-test.sh
|
||
./tests/release/manual-release-test.sh
|
||
```
|
||
|
||
仓库没有自动 CI 兜底，合并或推送前必须以本地命令的实际结果为验收依据；报告中应明确区分已运行、命中缓存、未运行和无法运行的项目，不得把未执行的检查表述为通过。
|
||
|
||
## Git 与人工发布
|
||
|
||
1. 仓库不使用 Gitea Actions，不存在 Push、PR、Tag、Webhook、轮询或定时触发的自动构建和自动部署。
|
||
2. `main` 不设置受保护分支或 required status；Agent 在获得用户明确授权后，可以合并已验证的 PR，也可以直接提交并推送 `main`。操作前必须获取最新 `origin/main`、确认工作区边界、检查提交差异和敏感信息，并执行与风险匹配的本地验证。
|
||
3. 不得等待、伪造或手工补写已经取消的 CI status，也不得为了满足旧流程擅自恢复 Gitea Actions。Git 提交、合并、Push 和 Tag 授权只覆盖源码历史变更，永远不等于 publish 或 deploy 授权。
|
||
4. 发布只能使用工作区干净、已经提交并属于 `origin/main` 历史的完整 SHA。镜像 Tag 使用完整 SHA，线上只能使用 Registry digest，禁止使用 `latest`。
|
||
5. 本地镜像发布必须由用户明确要求后单独执行：
|
||
|
||
```bash
|
||
./scripts/publish-release-images.sh --components auto
|
||
```
|
||
|
||
该命令只能构建、冒烟、推送镜像和生成 `dist/releases/<SHA>.json`，不得修改生产。
|
||
6. publish 成功后，Agent 必须报告 manifest、组件、digest 和验证结果并停止。只有用户再次明确确认上线，才可单独执行：
|
||
|
||
```bash
|
||
./scripts/deploy-production-release.sh dist/releases/<SHA>.json
|
||
```
|
||
|
||
7. deploy 前后必须验证线上基线、镜像架构/revision、数据库备份条件、内部及公网健康检查和自动应用回滚。未实际完成这些验证时不得声称生产发布成功。
|
||
8. 回滚也必须由用户明确要求，只能选择服务器已有的历史 manifest；应用回滚不自动恢复数据库。
|