fix: 修正文档示例 - 统一使用 leaderboardId 和对象参数格式

Author: MikotoZero

AI-CODE-ISSUES.md

@@ -0,0 +1,195 @@
+# AI 生成代码问题分析
+
+## AI 生成的代码中的问题
+
+### ❌ 问题 1: 使用了错误的字段名 `leaderboardName`
+
+**错误代码：**
+```javascript
+await this.tapManager.submitScores([{
+  leaderboardName: this.leaderboardName,  // ❌ 错误
+  score: score,
+  extraInfo: JSON.stringify({...})
+}])
+```
+
+**正确代码：**
+```javascript
+await leaderboardManager.submitScores({
+  scores: [{
+    leaderboardId: "your_leaderboard_id",  // ✅ 正确，使用 leaderboardId
+    score: 1000
+  }]
+})
+```
+
+**或者使用 Promise 版本（不传 callback）：**
+```javascript
+const result = await leaderboardManager.submitScores({
+  scores: [{
+    leaderboardId: "your_leaderboard_id",
+    score: 1000
+  }]
+})
+```
+
+### ❌ 问题 2: 参数格式不正确
+
+**错误：** AI 直接传数组，没有包装在对象中
+
+**正确格式：**
+```javascript
+// 方式1: 使用回调
+leaderboardManager.submitScores({
+  scores: [...],      // scores 数组
+  callback: {...}     // 回调对象
+})
+
+// 方式2: 使用 Promise（不传 callback）
+const result = await leaderboardManager.submitScores({
+  scores: [...]       // scores 数组
+})
+```
+
+### ❌ 问题 3: API 参数不完整
+
+**AI 生成的代码缺少参数：**
+```javascript
+// ❌ loadCurrentPlayerLeaderboardScore 缺少参数
+const playerScore = await this.tapManager.loadCurrentPlayerLeaderboardScore(this.leaderboardName)
+
+// ✅ 正确的调用
+const result = await leaderboardManager.loadCurrentPlayerLeaderboardScore({
+  leaderboardId: "your_leaderboard_id",
+  collection: "public"  // 可选
+})
+```
+
+### ✅ 正确：使用 await
+
+**AI 使用 await 是正确的！**
+- TapTap API 支持两种模式：
+  - 传递 callback → 回调模式
+  - 不传 callback → Promise 模式（可以用 await）
+
+## 文档中的不一致
+
+### 问题：文档示例不统一
+
+**leaderboardDocs.ts 中的问题：**
+
+1. **第 348 行** - 使用了 `leaderboardName`（错误）
+   ```javascript
+   await leaderboardManager.submitScores([{
+     leaderboardName: 'daily_ranking',  // ❌ 应该是 leaderboardId
+     score: finalScore
+   }])
+   ```
+
+2. **第 557 行** - 同样的问题
+   ```javascript
+   await leaderboardManager.submitScores([{
+     leaderboardName: 'my_leaderboard',  // ❌ 应该是 leaderboardId
+     score: 1000
+   }])
+   ```
+
+3. **第 562、566 行** - 缺少参数对象包装
+   ```javascript
+   // ❌ 错误：直接传字符串
+   await leaderboardManager.loadCurrentPlayerLeaderboardScore('my_leaderboard')
+   leaderboardManager.openLeaderboard()
+
+   // ✅ 正确：应该传对象
+   await leaderboardManager.loadCurrentPlayerLeaderboardScore({
+     leaderboardId: 'my_leaderboard'
+   })
+   leaderboardManager.openLeaderboard({
+     leaderboardId: 'my_leaderboard'
+   })
+   ```
+
+## 需要修复的文档位置
+
+### 1. submitScores 示例（第 124-165 行）
+
+**当前：** 正确使用了 `leaderboardId` 和对象格式 ✅
+
+### 2. common_scenarios 中的 submitScores（第 348 行）
+
+**当前：** 使用了错误的 `leaderboardName` ❌
+
+**需要改为：**
+```javascript
+const result = await leaderboardManager.submitScores({
+  scores: [{
+    leaderboardId: 'daily_ranking',
+    score: finalScore,
+    extraInfo: JSON.stringify({
+      timestamp: Date.now(),
+      gameMode: 'classic'
+    })
+  }]
+})
+```
+
+### 3. Quick Start 示例（第 557-566 行）
+
+**当前：** 使用了错误的字段名和参数格式 ❌
+
+**需要改为：**
+```javascript
+// 1. Get manager
+const leaderboardManager = tap.getLeaderboardManager();
+
+// 2. Submit score
+await leaderboardManager.submitScores({
+  scores: [{
+    leaderboardId: 'my_leaderboard',
+    score: 1000
+  }]
+});
+
+// 3. Query current player's rank
+const playerScore = await leaderboardManager.loadCurrentPlayerLeaderboardScore({
+  leaderboardId: 'my_leaderboard'
+});
+console.log('Your rank:', playerScore.rank);
+
+// 4. Open leaderboard UI
+leaderboardManager.openLeaderboard({
+  leaderboardId: 'my_leaderboard'
+});
+```
+
+## 优化建议
+
+### 1. 统一文档示例
+
+所有示例都应该：
+- ✅ 使用 `leaderboardId`（不是 leaderboardName）
+- ✅ 使用对象参数格式 `{ leaderboardId: "...", ... }`
+- ✅ 可以使用 `await`（Promise 模式）
+- ✅ 或使用 callback（回调模式）
+- ✅ 两种模式都提供示例
+
+### 2. 添加注意事项
+
+在每个 API 文档中添加：
+```
+⚠️ IMPORTANT:
+- Use leaderboardId (not leaderboardName)
+- Wrap all parameters in an object
+- Can use await (returns Promise) or provide callback
+```
+
+### 3. 添加完整的类示例
+
+提供一个正确的 LeaderboardManager 封装类示例，作为参考实现。
+
+## 为什么 AI 会生成错误代码？
+
+1. **文档不一致** - 有些示例用 `leaderboardName`，有些用 `leaderboardId`
+2. **参数格式混乱** - 有些示例直接传字符串，有些传对象
+3. **缺少明确说明** - 没有明确强调 leaderboardId vs leaderboardName
+4. **示例过于复杂** - AI 可能混淆了不同示例的写法

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.12] - 2025-10-10
+
+### Fixed
+- 📝 **Fix documentation inconsistencies** - Corrected code examples to prevent AI confusion
+  - Fixed: Use `leaderboardId` (not `leaderboardName`) consistently
+  - Fixed: All API calls must use object parameters, not direct strings
+  - Fixed: submitScores must wrap scores in `{ scores: [...] }` object
+  - Fixed: loadCurrentPlayerLeaderboardScore takes `{ leaderboardId, collection }` object
+  - Fixed: loadPlayerCenteredScores takes `{ leaderboardId, before, after }` object
+  - Fixed: openLeaderboard takes `{ leaderboardId, collection }` object
+  - Added warning in Quick Start section about correct parameter format
+  - Prevents AI agents from generating incorrect code with wrong field names
+
 ## [1.0.11] - 2025-10-10
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikoto_zero/minigame-open-mcp",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "type": "module",
   "description": "TapTap Minigame Open API MCP Server - Documentation and Management APIs for TapTap minigame (Leaderboard, and more features coming)",
   "main": "dist/server.js",

