diff --git a/backend/AGENTS.md b/backend/AGENTS.md deleted file mode 100644 index 2c3db52..0000000 --- a/backend/AGENTS.md +++ /dev/null @@ -1,73 +0,0 @@ -# 后端开发 - -## 技术栈 - -Python 3.12 + FastAPI + SQLAlchemy + Alembic + loguru + httpx + chromadb -uv (用于虚拟环境和依赖管理) - -## 开发命令 - -启动命令之前确保目前在backend目录下,并且已经激活了虚拟环境。默认本地开发使用 SQLite(aiosqlite)文件数据库,Redis、ChromaDB、Neo4j 暂不启用 - -```bash -uv venv -p 3.12 # 创建虚拟环境 -source .venv/bin/activate # 激活虚拟环境 -uv add # 添加依赖 -uv remove # 移除依赖 -uv run python -m app.main # 按 .env 中 BACKEND_HOST/BACKEND_PORT 启动服务 -uv run uvicorn app.main:app --reload --port 8000 # 手动指定端口启动服务(命令行 --port 会覆盖 .env) - -# 数据库迁移 -uv run alembic revision --autogenerate --rev-id=001 -m "描述" # 生成迁移 -uv run alembic upgrade head # 执行迁移 -uv run alembic downgrade -1 # 回滚一个版本 -uv run alembic current # 查看当前版本 - -# 测试 -uv run pytest # 运行测试 -``` - -## 代码规范 - -在__init__文件中可以将模块内的类、函数等导出,方便其他模块导入使用 -遵循 PEP 8 代码风格指南和更加pythonic的开发方式 -遵循单一职责原则,每个文件、类、函数等都要只干一件事 -使用 loguru 进行日志记录,避免使用 logging 模块 -使用 Alembic 进行数据库迁移,禁止手动修改数据库表结构,文件命名以迁移版本号开头,例如 001_initial.py;迁移必须优先兼容 SQLite,涉及 PostgreSQL 专用 DDL 时必须提供 SQLite 分支或显式跳过 -使用alembic init alembic命令初始化迁移环境,使用命令生成相关的迁移文件,不能直接生成迁移文件 -使用 httpx 进行异步 HTTP 请求,禁止在路由函数内直接使用同步数据库会话或 httpx 客户端 -所有的测试代码都写在tests目录下,测试文件命名以test_开头,测试函数命名以test_开头 -所有敏感信息(如密钥、Token、数据库密码)必须通过环境变量或配置文件管理,禁止硬编码到代码中 - -### 分层硬规矩 - -- `modules/` 禁止 import `repositories` / `db` / `integrations` / `httpx` / `sqlalchemy`——一旦需要 IO,立即上移到 `services` 或 `application`。 -- 路由函数禁止直接 `Depends(get_session)` 或写业务逻辑——改为注入 usecase / service。 -- `repositories/` 返回 ORM,禁止把 Query / Session 暴露到上层。 -- 模型能力(对话/多模态/嵌入/重排)一律进 `ai_provider/`;存储/检索/外部接入进 `integrations/`。 -- 配置一律进 `core/config/`,业务目录不持有 `settings.py` / `config.py`。 -- `.env` 只放项目根目录,`Settings` 以绝对路径 `_env_file` 初始化,不使用 `python-dotenv`。 - -## 代码审查 - -开发完成后必须使用以下命令进行代码检查: - -```bash -uv run ruff check # Lint 检查 -uv run ruff check --fix # 自动修复部分代码风格问题 -uv run pre-commit run --all-files # 可选:完整运行 CI 级检查(包括类型检查) -``` - -确保没有任何 lint 错误后再提交。 - -## 绝对禁止事项 - -直接修改 pyproject.toml 文件添加或者移除依赖(必须使用 uv add/remove 命令) -在路由函数内直接使用同步数据库会话(必须通过 Depends 注入) -在路由函数内直接 async with httpx.AsyncClient() -使用 logging 模块(统一用 loguru) -硬编码密钥、Token、数据库密码到代码 -手动创建/修改数据库表结构(必须使用 Alembic 迁移) -在 `modules/` 中 import `repositories` / `db` / `integrations` / `ai_provider` / `httpx` / `sqlalchemy`(领域层禁止 IO,需要 IO 时上移到 services/application) -在业务目录(`integrations` 等)中持有 `settings.py` / `config.py`(配置统一进 `core/config/`) -使用 `python-dotenv`(`.env` 由 `core/config` 以绝对路径 `_env_file` 加载) diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md deleted file mode 100644 index a5f2e19..0000000 --- a/frontend/AGENTS.md +++ /dev/null @@ -1,187 +0,0 @@ -# 前端开发规范 - -## 技术栈 - -Next.js + TypeScript + React + Tailwind CSS + Zustand/Jotai + pnpm - -### 核心依赖 - -- **实时通信**: SSE / WebSocket -- **可视化**: Mermaid + 图谱可视化库 -- **测试**: Vitest + Testing Library -- **代码质量**: ESLint (flat config) + Prettier + Husky + lint-staged - -## 开发命令 - -```bash -pnpm install # 安装依赖 -pnpm add # 添加依赖 -pnpm remove # 移除依赖 - -pnpm dev # 启动开发服务器 (默认端口 3000) -pnpm build # 构建生产版本 -pnpm start # 启动生产服务器 - -pnpm lint # 运行 ESLint 检查 -pnpm type-check # TypeScript 类型检查 - -# 代码格式化(Prettier) -pnpm format # 格式化全部文件 -pnpm format:check # 检查格式是否合规(CI / 提交钩子使用) - -# 测试(Vitest) -pnpm test # 运行全部测试(单次) -pnpm test:watch # 监听模式 -pnpm test:coverage # 运行测试并生成覆盖率报告 -``` - -## 代码规范 - -### 页面设计 - -图标:统一使用 Lucide 图标,界面全程禁止使用表情符号。 -设计标准:对标 Awwwards 顶级网站水准,达到 Awwwards、FWA、CSS Design Awards 每日最佳网站同等设计品质。 -创意自由度:将浏览器视作交互式艺术画布,跳出传统布局框架,追求先锋视觉风格、实验性排版、流畅物理动效、极具冲击力的文字版式。 -沉浸式体验:融合代码、高级渲染逻辑、图片素材,打造统一完整的精品页面,做出突破常规 UI 认知、令人惊艳的数字交互体验。 - -### 通用规范 - -- 遵循 ESLint + Prettier 配置,提交前必须通过 lint 与格式检查 -- 使用 TypeScript 严格模式 (`strict: true`),禁止使用 `any` 类型 -- 组件使用函数式组件 + Hooks,优先使用 Server Components,必要时使用 `'use client'` -- 文件命名: 组件使用 PascalCase (`UserProfile.tsx`),工具函数使用 camelCase (`formatDate.ts`) -- 使用 `path` 别名 (`@/*`) 导入模块,避免相对路径层级过深 -- 状态管理: 全局状态使用 Zustand/Jotai,局部状态使用 React useState/useReducer - -### CSS 变量引用 - -CSS 变量引用遵循 **三层递进规则**,优先级由上至下。 - -#### 规则 - -```text -Tailwind 映射类 → 优先使用 -Tailwind 任意值 [var(--)] → 仅当变量不在 @theme 映射表中时使用 -内联 style → 仅限复合值 / 动态运行时值 -``` - -#### 具体对照 - -`globals.css` 的 `@theme inline {}` 块已映射的部分,直接用 Tailwind 类: - -```tsx -// ✅ 正确:变量在 @theme inline {} 中有 --color-X 映射 → 用 Tailwind 类 -
- -
-
-