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. 非简单变更应在提交正文中用中文说明原因、影响、风险和验证结果。

仓库边界

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 固定执行：

cd apps/api && env -u AI_GATEWAY_TEST_DATABASE_URL go test ./... -count=1
node scripts/ci-validate-migrations.mjs <当前线上完整 Git SHA>

完整测试、审计和镜像扫描不再由 Gitea 自动运行。需要合并大范围重构、准备安全审计或人工要求完整验证时执行：

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. 本地镜像发布必须由用户明确要求后单独执行：

   ./scripts/publish-release-images.sh --components auto
   

   该命令只能构建、冒烟、推送镜像和生成 dist/releases/<SHA>.json，不得修改生产。

6. publish 成功后，Agent 必须报告 manifest、组件、digest 和验证结果并停止。只有用户再次明确确认上线，才可单独执行：

   ./scripts/deploy-production-release.sh dist/releases/<SHA>.json
   

7. deploy 前后必须验证线上基线、镜像架构/revision、数据库备份条件、内部及公网健康检查和自动应用回滚。未实际完成这些验证时不得声称生产发布成功。

8. 回滚也必须由用户明确要求，只能选择服务器已有的历史 manifest；应用回滚不自动恢复数据库。