Deckforge

DeckForge

面向人类和 AI Agent 的 API 优先演示文稿生成

---

只需一次 API 调用，即可生成适合高管使用的幻灯片。发送 JSON 中间表示（IR）或自然语言提示词，即可获得 .pptx 文件或 Google Slides 演示文稿，并具备专业布局、一致的品牌风格和经过验证的质量。

---

🚀 正在生产环境中使用 DeckForge，或想要更高的限额、优先支持或特定的幻灯片／图表功能？ 告诉我您的使用场景 → — 我会阅读每一条消息。

---

解决的问题

• 您的 Agent 需要将结构化的幻灯片规范转换为真正的 PowerPoint，而无需安装无头版 Office 或手写 python-pptx 代码。 将演示文稿 IR（幻灯片、元素、主题）发送给 render，即可获得带主题的 .pptx（或 Google Slides）演示文稿，以及质量评分和布局／QA 问题数量。
• 您的 Agent 需要根据一句提示词生成演示文稿，而无需自行设计叙事结构。 generate 运行一个包含 4 个阶段的内容流水线（意图 → 大纲 → 扩展 → 优化），用于选择幻灯片类型并编写内容，然后返回结构化 IR，供您随后传给 render。
• 您需要带有金融特色的幻灯片，而无需每次都重新构建 DCF、可比公司表、瀑布图或回报布局。 9 种金融幻灯片类型和面向金融的图表类型（瀑布图、龙卷风图、足球场图、敏感性分析表）都是一等 IR，因此模型输出的数字可以转化为可审计、带主题的幻灯片。
• 您的 Agent 必须在运行时选择有效的 slide_type、theme 和图表值，而不是靠猜测。 themes（15 种）和 slide_types（32 种：23 种通用类型 + 9 种金融类型，包含必需／可选元素）是发现工具，可返回准确的标识符和元素要求，帮助构建正确的 IR。
• 您需要在支付渲染费用前获得确定的成本估算，而无需试探性调用。 cost_estimate 根据 ceil(slides/10) 加上每张金融幻灯片和每个图表的额外费用计算点数，并返回费用明细和美元等值金额，让自主 Agent 能在执行前做好预算。
• 您希望演示文稿风格一致并经过机器检查，而无需人工进行设计审核。 每次渲染都会运行带有自动修复功能的 QA 流程，检查对比度、溢出和对齐情况，并向调用方返回 quality_score 和 qa_issues 数量。

---

功能

• 32 种幻灯片类型 -- 标题、议程、项目符号、对比、时间线、流程图、组织结构图、数据亮点、表格、图表、矩阵、漏斗、地图等
• 9 种金融专用幻灯片 -- DCF 摘要、可比公司表、瀑布图、交易概览、回报分析、资本结构、市场格局、风险矩阵、投资论点
• 24 种图表类型 -- 柱状图、折线图、面积图、饼图、环形图、散点图、气泡图、组合图、瀑布图、漏斗图、树状图、雷达图、龙卷风图、足球场图、敏感性表、热力图、桑基图、甘特图、旭日图等
• 15 种内置主题 -- corporate-blue、executive-dark、finance-pro、modern-gradient、minimal-light、tech-neon，以及另外 9 种（另支持自定义品牌套件）
• 原生 PPTX 输出 -- 使用 python-pptx 渲染，可逐元素控制、添加切换效果并嵌入图表
• Google Slides 输出 -- 通过 Google Slides API 直接导出（包含 OAuth 流程）
• AI 内容生成 -- 通过 Claude、OpenAI、Gemini 或 Ollama 将自然语言转为幻灯片（四阶段流水线：意图、提纲、扩展、润色）
• 五轮 QA 流水线 -- 自动质量检查，配备自动修复引擎，可处理对比度、溢出、对齐等问题
• 基于约束的布局 -- kiwisolver 约束求解器、12 列网格、自适应溢出处理（缩小字体、重新排版、拆分）
• MCP 服务 -- 提供 6 种工具，供 AI Agent 集成（render、generate、themes、slide_types、cost_estimate、pricing）
• x402 支付中间件 -- 为可自托管部署提供可选的按调用 USDC 支持（Base L2）；默认禁用
• 计费基础设施 -- 为可自托管部署提供 Stripe 订阅和积分系统支持（目前尚未提供付费托管方案）
• TypeScript SDK -- @lukastan/deckforge，采用流畅构建器模式，提供完整类型安全和 SSE 流式传输

