# Vocab Story Generator

> 将不同词典、背词软件、表格或笔记导出的英文单词、短语、搭配和短句，自适应解析并编排为篇幅合适、语境自然、格式统一的英文情境助记文章。支持 Markdown 悬停释义、段落级中译、⭐核心词标记、搭配小结、原生例句汇总、覆盖核验，以及依据历史索引或既有文章排除已使用词条后续写新章节。用于“生词助记短文”“生词表变故事”“背单词文章”“单词/短语/短句串记”“词典导出续写”“只用新增词生成后续章节”等需求。

- Skill: `yuzhihe/vocab-story-generator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yuzhihe/vocab-story-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuzhihe/vocab-story-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: yuzhihe (https://skillmd.com/u/yuzhihe)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yuzhihe/vocab-story-generator

---


# 英语生词、短语与短句情境助记生成器

将来源和格式不固定的英语学习条目转化为主题自适应、语境真实、输出结构稳定的助记文章。保留输入端的灵活性，同时严格控制成品的自然度、词义准确性、历史去重和覆盖完整性。

## 核心原则

1. 先理解数据，再提取词条；不要要求固定文件格式、列名或导出软件。
2. 区分单词、短语、完整短句和附带例句；不要把它们都当成单个单词处理。
3. 根据条目数量和认知负担决定篇幅；不要为满足固定字数而注水。
4. 优先保证语境自然和词义准确；密度只是写作指导，不是压倒质量的硬指标。
5. 对比历史记录，只用尚未使用的新条目生成后续章节；不要覆盖既有文章。
6. 在交付前核对输入、排除项、正文覆盖和历史索引，确保结果可追踪。

## 1. 灵活解析任意来源

接受当前 Agent 能够读取的结构化、半结构化或非结构化输入，例如 Excel、CSV、TSV、JSON、HTML、Markdown、纯文本、复制粘贴内容，以及不同词典或背词软件的导出文件。示例不是允许格式的穷举，不要因扩展名或列名不同而拒绝处理。

1. 先检查文件、工作表、编码、表头、重复结构和若干样例记录，再推断字段含义。
2. 根据内容识别目标条目、释义、原生例句、标签、熟练度、时间等字段；不要依赖 `word`、`definition`、`example` 等固定列名。
3. 多表、多工作表或嵌套数据应分别解析后合并，保留来源位置以便追踪。
4. 保留原始条目和原始释义，不修改源文件。把界面字段、时间、音标按钮、收藏状态等非学习内容排除在目标词表之外。
5. 格式能够可靠推断时直接继续。只有两种解释会显著改变目标词表时，才提出一个简短澄清问题或展示少量映射样例供确认。
6. 当前 Agent 无法解码专有格式时，明确说明限制，并请用户另存为可读格式或粘贴内容；不得假装已经读取成功。

将解析结果归一为内部记录：

```text
original | type(word/phrase/sentence) | definition | example | source
```

`original` 必须保留用户提供的原文。`example` 是词典附带例句时，只进入原生例句汇总，不自动作为目标短句。

## 2. 本批去重、历史去重与增量续写

### 历史来源优先级

1. 优先读取用户提供或既有输出目录中的 `00_已使用词条索引.jsonl`。
2. 索引不存在时，回溯扫描用户提供的既有助记文章：以英文正文中的悬停标注、⭐标注和明确的目标条目标记为主要证据；排除中文翻译、搭配总结和普通标题造成的重复计数。
3. 既无索引也无法访问旧文章时，只做本批内部去重，并明确说明无法验证历史使用情况。不要声称完成了历史去重。
4. 不假定固定桌面路径。换 Agent 或设备时，应使用用户提供的旧文章目录、索引文件或附件。

### 规范化与判重

为比较生成 `normalized_key`：采用 Unicode 兼容规范化，转为小写，去除首尾空白和无意义的外围标点，折叠连续空格，并统一常见引号、破折号及全半角差异；保留内部撇号、连字符和词序。不要直接词形还原，以免错误合并不同学习项。

- 同一批中 `normalized_key` 与目标义项相同：合并为一项，保留信息最完整的记录。
- 与历史记录的规范化形式和义项都相同：标记为 `history_duplicate`，不再写入新文章。
- 拼写相同但释义或用法明显不同：视为可能的新义项，不自动排除；结合原释义、例句和上下文判断，必要时列为待确认。
- 复数、时态、派生词或相似短句：不得只靠模糊匹配自动删除。只有能够确认属于历史上同一学习项时才排除。
- 无效、空白或无法识别的记录单独统计，不混入正文。

### 同词不同义复核门

同一个 `normalized_key` 同时出现在历史索引和本批输入时，生成前必须完成义项级复核，不能把新词典更长、更全的整段释义直接视为新义项。

1. 从历史正文的悬停释义和所在句提取“已实际学习的义项”，不要只读索引中的词面。
2. 从本批释义、笔记和原生例句提取“用户这次收藏的目标义项”；词典自动附加的词性变化、派生词、冷僻义和格式差异不自动构成新义。
3. 两者表达同一常用义时标为 `history_duplicate`；本批有明确、可单独造句且历史未覆盖的义项时标为 `new_sense`；证据不足时标为 `sense_pending`，不进入正文。
4. 对每个 `new_sense` 或 `sense_pending` 保存简短理由和证据，例如 `historical_meaning`、`current_meaning`、`example_or_note`、`decision`。同词新义写入索引时沿用相同词面，但义项和位置必须能够区分。

若输入释义只是把历史上的“兼容的”扩写成“可以并存的、相容的、协调的”，通常仍是同一义项；若历史只学过 `colon` 的“冒号”，本批又明确收藏解剖学“结肠”，才属于可补写的新义。

若过滤后没有新条目，停止生成文章，报告“本批没有尚未使用的新条目”，不要创建空章节。

### 续写与索引

1. 检查既有文章的数字前缀，新的主题文件从最大编号加一开始；不改写或覆盖旧章节。
2. 只有用户要求保存或交付文件时，才创建或更新输出目录中的 `00_已使用词条索引.jsonl`。
3. 每行保存一个 JSON 对象，至少包含：

```json
{"normalized_key":"play it off","original":"play it off","type":"phrase","meaning":"装作若无其事地掩饰","location":"07_主题名 / Part 1","batch":"YYYY-MM-DD"}
```

4. 先成功生成并核验文章，再把本批新条目追加到索引。失败、中止或未实际进入正文的条目不得标记为已使用。
5. 索引与旧文章冲突时，以可核查的正文和用户确认结果为准，并报告差异；不要静默删除历史记录。

## 3. 条目类型与融入方式

- **单词 `word`**：使用符合目标义项的词形自然融入叙述；必要的时态、单复数变化不算遗漏。
- **短语 `phrase`**：保持固定搭配的核心结构，优先放入动作、对话、邮件或评价中；不要拆散后分别计算。
- **完整短句 `sentence`**：优先作为人物台词、邮件、告示或情节关键句完整出现。不要为了连接上下文而擅自改变需要整体记忆的句子。
- **原生例句 `example`**：若输入明确将其作为例句字段，汇总到可选的 `00_原生例句汇总.md`，不计入目标覆盖率。

完整短句若不适合悬停链接，可将原句整体加粗，并在紧邻位置给出自然中译；不要为了套格式制造断裂的 Markdown。输入疑似有误时，先判断它是必须原样学习的目标还是普通例句，再决定保留、纠正或列为待确认。

### 疑似错误表达的教学格式

生成前把目标表达分为 `standard`、`nonstandard_but_recoverable` 和 `uncertain`。疑似错误的短语或句子不得像正常英语一样直接嵌入叙述。

- `standard`：按普通目标条目自然使用。
- `nonstandard_but_recoverable`：把用户原文完整保留在人物草稿、邮件、提问或编辑批注中，并照常为原文添加一次目标标记；在同一句或紧邻句明确说明它不自然或有误，再给出自然版本。悬停释义也应写明“原稿表达”或“错误表达”。
- `uncertain`：无法可靠判断意图、缩写展开或正确形式时列入待确认，不编造修正版，也不计入覆盖。

例如，收藏项 `Reserve a room of hotel` 应作为人物正在修改的原稿出现，并紧接 `reserve a hotel room`；`what extent` 应说明完整结构通常是 `to what extent`。验收时同时检查：原始目标得到保留、错误没有被当作推荐用法、自然版本清楚可见、中文说明没有把错误表达翻成正确表达后掩盖差异。

## 4. 自适应主题、容量与篇幅

根据语义领域和真实使用场景动态聚类，不套用固定类目。专业核心词进入相应主题，通用动词、副词和抽象词分散到最自然的情节位置。

### 写作前的主题分组验收

大批量任务必须先形成“文件 → Part → 目标条目”的唯一分配计划，再开始正文。对每个 Part 做一次语义连贯性检查：用一句话说明人物、任务和场景，并确认每个专业词都能在该场景中发挥真实作用。仅因条目都是名词、首字母相近或需要凑满容量，不足以把它们归为同组。

- 明显属于其他领域的条目先移动，例如解剖学 `colon` 不应留在数据工程场景，数字形象 `Avatar` 更适合媒体或产品场景。
- 少量通用词可以作为动作或评价自然分散；若一个 Part 需要连续转场才能容纳目标，应拆成有因果联系的微场景或重新分组。
- 分组完成后核对目标总数、唯一性、每 Part 容量和离群项。通过这一关后才开始写作，避免在结尾堆入无关词补漏。
- 标题应在分组稳定后依据实际人物、事件或核心矛盾拟定。保留数字前缀以承接系列，但中文名和英文名不必套用“甲与乙 / X and Y”的统一格式；优先使用能提示故事内容、彼此有辨识度的自然标题。重命名后同步更新正文标题、计划、覆盖记录和索引位置。

按每个 Part 的新目标条目数量规划英文正文：

| 新条目数 | 建议英文正文长度 | 结构 |
| --- | ---: | --- |
| 1–5 | 100–180 词 | 1 个微型场景 |
| 6–12 | 180–280 词 | 1 篇紧凑短文 |
| 13–20 | 280–400 词 | 1 篇标准短文 |
| 21–30 | 400–550 词 | 1 个完整 Part |

一般让一个新的单词或短语获得约 17–22 个英文正文词的上下文。完整句子的认知负担更高，应降低单 Part 容量。少量条目不强求密度；复杂专业词应增加铺垫。输入超过 30 项时，按主题拆为多个 Part；规模很大时再拆成多个主题文件。对于需要拆成多个主题文件的大批量词表，每个主题文件默认安排 3–4 个 Part，以保持成品结构稳定并与既有系列一致；只有该主题的新条目不足以自然支撑 3 个 Part 时，才允许使用 1–2 个 Part，不得为了凑数拆分、注水或重复条目。

## 5. 真实语境与语义准确性

1. 让情节符合行业、学术或生活逻辑，不为了消耗词条突然插入无关物品、疾病或动作。
2. 一个主题内部无法自然容纳所有条目时，拆分为多个微场景或新 Part，不强行缝合。
3. 释义以当前句中的具体义项为准。先读原释义和例句，再把目标词放回完整句子复核，避免套用词典第一义。
4. 悬停释义保持简洁，但取消固定“2–4 个字”的限制：普通单词通常用简短语境义；短语给出自然的整体含义；完整句子给出通顺的整句翻译。
5. 缩写、专有名词、专业术语和多义词没有足够依据时，保留不确定性或列为待确认，不得编造。

## 6. 统一输出格式

保留以下默认成品样式：

- 英文目标单词或短语：`[word](# "语境释义")`
- ⭐核心主动词汇：`[⭐ word](# "⭐ 核心应用 | 语境释义")`
- 每个英文段落后紧跟自然、通顺的中文翻译。
- 中文翻译中的对应重点可使用 `[⭐ 中文释义](# "word")`，但不要牺牲中文语序。
- 每个 Part 末尾提炼 3–5 组真正值得主动使用的搭配；少量词条时可相应减少，不为凑数添加普通表达。

```markdown
### 💡 重点搭配与实用表达 (Key Collocations & Usage)
- **核心搭配**（中文释义）
  - *应用指导*：说明自然用法、适用场景及必要的易错点。
```

输出文件沿用数字前缀和主题名，例如 `07_城市生活 (Urban Encounters).md`。若输入包含原生例句，可生成或续写 `00_原生例句汇总.md`；不要把历史例句重复追加。

## 7. 交付前质量核验

建立内部覆盖表，将每个本批新条目分配到唯一的主要 Part，并逐项检查：

- [ ] 输入记录数、有效学习条目数、本批重复数、历史重复数和新条目数能够对上。
- [ ] 每个新目标条目都在英文正文中出现；只出现在中文翻译或搭配总结中不算覆盖。
- [ ] 短语的核心结构和完整短句没有被破坏。
- [ ] 实际词形能够追溯到原始条目，未误把普通文本标为目标词。
- [ ] 每个悬停释义都与所在句的义项一致，中文翻译自然，没有逐词硬译。
- [ ] 情节过渡自然，没有为补漏而在结尾堆入无关词。
- [ ] 文件编号承接历史，旧文章未被覆盖；索引只记录已成功交付的新条目。

交付时简要报告统计，例如：

```text
输入记录：320｜有效条目：286｜本批重复：2｜历史已使用：241｜本次新增并覆盖：43/43｜待确认：0
```