dsh-hackertube 0.1.6 → 0.2.0

package/README.en.md

@@ -12,7 +12,40 @@ The dataset comes from [HackerTube](https://karpathy.bearblog.dev/hacker-tube/)
 
 This plugin consumes that official export. It is an unofficial project and is not affiliated with Andrej Karpathy, Hacker News, or YouTube.
 
-The original site works fine on its own. Moving it into the panel changes two things. You no longer switch windows, and the interface is fully available in Chinese, including titles, categories, summaries, and comments.
+The original site works fine on its own. Moving it into the panel adds a set of things the original cannot do, listed in [How it differs from the original site](#how-it-differs-from-the-original-site).
+
+## How it differs from the original site
+
+The original is a browse-only catalog: open it, watch, close it, all in English. Inside the DSH panel it differs in seven ways.
+
+**You never leave the window.** Player, details, HN discussion and related videos all live in the panel, so you can keep watching while you work.
+
+**The content is Chinese.** All 6454 titles and 166 category names ship with the repo and work the moment you install it. Summaries, recommendation reasons and HN comments are translated on demand, through the model first and machine translation as a fallback.
+
+**You can ask the video itself.** The AI drawer hands the model the subtitle lines around your current playhead, so "what is this part about" gets an answer grounded in the content rather than a paraphrase of the description.
+
+**There may be a Chinese-platform mirror.** Some videos have an existing repost on Bilibili, and the detail page adds a button next to YouTube when one is found. See [Alternative mirror](#alternative-mirror).
+
+**Likes and progress live on the host.** Likes, watch-later and history are written to the host directory, so clearing browser data does not lose them and a different browser still has them.
+
+**Your agent can search the library.** A `hackertube_search` tool is registered, so you can ask "is there a video about Raft" without opening the panel.
+
+**Recommendations follow your taste.** Liked videos feed the home ordering, with playlists and HN scores as a cold-start fallback.
+
+| Capability | Original site | This plugin |
+|---|---|---|
+| Browse and play | Yes | Yes |
+| Interface language | English | Chinese and English |
+| Chinese titles and categories | No | Complete, active on install |
+| Summary and comment translation | No | On demand, model first |
+| AI Q&A with subtitle context | No | Yes |
+| Share card | No | Yes |
+| Likes and watch history | Browser local | Persisted on the host |
+| Personalized recommendations | No | Yes |
+| Agent search tool | No | Yes |
+| Chinese-platform mirror | No | On demand, only when found |
+
+The original's advantage is that it is plain and instant. This plugin makes browsing heavier and buys the list above with it. If you only drop in occasionally, the original site is faster.
 
 ## Browse by category
 
@@ -91,6 +124,8 @@ The panel holds 6,454 videos across 16 areas and 150 categories, ordered by how
 
 The watch page has the player, the Hacker News discussion for that video, and a related rail on the right. The rail has a second pane for AI questions. It hands the model the subtitle lines within three minutes of the current playhead, so you can ask what a particular segment covers.
 
+A "Watch on Bilibili" button sometimes appears next to the YouTube one. It shows up only when the same video has an existing repost on the Chinese platform; when there is none, nothing appears at all.
+
 Search works with English and Chinese queries. A Chinese query matches both the Chinese title and the English tags.
 
 Likes, watch later, and history live on the host side, so clearing browser data does not lose them.
@@ -108,6 +143,32 @@ Likes, watch later, and history live on the host side, so clearing browser data
 | `?` | Show all shortcuts |
 | `Esc` | Close overlay |
 
+## Alternative mirror
+
+Some videos already have a repost on Bilibili, especially the subtitled ones. The watch page adds an entry next to "Watch on YouTube" when one is found, and shows nothing at all when there is none — no placeholder, no "not available" notice.
+
+The check is not keyword matching. Several hard constraints have to pass together:
+
+- **The duration must match**, within 2 seconds. A repost is a frame-accurate copy, which makes this the strongest physical fingerprint.
+- **It cannot predate the original.** A repost never goes up before the source.
+- **There has to be content evidence**: the description carries this video's source address, or the title overlaps heavily with the original, or one episode of a multi-part collection matches on duration.
+
+A video address in the description is two-way evidence. Pointing at this video is proof; pointing at **another** video by the same author is a veto, even when the titles look alike. That rule came from a real miss: a video titled "Not The Confederate Flag?" had its description link to a different video, and a same-channel clip with a coincidental duration got promoted in its place.
+
+When several reposts exist, the pick order is:
+
+```
+official channel  →  explicitly subtitled  →  Chinese title or high views  →  the rest by views
+```
+
+The small tag after the button is that tier: `Official`, `Subbed`, `Translated`, or `Repost`. A repost is never dropped for low view count — some channels have no official presence at all, and a good repost is the only option.
+
+Derivative works do not count. Commentary, adaptations and reaction videos are excluded, because clicking through has to land on the same film. The exclusion is skipped when the description carries the source address, since repost channels often put words like "analysis" in the title of a genuine subtitled copy.
+
+Lookups are on demand: one query when you open the watch page, about 0.8 seconds the first time, 0 milliseconds from the local cache afterwards. Videos you never open are never queried, and no request reaches the other site for them.
+
+The hit rate is roughly half. Obscure videos and rights-heavy broadcast material simply have no repost — that is about what exists on the other side, not about how well the lookup works.
+
 ## A tool for your agent
 
 The plugin registers a tool named `hackertube_search`. Once installed, your agent can search this video library from any conversation, without opening the panel.
@@ -193,6 +254,7 @@ Machine translation uses the public Google web translate endpoint. Comment bodie
 | AI questions | A model configured in DSH | The panel reports the model is unavailable, everything else works |
 | Comment translation | Network access | The button does nothing and the text stays as written |
 | Subtitles and direct-stream fallback | `yt-dlp` and `ffmpeg` on PATH | Video still plays, the AI answers lose subtitle context |
+| Alternative mirror | The Chinese platform is reachable | No button appears, everything else works |
 
 Both `yt-dlp` and `ffmpeg` are optional. They affect two things only, whether AI answers can use subtitles and whether playback can fall back to a direct stream when YouTube refuses the embed.
 
@@ -227,6 +289,7 @@ i18n/zh-comments.json Comment translation cache
 list.json             YouTube metadata and list snapshot
 prefs.json            Likes, watch later, history
 subs/                 Subtitles
+mirror.json           Mirror lookups and timestamps
 ```
 
 ## Known limitations
@@ -239,6 +302,8 @@ YouTube embeds follow upstream policy. Age-restricted and region-restricted vide
 
 The playback relay listens on `127.0.0.1:18090`, falling back to 18091 and 18092 when the port is taken.
 
+The mirror entry appears only when a matching repost actually exists, roughly half the time. A missing button does not mean the plugin failed: most of the time the other side simply does not have that video.
+
 ## Credits
 
 Thanks to Andrej Karpathy for building HackerTube and for publishing its data export. This plugin builds on that work.

package/README.md

@@ -12,7 +12,40 @@
 
 本插件使用的正是这份官方导出。非官方项目，与 Andrej Karpathy、Hacker News、YouTube 均无隶属关系。
 
-原站同样可以直接访问。将其并入面板带来两点差异：一是省去窗口切换，二是提供完整的中文支持，包括标题、分类、摘要与评论。
+原站同样可以直接访问。并入面板之后它多出一些原站做不到的事情，逐条列在[与原始站点的差别](#与原始站点的差别)一节。
+
+## 与原始站点的差别
+
+原站是一个纯浏览型的目录：打开、看片、关掉，界面全英文。并入 DSH 面板之后，它在七件事上不一样。
+
+**不用离开当前窗口。** 播放器、详情、HN 讨论、相关推荐都在面板内，边写代码边看，不用来回切标签页。
+
+**内容是中文的。** 6454 条标题与 166 个分类名随仓库附带，装完就是中文。摘要、推荐理由、HN 评论按需翻译，优先走模型，模型不可用时退到机翻。
+
+**可以问视频本身。** 详情页右侧的 AI 抽屉会把当前播放位置前后三分钟的字幕交给模型，所以「这一段在讲什么」得到的回答基于内容，不是复述简介。
+
+**可能有中文平台的备用入口。** 有些视频在 B 站上有现成搬运，详情页会在 YouTube 按钮旁边补一个，命中才出现。详见[备用观看源](#备用观看源)。
+
+**收藏和进度存在宿主侧。** 喜欢、稍后看、播放历史写在宿主目录里，清浏览器数据不会丢，换浏览器也还在。
+
+**Agent 可以直接检索这个库。** 注册了 `hackertube_search` 工具，不用打开面板，在对话里就能问「有没有讲 Raft 的视频」。
+
+**推荐会跟着你的口味走。** 喜欢过的视频参与首页排序，第一次打开时用播放列表和 HN 分数兜底。
+
+| 能力 | 原站 | 本插件 |
+|---|---|---|
+| 浏览与播放 | 有 | 有 |
+| 界面语言 | 英文 | 中英双语 |
+| 标题与分类中文 | 无 | 全量，装完即生效 |
+| 摘要与评论翻译 | 无 | 按需，模型优先 |
+| AI 问答（带字幕上下文） | 无 | 有 |
+| 分享卡片 | 无 | 有 |
+| 收藏与播放历史 | 浏览器本地 | 宿主侧持久化 |
+| 个性化推荐 | 无 | 有 |
+| Agent 检索工具 | 无 | 有 |
+| 中文平台备用源 | 无 | 按需，命中才出现 |
+
+原站的优势是简洁和即开即用，本插件把浏览体验做重了，换来了上面这些。如果只是偶尔点开看看，直接访问原站更快。
 
 ## 分类浏览
 
@@ -91,6 +124,8 @@ DSH 从 profile 目录加载插件，在普通项目里安装不会生效。需
 
 详情页包含播放器、该视频在 HN 上的讨论，以及右侧的相关推荐。右侧另有 AI 问答页，会把当前播放位置前后三分钟的字幕片段一并交给模型，因此可以询问某一段的具体内容。
 
+播放按钮旁边有时会多出一个「在 B 站观看」，那是查到同一支片子有中文平台搬运时才会出现的备用入口，没有就是没有。
+
 搜索支持中英文混用，中文查询会同时匹配中文标题与英文标签。
 
 喜欢、稍后看与播放历史记录在宿主侧，清除浏览器数据不会丢失。
@@ -108,6 +143,32 @@ DSH 从 profile 目录加载插件，在普通项目里安装不会生效。需
 | `?` | 显示快捷键一览 |
 | `Esc` | 关闭浮层 |
 
+## 备用观看源
+
+有些视频在 B 站上有现成的搬运，尤其是带字幕的那种。详情页会在「在 YouTube 观看」旁边补一个入口，命中才出现，没命中就什么都不显示——不放占位、不显示「暂无」。
+
+判定不是关键词匹配，是几条硬约束一起过：
+
+- **时长必须一致**，容差 ±2 秒。搬运是逐秒复制的，这是最稳的物理指纹。
+- **不能早于原视频发布**。搬运不会早于原片。
+- **要有内容凭据**：简介里写着本条原视频的地址，或者标题与原标题高度重合，或者合集里某一集的时长对得上。
+
+简介里的视频地址是双向证据。它指向本条，就是铁证；它指向同一个作者的**另一支**视频，就直接否决，哪怕标题很像。这条规则来自一次真实的误判：某频道《这不是邦联国旗？》的简介里写着另一支视频的地址，被同频道一条时长巧合的片子顶了上来。
+
+多个搬运版本时按这个顺序挑：
+
+```
+官方入驻号  →  明确标注中字或熟肉  →  中文标题或高播放  →  其余按播放量
+```
+
+按钮后面的小标就是档位，`官方`、`中字`、`中文`、`转载` 四种。转载不会因为播放量低被丢掉——有的频道根本没有官方入驻，高质量转载就是唯一选项。
+
+二次创作不算。解说、改编、reaction 这类重新演绎的内容会被排除，点过去看到的必须是同一支片子。但简介里有原视频地址时不排除，因为搬运号常把「万字解析」这类词当自家噱头，标在真熟肉标题上。
+
+查询是按需的：打开详情页才查一次，首次约 0.8 秒，之后读本地缓存是 0 毫秒。没打开过的视频不会被查，也不会向对方站点发出任何请求。
+
+命中率大约一半。冷门视频、版权严格的官媒内容基本找不到对应搬运，这是内容存量决定的——不是查询能力不够，是对面真的没有。
+
 ## 给 agent 用的工具
 
 插件注册了一个工具 `hackertube_search`。装了插件之后，不用打开面板，agent 在对话里就能检索这个视频库。
@@ -193,6 +254,7 @@ agent 据此回答：
 | AI 问答 | DSH 已配置模型 | 面板提示模型不可用，其余功能正常 |
 | 评论翻译 | 外网 | 按钮无响应，文本保持原文 |
 | 字幕与直链兜底播放 | PATH 中存在 yt-dlp 与 ffmpeg | 视频仍可播放，AI 缺少字幕上下文 |
+| 备用观看源 | 中文平台可达 | 不出现按钮，其余功能正常 |
 
 yt-dlp 与 ffmpeg 均为可选。它们只影响两件事：AI 问答能否携带字幕上下文，以及 YouTube 嵌入被拒绝时能否回退到直链播放。
 
@@ -227,6 +289,7 @@ i18n/zh-comments.json 评论机翻缓存
 list.json             YouTube 元信息与列表快照
 prefs.json            喜欢、稍后看、历史
 subs/                 字幕
+mirror.json           备用源解析结果与时间戳
 ```
 
 ## 已知限制
@@ -239,6 +302,8 @@ YouTube 嵌入受上游策略限制，年龄限制或地区限制的视频需前
 
 播放中转页监听 `127.0.0.1:18090`，端口被占用时依次尝试 18091 与 18092。
 
+备用源只在确实存在对应搬运时出现，覆盖率约一半。没出现按钮不代表插件没工作，多数情况是对面确实没有这支片子。
+
 ## 致谢
 
 感谢 Andrej Karpathy 开发 HackerTube 并将数据导出公开，本插件建立在这份工作之上。