LeaferAgent（Vizard）

我们是AI超级画板，它能将普通的画布变成一个“所画即所得”的智能沙盘。在这里不仅能输入文字，还可以通过手绘草图或手写公式与AI进行交流。你可以画出下落的物块与弹簧来触发连贯的物理碰撞动画，手写函数公式让其生成3D Manim演示视频，甚至只需在画板上手写“新闻”等简短提示，AI就会跳过枯燥的文本回复，直接生成UI资讯卡片。它不只是一个单纯的记录工具，而是一位能实时理解你的意图、并将思考过程转化为精美视觉演示的智能助理。

许可证

本项目采用 PolyForm Noncommercial 1.0.0 许可证发布。

• 允许查看、学习、修改和非商业用途下的再分发
• 禁止将本项目或其衍生版本用于商业用途
• 详细条款见仓库根目录的 LICENSE

这意味着本仓库是源码公开的，但不属于 OSI 定义下的“开源软件”。

系统架构

用户输入 → Web Editor / AIPanel / CLI → CloudRun project-agent → workspace / skill package
                                                          ↓
                                               腾讯云 CloudBase (云开发)
                                               ├── Cloud Function (slide-api) -> 画布数据保存与查询 (NoSQL)
                                               └── CloudRun (leafer-renderer) -> 后端渲染 (PNG / MP4视频导出 / Kokoro-js TTS 语音)

根目录 agent.py / react_agent.py / gen_server.py / prompts/ 为冻结的 legacy prompt 流水线，不再作为正式运行路径。

环境要求

依赖	版本要求	用途
Python	>= 3.12	AI Agent 运行环境
Node.js	>= 18.x	前端开发服务器
uv	最新版	Python 包管理（推荐）

快速开始

1. 克隆项目

git clone <repo-url>
cd LeaferAgent

2. 配置环境变量

# 复制模板文件
cp .env.template .env

编辑 .env，至少填入一个 AI 服务的 API Key：

# 推荐：使用 Google Gemini（免费额度较高）
GEMINI_API_KEY="your-gemini-api-key"

# 或使用 OpenAI 兼容接口
OPENAI_API_KEY="your-openai-api-key"
OPENAI_API_BASE="https://api.openai.com/v1"

完整的环境变量说明见 .env.template

3. 安装 Python 依赖

# 使用 uv（推荐）
uv sync

4. 安装 Node.js 依赖

npm install

5. 启动前端开发环境

本项目 Node.js 渲染端已重构并部署至腾讯云开发 (CloudBase)：

• 幻灯片数据接口 (/api/list, /api/save, /api/read) 由 Cloud Function slide-api 提供，底层采用云数据库 NoSQL (slides 集合) 存储。
• 渲染与音视频接口 (/api/png, /api/video, /api/tts, /tts-audio) 由 CloudRun leafer-renderer 提供，容器内部集成了 FFmpeg 与 KokoroJS 语音合成引擎。

启动 Vite 前端服务器（会自动代理 API 请求至云端）：

npm run dev

这将会启动浏览器，访问 http://localhost:5173。

使用方法

方式一：Legacy Python Prompt 流水线（冻结参考）

编辑 agent.py 中的 user_request，然后运行：

# 使用 uv
uv run python agent.py

# 或直接运行
python agent.py

方式二：正式运行时与浏览器可视化编辑

npm run dev

打开 http://localhost:5173，通过编辑器界面直接拖拽、编辑画布，或通过 AIPanel 调用 project-agent 进行会话式生成、批改与修复。

环境变量详细说明

.env.template 中包含以下配置项：

分组	变量名	说明
OpenAI	OPENAI_API_KEY	API Key
	OPENAI_API_BASE	自定义 API 地址（用于代理或兼容服务）
Google Gemini	GEMINI_API_KEY	Gemini API Key
	GEMINI_API_BASE	自定义 Gemini API 地址（可选）
Azure OpenAI	AZURE_API_KEY / AZURE_API_BASE / AZURE_API_VERSION	Azure 部署配置
Langfuse	LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY	可观测性追踪（可选）

项目结构

LeaferAgent/
├── agent.py                 # 冻结的 legacy Python Agent
├── react_agent.py           # 冻结的 legacy 单页 ReAct Agent
├── utils_agent.py           # 冻结的 legacy prompt 工具函数
├── vite.config.js           # Vite 前端配置代理
├── src/                     # 前端源码（LeaferJS 编辑器）
├── cloudfunctions/          
│   └── slide-api/           # (部署) 基于 CloudBase 的云函数，负责 Slide CRUD
├── cloudrun/    
│   ├── leafer-renderer/     # (部署) 基于 CloudRun 的 Node.js 渲染引擎 & TTS
│   └── project-agent/       # 正式运行时，使用 skills 驱动会话式 Agent
├── prompts/                 # 冻结的 legacy prompt 资产，只读参考
├── slides/                  # AI 生成的本地输出（JSON格式）
└── pyproject.toml           # Python 配置

发布说明

如果你准备公开此仓库，建议同时确认以下内容：

• .env、服务密钥、云资源凭证和私有地址没有进入版本控制
• 示例数据、导出数据和媒体素材具备可公开分发权限
• 若仓库包含第三方素材或模型资源，继续遵守它们各自的许可证要求