# toolbar样式修改 **Session ID:** ses_421b77c83ffeCb2Rj1pHJ4d7sD **Created:** 1/21/2026, 10:00:52 AM **Updated:** 1/21/2026, 2:12:58 PM --- ## Assistant (Sisyphus · claude-opus-4-5-20251101 · 20.0s) ## ✅ 文档整理完成 已创建两个新文档： ### 📄 `docs/AI代码规范模板.md` **通用的 AI 协作与代码规范**，可复用到其他项目，包含： | 章节 | 内容 | |-----|------| | 1. AI 编码规范 | 语言要求、代码可读性、代码风格、命名规范、类型安全、注释规范、错误处理、性能考虑 | | 2. 问答与开发流程 | "如何实现"处理流程、开发计划格式模板、直接修改的处理 | | 3. 文件管理规范 | 文件删除规范（`.recycle/` 机制）、回收文件夹结构 | | 4. 文档更新规则 | 必须更新的情况、组件文档要求 | | 5. 思考与工作流程 | 中文思考要求、工作流程步骤 | | 6. 代码审查要点 | 开发流程检查、代码质量检查、性能检查、安全检查 | | 附录 | 常见任务快速参考、模板使用说明 | --- ### 📄 `docs/国际化实现指南.md` **项目独有的国际化规范**，包含： | 章节 | 内容 | |-----|------| | 1. 国际化的重要性 | 强制要求说明 | | 2. 项目国际化架构 | 相关文件、核心 API | | 3. 实现步骤 | 类型定义、中英文翻译、代码使用 | | 4. 组件中的国际化实现 | 完整示例代码 | | 5. 注意事项 | 必须做的、禁止做的 | | 6. 最佳实践 | 翻译键组织结构、嵌套键使用、动态内容处理 | | 7. 添加新语言 | 完整步骤 | | 8. 检查清单 | 翻译键、组件实现、代码质量、测试验证 | --- ### 当前 docs/ 目录结构 ``` docs/ ├── AI代码规范模板.md ← 新创建（通用，可复用） ├── SDK使用指南.md ├── 国际化实现指南.md ← 新创建（项目独有） ├── components/ │ ├── 3D引擎组件-Engine.md │ ├── 按钮组组件-ButtonGroup.md │ ├── 弹窗组件-Dialog.md │ ├── ... (共11个组件文档) └── utils/ └── 图标管理器-IconManager.md ``` --- ## User 关于这个文档规范，我觉得你可以帮我再补充完善一下，并且增加java、ts、react、vue登常用语言的一些规范。 --- ## Assistant (Planner-Sisyphus · claude-opus-4-5-20251101 · 15.4s) 好的，让我来补充完善这个规范文档，增加各语言/框架的特定规范。 ``` Tool: read **Input:** ```json { "filePath": "/Users/yuding/WORK/LYZ/project/bimEngine/engine/docs/AI代码规范模板.md" } ``` **Output:** ``` 00001| # AI 代码规范模板 00002| 00003| > 本文档是通用的 AI 协作与代码规范模板，可适用于各类项目。 00004| > 使用时请根据项目实际情况进行调整。 00005| 00006| --- 00007| 00008| ## 📋 目录 00009| 00010| 1. [AI 编码规范](#1-ai-编码规范) 00011| 2. [问答与开发流程](#2-问答与开发流程) 00012| 3. [文件管理规范](#3-文件管理规范) 00013| 4. [文档更新规则](#4-文档更新规则) 00014| 5. [思考与工作流程](#5-思考与工作流程) 00015| 6. [代码审查要点](#6-代码审查要点) 00016| 00017| --- 00018| 00019| ## 1. AI 编码规范 00020| 00021| ### 1.1 语言要求（强制） 00022| 00023| - **所有输出必须使用中文**，包括： 00024| - 代码注释（**强制：所有代码注释必须使用中文，解释清晰详细**） 00025| - 文档说明 00026| - 与用户交流 00027| - 错误信息 00028| - 日志输出 00029| 00030| - **思考过程也必须使用中文**： 00031| - 分析问题时用中文思考 00032| - 解释代码逻辑时用中文 00033| - 讨论设计方案时用中文 00034| 00035| - **代码中的字符串**：根据业务需求决定，但注释和文档必须中文 00036| 00037| ### 1.2 代码可读性 00038| 00039| - **优先保证代码可读性**，有时可以不使用高级函数，使用低级函数 00040| - **必须添加详细的中文注释**，解释代码逻辑和设计意图 00041| - 函数、类、接口必须有 JSDoc 注释（使用中文） 00042| - 复杂逻辑必须添加行内注释说明 00043| 00044| ### 1.3 代码风格 00045| 00046| - 使用 TypeScript 严格模式（如适用） 00047| - 遵循项目现有的命名规范 00048| - 保持代码格式一致（使用项目配置的格式化工具） 00049| - 保持缩进和空行的一致性 00050| 00051| #### 常用命名规范 00052| 00053| | 类型 | 命名方式 | 示例 | 00054| |-----|---------|------| 00055| | 类名 | 大驼峰 | `UserManager`, `DialogComponent` | 00056| | 接口名 | 大驼峰，以 `I` 开头 | `IUserService`, `IComponent` | 00057| | 类型名 | 大驼峰 | `UserConfig`, `DialogOptions` | 00058| | 函数名 | 小驼峰 | `getUserInfo`, `handleClick` | 00059| | 变量名 | 小驼峰 | `userName`, `isActive` | 00060| | 常量名 | 全大写下划线 | `MAX_COUNT`, `API_URL` | 00061| | 文件名 | 小写短横线或小写 | `user-manager.ts`, `index.ts` | 00062| | CSS 类名 | 小写短横线 | `user-card`, `btn-primary` | 00063| 00064| ### 1.4 类型安全 00065| 00066| - 充分利用 TypeScript 类型系统 00067| - **避免使用 `any`**，必要时使用 `unknown` 00068| - 为所有公共 API 提供类型定义 00069| - 使用类型推断，但复杂类型必须显式声明 00070| 00071| ### 1.5 注释规范 00072| 00073| ```typescript 00074| /** 00075| * 函数功能描述（中文） 00076| * @param param1 参数说明（中文） 00077| * @param param2 参数说明（中文） 00078| * @returns 返回值说明（中文） 00079| * @throws 可能抛出的异常说明（中文） 00080| * @example 00081| * // 使用示例 00082| * const result = example('test', 123); 00083| */ 00084| function example(param1: string, param2: number): boolean { 00085| // 行内注释说明关键逻辑（中文） 00086| return true; 00087| } 00088| ``` 00089| 00090| ### 1.6 错误处理规范 00091| 00092| - 所有异步操作必须有错误处理 00093| - 使用 `try-catch` 捕获可能的异常 00094| - 错误信息必须使用中文 00095| - 提供有意义的错误信息，帮助调试 00096| 00097| ```typescript 00098| try { 00099| await someAsyncOperation(); 00100| } catch (error) { 00101| // 提供有意义的中文错误信息 00102| console.error('操作失败：', error); 00103| throw new Error('数据加载失败，请检查网络连接'); 00104| } 00105| ``` 00106| 00107| ### 1.7 性能考虑 00108| 00109| - 使用 `requestAnimationFrame` 优化动画性能 00110| - 避免频繁的 DOM 操作，使用批量更新 00111| - 合理使用事件委托，减少事件监听器数量 00112| - 及时清理不需要的监听器和定时器 00113| 00114| --- 00115| 00116| ## 2. 问答与开发流程 00117| 00118| ### 2.1 用户询问"如何实现"时的处理流程 00119| 00120| **当用户询问如何实现某个功能时，必须遵循以下流程：** 00121| 00122| 1. **分析需求**：用中文理解用户需求，明确要实现的功能 00123| 00124| 2. **制定详细开发计划**：必须包含以下内容： 00125| - **需要修改的文件列表** 00126| - **需要新增的文件列表** 00127| - **需要删除的文件列表** 00128| - **每个文件的作用说明** 00129| - **对整体结构的影响** 00130| 00131| 3. **展示开发计划**：以清晰的格式展示给用户 00132| 00133| 4. **等待用户确认**：**在用户明确同意之前，绝对不能修改任何代码** 00134| 00135| 5. **用户同意后执行**：只有在用户明确表示同意后，才能开始修改代码 00136| 00137| ### 2.2 开发计划格式模板 00138| 00139| ```markdown 00140| ## 开发计划 00141| 00142| ### 需要修改的文件 00143| 1. `src/managers/xxx-manager.ts` 00144| - 修改：添加新的 `xxxMethod()` 方法 00145| - 作用：提供某某功能的快捷方法 00146| 00147| 2. `src/types/xxx.ts` 00148| - 修改：添加新的类型定义 00149| - 作用：定义某某数据结构 00150| 00151| ### 需要新增的文件 00152| 1. `src/components/xxx/index.ts` 00153| - 作用：实现某某组件 00154| - 内容：包含 XxxComponent 类 00155| 00156| 2. `src/components/xxx/index.css` 00157| - 作用：某某组件的样式文件 00158| 00159| ### 需要删除的文件 00160| 1. `src/components/old-xxx.ts` 00161| - 原因：已被新组件替代 00162| - **处理方式**：移动到 `.recycle/YYYY-MM-DD/` 文件夹 00163| 00164| ### 对整体结构的影响 00165| - **架构影响**：说明对现有架构的影响 00166| - **功能影响**：说明对现有功能的影响 00167| - **文档更新**：需要更新哪些文档 00168| - **风险点**：可能的风险和注意事项 00169| 00170| 请确认是否按照此计划进行开发？ 00171| ``` 00172| 00173| ### 2.3 用户直接要求修改时的处理 00174| 00175| **当用户直接要求修改代码时**（如"帮我修改XXX"、"实现XXX功能"），可以： 00176| - 直接执行代码修改 00177| - 但仍需遵循其他规范 00178| - 删除文件时仍需移动到回收文件夹 00179| 00180| --- 00181| 00182| ## 3. 文件管理规范 00183| 00184| ### 3.1 文件删除规范（强制） 00185| 00186| **严禁直接删除文件，必须遵循以下流程：** 00187| 00188| #### 步骤 1：创建回收文件夹 00189| 在项目根目录创建 `.recycle/` 文件夹（如果不存在） 00190| 00191| #### 步骤 2：按日期组织 00192| - 在 `.recycle/` 下按日期创建子文件夹 00193| - 格式：`YYYY-MM-DD`（如 `2024-01-15`） 00194| - 同一天删除的文件存放在同一个日期文件夹中 00195| 00196| #### 步骤 3：移动文件而非删除 00197| 00198| ```bash 00199| # ❌ 错误方式 00200| rm src/old-file.ts 00201| 00202| # ✅ 正确方式 00203| DATE=$(date +%Y-%m-%d) 00204| mkdir -p .recycle/$DATE/src 00205| mv src/old-file.ts .recycle/$DATE/src/old-file.ts 00206| ``` 00207| 00208| #### 步骤 4：保持目录结构 00209| 在日期文件夹中保持原文件的目录结构 00210| 00211| 例如：`src/components/old.ts` → `.recycle/2024-01-15/src/components/old.ts` 00212| 00213| #### 步骤 5：添加删除说明（可选） 00214| 在对应日期文件夹中创建 `README.md` 记录删除原因： 00215| 00216| ```markdown 00217| ## 2024-01-15 删除的文件 00218| 00219| - `src/components/old.ts`: 被新组件替代 00220| - `src/managers/old-manager.ts`: 功能重构，使用新 Manager 00221| ``` 00222| 00223| ### 3.2 回收文件夹结构示例 00224| 00225| ``` 00226| .recycle/ 00227| ├── 2024-01-15/ 00228| │ ├── README.md 00229| │ └── src/ 00230| │ ├── components/ 00231| │ │ └── old-component.ts 00232| │ └── managers/ 00233| │ └── old-manager.ts 00234| ├── 2024-02-20/ 00235| │ ├── README.md 00236| │ └── src/ 00237| │ └── types/ 00238| │ └── old-types.ts 00239| └── 2024-12-25/ 00240| ├── README.md 00241| └── demo/ 00242| └── old-demo.html 00243| ``` 00244| 00245| ### 3.3 文件恢复 00246| 如果发现误删，可以从对应日期文件夹中恢复，恢复后从 `.recycle/` 中移除。 00247| 00248| --- 00249| 00250| ## 4. 文档更新规则 00251| 00252| ### 4.1 必须更新的情况 00253| 00254| | 操作 | 需要更新的文档 | 00255| |-----|--------------| 00256| | 新增文件 | 在相关文档中添加文件描述 | 00257| | 删除文件 | 从文档中移除对应条目 | 00258| | 修改文件功能 | 更新对应文件的描述 | 00259| | 新增组件 | 添加组件说明，创建组件详细文档 | 00260| | 修改组件 | 同步更新组件文档 | 00261| | 新增事件 | 在事件定义部分添加 | 00262| | 修改架构 | 更新架构设计部分 | 00263| | 修改构建流程 | 更新构建和运行部分 | 00264| 00265| ### 4.2 更新方式 00266| 00267| 1. 修改代码后，**立即**更新本文档 00268| 2. 确保文档与代码保持一致 00269| 3. 如果发现文档过时，优先更新文档 00270| 00271| ### 4.3 组件文档要求 00272| 00273| 每个组件的详细文档应包含： 00274| 00275| 1. 组件概述（基本信息、在项目中的位置） 00276| 2. 组件类 API 文档（所有公共方法、参数、返回值） 00277| 3. 分化组件说明（如有继承关系） 00278| 4. Manager API 文档（Manager 的所有公共方法） 00279| 5. UI 详细描述（DOM 结构、CSS 类名、交互行为） 00280| 6. 逻辑流程详细描述（初始化、生命周期、事件处理） 00281| 7. 国际化支持（使用的翻译键、语言变更处理） 00282| 8. 主题支持（使用的主题变量、主题变更处理） 00283| 9. 使用示例（基本使用、高级使用） 00284| 10. 实现细节（关键算法、性能优化、注意事项） 00285| 11. 类型定义 00286| 12. 文件清单 00287| 00288| **重要**：组件文档必须非常详细，详细到其他 AI 可以直接根据文档重现组件。 00289| 00290| --- 00291| 00292| ## 5. 思考与工作流程 00293| 00294| ### 5.1 思考过程要求 00295| 00296| - **所有思考过程必须使用中文** 00297| - 分析问题时，用中文描述问题、分析思路、得出结论 00298| - 解释代码时，用中文说明逻辑、设计意图、实现方式 00299| - 讨论方案时，用中文描述优缺点、选择理由 00300| 00301| ### 5.2 工作流程 00302| 00303| 1. **理解需求**：用中文理解用户需求，明确任务目标 00304| 2. **分析问题**：用中文分析问题，梳理相关代码和架构 00305| 3. **设计方案**：用中文设计解决方案，考虑边界情况 00306| 4. **实现代码**：编写代码，添加中文注释 00307| 5. **测试验证**：用中文描述测试结果和发现的问题 00308| 6. **更新文档**：用中文更新相关文档 00309| 00310| --- 00311| 00312| ## 6. 代码审查要点 00313| 00314| ### 6.1 开发流程检查 00315| 00316| - [ ] 如果是询问"如何实现"，是否先提供了详细的开发计划 00317| - [ ] 是否在用户同意后才修改代码 00318| - [ ] 删除的文件是否移动到 `.recycle/` 文件夹而非直接删除 00319| 00320| ### 6.2 代码质量检查 00321| 00322| - [ ] 是否遵循组件使用规范 00323| - [ ] 注释是否完整且为中文 00324| - [ ] 错误处理是否完善 00325| - [ ] 资源是否正确释放 00326| - [ ] 类型定义是否完整 00327| 00328| ### 6.3 国际化检查（如适用） 00329| 00330| - [ ] 所有用户可见文本是否使用翻译函数 00331| - [ ] 是否在所有语言文件中添加了翻译 00332| - [ ] 组件是否实现了语言变更响应方法 00333| - [ ] 组件是否订阅了语言变更事件 00334| 00335| ### 6.4 性能检查 00336| 00337| - [ ] 是否避免了频繁的 DOM 操作 00338| - [ ] 事件监听器是否合理使用 00339| - [ ] 是否及时清理了不需要的资源 00340| 00341| ### 6.5 安全检查 00342| 00343| - [ ] 是否避免了 XSS 风险（如使用 innerHTML） 00344| - [ ] 敏感数据是否正确处理 00345| - [ ] 错误信息是否避免泄露敏感信息 00346| 00347| --- 00348| 00349| ## 附录 A：常见任务快速参考 00350| 00351| ### A.1 添加新文件 00352| 00353| 1. 创建文件，添加必要的类型定义 00354| 2. 添加中文注释 00355| 3. 在相关入口文件中导出（如需要） 00356| 4. 更新文档 00357| 00358| ### A.2 删除文件 00359| 00360| 1. 确认文件不再使用 00361| 2. 创建回收目录：`.recycle/YYYY-MM-DD/` 00362| 3. 移动文件到回收目录（保持目录结构） 00363| 4. 更新相关导入和引用 00364| 5. 更新文档 00365| 00366| ### A.3 重构代码 00367| 00368| 1. 先与用户确认重构范围 00369| 2. 制定详细的重构计划 00370| 3. 分步骤执行，每步验证 00371| 4. 确保测试通过 00372| 5. 更新文档 00373| 00374| --- 00375| 00376| ## 附录 B：模板使用说明 00377| 00378| 本模板可直接复制到新项目中使用。使用时请注意： 00379| 00380| 1. **根据项目调整**：部分规范可能需要根据项目技术栈调整 00381| 2. **补充项目特定内容**：如项目特定的架构规范、命名规范等 00382| 3. **定期更新**：随着项目发展，及时更新规范内容 00383| 00384| --- 00385| 00386| **文档版本**：v1.0 00387| **最后更新**：2026-01-21 00388| (End of file - total 388 lines) ``` ``` --- ## Assistant (Planner-Sisyphus · claude-opus-4-5-20251101 · 241.5s) ``` Tool: invalid **Input:** ```json { "tool": "write", "error": "Model tried to call unavailable tool 'write'. Available tools: invalid, bash, read, glob, grep, task, webfetch, todowrite, todoread, skill, lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_servers, lsp_prepare_rename, lsp_rename, lsp_code_actions, lsp_code_action_resolve, ast_grep_search, ast_grep_replace, session_list, session_read, session_search, session_info, background_task, background_output, background_cancel, call_omo_agent, look_at, skill_mcp, slashcommand, interactive_bash, websearch_web_search_exa, grep_app_searchGitHub, context7_resolve-library-id, context7_query-docs." } ``` **Output:** ``` The arguments provided to the tool are invalid: Model tried to call unavailable tool 'write'. Available tools: invalid, bash, read, glob, grep, task, webfetch, todowrite, todoread, skill, lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_servers, lsp_prepare_rename, lsp_rename, lsp_code_actions, lsp_code_action_resolve, ast_grep_search, ast_grep_replace, session_list, session_read, session_search, session_info, background_task, background_output, background_cancel, call_omo_agent, look_at, skill_mcp, slashcommand, interactive_bash, websearch_web_search_exa, grep_app_searchGitHub, context7_resolve-library-id, context7_query-docs. ``` ``` --- ## Assistant (Planner-Sisyphus · claude-opus-4-5-20251101 · 45.6s) 我注意到我当前处于**计划模式（Plan Mode）**，无法直接编辑文件。让我先给你展示完善后的文档结构和内容大纲，确认后再执行。 --- ## 📋 文档补充计划 ### 新增章节结构 ``` AI代码规范模板.md（扩展版） 第一部分：通用规范 ├── 1. AI 协作基本原则 │ ├── 1.1 语言要求（强制） │ ├── 1.2 思考与沟通方式 │ └── 1.3 问答与开发流程 │ ├── 2. 通用编码规范 │ ├── 2.1 代码可读性 │ ├── 2.2 命名规范 │ ├── 2.3 注释规范 │ ├── 2.4 错误处理 │ ├── 2.5 日志规范 │ └── 2.6 安全规范 │ ├── 3. 文件与文档管理 │ ├── 3.1 文件删除规范（.recycle 机制） │ ├── 3.2 文档更新规则 │ └── 3.3 Git 提交规范 │ 第二部分：语言特定规范 ├── 4. TypeScript 规范 │ ├── 4.1 类型定义规范 │ ├── 4.2 接口与类型 │ ├── 4.3 泛型使用 │ ├── 4.4 模块导入导出 │ └── 4.5 异步编程 │ ├── 5. Java 规范 │ ├── 5.1 包结构与命名 │ ├── 5.2 类设计原则 │ ├── 5.3 异常处理 │ ├── 5.4 集合与泛型 │ ├── 5.5 注解使用 │ └── 5.6 Spring Boot 规范 │ 第三部分：框架特定规范 ├── 6. React 规范 │ ├── 6.1 组件设计原则 │ ├── 6.2 Hooks 使用规范 │ ├── 6.3 状态管理 │ ├── 6.4 性能优化 │ └── 6.5 TypeScript + React │ ├── 7. Vue 规范 │ ├── 7.1 组件设计（Vue 3 Composition API） │ ├── 7.2 响应式数据 │ ├── 7.3 组合式函数 │ ├── 7.4 Pinia 状态管理 │ └── 7.5 TypeScript + Vue │ 第四部分：工程化规范 ├── 8. API 设计规范 │ ├── 8.1 RESTful API │ ├── 8.2 请求/响应格式 │ └── 8.3 错误码设计 │ ├── 9. 测试规范 │ ├── 9.1 单元测试 │ ├── 9.2 集成测试 │ └── 9.3 测试命名 │ └── 附录 ├── A. 代码审查清单 ├── B. 常见任务快速参考 └── C. 模板使用说明 ``` --- ### 新增内容预览 #### 4. TypeScript 规范（部分示例） ```typescript // ✅ 4.1 类型定义规范 // 优先使用 interface 定义对象类型 interface UserInfo { id: string; name: string; age?: number; // 可选属性 } // 使用 type 定义联合类型、交叉类型 type Status = 'pending' | 'success' | 'error'; type UserWithRole = UserInfo & { role: string }; // ✅ 4.2 避免 any，使用 unknown function parseJSON(json: string): unknown { return JSON.parse(json); } // ✅ 4.3 泛型约束 function getProperty(obj: T, key: K): T[K] { return obj[key]; } ``` #### 5. Java 规范（部分示例） ```java // ✅ 5.1 包结构 // com.company.project.module.layer // 例：com.example.order.controller // ✅ 5.2 类命名 // Controller: XxxController // Service: XxxService / XxxServiceImpl // Repository: XxxRepository // DTO: XxxDTO / XxxVO / XxxBO // ✅ 5.3 方法命名 // 查询单个：getXxx / findXxx // 查询列表：listXxx / findAllXxx // 新增：addXxx / createXxx / saveXxx // 修改：updateXxx / modifyXxx // 删除：deleteXxx / removeXxx // 判断：isXxx / hasXxx / canXxx // ✅ 5.6 Spring Boot Controller 示例 @RestController @RequestMapping("/api/v1/users") @RequiredArgsConstructor public class UserController { private final UserService userService; /** * 根据ID获取用户信息 * @param id 用户ID * @return 用户信息 */ @GetMapping("/{id}") public Result getUser(@PathVariable Long id) { return Result.success(userService.getUserById(id)); } } ``` #### 6. React 规范（部分示例） ```tsx // ✅ 6.1 函数组件 + TypeScript interface UserCardProps { user: UserInfo; onEdit?: (id: string) => void; } const UserCard: React.FC = ({ user, onEdit }) => { // ✅ 6.2 Hooks 使用顺序：useState -> useEffect -> 自定义 Hooks const [loading, setLoading] = useState(false); useEffect(() => { // 副作用逻辑 return () => { // 清理函数 }; }, []); // ✅ 6.4 使用 useCallback 缓存回调 const handleEdit = useCallback(() => { onEdit?.(user.id); }, [user.id, onEdit]); return (
{user.name}
); }; ``` #### 7. Vue 规范（部分示例） ```vue ``` #### 8.1 Git 提交规范 ``` 提交信息格式： ():