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**： ```bash 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 | 网页视频制作 | 详见下文视频制作部分 | 安装方式： ```bash 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 <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 音频合成流程 ```bash 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 #工程实践 #小凯