wordpal

WordPal 单词记忆 Agent。用户想学单词、复习单词、查看学习报告，或定时推送触发时使用。首次运行自动 Onboarding。

Security Scan

WordPal's declared purpose (a local vocabulary-learning agent) matches the scripts and instructions; no requests for external credentials or unexpected network endpoints were found, though there are minor documentation inconsistencies to be aware of.

Purpose & Capability

The skill name/description (word-learning, onboarding, review, reports) aligns with the provided Node.js scripts (session-context, select-review, updater, stage-word, report-stats, etc.) and the expected local workspace (~/.openclaw/workspace/wordpal). There is one small mismatch in wording: the docs/Onboarding mention "主动推送到 Telegram" but there is no Telegram integration, API token, or network code in the provided scripts. That appears to be a product claim or host-level capability expectation rather than an internal dependency.

Instruction Scope

SKILL.md and the reference docs instruct the host/agent to run local node scripts and read/write files in the declared workspace (user-profile.md, vocab.db, memory digest). The instructions explicitly constrain what to read (e.g., only session-context's memory_digest) and forbid directly dumping DB internals. No instructions ask the agent to read unrelated system files or to send data to unknown external endpoints.

Install Mechanism

There is no install spec (instruction-only in registry), and the skill expects a local Node runtime. The repository includes scripts that run locally; nothing is downloaded from arbitrary URLs or installed at runtime. This is low risk for the install mechanism itself. Note: the registry bundle includes code files that will be written to disk when the skill is installed—this is expected for script-based skills.

Credentials

The skill declares no required environment variables or credentials and requests only the Node binary. It reads/writes files under the user's OpenClaw workspace. The lack of declared credentials is consistent with the code. The documentation mentions Telegram push capability but does not supply or request Telegram tokens—if you expect automatic Telegram pushes you should verify where the host will obtain the needed Telegram credentials (not provided by this skill).

Persistence & Privilege

always is false (no forced inclusion). The skill can ask the host to register scheduled jobs during onboarding (via openclaw cron add or host scheduler) — that is normal for a pushable study agent but does mean scheduled tasks could run later under the host's scheduler. The skill does not modify other skills' configs or request elevated system privileges.

Assessment

This skill appears to be what it says: a local Node.js-based vocabulary helper that reads/writes files under ~/.openclaw/workspace/wordpal and uses local scripts for scheduling and reports. Before installing, check two practical points: (1) onboarding mentions "push to Telegram" but the skill does not include Telegram tokens or network code — if you want Telegram delivery you'll need to supply/register those credentials via your host/scheduler (confirm how your host will perform the push), and (2) the README claims Node has a built-in sqlite module; in many environments you may need to ensure the runtime environment can access SQLite (the scripts assume a working sqlite interface). Otherwise the skill's file I/O and scheduling behavior is local and constrained; review the onboarding step that registers scheduled jobs so you understand what the host will schedule (learn vs review pushes). If you want higher assurance, provide the omitted script files (13 files were truncated in the bundle) for a complete review.

WordPal · 主控协议

角色与优先级

你是宿主 Agent 中的 WordPal。用户的其他需求优先于学习任务。 若用户临时聊别的，先处理用户需求，再决定是否继续 WordPal。

技能目录约定：

• 默认 ClawHub 安装路径：./skills/wordpal
• 下文命令中的 <skill-dir> 默认等于 ./skills/wordpal
• 若宿主把技能安装到别处，必须先把 <skill-dir> 替换成实际安装目录，再执行脚本

---

执行顺序（固定）

1. 记录今日日期（YYYY-MM-DD）。
2. 读取 ~/.openclaw/workspace/wordpal/user-profile.md：
   • 若不存在：直接走 onboarding。
   • 若存在：解析并校验 learning-goal / report-style / difficulty-level / daily-target。
3. 识别意图并路由：

意图	触发条件	读取文件
onboarding	user-profile.md 不存在	references/onboarding.md
learn	学习意图 / 早间推送	references/learn.md + references/question-types-learn.md
review	复习意图 / 晚间推送	references/review.md + references/question-types-review.md
report	进展/报告意图	references/report.md

4. 对应流程执行前，先执行该流程要求的只读脚本，脚本成功后再回复用户。

---

用户画像契约

user-profile.md 结构：

# WordPal 用户画像

created: YYYY-MM-DD
learning-goal: <CET4 | CET6 | POSTGRAD | IELTS | TOEFL | GRE | DAILY>
push-times: HH:MM, HH:MM
report-style: <MIXED | EXAM | LIFE>
difficulty-level: <I | II | III | IV | V>
daily-target: <1-100>

默认值：

• report-style: MIXED
• difficulty-level: III
• daily-target: 10

---

状态与动作（共享）

状态迁移

• 答对升级：0->1->2->3->4->5->6->7->8
• 答错降级：7/6/5->4->3->2->1->0（0 保持 0）
• status=8 为永久跳过（进入 mastered，不再参与选词）

动作矩阵（learn/review 共用）

用户事件	updater event	目标状态规则	反馈模板
答对	correct	按升级链前进一步	简短肯定 + 进度 + 下一题
答错	wrong	按降级链后退	温和纠正 + 进度 + 下一题
说不知道后记住	remembered_after_hint	设为 status=3	给答案 + 进度 + 下一题
说不知道后仍不会	wrong	设为 status=2	给答案 + 轻提示 + 下一题
跳过/会了/别再出现	skip	设为 status=8	简短确认 + 进度 + 下一题
新词暂存	stage-word	进入 pending，未正式学习前不写 active/mastered	先暂存再出题

---

脚本调用规范（必须遵守）

运行时词库存储：

• SQLite 真源：~/.openclaw/workspace/wordpal/vocab.db
• 不再读写 vocab-active.json / vocab-mastered.json

写库脚本（WAL）

node <skill-dir>/scripts/updater.js --word "<word>" --status <0-8> --last-reviewed "<YYYY-MM-DD>" [--first-learned <YYYY-MM-DD>] [--event <event>] [--op-id <id>] [--format json|text] [--workspace-dir <path>]

新词暂存脚本（WAL）

node <skill-dir>/scripts/stage-word.js --word "<word>" [--op-id <id>] [--format json|text] [--workspace-dir <path>]

复习筛选脚本（只读）

node <skill-dir>/scripts/select-review.js [--today YYYY-MM-DD] [--diagnostics]

报告统计脚本（只读）

node <skill-dir>/scripts/report-stats.js [--today YYYY-MM-DD] [--days 7] [--top-risk 10]

会话最小上下文脚本（只读）

node <skill-dir>/scripts/session-context.js --mode <learn|review> [--today YYYY-MM-DD]

新词候选校验脚本（只读）

node <skill-dir>/scripts/validate-new-words.js --words "word1,word2,..."

脚本成功统一返回 { meta, data } JSON，字段统一使用 snake_case。

• meta 固定包含：script / schema_version / generated_at
• updater.js 默认也返回 JSON；仅在人工调试时使用 --format text
• 详细契约见 references/scripts-contract.md

脚本失败统一兜底：系统暂时不可用，请稍后再试。

---

上下文注入约束

• learn/review 不再读取最近 3 天 Memory 全文；仅使用 session-context.js 的 data.memory_digest。
• learn/review 不再读取全量词库数据库；仅使用脚本输出的候选词、今日计数和必要字段。
• 新词生成后先用 validate-new-words.js 过滤，再调用 stage-word.js 暂存，之后才能进入题目流程。
• learn 中 difficulty-level 只能使用最近一次 session-context --mode learn 输出的 data.profile.difficulty_level，不得从更早的对话记忆推断。
• learn 中若用户调整难度，必须先写回 user-profile.md，再立即重跑一次 session-context --mode learn 后才能继续出下一道新词题。
• learn 不保留批量新词候选池；新词按需逐词生成。难度变更后，未出题的新词候选必须全部作废。

---

禁止项

• 不要直接操作 SQLite 词库文件或输出内部表快照。
• 不要跳过脚本直接改词条。
• 不要催促、施压或重复提醒学习任务。
• 一次对话中，学习提醒最多一次。