> **关键词**：WorkBuddy Skill、AI Agent 调度、Python 流水线、状态持久化、断点续传  
> **适用人群**：AI 工具开发者、教育科技工程师、WorkBuddy Skill 开发者

---

## 一、引言：当 AI Agent 遇上课程制作

传统的课程视频制作流程高度依赖人工：写大纲 → 做PPT → 写讲稿 → 录音 → 剪辑视频。每个环节都需要专业软件和大量时间。

**智课工坊 Lite版** 的本质，是一个**被 WorkBuddy Skill 系统调度起来的 Python 多阶段流水线**。它借助 WorkBuddy 的 Skill 触发与工具调用能力，让教师用一句自然语言就能驱动整个后端流水线自动运行。

```
用户说："帮我做一个人工智能导论的课程视频"
        ↓
WorkBuddy 识别触发词 → 加载 zhike-lite Skill
        ↓
Skill 指引 WorkBuddy 调用 Bash 工具 → 执行 zhike_pipeline.py
        ↓
Python 流水线三阶段自动运行 → 输出 MP4
```

本文将从 **Skill 开发者的视角**，深入剖析：

- WorkBuddy Skill 系统的架构与调度机制
- zhike-lite Skill 的设计与实现细节
- 如何让 AI Agent 可靠地调度复杂多阶段流水线
- 状态持久化与断点续传的工程实践

---

## 二、WorkBuddy Skill 系统架构

### 2.1 Skill 是什么？

Skill 是 WorkBuddy 的**模块化能力扩展包**，本质是一个自带"使用说明书"的目录。当 WorkBuddy 收到用户消息时，会：

1. 将所有已安装 Skill 的 `name` + `description`（元数据）注入上下文
2. 根据语义匹配度，**自动选择**最相关的 Skill
3. 加载该 Skill 的 `SKILL.md` 正文到上下文
4. 按照正文中的指令，调用工具执行任务

> **关键认知**：Skill 不是插件，不是函数，而是一份**写给另一个 AI 实例的阅读指南**。它告诉 WorkBuddy"当遇到这类任务时，你应该怎么做"。

### 2.2 三层渐进式加载（Progressive Disclosure）

Skill 系统最核心的设计思想是**上下文预算管理**：

```
┌─────────────────────────────────────────────────────┐
│  Layer 1: 元数据（name + description）               │
│  始终在上下文内，约 100 词                           │
│  → 决定"要不要触发这个 Skill"                        │
├─────────────────────────────────────────────────────┤
│  Layer 2: SKILL.md 正文                             │
│  触发后加载，建议 < 5000 词                          │
│  → 包含核心工作流程和指令                            │
├─────────────────────────────────────────────────────┤
│  Layer 3: Bundled Resources（scripts/references/assets）│
│  按需加载，理论上无限                                │
│  → 大文档、脚本、模板等重型资源                      │
└─────────────────────────────────────────────────────┘
```

这种分层设计让 WorkBuddy 可以在不爆上下文窗口的前提下，支持**数十个 Skill 同时安装**。

### 2.3 Skill 目录结构

```
zhike-lite/
├── SKILL.md              # 必需：元数据 + 指令正文
├── scripts/              # 可选：可执行脚本
├── references/           # 可选：参考文档（按需加载）
└── assets/              # 可选：输出用资源（模板/图片等）
```

#### SKILL.md 的 YAML Frontmatter

```yaml
---
name: zhike-lite
description: "无数字人版本,生成PPT+讲稿+字幕视频。适合快速预览、演示,不追求数字人效果。"
agent_created: true       # 允许 skill_manage 工具修改/删除
---
```

| 字段 | 作用 | 注意事项 |
|:---|:---|:---|
| `name` | Skill 唯一标识 | 与目录名一致 |
| `description` | 触发决策依据 | 用第三人称描述触发场景，直接影响匹配准确度 |
| `agent_created` | 可管理性标记 | 设为 `true` 才能被 `skill_manage` 工具修改 |
| `allowed-tools` | 工具白名单 | 省略则允许所有工具 |
| `disable` | 禁用开关 | `true` 时 Skill 不加载 |

