fix: 修复 pipeline runner 参数转发，整合文档与 .ps1 弃用声明

CHANGELOG.md

@@ -4,6 +4,31 @@
 
 ## [Unreleased]
 
+_本分支（`refactor/runner-fixes-docs-consolidation`）的改动记录见下文；发布时再并入正式版本号。_
+
+### Added
+
+- `tests/test_runner.py`：覆盖 pipeline runner 的参数转发、门禁拦截、运行状态文件等行为
+- `tests/test_fetch_aihot.py`：覆盖 `fetch_aihot.py` 的 CLI 与 `fetch_json` 重试逻辑
+
+### Changed
+
+- `pipeline/runner.py`：修复参数转发缺失（README 中的命令此前无法直接运行）、改为以模块方式调用各步骤、新增 `--list` 与运行诊断 JSON、明确报错与门禁提示
+- `fetch_aihot.py`：新增 `--base-url`（默认 `https://aihot.virxact.com`），与 `.ps1` 回退脚本的 `-BaseUrl` 对齐
+- `scripts/notify_delivery.ps1`、`skills/tryworld-topics/scripts/fetch_aihot.ps1`、`scripts/doctor.ps1`：标注为已废弃的 Windows 回退脚本，`.py` 为唯一规范路径
+- `README.md` / `README.zh-CN.md` / `CONTRIBUTING.md` / 各 `SKILL.md` / `references/`：统一指向 `.py` 脚本，移除 `.ps1` 作为规范路径的表述
+- `pipeline/steps/step_04_tts.py`：澄清 `--theme-content` 帮助文本（品牌/视觉主题，默认 `themes/paper-algorithm.json`），并提示与 step 01 的“内容主题”同名不同义
+- `CHANGELOG.md`：将此前 `[Unreleased]` 内容并入 `[1.0.0]`，改为真正的“未发布”区
+
+### Fixed
+
+- `README.md` / `README.zh-CN.md`：测试数量不再硬编码，改为引导用 `pytest --collect-only` 读取实际数量
+- `verify_output.py`：ffprobe/ffmpeg 发现逻辑与 `tts_yunxi.py` 的 `find_bin` 对齐（PATH 优先 → `HYPERFRAMES_FFMPEG_DIR` / `FFMPEG_BIN` → WinGet 目录），PATH 未配置时不再直接判定“工具不可用”而退出
+
+## [1.0.0] - 2026-09-05
+
+首个正式版本。
+
 ### Added
 
 - `scripts/check_skills.py`：仓库级检查脚本，编译技能 Python 脚本并跑活人感门禁

CONTRIBUTING.md

@@ -16,7 +16,7 @@ paper-algorithm/
 │   └── tryworld-topics/         # 选题技能（AIHOT 数据 → 选题清单）
 ├── scripts/                     # 仓库级检查脚本
 │   ├── check_skills.py          # 编译技能脚本 + 跑活人感门禁
