From 41ef047b6ee24b7e570dd69850a0fd7c27dd85c5 Mon Sep 17 00:00:00 2001
From: SmartUp Developer <dev@smartup.local>
Date: Mon, 6 Jul 2026 10:41:40 +0800
Subject: [PATCH] Add repository contributor guide

---
 AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4c3717c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,40 @@
+# 仓库指南
+
+## 项目结构与模块组织
+
+SmartUp 主应用由 FastAPI 后端和 Vue 3/Vite 前端组成，并通过 Docker Compose 打包运行。后端代码位于 `backend/app/`：`routers/` 定义 API 路由，`services/` 放业务逻辑和上游集成，`models/` 是 SQLAlchemy ORM，`schemas/` 是 Pydantic 类型，`utils/` 放通用工具。后端测试为 `backend/test_*.py`。
+
+前端代码位于 `frontend/src/`：`views/` 是页面，`components/` 是复用组件，`api/` 封装 Axios 请求，`stores/` 管理 Pinia 状态，`assets/` 存放样式和静态资源。`data/` 存放本地 SQLite 数据库，视为运行时数据。
+
+## 上下游网关与扩展目录
+
+`new-api/`、`nox-api/`、`sub2api/` 和 `browser-extension/` 是 SmartUp 监控、同步和对接的上下游 API 网关或配套扩展，不是 Python 应用的一部分。其中 Go 项目有独立的 `go.mod`、README、Dockerfile 或本地 `AGENTS.md`，修改时优先遵循各自目录内说明。
+
+当 Python 应用中关于上游/下游账号、密钥、分组、模型、额度、认证头或同步流程的逻辑不清楚时，应读取这些目录的源码来确认真实接口行为，不要只按后端字段名猜测协议。
+
+## 构建、测试与开发命令
+
+- `make up`：使用现有镜像启动 Docker Compose 应用。
+- `make up-build`：依赖或镜像配置变化后重新构建并启动。
+- `make log`：查看 `smartup` 服务日志。
+- `cd backend && pip install -r requirements.txt`：安装后端依赖。
+- `cd backend && uvicorn app.main:app --reload --port 8000`：本地运行 API。
+- `cd backend && pytest`：运行后端测试。
+- `cd frontend && npm install`：安装前端依赖。
+- `cd frontend && npm run dev`：启动 Vite；`npm run build` 执行类型检查并构建。
+
+## 编码风格与命名约定
+
+Python 使用 4 空格缩进，模块名使用 snake_case，例如 `finance_service.py`、`external_api_logs.py`。路由处理函数应保持精简，将业务逻辑下沉到 `services/`。请求和响应边界使用 Pydantic schema。
+
+前端使用 Vue SFC 和 `<script setup lang="ts">`，保持单引号、无分号风格。组件和页面使用 PascalCase，接口访问逻辑放在 `frontend/src/api/`。
+
+## 测试规范
+
+后端测试使用 `pytest`，文件命名为 `backend/test_*.py`。新增调度、上游、认证、财务、站点同步等行为时，应补充聚焦测试。前端暂无测试框架，修改 UI 后至少运行 `npm run build`，并记录关键页面的手动验证结果。
+
+## 提交与 Pull Request 规范
+
+历史提交混用 `feat:`、`fix:` 和祈使句摘要（如 `Add ...`、`Improve ...`）。建议使用简短祈使句；功能和修复类改动可使用 `feat:` 或 `fix:`。每个提交聚焦一个行为变化。
+
+PR 应包含变更说明、关联 issue 或背景、已运行命令（如 `pytest`、`npm run build`、Docker 检查）、UI 变更截图，以及 `.env` 或数据库影响说明。不要提交 `.env` 密钥或 `data/` 下的本地数据库文件。