58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
# 仓库协作指南（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 空格缩进。
|
||
- 注释使用简体中文。
|