@khorsheed/dsh-reader 0.3.0 → 0.3.1

package/lib/types/service.js

@@ -1,9 +1,14 @@
-import { MAX_RECENT_ENTRIES, ReaderStore, ReaderStoreError, boundTranslations, emptyStateDoc, memoryTableChars, TRANSLATION_MEMORY_FILE, } from "./store.js";
-import { defaultSourceLabel, errorMessage, isRetryablePreviewFailure, linkEntryId, DEFAULT_CACHE_POLICY, DEFAULT_TRANSLATION_BUDGET_CHARS, INLINE_BODY_MAX_CHARS, TRANSLATION_STORAGE_VERSION, } from "./types.js";
+import { MAX_RECENT_ENTRIES, ReaderStore, ReaderStoreError, boundTranslations, emptyStateDoc, memoryTableChars, resolveReaderStateRoot, TRANSLATION_MEMORY_FILE, } from "./store.js";
+import { defaultSourceLabel, errorMessage, isRetryablePreviewFailure, linkEntryId, DEFAULT_CACHE_POLICY, DEFAULT_TRANSLATION_BUDGET_CHARS, INLINE_BODY_MAX_CHARS, TRANSLATION_STORAGE_VERSION, isCookieHandshake, } from "./types.js";
 import { delayUntilNext, isCatchUpDue } from "./schedule.js";
 import { arxivHtmlUrl } from "./arxiv.js";
 import { fetchImageBytes, ImageFetchCache } from "./image-fetch.js";
 import { resolveLink } from "./link-resolvers.js";
+import { join } from 'node:path';
+import { LocalTranscriber } from "./local-transcribe.js";
+import { channelRss, episodePage, ReaderMediaHost, resolveShortLink, syntheticLabel, videoPage } from "./media-host.js";
+import { canonicalMediaUrl, isShortMediaLink, mediaLink } from "./media.js";
+import { podcastPageToRss, readEpisodePage } from "./xiaoyuzhou.js";
 /**
  * How many entries one automatic backfill run may fetch.
  *
@@ -14,6 +19,15 @@ import { resolveLink } from "./link-resolvers.js";
 export const BACKFILL_MAX_PER_RUN = 8;
 /** How long a FAILED fetch is left alone before it may be retried (6 hours). */
 export const BACKFILL_RETRY_MS = 6 * 60 * 60 * 1000;
+/**
+ * How many sources one refresh fetches at once.
+ *
+ * A strictly sequential loop made one dead source (a full 30 s timeout) stall
+ * every source behind it — the "refresh takes minutes" half of the slow-load
+ * report. Three at a time is the politeness ceiling this package applies to
+ * other people's servers everywhere (the backfill runs at two).
+ */
+export const REFRESH_CONCURRENCY = 3;
 /** Cross-origin redirect hops the service will follow before giving up. */
 const MAX_REDIRECT_HOPS = 3;
 /** Upper bound on summaries handed to the browser in one call. */
