mnote/AGENTS.md

Repository Guidelines

项目结构与模块组织

• wolai-frontend/：主前端（Next.js），源码在 wolai-frontend/src/，静态资源在 wolai-frontend/public/。
• wolai-backend/：后端（FastAPI + Celery），源码在 wolai-backend/app/。
• services/：配套服务与集成点（如 services/mineru/ OCR、RAG 相关服务等）。
• supabase/：本地 Supabase 迁移与配置（参考 supabase.md 的本地端口说明）。
• pw-tests/：端到端测试（Playwright + Python），脚本在 pw-tests/scripts/，产物在 pw-tests/artifacts/。
• 根目录 src/：Next.js 相关代码与共享模块（如 src/app/、src/components/ 等）。

构建、测试与本地开发命令

• 一键热启动（推荐）：在仓库根目录执行 npm run desktop:hot（启动 wolai-frontend + wolai-backend；Redis 可用时自动启动 Celery）。
• 前端：cd wolai-frontend && pnpm dev|build|start；质量检查：pnpm lint；单测：pnpm test。
• 后端：cd wolai-backend && pip install -r requirements.txt；运行：uvicorn app.main:app --reload --port 8000；Worker：celery -A app.workers.celery_app worker --loglevel=info。
• E2E：cd pw-tests/scripts && python e2e_mindmap_sync.py（更多脚本见 pw-tests/README.md）。

编码风格与命名约定

• 文件编码：统一使用 UTF-8；缩进建议：TS/TSX 2 空格，Python 4 空格。
• 命名示例：组件 PascalCase.tsx，hooks useXxx.ts，测试文件 *.test.ts(x)（Vitest 配置包含 src/**/*.test.ts(x)）。
• 优先遵循现有 ESLint/Vitest 配置（见 eslint.config.mjs、vitest.config.ts）。

提交与 Pull Request 规范

• 提交信息在历史中常见两类：版本号摘要（如 0.1.13 ...）与类 Conventional Commits（如 feat(mindmap): ... / fix(mindmap): ... / chore: ...）。新增提交建议延续该风格。
• PR 需要：变更说明（动机/影响范围）、必要的 UI 截图、可复现步骤或测试结果、关联的 issue/任务链接。

安全与配置提示

• 不要提交密钥/Token/账号；本地配置优先放在 .env.local、wolai-frontend/.env.local、wolai-backend/.env。
• 如发现敏感信息已进入仓库，请立即轮换密钥，并与维护者确认是否需要清理历史记录。

Agent/自动化协作注意

• 仅修改与目标相关的文件；不要擅自回滚、覆盖或丢弃他人改动；代码注释使用简体中文并保持 UTF-8。

代码索引

• 更细的前后端代码层级索引见 CODE_INDEX.md（按路由/API/模块/职责整理，便于后续快速定位与开发）。