【科普】WPS灵犀Claw的内置工具（二）

快乐小子新
快乐小子新

  • start_write_file 与 end_write_file 工具

这两个工具是一对配合使用的工具，共同构成系统的"写作模式"机制。

start_write_file — 开启写作模式

基本信息

属性

说明

功能

准备向文件写入内容

作用

将输出模式从"聊天消息"切换为"文件写入"

参数说明

参数名

类型

是否必填

说明

path

string

是

目标文件路径，支持绝对路径或工作目录的相对路径

mode

string

否

写入模式：write（覆盖，默认）/ append（追加）

brief

string

否

简要描述操作目的（用于操作日志）

mode 模式对比

模式

说明

适用场景

write（默认）

覆盖文件原有内容

创建新文件、重新生成文件

append

在文件末尾追加内容

向已有文件追加内容、分段写入

工作原理

调用 start_write_file 后，后续的所有输出（文本内容）将直接写入磁盘文件，而不作为聊天消息展示给用户。直到调用 end_write_file 为止。

end_write_file — 结束写作模式

基本信息

属性

说明

功能

结束写作模式，保存内容到文件

作用

将 start_write_file 之后输出的所有文本捕获并写入文件

参数说明

参数名

类型

是否必填

说明

brief

string

否

简要描述操作目的（用于操作日志）

工作原理

  • 调用时不需要传入 content 参数 — 直接调用即可

  • 在 start_write_file 之后、end_write_file 之前输出的所有文本会被自动捕获并写入目标文件

  • 调用后输出模式恢复为正常的聊天消息

配合使用流程

步骤1: 调用 start_write_file(path="output/report.md", mode="write")
       → 指定目标文件，进入写作模式

步骤2: 输出文件内容（纯文本）
       → 这些内容不会显示给用户，而是被捕获

步骤3: 调用 end_write_file()
       → 将捕获的内容写入文件，退出写作模式

示意图

用户消息 → AI 回复（正常聊天） 
         → start_write_file("report.md")
              → 输出文本 A（写入文件，不展示）
              → 输出文本 B（写入文件，不展示）
              → 输出文本 C（写入文件，不展示）
         → end_write_file()
              → 文件保存完成
         → AI 回复（正常聊天，告知用户文件已生成）

典型应用场景

场景

说明

生成 Markdown 文档

AI 直接输出结构化文本保存为 .md 文件

生成 HTML 页面

AI 输出 HTML 代码保存为 .html 文件

写入配置文件

AI 生成 YAML/JSON/TOML 等配置文本

生成代码文件

AI 输出 Python/JavaScript 等源代码

分段追加日志

使用 append 模式向日志文件持续追加内容

start_write_file 和 end_write_file 是一对文件写入开关工具，前者开启"写作模式"使输出重定向到文件，后者关闭模式并保存内容。其核心优势是让 AI 可以将自身生成的文本直接持久化为文件，无需通过 Python 代码中转。

  • generate_image 工具

基本信息

属性

说明

功能

通过 AI 模型生成图像，支持文生图和图生图两种模式

最小像素

3686400 像素（保证高质量输出）

参数说明

参数名

类型

是否必填

说明

prompt

string

是

图像生成提示词，建议英文，包含风格、构图、光线、主体等细节

brief

string

否

一句话描述本次生图目的

width

integer

否

图片宽度（像素），默认 2560

height

integer

否

图片高度（像素），默认 1440

aspect_ratio

string

否

宽高比，默认 16:9

input_images

array

否

图生图模式的参考图片列表

path

string

否

图片保存目录的绝对路径，默认为工作目录

两种生成模式

模式一：文生图（Text-to-Image）

仅通过文字描述生成图像，不需要参考图片。这是最常用的模式。

调用方式： 只提供 prompt 参数即可。

示例 prompt：

A professional McKinsey-style business chart showing global market growth trends,
clean modern design, blue and white color scheme, high resolution,
flat design illustration, corporate presentation style

模式二：图生图（Image-to-Image）

基于参考图片进行风格迁移、修改或变体生成。

调用方式： 通过 input_images 参数提供参考图片。

input_images 数组中每项的结构：

字段

类型

是否必填

说明

type

string

是

参考图来源：path（本地文件路径）/ url（网络地址）

path

string

type 为 path 时必填

参考图片的本地绝对路径

url

string

type 为 url 时必填

参考图片的网络 URL

weight

number

否

参考强度 0.0～1.0，默认 1.0，值越大与参考图越相似

input_images 示例：

[
  {
    "type": "path",
    "path": "D:\\images\\reference.png",
    "weight": 0.8
  }
]
[
  {
    "type": "url",
    "url": "https://example.com/photo.jpg",
    "weight": 0.6
  }
]

aspect_ratio 宽高比选项

值

比例

典型用途

16:9（默认）

宽屏横向

幻灯片封面、网页横幅、视频封面

1:1

正方形

社交媒体头像、图标、缩略图

4:3

标准横向

传统演示文稿、文档插图

3:4

标准纵向

书籍封面、竖版海报

9:16

竖屏

手机壁纸、短视频封面、竖版海报

3:2

摄影横向

摄影作品、风景照风格

