forked from datawhale/whale-town-end
43874892b7
- 新增 setup-user-info.js 脚本 - 自动获取当前日期并提示输入用户名 - 生成 me.config.json 配置文件供 AI 检查步骤使用 - 简化 AI 代码检查流程的用户信息收集
AI代码检查执行指南 - Whale Town 游戏服务器
🎯 执行前准备
📋 必须收集的用户信息
在开始任何检查之前，必须收集以下信息：
- 用户当前日期：用于修改记录和时间戳更新
- 用户名称：用于@author字段处理和修改记录
🏗️ 项目特性识别
本项目是NestJS游戏服务器，具有以下特点：
- 双模式架构：支持数据库模式和内存模式
- 实时通信：基于WebSocket的实时双向通信
- 属性测试：管理员模块使用fast-check进行随机化测试
- 分层架构：Core层（技术实现）+ Business层（业务逻辑）
🔄 执行原则
🚨 中间步骤开始规范（重要）
如果AI从任何中间步骤开始执行（非步骤1开始），必须首先完成以下准备工作：
📋 强制信息收集
在执行任何中间步骤之前，AI必须：
- 收集用户当前日期：用于修改记录和时间戳更新
- 收集用户名称：用于@author字段处理和修改记录
- 确认项目特性：识别这是NestJS游戏服务器项目的特点
🔍 全局上下文获取
AI必须先了解：
- 项目架构：双模式架构（数据库+内存）、分层结构（Core+Business）
- 技术栈：NestJS、WebSocket、Jest测试、fast-check属性测试
- 文件结构：当前项目的整体文件组织方式
- 已有规范：项目中已建立的命名、注释、测试等规范
🎯 执行流程约束
中间步骤开始请求
↓
🚨 强制收集用户信息（日期、名称）
↓
🚨 强制识别项目特性和上下文
↓
🚨 强制了解目标步骤的具体要求
↓
开始执行指定步骤
⚠️ 违规处理：如果AI跳过信息收集直接执行中间步骤，用户应要求AI重新开始并完成准备工作。
⚠️ 强制要求
- 分步执行：每次只执行一个步骤，严禁跳步骤或合并执行
- 等待确认：每步完成后必须等待用户确认才能进行下一步
- 修改验证：每次修改文件后必须重新检查该步骤并提供验证报告
- 🔥 修改后必须重新执行当前步骤：如果在当前步骤中发生了任何修改行为（文件修改、重命名、移动等），AI必须立即重新执行该步骤的完整检查，不能直接进入下一步骤
- 问题修复后重检：如果当前步骤出现问题需要修改时，AI必须在解决问题后重新执行该步骤，确保没有其他遗漏的问题
- 用户信息使用：所有日期字段使用用户提供的真实日期，@author字段正确处理
🎯 执行流程
用户请求代码检查
↓
收集用户信息（日期、名称）
↓
识别项目特性
↓
执行步骤1 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤1 → 验证报告 → 等待确认
↓
执行步骤2 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤2 → 验证报告 → 等待确认
↓
执行步骤3 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤3 → 验证报告 → 等待确认
↓
执行步骤4 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤4 → 验证报告 → 等待确认
↓
执行步骤5 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤5 → 验证报告 → 等待确认
↓
执行步骤6 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤6 → 验证报告 → 等待确认
↓
执行步骤7 → 提供报告 → 等待确认
↓
[如果发生修改] → 🔥 立即重新执行步骤7 → 验证报告 → 等待确认
⚠️ 关键规则：任何步骤中发生修改行为后，必须立即重新执行该步骤！
📚 步骤执行指导
步骤1：命名规范检查
执行时读取： step1-naming-convention.md
重点关注： 文件夹结构扁平化、游戏服务器特殊文件类型
完成后： 提供检查报告，等待用户确认
步骤2：注释规范检查
执行时读取： step2-comment-standard.md
重点关注： @author字段处理、修改记录更新、时间戳规则
完成后： 提供检查报告，等待用户确认
步骤3：代码质量检查
执行时读取： step3-code-quality.md
重点关注： TODO项处理、未使用代码清理
完成后： 提供检查报告，等待用户确认
步骤4：架构分层检查
执行时读取： step4-architecture-layer.md
重点关注： Core层命名规范、依赖关系检查
完成后： 提供检查报告，等待用户确认
步骤5：测试覆盖检查
执行时读取： step5-test-coverage.md
重点关注： 严格一对一测试映射、测试文件位置、测试执行验证
完成后： 提供检查报告，等待用户确认
🧪 测试文件调试规范
调试测试文件时必须遵循以下流程：
-
读取jest.config.js配置
- 查看jest.config.js了解测试环境配置
- 确认testRegex模式和文件匹配规则
- 了解moduleNameMapper和其他配置项
-
使用package.json中的已有测试指令
- 禁止自定义jest命令：必须使用package.json中scripts定义的测试命令
- 常用测试指令：
npm run test- 运行所有测试npm run test:unit- 运行单元测试(.spec.ts文件)npm run test:integration- 运行集成测试(.integration.spec.ts文件)npm run test:e2e- 运行端到端测试(.e2e.spec.ts文件)npm run test:watch- 监视模式运行测试npm run test:cov- 运行测试并生成覆盖率报告npm run test:debug- 调试模式运行测试npm run test:isolated- 隔离运行测试
-
特定模块测试指令
- Zulip模块测试：
npm run test:zulip- 运行所有Zulip相关测试npm run test:zulip:unit- 运行Zulip单元测试npm run test:zulip:integration- 运行Zulip集成测试npm run test:zulip:e2e- 运行Zulip端到端测试npm run test:zulip:performance- 运行Zulip性能测试
- Zulip模块测试：
-
测试执行验证流程
发现测试问题 → 读取jest.config.js → 选择合适的npm run test:xxx指令 → 执行测试 → 分析结果 → 修复问题 → 重新执行测试 -
测试指令选择原则
- 单个文件测试：使用
npm run test -- 文件路径 - 特定类型测试：使用对应的test:xxx指令
- 调试测试：优先使用
npm run test:debug - CI/CD环境：使用
npm run test:isolated
- 单个文件测试：使用
步骤6：功能文档生成
执行时读取： step6-documentation.md
重点关注： API接口文档、WebSocket事件文档
完成后： 提供检查报告，等待用户确认
步骤7：代码提交
执行时读取： step7-code-commit.md
重点关注： Git变更校验、修改记录一致性检查、规范化提交流程
完成后： 提供检查报告，等待用户确认
📋 统一报告模板
每步完成后使用此模板报告：
## 步骤X：[步骤名称]检查报告
### 🔍 检查结果
[发现的问题列表]
### 🛠️ 修正方案
[具体修正建议]
### ✅ 完成状态
- 检查项1 ✓/✗
- 检查项2 ✓/✗
**请确认修正方案，确认后进行下一步骤**
🚨 全局约束
📝 文件修改记录规范（重要）
每次执行完修改后，文件顶部都需要更新修改记录和相关信息
修改类型定义
代码规范优化- 命名规范、注释规范、代码清理等功能新增- 添加新的功能或方法功能修改- 修改现有功能的实现Bug修复- 修复代码缺陷性能优化- 提升代码性能重构- 代码结构调整但功能不变
修改记录格式要求
/**
* 最近修改：
* - [用户日期]: 代码规范优化 - 清理未使用的导入 (修改者: [用户名称])
* - 2024-01-06: Bug修复 - 修复邮箱验证逻辑错误 (修改者: 李四)
* - 2024-01-05: 功能新增 - 添加用户验证码登录功能 (修改者: 王五)
*
* @author [处理后的作者名称]
* @version x.x.x
* @since [创建日期]
* @lastModified [用户日期]
*/
🔢 最近修改记录数量限制
- 最多保留5条：最近修改记录最多只保留最新的5条记录
- 超出自动删除：当添加新的修改记录时，如果超过5条，自动删除最旧的记录
- 保持时间顺序：记录按时间倒序排列，最新的在最上面
- 完整记录保留：每条记录必须包含完整的日期、修改类型、描述和修改者信息
版本号递增规则
- 修订版本+1：代码规范优化、Bug修复 (1.0.0 → 1.0.1)
- 次版本+1：功能新增、功能修改 (1.0.1 → 1.1.0)
- 主版本+1：重构、架构变更 (1.1.0 → 2.0.0)
时间更新规则
- 仅检查不修改：如果只是检查而没有实际修改文件内容，不更新@lastModified字段
- 实际修改才更新：只有真正修改了文件内容时才更新@lastModified字段和添加修改记录
- Git变更检测：通过
git status和git diff检查文件是否有实际变更，只有git显示文件被修改时才需要添加修改记录和更新时间戳
🚨 重要强调：纯检查步骤不更新修改记录
AI在执行代码检查步骤时，如果发现代码已经符合规范，无需任何修改，则：
- 禁止添加修改记录：不要添加类似"AI代码检查步骤X：XXX检查和优化"的记录
- 禁止更新时间戳：不要更新@lastModified字段
- 禁止递增版本号：不要修改@version字段
- 只有实际修改了代码内容、注释内容、结构等才需要更新修改记录
错误示例：
// ❌ 错误：仅检查无修改却添加了修改记录
/**
* 最近修改：
* - 2026-01-12: 代码规范优化 - AI代码检查步骤2：注释规范检查和优化 (修改者: moyin) // 这是错误的！
* - 2026-01-07: 功能新增 - 添加用户验证功能 (修改者: 张三)
*/
正确示例：
// ✅ 正确：检查发现符合规范，不添加修改记录
/**
* 最近修改：
* - 2026-01-07: 功能新增 - 添加用户验证功能 (修改者: 张三) // 保持原有记录不变
*/
@author字段处理规范
- 保留原则：人名必须保留，不得随意修改
- AI标识替换：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
- 判断示例：
@author kiro→ 可替换，@author 张三→ 必须保留
游戏服务器特殊要求
- WebSocket文件：Gateway文件必须有完整的连接、消息处理测试
- 双模式服务：内存服务和数据库服务都需要完整测试覆盖
- 属性测试：管理员模块使用fast-check进行属性测试
- 测试分离：严格区分单元测试、集成测试、E2E测试、性能测试
🔧 修改验证流程
🔥 修改后立即重新执行规则（重要）
任何步骤中发生修改行为后，AI必须立即重新执行该步骤，不能直接进入下一步骤！
修改行为包括但不限于：
- 文件内容修改（代码、注释、配置等）
- 文件重命名
- 文件移动
- 文件删除
- 新建文件
- 文件夹结构调整
强制执行流程：
步骤执行中 → 发现问题 → 执行修改 → 🔥 立即重新执行该步骤 → 验证无遗漏 → 用户确认 → 下一步骤
问题修复后的重检流程
当在任何步骤中发现问题并进行修改后，必须遵循以下流程：
-
执行修改操作
- 根据发现的问题进行具体修改
- 确保修改内容准确无误
- 更新文件顶部的修改记录、版本号和@lastModified字段
-
🔥 立即重新执行当前步骤
- 不能跳过这一步！
- 完整重新执行该步骤的所有检查项
- 不能只检查修改的部分，必须全面重检
-
提供验证报告
- 确认之前发现的问题已解决
- 确认没有引入新的问题
- 确认没有遗漏其他问题
-
等待用户确认
- 提供完整的验证报告
- 等待用户确认后才能进行下一步骤
验证报告模板
## 步骤X：修改验证报告
### 🔧 已执行的修改操作
- 修改类型：[文件修改/重命名/移动/删除等]
- 修改内容：[具体修改描述]
- 影响文件：[受影响的文件列表]
### 📝 已更新的修改记录
- 添加修改记录：[用户日期]: [修改类型] - [修改内容] (修改者: [用户名称])
- 更新版本号：[旧版本] → [新版本]
- 更新时间戳：@lastModified [用户日期]
### 🔍 重新执行步骤X的完整检查结果
[完整重新执行该步骤的所有检查项的结果]
### ✅ 验证状态
- 原问题已解决 ✓
- 修改记录已更新 ✓
- 无新问题引入 ✓
- 无其他遗漏问题 ✓
- 步骤X检查完全通过 ✓
**🔥 重要：本步骤已完成修改并重新验证，请确认后进行下一步骤**
重检的重要性
- 确保完整性：避免修改过程中遗漏其他问题
- 防止新问题：确保修改没有引入新的问题
- 保证质量：每个步骤都达到完整的检查标准
- 维护一致性：确保整个检查过程的严谨性
- 🔥 强制执行：修改后必须重新执行，不能跳过这个环节
⚡ 关键成功要素
- 严格按步骤执行：不跳步骤，不合并执行
- 🔥 修改后立即重新执行：任何修改行为后必须立即重新执行当前步骤，不能直接进入下一步
- 问题修复后必须重检：修改文件后必须重新执行整个步骤，确保无遗漏
- 修改记录必须更新：每次修改文件后都必须更新文件顶部的修改记录、版本号和时间戳
- 真实修改验证：通过工具验证修改效果
- 用户信息准确使用：日期和名称信息正确应用
- 项目特性适配：针对游戏服务器特点优化检查
- 完整报告提供：每步都提供详细的检查报告
开始执行前，请确认已收集用户日期和名称信息！