@wji.ai/cli 0.9.1 → 0.9.4

package/skill/w-film-dialogue-editor/CHANGELOG.md

@@ -0,0 +1,44 @@
+# CHANGELOG — w-film-dialogue-editor
+
+版本號跟語料庫規模走：1.x = 只有中文語體有語料庫；2.x = 加入英文／韓文／日文語料庫。
+
+## 2.0.0 — 2026-11-09
+
+### 新增
+
+- **美式英文語料庫 133 條**（`references/data/en/`：core 45／work 45／slang 43）—— small talk、服務台詞、corporate-speak、美式裝修工程（estimate／permit／change order／punch list／up to code）、面試、客服、Gen Z／Millennial、地域（NY／Boston／Southern／California／Midwest）、AAVE 借用（已標語境）。
+- **韓文語料庫 133 條**（`references/data/ko/`）—— 합쇼체／해요체／반말 階級、편의점、카페、회식、면접、인테리어 공사、신조어、사투리（已標）。
+- **日文語料庫 133 條**（`references/data/ja/`）—— 敬語、コンビニ、飲食、報連相、飲み会、面接、リフォーム、若者言葉、関西弁、バイト敬語／二重敬語。
+- **`references/lang-ko.md`**（290 行）—— 三層語域、18 個語尾、호칭 禁忌、敬語三種高度、20 archetype、粗口 p0–p3 對平台尺度、書面→口語 20 組、中→韓 transcreation 陷阱 12 條、번역투 8 條、自檢清單。
+- **`references/lang-ja.md`**（312 行）—— 敬語三層對照、19 個終助詞、稱謂與呼び方、ウチ／ソト、關西敬語「〜はる」、粗口分級、書面→口語 20 組、中→日 transcreation 陷阱 12 條、翻訳調 8 條、自檢清單。
+- `references/lang-en.md` 加 §九「英文語料庫」。
+
+### 改動
+
+- `scripts/ref.mjs`：新增 `romanization` 欄位（韓文 Revised Romanization、日文 Hepburn，`show` 會顯示）；`LANG_LABEL` 加 `ko`／`ja`，`en` 正名「美式英文」；標籤詞表 61 → 81（新增 便利店／地鐵／居酒屋／街頭／酒吧／咖啡廳／校園／職場／情侶／上司／下屬／同事／敬語／半語／方言／黑話／戀愛／動漫／遊戲／外來語）。
+- `SKILL.md`：語體表 8 行、使用時機、品質檢查加韓日、新增「版本」段。
+- `references/dialogue_revision_framework.md`：§三 路由表改 8 行（連語料庫欄）。
+- `references/data/README.md`：現況 1035 條、新語言標籤表、`romanization` 欄位說明。
+- 語料庫總數：372 + 133 + 131 + 133 + 133 + 133 = **1035 條**，6 個語言，8 份 guide。
+
+### 生成物
+
+每個語言一套：`references/data/<lang>.all.json`、`references/<lang>-index.md`、`references/data/<lang>-sentences.md`、`references/data/<lang>-sentences.csv`。全部由 `./scripts/rebuild.sh` 重新生成。
+
+## 1.2.0 — 2026-11-09
+
+- 大陸普通話（zh-cn）133 條、台灣國語（zh-tw）131 條語料庫，各 3 shards。
+- `lang-zh-cn.md`、`lang-zh-tw.md` 加「語料庫」段。
+- 標籤系統擴充（兩岸角色／場口標籤）。
+
+## 1.1.0 — 2026-11-09
+
+- 香港粵語語料庫 372 條（core 70／rough 45／older 89／workplace 88／gen-z 80）。
+- 受控標籤詞表（61 個）+ 每條 entry 自動／手動標籤。
+- `scripts/ref.mjs` 查詢 CLI（list／search／show／random／stats／tags／validate／check／build／index／sentences／markdown／langs）。
+- `scripts/rebuild.sh`、`references/zh-hk-index.md`、句子清單 md／csv。
+
+## 1.0.0 — 2026-07-27
+
+- 原版：6 份語體 guide（粵語、大陸普通話、台灣國語、港式普通話、古裝／年代戲、英文）、`dialogue_revision_framework.md`、`templates/dialogue_revision_report.md`。
+- 未有語料庫、未有查詢工具。

