短视频口播稿生成器（koubo-generator）
用途
把给定主题 + 必备内容点，写成可直接照读的短视频口播稿，并生成排版干净的 Word 文档。
- 默认在每段前加 [MM:SS] 红色加粗时间戳，方便照稿录制对齐。
- 加 --no-timestamp 则只保留口播内容，不出现任何时间轴（满足"文档只保留口播内容"的硬性要求）。
- 按语速自动估算总时长，并对照用户给定的上限告警。
何时使用
- "写/生成/做一篇口播稿、短视频脚本、讲话稿、口播文案"
- "时长控制在 X 分钟以内""自动标注时间轴""Word 只保留口播内容""把时间轴去掉"
- 任何需要把一段知识/故事变成可直接录制稿的场景
工作流
1. 收集需求（缺失给合理默认，不要反复追问）
- 主题：如"春秋时期楚庄王"。
- 固定开场句（如有）：如"大家好，我是老猴猴讲故事"，必须作为全文第一句、一字不差。
- 必备内容点：用户列出的必须覆盖的情节/论点，逐条对应到段落。
- 目标时长：默认 300 秒（5 分钟）。据此反推字数上限。
- 风格：默认口语化、通俗易懂、严谨准确，穿插生动细节。
2. 起草口播稿（核心，由 AI 完成）
- 口语化表达，避免书面长句与术语堆砌；适当用设问、画面感细节、拟声词吸引观众。
- 严谨准确：人名、年代、地名、因果关系核对可靠来源；存疑先核实，生动细节不得歪曲史实。
- 按自然语篇节奏分段：每段一个逻辑节拍（背景/转折/高潮/结尾），便于录制剪辑。
- 字数预算：中文口播约 4 字/秒。目标时长 T 秒、段落数 N 时，总字数 ≈
4 × (T - N×0.7)。据此增删，使估算总时长略小于上限（留余量）。 - 将每段口播写进一个 UTF-8 文本文件，每行一段，空行忽略；如有固定开场句，置于首行。
3. 生成 Word 文档
用受管 Python 运行内置脚本（脚本会自动安装 python-docx，若缺失）：
PY="C:/Users/Houpingyuan/.workbuddy/binaries/python/versions/3.13.12/python.exe"
"$PY" "C:/Users/Houpingyuan/.workbuddy/skills/koubo-generator/scripts/generate_koubo_docx.py" \
--input 口播稿.txt --output 口播稿.docx \
--cps 4.0 --pause 0.7 --limit 300 \
--title "" --opening "大家好，我是老猴猴讲故事" --no-timestamp
参数说明：
--input：步骤 2 写出的文本文件（每行一段）。--output：输出 .docx 路径。--cps：语速（字/秒），默认 4.0；想更快可调到 4.5~5。--pause：段落间停顿（秒），默认 0.7。--limit：时长硬上限（秒），默认 300；超出会告警。--font：正文字体，默认"微软雅黑"。--size：正文字号（磅），默认 12。--title：可选居中标题；不填则文档纯口播、不带头标题。--opening：可选固定开场句，脚本会确保它作为首段（若文本首行已含且逐字相同则不会重复）。--no-timestamp：加上此开关则不生成时间轴，仅保留口播内容。
4. 交付与校验
- 脚本打印估算总时长与是否超限。若超
limit，调高--cps或删减内容后重跑。 - 将生成的 .docx 交付用户，口头给出总时长。
- 提示：如需改字体/配色/语速，调整脚本参数后重生成。
⚠️ 已踩过的坑（务必遵守）
- 开场句重复：脚本判断"文本首行 == --opening 参数"时才不会前置重复。若文本首行带了句号而 --opening 没带（或反之），会生成两段一模一样的开场句。
- 规避：要么文本首行直接写开场句、且--opening与之逐字一致；要么文本里已含开场句就不传--opening。 - 去掉时间轴：不要事后再用脚本去删 run——直接生成时加
--no-timestamp最干净。若拿到的是已带时间轴的旧文档，可用 python-docx 删除每段开头text.startswith('[')的 run。 - 只保留口播内容：文档正文不含任何制作备注、分镜说明或额外批注；时间戳是注解，不算口播（带时间轴版本属用户另行要求）。
- 准确性优先：生动细节不得歪曲史实/事实；存疑信息先核实。
参考资料
- 历史类口播常见结构：背景引入 → 反常/悬念 → 转折（关键人物/事件）→ 高潮（成语出处/名场面）→ 收束（意义/下期预告）。
- 成语出处须注明原始出处（如"一鸣惊人"出自《史记·楚世家》楚庄王与伍举的"三年不蜚不鸣"对话；"问鼎中原"出自楚庄王问周王室九鼎轻重）。