2:3

摄影纵向

人像摄影风格、竖版摄影

返回结果

生成完成后，工具会同时返回两种访问方式：

返回内容

说明

图片 URL

网络可访问的链接，可直接嵌入 HTML 或 Markdown

沙箱本地路径

本地文件系统路径，可供后续工具引用

prompt 编写最佳实践

一个好的 prompt 应包含以下要素：

要素

说明

示例

主体

画面中的核心对象

a modern office building

风格

视觉艺术风格

watercolor, flat design, photorealistic

构图

画面布局方式

centered composition, bird's eye view

光线

光照条件

soft natural light, golden hour, dramatic lighting

色调

颜色倾向

blue and white color scheme, warm tones

细节

补充细节

high resolution, clean background, minimalist

用途

预期使用场景

corporate presentation style

与其他工具的协作

协作工具

协作方式

start_write_file / end_write_file

生成图片后，将图片 URL 嵌入 HTML 或 Markdown 文件中

view_image

先用 generate_image 生成，再用 view_image 分析或验证生成结果

init_slides

生成幻灯片所需的插图、背景图、封面图

典型应用场景

场景

说明

文档插图

为报告、论文生成示意图、概念图

PPT 素材

生成幻灯片封面、背景图、装饰元素

风格迁移

基于参考图生成同风格变体

网页素材

为网站生成横幅、图标等视觉元素

数据可视化辅助

生成信息图背景、图标等补充素材

generate_image 是系统的AI 图像生成工具，支持文生图和图生图两种模式，可控制尺寸、宽高比和参考强度，生成的图片同时提供网络 URL 和本地路径，便于嵌入文档或供后续工具使用。

  • view_image 工具

基本信息

属性

说明

功能

通过视觉模型分析图片，返回文字描述或针对具体问题的回答

核心能力

图像理解，而非图像生成

参数说明

参数名

类型

是否必填

说明

question

string

是

关于图片的问题

type

string

是

图片来源类型：path（本地文件）/ url（网络地址）

paths

array

type 为 path 时必填

图片文件的绝对路径列表，最多 5 张

urls

array

type 为 url 时必填

图片的 URL 列表，最多 5 张

brief

string

否

一句话描述此次看图操作目的

支持的图片格式

格式

扩展名

PNG

.png

JPEG

.jpg / .jpeg

GIF

.gif

BMP

.bmp

WebP

.webp

TIFF

.tiff

两种图片来源

来源一：本地文件（path）

通过本地绝对路径指定图片。

{
  "question": "描述这张图片的内容",
  "type": "path",
  "paths": ["D:\\images\\photo1.png", "D:\\images\\photo2.jpg"]
}

来源二：网络地址（url）

通过网络 URL 指定图片。

{
  "question": "这张图片中有什么文字？",
  "type": "url",
  "urls": ["https://example.com/image.png"]
}

多图分析能力

view_image 支持同时分析最多 5 张图片，这使得它可以处理需要跨图比较或综合分析的场景。

多图分析要点：

能力

说明

同时上传

一次调用中传入多张图片的路径或 URL

数量上限

最多 5 张，超出会报错

来源混合

仅限同一类型（全部 path 或全部 url），不可混用

综合回答

视觉模型会综合所有图片内容回答问题

多图分析应用场景：

  • 对比多张图片的差异

  • 从多张截图中提取综合信息

  • 分析系列图片的规律或趋势

  • 验证多张生成图片的质量

question 编写指南

question 决定了分析的方向和深度，以下是常见问题类型：

问题类型

示例

适用场景

内容描述

"详细描述这张图片的内容"

了解图片整体信息

文字提取（OCR）

"图片中有哪些文字？"

从截图、照片中提取文字

数据读取

"读取图表中的数据值"

从可视化图表中获取数据

元素识别

"图片中有哪些人物/物体？"

目标检测与识别

对比分析

"这两张图有什么区别？"

多图对比

风格判断

"这张图的设计风格是什么？"

设计参考分析

质量评估

"这张图片的质量如何？有什么问题？"

生成结果验证

与其他工具的协作

协作工具

协作方式

generate_image

生成图片后，用 view_image 验证生成质量或分析内容

jupyter_cell_exec

用代码处理/下载图片后，用 view_image 分析结果

speech_to_text

先用 view_image 从截图中提取文字，再补充音频转写

PDF / 浏览器技能

从 PDF 或网页中提取图片后进行分析

典型应用场景

场景

说明

截图内容提取

分析用户截图，提取其中的文字、数据或界面信息

图表数据读取

从柱状图、折线图、饼图中读取具体数值

生成结果验证

检查 generate_image 生成的图片是否符合预期

图片描述

为无文字描述的图片生成文字说明

多图对比

比较多张方案的视觉差异

文档截图分析

从文档截图提取结构化信息

view_image 是系统的图像理解工具，通过视觉模型对图片进行"看"和"分析"，支持本地文件和网络 URL 两种来源，最多同时处理 5 张图片，可执行内容描述、OCR 文字提取、数据读取、质量评估等多种分析任务。

WPS AI WPS AI
北京
浏览 118
收藏
6
分享
6 +1
+1
全部评论