字幕词书生成器

使用本 skill 将影视字幕素材转化为英语学习包：生词表、真实字幕例句、长难句推荐、精讲分析、导入物料和导出文件。目标是帮人从影视语境中学习英语，而不是机械地扒字幕。

产出物

每次正常请求应产出：

• 默认输出完整词表，除非用户要求限制数量（如 Top 200）。
• 一列一词纯文本词表：每行一个英文单词，可直接导入背单词 App。
• 扇贝导入指南 HTML：说明如何用一列一词词表导入扇贝。
• 每个词的真实字幕例句（字幕中有对应中文则同步展示）。
• 长难句推荐：含英文原文、中文参考翻译、选句理由、重点目标词。
• 长难句精读页 HTML：用于精读、拆句、跟读。
• 导出格式至少包含：JSON + CSV + 一列 TXT + HTML 学习页 + 长难句 HTML + 导入指南；环境支持时追加 PDF。
• 可选豆瓣影视元数据（简介/海报），不绕过登录、验证码或访问限制。
• 中文向的说明文字和 UI（除非用户另有要求）。

Required User Choices

Before generating, always ask concise questions when the user has not specified these choices. The user must explicitly confirm each of these. If the user says “自动/你来决定”, use the recommended defaults but still surface the choices in the chat reply so the user can override.

• Scope: movie, single episode, season, full series. Ask which scope before searching.
• Known-word exclusion: none, primary (小学), middle-school/中考, high-school/高考, or custom word list. Always ask explicitly whether to exclude high-school/高考 words. Confirm before generating.
• Minimum word length: 2 or 3. Recommend 2 for 影视台词 (catches more words), 3 for cleaner lists.
• Sort order: frequency, subtitle/source order, or A-Z. Ask “按词频还是按字幕出现顺序” before generating.
• Size: all words or Top N. Confirm whether the user wants the full list or a cap.
• Lemmatization: restore word forms (e.g. running → run) or keep original subtitle forms. Ask before generating.
• Difficult sentences: count is 20-30 by default (was 12). Ask the user to confirm count, source language mode, and whether to enable LLM (DeepSeek) enrichment. Confirm before generating.
• Import package: whether they want a Shanbay/扇贝 one-column 词表 and tutorial. Confirm before generating.
• Metadata: whether they have a Douban URL to include public 作品简介/海报 metadata. Ask before generating.
• Output directory and filename slug: confirm --out path and a readable --title slug before running, especially when outputs may overwrite existing files.
• Re-run vs new run: when a previous wordbook for the same title already exists, ask whether to overwrite, append a suffix, or pick a new directory.

Never silently pick the default for scope, known-word exclusion, sort order, or output path. State the recommended default in the question and let the user confirm or change it.

Default to a bilingual English-learning package. Subtitle files must contain English dialogue and Chinese support. Pure Chinese subtitles are unusable; pure English subtitles are not accepted for the default package unless the user explicitly asks to allow English-only material.

Input Paths

Accept any of these:

• Local subtitle files: .srt, .ass, .ssa, .vtt
• A directory or archive of subtitles
• A movie/series title via ASSRT/射手网 when ASSRT_TOKEN is available
• A movie/series title where another subtitle-search implementation exists
• Existing JSON/CSV/word list to convert into a study page

If the user gives only a title, first try an enabled subtitle source such as ASSRT/射手网. If no subtitle source/token is available, ask for subtitle files. If the local web app project is available, you may use it as the richer subtitle-search implementation.

Quick Script

For standalone subtitle files or directories, use:

python /Users/yangbaibai/.codex/skills/subtitle-wordbook-agent/scripts/make_wordbook.py \
  --input /path/to/subtitles \
  --title "Friends S01" \
  --out /path/to/output \
  --min-len 2 \
  --exclude-level gaokao \
  --sort source

For ASSRT/射手网 subtitle search and download, use:

ASSRT_TOKEN=... python /Users/yangbaibai/.codex/skills/subtitle-wordbook-agent/scripts/make_wordbook.py \
  --query "Wednesday S01" \
  --title "星期三 S01" \
  --out /path/to/output \
  --download-dir /path/to/downloads \
  --max-results 1 \
  --exclude-level gaokao \
  --sort frequency \
  --language-mode bilingual

This creates JSON, CSV, a one-column TXT word list, an HTML study page, a long-sentence explainer HTML, and a Shanbay/扇贝 import guide without requiring the local web app. Add --douban-url <url> to include public Douban metadata.

For the existing local web app implementation, use:

