# AGENTS.md

给 AI 协作者的仓库指引。**开始任何工作前，先读 [`README.md`](README.md)**——它是全景入口：项目是什么、为什么长这样、走到哪了。

## 协作约定（长期有效）

- **Git**：仅当项目作者明确说"提交 / commit"时才执行提交；`git push` 永远由项目作者手工执行，AI 绝不推送
- **命名**：需求 / 设计 / 交互 / 技术 / 计划等**文档名**用中文（`README` / `AGENTS` / `LICENSE` 等约定俗成除外）、**目录**用英文；新文档按性质放入 `docs/design/`（我们定的方案与决策）或 `docs/references/`（平台可用接口参考——实证事实，不做设计决策），并同步更新 README 的「文档地图」；`docs/deprecated/` 只归档已废弃文档——**勿引用、勿作依据**（需要时再建）
- **代码文件命名**：所有**目录名与文件名**一律 kebab-case（如 `time-range-picker.vue` · `admin-session.ts`）；**组件在模板中引用时用大驼峰**（`<TimeRangePicker />`）——文件名 kebab、模板标签 PascalCase
- **文档状态**：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古）
- **部署**：交付物必须保证「一条命令链」可部署；**双形态并行已裁决**——完整前后端（运营方服务器）先行，Cloudflare Workers 抽取版（作者自部署）后续（见 `docs/design/需求清单.md` R13）
- **不引入版本叙事**：不使用 v1/v2/v3 之类版本编号，不以「MVP」等标签或指称显式描述任何历史阶段；文档内容必须**自立**——不得引用、描述任何当前仓库之外、可能被删除的分支或目录内容
- **本地不入库也不 ignore 的物料**（AI 提交时务必避开）：`api*.json`（上游实测快照）、`session-archive/`（作者主动备份的会话记录）——不加入 git、不写 `.gitignore`，靠提交时人工/执行者目视把关

## 项目速览（速记）

- **本仓库 = 设计文档中心 + 实现主线**：实现代码与文档同仓演进，monorepo 结构（`apps/server` · `apps/engine` · `apps/web` · `packages/core` · `packages/db`）见 `docs/design/技术选型.md` §4
- 数据模型：基线表（`api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history`）+ 三张访问主体表（`members` · `users` · `sessions`）——支付登记已拆为 `subscriptions` + `topups`（见 `docs/design/payments建模评估.md`）；同步架构（轮询 + `request_id` 去重 + 攒库）的动因由上游物理约束决定
- 需求总集与裁决档案见 `docs/design/需求清单.md`；交付形态已裁决（双形态并行，完整形态先行）
- 上游约束速记：只有 sk-key、无时间过滤接口 → 轮询攒库是唯一路径（README「架构的根本动因」）

## 命令

Bun 工具链（选型见 `docs/design/技术选型.md`）。**Windows 上 `bun` 需在 PowerShell 7（`pwsh`）里跑**——mise shim 由 pwsh profile 激活；Windows PowerShell 5.1 会报 command not found，改用 `pwsh -c "…"` 或绝对路径。

| 命令 | 用途 |
|------|------|
| `bun install` | 安装 / 链接 workspace 依赖（在仓库根） |
| `bun run db:generate` | 生成 SQL 迁移（`packages/db/drizzle/`） |
| `bun run db:push` | 推送到本地库（开发期；**服务启动不自动迁**） |
| `bun run db:studio` | Drizzle Studio 看库 |
| `bun run typecheck` | 根 tsconfig 类型检查（不含 web `.vue`） |
| `bun run dev:server` | 开发跑后端（hot reload） |
| `bun run dev:engine` | 开发跑同步引擎（独立进程，读 `SYNC_*` env） |
| `bun run dev:web` | 开发跑前端 Vite |
| `bun run build:web` | 前端类型检查 + 产物构建 |
| `docker compose up -d --build` | 部署一键起（server / engine / caddy / pg） |

环境变量见 `.env.example`（复制为 `.env` 后填写）。

**默认端口 `18456`**（避开 3000/3001 等本机占用）；`NEWAPI_BASE` 是上游 NewAPI 地址，与本服务端口无关。在线文档：`http://127.0.0.1:18456/api/docs`。