@zenaigc/zenmcp 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/INSTALL.md +114 -102
  2. package/dist/src/assets/index.js +1 -1
  3. package/dist/src/assets/model-library.js +157 -16
  4. package/dist/src/core/schema.js +1 -0
  5. package/dist/src/doctor.js +0 -0
  6. package/dist/src/effects/index.js +54 -13
  7. package/dist/src/engine/card.js +5 -2
  8. package/dist/src/engine/direct.js +2 -0
  9. package/dist/src/engine/generate.js +15 -2
  10. package/dist/src/engine/steps.js +84 -9
  11. package/dist/src/inspect/index.js +51 -12
  12. package/dist/src/mcp/guidance.js +1 -1
  13. package/dist/src/mcp/server.js +247 -19
  14. package/dist/src/timeline/conform.js +19 -5
  15. package/dist/src/timeline/cuts.js +13 -13
  16. package/dist/src/timeline/diff.js +25 -7
  17. package/dist/src/timeline/index.js +2 -2
  18. package/dist/templates/pop-title/render.js +28 -8
  19. package/package.json +1 -1
  20. package/skills/zenmcp/SKILL.md +77 -46
  21. package/skills/zenmcp/references/00-model-card.md +165 -0
  22. package/skills/zenmcp/references/01-dissect-and-checkpoints.md +68 -0
  23. package/skills/zenmcp/references/02-character-and-tryon.md +63 -0
  24. package/skills/zenmcp/references/03-wan3-camera-and-audio.md +43 -0
  25. package/skills/zenmcp/references/04-hyperframes-effects.md +61 -0
  26. package/skills/zenmcp/references/05-interaction-and-media.md +203 -0
  27. package/skills/zenmcp/references/06-work-delivery.md +29 -0
  28. package/skills/zenmcp/scripts/build-contact-sheet.mjs +179 -0
  29. package/skills/zenmcp/scripts/build-dissect-report.mjs +1233 -0
  30. package/skills/zenmcp/scripts/build-height-ruler.mjs +49 -0
  31. package/skills/zenmcp/scripts/build-side-by-side.mjs +56 -0
  32. package/skills/zenmcp/widgets/fixtures/zenmcp-budget-confirm.readonly.json +31 -0
  33. package/skills/zenmcp/widgets/zenmcp-account/template.json +1 -1
  34. package/skills/zenmcp/widgets/zenmcp-account/widget.html +8 -10
  35. package/skills/zenmcp/widgets/zenmcp-budget-confirm/template.json +5 -2
  36. package/skills/zenmcp/widgets/zenmcp-budget-confirm/widget.html +50 -13
  37. package/skills/zenmcp/widgets/zenmcp-install-checklist/template.json +1 -1
  38. package/skills/zenmcp/widgets/zenmcp-install-checklist/widget.html +18 -12
  39. package/skills/zenmcp/widgets/zenmcp-spend-confirm/template.json +13 -83
  40. package/skills/zenmcp/widgets/zenmcp-spend-confirm/widget.html +88 -65
  41. package/dist/src/setup/targets.js +0 -314
  42. package/skills/zenmcp/widgets/fixtures/zenmcp-asset-roles.json +0 -24
  43. package/skills/zenmcp/widgets/fixtures/zenmcp-model-picker.json +0 -25
  44. package/skills/zenmcp/widgets/fixtures/zenmcp-trim-range.json +0 -19
  45. package/skills/zenmcp/widgets/zenmcp-asset-roles/template.json +0 -54
  46. package/skills/zenmcp/widgets/zenmcp-asset-roles/widget.html +0 -73
  47. package/skills/zenmcp/widgets/zenmcp-model-picker/template.json +0 -31
  48. package/skills/zenmcp/widgets/zenmcp-model-picker/widget.html +0 -28
  49. package/skills/zenmcp/widgets/zenmcp-trim-range/template.json +0 -53
  50. package/skills/zenmcp/widgets/zenmcp-trim-range/widget.html +0 -52
