Imported from xiongxiansheng050454/LLMGateway (
AGENTS.md). Install upstream withnpx skills add xiongxiansheng050454/LLMGateway. Copyright stays with the author.
AGENTS.md
本文件面向在本仓库中工作的 AI Agent 和协作者。项目是一个 LLM API Gateway:后端使用 Go 标准库 net/http、PostgreSQL 和 sqlc,前端是无需构建的静态 HTML/CSS/JS 控制台。
目录放置规则
server/是 Go 模块根。所有 Go 命令在该目录执行,或在仓库根使用go -C server ...。server/cmd/llmgateway/只放进程装配、启动、优雅关闭和顶层 HTTP 路由表。路径到入口的映射统一放在router.go。server/internal/catalog/放渠道、模型映射、定价、渠道连通性测试及对应管理端入口。server/internal/accounts/放用户、余额、网关 Key、认证上下文和权限能力。server/internal/usage/放用量日志、审计查询和统计能力。server/internal/ratelimit/放限流规则管理;与代理请求执行强相关的限流编排放在server/internal/proxy/。server/internal/quota/放 UTC 日/月业务配额策略和管理端入口;rate_limit_rules只做速率控制,配额策略不得复用其持久化模型。server/internal/proxy/放下游代理业务编排,包括认证、选路、计费、限流、熔断、结算和上游调用。server/internal/proxy/openai/只放 OpenAI 兼容 wire DTO、请求解析和响应适配。server/internal/httpapi/只放顶层 HTTP 入口、统一响应、错误映射、静态 Dashboard 托管和对业务模块的委托,不集中放具体业务实现。server/internal/httpcommon/放跨业务复用的 HTTP 路径、JSON、分页、存储错误映射和响应 helper。server/internal/domain/放协议中立、存储中立的共享业务类型和纯规则。仅单个业务模块使用的类型优先留在该模块内。server/internal/store/只放存储端口、组合接口和通用存储错误;按channel.go、user.go、usage.go、ratelimit.go、channelhealth.go等业务领域拆分,禁止继续向单个总文件堆方法。server/internal/store/postgres/放 PostgreSQL Store 实现;业务模块不得直接导入该包。server/internal/store/postgres/是唯一生产 Store 实现;server/internal/testutil/storefake/仅供不需要数据库的单元与 HTTP 契约测试使用,生产代码不得导入,运行时不得提供 memory fallback。server/db/migrations/放 schema 迁移,server/db/queries/放 sqlc 查询,server/internal/db/migrate/放迁移 runner,server/internal/db/sqlc/放生成代码。禁止手改 sqlc 生成文件。server/internal/money/放定点金额能力,server/internal/crypto/放密钥加密、生成与哈希,server/internal/config/放环境变量名称、解析和默认值。dashboard/index.html是静态前端入口;dashboard/js/data.js放/admin数据接入;dashboard/js/core.js放导航、路由和启动逻辑;dashboard/js/views/按页面放视图代码。docs/api-requirements.md是管理端与下游 API 契约来源,docs/backend-structure.md记录后端结构细节。接口或结构发生变化时同步更新对应文档。deployments/放本地部署配置。communication/只用于本地协作,不得提交。- 新文件优先放入现有业务模块。只有出现独立、稳定且可清晰命名的业务能力时才新增顶层模块,禁止按
service、handler、utils等泛化技术层创建兜底目录。
边界规则
- 后端按业务能力纵向组织。
catalog、accounts、usage、ratelimit、quota、proxy各自持有本领域入口和规则,不把业务重新集中到通用 handler 或 service 包。 - 业务模块通过
server/internal/store中的窄端口访问持久化,不直接依赖 PostgreSQL、pgx 或 sqlc。Store 实现不得反向依赖 HTTP 层。 server/internal/httpapi负责协议入口和委托,不负责选路、计费、认证、限流、熔断或结算等代理业务。- OpenAI JSON wire type 只能出现在
server/internal/proxy/openai和必要的 HTTP 适配边界。domain、store、catalog、accounts、usage、ratelimit不能依赖 OpenAI 协议 DTO。 server/internal/proxy使用协议中立 contract 编排业务,不直接操作http.ResponseWriter,也不依赖具体 Store 实现。money和crypto是叶子能力包,不得依赖store、httpapi或业务模块。禁止各业务模块或 Store 重复实现金额、加密和哈希逻辑。/admin接口统一返回{code,message,data},列表统一返回{list,total}。时间使用 RFC3339,自然日使用YYYY-MM-DD。/v1尽量保持 OpenAI 兼容;认证使用Authorization: Bearer <gateway-key>,错误响应保持稳定、可识别。- 金额禁止使用
float64参与计算。数据库使用NUMERIC,Go 使用定点整数,对外使用字符串。 - 渠道 API Key 必须加密存储;网关 Key 只存哈希,明文只在创建或重置时返回一次。响应、日志和错误信息不得泄露密钥、Token、数据库密码或其他敏感配置。
- 修改 SQL 查询或 schema 后运行
sqlc generate;迁移只能新增,不修改已发布迁移的既有语义。 - Dashboard 默认请求同源
/admin,也支持?api_base=http://host:port/admin。如增加管理端认证、修改响应结构或接口路径,必须同步修改前端数据层。 - Dashboard 启动会并发请求多个管理端接口,任一失败都会进入错误页。修改启动接口时必须同时验证
/admin/stats/overview、/admin/stats/daily、/admin/channels、/admin/stats/channels、/admin/usage-logs、/admin/users、/admin/rate-limits、/admin/models、/admin/quota-policies和/admin/quota-usage。 - 前端当前使用带 JSON 请求体的
DELETE /admin/pricing;除非同步修改前端,否则后端必须保持兼容。 - 修改前检查工作区状态,不覆盖或回退他人改动,不做无关的大范围重排或格式化。提交应聚焦一个目标,不得提交
communication/、本地密钥或其他敏感文件。 - 后端变更至少执行
go test ./...、go build ./...、go vet ./...和gofmt -l cmd internal。PostgreSQL 集成测试使用TEST_DATABASE_URL;未设置时测试会跳过,不能据此宣称 PostgreSQL 路径已验证。
注释规则
- 注释解释设计原因、边界条件、事务语义、并发约束、安全要求或不直观的兼容行为,不复述代码表面动作。
- 公共 Go 标识符仅在名称和类型不足以表达契约时补充简洁注释;注释应以标识符名称开头并描述调用方需要知道的行为。
- 复杂业务流程只在关键决策点加注释,例如重试条件、熔断状态转换、计费舍入、结算原子性和 best-effort 行为。不要逐行注释。
- 已知限制必须说明影响和后续条件,优先关联对应 Issue,例如
TODO(#56): ...。禁止使用没有责任边界的TODO、FIXME或“临时处理”。 - 协议兼容代码应注明兼容对象和不能简化的原因,例如 OpenAI SSE 帧语义或前端
DELETE请求体约定。 - 安全相关注释不得包含真实密钥、Token、连接串或可用凭据;示例统一使用明显的占位值。
- SQL 注释说明查询意图、锁或事务要求,不重复字段名。迁移注释说明不可逆操作和数据兼容风险。
- 前端注释只说明数据来源、派生口径、浏览器兼容或非显然交互,不为普通 DOM 操作添加说明。
- 不在
server/internal/db/sqlc/生成文件中添加或修改注释;应修改源 SQL 后重新生成。 - 移动或重构代码时同步更新失效注释。与实现不一致的注释视为缺陷,不保留历史描述。
