Harness 工程实践深度解析：从 Claude Code 到全自动视频生产

研究日期：2025-05-11
信息来源：ConardLi 教程、Claude Code 官方文档、GitHub 开源仓库、社区实践案例

一、Harness 到底是什么？

Harness Engineering（驾驭工程）不是某个具体工具，而是一套让 AI Agent 稳定、可控、可复现地干活的系统性方法论。

模型不缺能力——GPT-4、Claude 3.5、Kimi K2 都能写代码、做设计、生成内容。问题是：怎么让它每次都做得出来？怎么让不同的人在不同的项目里都能稳定产出？怎么让效率不依赖运气？

Harness 要负责的事情就是：划定边界、管理状态、设立检查点、在关键节点拦住错误。

一个成熟的 Harness 包含六个核心部分：

二、核心工具链详解

2.1 Claude Code —— Harness 的旗舰载体

Claude Code 是 Anthropic 推出的命令行编程助手，但它远不止是一个"能在终端聊天的 AI"。到 2025 年，它已演变为一个完整的多智能体开发环境。

核心能力：

• Plan Mode（Shift+Tab）：先规划再编码。Claude 只分析和规划，不修改任何文件。把规划写入 plan.md，即使上下文被压缩也不会丢失。

• Hooks 系统：确定性执行的脚本。与 CLAUDE.md 的"建议性"指令不同，Hooks 保证动作 100% 执行。

  • PreToolUse：工具执行前触发（如写入文件前记录日志）
  • PostToolUse：工具执行后触发（如 Bash 后自动运行 lint）

• Skills 扩展：通过 SKILL.md 格式（YAML frontmatter + instructions）注入设计品味和工作流程。采用"渐进披露"架构——扫描时只需 100 token，激活后加载不超过 5K token。

• MCP 服务器：Model Context Protocol，让 Claude 直接调用外部工具（GitHub、Notion、Figma、数据库、浏览器等）。

• 子 Agent：在独立上下文中运行，适合读取大量文件或专业聚焦任务（安全审查、性能分析）。支持同时运行 5 个子 Agent。

• 权限模型：7 级层级 + AI 分类器，支持 ask/default/allow 三种模式，可配置 deny 列表（如禁止 sudo、rm -rf /、git push --force）。

2.2 CC Switch —— AI CLI 工具的"万能遥控器"

如果你同时用 Claude Code、Codex、Gemini CLI，大概率经历过这种痛苦：

• 早上想用 A 服务商的 Claude 渠道，下午想切 B 服务商
• 每切一次就要翻 ~/.claude/settings.json、~/.codex/config.toml、.env
• MCP 服务器新增了一个，要在三四个工具里分别配一遍
• 想找一个上周的对话记录，不记得是哪个工具里聊的了

CC Switch 解决了这些问题：

技术栈： React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui + Tauri 2.8 + Rust + SQLite（SSOT 设计）。

最小侵入设计——卸载 CC Switch，CLI 工具继续能用。数据存储在 ~/.cc-switch/，保留最近 10 个自动备份。

2.3 MiniMax CLI (MMX-CLI) —— 面向 Agent 的全模态命令行

传统命令行工具是给人用的，给 Agent 用会出很多问题：输出里混着进度条和彩色字符、错误只能靠读英文判断、缺参数会卡死、长任务一直占着终端。

MMX-CLI 在底层做了三项针对 Agent 的专门优化：

全模态能力：文本对话、图像生成、视频生成（异步）、语音合成（30+ 音色）、音乐创作、图像理解、网络搜索。

两行代码接入 Agent：

npx skills add MiniMax-AI/cli -y -g  # AI Agent 使用
npm install -g mmx-cli               # 终端直接使用

2.4 Garden Skills (ConardLi) —— 开源 Skill 集合

ConardLi 的 garden-skills 是一个开源 Skill 集合，覆盖多个领域：

安装方式：

npx skills add ConardLi/garden-skills
npx skills add ConardLi/garden-skills -s web-video-presentation

三、Harness 成熟度模型

四、视频效果到底是怎么做的？

4.1 核心方案：网页即视频

先声明：不是用视频生成模型做的，也没有用 NotebookLM。

答案就是网页。Vibe Coding 出来的网页。

为什么不用 Sora、Runway、Pika？

• 字体、配色、每一步停留几秒、某一帧要不要出现精确数字——网页里改几行代码就搞定
• 比视频模型抽卡稳定得多，成本也更低
• NotebookLM 做不了动画演示效果，出来的都是静态图
• Remotion 这种框架反而限制了模型本身的发挥

4.2 web-video-presentation Skill

