# 仓库协作指南（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/模块/职责整理）。