#### SKILL.md 正文写作规范

正文是写给 AI 读的指令，写作时有几个关键原则：

1. **用祈使句/动词开头**（ imperative form ）  
   ✅ `"To run the Lite pipeline, execute: ..."`  
   ❌ `"You should run the Lite pipeline by ..."`

2. **描述清晰，不留歧义**  
   AI 无法"猜测你的意图"，所有路径、文件名、参数格式都要明确。

3. **渐进式披露**  
   核心流程放在 SKILL.md，大段参考文档放到 `references/` 目录，用正文中的指令告诉 WorkBuddy"何时去读哪个 reference 文件"。

---

## 三、zhike-lite Skill 开发实战

### 3.1 需求分析与触发词设计

开发 Skill 的第一步，是明确**用户会说什么来触发它**。

对于 zhike-lite，用户的自然语言输入通常有这些模式：

```
"帮我做一个关于 XX 的课程视频"
"用智课工坊生成一个 PPT 视频"
"zhike-lite 做一个 XX 的课件"
"生成一个不带数字人的课程视频"
```

将这些模式提炼成 `description` 字段：

```yaml
description: "无数字人版本,生成PPT+讲稿+字幕视频。适合快速预览、演示,不追求数字人效果。"
```

这个描述同时覆盖了**功能特点**（无数字人、PPT、讲稿、字幕）和**适用场景**（快速预览、演示），确保 WorkBuddy 能在相关对话中准确触发。

### 3.2 Skill 触发后的执行流程设计

Skill 正文的核心是一份**执行计划**。zhike-lite 的执行计划分为三个明确阶段，每个阶段结束时 WorkBuddy 会暂停等待用户确认：

```
Phase 1: 大纲生成
  → WorkBuddy 调用 AI 生成 outline.json
  → 展示给用户审阅
  → 等待确认（用户可修改后继续）

Phase 2: PPT + 讲稿生成
  → WorkBuddy 调用 Bash 执行 zhike_pipeline.py 的 PPT 生成部分
  → 生成 .pptx + frames/ + scripts.json
  → 展示讲稿给用户审阅

Phase 3: 视频合成
  → WorkBuddy 调用 Bash 执行视频合成流水线
  → 监听输出进度
  → 完成后展示最终 MP4 路径
```

这种**分阶段暂停**的设计，让教师可以在每个关键节点介入修改，而不是"一键跑完不准改"。

### 3.3 调度外部 Python 脚本

Skill 本身不执行任何代码，它**指示 WorkBuddy 去调用工具**。对于 zhike-lite，最核心的调度指令是：

```markdown
## 执行命令

使用 Bash 工具执行以下命令：

```bash
cd C:\Users\Administrator\.qclaw\workspace
python zhike_pipeline.py lite "{{主题}}"
```

WorkBuddy 收到这条指令后，会：
1. 调用 `Bash` 工具
2. 在 Windows Git Bash 环境中执行上述命令
3. 等待命令输出
4. 将输出内容读回上下文，决定下一步操作

#### 路径处理要点

Windows 下 Skill 中的路径需要注意：

- WorkBuddy 的 Bash 工具使用 **Git Bash**，路径需写成 Unix 风格：`/c/Users/Administrator/...`
- 但 `zhike_pipeline.py` 内部用 Python 的 `os.path` 处理路径，传入 Windows 风格路径（`C:\...`）也可以
- **最佳实践**：Skill 中统一使用 Windows 绝对路径，Bash 工具会自动处理转换

```bash
# Skill 中这样写，Bash 工具能正确执行
cd "C:\Users\Administrator\.qclaw\workspace"
python zhike_pipeline.py lite "人工智能导论"
```

### 3.4 状态持久化设计

多阶段流水线最大的工程挑战是：**如何确保中途失败后能从断点恢复？**

zhike-lite 采用两套状态文件：

#### `pipeline_state.json` — 阶段级状态

```json
{
  "phase1_done": true,
  "phase2_done": true,
  "phase3_done": false,
  "current_slide": 3
}
```

每次阶段切换前写入，WorkBuddy 可以通过 `Read` 工具读取该文件判断进度。

#### `checkpoint.json` — 页面级断点

```json
{
  "slide_01": {"tts": true, "video": false},
  "slide_02": {"tts": true, "video": false},
  "slide_03": {"tts": false, "video": false}
}
```

TTS 和数字人渲染是逐页进行的，每完成一页立即更新 checkpoint。崩溃恢复时，脚本读取 checkpoint 跳过已完成的页面。

#### Skill 如何感知状态？

Skill 正文中包含这样的指令：

```markdown
## 断点续传