-│   └── doctor.ps1               # 环境自检
+│   └── doctor.py                # 环境自检（跨平台；doctor.ps1 为 Windows 回退，已弃用）
 ├── examples/                    # 默认主题产出的示例
 └── README.md / README.zh-CN.md  # 中英索引
 ```

README.md

@@ -317,14 +317,14 @@ Full edge-tts voice ids are accepted too. By default the pipeline never asks abo
 
 Before delivery, every polished script and platform title passes a machine gate — **the ban targets rhetorical moves, not literal strings**. Repeating the same move with different words still counts.
 
-- **Flip-flop rhetoric**: sets up a misunderstanding the reader never had, then overturns it for dramatic lift. Known guises include 不是……而是……, 并非……而是……, 表面……实际……, 看似……实则……, 你以为……其实……, 回头才发现, 说到底, 答案恰恰相反 — state judgments directly, judgment first, evidence after.
-- **Triple+ parallel structure**: three or more identical constructions; keep at most two.
-- **Lyric metaphor**: no concrete verbs bolted onto abstract nouns ("time keeps the details" type); unaffected when writing about concrete things.
-- **Nominalization**: "实现了效率的提升" → say how much faster, how many people saved.
-- **Punctuation tiers**: all dashes banned; colons only to introduce direct speech.
-- **Jargon tiers**: absolute bans + context-sensitive words, maintained by the checker.
+The banned moves (flip-flop rhetoric, triple+ parallel structure, lyric metaphor, nominalization, punctuation tiers, hard stop-words, model signposts, jargon tiers) are defined in exactly two places, so the list cannot drift between copies:
 
-`tryworld-paper/scripts/check_prose.py` (from [human-writing](https://github.com/KKKKhazix/human-writing) v1.1.0, MIT) runs these checks automatically and adds statistical signals — sentence-length variance, conjunction density, model-favorite lyric words, 「」-quote density. **Zero hard violations required before the user-confirmation gate; failing means no delivery.**
+| Source | What it holds |
+|---|---|
+| `skills/tryworld-paper/references/workflow.md` §1.2.1 (item 5) | The prose rules, with action-level definitions |
+| `skills/tryworld-paper/scripts/check_prose.py` | The checker that enforces them — absolute bans + context-sensitive words, plus statistical signals (sentence-length variance, conjunction density, model-favorite lyric words, 「」-quote density) |
+
+`check_prose.py` (from [human-writing](https://github.com/KKKKhazix/human-writing) v1.1.0, MIT) is the authority when the two disagree in wording. **Zero hard violations required before the user-confirmation gate; failing means no delivery.**
 
 ---
 
@@ -363,14 +363,14 @@ A skill fires when the request matches its trigger words — no commands to memo
 ### In-repo check scripts
 
 - `python -X utf8 scripts/check_skills.py`: compiles skill Python scripts and runs the aliveness gate
-- `python -m pytest tests/ -v`: run 23 unit tests (check_prose, verify_output, tts_yunxi, check_skills) over `examples/` scripts and titles.
+- `python -m pytest tests/ -v`: run the unit-test suite (check_prose, verify_output, tts_yunxi, check_skills, fetch_aihot, pipeline runner) over `examples/` scripts and titles. The exact count moves as tests are added — read it from `python -m pytest tests/ --collect-only -q` instead of hard-coding it in this file.
 - `python scripts/doctor.py`: checks Python, Node, FFmpeg/ffprobe, edge-tts, HyperFrames, and optional email credentials. Exits 1 when a required item is missing.
 
 ### Environment
 
 Run `npx hyperframes doctor` to check the environment at once. These skills are built for TryWorld's own production workflow, so a few things are assumed — all adjustable in the skill files:
 
-- **Cross-platform** — data-fetching (`tryworld-topics`) and email-notice (`tryworld-koubo`) scripts are Python (`.ps1` fallback versions retained); `tryworld-topics` documents a curl fallback in its `references/`.
+- **Cross-platform** — data-fetching (`tryworld-topics`) and email-notice (`tryworld-koubo`) scripts are Python (`.ps1` fallback versions retained but deprecated — the `.py` scripts are the canonical path); `tryworld-topics` documents a curl fallback in its `references/`.
 - **Python 3.10+** — `pip install edge-tts` for the voiceover pipeline (`tryworld-paper/scripts/tts_yunxi.py`, default Yunxi + voice presets); `tryworld-paper/scripts/check_prose.py` needs no third-party packages.
 - **Node.js >= 22 + HyperFrames** — rendering (`npx hyperframes render` / `lint` / `validate` / `inspect`).
 - **FFmpeg** (with ffprobe, on PATH) — audio processing.

README.zh-CN.md

@@ -317,14 +317,14 @@ python tryworld-paper/scripts/tts_yunxi.py script.txt --out work/audio --voice x
 
 成片之前，每一版口播稿与平台标题都要过一道机器门禁——**禁的是修辞动作，不是字面**。换一套字做同一个动作，仍然算命中。
 
-- **翻案腔**：先立读者没有的误解再推翻抬价。已知外衣不限于「不是……而是……」「并非……而是……」「不在于……而在于……」「表面……实际……」「看似……实则……」「你以为……其实……」「回头才发现」「说到底」「答案恰恰相反」，判断从正面下，先给判断再给依据。
-- **同构排比**：三项以上整齐排比，两项为限。
-- **抒情借喻**：不给抽象名词配具体动词（「时间保管细节」类），写具体事物不受影响。
-- **动词名词化**：「实现了效率的提升」还原成「快了多少、省了几个人」。
-- **标点分级**：破折号全禁；冒号只允许引出人物直接原话。
-- **黑话两档**：绝对禁词 + 语境判断词，清单由检测器维护。
+禁项（翻案腔、同构排比、抒情借喻、动词名词化、标点分级、硬停词、模型路标、黑话两档）只在两处定义，避免多份拷贝互相漂移：
 
-检测器 `tryworld-paper/scripts/check_prose.py`（源自 [human-writing](https://github.com/KKKKhazix/human-writing) v1.1.0，MIT）自动执行以上检查，并额外给出统计层提示——句长变异系数、连词密度、模型偏爱抒情词、「」金句密度。**硬禁项清零才允许进入用户确认闸门，失败不交付。**
+| 来源 | 内容 |
+|---|---|
+| `skills/tryworld-paper/references/workflow.md` §1.2.1 第 5 条 | 改稿规则与动作级定义 |
+| `skills/tryworld-paper/scripts/check_prose.py` | 执行检测的脚本——绝对禁词 + 语境判断词，并给出统计层提示（句长变异系数、连词密度、模型偏爱抒情词、「」金句密度） |
+
+措辞不一致时以 `check_prose.py`（源自 [human-writing](https://github.com/KKKKhazix/human-writing) v1.1.0，MIT）为准。**硬禁项清零才允许进入用户确认闸门，失败不交付。**
 
 ---
 
@@ -363,14 +363,14 @@ Copy-Item -Path .\skills\tryworld-paper -Destination "$env:USERPROFILE\.agents\s
 ### 仓库内检查脚本
 
 - `python -X utf8 scripts/check_skills.py`：编译技能 Python 脚本，并对 `examples/` 的口播稿与标题跑活人感门禁
-- `python -m pytest tests/ -v`：运行 23 个单元测试（check_prose、verify_output、tts_yunxi、check_skills）。
+- `python -m pytest tests/ -v`：运行单元测试（check_prose、verify_output、tts_yunxi、check_skills、fetch_aihot、pipeline runner），覆盖 `examples/` 下的脚本与标题。测试数量会随新增用例变化，请用 `python -m pytest tests/ --collect-only -q` 读取实际数量，本文档不再硬编码数字。
 - `python scripts/doctor.py`：检查 Python、Node、FFmpeg/ffprobe、edge-tts、HyperFrames 与可选邮件凭证。缺失必需项时退出码为 1。
 
 ### 环境要求
 
 运行 `npx hyperframes doctor` 可一键检查环境。这些技能按试界自己的工作流定制，默认假设如下——全部都可以在技能文件里自行调整：
 
-- **跨平台**——拉取数据（tryworld-topics）与发通知邮件（tryworld-koubo）的脚本均为 Python（同时保留 `.ps1` 回退版本）；`tryworld-topics` 的 `references/` 里提供了 curl 替代。
+- **跨平台**——拉取数据（tryworld-topics）与发通知邮件（tryworld-koubo）的脚本均为 Python（`.py` 为规范路径；`.ps1` 回退版本保留但已弃用，文件头有 DEPRECATED 声明）；`tryworld-topics` 的 `references/` 里提供了 curl 替代。
 - **Python 3.10+**——`pip install edge-tts` 用于配音管线（`tryworld-paper/scripts/tts_yunxi.py`，默认云希、内置多音色预设）；`tryworld-paper/scripts/check_prose.py` 无需第三方包。
 - **Node.js >= 22 + HyperFrames**——渲染（`npx hyperframes render` / `lint` / `validate` / `inspect`）。
 - **FFmpeg**（含 ffprobe，加入 PATH）——音频处理。