docs: README overhaul — pipeline runner section, repo structure update, fix escaped filenames, sync theme boundary, add content theme example, move Docker into proper section

Author: TryWorld2026

README.md

@@ -69,14 +69,37 @@ That's it. The request is recognized and routed through the whole pipeline autom
 
 **3 · Receive** — the pipeline ends with the rendered video, horizontal/vertical covers, platform titles, captions, a four-platform publish plan, and an automatic email notice.
 
-**Check your setup** — run `python -X utf8 scripts/check_skills.py` (should output `All checks passed`) and `python scripts/doctor\.py` (lists missing tools, cross-platform) before producing your first video. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute, [CHANGELOG.md](CHANGELOG.md) for recent changes, and the [Code of Conduct](CODE_OF_CONDUCT.md).
+**Check your setup** — run `python -X utf8 scripts/check_skills.py` (should output `All checks passed`) and `python scripts/doctor.py` (lists missing tools, cross-platform) before producing your first video. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute, [CHANGELOG.md](CHANGELOG.md) for recent changes, and the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ---
 
+
+### Pipeline Runner (Optional)
+
+After installation, use the pipeline runner instead of manually executing steps. The runner runs 6 step scripts in order, checks preconditions at each step, and stops on failure:
+
+```bash
+# List all steps
+python -m pipeline.runner --list
+
+# Preview execution plan
+python -m pipeline.runner --dry-run
+
+# Run steps (step 3 confirmation gate requires --confirm to pass)
+python -m pipeline.runner --project-dir <project-dir> --steps 1,2
+
+# Continue after confirmation
+python -m pipeline.runner --project-dir <project-dir> --steps 3,4,5,6
+```
+
+Six steps: `01 optimize` → `02 check_prose` → `03 confirm` (hard gate) → `04 tts` → `05 render` → `06 verify` (hard gate).
+
+---
 ## 📑 Contents
 
 - [What Is This](#-what-is-this)
 - [30-Second Quick Start](#-30-second-quick-start)
+- [Pipeline Runner](#pipeline-runner-optional)
 - [Three Pages · Skill Overview](#-three-pages--skill-overview)
 - [Showcase](#-showcase)
 - [The Voiceover Workflow](#-the-voiceover-workflow)
@@ -219,7 +242,7 @@ All samples above are synthesized with TryWorld's fixed sign-off line, so you he
 
 The default look is the **Paper Algorithm** theme (TryWorld's brand), but all brand values — palette, fonts, seal, platform name, sign-off, cover style, default voice — live in one theme file: `skills/tryworld-paper/themes/paper-algorithm.json`.
 
-Want your own brand on this pipeline? Copy the theme JSON, change the values following `tryworld-paper/references/theme-guide.md`, and ship videos under your name. The pipeline contract is not configurable — confirmation gates, the aliveness-gate check, burned-in captions, and quality checks all stay — only the skin changes. Note the boundary: theming covers the **paper production skill**; koubo's writing methodology and topics' channel positioning still carry TryWorld's editorial voice (adjust their SKILL.md / selection-rules.md for your channel, or wait for a later parameterized release).
+Want your own brand on this pipeline? Copy the theme JSON, change the values following `tryworld-paper/references/theme-guide.md`, and ship videos under your name. The pipeline contract is not configurable — confirmation gates, the aliveness-gate check, burned-in captions, and quality checks all stay — only the skin changes. Content theme (`content-default.json`) defines topic domain, audience, length range, and target platforms — modify this JSON to change domain/brand, SKILL.md references it automatically. Writing methodology is in `tryworld-koubo/references/writing-methodology.md`; set `"writing_rules": "custom"` in the content theme to replace with your own methodology (but the `check_prose.py` hard gate cannot be disabled). The repo includes `test-brand.json` as a complete rebranding example.
 
 ```jsonc
 // themes/your-brand.json (excerpt)
@@ -253,13 +276,13 @@ After installation into `~/.agents/skills`, hosts trigger these by the `descript
 
 1. **Route** — read `tryworld-koubo/SKILL.md`, decide Mode A (user gave a script → optimize & produce) or Mode B (topic request → select → write → produce).
 2. **Environment check** — `node --version` (≥22) · `python --version` (≥3.10) · `python -c "import edge_tts"` · `ffmpeg -version` · `npx hyperframes doctor`. Install or warn on whatever is missing before proceeding.
-3. **Mode B only** — run `python tryworld-topics/scripts/fetch_aihot\.py` (cross-platform) or the curl fallback in its `references/api\.md`, apply `references/selection-rules.md`, produce 3–8 candidate topics.
+3. **Mode B only** — run `python tryworld-topics/scripts/fetch_aihot.py` (cross-platform) or the curl fallback in its `references/api.md`, apply `references/selection-rules.md`, produce 3–8 candidate topics.
 4. **Gate 1 (STOP)** — present the topic list and wait for the user's pick. Do not proceed unasked.
 5. **Write** — follow the writing rules in koubo's SKILL.md (2,500–2,800 chars standard, sources for every datapoint, aliveness rules).
 6. **Polish & gate** — hand over to `tryworld-paper/SKILL.md`: optimize, then run `scripts/check_prose.py` until zero hard violations.
 7. **Gate 2 (STOP)** — show the full polished script + what/why of edits + element mapping + data sources. Wait for explicit confirmation. Never render without it.
 8. **Produce** — read the theme file (`skills/tryworld-paper/themes/paper-algorithm.json`) for all brand values → segment → `scripts/tts_yunxi.py` (voiceover + `sentences.json` timeline) → build HyperFrames compositions per `references/style-system.md` → `npx hyperframes lint` / `validate` / `inspect --strict` all pass → render (draft first, then high) → covers (independent design, never video frames) → titles per `references/titles.md` → everything into `outputs/` + `发布计划.txt`.
-9. **Notify** — run `python tryworld-koubo/scripts/notify_delivery\.py --project-dir <dir>`; missing credentials/node → skip gracefully, never block delivery.
+9. **Notify** — run `python tryworld-koubo/scripts/notify_delivery.py --project-dir <dir>`; missing credentials/node → skip gracefully, never block delivery.
 10. **Verify before delivery (hard gate)** — run `python -X utf8 tryworld-paper/scripts/verify_output.py --dir <outputs>`; every item must PASS (audio track present, durations aligned, both cover sizes, titles, publish plan). A FAIL means fix and re-run — never deliver an unverified outputs folder.
 
 Projects live in their own folder (default convention: `E:\Codex口播视频\<slug>\` with `work/` and `outputs/`).
@@ -341,7 +364,7 @@ A skill fires when the request matches its trigger words — no commands to memo
 
 - `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 scripts/doctor\.py`: checks Python, Node, FFmpeg/ffprobe, edge-tts, HyperFrames, and optional email credentials. Exits 1 when a required item is missing.
+- `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
 
@@ -359,6 +382,20 @@ Each skill folder carries its own `SKILL.md` with the full workflow and where to
 
 ---
 
+
+### Docker One-Shot Environment
+
+Skip all dependency installs with Docker:
+
+```bash
+docker build -t paper-algorithm .
+docker run --rm paper-algorithm
+```
+
+Container includes Node.js 22, FFmpeg, Python 3.12, edge-tts, and mutagen.
+
+---
+
 ## 🗂 Repository Layout
 
 ```text
@@ -402,17 +439,3 @@ This work is licensed under a **Creative Commons Attribution-ShareAlike 4.0 Inte
 ---
 
 <p align="center"><sub>TryWorld · Making AI clear for everyone</sub></p>
-
-### Docker One-Shot Environment
-
-Skip all dependency installs with Docker:
-
-```bash
-docker build -t paper-algorithm .
-docker run --rm paper-algorithm
-```
-
-The container includes Node.js 22, FFmpeg, Python 3.12, edge-tts, and mutagen.
-### Content Theme
-
-Beyond visual themes, this project supports a **content theme** (`skills/tryworld-paper/themes/content-default.json`) that defines topic domain, audience, writing rules, and target platforms. Copy and modify the JSON to rebrand or change domain — no SKILL.md changes needed.

README.zh-CN.md

@@ -73,10 +73,33 @@ Copy-Item -Path .\skills\* -Destination "$env:USERPROFILE\.agents\skills" -Recur
 
 ---
 
+
+### Pipeline Runner（可选）
+
+安装后可以用 pipeline runner 代替手动执行流程。Runner 按编号顺序运行 6 个步骤脚本，每步检查前置条件，失败即停：
+
+```bash
+# 查看所有步骤
+python -m pipeline.runner --list
+
+# 预览执行计划
+python -m pipeline.runner --dry-run
+
+# 执行全部步骤（步骤 3 确认闸门必须加 --confirm 才能通过）
+python -m pipeline.runner --project-dir <项目目录> --steps 1,2
+
+# 确认后继续
+python -m pipeline.runner --project-dir <项目目录> --steps 3,4,5,6
+```
+
+六个步骤：`01 optimize` → `02 check_prose` → `03 confirm`（硬闸门）→ `04 tts` → `05 render` → `06 verify`（硬闸门）。
+
+---
 ## 📑 目录
 
 - [这是什么](#-这是什么)
 - [30 秒上手](#-30-秒上手)
+- [Pipeline Runner](#pipeline-runner可选)
 - [三张纸页 · 技能总览](#-三张纸页--技能总览)
 - [效果展示](#-效果展示)
 - [一条口播工作流](#-一条口播工作流)
@@ -219,7 +242,7 @@ flowchart LR
 
 默认视觉是**纸上算法**主题（试界品牌），但全部品牌值——色板、字体、印章、平台名、签名语、封面风格、默认音色——都集中在一个主题文件里：`skills/tryworld-paper/themes/paper-algorithm.json`。
 
-想在这套流水线上挂你自己的品牌？复制主题 JSON，按 `tryworld-paper/references/theme-guide.md` 改值，就能用你自己的名字出片。流水线契约不可配置——确认闸门、活人感门禁、烧录字幕、质量检查全部保留，换的只是皮。边界说明：主题化当前覆盖 **paper 出片技能**；koubo 的写稿方法论与 topics 的选题定位仍带试界的内容视角（按你自己的频道定位调整其 SKILL.md / selection-rules.md，或等后续参数化版本）。
+想在这套流水线上挂你自己的品牌？复制主题 JSON，按 `tryworld-paper/references/theme-guide.md` 改值，就能用你自己的名字出片。流水线契约不可配置——确认闸门、活人感门禁、烧录字幕、质量检查全部保留，换的只是皮。内容主题（`content-default.json`）定义选题域、受众、字数范围、目标平台——换领域/品牌时修改此 JSON，SKILL.md 自动引用。写稿方法论拆在 `tryworld-koubo/references/writing-methodology.md`，可在内容主题中设置 `"writing_rules": "custom"` 替换为自己的方法论（但 `check_prose.py` 硬门禁不可关闭）。仓库中的 `test-brand.json` 是一个完整的换品牌示例。
 
 ```jsonc
 // themes/your-brand.json（节选）
@@ -253,13 +276,13 @@ flowchart LR
 
 1. **路由**——读 `tryworld-koubo/SKILL.md`，判定模式 A（用户给了稿 → 优化并出片）或模式 B（要选题 → 选题 → 写稿 → 出片）。
 2. **环境自检**——`node --version`（≥22）、`python --version`（≥3.10）、`python -c "import edge_tts"`、`ffmpeg -version`、`npx hyperframes doctor`。缺什么先装或明确告知，再继续。
-3. **仅模式 B**——运行 `python tryworld-topics/scripts/fetch_aihot.py`（跨平台）或其 `references/api\.md` 的 curl 替代，按 `references/selection-rules.md` 产出 3-8 个候选选题。
+3. **仅模式 B**——运行 `python tryworld-topics/scripts/fetch_aihot.py`（跨平台）或其 `references/api.md` 的 curl 替代，按 `references/selection-rules.md` 产出 3-8 个候选选题。
 4. **闸门 1（停下）**——展示选题清单，等用户挑选。未经允许不得继续。
 5. **写稿**——按 koubo SKILL.md 的写稿规范（标准版 2500-2800 字、数据点必须带来源、活人感规则）。
 6. **优化过门禁**——转入 `tryworld-paper/SKILL.md`：优化净化，然后跑 `scripts/check_prose.py` 直到硬禁项清零。
 7. **闸门 2（停下）**——完整展示优化稿 + 修改说明 + 元素落点 + 数据来源。等用户明确确认，未经确认禁止渲染。
 8. **出片**——读主题文件（`skills/tryworld-paper/themes/paper-algorithm.json`）获取全部品牌值 → 分段 → `scripts/tts_yunxi.py` 配音（产 `sentences.json` 时间轴）→ 按 `references/style-system.md` 写 HyperFrames 构图 → `npx hyperframes lint` / `validate` / `inspect --strict` 全部通过 → 渲染（先 draft 后 high）→ 封面（独立设计，禁止截帧）→ 按 `references/titles.md` 出标题 → 全部产物进 `outputs/` + `发布计划.txt`。
-9. **通知**——运行 `python tryworld-koubo/scripts/notify_delivery\.py --project-dir <目录>`；凭证或 node 缺失时脚本自动跳过，不阻塞交付。
+9. **通知**——运行 `python tryworld-koubo/scripts/notify_delivery.py --project-dir <目录>`；凭证或 node 缺失时脚本自动跳过，不阻塞交付。
 10. **交付核验（硬性闸门）**——运行 `python -X utf8 tryworld-paper/scripts/verify_output.py --dir <outputs目录>`；每一项都必须 PASS（音轨存在、时长对齐、双封面尺寸、标题、发布计划）。出现 FAIL 就修复重跑——禁止把未核验的 outputs 文件夹交给用户。
 
 项目各自独立文件夹（默认约定 `E:\Codex口播视频\<slug>\`，内含 `work/` 与 `outputs/`）。
@@ -341,7 +364,7 @@ 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 scripts/doctor\.py`：检查 Python、Node、FFmpeg/ffprobe、edge-tts、HyperFrames 与可选邮件凭证。缺失必需项时退出码为 1。
+- `python scripts/doctor.py`：检查 Python、Node、FFmpeg/ffprobe、edge-tts、HyperFrames 与可选邮件凭证。缺失必需项时退出码为 1。
 
 ### 环境要求
 
@@ -359,6 +382,20 @@ Copy-Item -Path .\skills\tryworld-paper -Destination "$env:USERPROFILE\.agents\s
 
 ---
 
+
+### Docker 一键环境
+
+不想装 Node/Python/FFmpeg？用 Docker 跳过所有依赖安装：
+
+```bash
+docker build -t paper-algorithm .
+docker run --rm paper-algorithm
+```
+
+容器内包含 Node.js 22、FFmpeg、Python 3.12、edge-tts、mutagen。
+
+---
+
 ## 🗂 仓库结构
 
 ```text
@@ -402,32 +439,3 @@ paper-algorithm/
 ---
 
 <p align="center"><sub>试界TryWorld · 持续把 AI 讲清楚 · 让每个普通人都看得懂、用得上</sub></p>
-
-### Docker 一键环境
-
-不想装 Node/Python/FFmpeg？用 Docker 跳过所有依赖安装：
-
-```bash
-docker build -t paper-algorithm .
-docker run --rm paper-algorithm
-```
-
-容器内包含 Node.js 22、FFmpeg、Python 3.12、edge-tts、mutagen。渲染类操作需要额外挂载 GPU（可选）：
-
-```bash
-docker run --rm -v "$(pwd)/output:/app/output" paper-algorithm
-```
-### 内容主题
-
-除视觉主题外，本项目还支持**内容主题**（`skills/tryworld-paper/themes/content-default.json`），用于定义选题域、受众、写稿规范、目标平台等。换品牌或换领域时，复制该 JSON 并修改，无需改 SKILL.md：
-
-```json
-{
-  "domain": "你的领域",
-  "audience": "你的目标受众",
-  "topic_sources": ["rss", "manual"],
-  "topic_rules": "你的选题筛选标准",
-  "platforms": ["你的目标平台"],
-  "topic_dedup_dir": "你的成片目录"
-}
-```