From 46dbbd9fbf86197862576fa1d2c4c4bcccbbe5d3 Mon Sep 17 00:00:00 2001
From: gouki <gouki.xiao@gmail.com>
Date: Sat, 17 Oct 2026 21:54:00 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20AGENTS.md=20?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BA=A7=E6=8C=87=E4=BB=A4=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 项目概述与技术栈速览
- 目录结构导航（app/static/scripts/agent/deploy/tests）
- 关键约束（移动端优先、凭据中心化、适配器注册、部署链路）
- 常用命令入口（测试、部署、本地运行）
- 专项规则索引（.qoder/rules/）
---
 AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9282181
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+# vps-manager
+
+VPS 数字资产统一管理面板：多云 VPS / 域名 / AI 账号 / 凭据的登记、监控、续费提醒与同步。
+
+## 技术栈
+
+FastAPI + SQLModel + SQLite 分库（assets.db / metrics.db）+ Vue 3 + Tailwind CSS + Fernet 加密。
+
+## 目录导航
+
+| 目录 | 职责 |
+|------|------|
+| `app/` | FastAPI 后端：routers（API 路由）、services（业务逻辑）、models（SQLModel 模型）、adapters（云厂商 SDK 适配层）、core（配置/加密/鉴权） |
+| `static/` | Vue 3 SPA 前端：js/（视图/状态/模态框）、css/、templates/ |
+| `scripts/` | 运维脚本：AI 余额同步、SSL 证书巡检、续费提醒 |
+| `agent/` | VPS 采集 Agent：资源监控、安全状态、上报中心 |
+| `deploy/` | 部署编排：systemd 单元、update.sh 自动更新、backup.sh 备份 |
+| `tests/` | pytest 测试套件（22 个文件） |
+| `static/js/__tests__/` | vitest 前端测试（4 个文件） |
+
+## 关键约束
+
+- **移动端优先**：底部 Tab 导航，无横向溢出；桌面端侧边栏
+- **凭据中心化**：`credentials` 表是唯一事实源，账号通过 `credential_id` 关联
+- **适配器注册**：`app/adapters/registry.py` 的 `@register` 是唯一事实源；新增 AI 适配器须同步 `app/core/seed.py`
+- **部署链路**：Gitea push → cc1 `update.sh` 自动拉取 → 健康闸门 → 失败回滚
+- **Service Worker**：HTML `network-first`，静态资源 `stale-while-revalidate` + `?v={mtime}`
+
+## 常用命令
+
+```bash
+# 本地运行
+./run.sh
+
+# Python 测试
+.venv/bin/python -m pytest tests/ -x -q
+
+# JS 测试
+npx vitest run
+
+# 部署
+./deploy/deploy.sh
+```
+
+## 专项规则
+
+- 编码规范与架构细节 → `.qoder/rules/coding-standards.md`
+- 部署验收流程 → `.qoder/rules/deploy-verification.md`
+- JS 测试闸门 → `.qoder/rules/js-test-gate.md`
+- Python 测试规则 → `.qoder/rules/vps-manager-pytest.md`