# Beyond Words

不止单词 · 织词成文 — an Obsidian plugin.

Turn a vocabulary list into a graded English article via LLM — every target word appears naturally in context and gets highlighted, with per-paragraph translations and a phrase bank. Learn words in context, not in isolation.

[中文说明](#中文说明)

## Features

- **Word sources**: paste words directly, pick a `.txt` word list (one word per line), or a **PDF** vocabulary file from your vault (text is extracted with Obsidian's bundled PDF.js).
- **Graded generation**: pick your IELTS listening band (4.0–9.0) — the article stays comprehensible at your level with a few stretch items (Krashen's i+1).
- **Style & length control**: narrative / expository / journal, 100–800 words.
- **Translations**: optional per-paragraph translation (简体中文 / English / 日本語) shown as a subtle quote block under each paragraph.
- **Phrase bank**: the LLM extracts 5–10 useful collocations from the article into a table.
- **Local verification**: articles are checked for missing target words and retried automatically (up to 3 attempts).
- **Highlighting**: target words (including inflected forms) are highlighted with `==mark==` in the generated note — done locally, no reliance on LLM markup.
- **Mock mode**: no API key? A built-in mock generator lets you try the whole pipeline for free.

## Usage

1. Click the ribbon icon (book) or run **"生成单词文章"** from the command palette.
2. Paste words, or select a word list file from your vault.
3. Choose count, difficulty, length, style, translation language.
4. Click **生成文章**. The note is saved to the `BeyondWords/` folder and opened automatically.

## API setup

Any OpenAI-compatible endpoint works. Presets included:

| Provider | Base URL | Model |
|---|---|---|
| DeepSeek (default) | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Kimi (high-speed) | `https://api.kimi.com/coding/v1` | `kimi-for-coding-highspeed` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |

Your API key is stored only in this vault's plugin `data.json`. Without a key, the plugin falls back to the mock generator.

## Development

```bash
npm install
npm run dev    # watch mode, rebuilds main.js on change
npm run build  # type-check + production bundle
```

`main.js` is the bundled artifact — always regenerate it from `src/` with `npm run build`, never edit it by hand.

## Known limitations

- Stem matching does not recognize internal mutations (e.g. run → ran); the LLM-reported `form` field covers this in real generation.
- Scanned (image-only) PDFs yield no text — use OCR first.
- Word hover definitions, spaced-repetition write-back, and TTS are not implemented yet.

---

## 中文说明

把背诵单词列表交给 LLM，生成一篇**自然用到全部目标词**的分级英语文章，目标词自动高亮，逐段附译文，文末附高频短语表和词汇对照表。在语境中学用法，而不是孤立背单词。

- 单词来源：直接粘贴 / 库内 txt 词表 / 库内 PDF 词表（自动提取每行首个英文词）
- 难度：雅思听力 4.0–9.0（可理解输入 i+1）
- 文体：记叙文 / 说明文 / 日记；长度 100–800 词
- 译文：每段英文下给出整段译文（中/英/日可选）
- 本地校验缺词自动重试（≤3 次）；无 API key 时自动走 Mock 生成器

API Key 仅保存在本库插件目录的 `data.json` 中，不会上传。