@cloud411716/fancy-webnovel 0.3.16 → 1.0.0

package/commands/scan/platforms/jinjiang.js

@@ -0,0 +1,143 @@
+/**
+ * jinjiang.js — 晋江文学城排行榜采集
+ *
+ * 策略：纯 HTTP + gb18030 解码。
+ * 详情页使用 fetch + arrayBuffer + TextDecoder('gb18030')。
+ * 无需 Playwright。
+ */
+
+export const platform = 'jinjiang';
+export const label = '晋江';
+
+export const rankList = [
+  { id: '5',  label: '月榜',       channel: 'all', type: '5'  },
+  { id: '7',  label: '总分榜',     channel: 'all', type: '7'  },
+  { id: '4',  label: '季度榜',     channel: 'all', type: '4'  },
+  { id: '12', label: '收入金榜',   channel: 'all', type: '12' },
+  { id: '16', label: '完结金榜',   channel: 'all', type: '16' },
+  { id: '17', label: '新手金榜',   channel: 'all', type: '17' },
+];
+
+const BASE_URL = 'https://www.jjwxc.net/topten.php';
+const DETAIL_BASE = 'https://www.jjwxc.net/onebook.php';
+
+/**
+ * Scrape one rank list.
+ * @param {string} rankId  - orderstr, e.g. '5'
+ * @param {object} ctx      - Cordis plugin context
+ * @param {AbortSignal} signal
+ * @returns {Promise<{ ok: boolean, books: object[], error?: string }>}
+ */
+export async function scrapeRank(rankId, ctx, signal) {
+  const url = `${BASE_URL}?orderstr=${rankId}`;
+
+  // 1. 抓列表页
+  const { ok: listOk, status, body, error: listError } = await httpGet(ctx, url, signal);
+  if (!listOk) return { ok: false, books: [], error: listError ?? `HTTP ${status}` };
+
+  // 2. 解析书籍 ID 列表
+  const bookIds = extractBookIds(body);
+  if (!bookIds.length) return { ok: false, books: [], error: 'no book ids found' };
+
+  // 3. 批量补采详情（每批 6 本）
+  const CHUNK = 6;
+  const books = [];
+  for (let i = 0; i < bookIds.length; i += CHUNK) {
+    if (signal?.aborted) break;
+    const chunk = bookIds.slice(i, i + CHUNK);
+    const details = await Promise.all(chunk.map(id => fetchDetail(ctx, id, signal)));
+    for (const d of details) {
+      if (d) books.push(d);
+    }
+  }
+
+  return books.length > 0
+    ? { ok: true, books }
+    : { ok: false, books: [], error: 'no books collected' };
+}
+
+async function httpGet(ctx, url, signal) {
+  let timerDispose;
+  const timeout = new Promise((_, reject) => {
+    timerDispose = ctx.timeout(() => reject(new Error('timeout')), 15000);
+  });
+  try {
+    const res = await Promise.race([
+      fetch(url, {
+        headers: {
+          'User-Agent': 'Mozilla/5.0 (compatible; fancy-webnovel/1.0)',
+          'Accept': 'text/html',
+          'Accept-Language': 'zh-CN',
+        },
+        signal,
+      }),
+      timeout,
+    ]);
+    if (!res.ok) return { ok: false, status: res.status, body: '', error: `HTTP ${res.status}` };
+    const body = await res.text();
+    return { ok: true, status: res.status, body };
+  } catch (err) {
+    return { ok: false, status: 0, body: '', error: err.message };
+  } finally {
+    try { timerDispose?.(); } catch (_) {}
+  }
+}
+
+function extractBookIds(html) {
+  const ids = [];
+  // 两种布局：表格行和交替行
+  const tableRows = html.match(/<tr[^>]*>[\s\S]*?<\/tr>/gi) ?? [];
+  for (const row of tableRows) {
+    const m = row.match(/onebook\.php\?novelid=(\d+)/);
+    if (m) ids.push(m[1]);
+  }
+  // 交替行布局: 书名 / 作者 交替
+  if (!ids.length) {
+    const novelLinks = html.match(/novelid=(\d+)/g) ?? [];
+    for (const link of novelLinks) {
+      const id = link.match(/(\d+)/)?.[1];
+      if (id && !ids.includes(id)) ids.push(id);
+    }
+  }
+  return [...new Set(ids)].slice(0, 60); // 最多 60 本
+}
+
+async function fetchDetail(ctx, novelid, signal) {
+  let timerDispose;
+  const timeout = new Promise((_, reject) => {
+    timerDispose = ctx.timeout(() => reject(new Error('timeout')), 10000);
+  });
+  try {
+    const res = await Promise.race([
+      fetch(`${DETAIL_BASE}?novelid=${novelid}`, { signal }),
+      timeout,
+    ]);
+    if (!res.ok) return null;
+    const buf = await res.arrayBuffer();
+    const h = new TextDecoder('gb18030').decode(new Uint8Array(buf));
+
+    const prop = (/** @type {string} */ name) => {
+      const m = h.match(new RegExp(`itemprop="${name}"[^>]*>([^<]*)<`));
+      return m ? m[1].trim() : '';
+    };
+
+    return {
+      rank:   0,
+      title:  prop('title') || prop('novelname') || '',
+      author: prop('author') || '',
+      category: '',
+      words:  parseInt(prop('wordCount').replace(/[^\d]/g, ''), 10) || 0,
+      collect: prop('collectedCount') || '',
+      nutrition: prop('nutritionCount') || '',
+      score:  prop('scoreCount') || '',
+      status: (h.match(/(连载中|已完结|完结)/) || [, ''])[1],
+      intro:  (h.match(/<meta[^>]+name="description"[^>]+content="([^"]*)"/i)?.[1] ?? '').slice(0, 150),
+      cover:  '',
+      bookId: novelid,
+    };
+  } catch (_) {
+    return null;
+  } finally {
+    try { timerDispose?.(); } catch (_) {}
+  }
+}

