# AI 模块代码约定 适用范围:`src/modules/assistant`、`web/modules/assistant`、`tests/assistant`,以及对应的测试辅助文件。保留服务端 CommonJS 和浏览器现有模块入口。 ## 格式与检查 使用项目固定版本的 Prettier。统一两空格缩进、单引号、分号和 LF 换行;较长表达式由工具换行。HTML 模板、SQL 和提示词中的文本内容不因排版调整而改变。 ```powershell npm run format:assistant npm run format:assistant:check ``` 这两个命令只覆盖上述 AI 模块,不批量格式化其他业务代码、第三方资源、运行输出或本地配置。编辑器可读取根目录 `.editorconfig` 和 `.prettierrc.json`。 ## 职责与命名 - 查询资源投影、角色和数据归属校验放在管理模块;模型调用与查询往返的编排独立处理。 - 使用具名常量说明查询轮数、分页和上下文预算,避免多个模块各自重复预算数字。 - 多个独立声明、权限分支、数据库操作和异常处理分行书写;函数名说明动作,变量名说明所代表的数据。 - 注释说明原因、外部接口约束或权限边界。函数已有清楚含义时,不重复逐句解释代码。 - 继续调用已有业务服务与校验器。代码整理不得另写一套规则发布、发信、归档或定时引擎。 ## 权限与状态 - 用户身份、角色、会话归属来自服务端当前账号,不接受模型声明的身份或权限。 - 只读查询返回明确投影、分页和覆盖范围;凭据和原始邮件正文不进入查询结果。 - 配置写入保持“建议、差异和风险、逐次审查授权、版本核验、保存结果”的链路。 - 保留原错误码、结果未知状态、审计先后顺序、请求去重和取消机制;不在格式整理中顺便改变这些行为。 ## 验证 纯格式调整先比对语法结构,职责拆分再运行对应行为回归;不为缩进和换行新增重复实现的测试。测试使用隔离数据和本机模型端点,不修改生产业务配置。 需要新增行为时,先添加能复现该行为的回归;仅整理代码时,复用现有权限、审批、额度、任务和协议测试验证行为一致。