# 仓库协作指南（AGENTS）

## 当前主线事实

- 当前仓库已经做过精简，旧设计稿已移动到 `/mnt/Data1T/mnote/recycle/design/`。
- 当前主前端在 `/mnt/Data1T/mnote/wolai-frontend/`，这是默认优先修改的位置。
- 当前辅助后端在 `/mnt/Data1T/mnote/wolai-backend/`。
- 当前 Convex 自托管配置在 `/mnt/Data1T/mnote/infra/convex/`。
- 根目录历史 `/mnt/Data1T/mnote/src/` 已只保留 `/mnt/Data1T/mnote/src/components/onlyoffice/`，这里仍然属于运行相关资源，不要误删。
- `/mnt/Data1T/mnote/ARCHITECTURE.md` 是当前仓库结构与嵌入关系的最新说明，涉及 BlockNote、Mindmap、OnlyOffice 时优先参考它。

## 目录约定

- `/mnt/Data1T/mnote/wolai-frontend/src/`
  当前前端主源码目录。
- `/mnt/Data1T/mnote/wolai-frontend/convex/`
  当前 Convex functions 目录。
- `/mnt/Data1T/mnote/wolai-backend/app/`
  当前后端主源码目录。
- `/mnt/Data1T/mnote/src/components/onlyoffice/`
  当前保留的 OnlyOffice 静态资源、插件与相关数据目录。
- `/mnt/Data1T/mnote/recycle/`
  已废弃或已下线内容的回收区，默认不要基于这里继续扩展实现。

## 开发优先级

1. 涉及页面、编辑器、块系统、思维导图、OnlyOffice 页面时，优先检查 `/mnt/Data1T/mnote/wolai-frontend/src/`。
2. 涉及数据模型、查询、动作、任务编排时，优先检查 `/mnt/Data1T/mnote/wolai-frontend/convex/`。
3. 涉及辅助服务、接口配合、异步处理时，检查 `/mnt/Data1T/mnote/wolai-backend/app/`。
4. 只有在处理 OnlyOffice 静态资源、插件或兼容问题时，才进入根目录 `/mnt/Data1T/mnote/src/components/onlyoffice/`。

## 关键架构认知

- `BlockNote` 是当前文档页主编辑器内核。
- `Mindmap` 是 BlockNote 的自定义 block，同时支持内嵌和独立全屏页，两者共用同一核心组件。
- `OnlyOffice` 是独立页面型编辑器，不直接嵌入 BlockNote 编辑画布；正文中通常通过附件块跳转进入。

## 协作边界

- 仅修改与当前任务直接相关的文件。
- 不要擅自恢复、覆盖、删除用户已有改动。
- 看到 `/mnt/Data1T/mnote/recycle/` 中的内容时，默认视为历史资料，不作为当前实现依据，除非任务明确要求。
- 若任务涉及架构判断，优先以当前代码与 `/mnt/Data1T/mnote/ARCHITECTURE.md` 为准，不要依赖旧文档记忆。

## 常用开发命令

- 根目录热启动：`npm run desktop:hot`
- 前端开发：`cd /mnt/Data1T/mnote/wolai-frontend && pnpm dev`
- 前端检查：`cd /mnt/Data1T/mnote/wolai-frontend && pnpm lint && pnpm test`
- 后端开发：`cd /mnt/Data1T/mnote/wolai-backend && uvicorn app.main:app --reload --port 8000`
- Convex 自托管：参考 `/mnt/Data1T/mnote/infra/convex/README.md`

## 文件编码与风格

- 所有新增或修改文件统一使用 UTF-8。
- TS/TSX 默认 2 空格缩进，Python 默认 4 空格缩进。
- 注释使用简体中文。