[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_271":272,"_273":274},"routes/_app.x.$handle.$name",{"_96":95,"_32":46,"_104":86,"_27":54,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":25,"_118":119,"_120":25,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_44":45,"_32":46,"_39":47,"_48":-5,"_49":25,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":-5,"_58":25,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":25},"version",60,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":35,"_36":38,"_39":40,"_41":14,"_42":43,"_24":25},"previous",{"_30":31,"_32":33,"_34":35,"_36":37},"deleted",false,"deletedHere","path","src/resolver.ts","latestPath","fileId","738cc2a4-8ef3-11f1-a0c7-1607ee4eb77e","name","resolver.ts","fileType","script","content","import type { Config } from \"./config.ts\";\nimport { type Repo, searchRepos, searchReposBatch } from \"./github.ts\";\nimport { fetchWithRetry } from \"./http.ts\";\nimport type {\n CacheEntry,\n Confidence,\n ResolvedItem,\n ResolveResult,\n SearchHit,\n WeeklyItem,\n} from \"./types.ts\";\n\n/** Link aggregators and content scrapers that outrank the original on search engines. */\nconst AGGREGATORS = [\n \"news.ycombinator.com\",\n \"lobste.rs\",\n \"reddit.com\",\n \"daily.dev\",\n \"vuink.com\",\n \"nostr.ae\",\n \"x.com\",\n \"twitter.com\",\n \"facebook.com\",\n \"linkedin.com\",\n \"onlinedocs.net\",\n \"viralpique.com\",\n \"emergentmind.com\",\n \"aicompass.dev\",\n \"csdn.net\",\n \"cnblogs.com\",\n \"juejin.cn\",\n \"zhihu.com\",\n \"51cto.com\",\n];\n\n/**\n * Same idea, but matched on the first label of the hostname so every country\n * domain is covered at once — Pinterest alone answers on .com, .co.uk, .ca,\n * .de and a dozen more, and listing them individually is a losing game.\n */\nconst AGGREGATOR_BRANDS = [\"pinterest\", \"flipboard\", \"scoop\"];\n\n// deno-fmt-ignore\nconst STOPWORDS = new Set([\n \"a\", \"an\", \"and\", \"are\", \"as\", \"at\", \"be\", \"by\", \"for\", \"from\", \"how\", \"in\",\n \"is\", \"it\", \"of\", \"on\", \"or\", \"that\", \"the\", \"to\", \"with\", \"what\", \"your\",\n]);\n\n/** Give up looking for a link after this many runs so a bad item never blocks the send. */\nconst MAX_ATTEMPTS = 2;\n\n/**\n * Title-overlap thresholds. Below `minimum` we publish no link at all: a wrong\n * link is worse than a 🔍 that asks the reader to check for themselves.\n *\n * `recall` is a separate floor for calling a link confident. A short, tidy\n * candidate title scores a high F1 off a fraction of the headline —\n * \"DuckDB vs. SQLite\" against \"SQLite vs DuckDB on the Same $16 Box\" reaches\n * 0.67 while ignoring every word that identifies the article. Requiring most\n * of the headline to be accounted for is what separates the two.\n */\nexport const LINK_THRESHOLD = { confident: 0.6, minimum: 0.45, recall: 0.6 };\n\nexport interface Candidate {\n url: string;\n score: number;\n recall: number;\n /** The url itself echoes some of the headline, not just the page title. */\n corroborated: boolean;\n via: string;\n}\n\n/**\n * Copying the headline verbatim is exactly what scrapers and pin boards do, so\n * a perfect title match on its own is as much a warning as a signal. Requiring\n * the url to echo something of the headline is what separates the article from\n * the sites that merely quote it — an original almost always carries the words\n * in its slug or its domain, while a reposter's url is an opaque id.\n */\nfunction isConfident(candidate: Candidate): boolean {\n return candidate.score >= LINK_THRESHOLD.confident &&\n candidate.recall >= LINK_THRESHOLD.recall &&\n candidate.corroborated;\n}\n\n/**\n * A candidate that accounts for the whole headline wins over one that doesn't,\n * even when the latter's raw overlap is a hair higher.\n */\nfunction better(candidate: Candidate, incumbent: Candidate | null): boolean {\n if (incumbent === null) return true;\n if (isConfident(candidate) !== isConfident(incumbent)) return isConfident(candidate);\n return candidate.score > incumbent.score;\n}\n\nfunction tokenize(text: string): string[] {\n return text\n .toLowerCase()\n .replace(/[^a-z0-9\\u4e00-\\u9fa5]+/g, \" \")\n .split(\" \")\n .filter((token) => token.length > 1 && !STOPWORDS.has(token));\n}\n\n/** Fraction of the query's significant tokens that appear in the candidate. */\nexport function coverage(query: string, candidate: string): number {\n const wanted = tokenize(query);\n if (!wanted.length) return 0;\n const have = new Set(tokenize(candidate));\n return wanted.filter((token) => have.has(token)).length / wanted.length;\n}\n\ninterface Match {\n /** F1: balances how much of the headline is covered against padding. */\n score: number;\n /** Share of the headline's own words the candidate accounts for. */\n recall: number;\n}\n\n/** Overlap of two token sets. Split out so a query is tokenized once per search. */\nfunction overlap(wanted: Set, have: Set): Match {\n if (!wanted.size || !have.size) return { score: 0, recall: 0 };\n\n let shared = 0;\n for (const token of wanted) if (have.has(token)) shared += 1;\n if (!shared) return { score: 0, recall: 0 };\n\n const recall = shared / wanted.size;\n const precision = shared / have.size;\n return { score: (2 * recall * precision) / (recall + precision), recall };\n}\n\n/**\n * Balanced overlap between two titles. Plain coverage is not enough: a long,\n * unrelated headline can contain most of a short query's words and still be\n * the wrong article, so the candidate's own extra words have to count against it.\n */\nexport function similarity(query: string, candidate: string): number {\n return overlap(new Set(tokenize(query)), new Set(tokenize(candidate))).score;\n}\n\nfunction isAggregator(url: string): boolean {\n try {\n const host = new URL(url).hostname.replace(/^www\\./, \"\");\n if (AGGREGATORS.some((domain) => host === domain || host.endsWith(`.${domain}`))) return true;\n return AGGREGATOR_BRANDS.includes(host.split(\".\")[0]);\n } catch {\n return true;\n }\n}\n\n/**\n * Tokens from the last path segment, which on most blogs is the headline in\n * slug form: /2026/07/30/wheels-bottles-images.html -> wheels bottles images.\n */\nfunction slugTokens(url: string): Set {\n try {\n const segment = new URL(url).pathname.split(\"/\").filter(Boolean).pop() ?? \"\";\n return new Set(tokenize(segment.replace(/\\.\\w+$/, \"\")));\n } catch {\n return new Set();\n }\n}\n\n/** Everything addressable in the url — host included, since a project's own domain often names it. */\nfunction urlTokens(url: string): Set {\n try {\n const parsed = new URL(url);\n return new Set(tokenize(`${parsed.hostname} ${parsed.pathname}`));\n } catch {\n return new Set();\n }\n}\n\n/**\n * A slug is a lossy copy of the headline, and being short it scores an\n * inflated precision, so it is worth slightly less than a real title match.\n */\nconst SLUG_WEIGHT = 0.95;\n\n/**\n * Breaks near-ties in favour of the engine's own ranking, and nothing more.\n * Anything larger and a correct match sitting at the bottom of the page loses\n * enough to drop under the confidence threshold.\n */\nconst RANK_NUDGE = 0.005;\n\nexport function pickHit(title: string, hits: SearchHit[], via: string): Candidate | null {\n const wanted = new Set(tokenize(title));\n let best: Candidate | null = null;\n\n for (let position = 0; position < hits.length; position++) {\n const hit = hits[position];\n if (isAggregator(hit.url)) continue;\n\n // The url is scored too: aggregator titles and rewritten headlines often\n // lose the original wording while the slug keeps it.\n const byTitle = overlap(wanted, new Set(tokenize(hit.title)));\n const slug = overlap(wanted, slugTokens(hit.url));\n const bySlug = { score: slug.score * SLUG_WEIGHT, recall: slug.recall };\n\n const match = bySlug.score > byTitle.score ? bySlug : byTitle;\n const candidate = {\n url: hit.url,\n score: match.score - position * RANK_NUDGE,\n recall: match.recall,\n corroborated: overlap(wanted, urlTokens(hit.url)).recall > 0,\n via,\n };\n\n if (better(candidate, best)) best = candidate;\n }\n return best;\n}\n\n/**\n * Search providers get a single retry: if one is flaky we would rather move on\n * to the next provider than spend the run's time budget here.\n */\nfunction search(url: string | URL, init: RequestInit | undefined, label: string) {\n return fetchWithRetry(url, init, { attempts: 2, baseDelayMs: 700, timeoutMs: 6000, label });\n}\n\n/**\n * Hacker News via the free Algolia endpoint. No key, and the hit carries the\n * original article url, so when the item was on HN this is the most reliable\n * source we have. Coverage is partial, hence the two fallbacks below.\n */\nasync function hackerNewsSearch(query: string): Promise {\n const url = new URL(\"https://hn.algolia.com/api/v1/search\");\n url.searchParams.set(\"query\", query);\n url.searchParams.set(\"tags\", \"story\");\n url.searchParams.set(\"hitsPerPage\", \"5\");\n // Without this the query also matches submission bodies and returns\n // loosely-related Show HN posts for almost any phrase.\n url.searchParams.set(\"restrictSearchableAttributes\", \"title,url\");\n\n const response = await search(url, undefined, \"Hacker News\");\n if (!response.ok) return [];\n\n const data = await response.json() as { hits?: { title: string | null; url: string | null }[] };\n return (data.hits ?? [])\n .filter((hit): hit is { title: string; url: string } => Boolean(hit.url && hit.title))\n .map((hit) => ({ url: hit.url, title: hit.title }));\n}\n\n/**\n * Serper returns Google's own result page as JSON. Signing up takes a minute\n * and needs no card, which since Google closed the Custom Search API to new\n * customers makes it the practical way to get Google coverage here. It is the\n * only provider in this file that takes a key.\n */\nasync function serperSearch(query: string, apiKey: string): Promise {\n const response = await search(\"https://google.serper.dev/search\", {\n method: \"POST\",\n headers: { \"X-API-KEY\": apiKey, \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ q: query, num: 10 }),\n }, \"Serper\");\n if (!response.ok) {\n console.warn(`Serper ${response.status}: ${await response.text()}`);\n return [];\n }\n const data = await response.json() as { organic?: { link: string; title: string }[] };\n return (data.organic ?? []).map((item) => ({ url: item.link, title: item.title }));\n}\n\n/**\n * Optional backup for when Serper is out of credits or down. Free tier is\n * 1000 searches a month with no card, and unlike a scraped engine it fails\n * with a status code instead of quietly serving a challenge page.\n */\nasync function tavilySearch(query: string, apiKey: string): Promise {\n const response = await search(\"https://api.tavily.com/search\", {\n method: \"POST\",\n headers: { \"Authorization\": `Bearer ${apiKey}`, \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ query, max_results: 10, search_depth: \"basic\" }),\n }, \"Tavily\");\n if (!response.ok) {\n console.warn(`Tavily ${response.status}: ${await response.text()}`);\n return [];\n }\n const data = await response.json() as { results?: { url: string; title: string }[] };\n return (data.results ?? []).map((item) => ({ url: item.url, title: item.title }));\n}\n\ninterface Provider {\n name: string;\n run: (query: string) => Promise;\n}\n\n/**\n * Tried in order, stopping at the first confident hit, so a later provider\n * only costs quota when the ones before it came up short. Hacker News leads\n * because it is free and returns the submitted url itself; Serper covers\n * everything HN never saw; Tavily is there for when Serper is out of credits.\n *\n * There used to be a keyless DuckDuckGo scraper at the end. It now answers\n * every request from a datacenter address with an anti-bot challenge, so it\n * found nothing while making the setup look more redundant than it was.\n */\nfunction providers(config: Config): Provider[] {\n const list: Provider[] = [{ name: \"hackernews\", run: hackerNewsSearch }];\n\n if (config.serperApiKey) {\n const apiKey = config.serperApiKey;\n list.push({ name: \"serper\", run: (query) => serperSearch(query, apiKey) });\n }\n if (config.tavilyApiKey) {\n const apiKey = config.tavilyApiKey;\n list.push({ name: \"tavily\", run: (query) => tavilySearch(query, apiKey) });\n }\n return list;\n}\n\n/**\n * Weekly headlines are often longer than the title the article was published\n * or submitted under, and Algolia requires every word to match, so the full\n * headline returns nothing at all. The leading significant words are the topic\n * — \"SQLite vs DuckDB on the Same $16 Box\" narrows to \"sqlite vs duckdb\",\n * which does find the article. Only used when the full query came back empty.\n */\nconst SHORT_QUERY_TOKENS = 3;\n\nexport function shortQuery(title: string): string | null {\n const tokens = tokenize(title);\n if (tokens.length <= SHORT_QUERY_TOKENS) return null;\n return tokens.slice(0, SHORT_QUERY_TOKENS).join(\" \");\n}\n\n/**\n * Everything in this newsletter is about Python, but a headline like \"Wheels,\n * Bottles, and Images\" never says so, and to a general engine those are three\n * ordinary nouns. Naming the topic is what points it at the packaging article.\n * Pointless when the headline already says Python, so it stays null there.\n */\nexport function topicalQuery(title: string): string | null {\n return /\\bpython\\b/i.test(title) ? null : `${title} python`;\n}\n\n/** A pinned link always wins — it is how you fix an item the search can't find. */\nfunction findOverride(item: WeeklyItem, overrides: Record): string | null {\n for (const [key, url] of Object.entries(overrides)) {\n if (item.title === key || item.title.includes(key) || item.name === key) return url;\n }\n return null;\n}\n\nasync function resolveBySearch(\n item: WeeklyItem,\n config: Config,\n deadline: number,\n): Promise {\n const pep = item.title.match(/\\bPEP[\\s-]?(\\d{3,4})\\b/i);\n if (pep) {\n const number = pep[1].padStart(4, \"0\");\n return {\n ...item,\n url: `https://peps.python.org/pep-${number}/`,\n confidence: \"high\",\n via: \"pep\",\n };\n }\n\n const shortened = shortQuery(item.title);\n const topical = topicalQuery(item.title);\n let best: Candidate | null = null;\n\n for (const provider of providers(config)) {\n // Checked between providers as well as before the item, so one slow\n // lookup can't push the run past Val Town's hard limit on its own.\n if (Date.now() > deadline) break;\n\n let hit: Candidate | null = null;\n try {\n const hits = await provider.run(item.title);\n hit = pickHit(item.title, hits, provider.name);\n\n // One retry per provider, picked to suit how the first attempt failed.\n // Nothing at all usually means the headline is longer than the title the\n // article was published under; results that don't match usually mean the\n // headline gave the engine no reason to think of Python.\n if (hit === null || !isConfident(hit)) {\n const retry = hits.length ? topical : shortened;\n if (retry) {\n const second = pickHit(item.title, await provider.run(retry), provider.name);\n if (second !== null && better(second, hit)) hit = second;\n }\n }\n } catch (error) {\n console.warn(`${provider.name} search failed for \"${item.title}\": ${error}`);\n }\n if (hit !== null && better(hit, best)) best = hit;\n // Only a match that covers the whole headline is worth stopping on; a\n // partial one leaves room for a later provider to do better.\n if (best !== null && isConfident(best)) break;\n }\n\n if (best === null) return { ...item, url: null, confidence: \"none\", via: null };\n\n const confidence: Confidence = isConfident(best)\n ? \"high\"\n : best.score >= LINK_THRESHOLD.minimum\n ? \"low\"\n : \"none\";\n return { ...item, url: confidence === \"none\" ? null : best.url, confidence, via: best.via };\n}\n\nfunction pickRepo(item: WeeklyItem, repos: Repo[]): Candidate | null {\n const name = item.name ?? item.title;\n let best: Candidate | null = null;\n\n for (const repo of repos) {\n const repoName = repo.fullName.split(\"/\")[1] ?? \"\";\n const match = overlap(new Set(tokenize(name)), new Set(tokenize(repoName)));\n const exact = repoName.toLowerCase() === name.toLowerCase() ? 1 : 0;\n const byDescription = item.description ? coverage(item.description, repo.description) * 0.6 : 0;\n // Stars break ties between same-named repos without ever outweighing a match.\n const popularity = Math.log10(repo.stars + 1) / 20;\n\n // Repos are judged on their own scale, above 1 for an exact name match,\n // so resolveProject compares these scores against its own thresholds.\n const score = exact + match.score * 0.5 + byDescription + popularity;\n if (best === null || score > best.score) {\n // The repo path is the name we matched on, so a hit here is corroborated\n // by construction — there is no title for a scraper to copy.\n best = {\n url: repo.htmlUrl,\n score,\n recall: exact ? 1 : match.recall,\n corroborated: true,\n via: \"github\",\n };\n }\n }\n return best;\n}\n\nasync function resolveProject(\n item: WeeklyItem,\n config: Config,\n preloaded: Map,\n deadline: number,\n): Promise {\n const name = item.name ?? item.title;\n const repos = preloaded.get(name) ?? await searchRepos(name, config.githubToken);\n const best = pickRepo(item, repos);\n\n if (best && best.score >= 1) return { ...item, url: best.url, confidence: \"high\", via: best.via };\n if (best && best.score >= 0.5) {\n return { ...item, url: best.url, confidence: \"low\", via: best.via };\n }\n\n // Not on GitHub under that name (or renamed) — fall back to a normal web search.\n return await resolveBySearch(item, config, deadline);\n}\n\nfunction fromCache(item: WeeklyItem, entry: CacheEntry): ResolvedItem {\n return { ...item, url: entry.url, confidence: entry.confidence, via: entry.via };\n}\n\n/**\n * Not a type predicate on purpose: an unsettled entry is still a CacheEntry,\n * and saying otherwise would narrow the caller's `entry` away to `undefined`.\n */\nfunction isSettled(entry: CacheEntry | undefined): boolean {\n return Boolean(entry && (entry.url || entry.attempts >= MAX_ATTEMPTS));\n}\n\n/**\n * How many items to resolve at once. Kept modest so a burst of parallel\n * lookups doesn't read as abuse to Algolia or Serper, both of which are being\n * used well inside their free tiers.\n */\nconst CONCURRENCY = 4;\n\ninterface Job {\n /** Position in the original item list, so results keep the issue's order. */\n index: number;\n run: () => Promise;\n}\n\nasync function drain(jobs: Job[], limit: number, into: ResolvedItem[]): Promise {\n let next = 0;\n const worker = async () => {\n while (next < jobs.length) {\n const job = jobs[next++];\n into[job.index] = await job.run();\n }\n };\n await Promise.all(Array.from({ length: Math.min(limit, jobs.length) }, worker));\n}\n\nexport async function resolveItems(\n items: WeeklyItem[],\n config: Config,\n cached: Record = {},\n): Promise {\n const cache: Record = { ...cached };\n const deadline = Date.now() + config.budgetMs;\n const resolved = new Array(items.length);\n let complete = true;\n\n const pending = items.filter((item) =>\n !findOverride(item, config.overrides) && !isSettled(cache[item.title])\n );\n const projectNames = pending\n .filter((item) => item.section === \"projects\")\n .map((item) => item.name ?? item.title);\n\n // Hacker News alone only covers the items that were submitted there, so a\n // keyless run quietly returns a much thinner issue. Say so rather than let it\n // look like the articles have no links to find.\n if (pending.length && !config.serperApiKey && !config.tavilyApiKey) {\n console.warn(\n `No SERPER_API_KEY or TAVILY_API_KEY: ` +\n `${pending.length} item(s) will be looked up on Hacker News only`,\n );\n }\n\n // One GraphQL round trip covers every project lookup; without a token we fall\n // back to throttled REST searches inside resolveProject.\n const preloaded = config.githubToken\n ? await searchReposBatch(projectNames, config.githubToken)\n : new Map();\n\n const jobs: Job[] = items.map((item, index) => ({\n index,\n run: async () => {\n const pinned = findOverride(item, config.overrides);\n if (pinned) return { ...item, url: pinned, confidence: \"high\" as const, via: \"override\" };\n\n const entry = cache[item.title];\n if (entry && isSettled(entry)) return fromCache(item, entry);\n\n if (Date.now() > deadline) {\n complete = false;\n return { ...item, url: null, confidence: \"none\" as const, via: null };\n }\n\n let result: ResolvedItem;\n try {\n result = item.section === \"projects\"\n ? await resolveProject(item, config, preloaded, deadline)\n : await resolveBySearch(item, config, deadline);\n } catch (error) {\n console.warn(`Could not resolve \"${item.title}\": ${error}`);\n result = { ...item, url: null, confidence: \"none\", via: null };\n }\n\n cache[item.title] = {\n url: result.url,\n confidence: result.confidence,\n via: result.via,\n attempts: (entry?.attempts ?? 0) + 1,\n };\n return result;\n },\n }));\n\n // Projects the GraphQL batch didn't cover need REST search, which is rate\n // limited to one call every few seconds. Those get their own single-file lane\n // so they can't sit in the main pool's slots and starve the article lookups.\n const needsRestSearch = (item: WeeklyItem) =>\n pending.includes(item) && item.section === \"projects\" &&\n !preloaded.has(item.name ?? item.title);\n\n const restLane = jobs.filter((job) => needsRestSearch(items[job.index]));\n const mainLane = jobs.filter((job) => !needsRestSearch(items[job.index]));\n\n await Promise.all([drain(mainLane, CONCURRENCY, resolved), drain(restLane, 1, resolved)]);\n\n return { items: resolved, cache, complete };\n}\n","import type { Config } from \"./config.ts\";\nimport { type Repo, searchRepos, searchReposBatch } from \"./github.ts\";\nimport { fetchWithRetry } from \"./http.ts\";\nimport type {\n CacheEntry,\n Confidence,\n ResolvedItem,\n ResolveResult,\n SearchHit,\n WeeklyItem,\n} from \"./types.ts\";\n\n/** Link aggregators and content scrapers that outrank the original on search engines. */\nconst AGGREGATORS = [\n \"news.ycombinator.com\",\n \"lobste.rs\",\n \"reddit.com\",\n \"daily.dev\",\n \"vuink.com\",\n \"nostr.ae\",\n \"x.com\",\n \"twitter.com\",\n \"facebook.com\",\n \"linkedin.com\",\n \"onlinedocs.net\",\n \"viralpique.com\",\n \"emergentmind.com\",\n \"aicompass.dev\",\n \"csdn.net\",\n \"cnblogs.com\",\n \"juejin.cn\",\n \"zhihu.com\",\n \"51cto.com\",\n];\n\n/**\n * Same idea, but matched on the first label of the hostname so every country\n * domain is covered at once — Pinterest alone answers on .com, .co.uk, .ca,\n * .de and a dozen more, and listing them individually is a losing game.\n */\nconst AGGREGATOR_BRANDS = [\"pinterest\", \"flipboard\", \"scoop\"];\n\n// deno-fmt-ignore\nconst STOPWORDS = new Set([\n \"a\", \"an\", \"and\", \"are\", \"as\", \"at\", \"be\", \"by\", \"for\", \"from\", \"how\", \"in\",\n \"is\", \"it\", \"of\", \"on\", \"or\", \"that\", \"the\", \"to\", \"with\", \"what\", \"your\",\n]);\n\n/** Give up looking for a link after this many runs so a bad item never blocks the send. */\nconst MAX_ATTEMPTS = 2;\n\n/**\n * Title-overlap thresholds. Below `minimum` we publish no link at all: a wrong\n * link is worse than a 🔍 that asks the reader to check for themselves.\n *\n * `recall` is a separate floor for calling a link confident. A short, tidy\n * candidate title scores a high F1 off a fraction of the headline —\n * \"DuckDB vs. SQLite\" against \"SQLite vs DuckDB on the Same $16 Box\" reaches\n * 0.67 while ignoring every word that identifies the article. Requiring most\n * of the headline to be accounted for is what separates the two.\n */\nexport const LINK_THRESHOLD = { confident: 0.6, minimum: 0.45, recall: 0.6 };\n\nexport interface Candidate {\n url: string;\n score: number;\n recall: number;\n via: string;\n}\n\nfunction isConfident(candidate: Candidate): boolean {\n return candidate.score >= LINK_THRESHOLD.confident &&\n candidate.recall >= LINK_THRESHOLD.recall;\n}\n\n/**\n * A candidate that accounts for the whole headline wins over one that doesn't,\n * even when the latter's raw overlap is a hair higher.\n */\nfunction better(candidate: Candidate, incumbent: Candidate | null): boolean {\n if (incumbent === null) return true;\n if (isConfident(candidate) !== isConfident(incumbent)) return isConfident(candidate);\n return candidate.score > incumbent.score;\n}\n\nfunction tokenize(text: string): string[] {\n return text\n .toLowerCase()\n .replace(/[^a-z0-9\\u4e00-\\u9fa5]+/g, \" \")\n .split(\" \")\n .filter((token) => token.length > 1 && !STOPWORDS.has(token));\n}\n\ninterface Match {\n /** F1: balances how much of the headline is covered against padding. */\n score: number;\n /** Share of the headline's own words the candidate accounts for. */\n recall: number;\n}\n\n/** Overlap of two token sets. Split out so a query is tokenized once per search. */\nfunction overlap(wanted: Set, have: Set): Match {\n if (!wanted.size || !have.size) return { score: 0, recall: 0 };\n\n let shared = 0;\n for (const token of wanted) if (have.has(token)) shared += 1;\n if (!shared) return { score: 0, recall: 0 };\n\n const recall = shared / wanted.size;\n const precision = shared / have.size;\n return { score: (2 * recall * precision) / (recall + precision), recall };\n}\n\n/**\n * Balanced overlap between two titles. Plain coverage is not enough: a long,\n * unrelated headline can contain most of a short query's words and still be\n * the wrong article, so the candidate's own extra words have to count against it.\n */\nexport function similarity(query: string, candidate: string): number {\n return overlap(new Set(tokenize(query)), new Set(tokenize(candidate))).score;\n}\n\ninterface ParsedUrl {\n host: string;\n slug: Set;\n tokens: Set;\n}\n\nfunction parseUrl(url: string): ParsedUrl | null {\n try {\n const parsed = new URL(url);\n const host = parsed.hostname.replace(/^www\\./, \"\");\n const path = parsed.pathname.replace(/\\.\\w+$/, \"\");\n const segment = path.split(\"/\").filter(Boolean).pop() ?? \"\";\n return { host, slug: new Set(tokenize(segment)), tokens: new Set(tokenize(`${host} ${path}`)) };\n } catch {\n return null;\n }\n}\n\nfunction isAggregator(host: string, url: string): boolean {\n if (AGGREGATORS.some((domain) => host === domain || host.endsWith(`.${domain}`))) return true;\n if (AGGREGATOR_BRANDS.includes(host.split(\".\")[0])) return true;\n // Articles live on blogs, not in a repo's pull/issue/commit view.\n return /(?:^|\\.)github\\.com$/.test(host) && /\\/(pull|issues|commit)\\//.test(url);\n}\n\n/**\n * A slug is a lossy copy of the headline, and being short it scores an\n * inflated precision, so it is worth slightly less than a real title match.\n */\nconst SLUG_WEIGHT = 0.95;\n\n/**\n * Breaks near-ties in favour of the engine's own ranking, and nothing more.\n * Anything larger and a correct match sitting at the bottom of the page loses\n * enough to drop under the confidence threshold.\n */\nconst RANK_NUDGE = 0.005;\n\nexport function pickHit(title: string, hits: SearchHit[], via: string): Candidate | null {\n const wanted = new Set(tokenize(title));\n let best: Candidate | null = null;\n\n for (let position = 0; position < hits.length; position++) {\n const hit = hits[position];\n const parsed = parseUrl(hit.url);\n if (!parsed || isAggregator(parsed.host, hit.url)) continue;\n // Scrapers copy the headline onto an opaque id. The original almost always\n // carries some of those words in the slug or the domain; a pin does not.\n if (!overlap(wanted, parsed.tokens).recall) continue;\n\n const byTitle = overlap(wanted, new Set(tokenize(hit.title)));\n const slug = overlap(wanted, parsed.slug);\n const bySlug = { score: slug.score * SLUG_WEIGHT, recall: slug.recall };\n const match = bySlug.score > byTitle.score ? bySlug : byTitle;\n\n const candidate = {\n url: hit.url,\n score: match.score - position * RANK_NUDGE,\n recall: match.recall,\n via,\n };\n if (better(candidate, best)) best = candidate;\n }\n return best;\n}\n\n/**\n * Search providers get a single retry: if one is flaky we would rather move on\n * to the next provider than spend the run's time budget here.\n */\nfunction search(url: string | URL, init: RequestInit | undefined, label: string) {\n return fetchWithRetry(url, init, { attempts: 2, baseDelayMs: 700, timeoutMs: 6000, label });\n}\n\n/**\n * Hacker News via the free Algolia endpoint. No key, and the hit carries the\n * original article url, so when the item was on HN this is the most reliable\n * source we have. Coverage is partial, hence the two fallbacks below.\n */\nasync function hackerNewsSearch(query: string): Promise {\n const url = new URL(\"https://hn.algolia.com/api/v1/search\");\n url.searchParams.set(\"query\", query);\n url.searchParams.set(\"tags\", \"story\");\n url.searchParams.set(\"hitsPerPage\", \"5\");\n // Without this the query also matches submission bodies and returns\n // loosely-related Show HN posts for almost any phrase.\n url.searchParams.set(\"restrictSearchableAttributes\", \"title,url\");\n\n const response = await search(url, undefined, \"Hacker News\");\n if (!response.ok) return [];\n\n const data = await response.json() as { hits?: { title: string | null; url: string | null }[] };\n return (data.hits ?? [])\n .filter((hit): hit is { title: string; url: string } => Boolean(hit.url && hit.title))\n .map((hit) => ({ url: hit.url, title: hit.title }));\n}\n\n/**\n * Serper returns Google's own result page as JSON. Signing up takes a minute\n * and needs no card, which since Google closed the Custom Search API to new\n * customers makes it the practical way to get Google coverage here.\n */\nasync function serperSearch(query: string, apiKey: string): Promise {\n const response = await search(\"https://google.serper.dev/search\", {\n method: \"POST\",\n headers: { \"X-API-KEY\": apiKey, \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ q: query, num: 10 }),\n }, \"Serper\");\n if (!response.ok) {\n console.warn(`Serper ${response.status}: ${await response.text()}`);\n return [];\n }\n const data = await response.json() as { organic?: { link: string; title: string }[] };\n return (data.organic ?? []).map((item) => ({ url: item.link, title: item.title }));\n}\n\n/**\n * Optional backup for when Serper is out of credits or down. Free tier is\n * 1000 searches a month with no card, and unlike a scraped engine it fails\n * with a status code instead of quietly serving a challenge page.\n */\nasync function tavilySearch(query: string, apiKey: string): Promise {\n const response = await search(\"https://api.tavily.com/search\", {\n method: \"POST\",\n headers: { \"Authorization\": `Bearer ${apiKey}`, \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ query, max_results: 10, search_depth: \"basic\" }),\n }, \"Tavily\");\n if (!response.ok) {\n console.warn(`Tavily ${response.status}: ${await response.text()}`);\n return [];\n }\n const data = await response.json() as { results?: { url: string; title: string }[] };\n return (data.results ?? []).map((item) => ({ url: item.url, title: item.title }));\n}\n\ninterface Provider {\n name: string;\n run: (query: string) => Promise;\n}\n\n/**\n * Hacker News is free and returns the submitted url itself. Serper covers\n * everything HN never saw. Tavily waits until that first wave fails, so it\n * does not spend quota on items Serper already settled.\n */\nfunction providers(config: Config): Provider[] {\n const list: Provider[] = [{ name: \"hackernews\", run: hackerNewsSearch }];\n\n if (config.serperApiKey) {\n const apiKey = config.serperApiKey;\n list.push({ name: \"serper\", run: (query) => serperSearch(query, apiKey) });\n }\n if (config.tavilyApiKey) {\n const apiKey = config.tavilyApiKey;\n list.push({ name: \"tavily\", run: (query) => tavilySearch(query, apiKey) });\n }\n return list;\n}\n\n/**\n * Weekly headlines are often longer than the title the article was published\n * or submitted under, and Algolia requires every word to match, so the full\n * headline returns nothing at all. The leading significant words are the topic\n * — \"SQLite vs DuckDB on the Same $16 Box\" narrows to \"sqlite vs duckdb\",\n * which does find the article. Only used when the full query came back empty.\n */\nconst SHORT_QUERY_TOKENS = 3;\n\nexport function shortQuery(title: string): string | null {\n const tokens = tokenize(title);\n if (tokens.length <= SHORT_QUERY_TOKENS) return null;\n return tokens.slice(0, SHORT_QUERY_TOKENS).join(\" \");\n}\n\n/**\n * Everything in this newsletter is about Python, but a headline like \"Wheels,\n * Bottles, and Images\" never says so, and to a general engine those are three\n * ordinary nouns. Naming the topic is what points it at the packaging article.\n * Pointless when the headline already says Python, so it stays null there.\n */\nexport function topicalQuery(title: string): string | null {\n return /\\bpython\\b/i.test(title) ? null : `${title} python`;\n}\n\n/** A pinned link always wins — it is how you fix an item the search can't find. */\nfunction findOverride(item: WeeklyItem, overrides: Record): string | null {\n for (const [key, url] of Object.entries(overrides)) {\n if (item.title === key || item.title.includes(key) || item.name === key) return url;\n }\n return null;\n}\n\nasync function lookup(\n provider: Provider,\n title: string,\n query: string,\n): Promise {\n try {\n return pickHit(title, await provider.run(query), provider.name);\n } catch (error) {\n console.warn(`${provider.name} search failed for \"${title}\": ${error}`);\n return null;\n }\n}\n\nfunction pickBest(hits: (Candidate | null)[]): Candidate | null {\n let best: Candidate | null = null;\n for (const hit of hits) {\n if (hit !== null && better(hit, best)) best = hit;\n }\n return best;\n}\n\nfunction toResolved(item: WeeklyItem, best: Candidate | null): ResolvedItem {\n if (best === null) return { ...item, url: null, confidence: \"none\", via: null };\n const confidence: Confidence = isConfident(best)\n ? \"high\"\n : best.score >= LINK_THRESHOLD.minimum\n ? \"low\"\n : \"none\";\n return { ...item, url: confidence === \"none\" ? null : best.url, confidence, via: best.via };\n}\n\nasync function resolveBySearch(\n item: WeeklyItem,\n searchProviders: Provider[],\n deadline: number,\n): Promise {\n const pep = item.title.match(/\\bPEP[\\s-]?(\\d{3,4})\\b/i);\n if (pep) {\n const number = pep[1].padStart(4, \"0\");\n return {\n ...item,\n url: `https://peps.python.org/pep-${number}/`,\n confidence: \"high\",\n via: \"pep\",\n };\n }\n\n const hn = searchProviders.find((provider) => provider.name === \"hackernews\");\n const serper = searchProviders.find((provider) => provider.name === \"serper\");\n const tavily = searchProviders.find((provider) => provider.name === \"tavily\");\n // Prefer Serper as the web engine; Tavily is only first-line when it's the only key.\n const web = serper ?? tavily;\n const webFallback = tavily && tavily !== web ? tavily : undefined;\n const webQuery = topicalQuery(item.title) ?? item.title;\n const shortened = shortQuery(item.title);\n\n const first: Promise[] = [];\n if (hn) {\n first.push(lookup(hn, item.title, item.title));\n if (shortened) first.push(lookup(hn, item.title, shortened));\n }\n if (web) first.push(lookup(web, item.title, webQuery));\n\n let best = first.length ? pickBest(await Promise.all(first)) : null;\n if ((best !== null && isConfident(best)) || Date.now() > deadline) return toResolved(item, best);\n\n const second: Promise[] = [];\n if (webFallback) second.push(lookup(webFallback, item.title, webQuery));\n if (web && webQuery !== item.title) second.push(lookup(web, item.title, item.title));\n if (second.length) {\n const extra = pickBest(await Promise.all(second));\n if (extra !== null && better(extra, best)) best = extra;\n }\n return toResolved(item, best);\n}\n\nfunction pickRepo(item: WeeklyItem, repos: Repo[]): Candidate | null {\n const name = item.name ?? item.title;\n let best: Candidate | null = null;\n\n for (const repo of repos) {\n const repoName = repo.fullName.split(\"/\")[1] ?? \"\";\n const match = overlap(new Set(tokenize(name)), new Set(tokenize(repoName)));\n const exact = repoName.toLowerCase() === name.toLowerCase() ? 1 : 0;\n const byDescription = item.description\n ? overlap(new Set(tokenize(item.description)), new Set(tokenize(repo.description))).recall *\n 0.6\n : 0;\n // Stars break ties between same-named repos without ever outweighing a match.\n const popularity = Math.log10(repo.stars + 1) / 20;\n\n // Repos are judged on their own scale, above 1 for an exact name match,\n // so resolveProject compares these scores against its own thresholds.\n const score = exact + match.score * 0.5 + byDescription + popularity;\n if (best === null || score > best.score) {\n best = { url: repo.htmlUrl, score, recall: exact ? 1 : match.recall, via: \"github\" };\n }\n }\n return best;\n}\n\nasync function resolveProject(\n item: WeeklyItem,\n config: Config,\n preloaded: Map,\n searchProviders: Provider[],\n deadline: number,\n): Promise {\n const name = item.name ?? item.title;\n const repos = preloaded.get(name) ?? await searchRepos(name, config.githubToken);\n const best = pickRepo(item, repos);\n\n if (best && best.score >= 1) return { ...item, url: best.url, confidence: \"high\", via: best.via };\n if (best && best.score >= 0.5) {\n return { ...item, url: best.url, confidence: \"low\", via: best.via };\n }\n\n return await resolveBySearch(item, searchProviders, deadline);\n}\n\nfunction fromCache(item: WeeklyItem, entry: CacheEntry): ResolvedItem {\n return { ...item, url: entry.url, confidence: entry.confidence, via: entry.via };\n}\n\n/**\n * Not a type predicate on purpose: an unsettled entry is still a CacheEntry,\n * and saying otherwise would narrow the caller's `entry` away to `undefined`.\n */\nfunction isSettled(entry: CacheEntry | undefined): boolean {\n return Boolean(entry && (entry.url || entry.attempts >= MAX_ATTEMPTS));\n}\n\nconst CONCURRENCY = 6;\n\ninterface Job {\n /** Position in the original item list, so results keep the issue's order. */\n index: number;\n run: () => Promise;\n}\n\nasync function drain(jobs: Job[], limit: number, into: ResolvedItem[]): Promise {\n let next = 0;\n const worker = async () => {\n while (next < jobs.length) {\n const job = jobs[next++];\n into[job.index] = await job.run();\n }\n };\n await Promise.all(Array.from({ length: Math.min(limit, jobs.length) }, worker));\n}\n\nexport async function resolveItems(\n items: WeeklyItem[],\n config: Config,\n cached: Record = {},\n): Promise {\n const cache: Record = { ...cached };\n const deadline = Date.now() + config.budgetMs;\n const resolved = new Array(items.length);\n let complete = true;\n\n const pending = items.filter((item) =>\n !findOverride(item, config.overrides) && !isSettled(cache[item.title])\n );\n const projectNames = pending\n .filter((item) => item.section === \"projects\")\n .map((item) => item.name ?? item.title);\n\n // Hacker News alone only covers the items that were submitted there, so a\n // keyless run quietly returns a much thinner issue. Say so rather than let it\n // look like the articles have no links to find.\n if (pending.length && !config.serperApiKey && !config.tavilyApiKey) {\n console.warn(\n `No SERPER_API_KEY or TAVILY_API_KEY: ` +\n `${pending.length} item(s) will be looked up on Hacker News only`,\n );\n }\n\n // One GraphQL round trip covers every project lookup; without a token we fall\n // back to throttled REST searches inside resolveProject.\n const preloaded = config.githubToken\n ? await searchReposBatch(projectNames, config.githubToken)\n : new Map();\n\n const searchProviders = providers(config);\n\n const jobs: Job[] = items.map((item, index) => ({\n index,\n run: async () => {\n const pinned = findOverride(item, config.overrides);\n if (pinned) return { ...item, url: pinned, confidence: \"high\" as const, via: \"override\" };\n\n const entry = cache[item.title];\n if (entry && isSettled(entry)) return fromCache(item, entry);\n\n if (Date.now() > deadline) {\n complete = false;\n return { ...item, url: null, confidence: \"none\" as const, via: null };\n }\n\n let result: ResolvedItem;\n try {\n result = item.section === \"projects\"\n ? await resolveProject(item, config, preloaded, searchProviders, deadline)\n : await resolveBySearch(item, searchProviders, deadline);\n } catch (error) {\n console.warn(`Could not resolve \"${item.title}\": ${error}`);\n result = { ...item, url: null, confidence: \"none\", via: null };\n }\n\n cache[item.title] = {\n url: result.url,\n confidence: result.confidence,\n via: result.via,\n attempts: (entry?.attempts ?? 0) + 1,\n };\n return result;\n },\n }));\n\n // Projects the GraphQL batch didn't cover need REST search, which is rate\n // limited to one call every few seconds. Those get their own single-file lane\n // so they can't sit in the main pool's slots and starve the article lookups.\n const needsRestSearch = (item: WeeklyItem) =>\n pending.includes(item) && item.section === \"projects\" &&\n !preloaded.has(item.name ?? item.title);\n\n const restLane = jobs.filter((job) => needsRestSearch(items[job.index]));\n const mainLane = jobs.filter((job) => !needsRestSearch(items[job.index]));\n\n await Promise.all([drain(mainLane, CONCURRENCY, resolved), drain(restLane, 1, resolved)]);\n\n return { items: resolved, cache, complete };\n}\n","createdAt",["D",1786637519417],"branchVersion","branchId","3454a3b0-304d-44df-8810-45864b58fef3","id","4fa04ca4-779a-4b32-9da5-2baf98313d81","python-weekly",["D",1785730366168],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","96c2793d-57c8-41d2-a49a-d1ee82f9dd24","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","93515af8-c7b7-459c-9bf2-3bb3df310a75","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":56,"_100":101,"_102":25},"branch",{"_13":85,"_32":86,"_44":43,"_87":45,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":46,"_94":95},"isOwned",69,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","yuxiaoy","handle","displayName","avatar","https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18yTm10cGhQUklwU0tqZHNiOHNnNGd2ZjJURFUiLCJyaWQiOiJ1c2VyXzJObXd1QWdCZmVtaUh0bGU5TkswOG1sM0xheiIsImluaXRpYWxzIjoiRlkifQ","tier","free","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_44":45,"_32":46,"_39":267,"_48":-5,"_49":25,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":-5,"_58":25,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":268,"_80":269,"_82":270,"_84":25},"tree",[167,178,179],"files",[167,168,169,170,171,172,173,174,175,176,177,178,179],"counts",{"_157":62,"_158":154,"_159":62,"_160":161,"_162":163},"contents",[125,126,127],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_44":148,"_32":149,"_30":150,"_131":-5,"_42":43,"_41":151,"_133":152,"_39":153,"_13":154,"_34":155,"_36":-5,"_24":25,"_138":-5,"_27":156},{"_44":140,"_32":141,"_30":142,"_131":-5,"_42":43,"_41":143,"_133":25,"_39":144,"_13":145,"_34":20,"_36":146,"_24":25,"_138":-5,"_27":147},{"_44":128,"_32":129,"_30":130,"_131":-5,"_42":43,"_41":132,"_133":25,"_39":134,"_13":135,"_34":136,"_36":137,"_24":25,"_138":-5,"_27":139},"3590fe2e-6c1c-4aac-944f-cf8c24b03c36","main.ts","94ebf106-8ef1-11f1-99a2-1607ee4eb77e","parentId",59,"latest",["D",1786637519189],6,"interval","import { loadConfig } from \"./src/config.ts\";\nimport { diagnose } from \"./src/errors.ts\";\nimport { fetchMarkdown, listIssues } from \"./src/github.ts\";\nimport { parseIssue } from \"./src/parser.ts\";\nimport { resolveItems } from \"./src/resolver.ts\";\nimport { decide } from \"./src/schedule.ts\";\nimport * as store from \"./src/store.ts\";\nimport {\n buildAlert,\n buildMessages,\n buildRecovery,\n sendMessages,\n type TelegramTarget,\n} from \"./src/telegram.ts\";\nimport type { CacheEntry } from \"./src/types.ts\";\n\ninterface Interval {\n lastRunAt: Date | undefined;\n}\n\ninterface ErrorState {\n signature: string;\n at: string;\n}\n\n/**\n * Bump whenever link scoring changes, so already-resolved issues get another\n * pass with the new rules instead of keeping links the old rules chose.\n */\nconst RESOLVER_VERSION = \"v4\";\n\nconst ERROR_KEY = \"python-weekly:last-error\";\n/** Re-send an alert about an unchanged problem at most this often. */\nconst REALERT_AFTER_MS = 12 * 60 * 60 * 1000;\n\n/** Alerts have to work even when loadConfig() is what failed. */\nfunction targetFromEnv(): TelegramTarget | null {\n const telegramBotToken = Deno.env.get(\"TELEGRAM_BOT_TOKEN\")?.trim();\n const telegramChatId = Deno.env.get(\"TELEGRAM_CHAT_ID\")?.trim();\n if (!telegramBotToken || !telegramChatId) return null;\n return { telegramBotToken, telegramChatId };\n}\n\nfunction alertsEnabled(): boolean {\n return Deno.env.get(\"ERROR_NOTIFY\") !== \"0\" && Deno.env.get(\"DRY_RUN\") !== \"1\";\n}\n\nasync function reportError(error: unknown): Promise {\n const diagnosis = diagnose(error);\n const previous = await store.get(ERROR_KEY);\n const repeated = previous !== null &&\n previous.signature === diagnosis.signature &&\n Date.now() - Date.parse(previous.at) < REALERT_AFTER_MS;\n\n await store.set(ERROR_KEY, { signature: diagnosis.signature, at: new Date().toISOString() });\n\n const target = targetFromEnv();\n if (repeated || !alertsEnabled() || !target) return;\n\n try {\n await sendMessages([buildAlert(diagnosis, error)], target);\n } catch (alertError) {\n // Nothing left to do but log — Telegram itself is how we'd report this.\n console.error(`Could not deliver the error alert: ${alertError}`);\n }\n}\n\nasync function clearError(): Promise {\n if (!await store.get(ERROR_KEY)) return;\n await store.set(ERROR_KEY, null);\n\n const target = targetFromEnv();\n if (!alertsEnabled() || !target) return;\n try {\n await sendMessages([buildRecovery()], target);\n } catch (alertError) {\n console.error(`Could not deliver the recovery notice: ${alertError}`);\n }\n}\n\nexport async function run(): Promise {\n const config = loadConfig();\n const dryRun = Deno.env.get(\"DRY_RUN\") === \"1\";\n\n const lastSentKey = `python-weekly:${config.lang}:last-sent`;\n const lastSent = await store.get(lastSentKey);\n\n // Decided before any request goes out, so runs inside the quiet window are free.\n const schedule = decide(lastSent, new Date(), config.quietDays);\n if (!schedule.check && !config.force && !dryRun) {\n return `Skipped: ${schedule.reason}.`;\n }\n\n const issues = await listIssues(config.docsDir, config.githubToken);\n if (!issues.length) return \"No weekly issues found in the repository.\";\n\n const latest = issues[0];\n\n if (lastSent === latest.name && !config.force) {\n return `No new issue (latest is still ${latest.name}).`;\n }\n\n // Link lookups cost search quota and wall-clock time, so they persist per\n // issue. The version in the key retires those results whenever the resolver\n // starts scoring differently, since old entries would otherwise be settled\n // and never looked at again. FORCE_RESEND is the manual version of that.\n const cacheKey = `python-weekly:links:${RESOLVER_VERSION}:${latest.name}`;\n const [markdown, cached] = await Promise.all([\n fetchMarkdown(latest.downloadUrl),\n config.force ? Promise.resolve(null) : store.get>(cacheKey),\n ]);\n\n const issue = parseIssue(markdown, latest.name, latest.htmlUrl);\n if (!issue.items.length) {\n // Parsing failed rather than the issue being empty; don't record it as sent.\n throw new Error(`Parsed 0 items from ${latest.name} — the markdown layout may have changed.`);\n }\n\n const { items, cache, complete } = await resolveItems(issue.items, config, cached ?? {});\n await store.set(cacheKey, cache);\n\n if (!complete) {\n const done = items.filter((item) => item.url).length;\n return `${latest.name}: resolved ${done}/${items.length} links so far, ` +\n \"continuing on the next run.\";\n }\n\n const messages = buildMessages(issue, items, config.lang);\n\n if (dryRun) {\n console.log(messages.join(\"\\n\\n--- message break ---\\n\\n\"));\n return `Dry run: ${items.length} items, ${messages.length} message(s).`;\n }\n\n await sendMessages(messages, config);\n await store.set(lastSentKey, latest.name);\n\n const missing = items.filter((item) => !item.url).length;\n return `Sent ${latest.name}: ${items.length} items in ${messages.length} message(s)` +\n (missing ? `, ${missing} without a link.` : \".\");\n}\n\nasync function main(): Promise {\n try {\n console.log(await run());\n await clearError();\n } catch (error) {\n console.error(error);\n await reportError(error);\n // Rethrow so the run is still marked as failed in the Val Town logs.\n throw error;\n }\n}\n\nexport default async function (_interval?: Interval): Promise {\n await main();\n}\n\nif (import.meta.main) {\n await main();\n}\n","label",[129],"c3cd2e29-8e49-4c38-aee3-46c55eb8e218","README.md","ec7985b6-8ef4-11f1-8f78-1607ee4eb77e",57,["D",1786257709917],5,"# Python 潮流周刊 → Telegram\n\n定时检查 [chinesehuazhou/python-weekly](https://github.com/chinesehuazhou/python-weekly)\n是否发布了新一期周刊，把其中的**文章**和**开源项目**标题补上真实链接，\n去掉订阅广告等无关内容，再通过 Telegram 机器人推送给你。\n\n原始周刊只有标题文本、没有链接，所以链接由脚本自动检索补全：项目走 GitHub API，文章先试 Hacker\nNews，没结果再交给 serper.dev（注册送 2500 次、不用绑卡）。想再加一层保险可以配 tavily.com\n兜底，但不是必须的。两个都不配也能跑，只是覆盖率会掉得很厉害。\n\n`samples/2026-08-01-weekly-resolved.md` 是第 161 期人工核对过的结果，可以对照参考。\n\n## 推送效果\n\n```\n📰 Python Weekly #161\nHow Claude Code Works, From Tokens to Agents\n2026-08-01 · 12 articles · 12 open-source projects\n\n🦄 Articles & Tutorials\n1. Planned Updates to the PyPI User Interface ← 超链接\n2. Binary search in Python with bisect\n...\n\n🐿 Projects & Resources\n1. vnpy\n Open-source Quantitative Trading Platform\n...\n```\n\n置信度低的链接后面会带 ⚠️，完全没找到的条目会附一个 🔍 搜索链接，方便你自己确认。\n\n## 工作流程\n\n1. 用 GitHub Contents API 列出 `docs/en`（或 `docs`）下的所有 `YYYY-MM-DD-weekly.md`，取最新一期。\n2. 与上次推送记录比对，没有更新就直接退出。\n3. 下载 Markdown，解析出 ①②③… 编号的条目，按 🦄 / 🐿 两个小标题分成文章与项目；\n 列表结束后的第一段普通文字之后的内容（订阅广告、往期合集链接等）全部丢弃。\n4. 逐条补链接，结果按期缓存，避免重试时重复消耗检索配额。\n5. 拼成 HTML 消息，超过长度自动分条发送，最后记录本期已推送。\n\n## 部署到 Val Town\n\n1. 在 [val.town](https://www.val.town) 新建一个 Val，按下面的结构创建文件：\n\n ```\n main.ts\n src/config.ts\n src/errors.ts\n src/github.ts\n src/http.ts\n src/parser.ts\n src/resolver.ts\n src/schedule.ts\n src/store.ts\n src/telegram.ts\n src/types.ts\n ```\n\n2. 在 `main.ts` 的编辑器右上角点 `+` → 选择 **CRON**，把调度设为 `0 */3 * * *`（每 3 小时，UTC）。\n 实际发起请求的次数远小于这个频率，原因见下面的「检查频率」。\n3. 在 Val 左侧栏的 **Environment Variables** 里填入下面的变量。\n4. 先把 `DRY_RUN` 设为 `1` 点一次 Run，在日志里确认消息内容正确，再删掉这个变量正式启用。\n\n## 环境变量\n\n一共只涉及三个平台的凭据：Telegram（必填）、GitHub（建议）、serper.dev（建议）。\n剩下的都是开关和调参，不用注册任何账号。\n\n| 变量 | 必填 | 说明 |\n| -------------------- | -------- | --------------------------------------------------------------------------------------------------------- |\n| `TELEGRAM_BOT_TOKEN` | 是 | 找 [@BotFather](https://t.me/BotFather) 发 `/newbot` 创建机器人后得到 |\n| `TELEGRAM_CHAT_ID` | 是 | 先给机器人发一条消息，再访问 `https://api.telegram.org/bot/getUpdates`，取 `message.chat.id` |\n| `GITHUB_TOKEN` | 强烈建议 | 任意 classic token（无需勾选权限）。有 token 时所有项目用一次 GraphQL 查完，否则要按 6.5 秒/次限速走 REST |\n| `SERPER_API_KEY` | 建议 | [serper.dev](https://serper.dev/) 注册即得，送 2500 次、不用绑卡。主力搜索渠道 |\n| `TAVILY_API_KEY` | 否 | [tavily.com](https://www.tavily.com/) 注册即得，每月 1000 次、不用绑卡。只在 Serper 没结果时才用 |\n| `LINK_OVERRIDES` | 否 | JSON 形式的人工链接，见下文「实在搜不到的条目」 |\n| `WEEKLY_LANG` | 否 | `en`（默认）或 `zh`，决定推送英文版还是中文版 |\n| `ERROR_NOTIFY` | 否 | 默认开启；设为 `0` 关闭出错时的 Telegram 告警 |\n| `DRY_RUN` | 否 | 设为 `1` 时只打印消息、不发送、不记录已推送 |\n| `FORCE_RESEND` | 否 | 设为 `1` 时忽略「已推送」记录**和链接缓存**，把最新一期从头查一遍再推 |\n| `RESOLVE_BUDGET_MS` | 否 | 单次运行用于检索链接的毫秒预算，默认 35000 |\n| `QUIET_DAYS` | 否 | 收到一期后静默多少天再开始查下一期，默认 6 |\n\n## 关于搜索渠道\n\n文章链接按下面的顺序依次尝试，一旦某个渠道给出足够可靠的结果就停下，\n所以排在后面的渠道只在前面没查到时才消耗配额。\n\n| 渠道 | 是否需要 Key | 特点 |\n| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------- |\n| PEP 直链 | 否 | 标题里出现 `PEP 842` 就直接拼 `peps.python.org`，零成本且必定正确 |\n| Hacker News（Algolia） | 否 | 免费无限制，返回的就是原文 URL，准确率最高；缺点是只覆盖上过 HN 的内容 |\n| serper.dev | **是**（免费送 2500 次，不绑卡） | 拿到的就是 Google 的结果，覆盖最全，主力就是它 |\n| tavily.com | 是（每月 1000 次，不绑卡）**可选** | 只在前面都没结果时才调用，用来兜 Serper 失效的情况 |\n\n两个 Key 都不配也能跑，但那样只剩 Hacker News，没上过 HN 的文章会直接查不到链接（日志里会写明\n`No SERPER_API_KEY or TAVILY_API_KEY: ...`）。如果你在意每期都尽量补全，`SERPER_API_KEY`\n基本是必配的；`TAVILY_API_KEY` 纯属保险，不想多注册一个账号就别配，配了也不会改变正常情况下的行为。\n\n用量其实很小：每期最多 12 次查询（项目那 12 条走 GitHub API，不消耗搜索额度），而且 Hacker News\n命中的条目根本不会走到 serper，一年撑死几百次，注册送的 2500 次够用好几年。\n\n### 为什么兜底选 Tavily，以及为什么没有免费无 Key 的兜底\n\n原先还有一路抓 `https://html.duckduckgo.com/html/` 的无 Key 兜底，已经删掉了。\n它现在对机器人一律返回 202 + 验证码页面而不是搜索结果，云服务器的 IP 必中，\n实测连查三个词全部被挡。它最糟的地方不是没用，而是**失败得很安静**—— 验证码页面也是\n2xx，看起来就像「这篇文章哪儿都搜不到」。\n\n替代品挑下来只有 Tavily 合适：免费额度每月 1000 次、每月 1 号重置、注册不用绑卡，而且是正经\nAPI，配额用尽会返回 429 而不是假装没搜到，脚本能识别并告警。其他几个都被排除了：**Brave** 官方 FAQ\n明说免费档也要绑卡（网上不少文章写「不用绑卡」，是错的）； **Exa** 只送一次性 $10\n额度，用完就断；**自建 SearXNG / UnSearch** 这类要自己维护服务，为一个每周跑一次的脚本不划算。\n\n顺带说一句，我也查过有没有「不用搜索引擎」的路子，结论是没有：\n中文版周刊同样只有标题、没有文章链接；作者的 Substack 里 20 期只有 1 期带外链，其余都被剥掉了；\nTelegram 频道只有图片；PyCoders Weekly 存档虽然有链接，但选题只跟周刊部分重合，\n这次出问题的两篇恰好都不在里面。所以搜索是绕不开的。\n\n### 拿 Serper 的 Key\n\n1. 打开 [serper.dev](https://serper.dev/)，用 Google 账号或邮箱注册（不需要信用卡）。\n2. 登录后在 Dashboard 的 **API Key** 一栏直接就能看到 key，复制出来。\n3. 在 Val Town 的 Environment Variables 里加 `SERPER_API_KEY`。\n4. 把 `DRY_RUN` 设成 `1` 手动 Run 一次，日志里看到链接补全就说明生效了。\n\n想同时配上兜底的话，[tavily.com](https://www.tavily.com/) 流程一样：邮箱注册、 Dashboard 复制\nKey、存成 `TAVILY_API_KEY`。它只在 Serper 没给出结果时才会被调用。\n\n### 为什么不用 Google / Brave\n\n如果你在 Google Cloud 控制台里翻遍了也找不到 Custom Search API，不是你的问题： Google 在 2025\n年就关闭了 Custom Search JSON API 的新用户注册，\n[官方文档](https://developers.google.com/custom-search/v1/overview)上写着 \"This API is not available\nfor new customers\"，并且整个服务在 2027-01-01 停服。配套的 Programmable Search Engine\n也在收紧，免费引擎被限制到 50 个域名、「搜索整个网络」选项正在取消。官方给的替代品 Vertex AI Search\n是面向企业的产品，起步门槛和计费方式都不适合这个脚本。\n\nBrave Search API 原来的 2000 次/月免费档在 2025 年底取消了，现在改成每月送 $5 额度（约 1000 次），\n且**注册必须绑卡**——这一点以官方 [FAQ](https://brave.com/search/api/) 为准（\"the card is only used\nto confirm your identity\"），网上不少对比文章写「Brave 免费档不用绑卡」是过时的。额度对我们够用，\n但为一个每周跑一次的脚本多绑一张卡不划算，所以兜底选了 Tavily。\n\n这两家的代码和环境变量都已经从仓库里删掉了。真要加回来的话，照着 `src/resolver.ts` 里的\n`serperSearch` 写一个同样形状的函数、在 `providers()` 里插一行就行，每家约十行。\n\n### 实在搜不到的条目：手动指定\n\n`LINK_OVERRIDES` 接受一个 JSON，键是条目标题（或标题里任意一段能唯一区分的文字），值是链接。\n命中的条目会跳过全部检索直接用你给的地址：\n\n```json\n{\n \"How Claude Code Works\": \"https://nem035.com/thoughts/how-claude-code-works\",\n \"Wheels, Bottles, and Images\": \"https://nesbitt.io/2026/07/30/wheels-bottles-images.html\",\n \"SQLite vs DuckDB\": \"https://tracewayapp.com/blog/sqlite-vs-duckdb\"\n}\n```\n\n改完环境变量再手动 Run 一次即可，不用改代码，也不用清缓存。\n\n想在部署前先看看某个标题能不能查到，本地跑：\n\n```bash\ndeno task live-check \"Wheels, Bottles, and Images\"\n```\n\n它会走完整的渠道链并打印命中的渠道、置信度和链接，方便判断是该配 Key 还是该加 override。\n\n## 检查频率：定时器每 3 小时响一次，但基本不发请求\n\n周刊每周六更新，真正需要盯着的只有周六前后那一天多。所以脚本没有靠 cron 表达式去\n猜发布时间，而是自己判断「现在该不该查」：\n\n- 记住上一期的**发布日期**（文件名里的 `2026-08-01`）。\n- 距离这个日期不满 `QUIET_DAYS`（默认 6 天）时，直接返回，**一个网络请求都不发**。\n- 到第 6 天（也就是周五）起进入「等待期」，此后每次定时器触发都会去 GitHub 看一眼。\n\n按每 3 小时一次算，一周 56 次触发里约有 48 次是毫秒级空转，只有周五到周六的 8 次左右会真的查\nGitHub。新一期发布后最迟 3 小时内送达。\n\n这样做的另一个好处是**自动适应变化**：某期拖到周日才发，静默期就从那个周日重新开始算，不用改\ncron；连着停更两周也只是维持每 3 小时看一眼的节奏。\n\n想更快可以把 cron 改成 `0 */2 * * *`，想更省就调大 `QUIET_DAYS`——两者互不影响。\n\n## 重试\n\n失败分两层处理。**一次运行内**，所有对外请求（GitHub、各搜索渠道、Telegram）都走 `src/http.ts` 的\n`fetchWithRetry`：遇到超时、网络异常、429、5xx 会退避重试，服务端给了 `Retry-After`\n就按它说的等。三类请求的重试次数和超时按重要性区分：\n\n| 请求 | 重试次数 | 单次超时 | 理由 |\n| ------------- | -------- | -------- | ------------------------------ |\n| Telegram 发送 | 4 | 15s | 内容都备好了，这一步失败最可惜 |\n| GitHub | 3 | 15s | 拿不到原文就没有后续 |\n| 搜索渠道 | 2 | 6s | 一个渠道卡住不如早点换下一个 |\n\n**跨运行**这层靠的是「查完才记录已推送」：只要没成功发出去，`last-sent` 就不变，\n下一次定时运行会重新走一遍。链接检索的中间结果存在 Blob 里，重来时不会重复查已经查到的条目；\n单个条目连续查不到会累计失败次数，超过上限就放弃它，不拖累整期。\n\n配合上面的静默窗口，失败后的重试节奏正好是每 3 小时一次，直到成功或你收到告警。\n\n### 链接缓存什么时候会失效\n\n缓存是「查到了就不再查」，这在正常情况下省时省配额，但也意味着**一个查错的链接会一直错下去**：\n条目已经有 URL（或连续失败达到上限）就算「定案」，后续运行直接跳过它。所以有两个失效机制：\n\n- 缓存键里带了 `src/../main.ts` 的 `RESOLVER_VERSION`。改动打分逻辑时把它加一，\n 旧结果自动作废，已经推过的那期也会用新规则重查一遍。\n- `FORCE_RESEND=1` 会同时忽略「已推送」记录和链接缓存，等于手动重来。\n\n换句话说，如果某期的链接不对，**光改代码不够**，还得让缓存失效，否则跑多少次都是同一个结果。\n\n## 速度\n\nVal Town 免费版单次运行上限是 1 分钟，这一分钟基本决定了脚本的所有设计取舍。\n时间都花在等网络上，所以优化的方向是**别让请求排队等**：\n\n- **条目并发检索**：24 个条目分 4 路同时查（`src/resolver.ts` 的 `CONCURRENCY`），\n 不是一条查完再查下一条。并发度压在 4 而不是拉满，是不想让一阵猛冲的请求在 Algolia 和 serper\n 那边看着像滥用——毕竟用的都是免费额度。\n- **项目批量查**：配了 `GITHUB_TOKEN` 时，12 个项目用一次 GraphQL 全部查完，而不是 12 次 REST\n 请求。\n- **REST 单独一条道**：没有 token 时项目只能走 REST，而 REST 搜索被限速到每 6.5 秒一次。\n 这类请求被放进独立的串行队列，不占并发池的位置，免得几个慢请求把文章检索堵死。\n- **渠道按顺序试、拿到就停**：某个渠道给出 ≥ 0.6 的结果就不再问下一家，既省时间也省配额。\n- **每个请求都有超时**：`fetchWithRetry` 给每次尝试挂了 `AbortSignal.timeout` （搜索 6 秒、其余 15\n 秒）。`fetch` 本身没有超时，少了这层，一个不响应的站点就能把整分钟耗光然后被平台强杀。\n- **检索预算**：默认 35 秒（`RESOLVE_BUDGET_MS`），前后要留给 GitHub 请求、 Telegram\n 发送和重试。预算不仅在每个条目开始前检查，渠道之间也检查，\n 这样单个条目再慢也不会独自把整个运行拖爆。\n\n预算用完时脚本会保存已查到的链接、本次不发送，由下一次定时运行接着查，全部查完才推送。配好\n`GITHUB_TOKEN` 和 `SERPER_API_KEY` 的情况下，一次运行通常十几秒就跑完了。\n万一没跑完，会等到下一次触发（最多 3 小时）才续上，介意的话可以把 cron 调密一点。\n\n## 本地开发\n\n```bash\ndeno task test # 跑解析与分条的单元测试\ndeno task dry-run # 走完整流程但只打印消息\ndeno task send # 真正发送一次\n```\n\n本地运行时状态写到 `./.state/`；部署在 Val Town 时自动改用 Blob 存储。\n\n## 链接检索策略\n\n- **文章**：按上面的渠道顺序检索，对每个结果计算标题相似度。判为「可靠」要同时满足两个条件：相似度 ≥\n 0.6，**且**候选覆盖了周刊标题里至少 60% 的关键词。只满足前者标 ⚠️，都不满足就不给链接只留\n 🔍——宁可让你自己点一下搜索，也不推一个错链接。 Hacker News 讨论页、Lobsters、Reddit\n 以及若干内容搬运站会从结果里排除，避免链到转载页而不是原文（注意：HN 渠道用的是 story 里的原文\n URL，不是讨论页）。\n- 相似度用的是两个标题分词后的 F1（同时看「查询词被覆盖了多少」和「候选标题里有多少是多余的」）。\n 只看覆盖率是不够的：一条很长的无关标题很容易凑齐短标题里的大部分词，比如 \"Show HN: I made a\n cheaper alternative to Claude Code or Codex CLI\" 对 \"How Claude Code Works, From Tokens to Agents\"\n 的覆盖率有 0.4，用 F1 算只有 0.29。\n- 但只看 F1 也不够，它会偏袒「标题短而干净」的候选：`DuckDB vs. SQLite` 对\n `SQLite vs DuckDB on the\n Same $16 Box` 能拿到 0.67，可它丢掉了 `same / 16 / box`\n 这几个真正区分文章的词，其实是另一篇。所以额外加了覆盖率门槛：这类候选最多算\n ⚠️，而且检索**不会**就此停下，会继续问下一个渠道。\n- **URL 也参与打分**：站点常常改写标题（Hacker News 上的投稿标题尤其如此），但 URL 里的 slug\n 往往保留了原标题。`/2026/07/30/wheels-bottles-images.html` 就能直接对上 \"Wheels, Bottles, and\n Images\"。slug 分数会乘 0.95，因为它比真正的标题匹配弱一些。\n- **URL 还要为标题作证**：光标题一模一样是不够的，URL 里必须也出现周刊标题中的某个词，\n 才算「可靠」。理由是**逐字照抄标题正是搬运站的本职**——第 162 期 ⑪ 就被搜索引擎返回的一个 Pinterest\n pin 骗到了：pin 的描述是从原文抄来的，标题匹配满分，而 URL 是 `/pin/424816177372869412/`，\n 纯数字、不含任何信息。原文的 URL 几乎总会在 slug 或域名里带上标题的词，转载页则不会。 Pinterest\n 这类站点同时也进了排除名单（按域名首段匹配，一次覆盖它所有国家域名）。\n- **每个渠道最多重试一次，且对症下药**：\n - **一条结果都没有** → 缩短到前三个关键词再查。Hacker News 用的 Algolia 要求所有词都命中，\n 周刊标题一旦比原文标题长就会返回空；上面那条缩短成 `sqlite vs duckdb` 后，原文\n `tracewayapp.com/blog/sqlite-vs-duckdb` 就是第一条。\n - **有结果但都不够可靠** → 在查询词后面补一个 `python` 再查。周刊里全是 Python 内容，\n 但标题本身未必说得出来——\"Wheels, Bottles, and Images\" 对搜索引擎就是三个普通名词，\n 补上主题词才可能指向那篇讲打包格式的文章。标题里已经有 Python 的条目不会重复添加。\n- **项目**：用仓库名搜 GitHub，仓库名完全一致得满分，再用「描述与周刊简介的重合度」和 star\n 数做加权，同名仓库很多时也能选对。搜不到才退回网页搜索。\n\n## 出错了怎么办\n\n任何一次运行失败都会往 Telegram 推一条告警，内容包含错误类型、原始错误信息和针对性的处理建议，\n不用去翻 Val Town 的日志。为了避免刷屏，同一类错误 12 小时内只提醒一次；\n问题消失后的第一次成功运行会推一条「已恢复」。不想要告警就把 `ERROR_NOTIFY` 设成 `0`。\n\n诊断规则写在 `src/errors.ts`，常见情况和处理方式：\n\n| 现象 | 原因 | 怎么解决 |\n| ----------------------------- | ------------------------ | -------------------------------------------------------------------------------- |\n| Telegram 401 | bot token 错了 | 去 @BotFather 用 `/mybots` 核对，必要时 `/revoke` 重新生成 |\n| Telegram 400 chat not found | chat_id 不对 | 先主动给机器人发条消息；群聊的 chat_id 是负数，别漏减号 |\n| Telegram can't parse entities | 标题里有未转义字符 | 检查 `telegram.ts` 的 `escapeHtml`；应急可先去掉 `parse_mode` |\n| GitHub 403 / rate limit | 匿名调用只有 60 次/小时 | 配 `GITHUB_TOKEN`，顺带让项目检索走 GraphQL 提速 |\n| Parsed 0 items | 周刊排版改了 | 改 `src/parser.ts` 的 `ITEM_PREFIX` / `SECTION_HEADER`，跑 `deno task test` 验证 |\n| Serper 401 / 403 | key 写错或 2500 次用完了 | 去 serper.dev 后台核对 key、看余额，充值或删掉这个变量 |\n| 超出运行时长 | 一分钟没跑完 | 调小 `RESOLVE_BUDGET_MS`，让它保存进度交给下一次运行 |\n\n下面几点是刻意设计的，出问题时不会造成更坏的后果：\n\n- 解析失败（0 条）时**不会**把这一期记成「已推送」，修好脚本后下一次运行会自动补发。\n- 单个条目检索失败只会让那一条没有链接，不会中断整期推送。\n- 告警发送本身失败时只写日志，不会因此再抛一次错。\n- 失败后「已推送」记录不变，静默窗口也就一直是打开的，下一次触发自动重试，不需要手动干预。\n\n## 已知限制\n\n- 周刊标题偶尔与原文标题不完全一致（比如加了副标题），这类条目会被标成 ⚠️ 或没有链接，需要人工确认。\n 第 161 期里的 \"How Claude Code Works, From Tokens to Agents\" 就属于这种情况。\n- 不配 `SERPER_API_KEY` 就只剩 Hacker News 一条渠道，覆盖率会掉得很厉害，且没有免费替代品可切。\n- 解析依赖周刊现有的 ①②③ 编号排版；如果作者改版，脚本会因为解析出 0 条而报错退出，\n 不会误把广告内容当成正文推送。\n",[141],"5cb8fa5d-0e89-42b9-b0c0-bfe8ab7e313b","src","fa72fb72-8ef2-11f1-ae04-1607ee4eb77e",4,true,["D",1785730968691],1,"directory",[149],"pulls","branches","forks","envVars",{"_164":145,"_166":62},"connections",{"_164":62,"_165":62},"count","unfilledCount","emptyCount",{"_44":148,"_32":149,"_30":150,"_131":-5,"_42":43,"_41":151,"_133":152,"_39":264,"_13":154,"_34":155,"_36":-5,"_24":25,"_138":-5,"_181":265,"_27":266},{"_44":256,"_32":257,"_30":258,"_131":150,"_42":43,"_41":259,"_133":25,"_39":260,"_13":192,"_34":35,"_36":261,"_24":25,"_138":-5,"_181":262,"_27":263},{"_44":248,"_32":249,"_30":250,"_131":150,"_42":43,"_41":251,"_133":25,"_39":252,"_13":145,"_34":35,"_36":253,"_24":25,"_138":-5,"_181":254,"_27":255},{"_44":240,"_32":241,"_30":242,"_131":150,"_42":43,"_41":243,"_133":25,"_39":244,"_13":151,"_34":35,"_36":245,"_24":25,"_138":-5,"_181":246,"_27":247},{"_44":232,"_32":233,"_30":234,"_131":150,"_42":43,"_41":235,"_133":152,"_39":236,"_13":192,"_34":35,"_36":237,"_24":25,"_138":-5,"_181":238,"_27":239},{"_44":224,"_32":225,"_30":226,"_131":150,"_42":43,"_41":227,"_133":25,"_39":228,"_13":192,"_34":35,"_36":229,"_24":25,"_138":-5,"_181":230,"_27":231},{"_44":220,"_32":33,"_30":31,"_131":150,"_42":43,"_41":14,"_133":152,"_39":221,"_13":145,"_34":35,"_36":38,"_24":25,"_138":-5,"_181":222,"_27":223},{"_44":212,"_32":213,"_30":214,"_131":150,"_42":43,"_41":215,"_133":152,"_39":216,"_13":192,"_34":35,"_36":217,"_24":25,"_138":-5,"_181":218,"_27":219},{"_44":204,"_32":205,"_30":206,"_131":150,"_42":43,"_41":207,"_133":152,"_39":208,"_13":192,"_34":35,"_36":209,"_24":25,"_138":-5,"_181":210,"_27":211},{"_44":196,"_32":197,"_30":198,"_131":150,"_42":43,"_41":199,"_133":25,"_39":200,"_13":192,"_34":35,"_36":201,"_24":25,"_138":-5,"_181":202,"_27":203},{"_44":187,"_32":188,"_30":189,"_131":150,"_42":43,"_41":190,"_133":25,"_39":191,"_13":192,"_34":35,"_36":193,"_24":25,"_138":-5,"_181":194,"_27":195},{"_44":140,"_32":141,"_30":142,"_131":-5,"_42":43,"_41":143,"_133":25,"_39":184,"_13":145,"_34":20,"_36":146,"_24":25,"_138":-5,"_181":185,"_27":186},{"_44":128,"_32":129,"_30":130,"_131":-5,"_42":43,"_41":132,"_133":25,"_39":180,"_13":135,"_34":136,"_36":137,"_24":25,"_138":-5,"_181":182,"_27":183},["D",1786637519189],"children",[],[129],["D",1786257709917],[],[141],"cec7b847-91fb-42e7-a6b1-dfeb1fead441","types.ts","8953dc94-8ef3-11f1-8af9-1607ee4eb77e",55,["D",1786256653694],3,"export type Section = \"articles\" | \"projects\";\n\nexport interface WeeklyItem {\n section: Section;\n index: number;\n /** Full text as it appears in the markdown, e.g. \"vnpy: Open-source Quantitative Trading Platform\". */\n title: string;\n /** For projects, the part before the colon (\"vnpy\"); undefined for articles. */\n name?: string;\n /** For projects, the part after the colon. */\n description?: string;\n}\n\nexport interface WeeklyIssue {\n /** Source file name, e.g. \"2026-08-01-weekly.md\". */\n file: string;\n /** ISO date parsed from the file name. */\n date: string;\n /** Issue number parsed from the H1, e.g. 161. */\n number: number | null;\n /** H1 text with the \"Python Trending Weekly #161:\" prefix stripped. */\n headline: string;\n sourceUrl: string;\n items: WeeklyItem[];\n}\n\nexport type Confidence = \"high\" | \"low\" | \"none\";\n\nexport interface ResolvedItem extends WeeklyItem {\n url: string | null;\n confidence: Confidence;\n /** Which resolver produced the url: \"github\" | \"pep\" | \"hackernews\" | \"serper\" | \"tavily\" | \"override\". */\n via: string | null;\n}\n\nexport interface SearchHit {\n url: string;\n title: string;\n}\n\n/** Persisted per issue so link lookups survive across cron runs. */\nexport interface CacheEntry {\n url: string | null;\n confidence: Confidence;\n via: string | null;\n attempts: number;\n}\n\nexport interface ResolveResult {\n items: ResolvedItem[];\n cache: Record;\n /** False when the time budget ran out before every item was looked up. */\n complete: boolean;\n}\n",[],[149,188],"6e546fa0-7f9d-4228-a657-f7920039385a","telegram.ts","84a71c4c-8ef3-11f1-a0c7-1607ee4eb77e",54,["D",1786256653502],"import type { Config, Lang } from \"./config.ts\";\nimport type { Diagnosis } from \"./errors.ts\";\nimport { fetchWithRetry } from \"./http.ts\";\nimport type { ResolvedItem, WeeklyIssue } from \"./types.ts\";\n\n/** Alerts must be sendable even when loadConfig() itself failed. */\nexport type TelegramTarget = Pick;\n\n/** Telegram's hard limit is 4096 characters; leave room for the part suffix. */\nconst MAX_MESSAGE = 3800;\n\nconst TEXT: Record> = {\n en: {\n articles: \"🦄 Articles & Tutorials\",\n projects: \"🐿 Projects & Resources\",\n counts: \"%a articles · %p open-source projects\",\n source: \"Source\",\n part: \"part %n/%t\",\n },\n zh: {\n articles: \"🦄 文章 & 教程\",\n projects: \"🐿 项目 & 资源\",\n counts: \"%a 篇文章 · %p 个开源项目\",\n source: \"原文\",\n part: \"第 %n/%t 条\",\n },\n};\n\nfunction escapeHtml(text: string): string {\n return text.replace(/&/g, \"&\").replace(//g, \">\");\n}\n\nfunction link(url: string, label: string): string {\n // A raw quote in the url would close the href attribute early.\n const href = escapeHtml(url.replace(/\"/g, \"%22\"));\n return `${escapeHtml(label)}`;\n}\n\nfunction searchUrl(query: string): string {\n return `https://www.google.com/search?q=${encodeURIComponent(query)}`;\n}\n\nfunction renderItem(item: ResolvedItem): string {\n const label = item.section === \"projects\" ? (item.name ?? item.title) : item.title;\n const head = item.url\n ? link(item.url, label)\n : `${escapeHtml(label)} ${link(searchUrl(label), \"🔍\")}`;\n const flag = item.confidence === \"low\" ? \" ⚠️\" : \"\";\n const tail = item.section === \"projects\" && item.description\n ? `\\n ${escapeHtml(item.description)}`\n : \"\";\n return `${item.index}. ${head}${flag}${tail}`;\n}\n\n/** One string per logical block, so chunking never splits an item in half. */\nfunction renderBlocks(issue: WeeklyIssue, items: ResolvedItem[], lang: Lang): string[] {\n const t = TEXT[lang];\n const articles = items.filter((item) => item.section === \"articles\");\n const projects = items.filter((item) => item.section === \"projects\");\n\n const title = issue.number ? `Python Weekly #${issue.number}` : `Python Weekly ${issue.date}`;\n const counts = t.counts\n .replace(\"%a\", String(articles.length))\n .replace(\"%p\", String(projects.length));\n\n const section = (header: string, entries: ResolvedItem[]) =>\n [`${escapeHtml(header)}`, ...entries.map(renderItem)].join(\"\\n\");\n\n const blocks = [\n `📰 ${escapeHtml(title)}\\n${escapeHtml(issue.headline)}\\n${issue.date} · ${counts}`,\n ];\n if (articles.length) blocks.push(section(t.articles, articles));\n if (projects.length) blocks.push(section(t.projects, projects));\n blocks.push(link(issue.sourceUrl, t.source));\n return blocks;\n}\n\n/** Break a block that is too long on its own back into whole lines. */\nfunction splitBlock(block: string): string[] {\n if (block.length <= MAX_MESSAGE) return [block];\n\n const parts: string[] = [];\n let current = \"\";\n for (const line of block.split(\"\\n\")) {\n const candidate = current ? `${current}\\n${line}` : line;\n if (candidate.length > MAX_MESSAGE && current) {\n parts.push(current);\n current = line;\n } else {\n current = candidate;\n }\n }\n if (current) parts.push(current);\n return parts;\n}\n\nexport function buildMessages(issue: WeeklyIssue, items: ResolvedItem[], lang: Lang): string[] {\n const messages: string[] = [];\n let current = \"\";\n\n for (const block of renderBlocks(issue, items, lang).flatMap(splitBlock)) {\n const candidate = current ? `${current}\\n\\n${block}` : block;\n if (candidate.length > MAX_MESSAGE && current) {\n messages.push(current);\n current = block;\n } else {\n current = candidate;\n }\n }\n if (current) messages.push(current);\n\n if (messages.length === 1) return messages;\n return messages.map((message, index) =>\n `${message}\\n\\n${\n TEXT[lang].part.replace(\"%n\", String(index + 1)).replace(\"%t\", String(messages.length))\n }`\n );\n}\n\nexport function buildAlert(diagnosis: Diagnosis, error: unknown): string {\n const message = error instanceof Error ? error.message : String(error);\n const hints = diagnosis.hints.map((hint) => `• ${escapeHtml(hint)}`).join(\"\\n\");\n\n return [\n `⚠️ Python 周刊推送失败`,\n escapeHtml(diagnosis.title),\n `

