diff --git a/scripts/test-keyword-api.ts b/scripts/test-keyword-api.ts
new file mode 100644
index 0000000..431fbe8
--- /dev/null
+++ b/scripts/test-keyword-api.ts
@@ -0,0 +1,140 @@
+/**
+ * 测试关键词词云 API 端点
+ * 模拟 n8n 工作流发送的请求
+ *
+ * 运行前请确保已设置环境变量:
+ * export API_URL=http://localhost:3000
+ * export WEBHOOK_API_KEY=your_api_key
+ */
+
+const API_URL = process.env.API_URL || 'http://localhost:3000';
+const API_KEY = process.env.WEBHOOK_API_KEY || '';
+
+async function testAPI() {
+  console.log('🧪 测试关键词词云 API...\n');
+
+  // 测试 1: 获取季度列表
+  console.log('1️⃣  测试 GET /api/keyword-cloud/quarters');
+  try {
+    const response = await fetch(`${API_URL}/api/keyword-cloud/quarters`);
+    const data = await response.json();
+    console.log('✅ 成功:', data.success);
+    console.log(`   季度数量: ${data.quarters?.length || 0}`);
+    if (data.quarters?.length > 0) {
+      console.log(`   第一个季度: ${data.quarters[0].quarter} (${data.quarters[0].keywordCount} 个关键词)`);
+    }
+  } catch (error) {
+    console.log('❌ 失败:', error.message);
+  }
+  console.log();
+
+  // 测试 2: 获取关键词
+  console.log('2️⃣  测试 GET /api/keyword-cloud/keywords/2023-Q1');
+  try {
+    const response = await fetch(`${API_URL}/api/keyword-cloud/keywords/2023-Q1`);
+    const data = await response.json();
+    console.log('✅ 成功:', data.success);
+    console.log(`   关键词数量: ${data.keywords?.length || 0}`);
+    if (data.keywords?.length > 0) {
+      console.log(`   最热词汇: ${data.keywords[0].word} (${data.keywords[0].trendScore}分)`);
+    }
+  } catch (error) {
+    console.log('❌ 失败:', error.message);
+  }
+  console.log();
+
+  // 测试 3: 获取视觉规则
+  console.log('3️⃣  测试 GET /api/keyword-cloud/rules');
+  try {
+    const response = await fetch(`${API_URL}/api/keyword-cloud/rules`);
+    const data = await response.json();
+    console.log('✅ 成功:', data.success);
+    console.log(`   规则数量: ${data.rules?.length || 0}`);
+    if (data.rules?.length > 0) {
+      console.log(`   规则示例: ${data.rules[0].name} (${data.rules[0].minScore}-${data.rules[0].maxScore}分)`);
+    }
+  } catch (error) {
+    console.log('❌ 失败:', error.message);
+  }
+  console.log();
+
+  // 测试 4: 批量写入关键词（模拟 n8n 工作流）
+  console.log('4️⃣  测试 POST /api/keyword-cloud/keywords (模拟 n8n 请求)');
+
+  const testPayload = {
+    apiKey: API_KEY,
+    quarter: '2024-Q1',
+    keywords: [
+      {
+        word: 'Claude',
+        trendScore: 95,
+        description: 'Anthropic 开发的 AI 助手',
+        descriptionEn: 'AI assistant developed by Anthropic',
+        detailPoints: ['支持长上下文', '安全对齐', '多模态能力'],
+        detailPointsEn: ['Long context', 'Safety alignment', 'Multimodal'],
+        visualConfig: {
+          color: 'primary',
+          size: 'text-5xl',
+          border: 'border-4',
+          rotation: 'rotate-1',
+        },
+      },
+      {
+        word: 'Gemini',
+        trendScore: 88,
+        description: 'Google 的多模态 AI 模型',
+        descriptionEn: 'Multimodal AI model by Google',
+        detailPoints: ['原生多模态', '长上下文窗口', '推理能力'],
+        detailPointsEn: ['Native multimodal', 'Long context', 'Reasoning'],
+        visualConfig: {
+          color: 'secondary',
+          size: 'text-4xl',
+          border: 'border-4',
+          rotation: 'rotate-2',
+        },
+      },
+    ],
+  };
+
+  try {
+    const response = await fetch(`${API_URL}/api/keyword-cloud/keywords`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(testPayload),
+    });
+    const data = await response.json();
+    if (data.success) {
+      console.log('✅ 成功: 创建了', data.created, '个关键词');
+      if (data.failed > 0) {
+        console.log('⚠️  失败:', data.failed, '个');
+        data.errors?.forEach((err: any) => console.log('   -', err.word, ':', err.error));
+      }
+    } else {
+      console.log('❌ 失败:', data.error);
+    }
+  } catch (error) {
+    console.log('❌ 失败:', error.message);
+  }
+  console.log();
+
+  // 验证新创建的数据
+  console.log('5️⃣  验证新创建的数据 (2024-Q1)');
+  try {
+    const response = await fetch(`${API_URL}/api/keyword-cloud/keywords/2024-Q1`);
+    const data = await response.json();
+    console.log('✅ 成功:', data.success);
+    console.log(`   关键词数量: ${data.keywords?.length || 0}`);
+    if (data.keywords?.length > 0) {
+      console.log(`   关键词: ${data.keywords.map((k: any) => k.word).join(', ')}`);
+    }
+  } catch (error) {
+    console.log('❌ 失败:', error.message);
+  }
+  console.log();
+
+  console.log('✨ 测试完成！');
+}
+
+testAPI().catch(console.error);