Qling Client

中文 | English

中文

项目简介

Qling Client 是 Qling 桌面 AI 平台的客户端，核心目标是让 AI 从“文本聊天”升级为“可交互应用”。
用户不仅能对话，还可以通过按钮、表单、滑块、单选框等 UI 控件完成任务，并将能力封装成 Q-App 进行分发和复用。

项目优势

• AI 应用化体验: 相比纯聊天窗口，Qling 让 AI 输出结构化交互界面，降低使用门槛。
• Q-App 生态: 支持构建、安装、管理和运行 AI 小应用，便于形成可复用能力库。
• 多模型接入: 支持 OpenAI、Anthropic、Gemini、DeepSeek、Groq、Mistral、xAI、Perplexity、Ollama 等。
• 本地优先安全: API Key 本地存储，不上传到客户端仓库或第三方托管服务。
• 桌面能力融合: 基于 Electron，具备系统级能力扩展空间（文件、窗口、权限控制等）。
• 多语言支持: 内置中文、英文、日文、韩文国际化能力。

开源范围说明

本仓库 仅包含客户端代码（Electron + React）。
不包含后端服务、管理后台、部署脚本等服务端项目。

如果你是首次接入，请准备一个可用的 Qling 后端 API 地址，并配置到 VITE_API_URL。

技术栈

层级	技术
桌面框架	Electron 33
前端	React 19 + TypeScript
构建工具	Vite 6 + electron-builder
AI SDK	Vercel AI SDK（多供应商）
渲染/UI	Tailwind CSS 4 + JSON Render
3D 能力	Three.js + React Three Fiber

快速开始

1) 环境要求

• Node.js >= 18
• npm（或 pnpm/yarn，自行适配命令）

2) 配置环境变量

cp .env.example .env

将 .env 中的 VITE_API_URL 改为你的后端地址，例如:

VITE_API_URL=http://localhost:4000

Windows PowerShell 可用:

Copy-Item .env.example .env

3) 安装并启动开发环境

npm install
npm run dev

常用命令

npm run dev        # 本地开发
npm run lint       # 代码检查
npm run build      # 构建前端与 Electron 产物
npm run pack       # 打包 Windows 安装包
npm run pack:dir   # 仅输出目录，不生成安装器

npm run pack 的输出位于 release/ 目录。

Q-App 开发模式

Q-App 运行在客户端内置运行时中，常见两种模式:

• 默认模式（Default Mode）: 使用 JS/TS 类与生命周期（如 onInit、onActivate、onDeactivate）。
• 自定义界面模式（Custom Mode）: 使用 HTML 页面，通过注入的 app 对象访问 AI、存储和文件能力。

项目结构

src/
  pages/         # 页面级功能
  components/    # 通用 UI 组件
  contexts/      # React 上下文
  services/      # 业务服务（AI、认证、应用等）
  qapp/          # Q-App 运行时核心
  qapps/         # 内置 Q-App
  types/         # 类型定义
  utils/         # 工具与 i18n
electron/
  main.ts        # Electron 主进程
  preload.ts     # 安全 IPC 桥接
  ai-ipc.ts      # AI 流式通信 IPC
  ai-service.ts  # 多模型接入服务

贡献

• 欢迎提交 Issue 和 PR。
• 提交前建议执行 npm run lint。
• 涉及功能改动时，请补充必要说明和测试步骤。

许可证

本项目使用 MIT License。

---

English

Overview

Qling Client is the desktop client of the Qling AI platform.
Its core idea is to move from plain chat to interactive AI applications.
Instead of only text responses, AI can drive app-like UI interactions with controls such as buttons, forms, sliders, and selectors.

Why Qling Client

• App-like AI UX: Structured, interactive workflows instead of text-only conversations.
• Q-App Ecosystem: Build, install, and run reusable AI mini-apps.
• Multi-Provider AI: OpenAI, Anthropic, Gemini, DeepSeek, Groq, Mistral, xAI, Perplexity, Ollama, and more.
• Local-First Security: API keys are stored locally and are not committed to this repo.
• Desktop Extensibility: Electron architecture enables deeper system integration.
• Built-in i18n: Chinese, English, Japanese, and Korean support.

Open-Source Scope

This repository contains client-side code only (Electron + React).
Backend services, admin panel, and deployment infrastructure are intentionally excluded.

You need a reachable backend API and should configure it via VITE_API_URL.

Tech Stack

Layer	Technology
Desktop	Electron 33
Frontend	React 19 + TypeScript
Build	Vite 6 + electron-builder
AI SDK	Vercel AI SDK (multi-provider)
UI	Tailwind CSS 4 + JSON Render
3D	Three.js + React Three Fiber

Quick Start

1) Prerequisites

• Node.js >= 18
• npm (or pnpm/yarn with equivalent commands)

2) Configure env

cp .env.example .env

Set backend endpoint in .env:

VITE_API_URL=http://localhost:4000

PowerShell alternative:

Copy-Item .env.example .env

3) Install and run

npm install
npm run dev

Common Scripts

npm run dev
npm run lint
npm run build
npm run pack
npm run pack:dir

npm run pack outputs the installer into release/.

Q-App Development Modes

• Default Mode: JS/TS class with lifecycle hooks (onInit, onActivate, onDeactivate).
• Custom Mode: HTML-based app using injected app APIs for AI, storage, and filesystem.

Project Structure

src/
  pages/
  components/
  contexts/
  services/
  qapp/
  qapps/
  types/
  utils/
electron/
  main.ts
  preload.ts
  ai-ipc.ts
  ai-service.ts

Contributing

• Issues and pull requests are welcome.
• Please run npm run lint before submitting.
• Include verification steps for functional changes.

License

Licensed under MIT.