docs: 精简 README，命令细节交还 SKILL.md

- 删除「七条命令」执行序列与「命令参考」表（属智能体职责，已完整保留在 SKILL.md） - 「快速开始」改为「视频项目结构」，只交代项目目录与 out/ 产物 - 删去 beats.js 顺序提示与 --keep-frames 提示块 - 「参考思路与姊妹项目」改名「参考项目思路」 - 删除路线图章节与文末作者签名 - 中英同步：README 364→295 行，README.en 390→319 行
2026-09-21 13:30:02 +08:00
1 parent 2581e2c685
commit 273ea4e80f
@@ -37,6 +37,9 @@
  （两者此前都没有被文档记录）。
 - 文档：lint 现在是工作流里的显式阶段，位置在生成字幕之后、渲染之前。
 - 文档：删除对私有客户项目的引用，使技能可以公开发布。
+- 文档：README 精简 —— 移除**面向智能体执行**的七条命令序列与「命令参考」表（这些属于
+  `SKILL.md` 的职责），改为只向使用者交代**视频项目结构**与产物位置；同时删去「路线图」
+  与文末作者签名。-150 行，中文 364→295 行、英文 390→319 行。
 - 许可：风格目录衍生自 Apache-2.0 内容，现已带上完整的来源署名。

 ### 备注
@@ -99,30 +99,10 @@ exception and only reads `.claude/skills/`.)

 ---

-## Quick start
+## Video project layout

-A video takes **seven commands**, all run inside the **video project directory**:
-
-```bash
-PY=<path to your venv python>   # expand to an absolute path when briefing a sub-agent
-SKILL=<skill install directory>
-
-# 0 · scaffold a project (tree + config + theme + both cover templates)
-"$PY" "$SKILL/scripts/new_project.py" ~/videos/sky-blue sky-blue --topic "why the sky is blue"
-cd ~/videos/sky-blue
-# …fill narration.json, fill project.json's order, author one frames/<id>.html per scene…
-
-"$PY" "$SKILL/scripts/tts_build.py"      --project .   # 1 · voiceover
-"$PY" "$SKILL/scripts/timeline_build.py" --project .   # 2 · global timeline
-"$PY" "$SKILL/scripts/subs.py"           --project .   # 3 · subtitles + beats
-"$PY" "$SKILL/scripts/lint_frames.py"    --project .   # 4 · audit frames before rendering
-node    "$SKILL/scripts/render_video.mjs" . --preview 30   # 5 · 30-second draft first
-"$PY" "$SKILL/scripts/qc_check.py"       --project .   # 6 · QC
-node    "$SKILL/scripts/render_video.mjs" .            # 7 · full render
-node    "$SKILL/scripts/cover_build.mjs"  .            #    + both covers
-```
-
-Output lands in `out/`: `slug.mp4`, `cover_169.png`, `cover_34.png`, `slug.srt`, `slug.vtt`, plus
+Say one sentence and the agent walks the whole pipeline inside a **video project directory**;
+output lands in `out/`: `slug.mp4`, `cover_169.png`, `cover_34.png`, `slug.srt`, `slug.vtt`, plus
 `qc_report.md` and `qc_sheet.jpg`.

 A **video project** looks like this:
