mnote/AGENTS.md

仓库协作指南（AGENTS）

关键事实（防止误判）

• 当前已使用 Convex 完全替换 Supabase：任何新功能/修复都应以 Convex 为唯一数据源与鉴权/权限基础。
• 仓库内可能仍存在 supabase/、supabase.md、wolai-frontend/src/lib/supabase/、@supabase/* 依赖等历史遗留：除非任务明确要求清理，否则不要基于它们继续扩展实现。

项目结构与模块组织

• wolai-frontend/：主前端（Next.js），源码在 wolai-frontend/src/，静态资源在 wolai-frontend/public/。
• wolai-frontend/convex/：Convex functions（schema / query / mutation / action 等）。
• infra/convex/：Convex 自托管（Docker Compose + README + 本地 .env）。
• wolai-backend/：后端（FastAPI + Celery），主要用于辅助能力（如 OCR、OnlyOffice/集成类服务等）。
• services/：配套服务与集成点（如 services/mineru/ OCR、RAG 相关服务等）。
• pw-tests/：端到端测试（Playwright + Python），脚本在 pw-tests/scripts/，产物在 pw-tests/artifacts/。
• 根目录 src/：Next.js 相关代码与共享模块（可能为历史/镜像目录；优先改 wolai-frontend/src/）。

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

• 一键热启动（推荐）：在仓库根目录执行 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）。
• Convex（自托管）启动：见 infra/convex/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）。

协作边界（重要）

• 仅修改与目标相关的文件；遇到与任务无关的改动保持不动；若认为会影响任务，先与维护者确认。
• 严禁自行还原、覆盖或丢弃他人/用户已有改动（包括未提交文件）。如需清理或回滚，必须先得到明确同意。
• 不需要进行任何 git 操作（由维护者手动确认与提交）。

代码索引

• 更细的前后端代码层级索引见 CODE_INDEX.md（按路由/API/模块/职责整理）。