AGENTS.md

@@ -0,0 +1,48 @@
+# 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. 非简单变更应在提交正文或 PR 描述中用中文说明原因、影响、风险和验证结果。
+
+## 仓库边界
+
+1. 后端位于 `apps/api`，前端位于 `apps/web`，共享 TypeScript 契约位于 `packages/contracts`。
+2. 修改 HTTP 接口、请求或响应类型后，必须执行 `pnpm openapi` 并提交匹配的 OpenAPI 产物。
+3. 数据库迁移只能新增，禁止修改已经进入生产基线的历史迁移；迁移必须通过生产迁移安全检查。
+4. 不得把 `.env`、密码、Secret、Token、授权码、私钥或生产凭据提交到 Git、日志、测试输出或验收证据中。
+5. 当前工作区存在用户改动时必须保留，不得覆盖、清理、重置或混入当前任务提交；需要隔离时使用独立分支、克隆或 worktree。
+
+## 验证要求
+
+根据改动范围执行最小充分验证；准备合并或发布时执行完整门禁：
+
+```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/ci-build-images-test.sh
+./tests/ci/migrations-test.sh
+./tests/ci/pipeline-test.sh
+./tests/ci/semver-test.sh
+```
+
+修改 Shell 脚本后还必须执行 `bash -n` 和 ShellCheck。修改 Go 文件后必须确认 `gofmt -l` 没有输出。
+
+## Git 与 CI/CD
+
+1. 一个提交只包含一个逻辑变更，提交前检查暂存差异并确认不含敏感信息。
+2. `main` 只能通过短生命周期分支和 PR 合并，禁止直接推送或强制推送。
+3. PR 必须通过精确的 `ci / verify (pull_request)` 状态后才能合并；合并后还要确认同一 SHA 的 `ci / verify (push)` 成功。
+4. 生产版本仅使用稳定 SemVer `vMAJOR.MINOR.PATCH` 标签，并同时要求 `release-ci / verify-tag (push)` 成功。
+5. 未验证 protected tag、发布账本、数据库备份、健康检查和回滚路径时，不得声称 CI/CD 或生产发布已经完成。