快速开始

不到 5 分钟，即可从零开始生成并渲染第一份幻灯片。

前提条件

• Docker 和 Docker Compose
• Git

步骤

# 1. Clone the repo
git clone https://github.com/Whatsonyourmind/deckforge && cd deckforge

# 2. Copy environment config (works out of the box for local dev)
cp .env.example .env

# 3. Start all services (API, workers, PostgreSQL, Redis, MinIO)
docker compose up -d

# 4. Initialize the database (runs migrations, seeds test user + API key)
bash scripts/bootstrap-db.sh

# 5. Verify the API is running
curl http://localhost:8000/v1/health
# => {"status":"healthy"}

引导脚本会输出一个测试 API 密钥（dk_test_...）。请保存该密钥，以便用于以下示例。

API 示例

从 IR 渲染幻灯片

curl -X POST http://localhost:8000/v1/render \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q4 Board Update",
    "theme": "corporate-blue",
    "slides": [
      {
        "slide_type": "title_slide",
        "elements": [
          {"type": "title", "content": "Q4 2026 Board Update"},
          {"type": "subtitle", "content": "Acme Corp -- Confidential"}
        ]
      },
      {
        "slide_type": "stats_callout",
        "elements": [
          {"type": "title", "content": "Key Metrics"},
          {"type": "metric", "content": "$4.2M", "label": "ARR"},
          {"type": "metric", "content": "142%", "label": "YoY Growth"},
          {"type": "metric", "content": "94%", "label": "Retention"}
        ]
      }
    ]
  }' \
  --output board-update.pptx

从自然语言生成幻灯片

curl -X POST http://localhost:8000/v1/generate \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 10-slide pitch deck for a B2B SaaS startup in the cybersecurity space, Series A, $2M ARR",
    "theme": "executive-dark",
    "output_format": "pptx"
  }' \
  --output pitch-deck.pptx

注意： /v1/generate 端点至少需要在 .env 中配置一个 LLM API 密钥（Anthropic、OpenAI、Gemini 或 Ollama）。

查看可用主题和幻灯片类型

# List all 15 themes
curl http://localhost:8000/v1/themes

# List all 32 slide types with example IR
curl http://localhost:8000/v1/slide-types

# Estimate credit cost before rendering
curl -X POST http://localhost:8000/v1/estimate \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"slides": [{"slide_type": "title_slide"}, {"slide_type": "chart_slide"}]}'

TypeScript SDK

从 npm 安装：

npm install @lukastan/deckforge

采用流畅构建器，提供完整类型安全：

import { DeckForge, Presentation, Slides } from "@lukastan/deckforge";

const client = new DeckForge({ apiKey: "dk_test_YOUR_KEY_HERE" });

const deck = Presentation.create("Q4 Board Update", "corporate-blue")
  .addSlide(
    Slides.titleSlide({
      title: "Q4 2026 Board Update",
      subtitle: "Acme Corp -- Confidential",
    })
  )
  .addSlide(
    Slides.statsCallout({
      title: "Key Metrics",
      metrics: [
        { value: "$4.2M", label: "ARR" },
        { value: "142%", label: "YoY Growth" },
        { value: "94%", label: "Retention" },
      ],
    })
  );

const pptx = await client.render(deck);
// => Buffer containing .pptx file

通过提示词生成幻灯片并使用 SSE 流式传输：

const stream = client.generate({
  prompt: "Create a PE deal memo for a $500M LBO of a healthcare platform",
  theme: "finance-pro",
});