package/skill/w-film-dialogue-editor/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: w-film-dialogue-editor
+metadata:
+  version: 2.0.0
+  updated: 2026-11-09
+  corpora: "zh-hk 372, zh-cn 133, zh-tw 131, en 133, ko 133, ja 133（共 1035 條）"
+  guides: 8
+description: "電影、短劇、劇集、舞台或影像劇本的對白校對、潤色、粵語化（附可按年齡／角色／語氣／粗口級別／標籤查詢嘅語料庫：粵語 372、大陸普通話 133、台灣國語 131、美式英文 133、韓文 133、日文 133 條；另有粵語、大陸普通話、台灣國語、港式普通話、古裝年代、英文、韓文、日文八份語言獨立 guide）、普通話化、國語化、英文化／English dialogue、潛台詞強化、角色聲音統一與導演表演提示。Use for: 修改劇本對白、校對人物口吻、提升電影感、處理 exposition、把書面中文改成自然粵語／港式對白或自然普通話／國語對白（涵蓋大陸普通話、台灣國語、港式普通話、古裝及年代戲普通話）；亦用於英文、韓文、日文對白創作與校對、中文劇本轉英文／韓文／日文版（transcreation／在地化，非逐字翻譯）、歐美短劇（ReelShort／DramaBox／TikTok 豎屏短劇）對白、美式英語與英式英語差異、地域口音（New York／Southern／Midwest／California／RP／Estuary／Northern）、階層與族裔語言（prep school、corporate jargon、AAVE、Spanglish）、世代語言（Gen Z／Millennial／Gen X／Boomer slang）、年代英語（1980s–2010s）、社媒與時尚／KOL 圈行話、平台粗口尺度；提供逐句修改表與整場改寫版。"
+---
+
+# Film Dialogue Editor
+
+## 使用時機
+
+當用戶要求校對、修改、潤飾、重寫、粵語化、港式化、普通話化、國語化、英文化、自然化、加強潛台詞、檢查角色口吻、改善節奏、修改劇本對白或提供導演／演員講戲提示時，使用此技能。亦適用於原創英文對白、把中文劇本轉成英文版、校對非母語者寫的英文對白，以及歐美短劇在地化。適用文本包括電影劇本、短劇單集、劇集分場、分場大綱中的對話、角色訪談式獨白，以及需要改成可拍攝對白的散文式內容。
+
+接到任務時先確認本劇預設語體：粵語／港式、大陸普通話、台灣國語、港式普通話、古裝／年代戲普通話、或英文（美式為主）、韓文（首爾標準語／사투리）、日文（標準語／関西弁）。若用戶未說明，依劇本既有用詞推斷並向用戶確認；不要默認改成書面中文。
+
+若任務是「中文稿轉英文版」，先確認這是 **transcreation（再創作）而非 translation（翻譯）**：保住場面目標、人物策略與轉折，重寫語言表層。同時確認目標地區（美式為主／英式為主／混合）、角色世代、投放平台尺度，再開始逐句處理。
+
+## 核心原則
+
+把對白視為**人物在場面壓力中的行動**。不要只把句子改得順口；要判斷角色此刻想得到甚麼、對方如何阻擋、角色為何不直接說真話，以及這句話說完後局面是否改變。
+
+優先保持用戶原本的故事意圖、角色設定、類型語氣與語言地域。若資料不足，不要擅自重設人物背景；先明確標示假設，必要時詢問用戶補充前後情節、角色關係、地域語言、尺度要求和修改幅度。
+
+## 工作流程
+
+| 步驟 | 行動 | 目的 |
+|---|---|---|
+| 1 | 讀取用戶文本，辨認場面、角色、關係、衝突、類型與語言要求。 | 避免只做表面潤色。 |
+| 2 | 判斷修改幅度：輕修、中修或重修。 | 控制改稿力度，避免過度重寫。 |
+| 3 | 先做整體診斷，再做逐句校對。 | 先解決戲劇問題，再處理字句。 |
+| 4 | 修改對白的功能、潛台詞、角色聲音、資訊處理與節奏。 | 令對白更有電影性和可演性。 |
+| 5 | 提供整場修改版，必要時提供導演／演員提示。 | 讓用戶可直接採用或拍攝。 |
+
+## 修改幅度
+
+| 幅度 | 適用情況 | 操作方式 |
+|---|---|---|
+| 輕修 | 用戶文本基本成立，只需更自然、更口語、更準確。 | 保留原句結構，修語氣、節奏、錯字、贅詞與少量口吻。 |
+| 中修 | 對白略直白、資訊太多、角色聲音不夠分明。 | 重組句子、刪減說明、加強攻防、調整潛台詞。 |
+| 重修 | 場面缺乏衝突、人物目的不清、對白不可演。 | 重新設計場面節拍、人物策略和整段對話，但保留故事意圖。 |
+
+## 診斷標準
+
+檢查每句對白是否有戲劇功能。若一句話不推動劇情、不揭露角色、不改變關係、不製造衝突、不承載主題，也不建立節奏，通常應刪除或改寫。檢查角色聲音是否獨特；若遮住角色名後無法分辨誰在說話，應按年齡、階層、職業、教育、地域、親密距離與防衛機制重寫。
+
+檢查潛台詞是否存在。若角色把感受、目的、背景和主題全部直接講出，應改成試探、否認、迂迴、玩笑、攻擊、照顧動作或沉默。檢查 exposition 是否太方便；熟人不應互相解釋雙方早已知道的事，應把資料藏入控訴、責任、交易、威脅、笑話或選擇。
+
+如需診斷維度、修改優先級同輸出格式，讀取 `references/dialogue_revision_framework.md`。**若任務涉及韓文或日文對白（韓劇／日劇改編、字幕、配音、中文稿轉韓／日版），必須先讀 `references/lang-ko.md`／`references/lang-ja.md`，唔可以靠英文或中文規則套落去。**
+
+**若任務涉及英文對白、中文轉英文版或歐美市場在地化，必須讀取 `references/lang-en.md`**，該文件涵蓋中→英 transcreation 陷阱、美式階層／地域／族裔分層、英式英語、世代語言、年代對照、社媒與時尚圈行話及平台尺度。如需標準報告格式，可使用 `templates/dialogue_revision_report.md`。
+
+## 語言／語體（每種語體一份獨立 guide）
+
+**唔可以靠直覺改對白。先定語體，再讀該語體嘅 guide，先至逐句改。** 每種語體規則唔同，唔可以互相套用（例如把粵語語氣詞搬入普通話、把普通話書面句式搬入粵語）。
+
+| 語體 | 獨立 guide | 語料庫（可查詢） |
+|---|---|---|
+| 香港粵語（港式） | `references/lang-zh-hk.md` | `references/data/zh-hk/` ✅ 372 條 |
+| 大陸普通話 | `references/lang-zh-cn.md` | `references/data/zh-cn/` ✅ 133 條 |
+| 台灣國語 | `references/lang-zh-tw.md` | `references/data/zh-tw/` ✅ 131 條 |
+| 港式普通話 | `references/lang-zh-hk-mandarin.md` | — |
+| 古裝／年代戲普通話 | `references/lang-zh-period.md` | — |
+| 英文（美式為主） | `references/lang-en.md` | `references/data/en/` ✅ 133 條 |
+| 韓文（韓國語） | `references/lang-ko.md` | `references/data/ko/` ✅ 133 條 |
+| 日文（日本語） | `references/lang-ja.md` | `references/data/ja/` ✅ 133 條 |
+
+流程：
+
+1. 判斷本劇語體（未講就由用詞推斷，再向用戶確認；唔好默認書面中文）。
+2. 讀對應 `lang-*.md`；混合語體就逐個角色讀。
+3. 有語料庫嘅（zh-hk／zh-cn／zh-tw／en／ko／ja），用 `node scripts/ref.mjs --lang <lang>` 抽真實講法，唔好自己作。
+4. 逐句改；最後用該 guide 嘅自檢清單收貨。
+
+
+
+## 輸出方式
+
+除非用戶只要求簡短潤色，否則使用以下結構輸出。先用一段完整文字說明整體診斷，再用表格做逐句修改，最後提供整場修改版。表格欄位建議為「原句」、「問題」、「修改句」、「修改理由」、「導演／演員提示」。
+
+| 輸出部分 | 要求 |
+|---|---|
+| 整體診斷 | 說明場面主要問題、人物攻防、潛台詞和修改策略。 |
+| 逐句校對表 | 每句給出問題、修改句和修改理由。 |
+| 整場修改版 | 保持劇本格式，提供可直接貼回稿件的版本。 |
+| 導演提示 | 用可執行動詞描述表演行動，例如逼、哄、避、刺、求、試探。 |
+| 後續問題 | 只在必要時詢問缺失資料，不要用過多問題阻塞工作。 |
+
+## 導演／演員提示規則
+
+不要只寫「自然一點」、「傷心一點」、「激動一點」。改用可演行動，例如「你不是解釋，你是在逼對方認錯」、「你講笑不是為了好笑，而是為了不讓對方看見你怕」、「這句停半拍，因為角色在決定是否把真正的話吞回去」。
+
+## 保護原作規則
+
+保留用戶指定不可改的金句、角色名、設定、劇情資訊和語言風格。若必須大幅改寫，先在輸出中註明「以下為重修示範」。若用戶提供的是完整劇本，只修改與對白相關的內容，不主動改變主線、人物命運或場景結構，除非用戶明確要求。
+
+## 品質檢查
+
+交付前檢查新版對白是否更短、更有目的、更貼近角色、更有潛台詞、更容易表演，並且沒有把所有角色改成同一種口吻。若是粵語版本，朗讀時應自然，不應像書面中文硬轉廣東話。若是普通話版本，按既定語體（大陸／台灣國語／港式普通話／古裝年代）檢查語氣詞、用詞時代、地域口音與英語夾雜的密度；避免大陸、台灣、港式三種口吻互相串味，避免現代詞滑入古裝戲，亦避免把粵語語氣詞「啦／喇／啫」直接搬入普通話。若劇本含多語體角色，檢查每個角色的語體標記是否一致。
+
+若是英文版本，逐項核對：contraction 是否已縮寫、不縮寫者是否都有戲劇理由；一場戲直呼對方名字是否超過兩次；是否有超過 20 字而無理由的長句；是否殘留 "I hate you" 式情緒宣言；遮住角色名朗讀是否像字幕（成語直譯、敬語殘留、主語缺失）；美式角色是否誤用英式詞（flat／trainers／mobile）或反之，是否有角色同時帶兩地標記；slang 是否符合角色出生年、是否堆砌過密；AAVE 或其他社群語言是否從角色出發而非刻板印象、是否被用來標記反派或笑點；時尚／KOL 行話是否服務角色的專業自信與權力關係而非炫技；粗口密度是否符合投放平台、開場 3 秒是否乾淨。完整清單見 `references/lang-en.md` 第八節。
+
+若是韓文或日文版本，按 `references/lang-ko.md`／`references/lang-ja.md` 嘅自檢清單核對：同一對關係內嘅敬語階層（합쇼체／해요체／반말；ですます／尊敬語・謙譲語／タメ口）有冇前後不一、終助詞／語尾有冇堆砌、稱謂同內外關係（우리／うち）是否正確、有冇字幕腔直譯（예：主語過多、直譯「あなた」）。
+
+若同時交付中文版與英文版，兩版必須場面目標、人物策略與轉折一致，但**不要求句句對應**——英文版可合併、拆分或改變攻防順序，只要戲劇功能相同。
+
+## 版本
+
+**v2.0.0**（2026-11-09）
+
+| 語言／語體 | guide | 語料庫 |
+|---|---|---|
+| 香港粵語 | `references/lang-zh-hk.md` | 372 條（5 shards） |
+| 大陸普通話 | `references/lang-zh-cn.md` | 133 條 |
+| 台灣國語 | `references/lang-zh-tw.md` | 131 條 |
+| 港式普通話 | `references/lang-zh-hk-mandarin.md` | — |
+| 古裝／年代戲普通話 | `references/lang-zh-period.md` | — |
+| 美式英文 | `references/lang-en.md` | 133 條 |
+| 韓文 | `references/lang-ko.md` | 133 條 |
+| 日文 | `references/lang-ja.md` | 133 條 |
+
+語料庫共 **1035 條**、6 個語言、8 份 guide、81 個受控標籤。查詢工具：`scripts/ref.mjs`；重建全部生成物：`./scripts/rebuild.sh`。版本紀錄見 `CHANGELOG.md`。

