AGENTS.md

本文件是代理在本仓库工作的常驻入口。这里只保留每次任务都应知道的规则；具体机制按任务阅读 docs/ 中的专题文档。代码和测试是当前行为的最终事实来源。

沟通语言

所有对话回复必须使用简体中文。代码、命令、路径、标识符、API 路径、配置项、日志原文、英文专有名词与缩写保持原样。

项目概览

Codex Helper 是单容器部署的 Codex 账户用量仪表盘，通过外部 CLIProxyAPI Management API 读取已托管 Codex 凭据对应的 ChatGPT/Codex 账户、限额和 Token 历史，并通过 Telegram 与 SMTP 发送重置提醒。

backend/：Go 1.26、net/http 与 SQLite 后端；backend/CONTRACT.md 是 API 路径、状态码、响应结构和兼容文案的契约。
frontend/：React 19、TypeScript、Vite、Recharts 前端；生产构建嵌入 Go 二进制。
Dockerfile：依次构建前端和 Go 后端，最终以 UID 10001 非 root 用户运行；运行镜像不包含 Codex CLI。
docker-compose.yml：对外映射端口并将 Codex Helper 自身的数据库与密钥保存到 codex-helper-data 卷的 /data；CPA 凭据由外部服务保存。

开始工作前

先阅读改动相关的代码、调用方和测试，不要仅凭文档推断行为。
从 docs/README.md 选择对应专题；修改 API 时同时核对 backend/CONTRACT.md。
修改鉴权、SQLite、账号删除、CLIProxyAPI 集成、凭据、提醒、备份或部署时，先读 docs/reference/engineering-invariants.md。
执行代码审查时，必须遵循 docs/reference/code-review-rules.md。

环境与执行政策

宿主机只保证 Docker 和 Docker Compose。依赖安装、Go/Node 命令、构建、测试、格式化、类型检查和安全扫描均在容器内执行；不得在宿主机安装或直接运行 go、node、npm 等工具，也不得修改宿主机工具链或 shell 配置。

后端基线为 golang:1.26.0-bookworm，前端为 node:24.19.0-bookworm-slim，E2E 使用与 @playwright/test 版本匹配的官方 Playwright 镜像。完整命令见 docs/guides/development-and-validation.md。纯文档改动无需运行应用构建。

验证与审查

行为修改必须验证成功路径、关键边界和失败路径；修复缺陷时优先添加能复现原问题的回归测试。
后端至少运行相关 Go 测试以及 gofmt 检查、go build ./... 和 go vet ./...；SQLite 迁移、并发、CLIProxyAPI 客户端或备份改动必须运行相关集成测试。
前端至少运行相关 Vitest 和 npm run build；布局、路由、账号设置或响应式交互改动运行相关 Playwright 测试。
Dockerfile、Compose、持久化或运行用户改动必须验证镜像或 Compose 配置，并核对升级数据路径。
代码审查只报告可复现、由当前改动引入或暴露的问题，按 P0–P3 排序；完整流程见 docs/reference/code-review-rules.md。

必须保持的约束

HTTP 业务接口保持在 /api/v1/；未初始化状态只开放 status、setup 和 login，其他接口必须经过 session 与非只读请求来源校验。
backend/internal/store/store.go 中的 schema 和兼容迁移是 SQLite 结构的事实来源；启动迁移必须保留旧库数据并保持幂等。
旧账号及其历史数据升级时必须保留，并以空 auth_index 等待管理员绑定 CPA；新数据库不再创建无绑定的默认账号。
每个非空 CPA authIndex 最多绑定一个本地账号；添加或修改前必须验证其唯一指向未禁用的 Codex auth，失败不得留下半完成记录。
删除账号会删除本地数据库历史且不可恢复，但不得删除 CLIProxyAPI 中的凭据；前后端必须明确确认精确目标。
session cookie 只保存随机 token，数据库只存 SHA-256 摘要；密码继续使用 argon2id，SMTP 密码和 Telegram Token 继续由 /data/secret.key 加密。
设置接口不得返回 SMTP 密码或 Telegram Token 明文；CPA management key、OAuth token 和其他秘密不得进入 Git、日志、前端状态快照或 Docker 构建上下文。
CPA 地址和 management key 只从服务端环境读取，公开响应必须隐藏 authIndex；所有 Management API 请求必须有超时、大小限制和不泄密错误。
限额百分比、窗口和 Token 摘要以 CPA 代请求的 /wham/usage 与 /wham/profiles/me 返回值为准；optional、null、多 bucket 和未知套餐必须安全降级。
提醒以稳定 dedupe key 去重，失败只在计划时间后六小时窗口内重试；提前、计划后和异常提前重置语义不得混淆。
SQLite 下载仅是包含已提交 WAL 数据的一致性数据库快照，不包含 secret.key 或 Codex 凭据；完整恢复必须备份整个 /data。
前端路由和隐藏控件只负责交互，安全边界必须由后端强制执行；账号邮箱在界面中继续掩码显示。

文档维护

后端运行、认证、Codex 集成、数据和通知机制写入 docs/backend/；前端实现写入 docs/frontend/。
可执行的开发与部署步骤写入 docs/guides/；工程不变量和代码审查规则写入 docs/reference/。
用户功能和部署概览继续维护在根 README.md；端点级 API 契约维护在 backend/CONTRACT.md，专题文档通过链接引用。
行为变更必须同步更新相关文档；文档与实现冲突时先以代码和测试为准，再修正文档。

5.7 KiB Raw Blame History Unescape Escape