python /Users/yangbaibai/.codex/skills/subtitle-wordbook-agent/scripts/start_agent.py --check
python /Users/yangbaibai/.codex/skills/subtitle-wordbook-agent/scripts/start_agent.py --port 8090

Agent Behavior

When implementing or operating an app, make it agentic:

• Let the user state a goal in chat.
• Ask the required user choices (see above) before invoking the script, especially: scope, known-word exclusion level, min word length, sort order, lemmatize yes/no, full vs top-N, difficult-sentence count, output path.
• Only after the user confirms (or explicitly says “自动/直接做/全帮我执行”) may you invoke the script. If they say “自动”, still surface the recommended choices in your reply so the user can override later.
• Show progress for search, download, parse, extract, sentence selection, export generation.
• When a previous wordbook for the same title already exists at the chosen output path, ask before overwriting: replace, suffix _v2/_v3, or pick a new folder.
• Ask only when a missing input blocks execution or when an external side effect is risky.

Extraction Rules

• Strip timestamps, ASS tags, HTML tags, speaker noise, and repeated formatting lines.
• Drop ASS/SSA metadata lines such as Format:, Style:, [Script Info], and [Events]; never let them appear as vocabulary examples or difficult sentences.
• Preserve bilingual subtitle text for examples, but extract English tokens only.
• Require English dialogue and Chinese subtitle support by default. If only English is available, explain that it needs explicit English-only mode and will lack Chinese learning support.
• Filter common stopwords and basic known-word lists when requested.
• Support known-word exclusion levels: primary, zhongkao, gaokao, all, and custom word lists.
• Support sorting by frequency, source, or az.
• Lemmatize common inflections, but avoid bad cuts like something -> someth or everything -> everyth.
• Keep proper names if useful to the source, but do not let names dominate the study list.
• For full series/seasons, keep file/source order available as a sort option.

Difficult Sentence Recommendations

• Default to 20-30 long sentences (was 12). Add a --sentences CLI option to override; pass any integer ≥ 0. The script must not silently clamp this value.
• Score sentences using a mix of:
• Length and clause complexity.
• Target vocabulary density.
• Rare or abstract words.
• Idioms, phrasal verbs, or culturally loaded expressions.
• High learning value for the user’s level.
• Enrichment is generated by the script itself (offline heuristics), not by calling a third-party LLM. The agent must improve the local pipeline directly, not delegate to an external model. Each picked sentence must include:
  1. 意群拆解 (clause breakdown) — split by punctuation + connectors (that/which/when/because/although…), mark the main clause and label each chunk with its Chinese role (主句 / that 从句 / 介词短语 / 修饰 / 补充信息).
  2. 重点词块 (key chunks / phrasal verbs / collocations) — regex-based detection of phrasal verbs (verb + away/back/down/for/in/...), prepositional phrases, and quantifier collocations. Always include the matched English phrase + a label.
  3. 翻译方法 (translation method) — choose from a curated playbook: 顺译 / 逆译 / 分译 / 介词短语后置 / 从句定位 / 意群断句 / 短语动词整体理解, with one example.
  4. 文化 / 剧情背景 (cultural or plot context) — keyword-driven: family / school / hospital / police / workplace / romance / horror. Output is 日常对白 when no keyword matches.
  5. Polished Chinese translation — the script may keep the bilingual subtitle translation as a baseline, but it must flag subtitle 直译 vs 本地启发式精讲 on each card so the user knows the source. LLM-polished translations are NOT required and must not be silently added.
• The HTML output must contain sections per card: 难点分析 / 翻译方法 / 意群拆解 / 重点词块 / 文化背景. The previous LLM-related CLI flags (--llm-enrich, --deepseek-*, --llm-batch-size) must be removed so the script does not appear to call out to a third-party model.
• Output per sentence: English sentence, Chinese reference translation, target words, a short reason, Chinese explanation, clause breakdown, key chunks, translation method, cultural context.
• For the long-sentence HTML, prefer a handout/note style: highlighted English sentence, key words, reference translation, difficulty analysis, clause breakdown, key chunks, translation method, and cultural context. Deduplicate by normalized English text so simplified/traditional/English-only variants of the same line appear once; prefer the bilingual version.
• Mark each sentence card with 本地启发式精讲 (or subtitle 直译 for English-only runs) so the user can see quality at a glance.

References

• Read references/standalone-workflow.md for standalone script behavior and output schema.
• Read references/local-webapp.md only when maintaining or using the local Chinese web app implementation.