Skip to content

Commit ca69516

Browse files
committed
feat(delivery-video): ship feedback report videos (1.1.1)
Sync the full plugin payload with the 1.1.1 source: feedback episodes with severity/phase badges, a repro panel, feedback.json and a generated markdown report bound to the artifact SHA256.
1 parent 37ee64c commit ca69516

13 files changed

Lines changed: 506 additions & 18 deletions

File tree

‎external_plugins/delivery-video/.zcode-plugin/plugin.json‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
{
22
"name": "delivery-video",
3-
"version": "1.0.6",
4-
"description": "Record, render and gate trustworthy delivery demo videos of real, working software — real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate.",
3+
"version": "1.1.1",
4+
"description": "Record, render and gate trustworthy delivery demo videos — or defect/feedback report videos — of real, working software: real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate.",
55
"description_i18n": {
6-
"en": "Record, render and gate trustworthy delivery demo videos of real, working software — real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate.",
7-
"zh-CN": "把真实运行的功能录成可交付的演示视频:真实录屏、edge-tts 旁白、逐字对齐字幕与确定性质量闸,产出到 1920x1080 成片与完整证据链。"
6+
"en": "Record, render and gate trustworthy delivery demo videos — or defect/feedback report videos — of real, working software: real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate.",
7+
"zh-CN": "把真实运行的功能录成可交付的演示视频,或把缺陷录成可追溯的问题反馈视频:真实录屏、edge-tts 旁白、逐字对齐字幕与确定性质量闸,产出 1920x1080 成片与完整证据链。"
88
},
99
"author": {
1010
"name": "Lumos-789",
@@ -16,6 +16,7 @@
1616
"keywords": [
1717
"delivery",
1818
"demo-video",
19+
"bug-report",
1920
"screen-recording",
2021
"acceptance",
2122
"quality-gate",

‎external_plugins/delivery-video/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ In DeepSeek Harness, the skill is registered in both the Host and each live Agen
1111
1. **Verify first, record second** — the workflow requires evidence that the current version really runs (git SHA, tickets, request IDs) before any recording.
1212
2. **Case-driven structure (recommended)** — for multi-case deliveries the skill suggests listing the acceptance cases first, recording one real run per case, then assembling segments in execution order with a result shot per case. Optional, not a gate.
1313
3. **episode.json recipe** — each segment binds one real take + time range + one narration line + optional crop/case chip.
14+
Set `intent: "feedback"` with an `issue` block to produce a defect report instead of a
15+
delivery: severity and phase chips, a repro-steps overlay, and both `feedback.json` and a
16+
ticket-ready `feedback.generated.md` bound to the artifact SHA256. The same quality gate
17+
applies.
1418
4. **Self-contained renderer** — `render.py` synthesizes narration via edge-tts (word-boundary clocks), times each segment to its narration (0.3x–3x speed clamp), draws the label chip and word-synced subtitles, concatenates, loudness-normalizes to −14 LUFS, and runs the built-in quality gate. Output: `screen_demo.mp4` (1920×1080, 30fps, h264+AAC), `timeline.json`, cover/preview frames, `quality_gate/report.json`.
1519
5. **Fail-loud checks** — `preflight.py` validates the recipe before rendering (structure, intervals, crops, browser-recording evidence, TTS cache contracts, narration red lines); `verify_delivery.py` verifies the finished artifact, gate binding and optional independent visual review afterwards.
1620
6. **Attachment gate** — `render.py gate` runs the same hard checks on any mp4 before it goes into a ticket, chat or customer channel.

‎external_plugins/delivery-video/README_CN.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
1. **先验真,再录**——工作流要求先有当前版本真实跑通的版本证据(git SHA、工单、请求 ID),才允许录制。
1212
2. **按用例组织(推荐)**——多 case 交付时,建议先拆一张用例清单,再一个 case 一次真实运行录制,最后按执行顺序拼镜头,每个 case 以自己的结果回读收尾。属使用建议,不做强制校验。
1313
3. **episode.json 配方**——每个镜头绑定一段真实原片 + 时间区间 + 一句旁白 + 可选裁切/case 徽标。
14+
写 `intent: "feedback"` 并添加 `issue` 块即可产出问题反馈视频:严重级别与阶段徽标、
15+
复现步骤浮层、复现/现象镜头,以及按成片 SHA256 绑定的 `feedback.json` 和可直接贴工单的
16+
`feedback.generated.md`,质量闸规则不变。
1417
4. **自包含渲染器**——`render.py` 用 edge-tts 合成旁白(逐字时间钟),按旁白时长配速每个镜头(0.3x–3x 变速钳制),绘制标签徽标与逐字同步字幕,拼接、响度归一到 −14 LUFS,并自动跑内置质量闸。输出:`screen_demo.mp4`(1920×1080、30fps、h264+AAC)、`timeline.json`、封面/预览帧、`quality_gate/report.json`。
1518
5. **Fail-loud 检查**——`preflight.py` 渲染前校验配方(结构、区间、裁切、浏览器录屏证据、TTS 缓存契约、旁白红线);`verify_delivery.py` 渲染后核验成片、闸绑定与可选的独立视觉复核。
1619
6. **附件闸**——`render.py gate` 对任意 mp4 跑同一套硬检查,贴进工单、群聊或客户渠道之前必须过。
-1.03 KB
Loading
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"voice": "zh-CN-YunxiNeural",
3+
"rate": "+5%",
4+
"title": "Bug report - order total stays stale",
5+
"intent": "feedback",
6+
"issue": {
7+
"id": "BUG-123",
8+
"title": "Saving the amount keeps the old total in the list",
9+
"severity": "major",
10+
"environment": "staging / build <version>",
11+
"expected": "The list shows the new total right after saving.",
12+
"actual": "The list still shows the old total until the page is fully reloaded.",
13+
"repro": [
14+
"Open the order detail page",
15+
"Change the amount to 1200 and save",
16+
"Return to the order list and read the total"
17+
]
18+
},
19+
"segments": [
20+
{
21+
"id": "01-repro",
22+
"phase": "repro",
23+
"label": "复现",
24+
"shot": "take-01.mp4",
25+
"start": 0.5,
26+
"end": 12.0,
27+
"text": "照着三个步骤操作,保存后返回列表。"
28+
},
29+
{
30+
"id": "02-actual",
31+
"phase": "actual",
32+
"label": "现象",
33+
"shot": "take-02.mp4",
34+
"start": 0.5,
35+
"end": 9.0,
36+
"text": "列表这里仍然是旧总额,和刚才保存的数值对不上。"
37+
}
38+
]
39+
}

‎external_plugins/delivery-video/package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "delivery-video",
3-
"version": "1.0.6",
4-
"description": "Turn a feature that actually runs into a trustworthy delivery demo video: real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate (ffmpeg-based, self-contained pipeline).",
3+
"version": "1.1.1",
4+
"description": "Turn a feature that actually runs into a trustworthy delivery demo video, or a defect into a traceable feedback video: real screen recordings, edge-tts narration, word-synced subtitles and a deterministic quality gate (ffmpeg-based, self-contained pipeline).",
55
"type": "module",
66
"main": "index.js",
77
"scripts": {
@@ -42,6 +42,7 @@
4242
"dsh-plugin",
4343
"delivery",
4444
"demo-video",
45+
"bug-report",
4546
"screen-recording",
4647
"quality-gate",
4748
"edge-tts",

‎external_plugins/delivery-video/skills/delivery-video/SKILL.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: delivery-video
3-
description: Produce trustworthy delivery/acceptance demo videos of real, working software — recorded from actual screen sessions with narration, subtitles and a deterministic quality gate. Use when the user says "record a delivery video", "make a feature demo", "acceptance demo video", "录交付视频", "录个演示", "功能演示", "验收演示视频", "给客户看的功能 demo". Renders real recordings only — no static screenshots, mocks or old footage stitched into a "demo".
3+
description: Produce trustworthy delivery/acceptance demo videos — or defect/feedback report videos — from real screen recordings with narration, subtitles and a deterministic quality gate. Use when the user says "record a delivery video", "make a feature demo", "acceptance demo video", "bug report video", "record the defect", "录交付视频", "录个演示", "功能演示", "验收演示视频", "问题反馈视频", "缺陷复现视频", "把 bug 录下来". Renders real recordings only — no static screenshots, mocks or old footage stitched into a video.
44
metadata:
55
short-description: Record, render and gate trustworthy delivery demo videos
66
---
@@ -37,6 +37,8 @@ A delivery is done only when all of these hold:
3737

3838
A passing gate is not the user's acceptance. Posting to a ticket or group is a delivery action — do it only when the user asks in that turn; public upload or publishing waits for an explicit "send".
3939

40+
For an `intent: "feedback"` episode the same evidence rules apply, but the result state is the **defect still being reproduced**: the last segment must show the wrong behaviour or its explicit impact, never a fix that was not actually proven.
41+
4042
## Workflow
4143

4244
### 1. Define what this demo must prove
@@ -167,11 +169,48 @@ In the target project (not inside this skill) write `delivery.md`: environment &
167169

168170
Reply with the conclusion first, then the artifact path, duration, gate result, SHA256 and the unproven items. Never just "the video is done".
169171

172+
## Feedback mode (defect evidence)
173+
174+
The same renderer and gate also produce bug/feedback videos. Set `intent: "feedback"` and add an `issue` block; delivery episodes stay unchanged when the fields are absent.
175+
176+
```json
177+
{
178+
"intent": "feedback",
179+
"voice": "zh-CN-YunxiNeural",
180+
"issue": {
181+
"id": "BUG-123",
182+
"title": "保存金额后列表仍显示旧总额",
183+
"severity": "major",
184+
"environment": "staging / build <version>",
185+
"expected": "保存后列表立即显示新的总额",
186+
"actual": "返回列表仍显示旧总额,必须整页刷新才更新",
187+
"repro": ["打开订单详情", "把金额改为 1200", "保存并返回列表"]
188+
},
189+
"segments": [
190+
{"id": "01-repro", "phase": "repro", "label": "复现", "shot": "take-01.mp4",
191+
"start": 0.5, "end": 12.0, "text": "照着三个步骤操作,保存后回到列表。"},
192+
{"id": "02-actual", "phase": "actual", "label": "现象", "shot": "take-01.mp4",
193+
"start": 12.0, "end": 20.0, "text": "列表这里仍然是旧总额,和刚才保存的数值对不上。"}
194+
]
195+
}
196+
```
197+
198+
Rules:
199+
200+
- `issue.title`, `issue.severity`, `issue.expected`, `issue.actual` are required. `severity` is one of `blocker`, `critical`, `major`, `minor`. `id`, `environment` and `repro` are optional.
201+
- At least one segment must carry `phase: "actual"`. Allowed phases: `context`, `repro`, `actual`, `expected`, `impact`.
202+
- The severity becomes the first on-screen chip and the phase the second, so a viewer can tell repro from symptom without narration.
203+
- During `phase: "repro"` segments the renderer overlays the first five `issue.repro` steps in the top-right. Keep steps short; the full list stays in the generated report.
204+
- A feedback video reports what the current build does. Do not mix in footage from an older build, do not claim a fix, and do not hide a passing case to make the defect look worse.
205+
- `render.py` writes `feedback.json` (issue, segment phases, artifact SHA256) and `feedback.generated.md` — a ticket-ready draft with expected/actual, numbered repro steps, per-segment source ranges and the gate result. `verify_delivery.py` fails a feedback episode whose JSON report is missing or bound to another file.
206+
- `feedback.generated.md` is overwritten on every render. Treat it as the source for the ticket; add impact and business context in a separate note or edit a copy, do not hand-edit the generated file.
207+
170208
## Common shapes
171209

172210
- Web/desktop UI: window-level recording cropped to the content area; controls, feedback and read-back all in frame.
173211
- CLI/API: dedicated terminal recording real commands and real responses; mask tokens, internal hosts and debug logs.
174212
- Multi-case acceptance (recommended for 2+ cases): one real run per case, one result segment per case; the `case` field becomes the chip, and narration covers only that case's delta and result.
213+
- Defect report: one continuous take that reproduces the problem, with `phase` segments for repro and actual; the `expected` state can be one narration line or a separate real segment when an earlier build is legitimately available.
175214
- No visual UI: show real API responses, logs or data — never fabricate a fake UI to stand in for the product.
176215
- Engineering acceptance: terminal and evidence frames are fine, but lead with the business conclusion.
177216

‎external_plugins/delivery-video/skills/delivery-video/references/episode-and-review.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,12 @@
99
| `voice` | yes | edge-tts voice, e.g. `zh-CN-YunxiNeural`, `en-US-AndrewNeural` |
1010
| `rate` | no | speech rate, default `+5%`, format `+N%` or `-N%` |
1111
| `title` | no | internal identification only |
12+
| `intent` | no | `delivery` (default) or `feedback`; feedback requires the `issue` block |
13+
| `issue` | for feedback | defect report metadata, see below |
1214
| `segments` | yes | non-empty array, unique `id`s |
1315
| `segments[].id` | yes | ASCII id, e.g. `01-entry` |
1416
| `segments[].case` | no | acceptance-case chip shown top-left, e.g. `D-02`; recommended when the video covers 2+ cases |
17+
| `segments[].phase` | for feedback | `context`, `repro`, `actual`, `expected` or `impact`; becomes the second chip |
1518
| `segments[].label` | yes | short top-left label, 2–10 chars |
1619
| `segments[].shot` | yes | recording file relative to the build directory |
1720
| `segments[].start` | yes | range start in the source, seconds |
@@ -20,6 +23,39 @@
2023
| `segments[].crop` | no | `[x, y, w, h]` in source pixels, default `[260, 64, 1340, 780]` |
2124
| `segments[].text` | yes | one continuous narration line, no newlines; subtitles auto-break at punctuation |
2225

26+
### Feedback issues
27+
28+
`intent: "feedback"` turns the artifact into a defect report while keeping the same recording and gate rules.
29+
30+
| Field | Required | Notes |
31+
| --- | --- | --- |
32+
| `issue.title` | yes | one sentence naming the wrong behaviour |
33+
| `issue.severity` | yes | `blocker`, `critical`, `major` or `minor` |
34+
| `issue.expected` | yes | what a correct build must show |
35+
| `issue.actual` | yes | what this build actually shows |
36+
| `issue.id` | no | ticket or case id |
37+
| `issue.environment` | no | build, environment, account or data |
38+
| `issue.repro` | no | up to 12 steps, one string per step |
39+
40+
At least one segment must use `phase: "actual"`. `render.py` writes `feedback.json` with the
41+
issue, the segment phases and the artifact SHA256; `verify_delivery.py` treats a missing or
42+
misbound report as a failure. Delivery episodes without `intent` keep the original contract.
43+
44+
During `phase: "repro"` segments the renderer also draws the first five `issue.repro` steps in
45+
the top-right corner; the full list stays in the generated markdown. A `phase` on a delivery
46+
episode is rejected, so the two modes cannot be mixed by accident.
47+
48+
### Generated feedback files
49+
50+
| File | Contents |
51+
| --- | --- |
52+
| `feedback.json` | machine-readable issue, segment phases and artifact SHA256; bound to the gate report |
53+
| `feedback.generated.md` | ticket-ready draft: expected/actual, numbered repro steps, per-segment in-video timing and source range, artifact hash and gate result |
54+
55+
`feedback.generated.md` is rewritten on every render — edit a copy or keep additions in a
56+
separate note. The draft deliberately does not claim a fix, a root cause or coverage of other
57+
environments.
58+
2359
### Case list (recommended, not enforced)
2460

2561
For a multi-case delivery, note the cases before recording and reuse the same ids everywhere (take names, `episode.json`, the delivery note). Keep this list in the target project with its build directory and delivery note; the plugin itself stays self-contained. A background block plus a compact table is enough:

‎external_plugins/delivery-video/skills/delivery-video/scripts/preflight.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
INTERNAL_TERMS,
4040
RenderError,
4141
check_edge_tts_version,
42+
feedback_errors,
4243
font_path,
4344
)
4445

@@ -478,6 +479,7 @@ def main() -> int:
478479
tts_voice, tts_rate, errors):
479480
tts_missing.append(prefix)
480481

482+
errors.extend(feedback_errors(episode, segments))
481483
if texts:
482484
check_redline(texts, errors, warnings)
483485
if tts_missing:

0 commit comments

Comments
 (0)