如果用户提供了 --resume 参数，或者检测到 pipeline_state.json 存在且 phase3_done 为 false：
  1. 读取 checkpoint.json
  2. 向用户报告已完成页数
  3. 从断点继续，不重复已完成的工作
```

WorkBuddy 按照指令，先 `Read` 状态文件，再根据内容决定执行策略。

---

## 四、Skill 调度能力深度解析

### 4.1 WorkBuddy 工具生态与 Skill 的协同

Skill 本身只是"说明书"，真正的执行力来自 WorkBuddy 的工具集。zhike-lite 的运作涉及以下工具：

| 工具 | 在 zhike-lite 中的用途 |
|:---|:---|
| `Bash` | 执行 `zhike_pipeline.py` 命令 |
| `Read` | 读取 outline.json、scripts.json、状态文件 |
| `Write` | 写入用户修改后的大纲/讲稿 |
| `Edit` | 精确修改 JSON 中的某一项 |
| `Glob`/`Grep` | 检查输出文件是否存在 |
| `present_files` | 将最终 MP4 展示给用户 |

Skill 正文的本质是**编排这些工具的调用顺序和决策逻辑**。

### 4.2 多阶段流水线中的决策节点

一个设计良好的 Skill，会在关键节点让 WorkBuddy 做决策，而不是盲目执行。

**决策点 1：用户是否提供了 PPT？**

```markdown
如果用户提供了 --ppt 参数：
  跳过 PPT 生成步骤
  直接读取用户 PPT 路径，导出 frames/
否则：
  执行 AI PPT 生成流程
```

**决策点 2：大纲是否需要修改？**

```markdown
Phase 1 完成后：
  将 outline.json 的内容以可读格式展示给用户
  询问："大纲是否符合预期？如需修改请直接告诉我"
  等待用户确认后再进入 Phase 2
```

**决策点 3：TTS 服务是否在线？**

```markdown
执行视频合成前：
  先执行 `python zhike_pipeline.py check`
  如果 tts 服务返回 not OK：
    提示用户先启动 CosyVoice 服务，暂停执行
```

### 4.3 Skill 之间的协同

智课工坊实际上有三个 Skill：**zhike-pipeline**（Pro版）、**zhike-lite**（Lite版）、**zhike-basic**（用户PPT版）。

它们的关系：

```
zhike-lite  ←→  zhike-basic  ←→  zhike-pipeline
     ↑                ↑                  ↑
  共用同一份       使用用户PPT       加数字人渲染
  zhike_pipeline.py
```

Skill 正文中可以指示 WorkBuddy "如果需要数字人效果，建议用户切换到 zhike-pipeline Skill"，实现**跨 Skill 的优雅降级/升级**。

---

## 五、调试与迭代

### 5.1 Skill 调试方法

Skill 的调试比普通代码调试更特殊——你在调试的是 **AI 的行为**。

#### 方法 1：直接对话测试

在 WorkBuddy 中直接与 Skill 对话：

```
用户："用 zhike-lite 做一个 Python 入门的课程视频"
→ 观察 WorkBuddy 是否触发了正确的 Skill
→ 观察每个阶段的输出是否符合预期
→ 记录 WorkBuddy 做出错误决策的位置
```

#### 方法 2：检查 Skill 触发情况

如果 Skill 没有按预期触发，检查：

1. `description` 是否涵盖了用户的表达方式的语义空间
2. 是否有其他 Skill 的 `description` 与之冲突（优先级更高的会覆盖）
3. Skill 是否被 `disable: true` 禁用

#### 方法 3：逐步执行验证

在 Skill 正文中临时加入"暂停点"：

```markdown
## Phase 2 调试模式

