From 7cac8ad8a59b4b9c463c1706c40bc43b20dd51f4 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Mon, 19 Jan 2026 18:35:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai-reading):=20=E5=AE=8C=E5=96=84AI?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=A3=80=E6=9F=A5=E8=A7=84=E8=8C=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 范围: docs/ai-reading/ 涉及文件: - README.md - step7-code-commit.md 主要改进: - 增强执行前强制性检查要求，添加明确的检查点 - 完善Step 0的执行流程和验证机制 - 强化代码提交原则，明确提交所有Git变更的规范 - 优化文档结构，提升可读性和执行指导性 - 添加更清晰的警告信息和错误示例 --- docs/ai-reading/README.md | 143 +++++++++++++++++++++++++-- docs/ai-reading/step7-code-commit.md | 56 ++++++++++- 2 files changed, 186 insertions(+), 13 deletions(-) diff --git a/docs/ai-reading/README.md b/docs/ai-reading/README.md index a2ff2b1..0527379 100644 --- a/docs/ai-reading/README.md +++ b/docs/ai-reading/README.md @@ -1,9 +1,17 @@ # AI Code Inspection Guide - Whale Town Game Server -## 🎯 Pre-execution Setup +## ⚠️ 🚨 CRITICAL: MANDATORY PRE-EXECUTION REQUIREMENTS 🚨 ⚠️ -### 🚀 User Information Setup -**Before starting any inspection steps, run the user information script:** +**� AI MUST READ THIS SECTION FIRST - EXECUTION WITHOUT COMPLETING THESE STEPS IS STRICTLY FORBIDDEN 🔴** + +**⛔ STOP! Before executing ANY step (including Step 1), you MUST complete ALL items in this section! ⛔** + +--- + +## 🎯 Pre-execution Setup (MANDATORY - CANNOT BE SKIPPED) + +### 🚀 User Information Setup (STEP 0 - MUST EXECUTE FIRST) +**⚠️ CRITICAL: Before starting any inspection steps (including Step 1), MUST run the user information script:** ```bash # Enter AI-reading directory @@ -13,6 +21,13 @@ cd docs/ai-reading node tools/setup-user-info.js ``` +**🚨 VERIFICATION CHECKPOINT:** +- [ ] Have you executed `node tools/setup-user-info.js`? +- [ ] Does `docs/ai-reading/me.config.json` file exist? +- [ ] Have you read and confirmed the user's date and name from the config file? + +**⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔** + #### Script Functions - Automatically get current date (YYYY-MM-DD format) - Check if config file exists or date matches @@ -43,13 +58,49 @@ const userName = config.name; // e.g.: "John" const modifyRecord = `- ${userDate}: Code standard optimization - Clean unused imports (Modified by: ${userName})`; ``` -### 🏗️ Project Characteristics +### 🏗️ Project Characteristics (MUST UNDERSTAND BEFORE STEP 1) +**⚠️ AI MUST read and understand these characteristics BEFORE executing Step 1:** + This project is a **NestJS Game Server** with the following features: - **Dual-mode Architecture**: Supports both database and memory modes - **Real-time Communication**: WebSocket-based real-time bidirectional communication - **Property Testing**: Admin modules use fast-check for randomized testing - **Layered Architecture**: Core layer (technical implementation) + Business layer (business logic) +**🚨 VERIFICATION CHECKPOINT:** +- [ ] Have you read and understood the project is a NestJS Game Server? +- [ ] Have you understood the dual-mode architecture? +- [ ] Have you understood the WebSocket real-time communication feature? +- [ ] Have you understood the property testing requirements? +- [ ] Have you understood the layered architecture? + +**⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔** + +--- + +## 🚨 FINAL PRE-EXECUTION CHECKLIST (MUST COMPLETE BEFORE STEP 1) 🚨 + +**Before proceeding to Step 1, AI MUST confirm ALL of the following:** + +### ✅ Mandatory Completion Checklist: +- [ ] ✅ Executed `node tools/setup-user-info.js` script +- [ ] ✅ Confirmed `me.config.json` file exists and contains valid date and name +- [ ] ✅ Read and stored user's date from config file +- [ ] ✅ Read and stored user's name from config file +- [ ] ✅ Understood this is a NestJS Game Server project +- [ ] ✅ Understood the dual-mode architecture (database + memory) +- [ ] ✅ Understood the WebSocket real-time communication feature +- [ ] ✅ Understood the property testing requirements +- [ ] ✅ Understood the layered architecture (Core + Business) +- [ ] ✅ Read and understood the execution principles below + +### 🔴 CRITICAL RULE: +**IF ANY ITEM IN THE CHECKLIST ABOVE IS NOT COMPLETED, AI IS ABSOLUTELY FORBIDDEN FROM EXECUTING STEP 1 OR ANY OTHER STEPS!** + +**AI MUST explicitly confirm completion of ALL checklist items before proceeding to Step 1!** + +--- + ## 🔄 Execution Principles ### 🚨 Mid-step Start Requirements (Important) @@ -95,9 +146,19 @@ Start Executing Specified Step ``` User Requests Code Inspection ↓ -Collect User Info (date, name) +🚨 MANDATORY: Execute node tools/setup-user-info.js ↓ -Identify Project Characteristics +🚨 MANDATORY: Verify me.config.json exists + ↓ +🚨 MANDATORY: Read and Store User Info (date, name) + ↓ +🚨 MANDATORY: Understand Project Characteristics + ↓ +🚨 MANDATORY: Complete Pre-execution Checklist + ↓ +🚨 MANDATORY: Explicitly Confirm ALL Checklist Items Completed + ↓ +⛔ CHECKPOINT: Cannot proceed without completing above steps ⛔ ↓ Execute Step 1 → Provide Report → Wait for Confirmation ↓ @@ -132,7 +193,18 @@ Execute Step 7 → Provide Report → Wait for Confirmation ## 📚 Step Execution Guide +**🚨 REMINDER: Before executing Step 1, ensure you have completed ALL items in the "FINAL PRE-EXECUTION CHECKLIST" above! 🚨** + ### Step 1: Naming Convention Check +**⚠️ BEFORE STARTING STEP 1, AI MUST:** +1. ✅ Confirm `node tools/setup-user-info.js` has been executed +2. ✅ Confirm user date and name have been read from `me.config.json` +3. ✅ Confirm project characteristics have been understood +4. ✅ Explicitly state: "Pre-execution checklist completed, now starting Step 1" + +**ONLY AFTER EXPLICIT CONFIRMATION CAN STEP 1 BEGIN!** + +--- **Read when executing:** `step1-naming-convention.md` **Focus on:** Folder structure flattening, game server special file types **After completion:** Provide inspection report, wait for user confirmation @@ -203,8 +275,9 @@ Execute Step 7 → Provide Report → Wait for Confirmation ### Step 7: Code Commit **Read when executing:** `step7-code-commit.md` -**Focus on:** Git change verification, modification record consistency check, standardized commit process -**After completion:** Provide inspection report, wait for user confirmation +**Focus on:** Git change detection, branch management, commit message standards, merge document generation +**🚨 Important Principle:** Regardless of when or what type of changes were made, if Git detects changes, provide commit service +**After completion:** Provide commit report, generate merge document ## 📋 Unified Report Template @@ -394,4 +467,56 @@ When issues are discovered and modifications made in any step, must follow this --- -**Before starting execution, please first run `node tools/setup-user-info.js` to set user information!** \ No newline at end of file +## 🔴 FINAL WARNING 🔴 + +**⚠️ AI EXECUTION REQUIREMENTS SUMMARY:** + +1. **STEP 0 (MANDATORY)**: Execute `node tools/setup-user-info.js` +2. **STEP 0.1 (MANDATORY)**: Verify `me.config.json` exists and read user info +3. **STEP 0.2 (MANDATORY)**: Understand project characteristics +4. **STEP 0.3 (MANDATORY)**: Complete and explicitly confirm pre-execution checklist +5. **ONLY THEN**: Begin Step 1 + +**🚨 VIOLATION CONSEQUENCES:** +- If AI skips Step 0 and directly executes Step 1, user MUST stop AI and require restart +- If AI does not explicitly confirm checklist completion, user MUST stop AI and require confirmation +- If AI does not read user info from config file, all subsequent steps are INVALID + +**✅ CORRECT EXECUTION START:** +``` +AI: "I will now begin the code inspection process. + +Step 0 - Pre-execution Setup: +1. ✅ Executing user information setup script... + Command: cd docs/ai-reading && node tools/setup-user-info.js + +2. ✅ Verifying me.config.json exists... + File found: docs/ai-reading/me.config.json + +3. ✅ Reading user information... + User Date: 2026-01-19 + User Name: [Name from config] + +4. ✅ Understanding project characteristics... + - NestJS Game Server ✓ + - Dual-mode Architecture ✓ + - WebSocket Communication ✓ + - Property Testing ✓ + - Layered Architecture ✓ + +5. ✅ Pre-execution checklist completed! + +All mandatory pre-execution requirements have been satisfied. +Now proceeding to Step 1: Naming Convention Check..." +``` + +**⛔ INCORRECT EXECUTION START (FORBIDDEN):** +``` +AI: "I will start with Step 1: Naming Convention Check..." ❌ WRONG! +AI: "Let me check the naming conventions..." ❌ WRONG! +AI: "Starting code inspection..." ❌ WRONG! +``` + +--- + +**🎯 Remember: Step 0 is NOT optional - it is MANDATORY before ANY other step!** \ No newline at end of file diff --git a/docs/ai-reading/step7-code-commit.md b/docs/ai-reading/step7-code-commit.md index 7bd0e75..d0ab8eb 100644 --- a/docs/ai-reading/step7-code-commit.md +++ b/docs/ai-reading/step7-code-commit.md @@ -19,10 +19,36 @@ ## 🎯 检查目标 完成代码修改后的规范化提交流程，确保代码变更记录清晰、分支管理规范、提交信息符合项目标准。 +## 🚨 重要原则：提交所有变更 + +### 核心原则 +**无论变更是何时产生的、是什么类型的，只要 Git 检测到有变更，就应该帮助用户提交！** + +### 常见误区 +❌ **错误想法**："这些变更不是本次代码检查产生的，所以不需要提交" +✅ **正确做法**：检查所有 Git 变更，分析变更类型，询问用户要提交哪些文件，然后用合适的方式提交 + +### 执行流程 +1. **检查 Git 状态**：`git status` 查看所有变更文件 +2. **分析变更内容**：`git diff` 查看每个文件的具体变更 +3. **分类变更类型**：判断是功能新增、Bug修复、代码优化等 +4. **询问用户意图**：确认要提交哪些文件、提交到哪个仓库 +5. **选择提交策略**：根据变更类型选择合适的分支命名和提交信息 +6. **执行提交操作**：创建分支、暂存文件、提交、推送 + +### 变更来源不重要 +变更可能来自： +- 本次代码检查的修改 ✓ +- 之前的功能开发 ✓ +- 其他时间的代码调整 ✓ +- 任何其他修改 ✓ + +**关键是：只要有变更，就应该提供提交服务！** + ## 📋 执行前置条件 -- 已完成前6个步骤的代码检查和修改 -- 所有修改的文件已更新修改记录和版本信息 -- 代码能够正常运行且通过测试 +- Git 工作区有变更文件（通过 `git status` 检测） +- 代码能够正常运行且通过测试（如适用） +- 用户明确要提交这些变更 ## 🚨 协作规范和范围控制 @@ -69,8 +95,30 @@ git diff git diff --cached ``` +### 🚨 重要：不要预判变更来源 +**AI 必须检查所有 Git 变更，不要因为变更不是"本次检查产生的"就忽略！** + +#### 错误示例 +``` +❌ AI: "检测到 chat.gateway.ts 有变更，但这是功能新增，不是代码规范检查产生的，所以不需要提交。" +``` + +#### 正确示例 +``` +✅ AI: "检测到以下文件有变更： +1. chat.gateway.ts - 功能新增（添加地图切换功能） +2. auth/login.service.ts - 代码优化 +3. chat/chat.service.ts - Bug修复 + +请问您要提交哪些文件？我可以帮您： +- 全部提交（可以分类提交不同类型的变更） +- 只提交部分文件 +- 按模块分别提交" +``` + ### 2. 文件修改记录校验 -**重要**：检查每个修改文件的头部信息是否与实际修改内容一致 +**注意**：如果变更不是本次代码检查产生的，文件头部可能没有更新修改记录，这是正常的。 +只需要检查变更内容，生成准确的提交信息即可。 #### 校验内容包括： - **修改记录**：最新的修改记录是否准确描述了本次变更