# 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.md intake/ execution-plan.md visual-system/ slides/ tasks/ handoff/ docs/ investigations/ requirements/ garden-gpt-image-2/ tmp/ ``` 常用含义： - `projects/`：所有真实项目都放这里。不要按 active / completed / series 分目录。 - `projects//intake/`：放用户接受的 GPT V2 规划、原始材料、参考说明、图片等。 - `projects//project.md`：项目小地图，记录状态、阶段、关键文件和下一步。 - `projects//execution-plan.md`：执行控制文件，记录当前生产策略、批次、轮次、下一步。 - `projects//visual-system/`：视觉系统权威位置，包括风格、角色、场景、参考图。 - `projects//slides/`：实际 slide / shot / page 单元区。 - `projects//tasks/`：长任务、子会话、生产批次、callback、handoff 的本地记录。 - `handoff/`：跨项目、跨阶段、上下文压缩时使用的仓库级交接。 - `docs/workflows/`：工作流规则。 - `investigations/`：有保存价值的实验和调查。 - `tmp/`：短期草稿，不放长期证据。 ## 一个新项目的最小流程 ### 1. 放入原始输入 把已经接受的 GPT / 用户材料放到： ```text projects//intake/ ``` 这些材料可以是： - GPT V2 输出的整体规划； - 视觉系统建议； - 分镜 / 页面骨架； - 参考图、角色说明、风格说明； - 用户自己的补充资料。 不要一开始就重写它们。`intake/` 是来源，Codex 后续会从中抽取本地执行文件。 ### 2. 建立项目控制文件 让 Codex 创建或整理： ```text projects//project.md projects//execution-plan.md projects//visual-system/visual-system.md projects//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//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//tasks//task-plan.md projects//tasks//task-log.md projects//tasks//production-run-status.md projects//tasks//session-01/child-session-handoff.md ``` 生产子会话完成时，`child-session-handoff.md` 应该短，只写主会话继续需要的信息： - 状态； - topology； - resolved versions； - image paths； - handoff path； - problems； - needs user。 干净完成时，主会话不需要重新审 prompt、图片细节或完整流水，只读 handoff 中的关键状态即可继续。 ## 常用指令模板 ### 启动新项目整理 ```md 请根据 projects//intake/ 中已接受的材料，建立或整理 project.md、execution-plan.md、visual-system/visual-system.md、slides/slides.md。不要复制整篇规划，只抽取本地执行控制需要的信息。 ``` ### 修复 intake 标题 ```md projects//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 -Encoding UTF8 Select-String -Path -Pattern -Encoding UTF8 ``` 不要等出现乱码后再补编码参数。 ## 朋友试用前的最小检查清单 - 能打开仓库根目录。 - 新会话已经读过 `AGENTS.md`、`README.md`、`VIDEO_WORKBENCH.md`。 - 知道真实项目放 `projects//`，草稿才放 `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`