package/skill/w-film-dialogue-editor/references/data/README.md

@@ -0,0 +1,222 @@
+# 對白語料庫（dialogue reference database）
+
+每個語言／語體一個獨立目錄：`references/data/<lang>/<shard>.json`。
+每個語言亦有一份獨立閱讀版指南：`references/lang-<lang>.md`。
+
+| 語言／語體 | 指南 | 語料庫 |
+|---|---|---|
+| zh-hk 香港粵語（港式） | `lang-zh-hk.md` | ✅ `data/zh-hk/` 372 條 |
+| zh-cn 大陸普通話 | `lang-zh-cn.md` | ✅ `data/zh-cn/` 133 條 |
+| zh-tw 台灣國語 | `lang-zh-tw.md` | ✅ `data/zh-tw/` 131 條 |
+| zh-hk-mandarin 港式普通話 | `lang-zh-hk-mandarin.md` | — |
+| zh-period 古裝／年代戲 | `lang-zh-period.md` | — |
+| en 美式英文（American English） | `lang-en.md` | ✅ `data/en/` 133 條 |
+| ko 韓文（韓國語） | `lang-ko.md` | ✅ `data/ko/` 133 條 |
+| ja 日文（日本語） | `lang-ja.md` | ✅ `data/ja/` 133 條 |
+
+未建語料庫嘅語體，照下面 schema 開 `data/<lang>/` 即可，`scripts/ref.mjs` 會自動發現。
+
+**語料庫版本：2.0.0**（2026-11-09）—— 6 個語言、1035 條、8 份 guide；版本紀錄見 `CHANGELOG.md`。
+
+## 現況（6 個語言，共 1035 條）
+
+**zh-hk 香港粵語（372）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 70 | 萬用：語氣詞組合、客套、婉拒、日常反應 |
+| `rough.json` | 45 | 寸嘴、衝突、威脅、侮辱（含粗口分級） |
+| `older.json` | 89 | 45+：師奶、長輩、茶餐廳、管理員、老師傅、諺語 |
+| `workplace.json` | 88 | 職場、OL、老細、客戶、工程行話 |
+| `gen-z.json` | 80 | 青少年、Gen Z、校園、討論區、潮語 |
+
+**zh-cn 大陸普通話（133）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 45 | 日常、客套、婉拒、服務業、小區街坊 |
+| `work.json` | 45 | 互聯網黑話、老闆下屬、裝修工程、面試 |
+| `slang.json` | 43 | 網絡用語、吵架不帶髒、東北／川渝／京腔 |
+
+**zh-tw 台灣國語（131）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 44 | 語氣詞、客套、婉拒、家庭、超商／飲料店 |
+| `work.json` | 44 | 職場、慣老闆、裝修工班、報價 |
+| `slang.json` | 43 | 網路用語、傻眼、衝突 |
+
+**en 美式英文（133）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 45 | small talk、服務台詞（咖啡店／diner／超商）、問路、鄰里、家庭、婉拒、道別 |
+| `work.json` | 45 | corporate-speak、上司下屬、面試、美式裝修工程、客服、談判 |
+| `slang.json` | 43 | Gen Z／Millennial、衝突升級、網絡、地域、AAVE 借用（已標語境） |
+
+**ko 韓文（133）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 45 | 인사／존댓말、편의점、카페、식당、길 묻기、가족、婉拒、收尾 |
+| `work.json` | 45 | 회사（팀장／과장／대리）、보고、야근／회식、면접、인테리어 공사、고객 응대 |
+| `slang.json` | 43 | 신조어、반말、衝突、인터넷、少量 사투리（已標） |
+
+**ja 日文（133）**
+
+| shard | 條數 | 內容 |
+|---|---|---|
+| `core.json` | 45 | あいさつ、コンビニ、飲食、道を尋ねる、家族、婉拒（大丈夫です 陷阱）、締め |
+| `work.json` | 45 | 敬語／報連相、上司部下、残業／飲み会、面接、リフォーム工事、クレーム対応 |
+| `slang.json` | 43 | 若者言葉、タメ口、衝突、ネット、少量関西弁（已標） |
+
+合共 1035 條。
+
+生成物（每個語言一套，跑 `./scripts/rebuild.sh` 會全部更新）：
+
+- `<lang>-index.md` — 索引（核心／年齡／角色，帶標籤）
+- `<lang>-sentences.md` — 全部對白句（句 ｜ 講法 ｜ 意思 ｜ 標籤）
+- `<lang>-sentences.csv` — 同上，CSV（Excel／Sheets 直接開）
+- `<lang>.all.json` — 合併版單一 JSON
+## 查詢
+
+~~~bash
+node scripts/ref.mjs list --age young --tone sassy
+node scripts/ref.mjs list --age senior --archetype craftsman --limit 15
+node scripts/ref.mjs search 咩料
+node scripts/ref.mjs show hk-core-001
+node scripts/ref.mjs random --archetype housewife -n 5
+node scripts/ref.mjs list --max-prof 0        # 只要乾淨（粗口 0 級）
+node scripts/ref.mjs list --json              # 機器讀
+node scripts/ref.mjs list --tag 裝修,拒絕            # 要同時有兩個 tag
+node scripts/ref.mjs list --any-tag 讚,踩            # 有其中一個
+node scripts/ref.mjs stats                    # 分佈
+node scripts/ref.mjs tags                     # 所有可用標籤
+node scripts/ref.mjs validate                 # 整個語言語料庫
+node scripts/ref.mjs check <file>             # 單一 shard
+node scripts/ref.mjs build                    # 合併 <lang>.all.json
+node scripts/ref.mjs index                    # 生成人讀索引（redirect 成 .md）
+node scripts/ref.mjs markdown --by age        # 生成 markdown 表
+node scripts/ref.mjs --lang ko list --tag 敬語    # 韓文
+node scripts/ref.mjs --lang ja list --tag 居酒屋  # 日文
+node scripts/ref.mjs --lang en list --tag 職場    # 美式英文
+node scripts/ref.mjs langs                    # 列出所有語言
+~~~
+
+## 檔案格式
+
+~~~json
+{
+  "lang": "zh-hk",
+  "entries": [
+    {
+      "id": "hk-core-001",
+      "phrase": "唔該",
+      "variants": ["唔該晒"],
+      "jyutping": "m4 goi1",
+      "meaning": "勞煩／多謝（服務、幫忙）",
+      "literal": "not should",
+      "categories": {
+        "age": ["teen", "young", "mid", "senior", "elder"],
+        "archetype": ["office", "craftsman"],
+        "tone": ["polite"],
+        "function": ["thanks"],
+        "register": "everyday",
+        "profanity": 0,
+        "socialDistance": ["stranger", "friend", "colleague", "client"]
+      },
+      "example": "唔該借借。",
+      "situation": "人多地方要人讓路",
+      "avoid": ["送禮物用「多謝」，唔係「唔該」"],
+      "note": "服務／幫忙用唔該；禮物／讚美用多謝。",
+      "tags": ["客套", "日常"],
+      "source": "general"
+    }
+  ]
+}
+~~~
+
+### 欄位
+
+| 欄位 | 必填 | 說明 |
+|---|---|---|
+| `id` | ✅ | `hk-<shard>-<序號>`，全語言唯一 |
+| `phrase` | ✅ | 最常見寫法，正字或慣用寫法 |
+| `variants` | | 同義／縮略／變體寫法 |
+| `jyutping` | | 粵拼（粵語專用）；唔肯定就省略，唔好亂寫 |
+| `romanization` | | 韓文用 Revised Romanization、日文用 Hepburn；英文省略 |
+| `meaning` | ✅ | 香港人實際點解，唔好照字面 |
+| `literal` | | 字面意思（幫母語非粵語讀者） |
+| `categories.age` | | `kid` 6-12、`teen` 13-19、`young` 20-29、`mid` 30-44、`senior` 45-59、`elder` 60+；省略＝任何年齡 |
+| `categories.archetype` | | 角色類型（可多個，第一位＝主要角色）；省略＝任何角色 |
+| `categories.tone` | ✅ | 態度／情緒，可多個 |
+| `categories.function` | ✅ | 對白功能（打招呼、拒絕、踩、安慰…） |
+| `categories.register` | ✅ | `everyday` \| `slang` \| `internet` \| `proverb` \| `idiom` \| `professional` \| `english-mix` \| `profanity` |
+| `categories.profanity` | ✅ | 0 乾淨、1 輕微發洩（頂／離譜／癡線）、2 侮辱／攻擊（食屎啦你）、3 真粗口（仆街及五大粗口） |
+| `categories.socialDistance` | | `family` \| `friend` \| `colleague` \| `client` \| `stranger` \| `conflict` |
+| `example` | ✅ | 一句真實會講嘅對白，可拍攝 |
+| `situation` | ✅ | 咩場口會講 |
+| `avoid` | | 用錯會點（對象、場合、語體） |
+| `tags` | | 2–6 個自由標籤，見下 |
+| `note` | | 語感補充、年齡／階層差異 |
+| `source` | | `general` 或網址 |
+
+### 標籤（tags）
+
+自由標籤用嚟跨維度檢索；**佢唔取代 facet**（角色／語氣／年齡仍然用 `--archetype`／`--tone`／`--age` 查）。
+
+| 組 | zh-hk（粵語） | zh-cn（大陸） | zh-tw（台灣） |
+|---|---|---|---|---|
+| 場口 | 裝修、地盤、茶記、街市、飲茶、公司、學校、家庭、大廈、店舖 | 裝修、工地、餐廳、菜市場、茶樓、公司、學校、家庭、小區、店舖 | 裝修、工地、餐廳、菜市場、公司、學校、家庭、社區、店舖 |
+| 角色 | 師傅、師奶、長輩、後生、老細、客戶、伙記、管理員、學生、OL、外賣 | 師傅、大媽、阿姨、老闆、客戶、服務員、保安、外賣員、司機、白領、學生、老師、年輕人 | 師傅、阿姨、老闆、客戶、店員、警衛、外送員、司機、上班族、學生、老師、年輕人 |
+| 用途（共用） | 開場、收尾、拒絕、讚、踩、八卦、講價、關心、抱怨、客套、日常、面試、投訴 | | |
+| 語感 | 直球、冷面、惜字如金、老派、中英夾雜、潮語 | 直球、冷面、惜字如金、老派、中英夾雜、網絡用語 | 直球、冷面、惜字如金、老派、中英夾雜、網絡用語 |
+
+英文／韓文／日文用：
+
+| 組 | en（美式英文） | ko（韓文） | ja（日文） |
+|---|---|---|---|
+| 場口 | 公司、學校、家庭、餐廳、酒吧、街頭、便利店、地鐵、咖啡廳、校園、職場 | 公司、學校、家庭、餐廳、便利店、咖啡廳、地鐵、職場 | 公司、學校、家庭、餐廳、居酒屋、便利店、地鐵、咖啡廳、職場 |
+| 角色 | 老闆、客戶、上司、下屬、同事、店員、服務員、司機、保安、白領、學生、老師、年輕人、長輩 | 老闆、客戶、上司、下屬、同事、店員、服務員、司機、保安、白領、學生、老師、年輕人、長輩 | 老闆、客戶、上司、下屬、同事、店員、服務員、司機、保安、白領、學生、老師、年輕人、長輩 |
+| 用途（共用） | 開場、收尾、拒絕、讚、踩、八卦、講價、關心、抱怨、客套、日常、面試、投訴 | | |
+| 語感 | 直球、冷面、老派、潮語、網絡用語、黑話、方言、外來語 | 直球、冷面、老派、敬語、半語、方言、網絡用語、外來語 | 直球、冷面、老派、敬語、方言、網絡用語、外來語、黑話 |
+
+唔喺受控詞表嘅標籤只會出 warning，唔算錯；加新標籤請同時加入 `scripts/ref.mjs` 嘅 `TAGS`，方便日後檢索。
+
+`ref.mjs` 用一套**共用詞表**（`node scripts/ref.mjs tags` 可睇全部）；上表只係各語言實際會用嘅子集。
+
+規則：
+
+1. 角色標籤只取**主要角色**（archetype 第一位）；其餘角色用 `--archetype` 查。
+2. 場口標籤由 phrase／example 關鍵詞 + 主要角色推導；寧缺勿濫。
+3. 可以自由加新標籤；`node scripts/ref.mjs validate` 會提示唔在受控詞表嘅標籤（warning，唔算錯）。
+4. 加完跑 `node scripts/ref.mjs validate` → `build` → `index`。
+
+### archetype 一覽
+
+`student` 學生・`slacker` 廢青躺平・`office` 打工仔 OL・`boss` 老細／老闆・
+`client` 客人／業主・`craftsman` 師傅／技工・`waitress` 茶餐廳伙記・`shopkeeper` 街市／小店・
+`security` 管理員・`housewife` 師奶・`designer` 設計／創意・`street` 江湖／地盤・
+`elder` 長輩・`trainer` 健身／運動・`mum` 阿媽・`dad` 阿爸・`kid` 細路・
+`teacher` 老師・`sales` 銷售／客服・`delivery` 外賣／司機
+
+### tone 一覽
+
+`sassy` 寸嘴・`blunt` 直球・`cold` 冷淡・`warm` 親切・`complain` 抱怨・`threat` 威脅・
+`whiny` 撒嬌／扭計・`helpless` 無奈・`gossip` 八卦・`funny` 搞笑・`polite` 客套・
+`angry` 嬲・`sarcastic` 曲線／反串・`worried` 擔心・`proud` 認叻・`shy` 怕醜・`flirty` 撩・`surprised` 驚訝
+
+### function 一覽
+
+`greet` `farewell` `praise` `insult` `refuse` `question` `urge` `comfort` `bargain`
+`gossip` `joke` `warn` `threaten` `dismiss` `agree` `disagree` `complain` `tease`
+`flirt` `apology` `thanks` `challenge` `boast` `surprise` `encourage` `refuse-soft`
+
+## 寫作規矩
+
+1. 只收**該語言母語者真實會講**嘅說法；唔好自創、唔好書面語直譯。粵語嘅見 `lang-zh-hk.md`，英文／韓文／日文見各自 guide。
+2. 每條最少一句真對白（`example`），要拍到、講得出。
+3. 標清楚年齡同角色；同一句喺唔同年齡層可能已經過時。
+4. 粗口一定要標 `profanity`，唔好為齊全而濫收。
+5. 只加自己有信心嘅粵拼；唔肯定就留空。
+6. 加完 entry 跑 `check`，最後 `build` ＋ 重生成 `zh-hk-index.md`。