How shuakami/qq-chat-exporter works
1. Repository shape
- This repo is a multi-part QQ chat export system, not a single application.
- The main production runtime is the NapCat plugin under plugins/qq-chat-exporter.
- The user-facing management UI is qce-v4-tool.
- There is also a lightweight legacy/static viewer in qce-viewer, plus build/release scripts and docs.
2. Primary runtime boundary: NapCat plugin
- plugins/qq-chat-exporter is the core backend plugin that runs inside the NapCatQQ environment.
- It is responsible for accessing QQ data, orchestrating exports, tracking progress, and serving API endpoints to the UI.
- The compiled output in dist/ mirrors this structure and indicates the plugin is the deployable unit.
3. Data acquisition layer
- The core data path begins with chat and metadata retrieval:
- core/fetcher/BatchMessageFetcher
- core/chat/ChatSessionManager
- core/chat/FriendInfoManager
- core/chat/GroupInfoManager
- These modules gather message history and entity metadata before export.
- The plugin also includes search and resource indexing services, suggesting read-only traversal over stored QQ content rather than live message interception only.
4. Export pipeline
- The export subsystem converts fetched chat data into multiple output formats:
- HTML
- JSON
- TXT
- Excel
- Key exporters live under core/exporter/, including HtmlExporter, ModernHtmlExporter, JsonExporter, TextExporter, and ExcelExporter.
- Parsing is separated from rendering via core/parser/MessageParser and SimpleMessageParser, which helps keep message normalization distinct from output formatting.
5. Media and attachment handling
- Export is not just text: the plugin has explicit support for resources and media packaging.
- Relevant components include:
- core/resource/ResourceHandler
- core/merger/ResourceMerger
- utils/ZipExporter and utils/StreamingZipExporter
- core/sticker/StickerPackExporter
- core/group/GroupFilesExporter and GroupAlbumExporter
- This indicates a pipeline that collects chat attachments, stickers, group assets, and bundles them alongside exported transcripts.
6. Operational services inside the plugin
- The plugin includes non-export orchestration services:
- core/scheduler/ScheduledExportManager for recurring backup/export jobs
- core/progress/ProgressTracker for long-running task state
- services/StreamSearchService for searching streamed or indexed data
- security/SecurityManager for access control around the local API surface
- storage/ConfigManager and DatabaseManager show the plugin keeps local configuration/state, not just stateless processing.
7. API and control plane
- The plugin exposes an API layer under lib/api / dist/api.
- ApiServer, ApiLauncher, and StandaloneServer form the interface between the UI and the export engine.
- This is the main integration boundary: the dashboard triggers exports, queries status/history, reads config, and receives progress/results through this API rather than directly touching export internals.
8. Modern management UI
- qce-v4-tool is the current frontend dashboard, built with Next.js-style structure (app/, components/, hooks/).
- Its hooks (use-api, use-export-tasks, use-scheduled-exports, use-search, use-system-info, etc.) show the UI is stateful and API-driven.
- The UI organizes workflows such as session browsing, export task setup, batch export, scheduled exports, settings, sticker export, file/essence dialogs, and execution history.
9. UI-to-backend data flow
- The typical flow is:
- user opens the dashboard in the browser
- dashboard authenticates via token/local auth
- UI calls the plugin API over HTTP and likely websocket-style updates for live state
- plugin fetches QQ data, performs export, streams progress, and writes artifacts locally
- The UI does not appear to own the export logic; it is a control and visualization layer over the plugin runtime.
10. Legacy viewer / static export browsing
- qce-viewer is a separate, simpler web app/server used to browse exported content.
- Its public/ HTML/JS/CSS assets and server.js suggest it serves previously generated export bundles rather than controlling the export engine.
- This is an important architectural boundary: it consumes export outputs, while qq-chat-exporter produces them.
11. Build, packaging, and deployment
- The repo includes release automation in .github/workflows for building the plugin, docs, and release artifacts.
- scripts/ contains packaging and conversion utilities such as ZIP packaging, Excel conversion, framework plugin building, version sync, and standalone startup helpers.
- The presence of public/dist/ and plugin dist/ indicates prebuilt browser bundles and plugin artifacts are shipped with releases.
12. Documentation and deployment modes
- Documentation in docs/ covers usage, contributing, Docker NapCat deployment, and guides.
- The README highlights two deployment styles:
- desktop/launcher-based usage
- Docker NapCat shell-mode plugin deployment
- That means the same export core can run in at least two operational contexts, but the internal architecture stays centered on the NapCat plugin plus the dashboard UI.
13. Overall architectural picture
- The system is best understood as a local-first export platform:
- NapCat plugin = data access, processing, storage, API
- qce-v4-tool = administrative UI and workflow orchestration
- qce-viewer = read-only browsing of generated artifacts
- The key domain objects are chat sessions, messages, resources, and export tasks, with local filesystem/database state used to persist configuration, history, and generated files.
Main entry points: ApiServer.ts API server · release-plugin.yml Build & release · HtmlExporter.ts Exporters · BatchMessageFetcher.ts Batch fetcher
Components 22
NapCat plugin
Core runtime inside NapCatQQ that fetches QQ data, runs exports, and serves the local API.
- API server · HTTP control plane for the dashboard and standalone access.
plugins/qq-chat-exporter/lib/api/ApiServer.ts - API launcher · Starts the API runtime in plugin or standalone mode.
plugins/qq-chat-exporter/lib/api/ApiLauncher.ts - Standalone server · Alternative startup path for running the exporter outside NapCat.
plugins/qq-chat-exporter/lib/api/StandaloneServer.ts - Batch fetcher · Pulls message history and drives bulk data acquisition.
plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts - Chat managers · Session, friend, and group metadata coordinators.
plugins/qq-chat-exporter/lib/core/chat/ChatSessionManager.ts - Message parser · Normalizes raw chat content before export formatting.
plugins/qq-chat-exporter/lib/core/parser/MessageParser.ts - Exporters · HTML, modern HTML, JSON, text, and Excel export writers.
plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts - Resources · Collects, merges, and bundles attachments and media assets.
plugins/qq-chat-exporter/lib/core/resource/ResourceHandler.ts - Group assets · Exports group files and albums as part of chat packages.
plugins/qq-chat-exporter/lib/core/group/GroupFilesExporter.ts - Sticker export · Builds sticker-pack outputs for chat archives.
plugins/qq-chat-exporter/lib/core/sticker/StickerPackExporter.ts - Scheduled exports · Recurring export and backup job manager.
plugins/qq-chat-exporter/lib/core/scheduler/ScheduledExportManager.ts - Progress tracker · Tracks long-running export status for UI updates.
plugins/qq-chat-exporter/lib/core/progress/ProgressTracker.ts - Config & DB · Persistent config and database layer for runtime state and history.
plugins/qq-chat-exporter/lib/core/storage/ConfigManager.ts - Security · Access control for the local API surface.
plugins/qq-chat-exporter/lib/security/SecurityManager.ts - Stream search · Searches streamed or indexed QQ content.
plugins/qq-chat-exporter/lib/services/StreamSearchService.ts
Management UI
Browser dashboard for configuring sessions, exports, schedules, search, and settings.
- QCE dashboard · Primary web interface for managing exports and settings.
qce-v4-tool/app/page.tsx - API hooks · Client hooks for exports, schedule, search, config, and websocket state.
qce-v4-tool/hooks/use-api.ts - Workflow UI · Session browsing, task wizard, scheduled exports, history, and dialogs.
qce-v4-tool/components/ui/task-wizard.tsx
Legacy viewer
Static/read-only app for browsing previously generated export bundles.
- QCE viewer · Legacy server that browses exported bundles and resources.
qce-viewer/server.js - Viewer assets · HTML, JS, and CSS for read-only archive browsing.
qce-viewer/public/index.html
Build & release
Packaging, release, and documentation automation for plugin and UI artifacts.
- Build & release · GitHub workflows and scripts for packaging, conversion, and publishing.
.github/workflows/release-plugin.yml - Docs · Usage, deployment, and contribution guides.
docs/guide.md
Connections 23
- API launcher → API server: starts · Bootstraps the API runtime.
- Standalone server → API server: hosts · Alternative standalone entrypoint for the same control plane.
- API server → Batch fetcher: requests data · Initiates bulk chat history retrieval.
- Batch fetcher → Chat managers: reads metadata · Uses session and entity managers to resolve conversations.
- Batch fetcher → Message parser: normalizes · Converts raw messages into export-ready records.
- Message parser → Exporters: feeds · Supplies normalized message content to format-specific writers.
- Exporters → Resources: bundles media · Includes attachments and generated assets with transcripts.
- Resources → Group assets: packages · Collects group files and album content.
- Resources → Sticker export: packages · Adds sticker packs to export output.
- Exporters → Config & DB: writes state · Persists export history, config, and runtime metadata.
- Scheduled exports → Exporters: triggers · Starts recurring export jobs.
- Scheduled exports → Progress tracker: updates · Publishes task progress for live monitoring.
- Progress tracker → API server: streams status · Exposes long-running job state to clients.
- Security → API server: protects · Constrains local API access.
- Stream search → Config & DB: indexes · Uses local persistence for searchable content.
- QCE dashboard → API hooks: calls · UI components consume API and websocket hooks.
- API hooks → API server: requests · Primary browser-to-plugin control flow over HTTP and live updates.
- Workflow UI → QCE dashboard: renders · Composes the management workflows inside the app shell.
- QCE viewer → Viewer assets: serves · Hosts the legacy static archive browser.
- Build & release → API server: packages · Builds plugin artifacts for release.
- Build & release → QCE dashboard: builds · Produces the management UI bundles.
- Build & release → QCE viewer: packages · Creates viewer and release artifacts.
- Docs → Build & release: documents · Explains deployment and packaging flows.