Purpose of the Debug Cache in WeChat Article Exporter (store/v2/debug.ts)

The debug cache is a dedicated IndexedDB table in store/v2/debug.ts that stores raw HTML blobs from failed article downloads to enable offline debugging without contaminating the main content cache.

The wechat-article-exporter project isolates problematic HTTP responses using a specialized persistence layer distinct from the standard HTML cache. Implemented in store/v2/debug.ts, this debug cache captures unparsable article content, preserving the exact server responses that trigger parsing exceptions or error states. By separating these diagnostic artifacts from successful downloads stored in store/v2/html.ts, the system enables developers to inspect anti-scraping blocks, malformed HTML, or credential failures long after the original network request completes.

What Is the Debug Cache?

The debug cache serves as a diagnostic buffer within the application's Dexie-based IndexedDB architecture. Unlike the primary html table that stores successfully processed articles, this table retains only exceptional cases where the download pipeline fails to extract valid metadata or content.

Key characteristics of the debug cache include:

• Isolation of error data: Failed downloads are segregated from successful cache entries to prevent data pollution
• Blob persistence: Raw HTML responses are stored as JavaScript Blob objects, preserving the exact byte-for-byte server response
• Metadata retention: Each entry includes the target URL, article title, WeChat fakeid, and error classification type

Core Implementation Details

The implementation in store/v2/debug.ts defines a minimal schema optimized for debugging workflows rather than high-volume storage.

The DebugAsset Interface

Each debug entry conforms to the DebugAsset interface, which structures the metadata surrounding a failed download:

interface DebugAsset {
  fakeid: string;      // WeChat article identifier
  type: string;        // Error classification (e.g., 'parse error', 'exception:...')
  url: string;         // Source URL of the failed request
  title: string;       // Article title for identification
  file: Blob;          // Raw HTML response as binary blob
}

Source: store/v2/debug.ts lines 3-9 define this interface with explicit typing for the Blob storage.

Database Operations

The module exposes three primary functions for interacting with the debug table:

updateDebugCache(asset: DebugAsset)
Inserts a new debug record within a Dexie transaction. This function is atomic and handles the IndexedDB write operation for persisting failed HTML blobs.

getDebugCache(url: string)
Retrieves a single DebugAsset by its URL, enabling targeted inspection of specific failed downloads.

getDebugInfo()
Returns the complete array of cached debug assets, typically used to populate a debug UI or diagnostic dashboard.

Source: Lines 15-32 in store/v2/debug.ts implement these CRUD operations using Dexie transactions.

When Failed Downloads Are Captured

The download pipeline in utils/download/Downloader.ts populates the debug cache during two specific failure modes, distinguishing between parsing exceptions and explicit parser errors.

Exception Scenarios

When the HTML downloads successfully but the parser throws an exception while extracting the comment ID, the system caches the response with a type indicating the specific exception context:

// In utils/download/Downloader.ts
if (status === 'Exception' && !commentID) {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: `exception:${commentID}`,
    url,
    title: article.title,
    file: blob,
  });
}

This scenario typically indicates server-side anti-scraping measures or unexpected HTML structure changes that prevent metadata extraction.

Parse Error Scenarios

When the parser returns an explicit error status rather than throwing, the system categorizes the failure differently:

if (status === 'Error') {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: 'parse error',
    url,
    title: article.title,
    file: blob,
  });
}

Source: Lines 10-22 and 28-31 in utils/download/Downloader.ts contain these conditional blocks that trigger debug cache updates.

Working with the Debug Cache

Developers can interact with the debug cache programmatically to build diagnostic tools or manual recovery workflows.

Storing Failed HTML Blobs

To manually capture a problematic response for later analysis, import the update function and persist the blob with appropriate metadata:

import { updateDebugCache } from '~/store/v2/debug';

async function captureFailure(article: Article, url: string, blob: Blob) {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: 'parse error',
    url,
    title: article.title,
    file: blob,
  });
}

Retrieving All Debug Entries

To display a list of failed downloads in a debug UI, fetch the complete dataset using getDebugInfo:

import { getDebugInfo } from '~/store/v2/debug';

async function displayDebugList() {
  const debugAssets = await getDebugInfo();
  
  debugAssets.forEach(asset => {
    console.log(`[${asset.type}] ${asset.title} – ${asset.url}`);
    // Create an object URL to preview the raw HTML
    const previewUrl = URL.createObjectURL(asset.file);
    window.open(previewUrl, '_blank');
  });
}

Source: The getDebugInfo function returns the full array of stored debug assets as implemented in store/v2/debug.ts lines 30-32.

Querying Specific Failed URLs

For targeted debugging of a particular article, retrieve the specific entry by URL:

import { getDebugCache } from '~/store/v2/debug';

async function inspectFailure(url: string) {
  const asset = await getDebugCache(url);
  if (asset) {
    const htmlText = await asset.file.text();
    console.error(`Failed HTML content (${asset.type}):`, htmlText);
    // Analyze the raw HTML to determine why parsing failed
  }
}

Source: getDebugCache performs lookups by URL in store/v2/debug.ts lines 26-28.

Key Files in the Debug System

File	Role
store/v2/debug.ts	Defines DebugAsset interface and provides CRUD helpers for the debug cache table
utils/download/Downloader.ts	Populates debug cache when HTML parsing fails with exceptions or errors
store/v2/html.ts	Primary cache for successfully parsed articles (contrast with debug cache)
store/v2/db.ts	Dexie database configuration where the debug table is registered

Summary

• The debug cache in store/v2/debug.ts is an IndexedDB-backed storage mechanism specifically for failed article downloads.
• It stores raw HTML as Blob objects to preserve exact server responses for forensic analysis.
• The cache is populated from utils/download/Downloader.ts during two failure modes: parsing exceptions and explicit parse errors.
• Functions updateDebugCache, getDebugCache, and getDebugInfo provide the complete interface for persisting and retrieving diagnostic data.
• This separation prevents cache pollution in the main HTML table while enabling offline debugging of anti-scraping blocks or malformed responses.

Frequently Asked Questions

What is the difference between the debug cache and the regular HTML cache?

The regular HTML cache in store/v2/html.ts stores successfully parsed articles for offline reading, while the debug cache exclusively retains failed downloads that could not be parsed. The debug cache acts as a diagnostic buffer, keeping error cases segregated to avoid contaminating the working dataset with corrupted or unparsable content.

How can I view the contents of a failed download stored in the debug cache?

Retrieve the specific entry using getDebugCache(url) or enumerate all failures with getDebugInfo(), then convert the stored Blob to text using blob.text() or create an object URL with URL.createObjectURL(blob) to render the HTML in a preview window. This allows inspection of the exact server response that caused the parsing failure.

When does the WeChat Article Exporter automatically save data to the debug cache?

The exporter automatically populates the debug cache when the download pipeline in utils/download/Downloader.ts encounters either a JavaScript exception during HTML parsing (status 'Exception') or an explicit parser error state (status 'Error'). Both scenarios preserve the raw HTTP response blob along with metadata including the URL, title, and WeChat fakeid.

Can I manually add entries to the debug cache for testing purposes?

Yes, you can import updateDebugCache from ~/store/v2/debug and programmatically insert any DebugAsset object containing a fakeid, error type, URL, title, and Blob. This is useful for testing debug UI components or preserving problematic responses encountered during development without triggering actual download failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}