easyai-ai-gateway/AGENTS.md

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。

验证要求

根据改动范围执行最小充分验证；准备合并或发布时执行完整门禁：

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 或生产发布已经完成。