@@ -0,0 +1,61 @@
1
+ # HyperFrames 字幕与贴片三预设规范
2
+
3
+ ## 1. 目标与产出
4
+
5
+ 在不消耗任何云端模型积分的前提下,利用本地确定性渲染器(`PopTitleRenderer` / HyperFrames)为成片叠加呼吸感强、不遮挡人脸与穿搭重点的花字和口播字幕。调整花字文案、字号、颜色或位置均属于 **0 积分本地重跑**。
6
+
7
+ 当前内置三套标准预设(兼容旧版 `pop-title`):
8
+ 1. **`hero-title`(开场醒目大花字)**:字号约占画宽 `8.8%`,默认 `y = 0.12`,粗描边立体阴影,适合无口播卡点视频前 2–6 秒的主题大标题(如「140斤微胖梨形早春穿搭」)。
9
+ 2. **`top-tag`(顶部精巧卖点标签)**:字号约占画宽 `5.0%`,默认 `y = 0.09–0.10`,粗描边居中高亮,专为远近跳切穿搭视频设计,绝不压头顶发丝。
10
+ 3. **`voice-caption`(底部口播字幕条)**:字号约占画宽 `4.6%`,默认 `y = 0.84`(避开底部平台 UI 遮挡区),适合连续长句口播。
11
+
12
+ ## 2. 验收标准
13
+
14
+ - **不压脸、不挡鞋**:`top-tag` 中心 `y` 保持在 `0.08–0.10`(处于人物头顶 `y ≈ 0.18` 上方的留白墙面内);`voice-caption` 中心 `y` 保持在 `0.82–0.85`(不遮挡高跟鞋尖主体,也不掉进抖音底部文案遮挡区)。
15
+ - **重点词一眼抓人**:卖点短句用 `{关键词}` 包裹核心形容词(如 `领口越{利落}`),默认渲染为明黄 `#FFE14D` + 主体白字 `#FFFFFF`,单行控制在 `4–8 个汉字` 以内。
16
+ - **切点时间轴对齐准确**:当前使用整数切点索引 `start_cut` + `end_cut` 对齐各分镜范围(`0` 为片头,`segments.length` 为片尾),确保花字切换与每镜硬切同步。
17
+
18
+ ## 3. 已知的坑
19
+
20
+ - **切勿拿默认大号 `pop-title`(`9.2%` 画宽、`y = 0.52` 居中)铺满全片每镜口播**:大号花字放在画面中上部会像广告牌一样死死糊住模特额头或胸口领口细节;全片逐镜卖点一律改用 `top-tag`(`5.0%` 画宽)或底部 `voice-caption`(`4.6%` 画宽)。
21
+ - **单行字数过长与行数限制**:竖屏 `9:16` 下单行超过 10 个字可能触发宽度溢出校验;`slots.lines` 限 **1–2 个非空字符串**(最多 2 行,如 `lines: ["早秋{一衣多搭}", "8套显瘦公式"]`),长句请拆分为两行或拆成前后两个切点片段。
22
+
23
+ ## 4. 已验证示例
24
+
25
+ 在 `job.storyboard.effects` 中配置开场大花字与逐镜顶部双色高亮卖点胶囊(按切点自动贴合每镜):
26
+
27
+ ```json
28
+ [
29
+ {
30
+ "template": "hero-title",
31
+ "start_cut": 0,
32
+ "end_cut": 2,
33
+ "slots": { "lines": ["早秋{一衣多搭}", "显瘦穿搭公式"] },
34
+ "assets": {},
35
+ "style": {
36
+ "position": { "x": 0.5, "y": 0.12 },
37
+ "color": "#FFFFFF",
38
+ "highlight_color": "#FFE14D"
39
+ }
40
+ },
41
+ {
42
+ "template": "top-tag",
43
+ "start_cut": 0,
44
+ "end_cut": 1,
45
+ "slots": { "lines": ["领口越{利落}"] },
46
+ "assets": {},
47
+ "style": {
48
+ "position": { "x": 0.5, "y": 0.09 },
49
+ "color": "#FFFFFF",
50
+ "highlight_color": "#FFE14D"
51
+ }
52
+ },
53
+ {
54
+ "template": "top-tag",
55
+ "start_cut": 1,
56
+ "end_cut": 2,
57
+ "slots": { "lines": ["裙子越{简洁}越显腿长"] },
58
+ "assets": {}
59
+ }
60
+ ]
61
+ ```
@@ -0,0 +1,203 @@
1
+ # 第一类穿搭视频交互规范、文件存储与会话内媒体预览手册
2
+
3
+ 本手册规定第一类穿搭展示短视频拆解二创(固定机位 + 同场景 + 单模特 + 1–8 套新衣服)的文件存储结构、单一交互面原则、跨智能体提问兼容规则及全流程会话内媒体渲染方式。
4
+
5
+ ---
6
+
7
+ ## 1. 双层存储结构与文件命名规范
8
+
9
+ ### 1.1 本机持久模卡库(跨项目复用)
10
+
11
+ 默认根目录:`~/.config/zenmcp/library/models/<model-id>/`(Windows 为 `%APPDATA%/zenmcp/library/models/<model-id>/`,可通过 `ZENMCP_LIBRARY_DIR` 覆盖)。
12
+
13
+ ```text
14
+ ~/.config/zenmcp/library/models/<model-id>/
15
+ ├── model.json # 指向最新版本的清单
16
+ └── versions/
17
+ └── <v>/
18
+ ├── model.json # 当前版本不可变清单(含各文件 sha256)
19
+ ├── original.<png|jpg|webp> # 用户原始人物参考图
20
+ ├── identity.<png|jpg|webp> # 主身份参考图(通常同 portrait-front)
21
+ ├── preview-sheet.<png|jpg|webp> # 五合一/多图总览预览拼图(可选,推荐必存)
22
+ ├── ref-portrait-front.<ext> # 0° 齐肩正脸定妆照
23
+ ├── ref-portrait-45.<ext> # 45° 斜侧脸定妆照(兼容旧库 ref-portrait-3q)
24
+ ├── ref-body-front-headless.<ext> # 0° 正面去头量体全身照
25
+ ├── ref-body-45-headless.<ext> # 45° 去头量体全身照
26
+ └── ref-body-side-headless.<ext> # 90° 纯侧去头量体全身照
27
+ ```
28
+
29
+ - **扩展名与旧卡零迁移兼容**:新版 `model_library(action: "save")` 按文件头魔数强制校验并保留真实扩展名(`.png` / `.jpg` / `.webp`)。读取旧版无扩展名模卡(如 `model-a-douyin`、`model-b-douyin`、`model-c`)时,`resolvePaths` 在校验 `sha256` 后自动在同目录补齐 `<slot>.<ext>` 硬链接(文件系统不支持硬链接时回退为副本),确保会话内图片渲染器能正常识别格式且不改动原 `model.json`。
30
+ - **模卡命名与 `id` 映射规范(每次新人物做完模卡必问是否入库)**:
31
+ - 持久模卡同时保存**面向用户的中文名称 `name`**(如 `清冷长发女模C`、`小雅`)与**底层安全目录标识 `id`**(满足 `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` 且不含 `..`,如 `model-c`、`xiaoya`)。
32
+ - 每次新人物完成五视图与 `preview-sheet.jpg` 展示验收后,**必须用一次选项式提问确认是否保存到本机持久模卡库(含人像使用授权)**,主动建议一个好记的中文名 + 对应英文/拼音 `id`,并支持用户在补充框自起中文名(由智能体自动生成拼音/英文 `id`);入库后明确回报 `name`、`id` 与存储路径,后续直接报中文名或 `id` 均可检索命中。
33
+ - **取模卡交互分支**:
34
+ 1. **用户点名已有模特**(如“用女模C”、“用轻熟御姐”或报 `id`):调用 `model_library({ action: "get", query: "女模C" })`。
35
+ - `match === "unique"`:直接使用返回的带扩展名路径;若旧卡 `paths.preview` 为 `null`,用 `build-contact-sheet.mjs` 将 `identity` 与 `references` 拼成 `03-model/model-preview.jpg` 供闸门 1 展示。
36
+ - `match === "ambiguous"` 或 `"none"`:用 `@native/image-gallery`(或 `@native/files-previewer`)展示候选模卡的 `previewPath`,再用一次选项式提问让用户单选。
37
+ 2. **用户未指定模特但想从库里选**:调用 `model_library({ action: "list" })`(**注意:查全库时不要传 `query: "模特"`**,因为 `query` 按子串匹配,会漏掉名称为“女模C”等不含“模特”二字的条目)→ 画廊展示各模卡 `previewPath` → 一次选项式提问选定。
38
+ 3. **用户发来新人物照片**:默认推荐「仅本次使用(0 额外积分,原图存入 `03-model/identity.<ext>`)」;仅当用户主动选择「制作持久五图模卡」时才进入 [00-model-card.md](00-model-card.md) 流程,做完五图后按上方规则确认起名并调用 `save(confirmed: true)` 入库。
39
+
40
+ ### 1.2 单次项目工作区目录(单任务全生命周期事实来源)
41
+
42
+ 除非用户明确指定输出目录,单次拆解二创任务统一建在 `<workspace>/zenmcp-projects/<YYYYMMDD>-<slug>/`:
43
+
44
+ ```text
45
+ <workspace>/zenmcp-projects/<YYYYMMDD>-<slug>/
46
+ ├── project.json # 任务总账(模特引用、服装映射、切点、积分记录)
47
+ ├── 01-reference/
48
+ │ ├── source.mp4 # 抓取或考入的原始参考视频
49
+ │ ├── motion-clean.mp4 # 剥离片头闪帧或超长裁剪后的干净动作参考片
50
+ │ ├── analysis.json # 切点帧号、景别上下沿、动作与口播结构化拆解
51
+ │ └── keyframes.jpg # 关键帧总览拼图(build-contact-sheet.mjs 生成)
52
+ ├── 02-garments/
53
+ │ ├── garment-01.png .. garment-08.png # 按顺序编号的目标服装图(或试穿视频抽出的清晰帧)
54
+ │ └── garments-sheet.jpg # 多件衣服/多帧提取总览拼图(带 01..N 编号角标)
55
+ ├── 03-model/
56
+ │ ├── model-preview.jpg # 本次所用模特预览拼图
57
+ │ └── identity.<ext> # 仅单次临时模特存放原图
58
+ ├── 04-tryon/
59
+ │ ├── outfit-01/ .. outfit-08/ # 各套定妆图的独立生成状态目录(严禁混用或重投覆盖)
60
+ │ ├── outfit-01.png .. outfit-08.png # 已通过初检的全身定妆确认图
61
+ │ └── qc/
62
+ │ ├── height-ruler.jpg # 原片最远帧 vs 全套定妆图头脚水平标尺对比图
63
+ │ └── fabric-qc-01.jpg .. # 原衣细节 vs 定妆图上半身面料/领口/妆容 1:1 放大对比图
64
+ ├── 05-video/ # import_assets / plan_job / execute_job 工作目录
65
+ └── 06-output/
66
+ ├── <作品名>-<人物简称>-成片-v02-720P.mp4
67
+ └── <作品名>-<人物简称>-原片对比-v02-720P.mp4
68
+ ```
69
+
70
+ - **`$SUPERONE_SESSION_DIR/agent/` 的职责边界**:仅当智能体运行在远程服务器(如 A 服务器)且桌面端预览本地路径报“文件不存在”时,将需展示的预览图/成片复制一份到 `$SUPERONE_SESSION_DIR/agent/<项目目录名>/` 用于渲染;项目目录始终是唯一执行与续查事实来源。
71
+ - **正式交付规则**:见 [06-work-delivery.md](06-work-delivery.md)。引擎内的 `final.mp4` 不移动;输出中文命名副本,分清待验收与已验收,不覆盖历史版本。
72
+
73
+ ### 1.3 本机可复用结构模板草案目录(预留衔接「从一个模板开始」与后续 DSL)
74
+
75
+ 默认目录:`~/.config/zenmcp/library/templates/<template-id>.json`(`template-id` 同样遵循 `[A-Za-z0-9._-]+` 安全路径段,配中文 `name`)。
76
+ - **触发时机**:当一条「从一条视频开始」的任务在阶段 6 完成交付后,若用户希望将本次跑通的视频节奏沉淀为可复用模板,智能体从当前项目的 `project.json` 与 `01-reference/analysis.json` 中抽离出**与具体人物/服装文件解耦的纯结构骨架**写入该目录。
77
+ - **草案保留字段(面向后续 DSL 平滑演进)**:`id`、`name`、`video_category`(类别、空间机位、口播形态)、`duration_seconds`、`aspect_ratio`、`required_slots`(如 `identity: 1, outfits: 6`)、`segments[]`(逐镜起止帧/秒、景别上下沿、`wan3_camera_directive`、口播时间窗与字数上限)、`effects[]`(花字预设名与位置样式,文案留作变量槽),**严禁把本次私密模特照片或服装原图绝对路径写死进共享模板**。
78
+
79
+ ---
80
+
81
+ ## 2. 单一交互面铁律(彻底告别 `sendPrompt` 塞草稿与双重提问)
82
+
83
+ 1. **为什么严禁在卡片中使用 `sendPrompt`**:
84
+ - 在 SuperOne 中,自定义 Widget iframe 内的 `window.sendPrompt(text)` 底层行为是向底部输入框填入草稿(`setDraftText`),**不会自动提交消息**,而卡片自身却变灰提示“已发送”,既把 `planDigest=... directory=...` 等内部机器参数暴露给用户,又造成用户误以为已提交而干等。
85
+ - 本仓库保留的 4 张模板(`zenmcp-spend-confirm`、`zenmcp-budget-confirm`、`zenmcp-account`、`zenmcp-install-checklist`)已全部改为**纯只读账单/状态展示卡**(仅保留外部浏览器打开账户充值页的 `openLink`),完全不含 `sendPrompt`。原 `zenmcp-asset-roles`、`zenmcp-trim-range`、`zenmcp-model-picker` 已下线停用。
86
+ 2. **为什么不用 `setContext` 做确认门控**:
87
+ - `setContext` / `updateModelContext` 仅存在于 MiniApp 与 SEP-1865 MCP App,普通 `widget_show` 没有该接口;且 `setContext` 只将上下文挂载到用户的**下一条手动输入消息**上,本身不会触发发送回合,用户点选后仍需打字回车才能唤醒智能体。它适合多素材自由挑选批注,不适合“点一下即批准执行”的确认门控。
88
+ 3. **防双重提问与全中文卡片硬约束**:
89
+ - **视觉层只负责看**:Markdown 内联媒体、`@native/*` 原生媒体组件与 `zenmcp-*` 只读账单卡只展示画面和数据,不承载对话回复按钮。
90
+ - **已获批预算内禁弹逐张报价卡**:当用户在阶段 3(闸门 1)或模卡预检已批准整阶段准备预算且单项 `large: false` 时,阶段 4 的定妆图(`outfit-01..N`)与模卡子阶段生图直接后台静默执行 `quote_generation` + `run_generation`,**严禁每生一张图就调用 `widget_show(template: "zenmcp-spend-confirm")` 弹出单张报价确认卡**;实扣积分与剩余准备额度统一在阶段产出画廊中回报。`zenmcp-spend-confirm` 仅在独立单次直出生图/生视频尚未获批、或超出预批额度需单独拍板时展示。
91
+ - **全中文展示零英文泄漏**:
92
+ - `widget_show` 的 `title` 参数会直接显示在 SuperOne 卡片右上角,**一律传简短中文标题**(如 `"原片与关键帧"`、`"拆解素材核对"`、`"定妆确认图与质检"`、`"视频预算账单"`、`"生成报价单"`),**严禁传 `outfit_01_quote`、`three_outfits_review` 等英文下划线词**。
93
+ - 调用 `zenmcp-spend-confirm` 时,`model_label` 直接使用 `quote_generation` 返回的中文 `model_label`(勿传 `gpt-image-2.6-sunburst` 等内部英文代号);若底层 `prompt` 为英文翻译或工程模板,必须在 `data.task_summary` 中传入简短中文生成说明,禁止向用户暴露内部英文工程提示词。
94
+ - **决策层只问一次**:每个需要用户拍板的回合,**最多调用 1 次宿主选项式提问工具,且必须作为本回合最后一个工具调用**;调用提问工具后不再重复输出文字选择题。
95
+ - **机器参数内部闭环**:`requestDigest`、`planDigest`、`directory` 均由智能体从上一轮 `quote_generation` / `plan_job` 工具返回上下文中直接读取,严禁拼入选项标签或让用户复制回传。
96
+
97
+ ---
98
+
99
+ ## 3. 跨智能体选项式提问兼容矩阵
100
+
101
+ ### 3.1 跨平台最小公约数(编写选项时统一遵守)
102
+
103
+ - **单次题数**:每次调用最多合并 **1–3 个问题**(严禁超过 3 题)。
104
+ - **每题选项数**:每题 **2–3 个选项**;推荐项固定放在第 1 位,名称末尾标注 `(推荐)`。
105
+ - **字数控制**:`header`(短标题)≤ 12 字符;选项标题 ≤ 14 个汉字;选项说明 ≤ 40 字。
106
+ - **禁止自建“其他”项**:各客户端提问卡片均自带自由输入入口(Other),不要手动添加“其他”选项。
107
+
108
+ ### 3.2 各客户端工具映射与降级表
109
+
110
+ | 客户端 / 宿主环境 | 选项式提问工具名 | 交互表现与兼容说明 |
111
+ |---|---|---|
112
+ | SuperOne(Claude) / Claude Code CLI | `AskUserQuestion` | 原生选项卡片,点击即提交唤醒,支持单选/多选与 Other 自由输入 |
113
+ | SuperOne(Codex) / Codex App & CLI | 当次可用的 `request_user_input_async` 或 `request_user_input` | 先检查工具及模式限制;异步提交后等待用户回复,未答不能视为批准;不可调用仅在其他模式可用的工具,无可用工具则编号列表降级 |
114
+ | SuperOne(Cursor) / Cursor IDE | `AskQuestion` | 原生选项卡片,遵循同一最小公约数 |
115
+ | SuperOne(Gemini) / Antigravity | `ask_question` | 原生选项卡片,推荐项置顶,自带 Other 输入框 |
116
+ | SuperOne(Grok) | `ask_user_question` | 原生选项卡片,点击即提交 |
117
+ | SuperOne(OpenCode) / OpenCode CLI | `question` | 原生选项卡片,点击即提交 |
118
+ | 无提问工具的纯标准 MCP 客户端 | *无专用工具* | **优雅降级**:在回复末尾输出简洁编号列表(`1. …(推荐)` / `2. …`),提示“回复编号即可,也可直接说明调整意见”,随即结束本回合等待用户回复 |
119
+
120
+ 客户端名称不保证工具存在;只使用本次实际暴露且可调用的一种提问能力。同一回合不要先发卡片再重复文本问题;用户已明确回答的内容不要再问。审批确认与上传同意仍须获得真实回复。
121
+
122
+ ---
123
+
124
+ ## 4. 会话内全媒体素材预览渲染总表与跨智能体对比
125
+
126
+ ### 4.1 各流程节点媒体组件选型表
127
+
128
+ | 流程节点 | 待展示素材 | SuperOne 会话内渲染方式 | 其他智能体(Claude Code / Codex / Cursor / 终端) |
129
+ |---|---|---|---|
130
+ | **1. 选模卡 / 查库** | 单个命中模特预览图 | 单张内联 `![模特预览](</abs/path/model-preview.jpg>)` | 输出可点击文件链接 `[model-preview.jpg](/abs/path/model-preview.jpg)` |
131
+ | **1. 选模卡 / 新建模卡** | 多个候选模卡或新建五视图 + 总览板 | `widget_show({ template: "@native/image-gallery", data: { images: [{ path }], params } })` | 列出各图可点击绝对路径与所在目录路径 |
132
+ | **2. 视频类别定性(阶段 2)** | 原片视频 + `01-reference/keyframes.jpg` | 原片用内联 `![参考原片](</abs/path/source.mp4>)`,关键帧拼图用内联 `![关键帧总览](</abs/path/keyframes.jpg>)` + 明确报出视频类别与所需服装套数 | 输出原片与 `keyframes.jpg` 可点击路径 + 视频类别结论 |
133
+ | **3. 服装提取** | 单张服装图或多件/多帧服装拼图 | 单张内联 `![服装提取预览](</abs/path/garments-sheet.jpg>)` + 一句话说明 | 输出 `[garments-sheet.jpg](/abs/path/garments-sheet.jpg)` |
134
+ | **4. 拆解核对(阶段 3 · 闸门 1)** | 原片(未展示过时)+(关键帧拼图、模特预览、服装拼图) | 三张拆解核对图合并为一个 `@native/files-previewer`(每张带 `note` 说明)或 `@native/image-gallery` | 输出三张拼图的可点击路径 + ≤5 行文字摘要 |
135
+ | **5. 出确认图(阶段 4 · 定妆质检)** | `outfit-01..N.png` + `height-ruler.jpg` + `fabric-qc-01..N.jpg` | **合并为一个** `@native/files-previewer`(逐张附身高偏差与面料 1:1 核对 `note`)或 `@native/image-gallery`(`params` 注明已花积分与剩余准备额度),禁止多图竖排刷屏 | 列出定妆图与 `qc/` 质检图可点击路径,提示在本地看图器查看 `04-tryon/` |
136
+ | **6. 视频报价(阶段 5 · 闸门 2)** | 执行计划摘要 + 预算账单 | 先简要列出关键计划摘要,再调 `widget_show({ template: "zenmcp-budget-confirm", data: { ..., readonly: true } })` | 原样输出 `plan_job` 返回的完整 `markdown` 账单摘要 |
137
+ | **7. 待验收交付(阶段 6)** | 中文命名预览 + 同步对比片 | 作品预览为主,对比为辅;已发现偏差简述,用原生画廊/文件卡展示,不把质检包当主作品 | 提供实际可访问的中文命名文件链接,不能假设支持 Widget 或内联视频 |
138
+ | **8. 用户验收通过** | 中文命名成片与可选对比文件 | 用一个原生文件卡交付正式文件,展示“已验收”;费用和制作细节按需查看,不重复验收问题 | 提供正式文件绝对路径链接;沿用用户已作出的验收结论 |
139
+
140
+ ### 4.2 SuperOne 媒体渲染语法速查(避免格式踩坑)
141
+
142
+ - **单文件内联(图 / 视频 / 音频)**:
143
+ - 图片:`![服装提取总览](</abs/path/02-garments/garments-sheet.jpg>)`
144
+ - 视频:`![动作参考原片](</abs/path/01-reference/source.mp4>)`
145
+ - 音频:`![配音试听](</abs/path/05-video/voice.mp3>)`
146
+ - **注意**:路径含空格或括号时必须用尖括号 `<...>` 包裹;文件必须具备真实扩展名(`.png` / `.jpg` / `.webp` / `.mp4` / `.mp3`),无扩展名二进制文件会被判定为不可预览;同一文件在同一条回复中最多渲染一次。
147
+ - **多文件逐项带批注预览(推荐用于闸门 1 核对包与定妆质检包)**:
148
+ ```json
149
+ {
150
+ "title": "定妆确认图与面料质检",
151
+ "template": "@native/files-previewer",
152
+ "data": {
153
+ "files": [
154
+ { "path": "/abs/path/04-tryon/outfit-01.png", "note": "第 1 套全身定妆图(实扣 4 积分)" },
155
+ { "path": "/abs/path/04-tryon/qc/height-ruler.jpg", "note": "头顶与脚底水平标尺核验(偏差 < 1.5%)" },
156
+ { "path": "/abs/path/04-tryon/qc/fabric-qc-01.jpg", "note": "左:原衣局部 · 右:定妆图上半身面料与领口 1:1 放大对比" }
157
+ ]
158
+ }
159
+ }
160
+ ```
161
+ - **纯图片画廊 / 纯视频画廊**:
162
+ - `@native/image-gallery`:`data: { images: [{ path: "/abs/1.png" }, { path: "/abs/2.jpg" }], prompt?: "...", params?: { ... } }`
163
+ - `@native/video-gallery`:`data: { videos: [{ path: "/abs/final.mp4" }, { path: "/abs/side-by-side.mp4" }], params?: { ... }, warnings?: ["服装与身份需人工验收"] }`
164
+ - **按宿主实际能力展示**:
165
+ - **SuperOne 桌面与移动端**:原生支持内联图片/视频/音频播放器、`@native/*` 画廊(点击全屏检视、拖拽导出 Finder)及只读账单 Widget。
166
+ - **其他图形客户端**:只使用当次可用的媒体能力;无法确认是否支持内联视频时,至少交付 `[中文文件名](</绝对路径/中文文件名.mp4>)` 和必要的完整路径,不假定能调用 SuperOne 的 `@native/*`。
167
+ - **纯终端**:直接输出简短摘要与绝对路径;没有 `widget_show` 就不调用,也不输出伪播放器按钮。
168
+
169
+ ---
170
+
171
+ ## 5. 标准选项式提问模板参考
172
+
173
+ 1. **链接/视频入口意图分流(仅当用户只甩链接/视频、未说明制作意图时提问)**
174
+ - 问题:`原片已准备好,需要怎么处理这条视频?`
175
+ - 选项:`拆解视频并确认二创方案(推荐)`(0 积分辨识视频类别、镜头套数与口播结构) / `仅提取口播文案` / `仅保存原片`
176
+ 2. **阶段 2:确定视频类别与询问任务改法(按识别分支二选一触发)**
177
+ - *分支 A(命中标准第一类穿搭展示,且尚未收齐模特/服装或改法未明时)*:`已识别为【第一类:固定同景穿搭展示】(需 N 套衣服),想怎么制作当下任务?`
178
+ - 选项:`换模特+换衣服(推荐)`(确认后告诉我用哪位模特或发人物照,再发 N 张衣服正面图) / `只换衣服` / `仅保留拆解报告`
179
+ - *(注:若参考视频、模特、服装三项已一次发齐且明确要做二创,报出第一类定性结论后直接合并进下方闸门 1 提问,不单独多停一轮。)*
180
+ - *分支 B(识别为非第一类:跨场景运镜 / 手持展示 / 场景展示 / 真人对口型 / 同片同衣只换人)*:`该片属于【具体类别名称】,超出当前第一类固定同景换装稳态范围,如何处理?`
181
+ - 选项:`仅保留原片与免费拆解报告(推荐)`(0 积分止损,不强行套用第一类管线) / `截取单场景片段或改画外音按第一类试做`(仅当片内确有可截取的固定单景换装段或可转旁白时提供)
182
+ 3. **新人物参考照用法确认(用户上传新人物照片时)**
183
+ - 问题:`这位人物参考图怎么用于本次任务?`
184
+ - 选项:`仅本次使用(推荐)`(直接作为本次身份参考,0 额外积分) / `做成持久五图模卡`(按模卡规范生成五视图,做完后可命名入库长期复用) / `改用库里的已有模特`(在补充说明写明模特名字或 ID)
185
+ 4. **新人物五图模卡验收与入库命名确认(每次新人物做完五图必问)**
186
+ - 问题:`五张标准模卡与总览图已就绪,要保存到本机模特库长期复用吗?`
187
+ - 选项:`按建议名称「清冷长发女模D」(ID:model-d-cool)保存入库(推荐)`(确认人像使用授权,存入 `~/.config/zenmcp/library/models/model-d-cool/`;也可直接在补充说明填写自定义名字如“小雅”,将自动生成对应 ID) / `仅本次使用,暂不入库` / `需要微调某张图(在补充说明写明图号)`
188
+ 5. **阶段 3(闸门 1):拆解核对与准备预算合并确认(按实际存在项组合 1–3 题)**
189
+ - *题 1(仅当服装参考图含包袋、墨镜/眼镜、帽子、围巾等可选配饰时出现)*:`检测到服装参考图带有配饰,定妆时如何处理?`(只管服装图,不删除原动作依赖物;明确保留要求与手部动作冲突时,将实际取舍合并在本次确认中。)
190
+ - 选项:`仅保留服装鞋袜(推荐)`(剥离包袋墨镜等道具,衣服版型还原最稳) / `保留服装与全部配饰` / `仅保留包袋(去掉墨镜帽子)`
191
+ - *题 2(仅当原片 > 13 秒需选段,或含人声需定音频路线时出现)*:`原片超建议时长,使用哪一段做动作参考?`
192
+ - 选项:`0.4–13.0 秒净片(推荐)`(剥离片头闪帧,保留完整走位) / `前 13 秒`
193
+ - *题 3(必问,放最后)*:`确认开始生成定妆确认图与质检对比图吗?`
194
+ - 选项:`批准定妆准备 ≤ X 积分(推荐)`(含每套 1 次重抽预留,同意上传模特与服装参考图用于生成;不含视频费用) / `暂不生成`
195
+ 6. **阶段 4:定妆确认图与面料质检拍板**
196
+ - 问题:`定妆确认图(含身高标尺与面料 1:1 放大对比)是否满意?`
197
+ - 选项:`满意,进入视频报价(推荐)` / `重抽指定套数(在补充说明写套号与问题)` / `暂停任务`
198
+ 7. **阶段 5(闸门 2):最终执行生成视频前确认**
199
+ - 问题:`请核对视频预算账单,确认发起生成吗?`
200
+ - 选项:`确认生成 N 积分(推荐)`(默认 720p,同意上传定妆图与参考视频) / `改为 1080p 重新报价` / `取消,不扣费`
201
+ 8. **阶段 6(交付后可选):保存为可复用结构模板草案(衔接后续 DSL)**
202
+ - 成片验收满意后可在回复末尾轻提示(或当用户主动表示想存成模板时单次提问):`要把这条视频的镜头节奏与字幕口播结构保存为可复用模板吗?`
203
+ - 选项:`保存为模板「6套穿搭快切公式」(ID:outfit-6sets-formula)(推荐)`(剥离个人模特衣服图片,将切点、景别、花字与口播槽存入 `~/.config/zenmcp/library/templates/`;支持补充说明自起模板名) / `暂不保存模板`
@@ -0,0 +1,29 @@
1
+ # 作品命名、验收与交付
2
+
3
+ ## 正式作品与执行记录
4
+
5
+ 引擎的 `final.mp4`、生成目录、付款记录和摘要用于续查,保持原位。面向用户的文件复制到当前项目 `06-output/`,不移动或改写执行记录,不新建作品库服务或交付工具。
6
+
7
+ - 文件名:`<作品名>-<人物简称>-<用途>-v<两位版本>-<分辨率>.<真实扩展名>`。人物无关作品省略人物简称;用途用“预览”“成片”“原片对比”等中文,不能把未验收稿命名为成片。
8
+ - 例如:`一周穿搭-模特A-成片-v02-720P.mp4`、`一周穿搭-模特A-原片对比-v02-720P.mp4`。对比片的分辨率标签指成片档位,实际拼接尺寸记入详情。
9
+ - 默认根据主题与已选人物起简短中文名,不为取名新增提问;用户命名优先。去除路径分隔符和 `< > : " | ? *` 等文件名禁用字符,去掉首尾空白/末尾句点,不使用 `..`、密钥、摘要或绝对路径作文件名。
10
+ - 同一次免费后期修改或付费重制都产生新版本,保留历史;同名同内容可复用,同名不同内容不得覆盖。验收前用“预览”,验收后新建“成片”副本。
11
+ - 在现有 `project.json.delivery` 记录作品名、版本、`awaiting_acceptance` / `accepted` 状态、交付文件相对路径及对应执行目录。已有字段等价时沿用,不引入重复总账;本次实扣、累计实扣、未用预留额度分别记录,不把剩余额度当作已花费用。
12
+
13
+ ## 两个交付状态
14
+
15
+ **待验收**:优先读取工具的 `result_summary`,主展示成片预览,说明名称、时长、分辨率和本次实扣;对比片作为辅助。已发现偏差简述,完整质检报告、版本记录、累计费用和执行细节按需展开,不自动粘贴报告长文。用宿主现有提问工具一次确认“满意,完成作品 / 修改指定位置 / 暂停”,不能将软件 `completed` 当作用户验收。
16
+
17
+ **已验收**:用户说“过关、满意、就用这个”即记录已验收,不再重复确认;制作正式命名副本并校验内容一致。主交付只突出作品、可下载文件和简短说明,对比片放次位。普通项目内归档不需要再问“是否保存作品”;跨项目模卡入库、结构模板保存仍各自遵守授权。
18
+
19
+ 宿主有原生画廊就使用原生播放/下载能力;没有时用 `[中文文件名](</绝对路径/中文文件名.mp4>)`,无法渲染则附完整路径。不要把 `file://`、SuperOne Widget 或虚构的下载按钮作为所有客户端的共同能力。多个交付文件在 SuperOne 使用一个原生文件预览卡;单个作品可内联。
20
+
21
+ 可用现有提问能力或自然语言提供“调整作品 / 做下一条”,不要制作没有真实处理能力的按钮。免费后期、需付费的旁白、整片重跑分别说明;展示过的选项不反复追问。模板保存是可选的下一步,不阻塞当前作品完成。
22
+
23
+ ## 过程反馈与恢复
24
+
25
+ - 素材、场景、服装来源分别记录;用户说已有或上次时先查项目/模卡库,不重复拉取已下载链接或要求重传已有素材。
26
+ - 已批准阶段预算内的小额生成静默执行,不逐图再弹账单;真正的新费用、涨价或大额操作仍单独批准。
27
+ - 轮询遵守返回间隔,长等待不重复粘贴整份 JSON、英文提示词或相同预算卡。宿主要求心跳时只给短状态,优先汇报新事实,不编造进度百分比或预计完成时间。
28
+ - 用户说“继续”时先查同一目录;真实中断时才按工具提示在原目录恢复,不能将恢复当作新任务提交。新制作沿用已验收素材,新增费用仍需批准。
29
+ - 实际声音未核听、未完整播放或只检查抽帧时如实说明;已验收后不再机械附上“尚需用户验收”。
@@ -0,0 +1,179 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Cross-platform contact sheet & 1:1 crop comparison builder (pure Node + ffmpeg, no drawtext/font dependency).
4
+ *
5
+ * Examples:
6
+ * 1) Video keyframe sheet:
7
+ * node skills/zenmcp/scripts/build-contact-sheet.mjs --video 01-reference/source.mp4 --count 8 --cols 4 --number --out 01-reference/keyframes.jpg
8
+ * 2) Garment / model preview sheet:
9
+ * node skills/zenmcp/scripts/build-contact-sheet.mjs --cols 3 --number --out 02-garments/garments-sheet.jpg g1.png g2.png g3.png
10
+ * 3) 1:1 fabric & makeup detail QC comparison (normalized #crop=x,y,w,h in 0..1):
11
+ * node skills/zenmcp/scripts/build-contact-sheet.mjs --cols 2 --cell-w 540 --cell-h 540 --out 04-tryon/qc/fabric-qc-01.jpg \
12
+ * "02-garments/garment-01.png#crop=0.15,0.08,0.70,0.55" "04-tryon/outfit-01.png#crop=0.22,0.18,0.56,0.45"
13
+ */
14
+ import { execFile } from 'node:child_process';
15
+ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
16
+ import { tmpdir } from 'node:os';
17
+ import { dirname, join } from 'node:path';
18
+ import { promisify } from 'node:util';
19
+
20
+ const execFileAsync = promisify(execFile);
21
+
22
+ const args = process.argv.slice(2);
23
+ let outPath = 'contact-sheet.jpg';
24
+ let cols = 0;
25
+ let cellW = 360;
26
+ let cellH = 480;
27
+ let videoPath = '';
28
+ let frameCount = 8;
29
+ let numbered = false;
30
+ const specs = [];
31
+
32
+ for (let i = 0; i < args.length; i++) {
33
+ const a = args[i];
34
+ if (a === '--out' && args[i + 1]) outPath = args[++i];
35
+ else if (a === '--cols' && args[i + 1]) cols = Number(args[++i]);
36
+ else if (a === '--cell-w' && args[i + 1]) cellW = Number(args[++i]);
37
+ else if (a === '--cell-h' && args[i + 1]) cellH = Number(args[++i]);
38
+ else if (a === '--video' && args[i + 1]) videoPath = args[++i];
39
+ else if (a === '--count' && args[i + 1]) frameCount = Number(args[++i]);
40
+ else if (a === '--number') numbered = true;
41
+ else if (!a.startsWith('--')) specs.push(a);
42
+ }
43
+
44
+ const SEGMENTS = {
45
+ '0': ['a', 'b', 'c', 'd', 'e', 'f'],
46
+ '1': ['b', 'c'],
47
+ '2': ['a', 'b', 'g', 'e', 'd'],
48
+ '3': ['a', 'b', 'g', 'c', 'd'],
49
+ '4': ['f', 'g', 'b', 'c'],
50
+ '5': ['a', 'f', 'g', 'c', 'd'],
51
+ '6': ['a', 'f', 'e', 'd', 'c', 'g'],
52
+ '7': ['a', 'b', 'c'],
53
+ '8': ['a', 'b', 'c', 'd', 'e', 'f', 'g'],
54
+ '9': ['a', 'b', 'c', 'd', 'f', 'g'],
55
+ };
56
+
57
+ function digitBoxes(digit, ox, oy) {
58
+ const w = 10;
59
+ const h = 16;
60
+ const t = 2;
61
+ const mh = Math.floor(h / 2);
62
+ const map = {
63
+ a: `drawbox=x=${ox}:y=${oy}:w=${w}:h=${t}:color=white:t=fill`,
64
+ d: `drawbox=x=${ox}:y=${oy + h - t}:w=${w}:h=${t}:color=white:t=fill`,
65
+ g: `drawbox=x=${ox}:y=${oy + mh - 1}:w=${w}:h=${t}:color=white:t=fill`,
66
+ f: `drawbox=x=${ox}:y=${oy}:w=${t}:h=${mh}:color=white:t=fill`,
67
+ e: `drawbox=x=${ox}:y=${oy + mh}:w=${t}:h=${h - mh}:color=white:t=fill`,
68
+ b: `drawbox=x=${ox + w - t}:y=${oy}:w=${t}:h=${mh}:color=white:t=fill`,
69
+ c: `drawbox=x=${ox + w - t}:y=${oy + mh}:w=${t}:h=${h - mh}:color=white:t=fill`,
70
+ };
71
+ return (SEGMENTS[digit] ?? []).map(s => map[s]);
72
+ }
73
+
74
+ function numberBadgeFilters(index1) {
75
+ const text = String(index1).padStart(2, '0');
76
+ const boxes = ['drawbox=x=8:y=8:w=34:h=26:color=0x000000@0.72:t=fill'];
77
+ for (let i = 0; i < text.length; i++) {
78
+ boxes.push(...digitBoxes(text[i], 13 + i * 14, 13));
79
+ }
80
+ return boxes;
81
+ }
82
+
83
+ function parseSpec(raw) {
84
+ const hashIdx = raw.indexOf('#crop=');
85
+ if (hashIdx === -1) return { path: raw, crop: null };
86
+ const path = raw.slice(0, hashIdx);
87
+ const parts = raw.slice(hashIdx + 6).split(',').map(Number);
88
+ if (parts.length !== 4 || parts.some(n => !Number.isFinite(n) || n < 0 || n > 1)) {
89
+ throw new Error(`Invalid #crop=x,y,w,h (expected normalized 0..1): ${raw}`);
90
+ }
91
+ const [x, y, w, h] = parts;
92
+ if (w <= 0 || h <= 0 || x + w > 1.0001 || y + h > 1.0001) {
93
+ throw new Error(`Out-of-range #crop=x,y,w,h: ${raw}`);
94
+ }
95
+ return { path, crop: { x, y, w: Math.min(w, 1 - x), h: Math.min(h, 1 - y) } };
96
+ }
97
+
98
+ let tempDir = '';
99
+ try {
100
+ const parsed = specs.map(parseSpec);
101
+ if (videoPath) {
102
+ tempDir = await mkdtemp(join(tmpdir(), 'zenmcp-sheet-'));
103
+ const { stdout } = await execFileAsync('ffprobe', [
104
+ '-v', 'error',
105
+ '-show_entries', 'format=duration',
106
+ '-of', 'default=nk=1:nw=1',
107
+ videoPath,
108
+ ]);
109
+ const dur = Math.max(0.2, Number(stdout.trim()) || 1);
110
+ const n = Math.max(1, Math.min(24, Math.round(frameCount)));
111
+ for (let i = 0; i < n; i++) {
112
+ const ts = Number(((dur * (i + 0.5)) / n).toFixed(3));
113
+ const frameFile = join(tempDir, `frame-${String(i + 1).padStart(2, '0')}.jpg`);
114
+ await execFileAsync('ffmpeg', [
115
+ '-y', '-ss', String(ts), '-i', videoPath, '-frames:v', '1', '-q:v', '2', frameFile,
116
+ ]);
117
+ parsed.push({ path: frameFile, crop: null });
118
+ }
119
+ }
120
+
121
+ if (parsed.length === 0) {
122
+ console.error('Usage: node build-contact-sheet.mjs --out <out.jpg> [--video <in.mp4> --count 8] [--cols N] [--cell-w 360] [--cell-h 480] [--number] [img1[#crop=x,y,w,h] ...]');
123
+ process.exit(1);
124
+ }
125
+
126
+ await mkdir(dirname(outPath), { recursive: true });
127
+ const total = parsed.length;
128
+ const gridCols = cols > 0 ? Math.min(cols, total) : (total <= 2 ? total : total <= 4 ? 2 : 3);
129
+ const gridRows = Math.ceil(total / gridCols);
130
+ const gap = 4;
131
+
132
+ const inputs = parsed.flatMap(item => ['-i', item.path]);
133
+ const filters = [];
134
+
135
+ parsed.forEach((item, idx) => {
136
+ const chain = [];
137
+ if (item.crop) {
138
+ const { x, y, w, h } = item.crop;
139
+ chain.push(`crop=iw*${w.toFixed(4)}:ih*${h.toFixed(4)}:iw*${x.toFixed(4)}:ih*${y.toFixed(4)}`);
140
+ }
141
+ chain.push(
142
+ `scale=${cellW}:${cellH}:force_original_aspect_ratio=decrease`,
143
+ `pad=${cellW}:${cellH}:(ow-iw)/2:(oh-ih)/2:color=0x18181B`,
144
+ 'setsar=1',
145
+ );
146
+ if (numbered) chain.push(...numberBadgeFilters(idx + 1));
147
+ filters.push(`[${idx}:v]${chain.join(',')}[c${idx}]`);
148
+ });
149
+
150
+ if (total === 1) {
151
+ filters.push('[c0]null[out]');
152
+ } else {
153
+ const padCount = gridCols * gridRows - total;
154
+ for (let p = 0; p < padCount; p++) {
155
+ filters.push(`color=c=0x18181B:s=${cellW}x${cellH}:d=1[c${total + p}]`);
156
+ }
157
+ const allCount = gridCols * gridRows;
158
+ const stackInputs = Array.from({ length: allCount }, (_, i) => `[c${i}]`).join('');
159
+ const layout = Array.from({ length: allCount }, (_, i) => {
160
+ const r = Math.floor(i / gridCols);
161
+ const c = i % gridCols;
162
+ return `${c * (cellW + gap)}_${r * (cellH + gap)}`;
163
+ }).join('|');
164
+ filters.push(`${stackInputs}xstack=inputs=${allCount}:layout=${layout}:fill=0x18181B[out]`);
165
+ }
166
+
167
+ await execFileAsync('ffmpeg', [
168
+ '-y',
169
+ ...inputs,
170
+ '-filter_complex', filters.join(';'),
171
+ '-map', '[out]',
172
+ '-frames:v', '1',
173
+ '-q:v', '2',
174
+ outPath,
175
+ ]);
176
+ console.log(outPath);
177
+ } finally {
178
+ if (tempDir) await rm(tempDir, { recursive: true, force: true });
179
+ }