【科普】WPS灵犀Claw的内置工具（三）
- init_slides 工具
基本信息
属性 | 说明 |
功能 | 根据三个 XML 配置文件生成 PPTX 构建脚本 |
定位 | PPT 生成的"中间编译器"——输入设计规范 + 内容大纲 + 图片描述，输出可执行的构建脚本 |
参数说明
参数名 | 类型 | 是否必填 | 说明 |
workspace_path | string | 是 | PPT 工作目录的绝对路径，该目录下必须包含三个 XML 文件 |
前置依赖：三个 XML 配置文件
调用 init_slides 之前，必须在 workspace_path 指定的目录下准备好以下三个文件：
文件名 | 用途 | 说明 |
design.xml | 样式规范文件 | 定义 PPT 的视觉风格（字体、颜色、布局等） |
outline.xml | 内容大纲文件 | 定义每页幻灯片的内容结构（标题、正文、数据等） |
images.xml | 图片描述文件 | 定义各页面所需的图片及其描述 |
工作流程
init_slides 在整个 PPT 生成流程中处于中间环节：
步骤1: 准备三个 XML 文件
├── design.xml （样式规范）
├── outline.xml （内容大纲）
└── images.xml （图片描述）
步骤2: 调用 init_slides(workspace_path="D:\\ppt_workspace")
→ 读取三个 XML 文件
步骤3: 返回 PPTX 构建脚本的路径
→ 后续通过 jupyter_cell_exec 执行该脚本
步骤4: 执行构建脚本
→ 生成最终的 .pptx 文件流程示意图
design.xml ─┐
outline.xml ─┼─→ init_slides ─→ 构建脚本(.py) ─→ 执行 ─→ .pptx 文件
images.xml ─┘三个 XML 文件详解
1. design.xml — 样式规范
定义 PPT 的全局视觉风格和设计规范。
典型内容：
规范项 | 说明 |
主题色 / 辅助色 | 主色调、强调色、背景色 |
字体 | 标题字体、正文字体、字号 |
版式 | 标题页、内容页、图表页等布局模板 |
Logo / 水印 | 品牌元素的位置和样式 |
动画 / 过渡 | 页面切换效果、元素动画 |
2. outline.xml — 内容大纲
定义 PPT 的内容结构，按页组织。
典型内容：
内容项 | 说明 |
页面标题 | 每页的标题文字 |
正文内容 | 要点列表、段落文字 |
数据/图表 | 需要展示的数据和图表类型 |
页面层级 | 章节页、内容页、总结页等 |
页面顺序 | 幻灯片的排列顺序 |
3. images.xml — 图片描述
定义各页面所需配图及其描述信息。
典型内容：
描述项 | 说明 |
图片位置 | 对应哪一页幻灯片 |
图片描述 | 图片内容的文字描述（可用于 generate_image 生成） |
图片尺寸 | 期望的图片大小或比例 |
图片样式 | 是否圆角、阴影、边框等 |
与 PPT SKILL 的关系
init_slides 是 PPT 生成流程中的一个环节，通常配合 PPT SKILL 使用：
阶段 | 工具/技能 | 职责 |
需求理解 | PPT SKILL | 理解用户需求，规划 PPT 结构 |
XML 准备 | AI 生成 | 编写 design.xml、outline.xml、images.xml |
脚本生成 | init_slides | 根据 XML 生成构建脚本 |
图片生成 | generate_image | 根据 images.xml 生成配图 |
脚本执行 | jupyter_cell_exec | 运行构建脚本生成 .pptx |
与其他工具的协作
协作工具 | 协作方式 |
start_write_file / end_write_file | 编写 design.xml、outline.xml、images.xml 三个配置文件 |
generate_image | 根据 images.xml 中的描述生成实际图片，供构建脚本引用 |
jupyter_cell_exec | 执行 init_slides 返回的构建脚本，生成最终 PPTX |
view_image | 验证生成的图片是否符合 images.xml 中的描述 |
返回值
返回内容 | 说明 |
构建脚本路径 | 一个 Python 脚本文件的路径，执行该脚本即可生成 .pptx 文件 |
典型应用场景
场景 | 说明 |
麦肯锡风格报告 | 通过 design.xml 定义麦肯锡视觉规范，outline.xml 定义咨询报告内容 |
数据汇报 PPT | 在 outline.xml 中定义图表页，配合数据生成可视化 |
产品发布演示 | images.xml 定义产品配图，design.xml 定义品牌视觉 |
培训课件 | 多页结构化内容，统一的样式规范 |
init_slides 是系统的 PPT 构建脚本编译器，以 design.xml（样式）、outline.xml（内容）、images.xml（图片）三个配置文件为输入，输出一个可执行的 Python 构建脚本，是结构化 PPT 生成流程中的核心中间环节。
- speech_to_text 工具详解
基本信息
属性 | 说明 |
功能 | 将音频文件中的语音内容转录为文字 |
核心能力 | 语音识别（Speech Recognition / ASR） |
参数说明
参数名 | 类型 | 是否必填 | 说明 |
path | string | 是 | 音频文件的路径，支持绝对路径或工作目录的相对路径 |
brief | string | 否 | 一句话描述操作目的（用于操作日志） |
参数非常简洁，只需提供音频文件路径即可。
支持的音频格式
格式 | 扩展名 | 说明 |
MP3 | .mp3 | 最常见的音频格式，压缩率高，兼容性广 |
WAV | .wav | 无损音频格式，音质好，文件较大 |
PCM | .pcm | 原始脉冲编码调制格式，未经压缩的数字音频 |
工作原理
音频文件(.mp3/.wav/.pcm)
│
▼
speech_to_text
│
▼
纯文本输出
│
▼
后续处理（文档创建、内容分析等）调用流程：
步骤1: 确认音频文件路径
→ 本地路径或工作目录相对路径
步骤2: 调用 speech_to_text(path="recordings/meeting.mp3")
→ 工具上传/读取音频文件
步骤3: 返回转录后的纯文本
→ 后续可直接使用文本内容转录结果特性
特性 | 说明 |
输出格式 | 纯文本（Plain Text） |
包含内容 | 语音中识别出的文字 |
不包含内容 | 不含时间戳、说话人识别等结构化信息 |
语言 | 取决于音频中的语言，工具自动识别 |
与其他工具的协作
协作工具 | 协作方式 |
start_write_file / end_write_file | 将转录文本保存为文档（.md、.txt 等） |
jupyter_cell_exec | 对转录文本进行进一步处理（分词、关键词提取、摘要等） |
PPT / docx SKILL | 将会议录音转录为会议纪要文档或汇报 PPT |
view_image | 搭配使用，从图片中提取文字 + 从音频中提取语音，实现多模态信息采集 |
典型应用场景
场景 | 说明 |
会议录音转写 | 将会议录音转为文字，整理为会议纪要 |
访谈记录 | 将访谈/采访音频转录为文本记录 |
语音备忘录 | 将语音备忘转为文字笔记 |
课程/讲座录音 | 将教学录音转录为文字稿 |
语音消息处理 | 将收到的语音消息转录为可编辑文字 |
播客/音频内容 | 将播客等音频内容转为文字便于检索和分析 |
局限性
局限 | 说明 |
仅支持 3 种格式 | 仅支持 mp3、wav、pcm，不支持 mp4、m4a、ogg、flac 等格式 |
纯文本输出 | 不含时间戳、说话人分离等高级信息 |
无音频编辑能力 | 只能转录，不能裁剪、合并或编辑音频文件 |
speech_to_text 是系统的语音转文字工具，支持 mp3、wav、pcm 三种音频格式，输入音频文件路径即可获得纯文本转录结果，适用于会议记录、访谈整理等语音内容文字化场景，但输出仅为纯文本，不含时间戳等结构化信息。
- pip_install 工具
基本信息
属性 | 说明 |
功能 | 在当前 Python 环境中使用 pip 安装缺失的 Python 包 |
运行环境 | 与 jupyter_cell_exec 共享同一个 Jupyter 内核环境 |
参数说明
参数名 | 类型 | 是否必填 | 说明 |
packages | array | 是 | 要安装的 Python 包列表，可附带版本限定符 |
upgrade | boolean | 否 | 是否升级已安装的包，默认 false |
index_url | string | 否 | 自定义 PyPI 源地址（如国内镜像），留空使用默认 PyPI |
brief | string | 否 | 简要描述操作目的（用于操作日志） |
packages 参数详解
packages 是一个字符串数组，支持以下写法：
写法 | 示例 | 说明 |
仅包名 | "pandas" | 安装最新版本 |
指定最低版本 | "numpy>=1.24" | 安装 1.24 及以上版本 |
指定精确版本 | "requests==2.31.0" | 安装指定版本 |
指定版本范围 | "django>=3.2,<4.0" | 安装范围内版本 |
多包批量安装 | ["numpy", "pandas", "matplotlib"] | 一次安装多个包，通过一条 pip install 命令执行 |
批量安装优势： 多个包会通过一次 pip install 命令安装，自动处理包之间的依赖关系，比逐个安装更高效。
upgrade 参数
值 | 说明 |
false（默认） | 已安装的包自动跳过，不会重复安装 |
true | 强制升级已安装的包到最新版本 |
index_url 参数
场景 | 说明 |
留空（默认） | 使用官方 PyPI 源 pypi.org |
国内镜像 | 加速下载，如清华源、阿里源等 |
常见国内镜像源：
镜像 | index_url |
清华大学 | |
阿里云 | |
中国科技大学 | |
豆瓣 |
使用时机
根据环境设计，pip_install 有明确的使用策略：
触发条件 | 动作 |
jupyter_cell_exec 执行时遇到 ModuleNotFoundError / ImportError | 调用 pip_install 安装缺失包 |
用户明确要求安装某个 Python 包 | 直接调用 pip_install |
运行脚本前需确保依赖就绪 | 预判性地调用 pip_install |
包已存在且版本满足 | 无需安装，pip_install 会自动跳过 |
关键特性
特性 | 说明 |
自动跳过 | 已安装的包会自动跳过，无需重复安装 |
无需重启 | 安装完成后无需重启解释器，可直接在后续 jupyter_cell_exec 中 import 使用 |
批量安装 | 多个包通过一条命令安装，自动处理依赖关系 |
完整输出 | 返回 pip 命令的完整输出，便于排查安装问题 |
标准使用流程
步骤1: jupyter_cell_exec 尝试导入模块
→ import some_library
步骤2: 遇到 ModuleNotFoundError
→ 识别缺失的包名
步骤3: 调用 pip_install(packages=["some_library"])
→ 安装缺失包
步骤4: jupyter_cell_exec 再次导入
→ import some_library ✓ 成功常见陷阱
陷阱 | 说明 | 解决方案 |
包名 ≠ 模块名 | pip install Pillow 但 import PIL | 安装时用 PyPI 上的包名，导入时用模块名 |
顺序错误 | 先执行代码再安装包 | 必须在执行依赖该库的代码之前完成安装 |
版本冲突 | 新包与已安装包的依赖版本不兼容 | 使用精确版本限定或创建虚拟环境 |
大型包耗时 | 如 torch、tensorflow 等 | 安装可能需要较长时间，耐心等待 |
pip_install 是系统的 Python 包管理工具，在 jupyter_cell_exec 遇到缺失依赖时按需安装，安装后无需重启即可使用，支持版本限定、批量安装和自定义镜像源，是代码执行环境的核心保障。
