前言

前两篇分别介绍了 VisNote 笔记工坊的 v1.0 和 v2.0，从最初的小红书配图工具，到新增封面图模板、导出优化，项目在持续迭代。

这一次，我做了一个比较大的功能扩展——给 VisNote 加上了 Skill 能力，让用户可以通过 AI 智能体（比如 OpenClaw、Claude 等）直接调用 VisNote 的模板生图。

简单说：你不用打开网页，跟 AI 说一句话就能出图。

本文讲清楚这个 Skill 的设计思路、技术实现方案、以及开发过程中的思考。

一、项目介绍

项目名称：VisNote 笔记工坊 v3.0

定位升级：

• 继续深耕小红书配图场景
• 新增 AI Skill 接口，支持智能体直接生图
• 提供开放 API，任何 AI Agent 都可以接入

在线体验：https://vis-note.netlify.app

本次核心新增：

1. VisNote Image Creator Skill——让 AI 智能体直接调用模板生图
2. 开放模板 API——获取所有可用模板及数据结构
3. API Key 机制——安全管控调用权限和配额

二、为什么要做 Skill？

做这个功能之前，我一直在思考一个问题：

VisNote 已经是个好用的网页工具了，为什么还要做 Skill？

原因有三：

1. 工作流整合：很多博主的内容创作流程已经离不开 AI（选题、写文案、做计划）。如果能直接在对话中生图，就不用来回切换工具。
2. 降低使用门槛：有些用户觉得"选模板 → 改文字 → 导出"还是多了一步。Skill 做到的是你说需求，AI 帮你出图。
3. 开放生态：把生图能力开放出去，任何 AI Agent 都能接入，这比单个工具的价值大得多。

三、Skill 的技术设计思路

1. 整体架构

整个 Skill 的工作流程：

用户（对话）→ AI 智能体 → 读取 Skill 文档 → 调用 VisNote API → 生成图片 → 返回给用户

核心是三件事：

• Skill 文档：告诉 AI 智能体"怎么用" VisNote
• 模板 API：让 AI 获取可用模板和数据结构
• 生图接口：AI 组装数据，调用接口完成生图

2. Skill 文档设计

Skill 的核心是一份文档（skill-document.md），AI 智能体阅读后就知道怎么操作。

阅读 https://vis-note.netlify.app/skill-document.md 并按照指引使用 VisNote 生图

文档包含了：

• 安装步骤
• API Key 配置方式
• 模板列表接口说明
• 生图指令格式
• 数据结构示例

这个设计思路参考了 OpenClaw 的 Skill 生态，文档即协议——只要 AI 能读懂，就能接入。

3. API Key 机制

安全方面做了简单但有效的管控：

• 用户在 VisNote 个人主页生成专属 API Key
• Skill 配置文件中填入 Key 才能调用
• 每次生图消耗用户配额

这样既保证了开放性，又不会被滥用。

四、核心模板库

Skill 目前支持多种模板风格：

模板 ID	风格	适用场景
yellow	高对比大字报	避坑/干货/教程
magazine	杂志风格	时尚/生活类
glass	玻璃拟态	科技/产品类
wechat	微信风格	公众号/朋友圈
newspaper	报纸风格	新闻/资讯类
singleCard	单卡片	金句/语录
academicNotes	学术笔记	学习/知识分享
memo	便签	日常/随手记
letterhead	信纸	正式/长文类

模板数量还在持续增加，通过 API 可以随时获取最新列表。

五、开发踩坑 & 经验

1. AI 能不能"读懂"接口文档？

这是最开始最担心的点。后来发现，只要文档结构清晰、示例完整，主流 AI 智能体都能正确理解并调用。

关键技巧：

• 每个字段都给示例值，不要只写类型
• 给完整的 curl/request 示例，不要只描述
• 错误情况也写清楚，减少 AI 的试错成本

2. 数据结构一致性

Skill 生图依赖 API 返回的 value 字段来组装数据。这意味着模板的数据结构必须稳定，不能随意改字段名或类型。

我的做法：

• 新增字段可以，但旧字段不删不改
• 数据结构变更时同步更新 API 文档
• 做了版本化的模板管理，方便后续迭代

3. 渲染一致性

用网页编辑出来的图，和通过 API 生成的图，必须完全一致。

这个问题的根源是：网页端用的是浏览器渲染，API 端用的是无头渲染。两者的字体加载、CSS 计算、图片处理可能存在差异。

解决方案：

• 统一使用 html-to-image 库
• 确保 API 端和网页端引用相同的字体和样式
• 做了大量的对比测试

4. 错误处理与用户体验

AI 调用失败时，需要给用户清晰的反馈：

• API Key 无效 → 提示重新配置
• 配额不足 → 提示升级或等待
• 模板数据格式错误 → 返回具体哪个字段有问题

好的错误信息能让 AI 智能体自动修正请求，而不需要反复人工干预。

六、使用方式

用户使用非常简单，三步搞定：

第一步：安装 Skill

把下面的指令发给你的 AI 智能体：

阅读 https://vis-note.netlify.app/skill-document.md 并按照指引使用 VisNote 生图

第二步：配置 API Key

AI 会引导你完成 API Key 配置（从 VisNote 个人主页获取）。

第三步：直接生图

跟 AI 说你要什么图，它会自动选择模板、组装数据、调接口生成。

比如：

帮我生成一张小红书封面图，标题是"Next.js 实战踩坑记录"，副标题是"3个让我头秃的Bug"，标签"干货分享"

AI 就会自动完成模板选择和数据填充。

七、对比前两版的变化

功能	v1.0	v2.0	v3.0（本次）
模板数量	20+	35+	35+（持续增加）
网页编辑	✅	✅	✅
Skill 生图	❌	❌	✅
开放 API	❌	❌	✅
API Key 管理	❌	❌	✅
AI 智能体接入	❌	❌	✅

八、总结

这次做 Skill 功能，最大的感受是：工具的未来不是越做越重，而是越来越"轻"。

网页端是 v1，API 是 v2，Skill 是 v3——用户离工具越来越近，操作步骤越来越少，最终目标是一句话出图。

对做类似项目的开发者，几点建议：

1. 接口先行：如果有可能，从一开始就把核心功能做成 API，网页只是 API 的一个前端。这样后续做 Skill、做开放平台都很自然。
2. 文档即产品：AI 时代，文档不只是给人看的，也是给 AI 看的。写好 Skill 文档，就是在做产品。
3. 保持简单：Skill 的安装和使用流程尽量做到三步以内。用户不会为了一个功能读一篇文章。

体验地址

欢迎体验 VisNote 笔记工坊 v3.0：
https://vis-note.netlify.app

想试试 Skill 生图功能的，访问你的 AI 智能体，发送以下指令即可：

阅读 https://vis-note.netlify.app/skill-document.md 并按照指引使用 VisNote 生图

后续会继续迭代，感兴趣的可以收藏关注一波 🚀