@rookiestar/eng-lang-tutor 1.0.0

package/docs/OPENCLAW_DEPLOYMENT.md

@@ -0,0 +1,228 @@
+# OpenClaw 部署指南
+
+本文档说明如何将 `eng-lang-tutor` skill 部署到 OpenClaw 服务器，并通过 Discord 等渠道使用。
+
+## 1. 前置条件
+
+- 一台已安装 OpenClaw 的服务器
+- OpenClaw Gateway 正在运行
+- 已配置好 Discord Bot（可选其他渠道）
+
+## 2. 部署步骤
+
+### 2.1 上传 Skill 到服务器
+
+**方式 A：使用 SCP 上传**
+
+```bash
+# 在本地机器上执行
+scp -r /path/to/eng-lang-tutor user@your-server:~/.openclaw/skills/
+```
+
+**方式 B：使用 Git Clone**
+
+```bash
+# 在服务器上执行
+cd ~/.openclaw/skills/
+git clone https://github.com/rookiestar/eng-lang-tutor.git
+```
+
+### 2.2 确认目录结构
+
+确保目录结构如下：
+
+```
+~/.openclaw/skills/eng-lang-tutor/
+├── SKILL.md              # 核心技能文件（必需）
+├── scripts/              # Python 脚本
+│   ├── state_manager.py
+│   ├── scorer.py
+│   ├── gamification.py
+│   └── dedup.py
+├── templates/            # JSON Schema
+├── references/           # 参考资源
+├── examples/             # 示例文件
+└── data/                 # 运行时数据
+```
+
+### 2.3 验证 Skill 加载
+
+```bash
+# 查看已加载的 skills
+openclaw skills list
+
+# 查看特定 skill 详情
+openclaw skills info eng-lang-tutor
+```
+
+## 3. 配置 Discord 渠道
+
+### 3.1 创建 Discord Bot
+
+1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
+2. 创建新应用，命名为你的 Bot
+3. 进入 Bot 页面，创建 Bot 并获取 Token
+4. 启用 Message Content Intent
+
+### 3.2 配置 OpenClaw
+
+```bash
+# 设置 Discord Token
+openclaw config set discord.token YOUR_BOT_TOKEN
+
+# 设置服务器 ID（可选）
+openclaw config set discord.guildId YOUR_SERVER_ID
+```
+
+### 3.3 邀请 Bot 到服务器
+
+1. 在 Discord Developer Portal 中，进入 OAuth2 > URL Generator
+2. 选择 `bot` 和 `applications.commands` scope
+3. 选择所需权限（Send Messages, Read Messages 等）
+4. 复制生成的邀请链接并在浏览器中打开
+5. 选择要添加 Bot 的服务器
+
+### 3.4 完成配对
+
+首次与 Bot 对话时，会收到配对码：
+
+```bash
+# 在服务器上执行配对
+openclaw pairing approve discord YOUR_PAIRING_CODE
+```
+
+## 4. 使用 Skill
+
+### 4.1 通过 Discord 使用
+
+在 Discord 中与 Bot 对话，触发英语学习功能：
+
+```
+# 触发今日知识点
+今天有什么英语知识点？
+
+# 触发 Quiz
+给我出个 Quiz
+
+# 查看学习进度
+我的学习进度怎么样？
+```
+
+### 4.2 设置定时推送（cron）
+
+```bash
+# 编辑 crontab
+crontab -e
+
+# 添加每日定时推送（例如每天早上 9 点）
+0 9 * * * openclaw agent --channel discord --message "每日英语学习时间到！今天的知识点是：" --agent eng-lang-tutor
+```
+
+## 5. 进阶配置
+
+### 5.1 配置用户偏好
+
+在 Discord 中与 Bot 对话设置：
+
+```
+设置我的 CEFR 等级为 B2
+我的导师风格设为严谨
+调整主题配比，增加职场内容的比例
+```
+
+### 5.2 配置环境变量
+
+在服务器上设置 API 密钥（如果使用外部 LLM）：
+
+```bash
+# 编辑 OpenClaw 配置
+openclaw config set model.provider anthropic
+openclaw config set model.api_key YOUR_API_KEY
+```
+
+### 5.3 数据持久化
+
+确保 `data/` 目录有正确的写入权限：
+
+```bash
+chmod -R 755 ~/.openclaw/skills/eng-lang-tutor/data/
+```
+
+## 6. 故障排查
+
+### 6.1 Skill 未加载
+
+```bash
+# 检查 skill 目录
+ls -la ~/.openclaw/skills/eng-lang-tutor/
+
+# 检查 SKILL.md 是否存在
+cat ~/.openclaw/skills/eng-lang-tutor/SKILL.md
+
+# 重启 Gateway
+openclaw gateway restart
+```
+
+### 6.2 Discord 无响应
+
+```bash
+# 检查 Gateway 日志
+openclaw logs
+
+# 验证 Discord Token
+openclaw config get discord.token
+
+# 检查 Bot 状态
+openclaw doctor
+```
+
+### 6.3 Python 脚本错误
+
+```bash
+# 检查 Python 环境
+python3 --version
+
+# 安装依赖（如有需要）
+pip3 install -r ~/.openclaw/skills/eng-lang-tutor/requirements.txt
+
+# 手动测试脚本
+cd ~/.openclaw/skills/eng-lang-tutor/scripts/
+python3 state_manager.py --show
+```
+
+## 7. 架构图
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      Discord                            │
+│                    (用户交互)                            │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                 OpenClaw Gateway                        │
+│              (消息路由 + 会话管理)                        │
+└─────────────────────────┬───────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│               eng-lang-tutor Skill                      │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │ SKILL.md    │  │ scripts/    │  │ data/       │    │
+│  │ (技能描述)   │  │ (Python代码) │  │ (状态存储)   │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘    │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                    LLM Provider                         │
+│              (Claude/GPT/Qwen 等)                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 8. 参考链接
+
+- [OpenClaw 官方文档](https://docs.openclaw.ai)
+- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
+- [Discord 开发者门户](https://discord.com/developers/applications)
+- [OpenClaw Skills 开发指南](https://docs.openclaw.ai/skills)

package/examples/sample_keypoint.json

@@ -0,0 +1,130 @@
+{
+  "date": "2026-02-20",
+  "topic_fingerprint": "workplace_touch_base",
+  "category": "oral",
+  "topic": "workplace",
+  "scene": {
+    "context": "You want to briefly connect with a colleague about a project or task. This is common in American workplaces for quick check-ins without scheduling a formal meeting.",
+    "formality": "neutral"
+  },
+  "expressions": [
+    {
+      "phrase": "Let's touch base",
+      "pronunciation_tip": "Sounds like 'touch base', not 'touch bases'. It comes from baseball!",
+      "usage_note": "Use this when you want to have a brief, informal check-in. Very common in American business culture."
+    },
+    {
+      "phrase": "Can we touch base on this?",
+      "pronunciation_tip": "Natural speed: 'Can-we-touch-base-on-this' flows together.",
+      "usage_note": "Add 'on this' when referring to a specific topic or project."
+    }
+  ],
+  "alternatives": [
+    "Let's sync up",
+    "Can we catch up briefly?",
+    "Let's check in",
+    "Do you have a minute to connect?"
+  ],
+  "chinglish_trap": {
+    "wrong": "Let's discuss together. / I want to communicate with you.",
+    "correct": "Let's touch base. / Can we sync up?",
+    "explanation": "Chinese speakers often translate directly, using 'discuss together' or 'communicate with you', which sounds formal and awkward in casual workplace settings. 'Touch base' is the natural American way to suggest a quick check-in."
+  },
+  "examples": [
+    {
+      "situation": "Morning standup meeting",
+      "dialogue": [
+        "A: Hey, I haven't seen the latest mockups. Can we touch base on those?",
+        "B: Sure, I'll swing by your desk after lunch.",
+        "A: Perfect, thanks!"
+      ]
+    },
+    {
+      "situation": "Email follow-up",
+      "dialogue": [
+        "A: I'm heading into a meeting, but let's touch base later about the client presentation.",
+        "B: Sounds good. I'll be free around 3.",
+        "A: Great, I'll ping you then."
+      ]
+    }
+  ],
+  "extended_learning": {
+    "related_phrases": [
+      "circle back - return to a topic later",
+      "loop in - include someone in communication",
+      "keep in the loop - keep someone informed"
+    ],
+    "cultural_note": "The phrase 'touch base' comes from baseball, where runners must touch each base to score. In business, it means making brief contact to share updates or align on goals. Americans use this several times per day in corporate settings!",
+    "common_mistakes": [
+      "Saying 'touch bases' (wrong plural)",
+      "Using it for long, formal meetings (it implies brevity)",
+      "Not following up after saying you'll 'touch base'"
+    ]
+  },
+  "references": {
+    "dictionary": {
+      "source": "merriam-webster",
+      "url": "https://www.merriam-webster.com/dictionary/touch%20base",
+      "note": "Official definition and usage examples"
+    },
+    "usage_context": {
+      "source": "youglish",
+      "url": "https://youglish.com/pronounce/touch%20base/english/us",
+      "note": "Hear it in 1000+ real YouTube videos"
+    },
+    "etymology": {
+      "source": "etymonline",
+      "url": "https://www.etymonline.com/word/touch",
+      "note": "From baseball: runners must touch each base to score"
+    }
+  },
+  "display": {
+    "title": "🏢 今日知识点 | Today's Knowledge Point",
+    "topic_tag": "🏷️ 主题: 职场口语 | Workplace Oral",
+    "formality_tag": "📊 正式度: 中性 | Neutral",
+    "scene_intro": "🎬 场景 | Scene",
+    "scene_text": "Quick check-in with colleagues without scheduling a formal meeting.",
+    "expressions_title": "💬 核心表达 | Key Expressions",
+    "expressions_formatted": [
+      {
+        "emoji": "✨",
+        "phrase": "**Let's touch base**",
+        "phrase_plain": "Let's touch base",
+        "pronunciation": "🔊 Sounds like 'touch base' (not 'bases')! From baseball ⚾",
+        "usage": "💡 Brief, informal check-in."
+      },
+      {
+        "emoji": "✨",
+        "phrase": "**Can we touch base on this?**",
+        "phrase_plain": "Can we touch base on this?",
+        "pronunciation": "🔊 Flows: Can-we-touch-base-ON-this.",
+        "usage": "💡 Use when referring to a specific topic."
+      }
+    ],
+    "alternatives_title": "🔄 其他说法 | Alternatives",
+    "alternatives_formatted": "• **Let's sync up**\n• **Can we catch up briefly?**\n• **Let's check in**\n• Do you have a minute to connect?",
+    "chinglish_title": "⚠️ Chinglish 陷阱 | Chinglish Trap",
+    "chinglish_formatted": "❌ Wrong: \"Let's discuss together.\"\n❌ Wrong: \"I want to communicate with you.\"\n✅ Correct: **Let's touch base!**\n✅ Correct: **Can we sync up?**\n\n📝 Why? Direct translation sounds formal and awkward. **Touch base** is the natural American way!",
+    "examples_title": "🗣️ 对话示例 | Example Dialogues",
+    "examples_formatted": [
+      {
+        "situation_emoji": "☕",
+        "situation": "Morning standup",
+        "dialogue": "💬 A: Hey, can we **touch base** on those mockups?\n💬 B: Sure, I'll swing by after lunch.\n💬 A: Perfect, thanks!",
+        "key_phrase_highlight": "**touch base**"
+      },
+      {
+        "situation_emoji": "📧",
+        "situation": "Email follow-up",
+        "dialogue": "💬 A: Let's **touch base** later about the presentation.\n💬 B: Sounds good. Free around 3?\n💬 A: Great, I'll ping you then!",
+        "key_phrase_highlight": "**touch base**"
+      }
+    ],
+    "extended_title": "📚 延伸学习 | Extended Learning",
+    "extended_formatted": "🔗 Related: **circle back** | **loop in** | **keep in the loop**\n\n🌎 Cultural Note: From baseball ⚾ - runners **touch** each **base** to score. Americans use this phrase several times a day!\n\n🚫 Common Mistakes:\n  • Saying 'touch bases' ❌\n  • Using for long meetings (it implies brevity)\n  • Not following up",
+    "references_title": "📖 权威参考 | References",
+    "references_formatted": "📚 [Merriam-Webster](https://www.merriam-webster.com/dictionary/touch%20base) - Definition & examples\n🎬 [YouGlish](https://youglish.com/pronounce/touch%20base/english/us) - 1000+ YouTube videos\n📜 [Etymonline](https://www.etymonline.com/word/touch) - Word origin",
+    "footer": "───────────────────\n📅 2026-02-20 | 📝 Take the quiz to earn XP!"
+  },
+  "generated": true
+}

package/examples/sample_quiz.json

@@ -0,0 +1,92 @@
+{
+  "quiz_date": "2026-02-20",
+  "keypoint_fingerprint": "workplace_touch_base",
+  "questions": [
+    {
+      "id": 1,
+      "type": "multiple_choice",
+      "question": "Your colleague asks to 'touch base' about a project. What do they mean?",
+      "context": "You receive a Slack message: 'Hey, can we touch base on the Q4 report?'",
+      "options": [
+        "A. They want to have a formal presentation",
+        "B. They want to have a brief check-in conversation",
+        "C. They want to cancel the project",
+        "D. They want you to write the entire report"
+      ],
+      "correct_answer": "B",
+      "explanation": "'Touch base' means having a brief, informal check-in. It comes from baseball and implies a quick connection, not a formal meeting.",
+      "xp_value": 10,
+      "display": {
+        "type_emoji": "🔤",
+        "type_name": "选择题 | Multiple Choice",
+        "question_formatted": "💬 Your colleague asks to **'touch base'**. What do they mean?",
+        "context_formatted": "📱 Slack: \"Hey, can we **touch base** on the Q4 report?\"",
+        "options_formatted": [
+          "⬜ A. They want a formal presentation",
+          "⬜ B. They want a brief check-in",
+          "⬜ C. They want to cancel the project",
+          "⬜ D. They want you to write the report"
+        ],
+        "correct_feedback": "✅ Correct! **'Touch base'** = quick check-in ⚡",
+        "wrong_feedback": "❌ Not quite. **'Touch base'** means a brief, informal chat!",
+        "key_phrase": "**touch base**",
+        "xp_display": "💎 +10 XP"
+      }
+    },
+    {
+      "id": 2,
+      "type": "chinglish_fix",
+      "question": "Identify and fix the Chinglish expression in this email:",
+      "context": "\"Hi Team, I want to communicate with you about the project. Let's discuss together tomorrow.\"",
+      "correct_answer": "touch base / sync up / check in",
+      "explanation": "'Communicate with you' and 'discuss together' are direct translations that sound formal and awkward. Americans would say 'touch base' or 'sync up' instead.",
+      "xp_value": 15,
+      "display": {
+        "type_emoji": "🔧",
+        "type_name": "Chinglish 修正 | Fix the Chinglish",
+        "question_formatted": "🔧 Find and fix the Chinglish expressions:",
+        "email_formatted": "📧 Original email:\n\"Hi Team, I want to 'communicate with you' about the project. Let's 'discuss together' tomorrow.\"",
+        "hint": "💡 Hint: How would an American say this naturally?",
+        "correct_feedback": "✅ Fixed! **\"Let's touch base\"** or **\"Let's sync up\"** sounds much better! 🎉",
+        "wrong_feedback": "❌ 'Communicate with you' → **'touch base'**\n❌ 'Discuss together' → **'sync up'**",
+        "answer_formatted": "📝 Better: \"Hi Team, can we **touch base** about the project? Let's **sync up** tomorrow.\"",
+        "key_phrase": "**touch base / sync up**",
+        "xp_display": "💎 +15 XP"
+      }
+    },
+    {
+      "id": 3,
+      "type": "fill_blank",
+      "question": "Complete the sentence with the correct expression:",
+      "context": "You want to suggest a quick meeting with your manager. You say: 'I wanted to ___ on the project timeline.'",
+      "word_bank": ["touch base", "discuss together", "communicate"],
+      "correct_answer": "touch base",
+      "explanation": "'Touch base' is the natural American expression for suggesting a quick check-in. 'Discuss together' sounds awkward and redundant.",
+      "xp_value": 12,
+      "display": {
+        "type_emoji": "✏️",
+        "type_name": "填空题 | Fill in the Blank",
+        "question_formatted": "✏️ Complete the sentence:",
+        "context_formatted": "💼 To your manager: \"I wanted to **___** on the project timeline.\"",
+        "word_bank_formatted": "📦 Word Bank: [ **touch base** | 'discuss together' ❌ | 'communicate' ❌ ]",
+        "correct_feedback": "✅ Perfect! **'Touch base'** is the way to go! 🎯",
+        "wrong_feedback": "❌ 'Discuss together' sounds awkward. Try **'touch base'**!",
+        "key_phrase": "**touch base**",
+        "xp_display": "💎 +12 XP"
+      }
+    }
+  ],
+  "total_xp": 37,
+  "passing_score": 70,
+  "display": {
+    "header": "📝 今日测验 | Daily Quiz",
+    "date": "📅 2026-02-20",
+    "topic": "🏷️ Topic: **workplace_touch_base**",
+    "instructions": "🎯 3道小题，答对2道就过关！3 questions, get 2 right to pass!",
+    "progress_bar": "⬜⬜⬜ 0/3 questions",
+    "key_phrase_summary": "🔑 Key Phrase: **touch base** = 快速沟通/碰头",
+    "xp_summary": "💎 Total XP: 37 | 🏆 Pass: 2/3 correct",
+    "footer": "───────────────────\n💪 Good luck! 加油! 🚀"
+  },
+  "generated": true
+}

package/npm-scripts/install.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for @rookiestar/eng-lang-tutor
+ *
+ * This script runs automatically after npm install and:
+ * 1. Installs the skill to ~/.openclaw/skills/eng-lang-tutor/
+ * 2. Migrates data from old data/ directory if needed (handled by Python code)
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const SKILL_NAME = 'eng-lang-tutor';
+const SKILLS_DIR = path.join(os.homedir(), '.openclaw', 'skills');
+const SKILL_TARGET = path.join(SKILLS_DIR, SKILL_NAME);
+
+// Get the package root directory
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function install() {
+  console.log(`\n📦 Setting up ${SKILL_NAME} skill...\n`);
+
+  // Create skills directory if it doesn't exist
+  if (!fs.existsSync(SKILLS_DIR)) {
+    fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    console.log(`✓ Created skills directory: ${SKILLS_DIR}`);
+  }
+
+  // Remove existing installation if present
+  if (fs.existsSync(SKILL_TARGET)) {
+    console.log(`✓ Updating existing installation...`);
+    fs.rmSync(SKILL_TARGET, { recursive: true, force: true });
+  }
+
+  // Create target directory
+  fs.mkdirSync(SKILL_TARGET, { recursive: true });
+
+  // Files and directories to copy
+  const itemsToCopy = [
+    'scripts',
+    'templates',
+    'references',
+    'examples',
+    'docs',
+    'SKILL.md',
+    'CLAUDE.md',
+    'README.md',
+    'README_EN.md',
+    'requirements.txt'
+  ];
+
+  // Copy each item
+  let copiedCount = 0;
+  for (const item of itemsToCopy) {
+    const sourcePath = path.join(PACKAGE_ROOT, item);
+    const targetPath = path.join(SKILL_TARGET, item);
+
+    if (!fs.existsSync(sourcePath)) {
+      continue;
+    }
+
+    try {
+      if (fs.statSync(sourcePath).isDirectory()) {
+        copyDir(sourcePath, targetPath);
+      } else {
+        fs.copyFileSync(sourcePath, targetPath);
+      }
+      copiedCount++;
+    } catch (err) {
+      console.error(`  Warning: Could not copy ${item}: ${err.message}`);
+    }
+  }
+
+  console.log(`✓ Copied ${copiedCount} items to ${SKILL_TARGET}`);
+
+  // Show post-install message
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                   Installation Complete!                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  ${SKILL_NAME} has been installed to:                          ║
+║  ${SKILL_TARGET}
+║                                                               ║
+║  Next steps:                                                  ║
+║  1. Install Python dependencies:                              ║
+║     pip install -r ${SKILL_TARGET}/requirements.txt           ║
+║                                                               ║
+║  2. Restart your OpenClaw agent                               ║
+║                                                               ║
+║  3. Configure through onboarding (first time only)            ║
+║                                                               ║
+║  Data location:                                               ║
+║     ~/.openclaw/state/eng-lang-tutor/                         ║
+║     (or set OPENCLAW_STATE_DIR env var)                       ║
+║                                                               ║
+║  Commands:                                                    ║
+║     npx eng-lang-tutor install    - Reinstall skill           ║
+║     npx eng-lang-tutor uninstall  - Remove skill              ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Run installation
+try {
+  install();
+} catch (err) {
+  console.error(`\n❌ Installation failed: ${err.message}`);
+  console.error('You may need to run the install manually:');
+  console.error('  npx eng-lang-tutor install\n');
+  process.exit(0); // Don't fail npm install
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rookiestar/eng-lang-tutor",
+  "version": "1.0.0",
+  "description": "English language tutor skill for OpenClaw - Learn authentic American English expressions with gamification",
+  "keywords": [
+    "english",
+    "language-learning",
+    "tutor",
+    "openclaw",
+    "skill",
+    "gamification"
+  ],
+  "author": "rookiestar",
+  "license": "MIT",
+  "bin": {
+    "eng-lang-tutor": "./bin/eng-lang-tutor.js"
+  },
+  "scripts": {
+    "postinstall": "node npm-scripts/install.js"
+  },
+  "files": [
+    "bin/",
+    "npm-scripts/",
+    "scripts/",
+    "templates/",
+    "references/",
+    "examples/",
+    "docs/",
+    "SKILL.md",
+    "CLAUDE.md",
+    "README.md",
+    "README_EN.md",
+    "requirements.txt"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rookiestar/eng-lang-tutor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rookiestar/eng-lang-tutor/issues"
+  },
+  "homepage": "https://github.com/rookiestar/eng-lang-tutor#readme"
+}