@wangjunjian/dsh-github-trending 0.1.0 → 0.2.0

package/lib/index.js

@@ -11,19 +11,32 @@
 import z from '@deepseek-ai/schemastery';
 import { TrendingCache } from './cache.js';
 import { DEFAULT_REFRESH_INTERVAL_MS } from './constants.js';
+import { IntroductionGenerator } from './intros.js';
+import { OverviewGenerator } from './summaries.js';
 import { applyGithubTrendingTool, buildTrendingUrl, fetchTrendingRepositories, MAX_RESULTS_LIMIT } from './tool.js';
 export { DEFAULT_REFRESH_INTERVAL_MS } from './constants.js';
 export { DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT } from './tool.js';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'github-trending';
+/** How long a `?wait=1` request is held while waiting for overview progress. */
+const OVERVIEW_WAIT_TIMEOUT_MS = 25_000;
 /** Services this plugin requires. */
-export const inject = ['tools', 'systemPrompt', 'webServer'];
+export const inject = ['tools', 'systemPrompt', 'webServer', 'llm', 'agentDefaultModel'];
 /** Schemastery config schema with defaults and bounds. */
 export const Config = z.object({
     enabled: z.boolean().default(true),
     timeoutMs: z.number().default(30_000),
     maxResults: z.number().default(10),
     refreshIntervalMs: z.number().default(DEFAULT_REFRESH_INTERVAL_MS),
+    overviewsEnabled: z.boolean().default(false),
+    overviewsLanguage: z.string().default('zh'),
+    overviewsMaxRepos: z.number().default(10),
+    overviewsProvider: z.string(),
+    overviewsModel: z.string(),
+    overviewsMaxTokens: z.number().default(2048),
+    overviewsTimeoutMs: z.number().default(60_000),
+    introsMaxTokens: z.number().default(4096),
+    introsTimeoutMs: z.number().default(120_000),
 });
 /**
  * Assert that a numeric config value is a positive finite integer.
@@ -47,15 +60,56 @@ export function apply(ctx, config) {
     assertPositiveInteger('timeoutMs', resolved.timeoutMs);
     assertPositiveInteger('maxResults', resolved.maxResults);
     assertPositiveInteger('refreshIntervalMs', resolved.refreshIntervalMs);
+    assertPositiveInteger('overviewsMaxRepos', resolved.overviewsMaxRepos);
+    assertPositiveInteger('overviewsMaxTokens', resolved.overviewsMaxTokens);
+    assertPositiveInteger('overviewsTimeoutMs', resolved.overviewsTimeoutMs);
+    assertPositiveInteger('introsMaxTokens', resolved.introsMaxTokens);
+    assertPositiveInteger('introsTimeoutMs', resolved.introsTimeoutMs);
+    if (resolved.overviewsLanguage !== 'zh' && resolved.overviewsLanguage !== 'en') {
+        throw new Error(`github-trending: overviewsLanguage must be "zh" or "en"`);
+    }
+    const hasProviderOverride = resolved.overviewsProvider !== undefined && resolved.overviewsProvider !== '';
+    const hasModelOverride = resolved.overviewsModel !== undefined && resolved.overviewsModel !== '';
+    if (hasProviderOverride !== hasModelOverride) {
+        throw new Error('github-trending: overviewsProvider and overviewsModel must be configured together');
+    }
     if (!resolved.enabled)
         return;
     applyGithubTrendingTool(ctx, {
         timeoutMs: resolved.timeoutMs,
         maxResults: Math.min(resolved.maxResults, MAX_RESULTS_LIMIT),
     });
+    let generator;
+    let introGenerator;
+    let onRefreshed;
+    if (resolved.overviewsEnabled) {
+        // Resolve the route lazily: currentSelection() is live-read, and the
+        // settings layer may not even be mounted yet when this plugin loads, so
+        // capturing the selection once here could freeze a stale fallback model.
+        const resolveRoute = () => hasProviderOverride
+            ? { provider: resolved.overviewsProvider, model: resolved.overviewsModel }
+            : ctx.agentDefaultModel.currentSelection();
+        generator = new OverviewGenerator(ctx, resolveRoute, {
+            language: resolved.overviewsLanguage,
+            maxRepos: resolved.overviewsMaxRepos,
+            maxTokens: resolved.overviewsMaxTokens,
+            timeoutMs: resolved.overviewsTimeoutMs,
+        });
+        introGenerator = new IntroductionGenerator(ctx, resolveRoute, {
+            language: resolved.overviewsLanguage,
+            maxTokens: resolved.introsMaxTokens,
+            timeoutMs: resolved.introsTimeoutMs,
+        });
+        onRefreshed = (entry, language, since) => {
+            // Fire-and-forget: overview generation never blocks the refresh path;
+            // the panel picks up overviews on its next fetch or poll.
+            generator?.request(entry, language, since);
+        };
+    }
     const cache = new TrendingCache({
         intervalMs: resolved.refreshIntervalMs,
         timeoutMs: resolved.timeoutMs,
+        onRefreshed,
     });
     ctx.effect(() => () => {
         cache.dispose();
@@ -72,7 +126,7 @@ export function apply(ctx, config) {
     ctx.effect(() => ctx.webServer.register({
         kind: 'prefix',
         path: '/github-trending',
-        handler: createTrendingHandler(cache),
+        handler: createTrendingHandler(cache, generator, introGenerator, resolved.overviewsMaxRepos),
     }), 'github-trending: web route');
 }
 /**
@@ -80,10 +134,55 @@ export function apply(ctx, config) {
  * data to the browser side. Runs from the host so it is not subject to browser
  * CORS restrictions. Supports `?refresh=1` to force a host-side refetch.
  *
+ * Each request also tells the overview generator which window the panel is
+ * looking at, and annotates top repositories still waiting for an overview
+ * with `overviewPending: true` (plus `overviewGenerating: true` on the one
+ * currently in flight) so the panel can show a generating indicator.
+ * Repositories whose generation already failed are left unflagged and instead
+ * carry `overviewError` with the reason, so the panel does not wait on them
+ * forever and the failure stays diagnosable.
+ *
+ * `?wait=1` turns the request into a long-poll: when the entry still has
+ * pending overviews, the response is held until the generator makes progress
+ * (or a timeout), so the panel sees each overview the moment it lands.
+ *
+ * `?intro=owner/name` instead serves a full Markdown project introduction,
+ * generated on demand (cached afterwards) — this is what the panel's overview
+ * click opens.
+ *
  * @param cache - shared trending cache.
+ * @param generator - overview scheduler, undefined when overviews are disabled.
+ * @param introGenerator - on-demand introduction generator, same gating.
+ * @param overviewsMaxRepos - only the top N repositories are overview-eligible.
  * @returns the request handler.
  */