这是 Garden Skills 中专门做视频的 Skill。它帮 Agent 构建一种 Vite + React + TypeScript 演示：看起来不是传统幻灯片，更像为录屏设计的视频舞台。

核心理念：

• 固定 16:9 舞台：内容写在 1920×1080 坐标系里，按视口缩放，没有响应式
• 全局 step 游标：点击或键盘推进 (chapter, step)，游标本地持久化
• 一步一个想法：每个节拍独占整屏，不堆叠项目符号
• 口播节拍驱动结构：讲述节奏直接映射为视觉 step
• 隐藏 chrome：进度控制悬浮才出现，录屏画面保持干净
• 动效优先：每一步都需要一个移动的视觉锚点，静态正文是坏味道

工作流（四个阶段 + 两个硬检查点）：

Phase 1  内容编写：文章 → 口播稿 + 开发大纲
    |
Checkpoint A1  用户确认：稿子 / 主题 / 素材 / 开发模式
    |
Phase 2  构建演示：Vite/React/TS 网页开发（逐章或并行）
    |
Checkpoint B  确认是否合成音频
    |
Phase 3  音频合成（可选）：MiniMax CLI 串行合成
    |
Phase 4  录屏：浏览器全屏 + 自动播放 → OBS 录制

三个硬检查点是 Skill 契约的一部分：Agent 不应该从原文一路闷头做到成品。主题选择会影响动效气质，outline 确认能避免章节节奏跑偏。

4.3 三种播放模式

自动模式的原理：第一次按空格绕过浏览器的自动播放限制，之后页面按音频时长自动推进，无需人工干预。

4.4 十条设计原则

1. 16:9 固定舞台：1920×1080 + transform scale
2. 全局 step 计数器：章节是 step 的纯函数，无定时器
3. 每步独占整屏：if (step === N) return <FullScene />
4. 口播节拍 = step：一节拍 = 一 step = 一聚焦想法
5. 隐藏的边角控件：进度条/翻页器默认 opacity 0
6. 舞台无 chrome：没有 header/footer/页码/品牌条
7. 内容驱动动画：先找内在动作，找不到才入场动画兜底
8. 多点逐个揭示：1 项 = 1 step，禁同步 stagger 上 N 项
9. 整片同一主题：颜色/字体走 token，章节间不翻表面色
10. 双源原则：script 定节拍，article 定画面密度

4.5 实战演示数据

以 Anthropic 的一篇文章为例：

• 输入：一篇博客文章
• 输出：13 个章节、100+ 细粒度讲解步骤
• 画布：固定 16:9，适配任意显示器
• 交互：底部隐藏进度条，悬浮时自由跳转
• 画面：无页眉、无页码、无品牌标识——录屏时就是一块干净画面

4.6 音频合成流程

cd presentation
npm run extract-narrations   # 扫所有 narrations.ts → audio-segments.json
npm run synthesize-audio     # 调 mmx-cli 串行合成，增量跳过已存在

合成后自动检查：哪些段时长异常（太长 = 该 step 拆分；太短 = 文案太薄），给用户最后一次校准节奏的机会。

五、完整工具链协作示例

假设你要做一个技术讲解视频：

1. CC Switch 切换到 Claude Code + 官方 Claude API
2. Claude Code 加载 web-video-presentation Skill
3. 输入文章 → Agent 产出口播稿 + outline
4. 用户确认（Checkpoint A1）
5. Agent 逐章构建 Vite/React/TS 演示
6. 用户确认（Checkpoint B）→ 选择合成音频
7. MiniMax CLI 串行合成每段口播音频
8. 浏览器开 ?auto=1，OBS 录屏一镜到底
9. 所有资产（文章、口播稿、大纲、代码、音频）进版本控制

以后换一个题材，不是从零开始——换一篇原始文章，沿着同一条流水线跑一遍。

六、关键洞察

1. Harness 不是工具，是纪律：模型有能力，但你需要系统来驾驭。划定边界、管理状态、设立检查点。

2. 网页视频的核心优势是可控：字体、配色、停留时长、精确数字——改几行代码就搞定，比视频模型抽卡稳定 10 倍。

3. 检查点是防止跑偏的关键：稿子/主题、outline、音频合成前必须停下来确认。Agent 不应该一路闷头做到成品。

4. Skills 是知识的封装：把设计品味、工作流程、质量标准封装成可复用的 SKILL.md，不同项目即插即用。

5. Agent 工具正在从"服务人类用户"转向"服务数字智能体"：MMX-CLI 的 stdout 隔离、语义化 Exit Code、异步模式，都是为 Agent 而非人类设计的。

#harness #claude-code #cc-switch #minimax-cli #garden-skills #视频制作 #agent-engineering #工程实践 #小凯