@@ -137,12 +117,6 @@ my-video/
 └── out/              # MP4, covers, SRT/VTT, QC report
 ```

-The order matters: `beats.js` is derived from the TTS output. That is why, after you edit the
-narration, everything downstream re-times automatically while no scene code changes.
-
-> **If you plan to reuse the rendered PNGs, always pass `--keep-frames`.** Preview mode clears the
-> frame directory after muxing by design.
-
 ---

 ## Why not screen recording
@@ -203,30 +177,6 @@ flowchart LR

 ---

-## Command reference
-
-| Command | Purpose |
-|---|---|
-| `new_project.py <dir> <slug> --topic "..."` | Scaffold a project |
-| `tts_build.py --project .` | Synthesise voiceover (caching, timeouts, backoff retries, silence trim) |
-| `timeline_build.py --project .` | Global timeline + stitched `narration-full.mp3` |
-| `subs.py --project .` | Three subtitle outputs + one `beats.js` per scene |
-| `lint_frames.py --project .` | Audit frames against the eight contract rules |
-| `render_video.mjs <dir>` | Render and mux the MP4 |
-| `qc_check.py --project .` | Loudness / duration / stream checks + contact sheet |
-| `cover_build.mjs <dir>` | Render both covers, 2× by default |
-
-Common optional flags: `--preview N` renders only the first N seconds, `--keep-frames` keeps the
-frame PNGs, `--only id,id` audits just the named scenes, `--scale N` sets the output multiplier.
-
-A few handy extras: `peek_frame.mjs <dir> <id>` (screenshot one scene in seconds — the one you
-reach for while designing), `make_theme.py --topic "medical" --use` (derive a palette from a topic
-word), `package_skill.py` (build a portable zip).
-
-**Full flag reference is in [`SKILL.md`](SKILL.md), or pass `--help` to any script.**
-
---
-
 ## The `B()` beat system

 `subs.py` emits one `beats.js` per scene, exposing each subtitle block by its **source text**, so
@@ -319,7 +269,7 @@ authoring model — that is the domain of the sibling project

 ---

-## Prior work and sibling projects
+## Reference project ideas

 `html-explainer` did not invent its methodology. It has two clear sources of ideas. Both are
 **independent projects by different authors — not the same author as this one**, and this
@@ -350,16 +300,6 @@ you want frame-level reproducibility, use this one.

 ---

-## Roadmap
-
- [ ] Per-scene render switch (`--only <id>`) — today this needs the temporary-project workaround
- [ ] Cover layout measurement tool (line count / margins / overlap / hook font size in one pass)
- [ ] More cover aspect ratios
- [ ] English descriptions in the style catalogue
- [ ] Optional music bed with automatic ducking under narration
-
---
-
 ## Contributing

 Issues and PRs are welcome. The most valuable contribution is a **diagnosed silent failure** added
@@ -377,14 +317,3 @@ MIT covers the original code and documentation. Bundled third-party components a
 style specifications remain under their own terms; GSAP is bundled under GreenSock's
 [standard "no charge" licence](https://gsap.com/standard-license). Full notices are in
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) (Chinese).
-
---
-
-<div align="center">
-
-**Author: Moh**
-
-Built because "edit one sentence, then re-align the entire video by hand" is not a good way to
-spend an afternoon.
-
-</div>
@@ -95,33 +95,13 @@ Windows 上 `~` 就是 `C:\Users\<你的用户名>`。

 ---

-## 快速开始
+## 视频项目结构

-一条视频由**七条命令**跑完，都在**视频项目目录**里执行：
+说一句需求，智能体会在一个**视频项目目录**里走完整个流水线；产物落在 `out/`：
+`slug.mp4`、`cover_169.png`、`cover_34.png`、`slug.srt`、`slug.vtt`，外加 `qc_report.md`
+与 `qc_sheet.jpg`。

-```bash
-PY=<你的 venv python 路径>     # 派给子智能体时要展开成绝对路径
-SKILL=<技能安装目录>
-
-# 0 · 建项目脚手架（目录树 + 配置 + 主题 + 两份封面模板）
-"$PY" "$SKILL/scripts/new_project.py" ~/videos/sky-blue sky-blue --topic "为什么天空是蓝色的"
-cd ~/videos/sky-blue
-# …填 narration.json、填 project.json 的 order、为每个场景写一个 frames/<id>.html…
-
-"$PY" "$SKILL/scripts/tts_build.py"      --project .   # 1 · 配音
-"$PY" "$SKILL/scripts/timeline_build.py" --project .   # 2 · 全局时间轴
-"$PY" "$SKILL/scripts/subs.py"           --project .   # 3 · 字幕 + 节拍
-"$PY" "$SKILL/scripts/lint_frames.py"    --project .   # 4 · 渲染前体检画面
-node    "$SKILL/scripts/render_video.mjs" . --preview 30   # 5 · 先出 30 秒样片
-"$PY" "$SKILL/scripts/qc_check.py"       --project .   # 6 · QC
-node    "$SKILL/scripts/render_video.mjs" .            # 7 · 全片渲染
-node    "$SKILL/scripts/cover_build.mjs"  .            #    + 封面双方案
-```
-
-产物都在 `out/`：`slug.mp4`、`cover_169.png`、`cover_34.png`、`slug.srt`、`slug.vtt`，
-外加 `qc_report.md` 与 `qc_sheet.jpg`。
-
-**视频项目**长这样：
+项目目录长这样：

 ```
 my-video/
