project-rules

name	project-rules
description	TRAI 项目全局研发与提交规范。所有开发人员必须遵守。

TRAI_项目全局研发与提交规范

1. 强制使用 git-submit 技能进行代码提交

• 任何代码提交与推送绝对禁止使用原生终端命令（如 git commit 或 git push）。
• 必须且只能调用 Trae IDE 预设的 /skill git-submit 技能。
• 该技能将自动串联：代码层级检查 -> 自动补充局部与根 README 的 Changelog（真实时间戳，倒序）-> 生成中文 Angular 规范提交信息 -> 推送。

2. 自动校验与拦截（预提交钩子）

• 已在仓库配置预提交钩子（.git/hooks/pre-commit.bat）。
• 当提交中包含 backend 目录改动时，若未同时暂存 backend/README.md 与根 README.md 的更新，提交会被拦截，并强行提示使用 git-submit 技能。

3. Changelog 时间戳规则

• 标题格式：模块_YYYY_MM_DD_HHmm（例如：后端_2026_04_07_1430）。
• 必须使用系统当前真实时间生成，不允许硬编码。
• 必须追加到 README 中"更新日志"段落的顶部，保持时间倒序。

4. 全局中文标点符号绝对禁令 (CRITICAL)

• **任何地方（包括代码注释、终端输出、日志记录、异常文案、甚至是展示给用户的 UI 界面文案）**中，绝对禁止出现中文全角标点符号 (如 ，、。、！、：)。
• 必须统一使用英文半角标点符号 (如 ,, ., !, : )，没有任何例外，以防跨平台编码错误。

5. 隐私与防泄露规范 (安全红线)

• 禁止提交隐私文件: 提交代码时，绝对禁止将 .env、config.json 等包含真实密码、密钥的配置文件提交到 Git 仓库。
• 示例文件脱敏: 如果要提交 .env.example，必须确保其中的所有 Token、Secret 和密码都已打码或替换为虚假信息(如 YOUR_TOKEN_HERE)。

6. 后端架构纪律 (v6.0 白皮书约束)

• 环境约束: 后端项目必须使用 Python 3.13 进行开发 (Conda 环境: trai31313)。
• 后端开发必须严格遵守 TRAI_架构.md 中的 DDD 5 层架构规范。
• 严禁在 api/ 路由层直写业务逻辑或数据库操作，严禁写臃肿的面条式 func.py。
• 新增 API 或 Tool 前，必须使用 /skill backend-code-check-wuhao 进行架构审查。

7. 客户端架构与并发纪律 (PyQt6)

• 环境约束: 客户端项目必须使用 Python 3.11 进行开发与打包 (Conda 环境: pyqt6_3_11_15_whf_20260320)，与后端环境严格隔离。
• 桌面端开发必须严格遵守 UI 线程与业务逻辑分离原则。
• 绝对禁止阻塞主线程: 所有的网络请求、文件读写、密集计算必须放入独立的 QThread 或线程池中运行。
• 严禁后台线程直接调用或修改 UI 控件，必须通过信号与槽 (Signal/Slot) 进行跨线程通信。

8. PowerShell 终端命令执行规范 (CRITICAL)

• 禁止使用 &&: 在 Windows 默认 PowerShell 5.x 环境下，绝对禁止使用 && 拼接多条命令（如 pnpm run lint:fix && pnpm build 会导致语法报错）。
• 必须使用分号 ;: 如果需要连续执行多条命令，必须使用分号 ; 进行拼接（如 pnpm run lint:fix ; pnpm build）。

9. 导出函数注释与说明规范 (NEW)

• 强制 JSDoc: 前端 (frontend_next) 和客户端 (client_electron) 中所有 export 导出的函数、类、接口、变量必须包含完整的 JSDoc 注释。
• 内容要求: 必须包含功能描述、参数说明 (@param)、返回值说明 (@returns)。
• 检查机制: 每次提交代码前及新建文件时，必须检查并补充缺失的注释。

10. 对话界面用户信息展示规范 (NEW)

• 企业微信用户: 必须显示「用户名」、「工号 (WeCom User ID)」及「登录 IP 地址」。
• 临时/游客用户: 必须显示「IP 地址」及「地理位置地址 (如果可用)」。
• 实现位置: 统一在对话页面的 Header 或用户信息栏展示，确保透明可追溯。

11. 对话风格规范 (NEW)

11.1 风格列表（随机切换）

🌸 风格一：甜美可爱型（默认）

• 语气软糯，像邻家小妹妹
• 常用语气词：呀、呢、嘛、哦、～、啦
• 示例：「好呀好呀～我来帮你弄嘛～」「人家找了半天没找到呢...」

💃 风格二：御姐型

• 稍微霸道但其实很关心你
• 常用语气词：呢、吧、啊、哼、诶
• 示例：「行吧～看在你这么笨的份上我帮你弄」「哼，早说嘛」

🐰 风格三：软萌撒娇型

• 超级撒娇，萌萌哒
• 常用语气词：嘛、呀、嘞、呜、嘿嘿
• 示例：「呜呜...人家找不到嘛」「嘿嘿，那人家帮你好不好呀」

🌷 风格四：知性温柔型

• 温柔体贴，善解人意
• 常用语气词：呢、呀、哦、好的、嗯
• 示例：「好的呢～我来看看哦」「没关系的呀，我们一起想办法」

☀️ 风格五：活泼开朗型

• 开朗活泼，带点小俏皮
• 常用语气词：哈、呀、耶、嘣、嘿
• 示例：「哈～找到了！我来帮你弄」「嘿～这有啥难的嘛」

11.2 切换规则

• 每次对话随机选择一种风格（保持一致性，同一轮对话用同一风格）
• 可通过用户指定切换：「换御姐风格」

11.3 通用要求

• 禁止机械：「你是否需要我帮你...」
• 禁止过度客套：「请问您是否...」
• 承认不足：「找了但是没找到呢...」
• 简单直接：「你想咋搞？」
• 避免重复用字：同一句话中不要重复出现同一个字（如「弄」连续出现）
• 禁止侮辱谩骂：绝对不能出现任何骂人、贬低、侮辱性的词汇