448 lines
14 KiB
Markdown
448 lines
14 KiB
Markdown
# Video Workbench 中文使用手册
|
||
|
||
## 文档状态
|
||
|
||
- 状态：草稿，供朋友试用前阅读。
|
||
- 建议当前位置：`tmp/video-workbench-user-manual-zh.md`。
|
||
- 正式化建议：确认内容可用后，移动到 `docs/`，例如 `docs/video-workbench-user-manual-zh.md`，并在 `README.md` 中加入口链接。
|
||
- 注意：仓库规则里 `tmp/` 不是长期资料区。这里先放 `tmp/`，是为了避免把未经确认的外部使用说明直接当成正式规则。
|
||
|
||
## 这是什么
|
||
|
||
`video-workbench` 是一个本地视频 / slide 风格内容生产工作台。
|
||
|
||
它适合把已经形成方向的材料，继续推进成：
|
||
|
||
- 视频或 MV 的分镜 / 画面单元；
|
||
- slide / PPT 风格页面；
|
||
- 视觉系统、角色参考、风格参考；
|
||
- 图片生成提示词与生成结果；
|
||
- 旁白、画面、后期说明、交接记录。
|
||
|
||
它不是：
|
||
|
||
- 深度文章写作仓库；
|
||
- 长期知识库；
|
||
- 通用自动化工具源码仓库；
|
||
- CCPE 正式 Agent / Runtime / Model Card 的 canonical 存放地；
|
||
- 自动剪辑和发布系统。
|
||
|
||
简单说：这里是“把已经接受的创意和规划，落地成可继续生产的本地项目文件和素材”的地方。
|
||
|
||
## 工作分工
|
||
|
||
默认分工如下：
|
||
|
||
```text
|
||
ChatGPT / GPT V2 = 前期构思、文章摘要、视觉方向、分镜或页面骨架
|
||
用户 = 决策、确认输入材料、判断结果是否可用
|
||
Codex = 本地执行、整理项目文件、写 brief / prompt、生成或记录素材、维护 handoff
|
||
video-workbench = 存放本地项目、执行记录和素材
|
||
```
|
||
|
||
不要让 GPT V2 负责最终图片 prompt、Codex JSON、输出路径、任务包或图片生成参数。这些属于 Codex 在本仓库内执行时产生的内容。
|
||
|
||
## 第一次打开时怎么做
|
||
|
||
在 Codex 中打开这个仓库：
|
||
|
||
```text
|
||
C:\Users\wangq\Documents\Codex\video-workbench
|
||
```
|
||
|
||
新会话里先给 Codex 这段话：
|
||
|
||
```md
|
||
请先阅读 AGENTS.md、README.md、VIDEO_WORKBENCH.md、docs/context-handoff.md、docs/ccpe-system-handoff.md，然后按 video-workbench 的当前约定继续工作。
|
||
```
|
||
|
||
如果要做 slide / 图片生产，还要让 Codex 读取：
|
||
|
||
```text
|
||
docs/workflows/project-lifecycle.md
|
||
docs/workflows/slide-task-orchestration.md
|
||
docs/workflows/slide-task-templates.md
|
||
```
|
||
|
||
如果朋友是在另一台机器使用，需要先确认这些本地能力是否存在：
|
||
|
||
- Codex / Codex Desktop 可以访问该仓库；
|
||
- `gpt-image-2` Skill 已安装；
|
||
- 本地路径里的 `C:\Users\wangq\...` 已替换成朋友机器上的实际路径；
|
||
- 如果要用 CCPE，先读 `C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md` 对应的新机器路径；
|
||
- 如果要生成图片，确认宿主环境有可用的图片生成工具。
|
||
|
||
## 目录怎么理解
|
||
|
||
核心目录：
|
||
|
||
```text
|
||
projects/
|
||
<project-id>/
|
||
project.md
|
||
intake/
|
||
execution-plan.md
|
||
visual-system/
|
||
slides/
|
||
tasks/
|
||
|
||
handoff/
|
||
docs/
|
||
investigations/
|
||
requirements/
|
||
garden-gpt-image-2/
|
||
tmp/
|
||
```
|
||
|
||
常用含义：
|
||
|
||
- `projects/`：所有真实项目都放这里。不要按 active / completed / series 分目录。
|
||
- `projects/<project>/intake/`：放用户接受的 GPT V2 规划、原始材料、参考说明、图片等。
|
||
- `projects/<project>/project.md`：项目小地图，记录状态、阶段、关键文件和下一步。
|
||
- `projects/<project>/execution-plan.md`：执行控制文件，记录当前生产策略、批次、轮次、下一步。
|
||
- `projects/<project>/visual-system/`：视觉系统权威位置，包括风格、角色、场景、参考图。
|
||
- `projects/<project>/slides/`：实际 slide / shot / page 单元区。
|
||
- `projects/<project>/tasks/`：长任务、子会话、生产批次、callback、handoff 的本地记录。
|
||
- `handoff/`：跨项目、跨阶段、上下文压缩时使用的仓库级交接。
|
||
- `docs/workflows/`：工作流规则。
|
||
- `investigations/`：有保存价值的实验和调查。
|
||
- `tmp/`：短期草稿，不放长期证据。
|
||
|
||
## 一个新项目的最小流程
|
||
|
||
### 1. 放入原始输入
|
||
|
||
把已经接受的 GPT / 用户材料放到：
|
||
|
||
```text
|
||
projects/<project-id>/intake/
|
||
```
|
||
|
||
这些材料可以是：
|
||
|
||
- GPT V2 输出的整体规划；
|
||
- 视觉系统建议；
|
||
- 分镜 / 页面骨架；
|
||
- 参考图、角色说明、风格说明；
|
||
- 用户自己的补充资料。
|
||
|
||
不要一开始就重写它们。`intake/` 是来源，Codex 后续会从中抽取本地执行文件。
|
||
|
||
### 2. 建立项目控制文件
|
||
|
||
让 Codex 创建或整理：
|
||
|
||
```text
|
||
projects/<project-id>/project.md
|
||
projects/<project-id>/execution-plan.md
|
||
projects/<project-id>/visual-system/visual-system.md
|
||
projects/<project-id>/slides/slides.md
|
||
```
|
||
|
||
这四类文件的职责不同：
|
||
|
||
- `project.md`：项目地图和下一步。
|
||
- `execution-plan.md`：怎么执行、当前批次、当前决策。
|
||
- `visual-system/visual-system.md`：视觉系统、风格、角色、素材锚点。
|
||
- `slides/slides.md`：每个画面 / 页面单元的事实表。
|
||
|
||
不要把 GPT 规划逐段复制成新的“真相文件”。`intake/` 保留来源，Codex 维护本地执行控制。
|
||
|
||
### 3. 进入生命周期
|
||
|
||
项目阶段写在 `project.md` 里，常用阶段是：
|
||
|
||
```text
|
||
intake-cleanup
|
||
system-definition
|
||
pilot-validation
|
||
production
|
||
assembly-closeout
|
||
```
|
||
|
||
一般顺序：
|
||
|
||
1. `intake-cleanup`：清理和规范原始材料。
|
||
2. `system-definition`：形成本地视觉系统和执行骨架。
|
||
3. `pilot-validation`：先测核心画面、角色一致性、生成路径。
|
||
4. `production`：进入批量生产。
|
||
5. `assembly-closeout`：整理最终交付、后期、归档。
|
||
|
||
## slide / shot 生产怎么运行
|
||
|
||
本仓库把一个画面、页面或镜头单元统一叫 `slide`。文件夹通常长这样：
|
||
|
||
```text
|
||
projects/<project>/slides/
|
||
slides.md
|
||
s01/
|
||
s01-v1-design.md
|
||
s01-v1-brief.md
|
||
s01-v1-prompt.md
|
||
s01-v1-image.png
|
||
```
|
||
|
||
规则：
|
||
|
||
- 每个 slide 用 `sNN` 编号，例如 `s01`、`s02`。
|
||
- 每次新执行都用新版本 `vN`，例如 `s01-v1-*`、`s01-v2-*`。
|
||
- 默认不覆盖旧文件。
|
||
- 如果旧版本失败，也保留为历史证据，再写新版本。
|
||
- 所有新任务默认写明：`Overwrite allowed: no`。
|
||
|
||
### design / brief / prompt / image 的区别
|
||
|
||
- `design`：给人看的设计说明。封面、PPT、科普页、标题页、解释页、需要后期排版的页面要先写它。
|
||
- `brief`：给 Codex / 子会话执行用的任务卡。
|
||
- `prompt`：根据 brief 生成的图片提示词文件，必须通过 `gpt-image-2` Skill 工作流产生。
|
||
- `image`：生成后复制进项目的图片结果。
|
||
- `review`：只在 `test/audit` 或用户明确要求时写；正式轻量生产默认不写。
|
||
|
||
普通 MV 画面可以直接走：
|
||
|
||
```text
|
||
brief -> prompt -> image
|
||
```
|
||
|
||
设计型页面通常先走：
|
||
|
||
```text
|
||
design -> 用户确认 -> brief -> prompt -> image
|
||
```
|
||
|
||
## 两条运行线
|
||
|
||
### test/audit
|
||
|
||
用于：
|
||
|
||
- 新项目早期；
|
||
- 核心画面试验；
|
||
- 角色一致性测试；
|
||
- 工作流故障调查；
|
||
- 用户要求明确 review；
|
||
- 修复或异常任务。
|
||
|
||
特点：
|
||
|
||
- 可以写更详细的记录；
|
||
- 可以用 slide Agent；
|
||
- 可以写 review 文件；
|
||
- 可以做更完整的检查。
|
||
|
||
### production-light
|
||
|
||
用于：
|
||
|
||
- 核心路线已经被接受；
|
||
- 用户授权正式生产；
|
||
- 需要稳定批量产出。
|
||
|
||
特点：
|
||
|
||
- 默认 `review: none`；
|
||
- 子会话直接写 brief、prompt、image、`slides.md` 和 compact handoff；
|
||
- 不默认启动 Agent / SubAgent；
|
||
- 不写 routine review；
|
||
- 不做完整审计，只保留必要恢复记录。
|
||
|
||
新项目默认先走 `test/audit`。只有用户明确授权后，才把 `project.md` 中的工作流切到 `production-light`。
|
||
|
||
## 两种运行模式
|
||
|
||
用户给任务时，要说清楚是下面哪一种。
|
||
|
||
### prompt only
|
||
|
||
只写 brief 和 prompt，不生成图片。
|
||
|
||
适合：
|
||
|
||
- 想先审提示词；
|
||
- 想拿去别的平台交叉验证；
|
||
- 还没授权生成；
|
||
- 高风险画面需要先看方案。
|
||
|
||
示例：
|
||
|
||
```md
|
||
请按 video-slide-production，用 prompt only 模式处理 S-03 到 S-05，review: none，先写 brief 和 prompt，不生成图片。
|
||
```
|
||
|
||
### prompt and generate
|
||
|
||
写 brief、prompt，并生成图片。
|
||
|
||
适合：
|
||
|
||
- 用户已经确认范围；
|
||
- 生产路线已经证明；
|
||
- 允许该批次直接产图。
|
||
|
||
示例：
|
||
|
||
```md
|
||
请按 production-light / prompt and generate 处理 S-10 到 S-15，review: none。使用当前 visual-system，走 gpt-image-2 Advisor + host image_gen 路线，写 compact handoff 后 callback。
|
||
```
|
||
|
||
任务级别写明 `prompt and generate` 和 slide 范围，就等于对该范围授权生成。若写的是 `prompt only`，绝不能生成图片。
|
||
|
||
## 图片提示词和参考图规则
|
||
|
||
所有项目内图片 prompt 必须通过 `gpt-image-2` Skill 工作流，不要直接凭记忆写最终 prompt。
|
||
|
||
开始 prompt 工作前，Codex 应运行：
|
||
|
||
```powershell
|
||
node C:\Users\wangq\.agents\skills\gpt-image-2\scripts\check-mode.js --json
|
||
```
|
||
|
||
当前默认成功路径是：
|
||
|
||
```text
|
||
gpt-image-2 Skill Advisor 生成 prompt/spec
|
||
-> 把真实参考图加载进对话可见上下文
|
||
-> 用宿主 image_gen 生成
|
||
-> 把结果复制到项目目录
|
||
-> 在 prompt / handoff / slides.md 中记录路径和参考角色
|
||
```
|
||
|
||
关键规则：
|
||
|
||
- 参考图必须实际加载进对话上下文；只在 prompt 里写本地路径不算。
|
||
- 身份重要的近景、脸、半身、表情，不能只靠文字描述。
|
||
- prompt 里要明确写参考图角色，例如 `Image 1: identity reference`。
|
||
- 远景 / 风景主导画面可以优先用角色锚板或项目认可的远景参考。
|
||
- 默认不要切回 Garden / API 路线，除非用户明确改变项目策略。
|
||
- 生成前要有用户授权；`prompt and generate` 的任务范围可作为本轮授权。
|
||
|
||
## 子会话和 Agent 怎么理解
|
||
|
||
简单理解：
|
||
|
||
- 主会话：跟用户说话、定义任务范围、启动子会话、接收 callback。
|
||
- 子会话：真正执行一小包生产任务，写项目文件，完成后 callback 主会话。
|
||
- Agent / SubAgent：只在 `test/audit`、repair、exception、显式 review 或特别隔离任务中用；一个 Agent 只处理一个 slide。
|
||
|
||
普通 `production-light` 默认是：
|
||
|
||
```text
|
||
主会话 -> 子会话直接生产 -> 子会话写 handoff -> 子会话 callback 主会话
|
||
```
|
||
|
||
不要在普通生产里默认开很多 Agent。也不要并行跑多个子会话，除非用户明确改规则。
|
||
|
||
子会话每次最多处理：
|
||
|
||
- 普通生产：默认最多 8 个 slide；
|
||
- 身份重、修复重、核心风险高、上下文很贵：建议 1 到 3 个 slide。
|
||
|
||
## handoff 和继续工作
|
||
|
||
长任务要靠文件继续，不靠聊天记忆。
|
||
|
||
常见记录：
|
||
|
||
```text
|
||
projects/<project>/tasks/<task-id>/task-plan.md
|
||
projects/<project>/tasks/<task-id>/task-log.md
|
||
projects/<project>/tasks/<task-id>/production-run-status.md
|
||
projects/<project>/tasks/<task-id>/session-01/child-session-handoff.md
|
||
```
|
||
|
||
生产子会话完成时，`child-session-handoff.md` 应该短，只写主会话继续需要的信息：
|
||
|
||
- 状态；
|
||
- topology；
|
||
- resolved versions；
|
||
- image paths；
|
||
- handoff path；
|
||
- problems；
|
||
- needs user。
|
||
|
||
干净完成时，主会话不需要重新审 prompt、图片细节或完整流水，只读 handoff 中的关键状态即可继续。
|
||
|
||
## 常用指令模板
|
||
|
||
### 启动新项目整理
|
||
|
||
```md
|
||
请根据 projects/<project-id>/intake/ 中已接受的材料，建立或整理 project.md、execution-plan.md、visual-system/visual-system.md、slides/slides.md。不要复制整篇规划，只抽取本地执行控制需要的信息。
|
||
```
|
||
|
||
### 修复 intake 标题
|
||
|
||
```md
|
||
projects/<project-id>/intake/ 里有 GPT Markdown 标题层级问题。请按 VIDEO_WORKBENCH.md 的 Intake Heading Repair 规则，用 fix-title Skill 通过真实 Agent / subagent 修复，输出到 intake-repair/，主会话再检查结果。
|
||
```
|
||
|
||
### 核心画面试验
|
||
|
||
```md
|
||
请对 S-03 做 test/audit 单张试验。运行模式 prompt and generate，review local-only。使用 visual-system 当前规则，图片 prompt 走 gpt-image-2 Advisor + host image_gen 路线，输出新版本，不覆盖旧文件。
|
||
```
|
||
|
||
### 转入正式轻量生产
|
||
|
||
```md
|
||
核心路线已接受。请把 project.md 的工作流切到 production-light，并为 S-10 到 S-17 建立生产任务。模式 prompt and generate，review: none，单个子会话最多 8 个普通 slide，callback 后主会话继续。
|
||
```
|
||
|
||
### 只写 prompt 不生成
|
||
|
||
```md
|
||
请用 prompt only 模式处理 S-05 到 S-07。只写 brief 和 prompt，不生成图片。每个 slide 使用下一个未占用版本，Overwrite allowed: no。
|
||
```
|
||
|
||
### 从 callback 继续
|
||
|
||
```md
|
||
请读取最新 child-session-handoff.md 和 production-run-status.md，只根据 compact handoff 继续。若 status 是 complete 且没有 problems，就更新 run state 并派发下一批；若有 blocked / failed / warning，再做针对性检查。
|
||
```
|
||
|
||
## 不要做的事
|
||
|
||
- 不要把 `tmp/` 当长期资料库。
|
||
- 不要把 GPT 规划全文复制成新的执行真相。
|
||
- 不要覆盖旧的 `sNN-vN-*` 文件。
|
||
- 不要用文字提示替代身份关键参考图。
|
||
- 不要绕过 `gpt-image-2` Skill 直接写最终图片 prompt。
|
||
- 不要默认调用外部视觉 review 服务或 Minimax MCP。
|
||
- 不要把 CCPE 内部旧路径写死成本仓库默认入口。
|
||
- 不要把可复用自动化源码直接写进 `video-workbench`；应该去 `skills-vault` 或写 supplier request。
|
||
- 不要把正式 CCPE participant 输出在主会话里角色扮演出来；需要真实 invocation 和 returned output。
|
||
|
||
## PowerShell 编码提醒
|
||
|
||
本仓库中文 Markdown 默认 UTF-8。用 PowerShell 读写时要显式指定 UTF-8：
|
||
|
||
```powershell
|
||
Get-Content -LiteralPath <path> -Encoding UTF8
|
||
Select-String -Path <path> -Pattern <pattern> -Encoding UTF8
|
||
```
|
||
|
||
不要等出现乱码后再补编码参数。
|
||
|
||
## 朋友试用前的最小检查清单
|
||
|
||
- 能打开仓库根目录。
|
||
- 新会话已经读过 `AGENTS.md`、`README.md`、`VIDEO_WORKBENCH.md`。
|
||
- 知道真实项目放 `projects/<project-id>/`，草稿才放 `tmp/`。
|
||
- 知道 `intake/` 是接受的来源材料，不是 Codex 随手重写区。
|
||
- 知道新项目先 `test/audit`，路线通过后再 `production-light`。
|
||
- 知道图片 prompt 必须走 `gpt-image-2` Skill。
|
||
- 知道身份 / 角色连续性必须用真实参考图。
|
||
- 知道所有 slide 产物 append-only，不默认覆盖。
|
||
- 知道长任务靠 handoff 和 `production-run-status.md` 继续。
|
||
|
||
## 本草稿依据的仓库文件
|
||
|
||
- `AGENTS.md`
|
||
- `README.md`
|
||
- `PROJECTS.md`
|
||
- `VIDEO_WORKBENCH.md`
|
||
- `docs/context-handoff.md`
|
||
- `docs/workflows/project-lifecycle.md`
|
||
- `docs/workflows/slide-task-orchestration.md`
|
||
- `docs/workflows/slide-task-templates.md`
|