📐 UML Generator

About

UML Generator Web 是一个基于 Next.js 16（App Router）+ React 19 + TypeScript 的轻量后端应用，将自然语言需求转换为 uml-diagrams.org 参考风格的 PlantUML 图，并通过 Kroki 渲染为 SVG。项目开源在 github.com/samonysh/uml-generator-web。

项目仓库

核心特性

  • 模型设置页：本地配置并加密保存 LLM base_url / model_name / token（存储在浏览器 localStorage），支持凭据的导入 / 导出。
  • UML 生成页：左侧多轮对话式需求输入，右侧同步展示 PlantUML 源码、浅色 SVG 与深色 SVG。
  • LLM 调用：基于 OpenAI SDK 的 chat/completions 协议，通过 Next.js API Route 代理转发，token 不会被静态打包进前端 bundle。
  • PlantUML 生成流程：识别图类型 → 生成带强制 monochrome 前导块的 PlantUML 源 → 交由 Kroki 渲染，完整遵循 plantuml-skill 规范。
  • SVG 渲染：通过 kroki.io 完成 PlantUML → SVG，服务端注入 <style> 生成深色主题版本。
  • 下载：支持单独导出 .puml / SVG，或打包下载（包含 puml、浅色/深色 SVG、以及记录 每轮对话的 log.json）。
  • 多轮优化：后续输入会将当前 .puml 与新需求一并交给 LLM，让其在现有代码上迭代修改。

对外 REST API

除面向前端的内部路由外，本服务还在 /api/v1/plantuml/* 下提供一组稳定版 REST 接口， 任何 Agent / IDE 插件都可直接调用：

  • POST /api/v1/plantuml/generate — 自然语言 → PlantUML（可选返回 SVG）
  • POST /api/v1/plantuml/render — PlantUML → 浅色 / 深色 / 双主题 SVG
  • GET /api/v1/plantuml/render — 通过查询参数直出 image/svg+xml，可内嵌<img> 或 Markdown
  • POST /api/v1/plantuml/validate — 校验源码是否可渲染
  • POST /api/v1/plantuml/encode — Kroki 规范的 deflate + base64url 编码
  • POST /api/v1/plantuml/dark — 浅色 SVG → 深色 SVG 转换
  • GET /api/v1/health — 健康检查

与 plantuml-skill 的关系

本项目是 plantuml-skill（同名 Skill 也发布在 ClawHub）的 Web 化承载与在线服务实现：

  • plantuml-skill：定义「自然语言 → PlantUML」流水线的 system prompt、图类型识别、 uml-diagrams.org monochrome 前导块、结构化 JSON 输出协议以及 Kroki 校验 / 自愈循环等约定。
  • uml-generator-web（本项目）：把该 Skill 规范工程化落地为一个可部署的 Next.js 应用与稳定版 REST API （/api/v1/plantuml/*），任何遵循 plantuml-skill 规范的 Agent / IDE 插件都可直接调用。

简言之：plantuml-skill 定义「怎么生成」，本项目负责「怎么在线跑起来」。

技术栈

  • Next.js 16（App Router）+ React 19 + TypeScript
  • OpenAI SDK 兼容协议（chat/completions）
  • Kroki（PlantUML → SVG 渲染）
  • Vitest（单元 / 集成测试）
  • Vercel Serverless 部署适配（maxDuration / runtime = 'nodejs'）

最新更新

  • 发布流水线自动化：新增 scripts/release.py，通过环境变量统一编排预检 / 质量门槛 / 打包 / git push / GitHub Release。
  • 透明模式与模型轨迹页：新增透明模式开关与只读的模型轨迹回放页，支持完整记录并回放 LLM 调用链路。
  • 项目导入 / 导出：顶栏菜单支持导入历史 log.json 继续迭代。
  • 深色模式与响应式顶栏：新增 light / dark 主题切换（自动读取系统偏好），顶栏在窄屏下自动折叠。
  • 页面展示改进：统一卡片、按钮、代码块在两种主题下的对比度与间距。
  • 导航栏按钮重设计：重排顶栏操作区，「新建项目」通过 URL 参数触发生成器页面 state reset，在 Vercel 生产环境下也能稳定清空客户端 state。

License

本项目采用 MIT License 开源，详见仓库根目录的 LICENSE 文件。

⚠ 使用远程 Kroki 会将 PlantUML 源码 POST 到 kroki.io。请勿在包含机密业务逻辑的场景下使用。