@@ -133,12 +113,6 @@ my-video/
 └── out/              # MP4、封面、SRT/VTT、QC 报告
 ```

-顺序不能乱：`beats.js` 由 TTS 产出推导而来。这就是为什么改了解说词之后，下游全部自动重排
-时序，而画面代码一行都不用动。
-
-> **只要打算复用渲出来的 PNG，就一定要加 `--keep-frames`。** 预览模式在合成后会按设计
-> 清空帧目录。
-
 ---

 ## 为什么不用录屏
@@ -195,29 +169,6 @@ flowchart LR

 ---

-## 命令参考
-
-| 命令 | 作用 |
-|---|---|
-| `new_project.py <dir> <slug> --topic "主题"` | 建项目脚手架 |
-| `tts_build.py --project .` | 合成配音（带缓存、超时、退避重试、裁静音） |
-| `timeline_build.py --project .` | 全局时间轴 + 拼接 `narration-full.mp3` |
-| `subs.py --project .` | 字幕三出口 + 每场景 `beats.js` |
-| `lint_frames.py --project .` | 按八条契约静态体检画面帧 |
-| `render_video.mjs <dir>` | 渲染并合成 MP4 |
-| `qc_check.py --project .` | 响度 / 时长 / 流体检 + 抽帧速览图 |
-| `cover_build.mjs <dir>` | 渲染封面双方案，默认 2 倍图 |
-
-常用可选参数：`--preview N` 只渲前 N 秒样片、`--keep-frames` 保留帧 PNG、
-`--only id,id` 只体检指定场景、`--scale N` 输出倍率。
-
-另有几个顺手的小工具：`peek_frame.mjs <dir> <id>`（单场景秒级截图，改画面时最常用）、
-`make_theme.py --topic "医疗" --use`（按主题词推配色）、`package_skill.py`（打成可移植 zip）。
-
-**完整参数表见 [`SKILL.md`](SKILL.md)，或对任一脚本加 `--help`。**
-
---
-
 ## `B()` 节拍系统

 `subs.py` 为每个场景生成一份 `beats.js`，把每块字幕按**原文**暴露出来，于是画面动画可以直接
@@ -302,7 +253,7 @@ tl.fromTo('.verdict', { scale: 0.8 },          { scale: 1, duration: 0.6 },

 ---

-## 参考思路与姊妹项目
+## 参考项目思路

 `html-explainer` 的方法论不是凭空来的。它有两处明确的思想来源，两个项目都**由不同作者独立
 开发，与本项目不是同一作者**；本仓库不打包、运行时不依赖它们的任何代码 —— 吸收的是设计规范
@@ -327,16 +278,6 @@ tl.fromTo('.verdict', { scale: 0.8 },          { scale: 1, duration: 0.6 },

 ---

-## 路线图
-
- [ ] 单场景渲染开关（`--only <id>`）—— 目前需要临时项目法绕过
- [ ] 封面排版终态测量器（行数 / 四边边距 / 元素重叠 / 钩子字号一次判完）
- [ ] 更多封面比例
- [ ] 风格目录补英文说明
- [ ] 可选背景音乐轨，并对解说自动做闪避（ducking）
-
---
-
 ## 参与贡献

 欢迎提 issue 和 PR。最有价值的贡献，是一条**已被定位的静默失败**，加进
@@ -352,13 +293,3 @@ tl.fromTo('.verdict', { scale: 0.8 },          { scale: 1, duration: 0.6 },
 MIT 覆盖原创代码与文档。第三方组件与衍生出的风格规范仍适用其各自的条款；GSAP 按 GreenSock
 的 [standard "no charge" 许可](https://gsap.com/standard-license) 内置。完整声明见
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
-
---
-
-<div align="center">
-
-**作者：Moh**
-
-做这个项目，是因为「改一句话然后把整片手工重新对位一遍」实在不是一种好的过下午的方式。
-
-</div>