src/data/leaderboardDocs.ts

@@ -344,14 +344,14 @@ const leaderboardManager = tap.getLeaderboardManager();
 // 1. After game ends, submit score
 async function submitGameScore(finalScore) {
   try {
-    await leaderboardManager.submitScores([{
-      leaderboardName: 'daily_ranking',
-      score: finalScore,
-      extraInfo: JSON.stringify({
-        timestamp: Date.now(),
-        gameMode: 'classic'
-      })
-    }]);
+    // Use leaderboardId (not leaderboardName!)
+    // Wrap in scores array within an object
+    await leaderboardManager.submitScores({
+      scores: [{
+        leaderboardId: 'daily_ranking',  // Use leaderboardId
+        score: finalScore
+      }]
+    });
     console.log('Score submitted!');
     return true;
   } catch (error) {
@@ -363,7 +363,11 @@ async function submitGameScore(finalScore) {
 // 2. Show player's ranking after submission
 async function showPlayerRanking() {
   try {
-    const playerScore = await leaderboardManager.loadCurrentPlayerLeaderboardScore('daily_ranking');
+    // Use object parameter with leaderboardId
+    const playerScore = await leaderboardManager.loadCurrentPlayerLeaderboardScore({
+      leaderboardId: 'daily_ranking',
+      collection: 'public'
+    });
 
     // Display ranking to player
     showMessage(\`Your rank: #\${playerScore.rank}\`);
@@ -381,7 +385,9 @@ async function showPlayerRanking() {
 // 3. Display nearby competitors
 async function showNearbyPlayers() {
   try {
-    const nearby = await leaderboardManager.loadPlayerCenteredScores('daily_ranking', {
+    // Use object parameter with leaderboardId
+    const nearby = await leaderboardManager.loadPlayerCenteredScores({
+      leaderboardId: 'daily_ranking',
       before: 3,
       after: 3
     });
@@ -395,7 +401,11 @@ async function showNearbyPlayers() {
 
 // 4. Open full leaderboard when player clicks "View All"
 function openFullLeaderboard() {
-  leaderboardManager.openLeaderboard();
+  // Use object parameter with leaderboardId
+  leaderboardManager.openLeaderboard({
+    leaderboardId: 'daily_ranking',
+    collection: 'public'
+  });
 }
 
 // Complete flow
@@ -548,22 +558,31 @@ Available methods: ${cat.apis.map(api => `\`${api.name}\``).join(', ')}
 
 ## Quick Start
 
+⚠️ **CRITICAL: Use leaderboardId (NOT leaderboardName) and wrap parameters in objects!**
+
 \`\`\`javascript
 // 1. Get LeaderboardManager instance
 const leaderboardManager = tap.getLeaderboardManager();
 
-// 2. Submit a score
-await leaderboardManager.submitScores([{
-  leaderboardName: 'my_leaderboard',
-  score: 1000
-}]);
+// 2. Submit a score (use leaderboardId and wrap in scores array)
+await leaderboardManager.submitScores({
+  scores: [{
+    leaderboardId: 'my_leaderboard',  // Use leaderboardId (not leaderboardName)
+    score: 1000
+  }]
+});
 
-// 3. Query current player's rank
-const playerScore = await leaderboardManager.loadCurrentPlayerLeaderboardScore('my_leaderboard');
+// 3. Query current player's rank (use object parameter)
+const playerScore = await leaderboardManager.loadCurrentPlayerLeaderboardScore({
+  leaderboardId: 'my_leaderboard',
+  collection: 'public'
+});
 console.log('Your rank:', playerScore.rank);
 
-// 4. Open leaderboard UI
-leaderboardManager.openLeaderboard();
+// 4. Open leaderboard UI (use object parameter)
+leaderboardManager.openLeaderboard({
+  leaderboardId: 'my_leaderboard'
+});
 \`\`\`
 `;
 }

src/server.ts

@@ -51,7 +51,7 @@ class TapTapMinigameMCPServer {
     this.server = new Server(
       {
         name: 'taptap-minigame-mcp',
-        version: '1.0.11',
+        version: '1.0.12',
       }
     );