# Cantonese Vocab Story Generator

> 将不同来源和格式的粤语或中文词语、短语及短句，自适应编排为自然、现代的香港口语助记文章与词汇表。支持繁体中文、粤拼标注、困难条目的补充情境例句、覆盖核验，以及依据历史索引或既有文章排除已使用条目后，从下一 Part 续写新章节。用于“粤语/粵語生词助记文档”“Wordshk 助记故事”“广东话/廣東話串联记忆”“香港口语情境故事”“粤语短句助记”“只用新增词续写”等需求。

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

---


# 粤语词语、短语与短句串联记忆生成器

将任意规模、领域和来源的粤语学习条目转化为主题自适应、情节自然、排版稳定的香港口语学习文档。保留现有“串联故事＋词汇表”效果，同时加强短句处理、增量去重、自然度和香港口语质量。

## 核心原则

1. 根据实际输入灵活识别词语、短语、完整句子、释义和例句，不要求固定列名或格式。
2. 先排除本批重复和历史已用条目，只为新条目续写；不覆盖既有 Part。
3. 优先使用自然、现代、适度的香港口语，不以堆砌语气词代替真实粤语句法。
4. 保持内容安全、尊重他人且整体有建设性；允许负面词进入必要、真实而克制的语境。
5. 保证每个新条目在整份学习文档中得到有效覆盖，但不强迫所有条目进入同一条主故事线。

## 1. 输入解析与条目分类

接受当前 Agent 能读取的表格、数据库导出、JSON、HTML、Markdown、纯文本、复制粘贴内容及其他结构化或半结构化材料。示例不是格式白名单。

1. 先检查文件结构、工作表、编码、表头、重复模式和样例记录，再推断目标词、粤拼、释义、例句、标签等字段。
2. 不依赖固定列名，不因导出软件变化而拒绝处理；格式可可靠推断时直接继续。
3. 保留原始条目、原始粤拼和原始释义，不修改源文件。界面字段、时间和收藏状态等不得误识别为生词。
4. 两种解析方式会显著改变目标词表时，才提出一个简短澄清问题或展示少量映射样例。
5. 当前 Agent 无法解码专有格式时，说明限制并请用户转换为可读格式；不得猜测文件内容。

将目标条目标记为：

- `word`：单个词语或固定词形；
- `phrase`：成语、惯用语、固定搭配或较短表达；
- `sentence`：需要整体记忆的完整句子；
- `example`：词典附带例句，不自动算作目标短句。

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

### 历史来源

1. 优先读取用户提供或既有输出目录中的 `00_已使用詞條索引.jsonl`；同时兼容此前使用简体文件名保存的同类索引。
2. 索引不存在时，扫描用户提供的既有学习文档；以故事、补充情境例句和词汇表中明确加粗并带粤拼的目标项为依据，合并同一 Part 内的重复出现。
3. 既无索引也无法访问旧文章时，只做本批内部去重，并明确说明无法确认历史使用情况。
4. 不假定固定桌面路径。换 Agent 或设备时，应使用用户提供的旧文章目录、索引或附件。

### 规范化与判重

为比较生成 `normalized_key`：采用 Unicode 兼容规范化，去除首尾空白和无意义的外围标点，折叠空格，并统一常见全半角标点及明确等价的字形差异；保留原始繁简形式、内部标点和词序以便追踪。无法确认是否等价的异体字、近义表达或相似句子，不得自动合并。

- 规范化形式和目标义项相同：自动视为重复。
- 字面相同但释义、读音或用法明显不同：视为可能的新义项，不直接排除。
- 完整句子只做可靠的格式级去重；不要用宽松的语义相似度自动删除。
- 同一词和包含它的较长短语是不同学习项，除非输入明确表示二者重复。

过滤后没有新条目时，报告“本批没有尚未使用的新条目”，不要创建空 Part。

### 续写和索引

1. 读取既有文件中的最大 `Part X`，新文档从 `Part X+1` 开始；没有历史文档时从 Part 1 开始。
2. 不改写、重编号或覆盖旧 Part。
3. 只有用户要求保存或交付文件时，才创建或更新 `00_已使用詞條索引.jsonl`。
4. 每行至少包含：

```json
{"normalized_key":"講多無謂","original":"講多無謂","type":"phrase","meaning":"多說沒有意義，應直接行動","location":"Part 15 / 單元一","batch":"YYYY-MM-DD"}
```

5. 先成功生成并核验新 Part，再将实际覆盖的新条目追加到索引。失败、遗漏或未交付的条目不得标记为已使用。
6. 索引与旧文章冲突时，以可核查的正文和用户确认结果为准，并报告差异。

## 3. 自适应分篇与容量

根据新条目数量、语义领域和认知复杂度划分 Part 与单元，不固定套用主题。

- 每个单元通常承载 15–30 个词语或短语。
- 完整句子、抽象术语或复杂俗语较多时，将单元容量降至约 10–20 项。
- 新条目不超过 30 项时，生成 1 个 Part，包含 1–2 个自然单元。
- 30–100 项时，生成 1 个或多个连续 Part，每个 Part 通常包含 2–4 个单元。
- 超过 100 项时，按每个 Part 约 60–100 项动态拆分，并继续历史编号。