package/commands/scan/platforms/qidian.js

@@ -0,0 +1,106 @@
+/**
+ * qidian.js — 起点排行榜采集
+ *
+ * 策略：纯 HTTP mobile SSR。移动端页面在 script 标签里内嵌完整的
+ * pageContext JSON，绕过了服务端渲染的加密，直接提取书籍数据。
+ * 无需 Playwright。
+ *
+ * Rank paths (mobile):
+ *   /rank/1_5173_2    畅销榜
+ *   /rank/1_5173_7    月票榜
+ *   /rank/1_5173_14   签约作者新书榜
+ *   /rank/1_5173_22   公众作者新书榜
+ *   /rank/1_5173_31   新人作者新书榜
+ */
+
+const MOBILE_BASE = 'https://m.qidian.com';
+
+const RANK_PATHS = {
+  hotsales:    '/rank/1_5173_2',
+  yuepiao:     '/rank/1_5173_7',
+  signnewbook: '/rank/1_5173_14',
+  pubnewbook:  '/rank/1_5173_22',
+  newauthor:   '/rank/1_5173_31',
+};
+
+export const platform = 'qidian';
+export const label = '起点';
+
+export const rankList = [
+  { id: 'hotsales',    label: '畅销榜',           channel: '1',  type: '5173_2' },
+  { id: 'yuepiao',     label: '月票榜',            channel: '1',  type: '5173_7' },
+  { id: 'signnewbook', label: '签约作者新书榜',    channel: '1',  type: '5173_14' },
+  { id: 'pubnewbook',  label: '公众作者新书榜',    channel: '1',  type: '5173_22' },
+  { id: 'newauthor',   label: '新人作者新书榜',    channel: '1',  type: '5173_31' },
+];
+
+const HEADERS = {
+  'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+  'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+  'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+  'Accept-Encoding': 'identity',
+};
+
+/**
+ * Scrape one rank list.
+ * @param {string} rankId   - rank id (e.g. 'hotsales')
+ * @param {object} ctx      - Cordis plugin context
+ * @param {AbortSignal} signal
+ * @returns {Promise<{ ok: boolean, books: object[], error?: string }>}
+ */
+export async function scrapeRank(rankId, ctx, signal) {
+  const path = RANK_PATHS[rankId];
+  if (!path) return { ok: false, books: [], error: `unknown rank: ${rankId}` };
+
+  const url = MOBILE_BASE + path;
+
+  const { ok, status, body, error } = await httpGet(ctx, url, signal);
+  if (!ok) return { ok: false, books: [], error: error ?? `HTTP ${status}` };
+
+  // Extract pageContext from <script id="vite-plugin-ssr_pageContext">
+  const m = body.match(/<script[^>]+id=["']vite-plugin-ssr_pageContext["'][^>]*>([\s\S]*?)<\/script>/i);
+  if (!m) return { ok: false, books: [], error: 'pageContext not found' };
+
+  let pageContext;
+  try {
+    pageContext = JSON.parse(m[1]);
+  } catch {
+    return { ok: false, books: [], error: 'pageContext JSON parse failed' };
+  }
+
+  const records = pageContext?.pageContext?.pageProps?.pageData?.records ?? [];
+  if (!records.length) return { ok: false, books: [], error: 'no book records found' };
+
+  const books = records.map((r) => ({
+    rank:       r.rank ?? 0,
+    title:      r.title ?? '',
+    author:     r.author ?? '',
+    category:   r.categoryName ?? '',
+    status:     r.statusName ?? '',
+    words:      r.wordCount ?? 0,
+    intro:      (r.description ?? '').slice(0, 150),
+    cover:      r.cover ?? '',
+    bookId:     r.bookId ?? '',
+  }));
+
+  return { ok: true, books };
+}
+
+async function httpGet(ctx, url, signal) {
+  let timerDispose;
+  const timeout = new Promise((_, reject) => {
+    timerDispose = ctx.timeout(() => reject(new Error('timeout')), 15000);
+  });
+  try {
+    const res = await Promise.race([
+      fetch(url, { headers: HEADERS, signal }),
+      timeout,
+    ]);
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body };
+  } catch (err) {
+    return { ok: false, status: 0, body: '', error: err.message };
+  } finally {
+    try { timerDispose?.(); } catch (_) {}
+  }
+}

package/commands/scan/platforms/qimao.js

@@ -0,0 +1,127 @@
+/**
+ * qimao.js — 七猫小说排行榜采集
+ *
+ * 策略：纯 HTTP。榜单页通过 XHR 加载 JSON 数据。
+ * 无需 Playwright。
+ */
+
+export const platform = 'qimao';
+export const label = '七猫';
+
+export const rankList = [
+  { id: 'male_hot',   label: '男生大热榜',  channel: 'male',   type: 'hot'   },
+  { id: 'male_new',   label: '男生新书榜',  channel: 'male',   type: 'new'   },
+  { id: 'female_hot', label: '女生大热榜',  channel: 'female', type: 'hot'   },
+  { id: 'female_new', label: '女生新书榜',  channel: 'female', type: 'new'   },
+];
+
+const RANK_URL = 'https://www.qimao.com/paihang';
+
+/**
+ * Scrape one rank list.
+ * @param {string} rankId  - e.g. 'male_hot'
+ * @param {object} ctx      - Cordis plugin context
+ * @param {AbortSignal} signal
+ * @returns {Promise<{ ok: boolean, books: object[], error?: string }>}
+ */
+export async function scrapeRank(rankId, ctx, signal) {
+  const [channelId, rankTypeId] = rankId.split('_');
+
+  const channelMap = { male: 'boy', female: 'girl' };
+  const rankTypeMap = { hot: 'hot', new: 'new' };
+  const channel = channelMap[channelId] ?? channelId;
+  const rankType = rankTypeMap[rankTypeId] ?? rankTypeId;
+
+  const url = `${RANK_URL}/${channel}/${rankType}/date/`;
+
+  const { ok, status, body, error } = await httpGet(ctx, url, signal);
+  if (!ok) return { ok: false, books: [], error: error ?? `HTTP ${status}` };
+
+  const books = parseBooks(body, channelId, rankTypeId);
+  return books.length > 0
+    ? { ok: true, books }
+    : { ok: false, books: [], error: 'no books found in page' };
+}
+
+async function httpGet(ctx, url, signal) {
+  let timerDispose;
+  const timeout = new Promise((_, reject) => {
+    timerDispose = ctx.timeout(() => reject(new Error('timeout')), 15000);
+  });
+  try {
+    const res = await Promise.race([
+      fetch(url, {
+        headers: {
+          'User-Agent': 'Mozilla/5.0 (compatible; fancy-webnovel/1.0)',
+          'Accept': 'text/html,application/xhtml+xml',
+          'Accept-Language': 'zh-CN,zh;q=0.9',
+        },
+        signal,
+      }),
+      timeout,
+    ]);
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body };
+  } catch (err) {
+    return { ok: false, status: 0, body: '', error: err.message };
+  } finally {
+    try { timerDispose?.(); } catch (_) {}
+  }
+}
+
+function parseBooks(html, channelId, rankTypeId) {
+  const books = [];
+
+  // 尝试从 JSON 数据块提取
+  const jsonMatch = html.match(/var\s+RANK_DATA\s*=\s*(\{.*?\});/s)
+    ?? html.match(/window\.__INITIAL_STATE__\s*=\s*(\{.*?\});/s);
+
+  if (jsonMatch) {
+    try {
+      const data = JSON.parse(jsonMatch[1]);
+      const list = data?.rankList ?? data?.bookList ?? data?.books ?? [];
+      return normalizeBooks(list, channelId, rankTypeId);
+    } catch (_) { /* fall through */ }
+  }
+
+  // DOM 解析: 从页面 HTML 提取书籍信息
+  // 匹配模式: <a class="book-title">书名</a> ... <span class="author">作者</span>
+  const titleMatches = [...html.matchAll(/class="(?:book-)?title[^"]*"[^>]*>([^<]+)<\/a>/g)];
+  const authorMatches = [...html.matchAll(/class="author[^"]*"[^>]*>([^<]+)<\/a>/g)];
+  const rankMatches = [...html.matchAll(/class="(?:rank|num)[^"]*"[^>]*>(\d+)<\/span>/g)];
+
+  const count = Math.min(titleMatches.length, authorMatches.length);
+  for (let i = 0; i < count; i++) {
+    const title = (titleMatches[i][1] ?? '').trim();
+    const author = (authorMatches[i][1] ?? '').trim();
+    if (!title || /^(上一页|下一页|跳转)$/.test(title)) continue;
+    if (!author || /^(上一页|下一页|跳转|友情链接)$/.test(author)) continue;
+
+    books.push({
+      rank:    rankMatches[i] ? parseInt(rankMatches[i][1], 10) : (i + 1),
+      title,
+      author,
+      category: '',
+      words:   0,
+      intro:   '',
+      cover:   '',
+      bookId:  '',
+    });
+  }
+
+  return books;
+}
+
+function normalizeBooks(list, channelId, rankTypeId) {
+  if (!Array.isArray(list)) return [];
+  return list.map((b, i) => ({
+    rank:   b.rank ?? (i + 1),
+    title:  b.title ?? b.bookTitle ?? '',
+    author: b.author ?? '',
+    category: b.categoryName ?? b.typeName ?? '',
+    words:  b.wordCount ?? b.words ?? 0,
+    intro:  (b.description ?? '').slice(0, 150),
+    cover:  b.cover ?? b.thumbnail ?? '',
+    bookId: b.bookId ?? b.id ?? '',
+  }));
+}

package/commands/scan/scraper.js

@@ -0,0 +1,195 @@
+/**
+ * scraper.js — 扫榜编排层
+ *
+ * 职责：
+ *   1. 对每个平台/榜单调用对应的 platform scraper
+ *   2. 重试逻辑（每个榜单最多 3 次，间隔 5 秒）
+ *   3. 通过 DSH 事件实时汇报进度
+ *   4. 生成 Markdown 文件并写入项目目录
+ *   5. 所有操作纳入 ctx.effect() 生命周期，Ctrl+C 可终止
+ */
+
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { sleep, scanProgress, writeFile } from '../../infra.js';
+import * as qidian from './platforms/qidian.js';
+import * as fanqie from './platforms/fanqie.js';
+import * as jinjiang from './platforms/jinjiang.js';
+import * as qimao from './platforms/qimao.js';
+
+const SCRAPER_TIMEOUT = 30 * 60 * 1000; // 30 分钟 per rank
+const MAX_RETRIES = 3;
+const RETRY_DELAY = 5000;
+
+// Platform registry
+const PLATFORMS = { qidian, fanqie, jinjiang, qimao };
+
+function todayStr() {
+  const d = new Date();
+  return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}`;
+}
+
+/**
+ * Run scans for a list of { platform, channel, type, label } entries.
+ * Uses ctx.effect() for lifecycle management and ctx.events for progress.
+ *
+ * @param {object} ctx       - Cordis plugin context
+ * @param {string} projectRoot
+ * @param {Array}  ranks     - array of { platform, channel, type, label }
+ * @param {AbortSignal} signal
+ * @returns {Promise<{ totalBooks: number, totalFiles: number, failedRanks: Array, lastReceipt: object|null }>}
+ */
+export async function runScans(ctx, projectRoot, ranks, signal) {
+  const scanDir = join(projectRoot, '扫榜数据');
+  mkdirSync(scanDir, { recursive: true });
+
+  const today = todayStr();
+  let totalBooks = 0;
+  let totalFiles = 0;
+  const failedRanks = [];
+  let lastReceipt = null;
+
+  for (const rank of ranks) {
+    if (signal.aborted) {
+      scanProgress(ctx, 'rank-done', {
+        platform: rank.platform, channel: rank.channel, type: rank.type,
+        ok: false, written: 0, failed: 0, errorMsg: 'aborted by user',
+      });
+      break;
+    }
+
+    const platform = PLATFORMS[rank.platform];
+    if (!platform) {
+      failedRanks.push({ rank, err: `unknown platform: ${rank.platform}` });
+      continue;
+    }
+
+    scanProgress(ctx, 'start', {
+      platform: rank.platform,
+      channel: rank.channel,
+      type: rank.type,
+      label: rank.label,
+    });
+
+    let result;
+    let attempt = 0;
+
+    while (attempt < MAX_RETRIES) {
+      if (signal.aborted) break;
+      attempt++;
+      try {
+        result = await withTimeout(
+          platform.scrapeRank(rank.type, ctx, signal),
+          ctx,
+          SCRAPER_TIMEOUT,
+        );
+        if (result.ok) break;
+      } catch (err) {
+        result = { ok: false, books: [], error: err.message };
+      }
+      if (attempt < MAX_RETRIES && !signal.aborted) {
+        await sleep(ctx, RETRY_DELAY);
+      }
+    }
+
+    if (signal.aborted) {
+      failedRanks.push({ rank, err: 'aborted' });
+      continue;
+    }
+
+    if (!result.ok || !result.books.length) {
+      failedRanks.push({ rank, err: result.error ?? 'no books' });
+      scanProgress(ctx, 'rank-done', {
+        platform: rank.platform, channel: rank.channel, type: rank.type,
+        ok: false, written: 0, failed: result.books?.length ?? 0,
+        errorMsg: result.error,
+      });
+      continue;
+    }
+
+    // Write markdown file
+    let filepath;
+    try {
+      const content = renderMarkdown(platform.label, rank.label, result.books);
+      const filename = `${platform.label}${rank.label}_${today}.md`;
+      filepath = join(scanDir, filename);
+      await writeFile(filepath, content);
+      totalFiles++;
+      totalBooks += result.books.length;
+      lastReceipt = {
+        platform: rank.platform,
+        date: today,
+        scan_files: [filepath],
+        topic_decision: join(scanDir, `topic_decision_${today}.md`),
+      };
+    } catch (err) {
+      failedRanks.push({ rank, err: `write failed: ${err.message}` });
+      scanProgress(ctx, 'rank-done', {
+        platform: rank.platform, channel: rank.channel, type: rank.type,
+        ok: false, written: 0, failed: result.books.length,
+        errorMsg: `write failed: ${err.message}`,
+      });
+      continue;
+    }
+
+    scanProgress(ctx, 'rank-done', {
+      platform: rank.platform, channel: rank.channel, type: rank.type,
+      ok: true, written: result.books.length, failed: 0,
+    });
+  }
+
+  scanProgress(ctx, 'done', {
+    platform: ranks[0]?.platform ?? '',
+    totalBooks,
+    totalFiles,
+    ok: failedRanks.length < ranks.length,
+  });
+
+  return { totalBooks, totalFiles, failedRanks, lastReceipt };
+}
+
+/**
+ * Wrap a promise with a ctx.timeout deadline.
+ * ctx.timeout(fn, ms) returns a synchronous dispose function that is safe
+ * to call multiple times (idempotent), so this is guaranteed leak-free.
+ */
+async function withTimeout(promise, ctx, ms) {
+  let dispose;
+  const timeout = new Promise((_, reject) => {
+    dispose = ctx.timeout(() => reject(new Error(`timeout after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    try { dispose?.(); } catch (_) {}
+  }
+}
+
+/**
+ * Render books as Markdown.
+ */
+function renderMarkdown(platformLabel, rankLabel, books) {
+  const lines = [
+    `# ${platformLabel} · ${rankLabel}`,
+    '',
+    `> 自动采集于 ${new Date().toLocaleString('zh-CN')}`,
+    '',
+    '| 排名 | 书名 | 作者 | 类别 | 字数 | 简介 |',
+    '|------|------|------|------|------|------|',
+  ];
+
+  for (const b of books) {
+    const title = escapeTable(b.title || '');
+    const author = escapeTable(b.author || '');
+    const category = escapeTable(b.category || '-');
+    const words = b.words ? `${(b.words / 10000).toFixed(1)}万` : '-';
+    const intro = escapeTable((b.intro || '').slice(0, 80));
+    lines.push(`| ${b.rank ?? ''} | ${title} | ${author} | ${category} | ${words} | ${intro} |`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function escapeTable(s) {
+  return String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}

package/cordis.patch.yml

@@ -1,3 +1,17 @@
+# @cloud411716/fancy-webnovel — DSH Cordis Plugin Patch
+#
+# IMPORTANT: This plugin creates project directories at user-specified paths
+# (which may be OUTSIDE the DSH workspace). Therefore it REQUIRES
+# `danger-full-access` sandbox mode. Add this to your profile's patch, e.g.:
+#
+#   - insert:
+#       - id: sandbox-policy
+#         config:
+#           mode: danger-full-access
+#
+# All other services used (commands, userQuestions, timer, events, session)
+# are part of dsh-base and available in every DSH UI (tui, web, desktop).
+
 - insert:
     - id: fancy-webnovel
       name: "@cloud411716/fancy-webnovel"

package/events.js

@@ -0,0 +1,53 @@
+/**
+ * events.js — Scan progress event vocabulary
+ *
+ * These are pure in-memory plugin events emitted via ctx.events.emit().
+ * They flow through DSH's session log and are visible to the agent
+ * as structured data, enabling real-time progress reporting.
+ */
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Emitted when a rank scan starts.
+     * @param platform - platform id (qidian|fanqie|jinjiang|qimao)
+     * @param channel  - channel id
+     * @param type     - rank type id
+     * @param label    - human-readable rank label
+     */
+    'fancy/scan:start'(platform: string, channel: string, type: string, label: string): void
+
+    /**
+     * Emitted after each book is successfully scraped.
+     * @param platform - platform id
+     * @param channel  - channel id
+     * @param type     - rank type id
+     * @param index    - 0-based index of this book in the rank
+     * @param total    - total books expected (may be 0 if unknown)
+     * @param title    - book title
+     * @param rank     - displayed rank number
+     */
+    'fancy/scan:book'(platform: string, channel: string, type: string, index: number, total: number, title: string, rank: number): void
+
+    /**
+     * Emitted when a rank scan finishes (success or failure).
+     * @param platform   - platform id
+     * @param channel    - channel id
+     * @param type       - rank type id
+     * @param ok         - true on success
+     * @param written    - number of books written to file
+     * @param failed     - number of books that failed
+     * @param errorMsg   - error message if !ok
+     */
+    'fancy/scan:rank-done'(platform: string, channel: string, type: string, ok: boolean, written: number, failed: number, errorMsg?: string): void
+
+    /**
+     * Emitted when all scans for a platform finish.
+     * @param platform - platform id
+     * @param totalBooks  - total books collected
+     * @param totalFiles  - total files written
+     * @param ok          - true if at least one rank succeeded
+     */
+    'fancy/scan:done'(platform: string, totalBooks: number, totalFiles: number, ok: boolean): void
+  }
+}

package/index.js

@@ -1,10 +1,44 @@
-// @cloud411716/fancy-webnovel unified entry point
-import { apply as applyBootstrap } from './plugins/fancy-bootstrap/index.js';
-import { apply as applyScan } from './plugins/fancy-scan/index.js';
+/**
+ * @cloud411716/fancy-webnovel — DSH Cordis Plugin
+ *
+ * Provides slash commands for web novel project workflow:
+ *   /fancy-bootstrap  — Initialize a project root
+ *   /fancy-scan       — Scan platform rank lists
+ *
+ * Architecture:
+ *   - All scrapers run IN-PROCESS (no subprocess).
+ *     DSH manages the lifecycle via ctx.effect() and AbortSignal.
+ *     Progress is reported via ctx.events (fancy/scan:* events).
+ *   - HTTP fetching uses Node.js native fetch (portable across all DSH UIs).
+ *   - File operations use Node.js fs (project roots may be outside workspace).
+ *   - ctx.timer (via ctx.timeout()) handles all delays/timeouts.
+ *
+ * Required Cordis services: commands, userQuestions, timer, events, session
+ * (all are part of dsh-base, so this plugin works on dsh-tui, dsh-web, dsh-desktop).
+ *
+ * IMPORTANT: This plugin needs `danger-full-access` sandbox mode because it
+ * creates project directories outside the DSH workspace (at paths the user
+ * specifies). Declare this in the profile's cordis.patch.yml.
+ */
 
+import './events.js'; // registers fancy/scan:* event types with Cordis
+
+import { apply as applyBootstrap } from './commands/bootstrap/index.js';
+import { apply as applyScan }      from './commands/scan/index.js';
+
+/**
+ * Services this plugin requires from the Cordis context.
+ * All are provided by dsh-base, so this works on every DSH UI.
+ */
 export const inject = ['commands', 'userQuestions'];
 
-export async function apply(ctx) {
-  await applyBootstrap(ctx);
-  await applyScan(ctx);
+/**
+ * Called once when the plugin is loaded into a Cordis context (fiber).
+ * Registers slash commands; actual logic lives in per-command modules.
+ *
+ * @param {object} ctx - Cordis plugin context
+ */
+export function apply(ctx) {
+  applyBootstrap(ctx);
+  applyScan(ctx);
 }