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

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

---

一、Harness 到底是什么？

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

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

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

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

核心部分	解决的问题	典型作用
上下文管理	模型到底看到了什么	系统提示词、项目文档、历史对话、任务状态
工具系统	模型到底能做什么	搜索、读写文件、调用 API、执行代码
执行编排	模型下一步该做什么	决策、分步执行、工具调用、结果回写
状态与记忆	如何跨步骤保持连续性	保存任务进度、中间结果、长期偏好
评估与观测	怎么知道自己做得对不对	结果验收、过程追踪、质量评估、错误归因
约束与恢复	出错了怎么办	权限控制、格式约束、重试机制、回滚与校验

---

二、核心工具链详解

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 解决了这些问题：

功能	说明
Provider 一键切换	支持官方 API、第三方中转、本地模型；Claude Code 支持热切换
MCP 统一管理	配一次，所有工具生效；从模板快速添加
Prompts / Skills 市场	内置 Markdown 编辑器，一键安装到所有工具
Sessions 跨工具搜索	统一历史会话管理，关键词定位
代理和测速	自动选最快节点，故障转移

技术栈： 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 的专门优化：

优化点	传统 CLI	MMX-CLI
输出	stdout 混着进度条、彩色字符	stdout 仅输出干净数据，stderr 走进度条；支持 `--quiet` + `--output json`
错误处理	读英文报错文本判断	语义化 Exit Code：鉴权失败、参数错误、超时、网络异常各有独立代号
异步控制	缺参数傻等输入	`--async` 一键开启异步，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 集合，覆盖多个领域：

Skill	功能	亮点
web-design-engineer	提升 AI 生成网页的设计品质	反俗套规则、OKLCH 色彩理论、520+ 行高级模式库
kb-retriever	本地知识库检索	分层索引、渐进式 grep、PDF/Excel 支持
gpt-image-2	图像生成	18 大类 80+ 结构化提示模板、三种运行模式
web-video-presentation	网页视频制作	详见下文视频制作部分

安装方式：

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

---

三、Harness 成熟度模型

级别	投入时间	核心配置	适用场景
Level 1 个人	1-2 小时	CLAUDE.md + 基本权限 + 基本 Hooks	个人项目
Level 2 团队	1-2 天	共享设置 + 团队 Agents + MCP + Skills	团队协作
Level 3 组织	数周	企业 MDM + 多 Agent 编排 + 工作树隔离 + 熵管理	企业级部署

---

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

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 三种播放模式

模式	参数	说明
手动	无	无音频，鼠标点击推进。适合检查画面细节，或自己录制音频
音频	`?audio=1`	手动推进，每步自动播放对应音频。自由控制节奏
自动	`?auto=1`	按空格后按音频节奏自动播放到底。配合 OBS 录屏直接出片

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

4.4 十条设计原则

1. 16:9 固定舞台：1920×1080 + transform scale 2. 全局 step 计数器：章节是 step 的纯函数，无定时器 3. 每步独占整屏：if (step === N) return 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 #工程实践 #小凯