通用动词、语气词和抽象表达应分配到最自然的单元。语义跨度太大时拆成多个微场景，不要用突然转题的句子强行串联。

## 4. 词语、短语和完整短句的写法

- **词语和短语**：首次出现时使用 `**生词 (jyutping)**`，保持固定搭配完整。
- **完整句子**：优先作为人物对白、讯息、告示或情节关键句原样出现。正文可将整句加粗；完整粤拼放在紧邻位置或词汇表中，避免一长串行内粤拼割裂阅读。
- **附带例句**：只在它本身被指定为学习目标时才纳入目标覆盖，否则作为理解参考。
- **疑似错误句子**：判断用户是否需要原样记忆。未经确认不要擅自改写必须保留的原句；可将问题列为待确认。

同一个完整句子不得拆成若干普通词后重复计算。为了适应语法而做的极小变化必须保留与原条目的可追踪关系。

## 5. 自然、现代的香港口语

故事叙述和对白应像现代香港日常交流，而不是普通话句法替换少量粤语词。

1. 根据人物关系和场景选择语域：家庭、朋友、职场、服务行业和正式机构的说法应有差别。
2. 自然使用粤语语序、体貌标记、语气和常用连接方式；不要机械堆入 `喺`、`咗`、`嘅` 等字来伪装口语。
3. 避免不必要的普通话表达和生硬书面句式，例如在纯口语叙述中机械使用“每天”“给人看见”“在那里”等；应整句重写，而非逐字替换。
4. 法律、商业、医学和学术术语可保留正式书面词，但周围句法应符合香港粤语。
5. 故事正文、标题和词汇表统一使用规范繁体字。词汇表可用清楚的繁体书面中文解释，不必强行口语化。
6. 不刻意加入老派、极小众或粗俗黑话，除非它本身就是目标条目。

完成初稿后进行一次口语回读：检查香港人是否可能在该场景中这样叙述或说话，并修复普通话语序、书面腔、角色语域不一致和不自然的语气词。

## 6. 安全而不机械的故事边界

让内容保持安全、尊重他人，整体基调健康或有建设性。不得美化伤害、违法行为或剥削，不制造低俗猎奇情节，也不把受害者当作笑料。

负面、冲突、违法或敏感目标词可以在真实且必要的语境中出现，例如生活矛盾、新闻讨论、风险提醒、历史叙述、影视情节、法律教育或社会工作；应准确呈现词义和后果。不要把所有敏感词机械塞进法治讲座、公益纪录片或剧组排练，也不要为了“正面化”而改变词义。

## 7. 自然性与完整覆盖

“完整覆盖”指每个本批新条目都在学习文档中获得可理解的语境和词汇表解释，不要求全部进入同一篇主故事。

按以下顺序安置条目：

1. 能自然推动情节的，进入主故事。
2. 与主题相关但不适合主线的，进入同单元的简短补充对话。
3. 仍无法自然衔接的，进入 `### 📝 补充情境例句`，为每项写一个真实、完整的粤语语境。
4. 所有条目都进入对应单元的词汇表，并与故事、对话或补充例句一一对应。

不要为了补漏而在故事末尾突然串入无关的疾病、物件、动作或抽象概念。必要时增加微场景或新单元。

## 8. 统一输出格式

```markdown
# 粵語生詞串聯記憶學習文檔 (Part X)

本學習文檔使用本批尚未在歷史文章中覆蓋的新條目，以自然、現代的香港口語編寫。

---

## 單元一：[自適應主題名稱]

### 📖 串聯故事

[自然香港口語故事；詞語和短語首次出現時標為 **生詞 (jyutping)**]

### 📝 補充情境例句

- [僅在有難以自然融入主線的條目時使用；沒有則省略本節]

### 📚 詞彙表

- **生詞 (jyutping)**：準確釋義、常見語境或必要的近義辨析。
```

保留现有的 Part、单元、串联故事和词汇表结构。`补充情境例句` 是解决少数困难条目的后备区，不要把大部分词都移到这里。

## 9. 交付前质量核验

- [ ] 输入记录数、有效条目数、本批重复数、历史重复数和新条目数能够对上。
- [ ] 每个新条目都出现在故事、补充对话或补充情境例句之一，并在词汇表中有对应解释。
- [ ] 词语、短语和完整句子的覆盖没有重复计算，原始条目可以追溯。
- [ ] 故事为自然香港口语，无明显普通话句法、简体字或不必要的书面腔。
- [ ] 负面或敏感词的含义准确，语境克制，没有机械套用固定宣传场景。
- [ ] 没有为补漏而突兀转题；困难条目已合理分流。
- [ ] 新 Part 编号承接历史，旧文章未被覆盖；索引只记录成功交付的新条目。

交付时简要报告：

```text
输入记录：180｜有效条目：162｜本批重复：4｜历史已使用：121｜本次新增并覆盖：37/37｜待确认：0｜新增：Part 15
```