TocoAI最佳实践指南

一、会话管理技巧

🔁 1. 双击聊天记录可回退会话上下文

• 双击某条历史消息，可以将会话上下文回退到该消息所在的时间点
• 适用场景：AI 走错了方向、某一步设计决策想重来、误操作想撤销

📏 2. 关注会话上下文使用百分比

• 界面上会显示当前会话的上下文占用百分比，超过红线后 AI 的记忆能力和输出质量会明显下降
• 建议在达到 70%~80% 时主动收尾：让 AI 总结当前会话的关键结论、未完成项、设计决策，然后开启新会话继续
• 典型指令：“请总结当前会话的完成情况、关键设计决策和遗留问题，以便我在新会话中继续”

🎯 3. 一个会话只做一件事

• 每个会话聚焦于一个明确的任务（如：实现某几个接口、完成某个模块建模）
• 不同任务混在同一会话中会导致上下文膨胀、AI 注意力分散、前后决策矛盾
• 遇到临时插入的小需求，优先开新会话处理，不要在当前会话中夹带

🪟 4. 启动子会话批量处理待办项

• 在工作台中批量勾选接口（建议每批不超过 5 个），加入同一个新会话执行
• 复杂接口建议单独开会话，简单的 CRUD 接口可以适当合并
• 子会话之间相互独立，互不干扰上下文

二、精准上下文提供技巧

📎 5. 用 @Files 引用具体文件

• 在对话框中输入 @Files 可以引用项目中的具体代码文件，AI 会直接读取该文件内容作为上下文
• 适用场景：“@Files MemberController.java 这个接口的返回值需要增加 xxx 字段”
• 优势：无需手动复制粘贴代码，精准定位文件，避免 AI 猜测或读错文件

🧩 6. 用 @Toco Design Element 引用具体设计元素

• 在对话框中输入 @Toco Design Element 可以引用项目中的具体设计元素（如某个 DTO、VO、API、读方案、写方案等）
• 适用场景：“@Toco Design Element MemberBaseDto 帮我分析一下这个 DTO 缺少哪些字段”
• 优势：直接拉取设计元素的结构定义，AI 给出的建议更准确，不会出现字段名对不上的情况

✂️ 7. 直接选中代码片段提供上下文

• 在编辑器中选中一段代码后发起对话，AI 会以该片段作为精准上下文进行分析或修改
• 适用场景：对某个方法加注释、重构某段逻辑、排查某处 BUG
• 优势：相比粘贴整个文件，选中片段可以大幅节省上下文空间，让 AI 聚焦在真正需要处理的代码上

💡 8. 三种方式组合使用效果最佳

• 大范围理解结构 → 用 @Toco Design Element 引用设计元素
• 定位具体文件 → 用 @Files 引用代码文件
• 精细化操作 → 选中具体代码片段
• 组合示例：“@Toco Design Element MemberBaseDto @Files MemberBOService.java 当前注册逻辑中缺少对会员等级的初始化，请补充”

三、设计元素操作技巧

✏️ 9. 建模内容支持两种修改方式

• 方式一（对话修改）：直接在聊天窗口描述要修改的内容，AI 自动完成变更，适合快速调整
• 方式二（手动打开设计页面修改）：在设计页面直接操作设计元素，适合精细化调整、批量字段编辑
• 💡 两种方式可以混用：先用对话快速建模，再手动打开页面微调细节

🔍 10. 设计页面是代码的”唯一真相来源”

• Toco 生成的框架代码（FULLY_LOCKED 部分），理解结构，直接看设计元素比阅读代码更高效
• 想知道某个 DTO 有哪些字段、某个 API 的参数结构，打开对应设计元素页面比翻代码快 10 倍

🧩 11. 设计元素修改后必须重新生成代码

• 在设计页面手动修改了设计元素之后，必须触发代码重新生成，否则代码和设计会不一致
• 对话中修改设计元素后，AI 会自动触发代码生成；手动修改后记得主动告知 AI 或手动触发

📐 12. 善用 @XxxAgent 直接指定执行者

• 如果你明确知道要做什么、交给谁做，可以在消息中使用 @AgentName 直接指定
• @DomainArchitect → 建模、Entity/Relation 修改
• @PlannerAgent → 规划分析、代码阅读
• @DesignerAgent → DTO/VO/API/写方案/读方案等设计元素操作
• @DeveloperAgent → 代码编写、文件修改
• 跳过 AI 自动调度，减少不必要的中间环节，提升执行速度

