Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (72 loc) · 5.09 KB

AGENTS.md

File metadata and controls

80 lines (72 loc) · 5.09 KB

Repository Guidelines

Project Structure & Module Organization

  • src/app/page.tsx: 主界面（账号中心）、账号卡片、搜索、批量刷新、创建/编辑/写入本地 auth 对话框。
  • src/app/api/profiles/route.ts: 账号列表与创建；创建支持 prefetchedQuota / prefetchedFailure。
  • src/app/api/profiles/[id]/route.ts: 单账号读取、更新（备注+rawJson）、删除。
  • src/app/api/profiles/quota/preview/route.ts: 创建前额度预览。
  • src/app/api/profiles/import-auth/route.ts: 从 ~/.codex/auth.json 导入 JSON。
  • src/app/api/profiles/[id]/replace-auth/route.ts: 将已存账号 JSON 写回 ~/.codex/auth.json。
  • src/app/api/profiles/[id]/quota/refresh/route.ts: 手动刷新某个账号额度。
  • src/app/api/profiles/[id]/quota/latest/route.ts: 获取该账号最新 quota 快照。
  • src/lib/auth: auth JSON 检测、归一化、基础信息预览（支持 tokens 与 openai-codex）。
  • src/lib/quota: 上游请求、quota 解析、刷新与失效标记逻辑。
  • src/lib/db: SQLite 初始化与兼容迁移（client.ts）+ Drizzle schema（schema.ts）。
  • src/lib/ui: 纯 UI 逻辑工具（accountCard.ts、autoRefreshSettings.ts）。
  • src/store/useAuthProfilesStore.ts: 前端全局状态与 API 编排。
  • src/components/ui/ActionTooltip.tsx: 通用提示组件。
  • db/: 本地 SQLite 文件（app.db、WAL/SHM、备份文件）。
  • drizzle/: 迁移 SQL 与元数据快照。
  • auth/: 本地 auth JSON 示例/临时文件（敏感，勿提交真实内容）。
  • codex_quota.py: quota 相关独立辅助脚本。

Build, Test, and Development Commands

  • pnpm dev: 本地开发（http://localhost:3000）。
  • pnpm build: 生产构建。
  • pnpm start: 本地运行生产构建。
  • pnpm lint: ESLint 检查。
  • pnpm test: Vitest 单次运行。
  • pnpm db:generate: 根据 src/lib/db/schema.ts 生成 Drizzle migration。
  • pnpm -s tsc --noEmit: 类型检查（推荐在 UI/store 变更后执行）。

Coding Style & Naming Conventions

  • 使用 TypeScript 且保持 strict 兼容。
  • 保持现有格式：2 空格缩进、分号、双引号。
  • 优先使用 @/ 路径别名导入 src 模块。
  • 命名规范：组件/类型 PascalCase，函数/变量 camelCase，hooks/stores 使用 useXxx。
  • 模块保持领域边界清晰：auth、quota、db、ui、store，避免跨层耦合。
  • API 错误响应统一走 jsonError，结构为 { error: string, ... }。

Domain & API Behavior Conventions

  • 创建流程优先通过 POST /api/profiles/quota/preview 获取预览，再调用 POST /api/profiles。
  • prefetchedQuota 与 prefetchedFailure 互斥；服务端会校验 endpoint 一致性与预取时效（30 分钟内）。
  • quota 预览遇到上游 401/403 时，返回 200 且 quota: null，并携带 deactivated 信息（用于前端“可保存为失效账号”流程）。
  • 刷新策略按标准化 email 复用请求：同邮箱账号可共享刷新结果。
  • 当上游报 401/403 或明显 token 失效信号时，相关账号会被标记 isDeactivated=true。
  • 已停用账号禁止手动刷新（接口返回冲突错误，前端需维持禁用态）。
  • replace-auth 仅允许 sourceType === "chatgpt_tokens" 的账号写入 ~/.codex/auth.json。

Testing Guidelines

  • 测试框架：Vitest（Node 环境），文件命名 *.test.ts，就近放置。
  • 重点覆盖：
    • auth 识别/归一化/预览解析边界（JWT、字段缺失、非法 JSON）。
    • quota 解析与刷新行为（含去激活策略、同邮箱复用）。
    • API 路由行为（import-auth、replace-auth、quota/preview、创建/更新策略）。
    • store 编排行为（串行刷新、并发请求覆盖、动画删除流程）。
  • 提交前建议至少执行：pnpm lint && pnpm test。
  • 涉及 UI/state 变更时再加跑：pnpm -s tsc --noEmit。

UI & Copy Conventions

  • 顶部品牌文案必须保持：
    • Codex Auth Manager
    • Next.js + SQLite 的多账号 Token 管理与额度查询面板
  • 主区块标题必须是 账号中心（不要改成 账号列表 / 账户列表）。
  • + 新建 按钮保持在 账号中心 标题行操作区。
  • 标题旁不要展示账号总数文本。
  • 停用态文案语义保持一致（如“账号已停用，手动刷新已禁用”）。

Commit & Pull Request Guidelines

  • Commit 信息保持短句祈使语气（中文或英文均可），例如：新增认证配额接口与基础配置。
  • 每个 commit 聚焦单一逻辑改动。
  • PR 描述需包含：变更内容、影响路径、验证命令、环境变量/配置影响。
  • 若改动 API，补充示例请求/响应（含错误场景）。

Security & Configuration Tips

  • 常用环境变量：
    • SQLITE_PATH：SQLite 文件路径。
    • QUOTA_ENDPOINT：quota 上游 endpoint。
    • HTTPS_PROXY / HTTP_PROXY / ALL_PROXY / NO_PROXY：上游请求代理控制。
  • 严禁提交真实 auth JSON、access token、生产数据库快照。
  • db/*.db* 与 auth/* 默认按敏感本地文件看待，提交前确认脱敏与必要性。