${escapeHtml(message.slice(0, 600))}

`,\n `处理建议\\n${hints}`,\n ].join(\"\\n\\n\");\n}\n\nexport function buildRecovery(): string {\n return \"✅ Python 周刊推送已恢复\\n上一次失败的问题已经不再出现。\";\n}\n\nexport async function sendMessages(messages: string[], target: TelegramTarget): Promise {\n for (const [position, text] of messages.entries()) {\n // Delivery is the one step we really don't want to lose, so it gets the\n // most retries; Telegram sends Retry-After on 429 and fetchWithRetry obeys it.\n const response = await fetchWithRetry(\n `https://api.telegram.org/bot${target.telegramBotToken}/sendMessage`,\n {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n chat_id: target.telegramChatId,\n text,\n parse_mode: \"HTML\",\n disable_web_page_preview: true,\n }),\n },\n { attempts: 4, label: \"Telegram sendMessage\" },\n );\n if (!response.ok) {\n throw new Error(`Telegram sendMessage -> ${response.status} ${await response.text()}`);\n }\n // Space out consecutive messages, but don't linger after the last one.\n if (position < messages.length - 1) {\n await new Promise((resolve) => setTimeout(resolve, 500));\n }\n }\n}\n",[],[149,197],"40ec9625-e8f5-4c5f-9fc6-c4fdb463ed21","store.ts","7fe5c230-8ef3-11f1-a01c-1607ee4eb77e",53,["D",1786256653415],"/**\n * Small key/value wrapper: Val Town blob storage when deployed, a local file\n * when running the script from a terminal (Val Town has no filesystem).\n */\n\ntype Blob = {\n getJSON(key: string): Promise;\n setJSON(key: string, value: unknown): Promise;\n};\n\nlet blob: Blob | null | undefined;\n\nasync function valTownBlob(): Promise {\n if (blob !== undefined) return blob;\n try {\n const module = await import(\"https://esm.town/v/std/blob\");\n blob = module.blob as Blob;\n } catch {\n blob = null;\n }\n return blob;\n}\n\nfunction localPath(key: string): string {\n return `./.state/${key.replace(/[^a-zA-Z0-9._-]/g, \"_\")}.json`;\n}\n\nexport async function get(key: string): Promise {\n const store = await valTownBlob();\n if (store) {\n try {\n return (await store.getJSON(key) as T) ?? null;\n } catch {\n return null;\n }\n }\n try {\n return JSON.parse(await Deno.readTextFile(localPath(key))) as T;\n } catch {\n return null;\n }\n}\n\nexport async function set(key: string, value: unknown): Promise {\n const store = await valTownBlob();\n if (store) {\n await store.setJSON(key, value);\n return;\n }\n await Deno.mkdir(\"./.state\", { recursive: true });\n await Deno.writeTextFile(localPath(key), JSON.stringify(value, null, 2));\n}\n",[],[149,205],"62deaddb-decf-49e8-a389-d10ad44062a2","schedule.ts","7b5f7738-8ef3-11f1-a0c7-1607ee4eb77e",52,["D",1786256653621],"/**\n * The weekly ships on Saturdays. Rather than polling around the clock, the job\n * stays quiet for the first few days after an issue and only starts looking as\n * the next one comes due — the cron can then fire often without costing\n * anything, because off-window runs return before touching the network.\n */\nexport const DEFAULT_QUIET_DAYS = 6;\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\nexport interface ScheduleDecision {\n check: boolean;\n reason: string;\n}\n\n/** Issue files are named like `2026-08-01-weekly.md`. */\nexport function issueDate(fileName: string): number | null {\n const match = fileName.match(/\\d{4}-\\d{2}-\\d{2}/);\n if (!match) return null;\n const time = Date.parse(`${match[0]}T00:00:00Z`);\n return Number.isNaN(time) ? null : time;\n}\n\nexport function decide(\n lastSent: string | null,\n now: Date = new Date(),\n quietDays: number = DEFAULT_QUIET_DAYS,\n): ScheduleDecision {\n if (!lastSent) return { check: true, reason: \"nothing sent yet\" };\n\n const published = issueDate(lastSent);\n // An unexpected file name is not a reason to stop working.\n if (published === null) return { check: true, reason: `cannot read a date from ${lastSent}` };\n\n const age = (now.getTime() - published) / DAY_MS;\n if (age >= quietDays) {\n return { check: true, reason: `${lastSent} is ${age.toFixed(1)} days old, a new issue is due` };\n }\n\n const waitDays = quietDays - age;\n const resumesAt = new Date(published + quietDays * DAY_MS).toISOString().slice(0, 10);\n return {\n check: false,\n reason: `${lastSent} is only ${age.toFixed(1)} days old; ` +\n `checks resume on ${resumesAt} (in ${waitDays.toFixed(1)} days)`,\n };\n}\n",[],[149,213],"ed3873fd-2a15-4bfd-9161-ee90a71ce42c",["D",1786637519417],[],[149,33],"9fa7d97e-34f4-4eb4-aa39-6bf6a749b6a4","parser.ts","6e45bf30-8ef3-11f1-81d2-1607ee4eb77e",49,["D",1786256652998],"import type { Section, WeeklyIssue, WeeklyItem } from \"./types.ts\";\n\n/** ①-⑳, ㉑-㉟, ㊱-㊿ — the circled numbers the weekly uses to number its items. */\nconst ITEM_PREFIX = /^([\\u2460-\\u2473\\u3251-\\u325F\\u32B1-\\u32BF])\\s*/;\nconst SECTION_HEADER = /^\\*\\*\\[/;\nconst H1 = /^#\\s+(.*)$/;\nconst ISSUE_NUMBER = /#\\s*(\\d+)/;\n\nfunction circledToNumber(ch: string): number {\n const code = ch.codePointAt(0)!;\n if (code >= 0x2460 && code <= 0x2473) return code - 0x2460 + 1;\n if (code >= 0x3251 && code <= 0x325f) return code - 0x3251 + 21;\n if (code >= 0x32b1 && code <= 0x32bf) return code - 0x32b1 + 36;\n return 0;\n}\n\n/** Markdown escapes leak into titles (`pytorch\\_geometric`); undo them. */\nfunction unescapeMarkdown(text: string): string {\n return text.replace(/\\\\([\\\\`*_{}[\\]()#+\\-.!~])/g, \"$1\");\n}\n\nfunction sectionOf(headerLine: string, seen: number): Section | null {\n if (/🦄|Articles|文章/i.test(headerLine)) return \"articles\";\n if (/🐿|Projects|项目/i.test(headerLine)) return \"projects\";\n return seen === 0 ? \"articles\" : seen === 1 ? \"projects\" : null;\n}\n\n/** Projects are written as \"name: description\"; articles have no such split. */\nfunction splitProject(title: string): { name: string; description?: string } {\n const match = title.match(/^([^:：]+)[:：]\\s*(.+)$/);\n if (!match) return { name: title };\n return { name: match[1].trim(), description: match[2].trim() };\n}\n\nexport function parseIssue(markdown: string, file: string, sourceUrl: string): WeeklyIssue {\n const lines = markdown.split(/\\r?\\n/);\n\n let headline = \"\";\n let number: number | null = null;\n const items: WeeklyItem[] = [];\n\n let section: Section | null = null;\n let headersSeen = 0;\n\n for (const raw of lines) {\n const line = raw.trim();\n if (!line) continue;\n\n const h1 = line.match(H1);\n if (h1 && !headline) {\n const text = unescapeMarkdown(h1[1]);\n number = Number(text.match(ISSUE_NUMBER)?.[1] ?? NaN) || null;\n // Drop the \"Python Trending Weekly #161:\" / \"Python 潮流周刊#161：\" prefix.\n headline = text.replace(/^.*?#\\s*\\d+\\s*[:：]?\\s*/, \"\").trim() || text;\n continue;\n }\n\n if (SECTION_HEADER.test(line)) {\n section = sectionOf(line, headersSeen);\n headersSeen += 1;\n continue;\n }\n\n if (!section) continue;\n\n const prefix = line.match(ITEM_PREFIX);\n if (!prefix) {\n // First non-item paragraph after a list ends the section. Everything that\n // follows the projects list is subscription/marketing copy we don't want.\n section = null;\n continue;\n }\n\n const title = unescapeMarkdown(line.slice(prefix[0].length).trim());\n if (!title) continue;\n\n const item: WeeklyItem = {\n section,\n index: circledToNumber(prefix[1]) || items.filter((i) => i.section === section).length + 1,\n title,\n };\n if (section === \"projects\") Object.assign(item, splitProject(title));\n items.push(item);\n }\n\n return {\n file,\n date: file.match(/^(\\d{4}-\\d{2}-\\d{2})/)?.[1] ?? \"\",\n number,\n headline,\n sourceUrl,\n items,\n };\n}\n",[],[149,225],"53c2fc00-75db-4dcb-9d3a-60a310e4f947","http.ts","6910fbce-8ef3-11f1-be6f-1607ee4eb77e",50,["D",1786256652947],"/** Statuses worth trying again; anything else is a real answer from the server. */\nconst RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);\n\n/** Never sleep longer than this — a Val Town run is capped at one minute. */\nconst MAX_WAIT_MS = 15_000;\n\n/**\n * fetch has no timeout of its own, so one unresponsive host could otherwise\n * hold a slot until Val Town kills the whole run.\n */\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\nexport interface RetryOptions {\n /** Total tries, including the first one. */\n attempts?: number;\n baseDelayMs?: number;\n /** Per-attempt deadline, not a budget for all attempts together. */\n timeoutMs?: number;\n label?: string;\n}\n\nfunction sleep(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/** Exponential backoff with jitter so parallel jobs don't retry in lockstep. */\nfunction backoff(base: number, attempt: number): number {\n const exponential = Math.min(base * 2 ** (attempt - 1), MAX_WAIT_MS);\n return exponential + Math.random() * 300;\n}\n\nfunction retryAfter(response: Response): number | null {\n const header = response.headers.get(\"Retry-After\");\n if (!header) return null;\n const seconds = Number(header);\n if (!Number.isFinite(seconds) || seconds <= 0) return null;\n return seconds * 1000;\n}\n\n/**\n * fetch that retries transient failures. Bodies used here are strings or\n * URLSearchParams, so replaying a request is safe.\n */\nexport async function fetchWithRetry(\n input: string | URL,\n init?: RequestInit,\n options: RetryOptions = {},\n): Promise {\n const attempts = options.attempts ?? 3;\n const base = options.baseDelayMs ?? 1000;\n const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const label = options.label ?? String(input);\n\n for (let attempt = 1; attempt <= attempts; attempt++) {\n try {\n // A fresh signal per attempt: it starts counting the moment it is made.\n const response = await fetch(input, { ...init, signal: AbortSignal.timeout(timeout) });\n if (!RETRYABLE.has(response.status) || attempt === attempts) return response;\n\n const after = retryAfter(response);\n if (after !== null && after > MAX_WAIT_MS) {\n // Waiting it out would eat the run's budget; the next cron run is the\n // better place to try again.\n console.warn(`${label} -> ${response.status}, asked to wait ${Math.round(after / 1000)}s`);\n return response;\n }\n\n const wait = after ?? backoff(base, attempt);\n console.warn(`${label} -> ${response.status}, retrying in ${Math.round(wait)}ms`);\n await sleep(wait);\n } catch (error) {\n if (attempt === attempts) throw error;\n const wait = backoff(base, attempt);\n console.warn(`${label} failed (${error}), retrying in ${Math.round(wait)}ms`);\n await sleep(wait);\n }\n }\n\n throw new Error(`${label}: exhausted ${attempts} attempts`);\n}\n",[],[149,233],"bbe21d2f-8bf6-48a3-bbc8-f127b2e96dbc","github.ts","153fefd2-8ef3-11f1-ae04-1607ee4eb77e",47,["D",1786256652851],"import { REPO } from \"./config.ts\";\nimport { fetchWithRetry } from \"./http.ts\";\n\nconst API = \"https://api.github.com\";\nconst FILE_NAME = /^(\\d{4}-\\d{2}-\\d{2})-weekly\\.md$/;\n\n/** Search is rate limited to 10 req/min anonymously and 30 req/min with a token. */\nconst SEARCH_GAP_MS = { anonymous: 6500, authenticated: 2200 };\nlet lastSearchAt = 0;\n/** Callers queue up here so the gap holds even if two of them ask at once. */\nlet searchQueue: Promise = Promise.resolve();\n\nfunction takeSearchSlot(gap: number): Promise {\n const turn = searchQueue.then(async () => {\n const wait = lastSearchAt + gap - Date.now();\n if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));\n lastSearchAt = Date.now();\n });\n searchQueue = turn.catch(() => {});\n return turn;\n}\n\nexport interface IssueFile {\n name: string;\n date: string;\n downloadUrl: string;\n htmlUrl: string;\n}\n\nexport interface Repo {\n fullName: string;\n htmlUrl: string;\n description: string;\n stars: number;\n}\n\nfunction headers(token: string | null): HeadersInit {\n const base: Record = {\n Accept: \"application/vnd.github+json\",\n \"User-Agent\": \"python-weekly-telegram-bot\",\n };\n if (token) base.Authorization = `Bearer ${token}`;\n return base;\n}\n\nasync function api(path: string, token: string | null): Promise {\n const response = await fetchWithRetry(\n `${API}${path}`,\n { headers: headers(token) },\n { label: `GitHub ${path}` },\n );\n if (!response.ok) {\n throw new Error(`GitHub ${path} -> ${response.status} ${await response.text()}`);\n }\n return await response.json() as T;\n}\n\n/** All weekly issues in `dir`, newest first. */\nexport async function listIssues(dir: string, token: string | null): Promise {\n type Entry = { name: string; type: string; download_url: string; html_url: string };\n const entries = await api(`/repos/${REPO}/contents/${dir}`, token);\n\n return entries\n .filter((entry) => entry.type === \"file\" && FILE_NAME.test(entry.name))\n .map((entry) => ({\n name: entry.name,\n date: entry.name.match(FILE_NAME)![1],\n downloadUrl: entry.download_url,\n htmlUrl: entry.html_url,\n }))\n .sort((a, b) => b.date.localeCompare(a.date));\n}\n\nexport async function fetchMarkdown(url: string): Promise {\n const response = await fetchWithRetry(\n url,\n { headers: { \"User-Agent\": \"python-weekly-telegram-bot\" } },\n { label: `Fetch ${url}` },\n );\n if (!response.ok) throw new Error(`Fetch ${url} -> ${response.status}`);\n return await response.text();\n}\n\n/** One REST search per call, throttled to stay under the search rate limit. */\nexport async function searchRepos(name: string, token: string | null): Promise {\n await takeSearchSlot(token ? SEARCH_GAP_MS.authenticated : SEARCH_GAP_MS.anonymous);\n\n type Item = {\n full_name: string;\n html_url: string;\n description: string | null;\n stargazers_count: number;\n };\n const query = encodeURIComponent(`${name} in:name`);\n try {\n const data = await api<{ items: Item[] }>(\n `/search/repositories?q=${query}&sort=stars&per_page=8`,\n token,\n );\n return data.items.map((item) => ({\n fullName: item.full_name,\n htmlUrl: item.html_url,\n description: item.description ?? \"\",\n stars: item.stargazers_count,\n }));\n } catch (error) {\n console.warn(`GitHub search failed for \"${name}\": ${error}`);\n return [];\n }\n}\n\n/**\n * Looks up every project in a single GraphQL request. Needs a token, but keeps\n * the whole job inside Val Town's one-minute free-plan budget.\n */\nexport async function searchReposBatch(\n names: string[],\n token: string,\n): Promise> {\n const results = new Map();\n if (!names.length) return results;\n\n type Node = {\n nameWithOwner: string;\n url: string;\n description: string | null;\n stargazerCount: number;\n };\n\n for (let offset = 0; offset < names.length; offset += 20) {\n const chunk = names.slice(offset, offset + 20);\n const fields = chunk.map((name, index) =>\n `r${index}: search(query: ${JSON.stringify(`${name} in:name`)}, type: REPOSITORY, first: 8) {\n nodes { ... on Repository { nameWithOwner url description stargazerCount } }\n }`\n ).join(\"\\n\");\n\n const response = await fetchWithRetry(\n `${API}/graphql`,\n {\n method: \"POST\",\n headers: { ...headers(token), \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ query: `query { ${fields} }` }),\n },\n { label: \"GitHub GraphQL\" },\n );\n\n if (!response.ok) {\n console.warn(`GitHub GraphQL -> ${response.status} ${await response.text()}`);\n return results;\n }\n\n const body = await response.json() as {\n data?: Record;\n errors?: { message: string }[];\n };\n if (body.errors?.length) console.warn(`GitHub GraphQL: ${body.errors[0].message}`);\n if (!body.data) return results;\n\n chunk.forEach((name, index) => {\n const nodes = body.data![`r${index}`]?.nodes ?? [];\n results.set(\n name,\n nodes.filter((node) => node?.nameWithOwner).map((node) => ({\n fullName: node.nameWithOwner,\n htmlUrl: node.url,\n description: node.description ?? \"\",\n stars: node.stargazerCount,\n })),\n );\n });\n }\n\n return results;\n}\n",[],[149,241],"bb65d10b-bcce-4b33-9b06-1866e879eac1","errors.ts","0803e79c-8ef3-11f1-9f8e-1607ee4eb77e",44,["D",1786256652527],"export interface Diagnosis {\n /** Stable id used to avoid alerting about the same problem every hour. */\n signature: string;\n title: string;\n hints: string[];\n}\n\ninterface Rule {\n signature: string;\n test: RegExp;\n title: string;\n hints: string[];\n}\n\nconst RULES: Rule[] = [\n {\n signature: \"config-missing\",\n test: /TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be set/,\n title: \"缺少 Telegram 配置\",\n hints: [\"在 Val 的 Environment Variables 里补上 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID\"],\n },\n {\n signature: \"telegram-auth\",\n test: /Telegram sendMessage -> 401/,\n title: \"Telegram token 无效\",\n hints: [\n \"去 @BotFather 用 /mybots 确认 token，或 /revoke 后重新生成\",\n \"注意 token 不要带引号或多余空格\",\n ],\n },\n {\n signature: \"telegram-chat\",\n test: /Telegram sendMessage -> 400[\\s\\S]*chat not found/i,\n title: \"Telegram chat_id 不正确\",\n hints: [\n \"先主动给机器人发一条消息，机器人才能给你发消息\",\n \"访问 https://api.telegram.org/bot/getUpdates 取 message.chat.id\",\n \"推到群里时 chat_id 是负数，别漏掉减号\",\n ],\n },\n {\n signature: \"telegram-parse\",\n test: /can't parse entities|Bad Request: can not parse/i,\n title: \"Telegram 解析 HTML 失败\",\n hints: [\n \"多半是标题里出现了未转义的 < > &，检查 telegram.ts 的 escapeHtml\",\n \"临时办法：把 parse_mode 去掉先发纯文本，保证内容能送达\",\n ],\n },\n {\n signature: \"telegram-rate\",\n test: /Telegram sendMessage -> 429/,\n title: \"Telegram 触发限流\",\n hints: [\"调大 sendMessages 里每条之间的间隔（当前 500ms）\", \"下一次定时运行会自动重试\"],\n },\n {\n signature: \"github-rate\",\n test: /GitHub[\\s\\S]*(403|429)|API rate limit exceeded/i,\n title: \"GitHub API 限流\",\n hints: [\n \"配置 GITHUB_TOKEN 环境变量，把限额从 60 次/小时提到 5000 次/小时\",\n \"有 token 后项目检索会走 GraphQL，一次请求查完全部项目\",\n ],\n },\n {\n signature: \"github-auth\",\n test: /GitHub[\\s\\S]*401|Bad credentials/i,\n title: \"GITHUB_TOKEN 无效或已过期\",\n hints: [\"重新生成一个 classic token（不需要勾任何权限）并更新环境变量\"],\n },\n {\n signature: \"github-404\",\n test: /GitHub \\/repos[\\s\\S]*404/,\n title: \"找不到周刊目录\",\n hints: [\n \"确认 chinesehuazhou/python-weekly 仓库里 docs/en 目录还在\",\n \"如果作者调整了目录结构，改 src/config.ts 里的 REPO_DIR\",\n ],\n },\n {\n signature: \"parse-empty\",\n test: /Parsed 0 items/,\n title: \"解析不出任何条目\",\n hints: [\n \"周刊排版可能变了（①②③ 编号或 🦄/🐿 小标题被改动）\",\n \"改 src/parser.ts 的 ITEM_PREFIX / SECTION_HEADER 后跑 deno task test 验证\",\n \"本次不会推送，也不会记为已发送，修好后会自动补发\",\n ],\n },\n {\n signature: \"serper-quota\",\n test: /Serper (401|403|429)/i,\n title: \"Serper 额度用尽或 Key 无效\",\n hints: [\n \"注册送的 2500 次是一次性的，用完要去 serper.dev 充值\",\n \"按每期 12 次算够用四年多，提前用完通常说明 Key 被别处共用了\",\n \"配一个 TAVILY_API_KEY 就能自动兜底（每月 1000 次免费、不用绑卡）\",\n ],\n },\n {\n signature: \"tavily-quota\",\n test: /Tavily (401|403|429)/i,\n title: \"Tavily 额度用尽或 Key 无效\",\n hints: [\n \"免费额度每月 1 号重置，每月 1000 次，正常用量远远用不完\",\n \"Tavily 只是 Serper 的兜底，它挂了不影响 Serper 正常出结果\",\n \"确认 tavily.com 后台的 Key 没有过期或被撤销\",\n ],\n },\n {\n signature: \"network\",\n test: /fetch failed|error sending request|timed out|ETIMEDOUT|ECONNRESET/i,\n title: \"网络请求失败\",\n hints: [\"一般是临时抖动，下一次定时运行会重试\", \"连续多次出现的话检查对应站点是否可达\"],\n },\n {\n signature: \"timeout\",\n test: /execution.*(timeout|time limit)|exceeded.*wall clock/i,\n title: \"超出 Val Town 单次运行时长\",\n hints: [\n \"调小 RESOLVE_BUDGET_MS（默认 35000），让脚本更早保存进度并交给下一次运行\",\n \"配置 GITHUB_TOKEN 可以大幅缩短项目检索时间\",\n ],\n },\n];\n\nexport function diagnose(error: unknown): Diagnosis {\n const message = error instanceof Error ? `${error.message}` : String(error);\n const rule = RULES.find((candidate) => candidate.test.test(message));\n\n if (rule) return { signature: rule.signature, title: rule.title, hints: rule.hints };\n\n return {\n signature: `unknown:${message.slice(0, 80)}`,\n title: \"未分类的错误\",\n hints: [\"查看 Val Town 的日志定位具体位置\", \"先用 DRY_RUN=1 手动 Run 一次复现问题\"],\n };\n}\n",[],[149,249],"e3e28fa6-694f-4dd9-9092-a6a1d55517b8","config.ts","ffc1510a-8ef2-11f1-adce-1607ee4eb77e",46,["D",1786256652529],"import { DEFAULT_QUIET_DAYS } from \"./schedule.ts\";\n\nexport type Lang = \"en\" | \"zh\";\n\nexport interface Config {\n telegramBotToken: string;\n telegramChatId: string;\n lang: Lang;\n /** Directory inside the weekly repo that holds the issues for `lang`. */\n docsDir: string;\n /** serper.dev — the main search key. Optional, but coverage suffers without it. */\n serperApiKey: string | null;\n /** tavily.com — optional backup for when Serper is out of credits or down. */\n tavilyApiKey: string | null;\n githubToken: string | null;\n /** Push a Telegram alert when a run fails. */\n notifyErrors: boolean;\n /** Manual link pins, keyed by the item title (or any distinctive part of it). */\n overrides: Record;\n /** Skip the \"already sent\" check and push the newest issue again. */\n force: boolean;\n /** Days of silence after an issue before the job starts looking for the next one. */\n quietDays: number;\n /**\n * Time allowed for link lookups. Val Town caps a run at 1 minute on the free\n * plan, so anything left over is picked up by the next scheduled run.\n */\n budgetMs: number;\n}\n\nconst REPO_DIR: Record = {\n en: \"docs/en\",\n zh: \"docs\",\n};\n\nfunction env(key: string): string | null {\n const value = Deno.env.get(key);\n return value && value.trim() ? value.trim() : null;\n}\n\nfunction parseOverrides(): Record {\n const raw = env(\"LINK_OVERRIDES\");\n if (!raw) return {};\n try {\n const parsed = JSON.parse(raw) as Record;\n return Object.fromEntries(\n Object.entries(parsed)\n .filter(([, url]) => typeof url === \"string\")\n .map(([title, url]) => [title, url as string]),\n );\n } catch (error) {\n // A malformed override map shouldn't stop the whole issue from going out.\n console.warn(`Ignoring LINK_OVERRIDES, not valid JSON: ${error}`);\n return {};\n }\n}\n\nexport function loadConfig(): Config {\n const telegramBotToken = env(\"TELEGRAM_BOT_TOKEN\");\n const telegramChatId = env(\"TELEGRAM_CHAT_ID\");\n if (!telegramBotToken || !telegramChatId) {\n throw new Error(\"TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be set\");\n }\n\n const lang: Lang = env(\"WEEKLY_LANG\") === \"zh\" ? \"zh\" : \"en\";\n\n return {\n telegramBotToken,\n telegramChatId,\n lang,\n docsDir: REPO_DIR[lang],\n serperApiKey: env(\"SERPER_API_KEY\"),\n tavilyApiKey: env(\"TAVILY_API_KEY\"),\n githubToken: env(\"GITHUB_TOKEN\"),\n notifyErrors: env(\"ERROR_NOTIFY\") !== \"0\",\n overrides: parseOverrides(),\n force: env(\"FORCE_RESEND\") === \"1\",\n quietDays: Number(env(\"QUIET_DAYS\")) || DEFAULT_QUIET_DAYS,\n // Leaves room inside Val Town's one-minute cap for the GitHub calls before\n // the loop, the retries inside it, and the Telegram send after it.\n budgetMs: Number(env(\"RESOLVE_BUDGET_MS\")) || 35_000,\n };\n}\n\nexport const REPO = \"chinesehuazhou/python-weekly\";\n",[],[149,257],["D",1785730968691],[168,169,170,171,172,173,174,175,176,177],[149],["D",1785730366168],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":56,"_100":101,"_102":25},{"_13":85,"_32":86,"_44":43,"_87":45,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":46,"_94":95},"ctx",{"_78":-5,"_122":304,"_305":306,"_307":308,"_309":25,"_310":25,"_311":25,"_312":152,"_313":-5,"_314":-7,"_315":-7,"_316":62,"_317":25,"_318":25,"_319":-5,"_320":25,"_321":25,"_322":25,"_323":-5},"ENV",{"_275":276,"_277":278,"_279":86,"_280":281,"_282":283,"_284":285,"_286":287,"_288":289,"_290":291,"_292":293,"_294":295,"_296":297,"_298":299,"_300":301,"_302":303},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","71c1b20804b3232a7e513be260cfffc1932a9e97","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v60