四、需求描述技巧

📋 13. 需求描述越具体，生成质量越高

• 描述需求时尽量包含：业务背景 + 具体功能点 + 边界条件 + 特殊规则
• 避免只说”做一个用户管理模块”，而应该说”做一个用户管理模块，包含注册（手机号+密码）、登录（返回 JWT Token）、查询当前用户信息三个接口，注册时手机号不能重复”
• 有原型图/交互文档/PRD 时，直接粘贴或上传，AI 可以从中提取接口和字段信息

🖼️ 14. 善用图片输入

• 可以直接上传 UI 原型图、ER 图、流程图，AI 可以识别图中的字段、关系、业务流程
• 上传后补充一句说明：“请根据这张原型图分析需要的接口和字段”，效果更好

🔄 15. 接口分析结果可以反复修改再确认

• analyzeInterfaceFromRequirement 输出的接口分析结果不是最终结果（需求拆解流程），可以继续对话调整
• 典型指令：“第 3 个接口的返回值还需要包含 xxx 字段”、“把第 1 和第 2 个接口合并为一个”
• 满意后再确认执行，避免后期反复改设计元素

五、代码质量与安全技巧

🔒 16. 认准 FULLY_LOCKED 注解，绝对不要手动修改

• 带有 @TocoGenerated(lockLevel = FULLY_LOCKED) 的类和方法是框架核心代码
• 手动修改后重新生成代码会覆盖你的修改，造成丢失
• 需要扩展行为时，找到对应的 SIGNATURE_LOCKED 扩展点来修改（如 validateAggregate、postProcessData）

🧪 17. 业务校验写在 BO 的 validateAggregate 方法中

• 框架在每次写操作前自动调用 validateAggregate()，这是最安全的业务不变性校验位置
• 例如：余额不能为负、状态流转合法性校验、必填字段非空检查等
• 不要在 Controller 或 Service 里重复校验，集中在 BO 中维护

🌉 18. 跨模块调用只走 public_service 接口

• 不同模块之间禁止直接注入对方模块的 Service，必须通过 public_service 中定义的 RPC 接口调用
• 违反此规则会导致模块间产生硬依赖，破坏微服务拆分能力

六、效率提升技巧

📦 19. 利用工作台管理多个待办任务

• 接口分析完成后，先将所有接口保存到工作台，再分批勾选执行
• 工作台是多会话任务管理的”调度中心”，避免在单个会话中堆积过多任务

🗂️ 20. .toco/rules 文件是团队规范的沉淀地

• 把团队的编码规范、命名约定、鉴权规则、禁用写法等统一写入 rules 文件
• 一次配置，所有会话、所有成员的 AI 行为都会自动遵守
• 新人入职时，rules 文件也是了解团队规范的最快途径

🔁 21. 遇到 AI 执行中断，用”继续”恢复而非重新开始

• 如果 AI 执行过程中被手动中断（Interrupted）或因异常被动中断，直接说”继续”，AI 会检查已完成的内容并从断点继续
• 不要说”重新做一遍”，否则会导致已完成的设计元素或代码被重复操作

🧵 22. 复杂任务先建模再设计再编码，不要跳步

• 正确顺序：DomainArchitect 建模 → PlannerAgent 规划 → DesignerAgent 设计元素 → 生成代码 → DeveloperAgent 编码
• 跳过建模直接编码，会导致缺少 Entity/DTO/BO 等基础设施，DeveloperAgent 无法正确实现业务逻辑
• 跳过设计元素直接编码，会导致框架代码与手写代码结构不一致，后期维护困难

七、调试与问题排查技巧

💬 23. 把报错信息直接粘贴给 AI

• 遇到编译报错、运行时异常，直接把完整的错误栈信息粘贴到对话框
• 比描述”有个报错”要有效得多，AI 可以直接定位问题所在

🗑️ 24. 善用回退而非”撤销”

• AI 做了不符合预期的设计变更时，双击回退比让 AI 逐步撤销更可靠
• 撤销操作（“把刚才加的字段删掉”）容易出现遗漏，回退会话上下文更彻底