执行 PPT 生成后，先不要继续：
  1. 读取 zhike_output/{主题}/ppt/ 目录
  2. 向用户展示生成的 PPT 文件路径
  3. 等待用户确认 PPT 内容正确后，再继续讲稿生成
```

### 5.2 常见坑与最佳实践

#### 坑 1：description 写得太大而误触发

```yaml
# ❌ 太宽泛，容易误触发
description: "处理视频相关的任务"

# ✅ 精准，只在真正相关时触发
description: "无数字人版本,生成PPT+讲稿+字幕视频。适合快速预览、演示,不追求数字人效果。"
```

#### 坑 2：SKILL.md 正文过长

超过 5000 词后，WorkBuddy 的上下文窗口压力增大，可能导致后续工具调用质量下降。

**解决方案**：将大段参考文档移到 `references/` 目录，在 SKILL.md 中用指令告诉 WorkBuddy 何时去读：

```markdown
## 如果需要了解 PPT 配色方案的详细色值

读取 references/theme_colors.md 获取完整配色表。
```

#### 坑 3：路径中的空格未加引号

```bash
# ❌ 路径有空格会报错
cd C:\Users\Administrator\Desktop\my project

# ✅ 加引号
cd "C:\Users\Administrator\Desktop\my project"
```

#### 坑 4：未处理命令执行失败的情况

Skill 必须告诉 WorkBuddy 命令失败怎么办：

```markdown
执行 python zhike_pipeline.py lite "主题" 后：
  如果返回非零退出码：
    读取错误输出，分析失败原因
    如果是 TTS 服务未启动：提示用户启动服务后重试
    如果是 PPT 导出失败：检查 PowerPoint 是否已安装
    向用户报告具体错误信息，不要静默失败
```

### 5.3 迭代工作流

```
编写 SKILL.md
    ↓
对话测试 → 观察 WorkBuddy 行为
    ↓
发现问题 → 修改 SKILL.md
    ↓
重新测试 → 验证修改效果
    ↓
