npm package: @jungle666/openclaw-vocab-coach
Description: Adaptive spaced-repetition vocabulary plugin for OpenClaw — pushes IELTS/TOEFL/CET words to Feishu, Telegram, WhatsApp and more with LLM-enriched cards
Author: JungleLiu
Latest version: 0.3.0

# vocab-coach — OpenClaw Plugin

**English** | [中文](#中文)

An adaptive, proactive vocabulary tutor that pushes word cards directly into your chat — **Feishu, Telegram, WhatsApp, Discord** and more. No app to open; the words come to you.

```bash
openclaw plugins install @openclaw/vocab-coach
```

---

## Features

- **Proactive push** — Poisson-process scheduler delivers words at random times within your active window, so you can't predict (and skip) them
- **FSRS spaced repetition** — Tap 认识 / 模糊 / 忘记 to dynamically adjust each word's next review interval
- **LLM-enriched cards** — Each new word card includes an English definition, 3 example sentences (last one tied to a real current event), related words, and a memory trick — generated by your OpenClaw agent
- **Per-conversation isolation** — DMs and group chats each maintain their own vocabulary queue and progress
- **User-configurable** — `/vocab-set` lets anyone tune their own daily target, active hours, and word list
- **11 000+ words bundled** — IELTS, TOEFL, CET-4, CET-6, GRE — all offline, zero CDN dependency
- **Interactive Feishu cards** — Tap-to-rate buttons rendered natively in Feishu/Lark

---

## Card Preview

```
┌─ 📚 新单词 ──────────────────────────┐
│ resilient  /rɪˈzɪliənt/             │
│ B2 · IELTS                           │
│                                      │
│ 🇨🇳 有弹性的；能快速恢复的           │
│ 🇬🇧 Able to recover quickly from     │
│    difficulties or setbacks.         │
│                                      │
│ 例句                                  │
│ 1. She is resilient enough to bounce │
│    back from any failure.            │
│ 2. Resilient supply chains reduce    │
│    exposure to trade disruptions.    │
│ 🌐 时事 Ukraine's resilient grid     │
│    withstood another missile strike. │
│                                      │
│ 关联词 ｜ robust (强健的) · flexible │
│                                      │
│ 💡 "re-" + "sil" (spring) → springs │
│    back after being bent             │
├──────────────────────────────────────┤
│  认识 ✓  │  模糊 ~  │  忘记 ✗  │  ⭐  │
└──────────────────────────────────────┘
```

---

## Quick Install

**Requirements:** [OpenClaw](https://openclaw.ai) ≥ 2026.2.13, Node.js ≥ 18

```bash
# From npm
openclaw plugins install @openclaw/vocab-coach
openclaw plugins enable vocab-coach

# From source
git clone https://github.com/JungleLiu-LHJ/openclaw-vocab-coach
cd openclaw-vocab-coach
npm install
openclaw plugins install .
openclaw plugins enable vocab-coach
```

---

## Feishu / Lark Setup

1. Create a Feishu app → add **Bot** capability
2. **Event Subscription** → enable WebSocket mode → subscribe to:
   - `im.message.receive_v1`
   - `card.action.trigger`
3. Configure the Feishu gateway in OpenClaw: `openclaw configure`
4. Send `/vocab` to your bot to get the first word card

---

## Commands

| Command | Description |
|---------|-------------|
| `/vocab` | Push a word card right now |
| `/vocab-set target <n>` | Set daily word goal (1–50) |
| `/vocab-set hours <start> <end>` | Set active push window, e.g. `8 22` |
| `/vocab-set source <tag>` | Switch word list: `ielts` `toefl` `cet4` `cet6` `gre` |
| `/vocab-set pause` | Pause all pushes |
| `/vocab-set resume` | Resume pushes |
| `/vocab-status` | Show progress stats and current settings |

> You can also configure via natural language — OpenClaw's agent routes requests like *"set daily target to 10"* to the right command automatically.

---

## How It Works

Each word card is generated on the fly by your OpenClaw LLM agent (English definition, 3 example sentences including a current-event one, related words, memory trick). Feedback updates an FSRS state machine that schedules the next review. A Poisson-process timer ensures pushes arrive unpredictably within your active window.

---

## Project Structure

```
openclaw-vocab-coach/
├── index.ts                  Plugin entry (loaded by OpenClaw jiti runtime)
├── openclaw.plugin.json      Manifest & config schema
├── data/
│   └── ielts-vocab.json      11 287 words bundled offline
├── src/
│   ├── types.ts
│   ├── storage.ts            Per-conversation progress (JSON in stateDir)
│   ├── vocab-fs.ts           Word selector
│   ├── srs.ts                FSRS algorithm
│   ├── scheduler.ts          Poisson scheduler
│   ├── generator.ts          LLM card content
│   └── card.ts               Feishu card + plain-text builder
└── tests/                    32 unit tests
```

---

## Development

```bash
npm test          # 32 unit tests
npm run typecheck
```

---

## License

MIT © [JungleLiu](https://github.com/JungleLiu-LHJ)

---

---

# 中文

**[English](#vocab-coach--openclaw-plugin)** | 中文

一个自适应的主动词汇推送插件，直接将单词卡片推送到你的聊天窗口 —— **飞书、Telegram、WhatsApp、Discord** 等平台均支持。无需打开任何 App，单词主动找你。

```bash
openclaw plugins install @openclaw/vocab-coach
```

---

## 功能特点

- **主动推送** — 泊松过程调度器在你的活跃时间窗口内随机推送，无法预测时间点（因此无法提前跳过）
- **FSRS 间隔重复** — 点击 认识 / 模糊 / 忘记 动态调整每个单词的下次复习间隔
- **LLM 增强卡片** — 每张新单词卡片包含英文释义、3 条例句（最后一条结合当前时事）、关联词和记忆技巧，由你的 OpenClaw Agent 实时生成
- **会话级隔离** — 每个私聊和群聊拥有独立的词汇队列和学习进度
- **用户自配置** — `/vocab-set` 让每个用户/群组独立设置每日目标、推送时间和词库
- **11000+ 单词本地内置** — IELTS、TOEFL、CET-4、CET-6、GRE，全部离线打包，零 CDN 依赖
- **飞书互动卡片** — 评分按钮以飞书原生交互卡片形式渲染

---

## 快速安装

**前置条件：** [OpenClaw](https://openclaw.ai) ≥ 2026.2.13，Node.js ≥ 18

```bash
# 从 npm 安装
openclaw plugins install @openclaw/vocab-coach
openclaw plugins enable vocab-coach

# 从源码安装
git clone https://github.com/JungleLiu-LHJ/openclaw-vocab-coach
cd openclaw-vocab-coach
npm install
openclaw plugins install .
openclaw plugins enable vocab-coach
```

---

## 飞书配置

1. 创建飞书应用 → 添加**机器人**能力
2. **事件与回调** → 启用长连接模式 → 订阅以下事件：
   - `im.message.receive_v1`（接收消息）
   - `card.action.trigger`（接收按钮点击回调）
3. 在 OpenClaw 中配置飞书网关：`openclaw configure`
4. 向机器人发送 `/vocab` 即可收到第一张单词卡片

---

## 命令列表

| 命令 | 说明 |
|------|------|
| `/vocab` | 立即推送一个单词 |
| `/vocab-set target <n>` | 设置每日单词目标（1–50） |
| `/vocab-set hours <开始> <结束>` | 设置推送时间段，例如 `8 22` |
| `/vocab-set source <词库>` | 切换词库：`ielts` `toefl` `cet4` `cet6` `gre` |
| `/vocab-set pause` | 暂停推送 |
| `/vocab-set resume` | 恢复推送 |
| `/vocab-status` | 查看学习进度和当前配置 |

> 也支持自然语言配置 —— OpenClaw Agent 会自动将 *"每天推送 10 个单词"* 等请求路由到对应命令。

---

## 工作原理

```
用户发送任意消息
        │
        ▼
message_received 钩子
  ├─ 注册/更新路由（channelId + conversationId）
  ├─ 初次访问：从插件配置初始化用户设置
  ├─ 处理按钮点击：更新 FSRS 状态
  └─ 启动泊松调度器（如未运行）
                │
                ▼（活跃时间窗口内随机延迟后）
         triggerPush()
  ├─ 按 FSRS 到期时间 + 用户等级选词
  ├─ 调用 LLM 生成卡片内容
  └─ 发送互动卡片到会话
```

### FSRS 间隔重复算法

每个单词维护 `{ 稳定性, 难度, 下次复习时间, 复习次数, 遗忘次数 }`：

| 按钮 | 效果 |
|------|------|
| 认识 ✓ | 稳定性 × 2.5 |
| 模糊 ~ | 稳定性 × 1.5 |
| 忘记 ✗ | 稳定性 × 0.1（重置） |
| 完全认识 ⭐ | 永久从队列中移除 |

稳定性 ≥ 21 天的单词视为已掌握，不再出现。

### 泊松调度器

每日推送次数（`dailyTarget`）按泊松过程随机分布在活跃时间窗口内，推送时机不可预测，有效防止习惯性跳过。

---

## 本地开发

```bash
npm test          # 运行 32 个单元测试
npm run typecheck # TypeScript 类型检查
```

---

## License

MIT © [JungleLiu](https://github.com/JungleLiu-LHJ)