Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: clarify visual and layout sampling (#126)

rponeawa0579c260e180
diff --git a/docs/guide/skill.md b/docs/guide/skill.md
index 7ddb2c7d..bfb2bf8d 100644
--- a/docs/guide/skill.md
+++ b/docs/guide/skill.md
@@ -15,6 +15,30 @@ The important distinction is:
- tools decide whether the written project is legal, wired, covered, measurable and recoverable;
- a visual observer reports differences, but the agent decides whether a report is a real defect.
+## Two extraction rules that keep the checks complementary
+
+This is a central design rule for both `original-authoring` and `reconstruction`:
+
+| Check | What it extracts | What it answers | Why this rule |
+|---|---|---|---|
+| Visual review | One **full clip** at the first appearance of each distinct visual declaration/style change | Does the complete look and motion match the brief (original) or the reference (reconstruction)? | A full clip preserves entrance, movement, exit, transient overlap and appearance changes. Rechecking every caption text or every timestamp would add repetition without adding a new visual declaration. |
+| Mechanical layout | One frame from the **longest stable interval of each `Present`** | In a settled, actually rendered DOM, do content and containers fit and align? | Sampling during motion would report normal animation as overflow or offset. Sampling per `Present` means separate caption Cues/content states are measured independently. |
+
+These rules are deliberately different and must not be swapped. The visual plan does not use the
+longest-stable frame; it reviews the whole clip. `layout_check` does not judge visual similarity; it
+measures the realized composition and returns candidates for the Agent to interpret. Content or time
+extremes are not additional visual-selection rules: a stable overflow is found by the per-`Present`
+layout measurement, while a transient or media-internal problem remains the responsibility of the
+full-clip visual review.
+
+The extraction is shared across the two creation routes. Only the judging basis changes:
+
+```text
+original-authoring: visual clip → compare with brief
+reconstruction: visual clip → compare with reference
+both routes: Present stable frame → measure DOM → Agent judges the candidate
+```
+
## How a request becomes a video
```text
@@ -154,9 +178,10 @@ invalidates affected evidence.
### 6. Creation-route visual review and repair
Original authoring calls `authoring_check`; reconstruction calls `reconstruction_check`. Each command
-reads Source and creates a deterministic review plan. It selects the first appearance of each distinct
-visual declaration and the relevant stable stretch, rather than asking an agent to invent an arbitrary
-render list.
+reads Source and creates a deterministic visual-review plan. It selects one full clip at the first
+appearance of each distinct visual declaration (including each style/declaration change), rather than
+asking an agent to invent an arbitrary render list. The longest-stable-interval sample belongs only to
+the separate hidden-browser `layout_check`, not to this visual review.
For each plan entry:
@@ -204,7 +229,7 @@ edge needed by the Film. It has no reference video, so `brief.json` is the autho
| 5. Write the Script | Split the narration into Segments/Takes and short Cues; assign each shot one job and keep timing semantic. | `script-time.md`, `authoring.md` | `main.svml` contains the complete spoken/text progression and deterministic `estimate:Speech` timing. |
| 6. Wire the project | Author `main.svml`, `recipes.svs`, `build.svrun` and `hypit.runtime.json`; declare each generation, Track, Candidate, satisfaction and Target. | `authoring.md`, `runtime.md` | The Film graph is explicit and reproducible rather than a prompt plus disconnected assets. |
| 7. Prove sources and graph | Run package, Cue, syntax, graph-trace and realized-layout gates. | `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check` | The project is legal, every Track reaches the Film, and browser geometry has been measured before visual review. |
-| 8. Plan the visual review | Ask the route check for the first appearance of each distinct visual declaration and its longest stable stretch. | `authoring_check` | `.hypit/evidence/` records exactly what must be reviewed; the agent does not omit later states or invent a render list. |
+| 8. Plan the visual review | Ask the route check for one full clip at the first appearance of each distinct visual declaration/style change. | `authoring_check` | `.hypit/evidence/` records exactly what must be reviewed; the agent does not omit a style change or invent a render list. The longest stable sample is produced separately by `layout_check`. |
| 9. Render and review | Materialize the planned preview/mock clips, read every entry against the frozen brief, and record findings. | `render_element`, `review_element`, `record_review`, `element-review.md`, `conformance-round.md` | Each visual system has explicit evidence, including text fit, coverage, contrast, motion and geometry. |
| 10. Repair and close | Repair only confirmed issues, rerun affected gates and review entries, then run the final route check. | `layout_accept` when geometry is intentional; `authoring_check` | `final-checked` means no required visual review, graph, package, Cue or layout evidence is stale. |
| 11. Hand off | Create the estimate-timed preview-mock Run, show Studio, disclose cost and Build only after approval. | `preview-mock.md`, `studio-confirmation.md`, `hypit plan/build/status/inspect/get` | Studio sees the live Film graph; the paid Build reuses the checked Run and produces the complete delivery. |
diff --git a/docs/zh/guide/skill.md b/docs/zh/guide/skill.md
index 24fb5df0..9436485f 100644
--- a/docs/zh/guide/skill.md
+++ b/docs/zh/guide/skill.md
@@ -14,6 +14,28 @@ description: Hypit skill 如何把描述或参考视频变成可检查、可恢
- 工具决定项目是否合法、graph 是否接通、布局和证据是否稳定;
- 视觉 observer 只报告差异,是否算问题由 agent 判断。
+## 两条必须先看懂的抽取规则
+
+这是 `original-authoring`(原创制作)和 `reconstruction`(复刻)共用的核心设计:
+
+| 检查 | 抽取什么 | 回答什么问题 | 为什么这样做 |
+|---|---|---|---|
+| 视觉检查 | 每种不同视觉声明/样式变化在首次出现处的一个**完整片段** | 画面和运动是否符合 brief(原创)或参考视频(复刻)? | 完整片段能保留出现、移动、离开、瞬时重叠和外观变化。无需因为每句 caption 内容或每个时间点不同而重复检查。 |
+| 机械布局检查 | 每个 `Present` 的**最长稳定区间中的一帧** | 在真实渲染的稳定 DOM 中,内容和容器是否越界、偏移或重叠? | 动画过程中的偏移是正常运动,不应被误报为布局问题;按 `Present` 分开取样可以分别测量不同 caption Cue/内容状态。 |
+
+这两条规则职责不同,不能互换。视觉计划不使用最长稳定帧,而是检查完整片段;`layout_check`
+不判断视觉相似度,只测量真实 composition 并把结果作为候选交给 Agent。内容极值和时间极值不再
+是额外的视觉选片规则:稳定状态下的越界由逐个 `Present` 的布局测量发现,瞬时运动问题或媒体
+内部的问题仍由完整片段的视觉检查负责。
+
+两条创作路径共用同一套抽取方式,只有判断依据不同:
+
+```text
+原创制作:视觉片段 → 对照 brief
+复刻: 视觉片段 → 对照参考视频
+两者: Present 稳定帧 → 测量 DOM → Agent 判断候选是否真是问题
+```
+
## 用户请求如何变成完整视频
```text
@@ -136,7 +158,7 @@ hypit-reference-video-tools layout_check --run <run>
### 6. 创作路径的视觉检查与修复
-原创制作使用 `authoring_check`,复刻使用 `reconstruction_check`。命令读取 Source,按不同视觉声明的首次出现和最长稳定片段生成确定性检查计划,不让 agent 随意编一份 render 列表。
+原创制作使用 `authoring_check`,复刻使用 `reconstruction_check`。命令读取 Source,按每个不同视觉声明(包括样式/声明变化)的首次出现生成一个完整片段的视觉检查计划,不让 agent 随意编一份 render 列表。最长稳定区间取样只属于另外的隐藏浏览器 `layout_check`,不属于视觉检查。
每个计划项按以下闭环执行:
@@ -176,7 +198,7 @@ environment → brief-frozen → examples/格式/craft 决策
| 5. 写 Script | 把旁白切成 Segment/Take 和短 Cue;每个镜头只承担一个明确任务,时间保持语义化。 | `script-time.md`、`authoring.md` | `main.svml` 包含完整的说话/文字推进和确定性的 `estimate:Speech` 时长。 |
| 6. 接通项目 | 编写 `main.svml`、`recipes.svs`、`build.svrun`、`hypit.runtime.json`;显式声明每个生成、Track、Candidate、satisfy 和 Target。 | `authoring.md`、`runtime.md` | Film graph 是完整、可复现的,不是一个提示词加上一堆互不相连的素材。 |
| 7. 证明 Source 与 graph | 运行包、Cue、语法、graph tracing 和真实布局门禁。 | `validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check` | 项目合法、每条 Track 都能到达 Film,并且在视觉检查前已经测过浏览器布局。 |
-| 8. 生成视觉检查计划 | 让路线检查找出每种不同视觉声明的首次出现和最长稳定区间。 | `authoring_check` | `.hypit/evidence/` 记录必须检查的内容;Agent 不会漏掉状态,也不用手写 render 列表。 |
+| 8. 生成视觉检查计划 | 让路线检查为每种不同视觉声明/样式变化在首次出现处生成一个完整片段。 | `authoring_check` | `.hypit/evidence/` 记录必须检查的内容;Agent 不会漏掉样式变化,也不用手写 render 列表。最长稳定区间由独立的 `layout_check` 取样。 |
| 9. 渲染并检查 | 生成计划中的 preview/mock 片段,逐项对照冻结的 brief,记录发现。 | `render_element`、`review_element`、`record_review`、`element-review.md`、`conformance-round.md` | 每种视觉系统都有证据,覆盖文字适配、画面覆盖、对比度、运动和几何。 |
| 10. 修复并收口 | 只修复确认的问题,重跑受影响门禁和检查项,再运行最终路线检查。 | 有意几何用 `layout_accept`;最终用 `authoring_check` | `final-checked` 表示视觉、graph、包、Cue、布局证据都没有过期。 |
| 11. 交接 | 创建 estimate 时长的 preview-mock Run,打开 Studio,披露费用,获批准后才 Build。 | `preview-mock.md`、`studio-confirmation.md`、`hypit plan/build/status/inspect/get` | Studio 看到的是活的 Film graph;付费 Build 复用已检查的 Run,产出完整交付。 |