稳定后  → 打包分享（package_skill.py）
```

---

## 六、zhike_pipeline.py 核心函数与 Skill 调度映射

为了帮助开发者理解 Skill 是如何驱动后端脚本的，以下是关键函数与 Skill 指令的对应关系：

| Python 函数 | Skill 触发命令 | Skill 中的指令描述 |
|:---|:---|:---|
| `cmd_lite(mode, theme, ppt_path)` | `python zhike_pipeline.py lite "主题"` | "执行 Lite 模式全流程" |
| `phase1(theme)` | 隐含在 `lite` 命令中 | "Phase 1: AI 生成大纲，保存 outline.json" |
| `phase2_lite(theme, ppt_path)` | 隐含在 `lite` 命令中 | "Phase 2: 生成 PPT，导出 frames，生成讲稿" |
| `phase3_lite(theme)` | 隐含在 `lite` 命令中 | "Phase 3: TTS 合成，字幕生成，视频合成" |
| `check_services()` | `python zhike_pipeline.py check` | "检查 TTS 和视频服务是否在线" |
| `show_status(theme)` | `python zhike_pipeline.py status "主题"` | "展示当前任务进度" |

Skill 开发者需要同时满足两个读者：

1. **WorkBuddy（AI）** — 读 SKILL.md 正文，决定调用哪些工具
2. **人类开发者** — 读 SKILL.md 和 Python 源码，理解整个系统如何协作

---

## 七、从 Skill 到生产：部署与分享

### 7.1 打包 Skill

Skill 开发完成后，使用内建脚本打包：

```bash
python scripts/package_skill.py C:\Users\Administrator\.workbuddy\skills\zhike-lite
```

脚本会先自动验证：

- YAML frontmatter 格式是否正确
- `name` 和 `description` 是否填写
- 目录结构是否合规
- 引用的 bundled resources 是否实际存在

验证通过后生成 `zhike-lite.zip`，可分享给其他 WorkBuddy 用户安装。

### 7.2 版本管理建议

| 场景 | 建议做法 |
|:---|:---|
| 功能新增 | 更新 SKILL.md，递增版本号（记录在文件头部） |
| Bug 修复 | 直接修改，不需要改版本号 |
| 重大重构 | 新建分支 Skill（如 zhike-lite-v2），旧版保留 |

---

## 八、总结

本文从 Skill 开发者的视角，完整剖析了智课工坊 Lite版的技术实现：

**架构层面**：WorkBuddy Skill 系统通过三层渐进式加载，在有限的上下文窗口内容纳数十个 Skill，实现了 AI Agent 能力的模块化扩展。

**调度层面**：Skill 的本质是一份写给 AI 的阅读指南，通过精心设计的 `description` 触发匹配，通过 SKILL.md 正文编排工具调用顺序，通过状态文件实现复杂流水线的断点续传。

**工程层面**：`zhike_pipeline.py` 作为后端执行引擎，负责所有重型计算（PPT 生成、TTS 合成、视频编码），Skill 则专注于"什么时候调用什么工具"的决策逻辑，实现了清晰的**关注点分离**。

```
┌─────────────────────────────────────────┐
│         用户自然语言输入                  │
│   "做一个 AI 导论的课程视频"             │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│    WorkBuddy Skill 匹配器                │
│    扫描所有 Skill 的 description         │
│    → 匹配到 zhike-lite                  │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│    加载 zhike-lite/SKILL.md             │
│    按照正文指令编排工具调用               │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│    Bash 工具 → zhike_pipeline.py        │
│    三阶段流水线自动执行                   │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│    最终输出: final/人工智能导论.mp4      │
│    present_files 展示给用户              │
└─────────────────────────────────────────┘
```

这套架构的通用性远超课程制作——任何"多阶段、有状态、需要人机协同决策"的复杂任务，都可以用同样的模式构建 Skill：**让 AI Agent 负责调度与决策，让专用脚本负责执行与计算**。

---

*本文基于 WorkBuddy Skill 系统及智课工坊 Lite版实际代码撰写。Skill 系统详情参考 WorkBuddy 官方文档，智课工坊项目持续迭代中。*


关键词：WorkBuddy Skill、AI Agent 调度、Python 流水线、状态持久化、断点续传   适用人群：AI 工具开发者、教育科技工程师、WorkBuddy Skill 开发者

基于 WorkBuddy的零门槛AI课程制作工具

“智课工坊”是为高职院校教师设计的一站式AI微课视频生成系统，应用场景包括班会微课、政策宣讲、就业指导等。系统基于腾讯WorkBuddy智能体平台构建，主要功能包括AI智能生成PPT大纲与讲稿、数字人形象与音色定制、PPT数字人讲解视频全自动合成等。

人工智能

开发工具

后端

WorkBuddySkill系统通过AI调度Python流水线实现自动化课程制作，支持状态持久化和断点续传。开发者可学习Skill架构设计、多阶段流水线调度及工程实践，提升AI工具开发效率。适用于教育科技工程师和WorkBuddySkill开发者。

代码解释

WorkBuddy 

Windows

Python

JSON

Unix

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

基于 WorkBuddy的零门槛AI课程制作工具-腾讯云开发者社区-腾讯云

基于 WorkBuddy的零门槛AI课程制作工具

基于 WorkBuddy的零门槛AI课程制作工具

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