@@ -77,6 +91,10 @@ export function classifyPayload(raw) {
 /** The reader service. */
 export class ReaderService {
     store;
+    /** Video and audio entries: synthetic pages, channel feeds, transcripts. */
+    media;
+    /** Local transcription of entries without captions (the optional `transcribe` engine). */
+    local;
     ctx;
     timer;
     disposed = false;
@@ -91,8 +109,30 @@ export class ReaderService {
     constructor(ctx, config = {}) {
         this.ctx = ctx;
         this.store = new ReaderStore(config);
+        const stateRoot = resolveReaderStateRoot(config.stateRoot);
+        this.media = new ReaderMediaHost(stateRoot, config.ytdlpPath);
+        this.local = new LocalTranscriber({
+            engine: () => ctx.get('transcribe'),
+            tmpRoot: join(stateRoot, 'tmp'),
+            videoAudio: (url, dir, options) => this.media.ytdlp.audio(url, dir, options),
+            store: async (entryId, url, html, language, speakers) => {
+                await this.storeEntryBody({ entryId, url, html, keep: true });
+                const before = this.media.captions(entryId);
+                // Names survive a re-transcription that finds the same number of voices.
+                const names = before?.names !== undefined && (speakers === undefined || speakers === before.speakers) ? before.names : undefined;
+                const count = speakers ?? before?.speakers;
+                this.media.remember(entryId, {
+                    state: 'local',
+                    ...(language === undefined ? {} : { language }),
+                    checkedAt: new Date().toISOString(),
+                    ...(count === undefined ? {} : { speakers: count }),
+                    ...(names === undefined ? {} : { names }),
+                });
+            },
+        });
         ctx.effect(() => () => {
             this.disposed = true;
+            this.local.dispose();
             if (this.timer !== undefined)
                 clearTimeout(this.timer);
         }, 'reader: daily refresh');
@@ -161,7 +201,7 @@ export class ReaderService {
             return 'duplicate';
         let fetched;
         try {
-            fetched = await this.fetchFollowing(upgrade ?? url);
+            fetched = await this.fetchSource(upgrade ?? url);
         }
         catch (error) {
             if (upgrade !== undefined && isNoHtmlVersion(error)) {
@@ -180,7 +220,7 @@ export class ReaderService {
             }
         }
         const feed = classifyPayload(fetched.raw) === 'feed';
-        if (!feed) {
+        if (!feed && fetched.media !== true) {
             // A page that fetched fine can still have nothing to read: a bot
             // challenge, a login interstitial, an empty shell. Classify BEFORE the
             // payload is stored, so a challenge page never becomes the card's body —
@@ -189,13 +229,20 @@ export class ReaderService {
             const problem = inspectPreview(fetched.raw, fetched.url, upgrade ?? url);
             if (problem !== undefined) {
                 return await this.saveLinkOnly({
-                    url: fetched.url,
+                    // The address the reader gave, not where the refusal landed: a
+                    // challenge redirect (mp.weixin.qq.com → /wappoc_appmsgcaptcha)
+                    // would otherwise become the card's title and the URL every later
+                    // fetch — the rendered one included — asks for.
+                    url,
                     ...(request.label === undefined ? {} : { label: request.label }),
                     ...(resolvedFrom === undefined ? {} : { resolvedFrom }),
                 }, { code: problem.code, message: problem.message, at: now }, now);
             }
         }
-        const label = request.label ?? (resolution?.kind === 'arxiv' ? resolution.title : undefined) ?? defaultSourceLabel(fetched.url);
+        const label = request.label
+            ?? (resolution?.kind === 'arxiv' ? resolution.title : undefined)
+            ?? (fetched.media === true ? syntheticLabel(fetched.raw) : undefined)
+            ?? defaultSourceLabel(fetched.url);
         const source = {
             id: `${feed ? 'rss' : 'link'}-${hash(fetched.url)}`,
             kind: feed ? 'rss' : 'link',
@@ -209,7 +256,7 @@ export class ReaderService {
             ...(resolvedFrom === undefined ? {} : { resolvedFrom }),
             raw: fetched.raw,
         };
-        await this.commit(current => ({ ...current, sources: [source, ...current.sources] }));
+        await this.commit(current => withNewSource(current, source));
         return { outcome: feed ? 'subscribed' : 'saved-link', kind: source.kind, id: source.id, label };
     }
     /**
@@ -245,7 +292,7 @@ export class ReaderService {
             failure,
             ...(request.resolvedFrom === undefined ? {} : { resolvedFrom: request.resolvedFrom }),
         };
-        await this.commit(current => ({ ...current, sources: [source, ...current.sources] }));
+        await this.commit(current => withNewSource(current, source));
         await this.recordFetchFailure(linkEntryId(source.id), failure.message);
         return {
             outcome: 'saved-link',
@@ -345,63 +392,80 @@ export class ReaderService {
         const results = [];
         const patches = new Map();
         const base = new Map(doc.sources.map(source => [source.id, source]));
-        for (const source of wanted) {
-            const fetchedAt = new Date().toISOString();
-            try {
-                const fetched = await this.fetchFollowing(source.url);
-                // The same classification the add performs: a refresh that comes back
-                // with a challenge page or a PDF must not replace a good body with it,
-                // and must record why there is nothing to read.
-                const problem = source.kind === 'link' ? inspectPreview(fetched.raw, fetched.url, source.url) : undefined;
-                if (problem !== undefined) {
-                    const failure = { code: problem.code, message: problem.message, at: fetchedAt };
+        /**
+         * Failures to record AFTER the pool: the workers below run concurrently,
+         * but every document write (a failure record is its own commit) stays
+         * single-filed here — the store's commit is a read-modify-write, and two
+         * in flight at once is how a lost update happens.
+         */
+        const failures = [];
+        const queue = [...wanted];
+        const workers = Array.from({ length: Math.min(REFRESH_CONCURRENCY, queue.length) }, async () => {
+            for (;;) {
+                const source = queue.shift();
+                if (source === undefined)
+                    return;
+                const fetchedAt = new Date().toISOString();
+                try {
+                    const fetched = await this.fetchSource(source.url);
+                    // The same classification the add performs: a refresh that comes back
+                    // with a challenge page or a PDF must not replace a good body with it,
+                    // and must record why there is nothing to read.
+                    const problem = source.kind === 'link' && fetched.media !== true ? inspectPreview(fetched.raw, fetched.url, source.url) : undefined;
+                    if (problem !== undefined) {
+                        const failure = { code: problem.code, message: problem.message, at: fetchedAt };
+                        patches.set(source.id, {
+                            // Keep the last-known-good payload: a site that starts refusing us
+                            // must not erase the article the reader already had.
+                            // …and keep its address: the refusal's landing page is not it.
+                            ...withoutFailure(source),
+                            fetchedAt,
+                            status: 'error',
+                            error: failure.message,
+                            failure,
+                        });
+                        failures.push({ entryId: linkEntryId(source.id), message: failure.message });
+                        results.push({ id: source.id, status: 'unavailable', message: failure.message });
+                        continue;
+                    }
                     patches.set(source.id, {
-                        // Keep the last-known-good payload: a site that starts refusing us
-                        // must not erase the article the reader already had.
-                        ...withoutFailure({ ...source, url: fetched.url, ...(source.raw === undefined ? {} : { raw: source.raw }) }),
+                        ...withoutFailure(source),
+                        url: fetched.url,
+                        raw: fetched.raw,
+                        fetchedAt,
+                        status: 'ok',
+                        truncated: fetched.truncated,
+                    });
+                    results.push({
+                        id: source.id,
+                        status: fetched.truncated ? 'truncated' : 'ok',
+                        ...(fetched.truncated ? { message: "payload hit the fetch seam's size cap" } : {}),
+                    });
+                }
+                catch (error) {
+                    const failure = classifyFetchFailure(error, fetchedAt);
+                    // A failed refresh keeps the previous payload (last-known-good) and
+                    // records why: a transient network error must not erase the reader's
+                    // copy of an article.
+                    const previous = base.get(source.id);
+                    patches.set(source.id, {
+                        ...(previous ?? source),
                         fetchedAt,
                         status: 'error',
                         error: failure.message,
                         failure,
                     });
-                    await this.recordFetchFailure(linkEntryId(source.id), failure.message);
-                    results.push({ id: source.id, status: 'unavailable', message: failure.message });
-                    continue;
+                    results.push({
+                        id: source.id,
+                        status: error instanceof UnsupportedContent ? 'unavailable' : 'fetch-failed',
+                        message: failure.message,
+                    });
                 }
-                patches.set(source.id, {
-                    ...withoutFailure(source),
-                    url: fetched.url,
-                    raw: fetched.raw,
-                    fetchedAt,
-                    status: 'ok',
-                    truncated: fetched.truncated,
-                });
-                results.push({
-                    id: source.id,
-                    status: fetched.truncated ? 'truncated' : 'ok',
-                    ...(fetched.truncated ? { message: "payload hit the fetch seam's size cap" } : {}),
-                });
             }
-            catch (error) {
-                const failure = classifyFetchFailure(error, fetchedAt);
-                // A failed refresh keeps the previous payload (last-known-good) and
-                // records why: a transient network error must not erase the reader's
-                // copy of an article.
-                const previous = base.get(source.id);
-                patches.set(source.id, {
-                    ...(previous ?? source),
-                    fetchedAt,
-                    status: 'error',
-                    error: failure.message,
-                    failure,
-                });
-                results.push({
-                    id: source.id,
-                    status: error instanceof UnsupportedContent ? 'unavailable' : 'fetch-failed',
-                    message: failure.message,
-                });
-            }
-        }
+        });
+        await Promise.all(workers);
+        for (const failure of failures)
+            await this.recordFetchFailure(failure.entryId, failure.message);
         if (patches.size > 0) {
             await this.commit(current => ({
                 ...current,
@@ -534,6 +598,15 @@ export class ReaderService {
         await this.markFetching(request.entryId);
         try {
             const fetched = await this.fetchFollowing(url);
+            // A bot challenge answers 200 with its own little page (mp.weixin.qq.com's
+            // 「环境异常」, for one): extracted, it would be stored as the article.
+            // Record it as the refusal it is, so the browser half can escalate to a
+            // rendered fetch instead of showing the challenge text as the body.
+            const wall = inspectPreview(fetched.raw, fetched.url, url);
+            if (wall?.code === 'blocked') {
+                await this.recordFetchFailure(request.entryId, wall.message, wall.code);
+                return { entryId: request.entryId, error: wall.message };
+            }
             // The raw payload is written to disk BEFORE the caller gets it, so a
             // browser that goes away mid-request does not cost the reader the
             // download: the next visit finds the stored payload and extracts it.
@@ -720,7 +793,7 @@ export class ReaderService {
             fetchedAt: now.toISOString(),
             // 0 = keep until the budget evicts it; a far-future date keeps the
             // freshness check a single comparison instead of a special case.
-            expiresAt: ttlHours === 0
+            expiresAt: ttlHours === 0 || request.keep === true
                 ? new Date(now.getTime() + 100 * 365 * 24 * 60 * 60 * 1000).toISOString()
                 : new Date(now.getTime() + ttlHours * 60 * 60 * 1000).toISOString(),
             url: request.url,
@@ -800,6 +873,9 @@ export class ReaderService {
                 continue;
             if (entry.hasBody)
                 continue;
+            // A video or podcast page is not an article: its text is the transcript.
+            if (mediaLink(entry.url) !== undefined)
+                continue;
             // A reason that will answer the same way forever — a bot wall, a login
             // wall, a PDF, a 404 — is not retried on a timer: that is a crawler with
             // a grudge, not a reader. The manual refresh in the subscription page
@@ -1410,6 +1486,128 @@ export class ReaderService {
         }
         throw new UnsupportedContent(`more than ${MAX_REDIRECT_HOPS} cross-origin redirects`);
     }
+    /**
+     * Fetch a source's payload, media-aware (media-host.ts).
+     *
+     * A YouTube channel is fetched as YouTube's own channel feed; a Xiaoyuzhou
+     * podcast page as the RSS document it is turned into; a single video or
+     * Xiaoyuzhou episode as a synthetic page carrying its media description.
+     * Everything else is the ordinary {@link fetchFollowing}.
+     *
+     * @param url - the source URL.
+     */
+    async fetchSource(url) {
+        // A share short link (b23.tv) is a cross-site redirect the ordinary fetch
+        // refuses by design: resolve it first, then treat the page it names.
+        if (isShortMediaLink(url)) {
+            const target = await resolveShortLink(url);
+            if (target === '' || isShortMediaLink(target))
+                throw new UnsupportedContent('the short link leads nowhere');
+            return this.fetchSource(canonicalMediaUrl(target) ?? target);
+        }
+        const link = mediaLink(url);
+        if (link === undefined)
+            return this.fetchFollowing(url);
+        if (link.provider === 'youtube' && link.kind === 'channel') {
+            return { url, raw: channelRss(await this.media.ytdlp.channel(url), url), truncated: false };
+        }
+        if (link.provider === 'xiaoyuzhou') {
+            const page = await this.fetchFollowing(url);
+            if (link.kind === 'podcast') {
+                const rss = podcastPageToRss(page.raw, url);
+                if (rss === undefined)
+                    throw new UnsupportedContent('the podcast page carries no episodes');
+                return { url, raw: rss, truncated: false };
+            }
+            const episode = readEpisodePage(page.raw);
+            if (episode === undefined)
+                throw new UnsupportedContent('the episode page carries no audio');
+            return { url, raw: episodePage(episode), truncated: false, media: true };
+        }
+        if (link.kind === 'video' && (link.provider === 'youtube' || link.provider === 'bilibili')) {
+            const clean = canonicalMediaUrl(url) ?? url;
+            const info = await this.media.ytdlp.info(clean);
+            return { url: clean, raw: videoPage(info, link.provider, link.id), truncated: false, media: true };
+        }
+        return this.fetchFollowing(url);
+    }
+    /**
+     * A video entry's transcript: the stored one, else the platform captions
+     * fetched now and kept (no TTL — it costs a yt-dlp run). A video known to
+     * have no captions answers so without running yt-dlp again.
+     *
+     * @param request - the entry and its video page URL.
+     * @returns the transcript markup, `none`, or why it failed.
+     */
+    async mediaTranscript(request) {
+        const known = this.media.captions(request.entryId);
+        // `local`: the platform had none — the stored body is the local transcript.
+        if (known?.state === 'none' || known?.state === 'local')
+            return { entryId: request.entryId, captions: 'none' };
+        const link = mediaLink(request.url);
+        if (link?.kind !== 'video' || (link.provider !== 'youtube' && link.provider !== 'bilibili')) {
+            return { entryId: request.entryId, captions: 'none' };
+        }
+        try {
+            const transcript = await this.media.transcript(request.url);
+            if (transcript === 'none') {
+                this.media.remember(request.entryId, { state: 'none', checkedAt: new Date().toISOString() });
+                return { entryId: request.entryId, captions: 'none' };
+            }
+            const stored = await this.storeEntryBody({ entryId: request.entryId, url: request.url, html: transcript.html, keep: true });
+            this.media.remember(request.entryId, { state: 'platform', language: transcript.language, checkedAt: new Date().toISOString() });
+            return { entryId: request.entryId, captions: 'platform', language: transcript.language, ...(stored.html === undefined ? {} : { html: stored.html }) };
+        }
+        catch (error) {
+            return { entryId: request.entryId, captions: 'failed', error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /** The reader's names for an entry's speakers, by index. */
+    speakerNames(request) {
+        return { ...(this.media.captions(request.entryId)?.names ?? {}) };
+    }
+    /**
+     * Name one speaker of an entry's transcript (an empty name restores the default).
+     *
+     * @param request - the entry, the speaker's index, the name.
+     */
+    nameSpeaker(request) {
+        const record = this.media.captions(request.entryId);
+        if (record === undefined)
+            return {};
+        const names = { ...(record.names ?? {}) };
+        const name = request.name.trim().slice(0, 40);
+        if (name === '')
+            delete names[String(request.speaker)];
+        else
+            names[String(request.speaker)] = name;
+        this.media.remember(request.entryId, { ...record, names });
+        return names;
+    }
+    /**
+     * The wall's media cards: a live local job first, else what the captions
+     * record says (platform captions, a stored local transcript, none).
+     *
+     * @param request - the card ids on screen.
+     */
+    mediaStates(request) {
+        const states = {};
+        for (const entryId of request.entryIds) {
+            const job = this.local.status(entryId);
+            if (job.state === 'fetching' || job.state === 'queued' || job.state === 'transcribing') {
+                states[entryId] = { state: job.state, ...(job.progress === undefined ? {} : { progress: job.progress }), ...(job.ahead === undefined ? {} : { ahead: job.ahead }) };
+                continue;
+            }
+            if (job.state === 'failed') {
+                states[entryId] = { state: 'failed' };
+                continue;
+            }
+            const record = this.media.captions(entryId);
+            if (record !== undefined)
+                states[entryId] = { state: record.state };
+        }
+        return { engine: this.local.engineAvailable(), states };
+    }
     /** Arm (or re-arm) the daily refresh timer against the current document. */
     async armSchedule() {
         if (this.disposed)
@@ -1450,6 +1648,25 @@ export function normalizeUrl(input) {
     }
 }
 /** Whether two URLs point at the same target, ignoring a trailing slash. */
+/**
+ * The document with `source` added, unless an add that raced this one already
+ * filed it.
+ *
+ * `addSource` checks for a duplicate BEFORE its fetch, which takes long enough
+ * (hundreds of ms to seconds) for a second click on 「添加」 to pass the same
+ * check; both then committed, and the reader saw the card twice under one id
+ * (measured on 3080, 2026-10-04: two `link-1v6imqy` rows 0.7 s apart). The
+ * re-check inside the commit is what makes the add idempotent.
+ *
+ * @param doc - the current document.
+ * @param source - the source to file.
+ * @returns the document, with the source prepended when it is new.
+ */
+function withNewSource(doc, source) {
+    if (doc.sources.some(existing => existing.id === source.id || sameTarget(existing.url, source.url)))
+        return doc;
+    return { ...doc, sources: [source, ...doc.sources] };
+}
 function sameTarget(a, b) {
     const strip = (value) => value.replace(/\/+$/, '');
     return strip(a) === strip(b);
@@ -1514,7 +1731,7 @@ function errorCode(error) {
     return typeof code === 'string' ? code : undefined;
 }
 /** Marker words a bot wall leaves on an otherwise empty page. */
-const BOT_WALL_PATTERN = /just a moment|checking your browser|cf-chl|cf_chl|attention required|unusual traffic|captcha|verifying you are human|enable javascript and cookies|access denied|are you a robot|验证码|人机验证|访问验证|安全验证/;
+const BOT_WALL_PATTERN = /just a moment|checking your browser|cf-chl|cf_chl|attention required|unusual traffic|captcha|verifying you are human|enable javascript and cookies|access denied|are you a robot|验证码|人机验证|访问验证|安全验证|环境异常|完成验证后/;
 /** Marker words an authentication interstitial leaves behind. */
 const LOGIN_WALL_PATTERN = /cookie required|requires? cookies|sign in|sign-in|log in|login|please log|single sign|sso|qurl=|ezproxy|shibboleth|访问权限|请登录|登录后/;
 /** Hosts whose NAME alone says the hop is an authentication wall. */
@@ -1575,6 +1792,10 @@ export function classifyFetchFailure(error, at) {
         return { code: 'unsupported-type', message, at };
     }
     if (code === 'WEB_REDIRECT_BLOCKED' || /cross-origin redirect/i.test(message)) {
+        // A cookie handshake (Springer Nature's idp bounce) is a wall a browser
+        // walks through, not a login: `blocked` lets the pane render it.
+        if (isCookieHandshake(message))
+            return { code: 'blocked', message, at };
         // A hop to a host whose name says "login" is a login wall, not merely a
         // move: the reader's next action differs (sign in elsewhere vs paste the
         // destination URL).

package/lib/types/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `reader` skill: how to discuss an article from the user's reader, when
+ * to write into its notes, and how a 「让Agent考考我」 round runs. The tool
+ * descriptions stay one or two lines; this is loaded on demand (the canvas
+ * skill's pattern).
+ *
+ * The 考考我 contract is the 2026-10-19 design (proposals/active/
+ * 2026-10-19-reader-notes-feynman.md, D5–D7): the model plays a student, asks
+ * one batch of explain-it questions, and after the user's single answer writes
+ * down only what was not yet right — never a score.
+ *
+ * @module @khorsheed/dsh-reader/skill
+ */
+/** The skill's catalog name. */
+export declare const READER_SKILL_NAME = "reader";
+/** The one catalog line the model sees before loading it. */
+export declare const READER_SKILL_DESCRIPTION: string;
+/** The skill body. */
+export declare const READER_SKILL_CONTENT = "# reader \u2014 discussing an article and keeping what it came to\n\nThe user reads articles in the reader (\u7075\u611F\u7A7A\u95F4), keeps excerpts with comments (notes n1, n2\u2026), and brings them into\nthe conversation. A draft from the reader quotes notes as `n2 \u00B63\u300C\u2026\u300D` and names the article id.\n\n## Reading \u2014 reader_read\n\n- No arguments: the article this conversation discussed, else the one the user opened last. `entry` takes an id,\n  a link or part of the title. Long articles page: continue with `from`.\n- The text is \u00B6-numbered; cite paragraphs as \u00B63 so the user can jump back. The notes and earlier discussion notes\n  follow the text \u2014 use them, do not ask the user to paste.\n- An article the user never opened has no text on the host; say so and ask them to open it once.\n\n## Writing notes \u2014 reader_note\n\nWrite only when the user asks (\u300C\u8BB0\u5230\u7B14\u8BB0\u300D\u300C\u628A\u7ED3\u8BBA\u5B58\u4E0B\u6765\u300D\u2026) or a \u8003\u8003\u6211 round ends. Never on your own initiative,\nnever every turn. You cannot edit or delete what the user wrote; they can edit what you wrote.\n\n- A conclusion about ONE note: `op=conclusion`, `note=n2`, `text` = the conclusion in one or two sentences,\n  in the user's language, as plain as possible.\n- Conclusions spanning several notes, or a whole discussion: `op=discussion`, `text` = one point per line; put\n  `\u00B63` in a line to cite the paragraph it rests on.\n- If nested or optional arguments may not arrive, the text alone works: first lines `\u7B14\u8BB0\uFF1An2` or `\u7C7B\u578B\uFF1A\u8003\u8003\u6211`,\n  then the body.\n\n## \u8BA9Agent\u8003\u8003\u6211 \u2014 a Feynman check, not an exam\n\nThe user finished the article and wants to see what they really understood by explaining it.\n\n1. Read the article and the notes with reader_read.\n2. Play a student who has NOT read it. Ask 3\u20135 questions in ONE message, numbered. Every question asks the user to\n   explain in their own words \u2014 \u300C\u7ED9\u6211\u8BB2\u8BB2\u2026\u300D\u300C\u4E3A\u4EC0\u4E48\u2026\u300D\u300C\u6253\u4E2A\u6BD4\u65B9\uFF1F\u300D. No multiple choice, no fill-in-the-blank, no\n   recall of numbers or names for their own sake.\n3. Pick questions from two places: what the user noted (do they really get it?) and the article's key points they\n   did NOT note (likely skimmed).\n4. Wait for the user to answer all of them in one message. Do not judge, hint or correct while asking.\n5. Then, against the article: say in one line which answers were fine, and for each one that was wrong, missing a\n   step, or vague (\u300C\u6548\u679C\u597D\u300D is vague \u2014 say what the actual reason is), give the specific explanation and the \u00B6 it\n   rests on. Do not ask follow-up questions first; the user can keep talking if they want more.\n6. Write it down: `reader_note` with `op=discussion`, `kind=check`, one point per line \u2014 ONLY what was not yet\n   right, each with its explanation and \u00B6; a last line \u300C\u5176\u4F59 N \u9898\u8BB2\u5230\u4F4D\u4E86\u300D when some were fine.\n\nNo score, no grade, no \"retake\": another round is simply another discussion note.\n\n## \u8BA9Agent\u6DA6\u8272\u8BD1\u6587 \u2014 reader_translate\n\nThe user asked for a better Chinese translation of the whole article than the browser's machine translation.\n\n1. Read the original with reader_read, a batch at a time (`from`). Translate from the ORIGINAL, whole paragraphs,\n   with the paragraphs around them in mind: faithful, natural Chinese, not word for word. Keep names, terms and how\n   each speaker is rendered consistent across batches. Do not add notes or explanations inside the translation.\n   A transcript paragraph starts with `[mm:ss] \u540D\u5B57\uFF1A` \u2014 translate only the speech after it.\n2. Send each batch with reader_translate: `text` = lines `\u00B612\uFF1A\u8BD1\u6587`, one paragraph per line, the \u00B6 numbers\n   reader_read showed. Its answer says how many are done and where the next batch starts.\n3. Keep going batch after batch in the same turn until it says every paragraph is done. Do not stop to ask. Follow\n   any wish the user added to the request (\u300C\u53E3\u8BED\u4E00\u70B9\u300D\u2026).\n4. Finish with one line to the user: done, and anything you could not render well. Do not paste the translation\n   into the conversation \u2014 it is in the reader.\n";
+//# sourceMappingURL=skill.d.ts.map

package/lib/types/skill.js

@@ -0,0 +1,78 @@
+/**
+ * The `reader` skill: how to discuss an article from the user's reader, when
+ * to write into its notes, and how a 「让Agent考考我」 round runs. The tool
+ * descriptions stay one or two lines; this is loaded on demand (the canvas
+ * skill's pattern).
+ *
+ * The 考考我 contract is the 2026-10-19 design (proposals/active/
+ * 2026-10-19-reader-notes-feynman.md, D5–D7): the model plays a student, asks
+ * one batch of explain-it questions, and after the user's single answer writes
+ * down only what was not yet right — never a score.
+ *
+ * @module @khorsheed/dsh-reader/skill
+ */
+/** The skill's catalog name. */
+export const READER_SKILL_NAME = 'reader';
+/** The one catalog line the model sees before loading it. */
+export const READER_SKILL_DESCRIPTION = 'How to work with the user\'s reader (灵感空间) articles and notes: reading with reader_read, when and how to write '
+    + 'conclusions and discussion notes with reader_note, how a 「让Agent考考我」 (quiz me) round runs, and how to 润色 (re-translate) an article with reader_translate. Load before reader_note or reader_translate.';
+/** The skill body. */
+export const READER_SKILL_CONTENT = `# reader — discussing an article and keeping what it came to
+
+The user reads articles in the reader (灵感空间), keeps excerpts with comments (notes n1, n2…), and brings them into
+the conversation. A draft from the reader quotes notes as \`n2 ¶3「…」\` and names the article id.
+
+## Reading — reader_read
+
+- No arguments: the article this conversation discussed, else the one the user opened last. \`entry\` takes an id,
+  a link or part of the title. Long articles page: continue with \`from\`.
+- The text is ¶-numbered; cite paragraphs as ¶3 so the user can jump back. The notes and earlier discussion notes
+  follow the text — use them, do not ask the user to paste.
+- An article the user never opened has no text on the host; say so and ask them to open it once.
+
+## Writing notes — reader_note
+
+Write only when the user asks (「记到笔记」「把结论存下来」…) or a 考考我 round ends. Never on your own initiative,
+never every turn. You cannot edit or delete what the user wrote; they can edit what you wrote.
+
+- A conclusion about ONE note: \`op=conclusion\`, \`note=n2\`, \`text\` = the conclusion in one or two sentences,
+  in the user's language, as plain as possible.
+- Conclusions spanning several notes, or a whole discussion: \`op=discussion\`, \`text\` = one point per line; put
+  \`¶3\` in a line to cite the paragraph it rests on.
+- If nested or optional arguments may not arrive, the text alone works: first lines \`笔记：n2\` or \`类型：考考我\`,
+  then the body.
+
+## 让Agent考考我 — a Feynman check, not an exam
+
+The user finished the article and wants to see what they really understood by explaining it.
+
+1. Read the article and the notes with reader_read.
+2. Play a student who has NOT read it. Ask 3–5 questions in ONE message, numbered. Every question asks the user to
+   explain in their own words — 「给我讲讲…」「为什么…」「打个比方？」. No multiple choice, no fill-in-the-blank, no
+   recall of numbers or names for their own sake.
+3. Pick questions from two places: what the user noted (do they really get it?) and the article's key points they
+   did NOT note (likely skimmed).
+4. Wait for the user to answer all of them in one message. Do not judge, hint or correct while asking.
+5. Then, against the article: say in one line which answers were fine, and for each one that was wrong, missing a
+   step, or vague (「效果好」 is vague — say what the actual reason is), give the specific explanation and the ¶ it
+   rests on. Do not ask follow-up questions first; the user can keep talking if they want more.
+6. Write it down: \`reader_note\` with \`op=discussion\`, \`kind=check\`, one point per line — ONLY what was not yet
+   right, each with its explanation and ¶; a last line 「其余 N 题讲到位了」 when some were fine.
+
+No score, no grade, no "retake": another round is simply another discussion note.
+
+## 让Agent润色译文 — reader_translate
+
+The user asked for a better Chinese translation of the whole article than the browser's machine translation.
+
+1. Read the original with reader_read, a batch at a time (\`from\`). Translate from the ORIGINAL, whole paragraphs,
+   with the paragraphs around them in mind: faithful, natural Chinese, not word for word. Keep names, terms and how
+   each speaker is rendered consistent across batches. Do not add notes or explanations inside the translation.
+   A transcript paragraph starts with \`[mm:ss] 名字：\` — translate only the speech after it.
+2. Send each batch with reader_translate: \`text\` = lines \`¶12：译文\`, one paragraph per line, the ¶ numbers
+   reader_read showed. Its answer says how many are done and where the next batch starts.
+3. Keep going batch after batch in the same turn until it says every paragraph is done. Do not stop to ask. Follow
+   any wish the user added to the request (「口语一点」…).
+4. Finish with one line to the user: done, and anything you could not render well. Do not paste the translation
+   into the conversation — it is in the reader.
+`;