cd backend
npm install

# 仓库里已带一份可用的 .env;也可从样例复制
cp .env.example .env

# 开发模式(watch)
npm run start:dev

# 生产模式
npm run build && npm run start:prod

Flint backend listening on http://localhost:3000/api
MCP (Streamable HTTP) endpoint: http://localhost:3000/mcp
Artifact delivery: url | store: fs(./output/artifacts) | ttl: 604800s | auth: off

# 1) 交付一个可下载的产物(默认 delivery=url)
curl -X POST http://localhost:3000/api/flint/render \
  -H 'content-type: application/json' \
  -d '{
    "backend": "echarts",
    "format": "png",
    "input": {
      "data": { "values": [{ "region": "华北", "revenue": 1284 }, { "region": "华东", "revenue": 976 }] },
      "semantic_types": { "region": "Category", "revenue": "Quantity" },
      "chart_spec": {
        "chartType": "Bar Chart",
        "title": "各区域收入对比",
        "encodings": { "x": { "field": "region" }, "y": { "field": "revenue" } },
        "baseSize": { "width": 480, "height": 300 }
      },
      "theme_spec": "economist"
    }
  }'
# → {"artifactId":"20260911-...","url":"http://localhost:3000/api/flint/artifacts/...?exp=...&sig=...",...}

# 2) 直接拿二进制(delivery=inline)
curl -X POST http://localhost:3000/api/flint/render \
  -H 'content-type: application/json' -o chart.svg \
  -d '{"backend":"vegalite","format":"svg","delivery":"inline","input":{...}}'

{
  "mcpServers": {
    "flint": {
      "transport": "streamable_http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

src/
├── main.ts                       # 入口:全局前缀 /api、CORS、body 限制、挂载 /mcp、启动日志
├── app.module.ts                 # 根模块;ConfigModule 自动加载 .env
├── health.controller.ts          # GET /api/health
├── flint/
│   ├── flint.controller.ts       # 编译 / 模板 / 主题 路由
│   ├── render.controller.ts      # 渲染 / 产物下载 路由(挂载在 /api/flint)
│   ├── flint.service.ts          # 编译与渲染的业务入口(薄封装)
│   ├── flint.types.ts            # FlintBackend 定义与别名归一化
│   ├── dto/                      # class-validator 请求体校验
│   ├── render/
│   │   ├── render-core.ts        # 三个后端的无头渲染 + 尺寸/背景处理
│   │   ├── flint-assemble.ts     # 校验、编译、Waterfall/主题/标题规范化
│   │   ├── render.types.ts       # 后端枚举与安全上限
│   │   ├── theme.tokens.ts       # ThemeSpec → 设计 token
│   │   ├── theme-map.ts          # token → ECharts / Chart.js 注入
│   │   ├── render-fonts.ts       # 字体注册与 Vega 文本测量
│   │   └── esm-loader.ts         # 在 CJS 运行时加载 ESM 包(vega/vega-lite)
│   └── artifacts/
│       ├── artifact.service.ts   # 产物读写、id、过期、签名 URL
│       ├── artifact.store.ts     # fs / s3 两种存储适配器
│       ├── artifact.config.ts    # 环境变量解析
│       ├── artifact.types.ts     # 存储接口类型
│       └── public-url.ts         # 从请求头推导对外 base URL
├── mcp/
│   ├── mcp-http.ts               # Express Router 挂载 /mcp(stateless Streamable HTTP)
│   ├── mcp-server.ts             # 工具 / 资源 / 提示词注册
│   ├── mcp-schemas.ts            # 工具入参 zod schema(拍平的 ChartAssemblyInput)
│   └── mcp-constants.ts          # /mcp 路径与 body 上限
assets/
├── fonts/                        # Liberation / DejaVu 字体
└── skills/                       # agent 编写图表/主题的规范(MCP 资源)
skill-flint-chart/                # 可选的 agent skill(让 agent 把图直接贴进回复)
scripts/generate-theme-gallery.js # 生成 3 后端 × 10 主题对比图册
docs/
├── images/                       # README 用图:4 张架构图 + 主题对比图
└── diagrams/                     # 架构图的可编辑 HTML 源文件与截图脚本

curl http://localhost:3000/api/health

# 原生模块可加载(渲染依赖)
node -e "require('@napi-rs/canvas'); console.log('canvas ok')"
node -e "require('@resvg/resvg-js'); console.log('resvg ok')"

# 编译(五后端)
curl -s -X POST http://localhost:3000/api/flint/compile \
  -H 'content-type: application/json' \
  -d '{"backend":"vega-lite","input":{"data":{"values":[{"c":"A","v":1}]},"semantic_types":{"c":"Category","v":"Quantity"},"chart_spec":{"chartType":"Bar Chart","encodings":{"x":{"field":"c"},"y":{"field":"v"}}}}}' | head -c 200

# 渲染 + 产物下载
curl -s -X POST http://localhost:3000/api/flint/render \
  -H 'content-type: application/json' \
  -d '{"backend":"chartjs","format":"png","input":{"data":{"values":[{"c":"A","v":1},{"c":"B","v":2}]},"semantic_types":{"c":"Category","v":"Quantity"},"chart_spec":{"chartType":"Bar Chart","encodings":{"x":{"field":"c"},"y":{"field":"v"}}}}}'

# MCP 工具面
curl -s -X POST http://localhost:3000/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

npm run build && npm run start:prod