easyai
dae5d16a58
删除 Gitea Actions、Tag/Main 自动流水线和旧 Runner 配置，取消 Git 操作与发布授权的绑定。\n\n新增本地镜像发布、固定生产部署助手、digest manifest、迁移安全检查、simulation 冒烟及显式回滚流程。\n\n验证：pnpm lint、pnpm test、pnpm build、Go 全量测试、ShellCheck、Compose 配置、人工发布测试和 linux/amd64 完整栈冒烟。
67 lines
3.8 KiB
Markdown
67 lines
3.8 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
|
|
```
|
|
|
|
## Git 与人工发布
|
|
|
|
1. 仓库不使用 Gitea Actions，不存在 Push、PR、Tag、Webhook、轮询或定时触发的自动构建和自动部署。
|
|
2. `main` 不设置受保护分支或 required status；允许 Agent 在获得用户明确授权后直接提交并推送，但 commit 或 push 永远不等于发布授权。
|
|
3. 发布只能使用工作区干净、已经提交并属于 `origin/main` 历史的完整 SHA。镜像 Tag 使用完整 SHA，线上只能使用 Registry digest，禁止使用 `latest`。
|
|
4. 本地镜像发布必须由用户明确要求后单独执行：
|
|
|
|
```bash
|
|
./scripts/publish-release-images.sh --components auto
|
|
```
|
|
|
|
该命令只能构建、冒烟、推送镜像和生成 `dist/releases/<SHA>.json`，不得修改生产。
|
|
5. publish 成功后，Agent 必须报告 manifest、组件、digest 和验证结果并停止。只有用户再次明确确认上线，才可单独执行：
|
|
|
|
```bash
|
|
./scripts/deploy-production-release.sh dist/releases/<SHA>.json
|
|
```
|
|
|
|
6. deploy 前后必须验证线上基线、镜像架构/revision、数据库备份条件、内部及公网健康检查和自动应用回滚。未实际完成这些验证时不得声称生产发布成功。
|
|
7. 回滚也必须由用户明确要求，只能选择服务器已有的历史 manifest；应用回滚不自动恢复数据库。
|