-function createTrendingHandler(cache) {
+function createTrendingHandler(cache, generator, introGenerator, overviewsMaxRepos) {
+    /** Whether the entry still has overview-eligible repositories worth waiting for. */
+    function hasPending(entry) {
+        if (generator === undefined)
+            return false;
+        return entry.repositories.some((repo, index) => index < overviewsMaxRepos &&
+            repo.overview === undefined &&
+            generator.failureReason(entry, repo.fullName) === undefined);
+    }
+    /** Attach overviewPending / overviewGenerating / overviewError fields when generation is active. */
+    function present(entry) {
+        if (generator === undefined)
+            return JSON.stringify(entry);
+        const currentFullName = generator.currentFullName;
+        const repositories = entry.repositories.map((repo, index) => {
+            if (index >= overviewsMaxRepos || repo.overview !== undefined)
+                return repo;
+            const failure = generator.failureReason(entry, repo.fullName);
+            if (failure !== undefined)
+                return { ...repo, overviewError: failure };
+            const flags = { overviewPending: true };
+            if (repo.fullName === currentFullName)
+                flags.overviewGenerating = true;
+            return { ...repo, ...flags };
+        });
+        return JSON.stringify({ ...entry, repositories });
+    }
     return async (req, res) => {
         if (req.method !== 'GET' && req.method !== 'HEAD') {
             res.writeHead(405, { 'content-type': 'application/json' });
@@ -91,10 +190,36 @@ function createTrendingHandler(cache) {
             return;
         }
         const url = new URL(req.url ?? '/', 'http://x');
+        // On-demand full project introduction: `?intro=owner/name`.
+        const introFullName = url.searchParams.get('intro');
+        if (introFullName !== null) {
+            if (introGenerator === undefined) {
+                res.writeHead(404, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'introductions are disabled (overviewsEnabled is off)' }));
+                return;
+            }
+            if (!/^[\w.-]+\/[\w.-]+$/.test(introFullName)) {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'intro must be an owner/name repository path' }));
+                return;
+            }
+            try {
+                const introduction = await introGenerator.get(introFullName, cache.findRepository(introFullName));
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
+                res.end(JSON.stringify({ fullName: introFullName, introduction }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                res.writeHead(502, { 'content-type': 'application/json; charset=utf-8' });
+                res.end(JSON.stringify({ error: message }));
+            }
+            return;
+        }
         const language = url.searchParams.get('language') ?? undefined;
         const sinceRaw = url.searchParams.get('since') ?? 'daily';
         const since = sinceRaw === 'weekly' || sinceRaw === 'monthly' ? sinceRaw : 'daily';
         const forceRefresh = url.searchParams.get('refresh') === '1';
+        generator?.setActiveSince(since);
         try {
             const fetchers = {
                 daily: async (signal) => {
@@ -121,11 +246,21 @@ function createTrendingHandler(cache) {
             else {
                 entry = cache.get(language, since);
             }
+            // Long-poll: while overviews are pending, hold the request until the
+            // generator finishes (or starts) the next repository, so the panel
+            // updates the moment each overview lands instead of on a fixed poll
+            // interval. Re-read the cache afterwards: a refresh may have replaced
+            // the entry during the wait.
+            const waitForProgress = req.method === 'GET' && url.searchParams.get('wait') === '1';
+            if (waitForProgress && generator !== undefined && hasPending(entry)) {
+                await generator.waitForChange(OVERVIEW_WAIT_TIMEOUT_MS);
+                entry = cache.get(language, since) ?? entry;
+            }
             res.writeHead(200, {
                 'content-type': 'application/json; charset=utf-8',
                 'cache-control': 'no-cache',
             });
-            res.end(JSON.stringify(entry));
+            res.end(present(entry));
         }
         catch (error) {
             const cached = cache.get(language, since);
@@ -135,7 +270,7 @@ function createTrendingHandler(cache) {
                     'content-type': 'application/json; charset=utf-8',
                     'cache-control': 'no-cache',
                 });
-                res.end(JSON.stringify(cached));
+                res.end(present(cached));
                 return;
             }
             const message = error instanceof Error ? error.message : String(error);

package/lib/intros.js

@@ -0,0 +1,131 @@
+/**
+ * On-demand, README-backed project introductions generated through the harness
+ * LLM service.
+ *
+ * Unlike the automatic per-refresh overviews, a full introduction is generated
+ * only when the user clicks a repository's overview area in the panel
+ * (`GET /github-trending?intro=owner/name`), then cached in memory for the
+ * lifetime of the host process. Concurrent requests for the same repository
+ * share one in-flight generation.
+ *
+ * @module @wangjunjian/dsh-github-trending/intros
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { fetchReadmeText, LANGUAGE_NAMES, streamGeneratedText } from './summaries.js';
+/** Fixed section template, per output language, that every introduction follows. */
+const SECTION_TEMPLATE = {
+    zh: `## <项目名>
+
+#### 核心定位
+面向人群、核心痛点与差异化核心价值；2-3 句。
+
+#### 应用场景
+正向落地场景 + 反向禁忌场景，覆盖适用与不适用边界；2-4 句。
+
+#### 许可证协议
+开源授权说明、商用权限界定、合规与风险评估；1-3 句。README 未提及许可证时，明确写出"仓库未声明开源许可证"。`,
+    en: `## <project name>
+
+#### Core positioning
+Target audience, core pain point, and differentiated core value; 2-3 sentences.
+
+#### Use cases
+Positive fit scenarios plus counter-indications, covering where it applies and where it does not; 2-4 sentences.
+
+#### License
+Open-source license terms, commercial-use permissions, compliance and risk assessment; 1-3 sentences. State explicitly when the README declares no license.`,
+};
+/**
+ * Generate a structured Markdown introduction for a repository via the harness
+ * LLM service.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param repo - trending metadata when the repository is in the cache.
+ * @param fullName - `owner/name` repository path.
+ * @param readme - truncated README text.
+ * @param options - resolved introduction options.
+ * @returns the Markdown introduction.
+ */
+export async function generateIntroduction(ctx, route, repo, fullName, readme, options) {
+    const languageName = LANGUAGE_NAMES[options.language];
+    const system = `You write clear, uniformly structured introductions of GitHub repositories for a trending list. Write in ${languageName}. Output Markdown following EXACTLY this section template, in this order, keeping the headings verbatim:
+
+${SECTION_TEMPLATE[options.language]}
+
+Rules: base everything strictly on the README and metadata given by the user; never invent features, version numbers, or commands that are not in the README; keep the whole introduction under 400 words; output nothing outside this structure.`;
+    const metadata = repo === undefined
+        ? `Repository: ${fullName}`
+        : `Repository: ${repo.fullName}\nDescription: ${repo.description ?? '(none)'}\nLanguage: ${repo.language ?? '(unknown)'}\nStars: ${repo.stars}\nForks: ${repo.forks}\nStars gained in the current window: ${repo.starsToday}`;
+    const messages = [
+        createUserMessage({
+            content: [{ type: 'text', text: `${metadata}\n\nREADME (truncated):\n${readme}` }],
+            source: { kind: 'plugin', plugin: 'github-trending' },
+        }),
+    ];
+    return streamGeneratedText(ctx, route, {
+        messages,
+        system,
+        maxTokens: options.maxTokens,
+        timeoutMs: options.timeoutMs,
+        label: `introduction generation for ${fullName}`,
+    });
+}
+/**
+ * On-demand introduction generator with in-memory caching and in-flight
+ * deduplication.
+ *
+ * Results are cached per `language:fullName` for the lifetime of the host
+ * process — introductions are prose about a repository's README, which rarely
+ * changes within a session. Failures are never cached, so the next click
+ * retries.
+ */
+export class IntroductionGenerator {
+    ctx;
+    resolveRoute;
+    options;
+    cache = new Map();
+    inflight = new Map();
+    constructor(ctx, resolveRoute, options) {
+        this.ctx = ctx;
+        this.resolveRoute = resolveRoute;
+        this.options = options;
+    }
+    /**
+     * Get the introduction for a repository, generating it on first request.
+     *
+     * @param fullName - `owner/name` repository path.
+     * @param repo - trending metadata when available in the cache.
+     * @returns the Markdown introduction.
+     * @throws when the README is unavailable or the LLM call fails.
+     */
+    async get(fullName, repo) {
+        const key = `${this.options.language}:${fullName}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const existing = this.inflight.get(key);
+        if (existing !== undefined)
+            return existing;
+        const promise = this.generate(fullName, repo)
+            .then((text) => {
+            this.cache.set(key, text);
+            return text;
+        })
+            .finally(() => {
+            this.inflight.delete(key);
+        });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    async generate(fullName, repo) {
+        const readme = await fetchReadmeText(fullName);
+        if (readme === undefined) {
+            throw new Error(`introduction generation for ${fullName}: no README found on the default branch`);
+        }
+        // Resolve the route per generation so the current default-model selection
+        // always applies, same as overview generation.
+        return generateIntroduction(this.ctx, this.resolveRoute(), repo, fullName, readme, this.options);
+    }
+}
+//# sourceMappingURL=intros.js.map