QCVP — Qimiao Character Pairing Lab

An open-source, AI-assisted character pairing and storytelling web app for fan communities. Search characters, compose CP (character pair) matches, generate compatibility scores and micro-stories, and export shareable cards — all in the browser.

QCVP = Qimiao Character Viewer & Pairing

---

Overview

QCVP is a full-stack Vue application built for community-driven character discovery and creative engagement. It combines a searchable character gallery, rule-based + AI-powered CP generation, and lightweight content tooling suitable for fan communities, civic storytelling pilots, and AI workflow experiments.

Key capabilities:

• Built-in character roster (46+ Qimiao Universe characters across multiple series)
• Search & filter by name, series, tags, and personality
• Manual selection or random pairing
• CP compatibility score (60–99%) with AI-generated micro-stories
• Character creation wizard with online source aggregation (Bilibili, Baidu Baike, Wiki)
• AI avatar enhancement via image-editing API
• One-click PNG export and QR share cards

---

Architecture

flowchart TB
  subgraph Client["Browser (Vue 3 + Vite)"]
    UI[Home / Create / Result Views]
    Store[Character Store & CP Engine]
    Export[html2canvas + QR Share]
  end

  subgraph Server["Node.js API (Vite Middleware)"]
    API[characterApi.js]
    SQLite[(SQLite — localCharacterStore)]
    Parser[characterTextParser]
    Sources[characterSources / Discovery]
  end

  subgraph External["External Services"]
    AIGATE[AIGATE Gateway\nDeepSeek + Gemini Image]
    Bili[Bilibili API]
    Baike[Baidu Baike]
    Wiki[Qimiao Wiki]
  end

  UI --> Store
  Store --> API
  Export --> UI
  API --> SQLite
  API --> Parser
  API --> Sources
  Parser --> AIGATE
  API --> AIGATE
  Sources --> Bili
  Sources --> Baike
  Sources --> Wiki

Loading

Layer	Stack
Frontend	Vue 3, Vue Router, Vite 8
Backend	Node.js ESM, Vite dev-server middleware
Storage	SQLite (better-sqlite3), JSON seed data
AI	AIGATE unified gateway (DeepSeek v4 Flash + Gemini image)
Export	html2canvas, qrcode

---

Use Cases

Scenario	How QCVP helps
Fan community engagement	Let community members explore characters, create pairings, and share results — lowering the barrier to participatory content creation.
Civic / community storytelling	Template for localized "community character" apps: swap the character dataset for local mascots, historical figures, or neighborhood personas.
AI workflow prototyping	End-to-end demo of multi-step AI pipelines: source aggregation → profile parsing → structured JSON → generative storytelling → image enhancement.
Digital government pilots	Reference implementation for lightweight, self-hosted community tools that run on static + edge Node without heavy infrastructure.
Open-source learning	Clear separation of frontend composables, API middleware, and pluggable AI clients — suitable for studying Vue + Node integration patterns.

---

Quick Start

Prerequisites

• Node.js 18+
• npm

Install & run

git clone https://github.com/wzsqcmap/QCVP.git
cd QCVP
npm install
npm run dev

Open the URL shown in the terminal (default: http://localhost:2173).

Environment variables

Copy the example file and add your API key:

cp .env.example .env

Variable	Required	Description
AIGATE_API_KEY	Yes (for AI features)	Unified gateway key for text + image AI
AIGATE_BASE_URL	No	Default: https://ai.zhaoxiaolin.com/v1
AIGATE_IMAGE_MODEL	No	Default: Gemini image model via AIGATE

Without AIGATE_API_KEY, local rule-based CP scoring still works; AI story generation and avatar enhancement are disabled.

Build for production

npm run build
npm run preview   # preview dist locally

Deploy the dist/ folder to any static host. For full API features, run with Vite/PM2 (ecosystem.config.cjs included).

---

Project Structure

QCVP/
├── src/                  # Vue 3 frontend
│   ├── views/            # Home, Create, Result pages
│   ├── components/       # Gallery, CP card, wizard, share
│   ├── composables/      # Character store, toast
│   └── utils/            # CP engine, AI client, filters
├── server/               # Node.js API & data pipeline
│   ├── characterApi.js   # REST middleware (mounted in Vite)
│   ├── aiService.js      # CP + story generation
│   ├── deepseekClient.js # Text AI via AIGATE
│   ├── imageService.js   # Image AI via AIGATE
│   └── data/             # SQLite DB (gitignored)
├── public/               # Static assets
└── ecosystem.config.cjs  # PM2 config

---

Character Data Format

Edit src/data/characters.json:

{
  "id": "maoxiaojiu",
  "name": "猫小九",
  "avatar": "",
  "series": "猫小九历险记",
  "personality": "热血、倔强、不服输",
  "tags": ["战神", "猫族", "少年"],
  "relations": { "maobailing": "青梅竹马" }
}

• id — unique English slug
• avatar — leave empty for initial-based placeholder, or set e.g. /local-avatars/xiaojiu.png
• relations — keys are partner id; preset relations boost compatibility and story quality

---

Scripts

Command	Description
npm run dev	Start dev server with API middleware
npm run build	Production build
npm run test	Run server unit tests
npm run discover:characters	Discover characters from online sources
npm run download:characters:loop	Batch download character assets
npm run refresh:characters	Refresh all character profiles

---

License

MIT License — see LICENSE for details.

---

Contributing

Issues and pull requests are welcome on GitHub.