skycurtain
0e9db439ba
- docs/delivery/部署文档.md：前置条件 / 环境变量 / 一条命令链 / systemd 与 Nginx 示例 / 首次运行检查 / 运行约束（后端单实例 · 3 天窗口 · 主密钥 · 401 摘除）/ 升级 / 排查 - 从零端到端走查：清库 → db:push → 启动（空转 + QPU 基线）→ 管理面登记 → 引擎立即补一轮（984 条）→ 查看面查询（未折算「—」）→ 补录购买记录 → 金额出现 → 换算参数时间线；无 pageerror - 8 篇设计文档状态 → 已实现（2026-09-15） - README：状态行 / 文档地图（含 delivery）/ 下一步（部署 + 待补验与裁决清单） - AGENTS.md：项目速览更新
44 lines
3.2 KiB
Markdown
44 lines
3.2 KiB
Markdown
# AGENTS.md
|
||
|
||
给 AI 协作者的仓库指引。**开始任何工作前，先读 [`README.md`](README.md)**——它是全景入口：项目是什么、为什么长这样、走到哪了。
|
||
|
||
## 协作约定（长期有效）
|
||
|
||
- **Git**：仅当项目作者明确说"提交 / commit"时才执行提交；`git push` 永远由项目作者手工执行，AI 绝不推送
|
||
- **命名**：需求 / 设计 / 交互 / 技术方案 / 计划等**文档名**用中文（`README` / `AGENTS` / `LICENSE` 等约定俗成除外）、**目录**用英文；新文档按性质放入 `docs/design/`（我们定的方案与决策）或 `docs/upstream/`（NewAPI 的实证事实，不做设计决策），并同步更新 README 的「文档地图」；`docs/deprecated/` 只归档已废弃文档——**勿引用、勿作依据**
|
||
- **文档状态**：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古），尚未入库的历史文档移入 `docs/deprecated/`
|
||
- **部署**：项目作者不接触服务器，一切部署由实例运营方执行；交付物需保证「一条命令链」可跑
|
||
|
||
## 项目速览（速记）
|
||
|
||
- 针对 NewAPI 平台的 key 用量统计工具；**只有 sk-key，没有管理员账号**，一切数据走 key 级接口
|
||
- 上游没有任何时间过滤接口 → 轮询 `/api/log/token` + `request_id` 去重攒本地库，任一时段用量 = 本地聚合
|
||
- 数据模型四张表：`api_keys` · `usage_logs` · `purchases` · `qpu_history`（**四张表设计均已实现**）；四张表各有一篇独立表字段设计文档（`docs/design/`）
|
||
- **功能已实现（阶段 0–8，2026-09-15）**：前后端独立部署、后端单进程（API + 同步引擎同进程、单实例）；部署见 `docs/delivery/部署文档.md`；未决事项（实现假设与待定问题）见 `docs/design/实施计划.md`
|
||
|
||
## 命令
|
||
|
||
monorepo（Bun workspaces：`apps/web` · `apps/server` · `packages/shared`）——根目录执行：
|
||
|
||
```bash
|
||
bun install # 安装全部依赖（一次搞定）
|
||
|
||
bun run dev # 并行起前端（Vite :5173）与后端（Hono :3000）
|
||
bun run dev:web # 只起前端
|
||
bun run dev:server # 只起后端（--hot 热重载）
|
||
|
||
bun run build # 构建前端产物（apps/web/dist）
|
||
bun run test # 前端单测（Vitest）
|
||
bun run lint # 前端 lint（oxlint + eslint）
|
||
bun run type-check # 类型检查（vue-tsc + tsc）
|
||
|
||
bun run db:generate # 生成 Drizzle 迁移（apps/server/drizzle）
|
||
bun run db:migrate # 执行迁移
|
||
bun run db:push # 直接推 schema（开发期）
|
||
bun run seed # 灌入开发数据（样例快照 → 四张表；幂等，仅本地）
|
||
```
|
||
|
||
- 环境变量：复制 `.env.example` 为 `.env` 并填值（`DATABASE_URL` / `MANAGE_TOKEN` / `KEYS_MASTER_KEY` / `NEWAPI_BASE`；离线开发可加 `UPSTREAM_SOURCE=fixture` 走样例快照，见 `docs/design/实施计划.md` §6）
|
||
- 目录速记：前端 `apps/web/src/{api,router,views}` · 后端 `apps/server/src/{db,routes,sync,lib}` · 契约类型在 `packages/shared`
|
||
- 开发期前端 `/api` 由 Vite 代理到 :3000（`apps/web/vite.config.ts`）；生产由同域反代承担（见 README 工程注记）
|