开发约定

协作语言

协作、提交说明和项目文档使用中文。

文件职责

单个代码文件应控制行数。文件职责过多、分支复杂或测试难以聚焦时，应优先拆分模块。

文件头注释

每个源代码文件开头应包含文件功能描述，Markdown 文件除外。

函数注释

函数注释优先解释职责、输入输出和关键约束，避免重复代码字面含义。

包管理

• 前端使用 pnpm。
• Python 项目使用 uv 管理依赖，并使用 venv 管理虚拟环境。

服务启动

项目通常已经启动。需要确认运行态时，先查看现有进程、端口或文档说明，不要反复启动服务。

文档更新

产品定位、核心流程、部署入口、开发约束、测试策略或跨模块契约变化时，应同步更新对应文档。