for await (const event of stream) {
  console.log(`${event.stage}: ${event.message}`);
}
// intent: Analyzing prompt for presentation structure...
// outline: Creating 12-slide deal memo outline...
// expand: Generating slide content...
// refine: Running QA pipeline (5 passes)...
// complete: Deck ready for download

架构

                        +------------------+
                        |    Clients       |
                        |  (curl/SDK/MCP)  |
                        +--------+---------+
                                 |
                        +--------v---------+
                        |  FastAPI (uvicorn)|
                        |  /v1/* routes     |
                        |  Auth + Rate Limit|
                        |  Credit Billing   |
                        +--+-----+------+--+
                           |     |      |
               +-----------+     |      +----------+
               |                 |                  |
      +--------v------+  +------v--------+  +------v--------+
      | Content Worker |  | Render Worker |  |   Sync Path   |
      | (ARQ + Redis)  |  | (ARQ + Redis) |  | (< 10 slides) |
      | NL -> IR       |  | IR -> PPTX    |  | Direct return  |
      +--------+------+  +------+--------+  +------+--------+
               |                 |                  |
               v                 v                  v
      +--------+------+  +------+---------+  +-----+--------+
      | LLM Adapters  |  | PPTX Renderer  |  | Google Slides|
      | Claude/GPT/   |  | Layout Engine  |  | Renderer     |
      | Gemini/Ollama  |  | Theme Resolver |  | (OAuth)      |
      +---------------+  | Chart Renderer |  +--------------+
                          | QA Pipeline    |
                          +------+---------+
                                 |
                          +------v---------+
                          |    Storage     |
                          | MinIO (dev)    |
                          | R2/S3 (prod)   |
                          +----------------+

      +----------------+  +----------------+
      |   PostgreSQL   |  |     Redis      |
      |   Users, Keys  |  |  Queue, Cache  |
      |   Jobs, Decks  |  |  Rate Limits   |
      |   Billing      |  |  SSE Pub/Sub   |
      +----------------+  +----------------+

API 路由

所有路由均挂载在 /v1 前缀下。交互式文档请访问 http://localhost:8000/docs。

端点	方法	身份验证	说明
/v1/health	GET	否	健康检查
/v1/render	POST	API 密钥	将 IR 渲染为 PPTX/Google Slides
/v1/generate	POST	API 密钥	根据自然语言生成幻灯片
/v1/preview	POST	API 密钥	生成 PNG 缩略图
/v1/estimate	POST	API 密钥	估算积分费用
/v1/jobs/{id}	GET	API 密钥	查看异步任务状态
/v1/themes	GET	否	列出可用主题
/v1/slide-types	GET	否	列出幻灯片类型及示例
/v1/decks	GET/POST/DELETE	API 密钥	幻灯片的 CRUD 操作
/v1/batch	POST	API 密钥	批量渲染多份幻灯片
/v1/webhooks	GET/POST/DELETE	API 密钥	管理 webhook 订阅
/v1/billing/*	Various	API 密钥	Stripe 订阅管理
/v1/pricing	GET	否	当前定价和套餐信息
/v1/onboard/signup	POST	否	创建账户和 API 密钥
/v1/analytics/*	GET	管理员	使用情况分析和指标
/v1/auth/google/*	GET	API 密钥	用于 Slides 的 Google OAuth 流程

环境变量

所有变量均以 DECKFORGE_ 为前缀。完整参考（含注释和示例值）请参阅 .env.example。

变量	默认值	描述
DECKFORGE_DATABASE_URL	postgresql+psycopg://...localhost	PostgreSQL 连接字符串
DECKFORGE_REDIS_URL	redis://localhost:6379/0	Redis 连接（队列、缓存、发布/订阅）
DECKFORGE_S3_ENDPOINT_URL	http://localhost:9000	兼容 S3 的存储端点
DECKFORGE_S3_ACCESS_KEY	minioadmin	S3 访问密钥（MinIO 开发环境默认值）
DECKFORGE_S3_SECRET_KEY	minioadmin	S3 秘密密钥
DECKFORGE_S3_BUCKET	deckforge	S3 存储桶名称
DECKFORGE_API_HOST	0.0.0.0	API 绑定地址
DECKFORGE_API_PORT	8000	API 端口
DECKFORGE_DEBUG	true	调试模式（生产环境中请禁用）
DECKFORGE_ENVIRONMENT	development	development / staging / production
DECKFORGE_LLM_DEFAULT_PROVIDER	claude	内容生成的默认 LLM
DECKFORGE_LLM_FALLBACK_CHAIN	claude,openai,gemini	LLM 回退顺序
DECKFORGE_ANTHROPIC_API_KEY	--	Claude 的 Anthropic API 密钥
DECKFORGE_OPENAI_API_KEY	--	OpenAI API 密钥
DECKFORGE_GEMINI_API_KEY	--	Google Gemini API 密钥
DECKFORGE_OLLAMA_BASE_URL	http://localhost:11434	Ollama 本地服务 URL
DECKFORGE_STRIPE_SECRET_KEY	--	Stripe 秘密密钥
DECKFORGE_STRIPE_WEBHOOK_SECRET	--	Stripe webhook 签名密钥
DECKFORGE_STRIPE_STARTER_PRICE_ID	--	Starter 套餐的 Stripe 价格 ID
DECKFORGE_STRIPE_PRO_PRICE_ID	--	Pro 套餐的 Stripe 价格 ID
DECKFORGE_GOOGLE_CLIENT_ID	--	Google OAuth 客户端 ID（用于 Slides）
DECKFORGE_GOOGLE_CLIENT_SECRET	--	Google OAuth 客户端密钥
DECKFORGE_GOOGLE_REDIRECT_URI	http://localhost:8000/v1/auth/google/callback	OAuth 重定向 URI
DECKFORGE_UNKEY_ROOT_KEY	--	Unkey 根密钥（生产环境身份验证）
DECKFORGE_UNKEY_API_ID	--	Unkey API ID
DECKFORGE_X402_ENABLED	false	启用 x402 USDC 支付
DECKFORGE_X402_WALLET_ADDRESS	--	Base 上用于接收 USDC 的钱包地址
DECKFORGE_X402_FACILITATOR_URL	https://x402.org/facilitator	x402 协调器端点
DECKFORGE_X402_NETWORK	eip155:8453	Base 主网链 ID

部署

Render（推荐）

托管的生产 API 运行在 Render 上，地址为 https://deckforge-api.onrender.com。DeckForge 提供 render.yaml 蓝图：

1. 在 Render 控制面板中选择 New → Blueprint，并指定此仓库 — Render 会读取 render.yaml（Web 服务 + Worker + 托管的 Postgres + Redis）。
2. 在服务的 Environment 选项卡中设置生产环境密钥（Stripe / Anthropic / S3），然后启动首次部署。

# Verify
curl https://deckforge-api.onrender.com/v1/health

Fly.io（替代方案）

DeckForge 还提供可用于生产环境的 fly.toml 和多阶段 Dockerfile。

# 1. Install Fly CLI
curl -L https://fly.io/install.sh | sh

# 2. Login and launch
fly auth login
fly launch --name deckforge-api --region iad

# 3. Provision PostgreSQL
fly postgres create --name deckforge-db --region iad
fly postgres attach deckforge-db

# 4. Provision Redis (via Upstash or Fly Redis)
fly redis create --name deckforge-redis
# Copy the REDIS_URL from output

# 5. Set production secrets
fly secrets set \
  DECKFORGE_ENVIRONMENT=production \
  DECKFORGE_DEBUG=false \
  DECKFORGE_DATABASE_URL="postgres://..." \
  DECKFORGE_REDIS_URL="redis://..." \
  DECKFORGE_S3_ENDPOINT_URL="https://..." \
  DECKFORGE_S3_ACCESS_KEY="..." \
  DECKFORGE_S3_SECRET_KEY="..." \
  DECKFORGE_S3_BUCKET="deckforge" \
  DECKFORGE_STRIPE_SECRET_KEY="sk_live_..." \
  DECKFORGE_STRIPE_WEBHOOK_SECRET="whsec_..." \
  DECKFORGE_ANTHROPIC_API_KEY="sk-ant-..."

# 6. Deploy
fly deploy

# 7. Run database migrations
fly ssh console -C "alembic upgrade head"

# 8. Verify
curl https://<your-app>.fly.dev/v1/health

Fly.io 配置要点：

• 每个 VM 配备 2 个共享 CPU、1 GB RAM
• 自动停止/启动以节省成本（至少运行 1 台机器）
• 强制使用 HTTPS，并设置并发限制（软限制 200 / 硬限制 250）
• 多进程：api（uvicorn）+ worker（ARQ）

Docker Compose（本地开发）

# Start all 6 services
docker compose up -d

# Services:
#   api             - FastAPI + uvicorn (port 8000)
#   content-worker  - ARQ worker for NL-to-IR generation
#   render-worker   - ARQ worker for IR-to-PPTX rendering
#   postgres        - PostgreSQL 16 (port 5432)
#   redis           - Redis 7 (port 6379)
#   minio           - MinIO S3-compatible storage (port 9000, console 9001)

# Check service health
docker compose ps

# View API logs
docker compose logs -f api

# Tear down (preserves data volumes)
docker compose down

# Full reset (removes data)
docker compose down -v

S3 存储选项

环境	提供商	配置
本地开发	MinIO（通过 Docker Compose）	.env.example 默认值
生产环境	Cloudflare R2	设置 S3_ENDPOINT_URL、S3_ACCESS_KEY、S3_SECRET_KEY
生产环境	AWS S3	将 S3_ENDPOINT_URL 设置为 AWS 端点
Fly.io	Fly Tigris	fly storage create，自动配置

定价

目前尚未提供定价——今天没有可供购买的付费方案。 想要托管版或商业版、更高的限额或优先支持？加入早期访问 →

此代码库中的计费代码（Stripe 订阅、积分系统、x402 USDC 中间件）是为可自托管部署准备的基础设施，默认处于禁用状态。

积分消耗（引擎机制）

每次 API 调用都会根据复杂程度消耗积分：

• 简单渲染（少于 5 张幻灯片）：1 积分
• 标准渲染（5-20 张幻灯片）：2-3 积分
• 复杂渲染（图表、财务幻灯片）：3-5 积分
• 内容生成（NL-to-IR）：+2 积分（大模型用量）

演示文稿

demos/ 中有 5 份达到生产质量的演示 IR：

演示文稿	幻灯片数	主题	用例
McKinsey Strategy	12	corporate-blue	战略咨询演示文稿
PE Deal Memo	10	finance-pro	私募股权投资委员会
Startup Pitch	12	modern-gradient	A 轮融资
Board Update	8	executive-dark	季度董事会会议
Product Launch	10	tech-neon	产品发布公告

渲染任意演示文稿：

curl -X POST http://localhost:8000/v1/render \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d @demos/mckinsey-strategy/ir.json \
  --output mckinsey-strategy.pptx

集成

MCP 服务（AI Agent）

DeckForge 包含一个 模型上下文协议 服务，提供 6 个工具：

{
  "mcpServers": {
    "deckforge": {
      "command": "python",
      "args": ["-m", "deckforge.mcp.server"]
    }
  }
}

工具：render、generate、themes、slide_types、cost_estimate、pricing

Agent 框架支持

• LangChain —— 渲染和生成工具类
• CrewAI —— 带有 action 参数的统一工具
• AutoGen —— 使用 Annotated 类型的普通函数工具

集成示例请参阅 demos/。

链接

• TypeScript SDK（@lukastan/deckforge）
• API 文档（交互式）
• API 状态
• GitHub Issues

贡献

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/my-feature）
3. 运行测试（Python 使用 pytest，TypeScript 使用 cd sdk && npm test）
4. 提交并推送
5. 发起 Pull Request

许可证

MIT

---

DeckForge —— 只需一次 API 调用，即可生成适合高管使用的幻灯片。