hackertube-zh 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crisxuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
+    <img src="docs/logo-light.png" width="470" alt="HackerTube 中文插件">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/hackertube-zh"><img src="https://img.shields.io/npm/v/hackertube-zh?color=ff6600" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+</p>
+
+<p align="center"><code>npx hackertube-zh</code></p>
+
+给 [HackerTube](https://hackertube.org)（Karpathy 做的“HN 推荐过的 YouTube 视频”站）用的 Chrome 扩展，把整个观看体验实时变成中文：
+
+- **界面汉化**：菜单、筛选、按钮、观看次数、日期、HN 推荐信息等，本地词典即时替换，不走网络。
+- **内容翻译**：视频标题、简介、“HN 为什么喜欢它”、HN 评论、分类名、播放列表介绍。滚动到哪翻到哪，译文以**双语对照**或**仅中文**方式渲染在原文位置，样式与原站一致。
+- **实时中文字幕**：在 HackerTube 的嵌入播放器里显示中英双语（或仅中文）字幕，全屏也能看到，提前翻译当前播放位置往后 5 分钟。
+- **中文搜索**：在搜索框输入中文，会先翻译成英文再交给 HackerTube 的语义搜索（它只理解英文）。
+- **用 YouTube 登录状态播放**（可选）：解决嵌入播放器一直提示 “Sign in to confirm you're not a bot” 的问题，见下方“常见问题”。
+- **三种翻译引擎**：Google 翻译（免费，默认）、Claude、任意 OpenAI 兼容接口（DeepSeek、通义千问、Ollama 等）。LLM 出错时自动临时回退到 Google。
+- 所有译文缓存在本地，同一个视频、同一页再次打开不再请求翻译。缓存有上限，很久没用到的译文会自动清掉。
+- 翻译请求失败（断网、被限流）时会自动重试，网络恢复后页面和字幕会自己补上中文，不用刷新。
+
+## 安装
+
+需要 Node.js 18+ 和 Chrome 116+（Edge 等 Chromium 浏览器同样可用）。
+
+```bash
+npx hackertube-zh
+```
+
+它会把扩展放到 `~/hackertube-zh`，把 `chrome://extensions` 复制到剪贴板，并在 Finder 里选中这个文件夹。然后在 Chrome 里：
+
+1. 地址栏粘贴 `chrome://extensions` 回车；
+2. 打开右上角「开发者模式」；
+3. 点「加载已解压的扩展程序」选择 `~/hackertube-zh`（或者直接把 Finder 里的文件夹拖到页面上）。
+
+打开 <https://hackertube.org>，页面就是双语的了。点工具栏上橙色的「中」图标可以切换模式和引擎。
+
+**更新**：再运行一次 `npx hackertube-zh`，然后在扩展卡片上点刷新按钮 ↻。可选参数：`--dir <路径>` 换安装位置，`--no-open` 只复制文件，`--help` 查看帮助。
+
+为什么最后三步不能也自动化：Chrome 正式版会忽略命令行传入的 `chrome://` 地址，也不再支持用命令行参数加载扩展，加载未上架的扩展必须由用户自己打开开发者模式。要做到真正的一键安装，需要上架 Chrome 应用商店。
+
+**从源码安装**：在 `chrome://extensions` 打开开发者模式，点「加载已解压的扩展程序」选择本目录。改代码后在扩展卡片上点刷新按钮，再刷新 HackerTube 页面。
+
+## 使用
+
+| 位置 | 作用 |
+| --- | --- |
+| 工具栏弹窗 | 网页翻译：双语对照 / 仅中文 / 关闭；视频字幕：中英双语 / 仅中文 / 关闭；字幕大小；用 YouTube 登录状态播放；翻译引擎 |
+| 更多设置（选项页） | 引擎的 Key / 模型 / 接口地址，测试引擎，字幕离底部的距离，中文搜索开关，清空缓存 |
+| 视频页 | 点播放后，播放器左上角会提示“中文字幕 · 已获取 N 句 / 翻译中 / 已就绪” |
+
+### 翻译引擎
+
+- **Google 翻译**：免费、零配置，需要网络能访问 `translate.googleapis.com`。个别标题 Google 会原样返回（它当成专有名词），这时不显示译文。
+- **Claude**：在选项页填 API Key。默认模型 `claude-opus-5-5`，思考力度默认 `low`（翻译不需要深度推理，响应更快、思考开销更小）；想更省钱可以把模型换成 `claude-haiku-5-5`。字幕请求会带上视频标题和前几句作为上下文，自动生成字幕里没有标点的碎句也能翻得通顺。Key 只存在本机 `chrome.storage.local`，不会同步。
+- **OpenAI 兼容接口**：填 Base URL 和模型名，例如 DeepSeek `https://api.deepseek.com/v1` + `deepseek-chat`，本地 Ollama `http://localhost:11434/v1` + 模型名。保存时浏览器会请求访问该地址的权限。
+
+LLM 引擎按用量计费。字幕只翻译播放位置往后 5 分钟的内容，所以费用跟实际看了多少成正比，不会一打开视频就把整部翻完。
+
+## 常见问题
+
+**播放器提示 “Sign in to confirm you're not a bot”，在 YouTube 登录了还是看不了？**
+
+两个原因叠在一起：
+
+1. YouTube 怀疑你的网络环境（最常见的是代理 / VPN 节点，很多人共用同一个出口 IP），要求登录才能播放。
+2. HackerTube 用 `youtube-nocookie.com`（隐私增强模式）嵌入视频，这个域名故意不使用 youtube.com 的登录 Cookie，所以你在 youtube.com 登录了，嵌入播放器里仍然是未登录状态。
+
+解决办法（任选其一）：
+
+- 在弹窗或选项页打开 **“用我的 YouTube 登录状态播放”**，然后刷新视频页。扩展会把 HackerTube 的嵌入改由 `www.youtube.com/embed` 播放（HackerTube 的安全策略本来就允许这个域名），能用上你已登录的账号，中文字幕照常显示。代价是观看会计入你的 YouTube 历史记录；还需要 Chrome 允许第三方 Cookie（设置 → 隐私和安全 → 第三方 Cookie，无痕窗口默认屏蔽）。
+- 换一个不那么拥挤的代理节点。
+- 点视频下方的「YouTube」按钮到 youtube.com 观看（中文字幕在那里不生效）。
+
+这个开关只影响 HackerTube 页面里加载的播放器（用 declarativeNetRequest 规则，限定由 hackertube.org 发起的 iframe 请求），不影响其他网站。
+
+## 工作原理
+
+```
+hackertube.org 页面                         YouTube 嵌入播放器（iframe, youtube-nocookie.com）
+┌──────────────────────────────┐           ┌─────────────────────────────────────────────┐
+│ content/site.js               │           │ content/player-main.js（页面主世界）         │
+│  MutationObserver 监听 SPA 渲染 │           │  播放后通过播放器 API 打开英文字幕，            │
+│  ├ 界面字符串 → lib/uidict.js   │           │  拦截播放器自己下载的 /api/timedtext 字幕文件   │
+│  ├ 内容元素进入视口 → 批量翻译   │           │        │ postMessage                         │
+│  └ 中文搜索词 → 英文再搜索       │           │ content/player.js（扩展隔离世界）             │
+└──────────────┬───────────────┘           │  lib/subtitles.js 把字幕重组为句子             │
+               │                           │  按播放进度分批翻译，叠加层渲染双语字幕          │
+               │ chrome.runtime            └──────────────────────┬──────────────────────┘
+               ▼                                                  │
+        background.js（Service Worker）◄───────────────────────────┘
+          缓存（内存 + storage.local）→ lib/engines.js：Google / Claude / OpenAI 兼容
+```
+
+几个关键设计：
+
+- **为什么要拦截字幕而不是自己下载**：YouTube 的字幕接口现在要求播放器生成的 proof-of-origin 令牌，直接请求通常拿到空文件。所以扩展在嵌入页的主世界里调用播放器的 `loadModule('captions')` / `setOption('captions','track',…)` 打开英文字幕（优先人工字幕，其次自动生成），再复制播放器自己下载的那份。拿不到时会提示“点一下 CC 按钮重试”。
+- **字幕重组**：自动生成字幕是逐词、无标点的；人工字幕常把一句话拆在两行。`lib/subtitles.js` 按标点、停顿和长度把它们重组成适合翻译和阅读的句子，并按字数比例分配时间。
+- **只在 HackerTube 里生效**：嵌入播放器的脚本会检查 iframe 的上级页面是不是 hackertube.org，其他网站里的 YouTube 嵌入完全不受影响。
+- **可完全还原**：网页翻译设为“关闭”时，所有替换的文字恢复原样，插入的译文全部移除。
+
+## 隐私
+
+- 被发送去翻译的只有：页面上的标题、简介、评论、分类名，字幕文本，以及你输入的中文搜索词。发送对象是你选的那个引擎。
+- 不收集、不上传任何浏览记录；HackerTube 自己存在 localStorage 里的“赞过 / 历史 / 稍后观看”不会被读取。
+- API Key 只存在本机。
+
+## 已知限制
+
+- 视频本身没有任何字幕（人工和自动生成都没有）时，无法生成中文字幕。
+- 只处理 HackerTube 页面内的嵌入播放器；点“YouTube”按钮跳到 youtube.com 观看时不生效。
+- YouTube 播放器接口不是公开 API，YouTube 改版后字幕获取可能需要调整（`content/player-main.js`）。
+
+## 开发
+
+项目没有构建步骤，也没有任何依赖。
+
+```bash
+npm test          # 单元测试：字幕解析与分句、引擎请求/响应、界面词典
+npm run check     # 静态检查：manifest 引用的文件都存在、所有 JS 语法正确
+npm run icons     # 从 icons/*.svg 渲染插件图标 PNG 和 README 横版 logo（用本机 Chrome 的无头模式）
+npm run zip       # 打包到 dist/hackertube-zh.zip（上架 Chrome 应用商店用）
+```
+
+发布 npx 安装包（`bin/install.js` 是安装器，`package.json` 的 `files` 决定包里有什么，`npm run check` 会核对它覆盖了扩展用到的每个文件、版本号与 manifest 一致）：
+
+```bash
+npm publish                        # 之后任何人都能 npx hackertube-zh
+```
+
+不想发布到 npm 的话，推到 GitHub 后也可以用 `npx github:crisxuan/hackertube-zh`。发布前在本地试：`npm pack` 后运行 `npx --package=./hackertube-zh-<版本号>.tgz hackertube-zh --dir /tmp/htz-test --no-open`。
+
+不安装扩展也能调试：`node dev/server.js 8787 <放测试视频的目录>` 启动开发服务器（HackerTube 的 CSP 禁止注入脚本，所以这里用本地镜像）：
+
+- `http://localhost:8787/`：真实的 HackerTube 页面（`/api` 代理到 hackertube.org），注入了扩展的页面脚本和后台逻辑，`chrome.*` 由 `dev/chrome-shim.js` 模拟。控制台里可以用 `__htzDev.setSettings({ pageMode: 'zh' })` 切换设置。
+- `http://localhost:8787/player`：模拟嵌入播放器，按钮发送自动生成 / 人工字幕，检查字幕叠加层、同步和样式。测试视频可以用 `ffmpeg -f lavfi -i testsrc=size=640x360:rate=24 -t 60 -pix_fmt yuv420p test.mp4` 生成。
+- `http://localhost:8787/preview/popup`、`/preview/options`：弹窗和选项页。
+
+```
+manifest.json          扩展清单（MV3）
+background.js          Service Worker：翻译调度、并发限制、缓存、引擎回退
+lib/                   公共模块（浏览器和 node 测试共用）
+  engines.js           Google / Claude / OpenAI 兼容引擎
+  cache.js             译文缓存（内存 + storage.local，分两代淘汰旧条目）
+  embedlogin.js        “用 YouTube 登录状态播放”的重定向规则
+  subtitles.js         json3 / srv3 / WebVTT 解析与分句
+  uidict.js            HackerTube 界面词典
+  textutil.js          哈希、分批等小工具
+  runtime.js           设置读写、消息通信
+content/               内容脚本：site.*（HackerTube 页面）、player*（嵌入播放器）
+popup/ options/ ui/    弹窗、选项页、公共样式
+bin/install.js         npx 安装器
+dev/                   本地调试服务器和模拟页面
+tests/                 node:test 单元测试
+scripts/               静态检查、图标渲染
+icons/                 插件图标：icon.svg（48/128px）、icon-small.svg（16/32px 简化版）及渲染出的 PNG
+docs/                  README 横版 logo（浅色 / 深色两版，由 npm run icons 生成）
+```
+
+## 参与贡献
+
+欢迎提 Issue 和 Pull Request。提交前请跑一下 `npm test` 和 `npm run check`；改动行为时请补上对应的测试。HackerTube 或 YouTube 改版导致失效时，欢迎附上出问题的页面地址。
+
+## 许可证
+
+[MIT](LICENSE)。本项目与 HackerTube、Hacker News、YouTube 均无关联。

package/background.js

@@ -0,0 +1,140 @@
+// Service worker: the only place that talks to translation engines. Content scripts send batches of text;
+// results are cached (lib/cache.js) per engine, so revisiting a page or video is free and instant.
+import "./lib/textutil.js";
+import "./lib/engines.js";
+import "./lib/runtime.js";
+import "./lib/embedlogin.js";
+import "./lib/cache.js";
+
+const { text: T, engines: E, runtime: R, embedlogin: EL, cache: C } = globalThis.HTZ;
+
+// keep the embed redirect rule in step with the setting: on every service worker start, and on every change
+const syncEmbedLogin = (s) => EL.sync(!!s.embedLogin).catch((e) => console.warn("[HackerTube 中文] embed rule:", e));
+R.loadSettings().then(syncEmbedLogin);
+R.onSettings(syncEmbedLogin);
+
+const ENGINE_NAMES = { google: "Google 翻译", claude: "Claude", openai: "OpenAI 兼容接口" };
+const LIMITS = {
+  google: { maxItems: 50, maxChars: 4500, concurrency: 4 },
+  // small batches: a model has to finish the whole reply inside the engines' 25 s limit (see lib/engines.js)
+  llm: { maxItems: 12, maxChars: 1500, concurrency: 3 },
+};
+
+// ---------- small helpers ----------
+function limiter(n) {
+  let active = 0;
+  const queue = [];
+  const next = () => {
+    if (active >= n || !queue.length) return;
+    active++;
+    const { fn, resolve, reject } = queue.shift();
+    fn().then(resolve, reject).finally(() => { active--; next(); });
+  };
+  return (fn) => new Promise((resolve, reject) => { queue.push({ fn, resolve, reject }); next(); });
+}
+const limits = { google: limiter(LIMITS.google.concurrency), llm: limiter(LIMITS.llm.concurrency) };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const cache = C.create(chrome.storage.local);
+
+// The cache key includes everything that changes the output: engine, model, target language and, for LLMs,
+// the kind of text (subtitle prompts differ from page prompts).
+function engineId(s, kind, to) {
+  if (s.engine === "claude") return `claude|${s.claudeModel}|${kind}|${to}`;
+  if (s.engine === "openai") return `openai|${s.openaiBaseUrl}|${s.openaiModel}|${kind}|${to}`;
+  return `google|${to}`;
+}
+
+// ---------- engines ----------
+async function googleBatch(texts, to) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await limits.google(() => E.google(texts, { to }));
+    } catch (e) {
+      // the free endpoint rate-limits bursts: back off once, then give up
+      if (attempt === 0 && (e.status === 429 || e.status >= 500 || e.name === "TimeoutError")) { await sleep(1500); continue; }
+      throw e;
+    }
+  }
+}
+
+async function runChunks(texts, opts, fn) {
+  const chunks = T.chunk(texts, opts);
+  const parts = await Promise.all(chunks.map((idx) => fn(idx.map((i) => texts[i]))));
+  const out = new Array(texts.length);
+  chunks.forEach((idx, c) => idx.forEach((i, j) => { out[i] = parts[c][j]; }));
+  return out;
+}
+
+async function runEngine(texts, { settings, secrets, kind, to, context }) {
+  if (settings.engine === "claude" || settings.engine === "openai") {
+    const call = settings.engine === "claude"
+      ? (batch) => limits.llm(() => E.claude(batch, {
+          to, kind, context, model: settings.claudeModel, effort: settings.claudeEffort, apiKey: secrets.claudeKey,
+        }))
+      : (batch) => limits.llm(() => E.openai(batch, {
+          to, kind, context, model: settings.openaiModel, baseUrl: settings.openaiBaseUrl, apiKey: secrets.openaiKey,
+        }));
+    try {
+      return { translations: await runChunks(texts, LIMITS.llm, call), cache: true };
+    } catch (e) {
+      // keep the page and subtitles working: fall back to Google for this request and say why
+      console.warn("[HackerTube 中文] LLM engine failed, falling back to Google:", e);
+      const translations = await runChunks(texts, LIMITS.google, (b) => googleBatch(b, to));
+      return { translations, cache: false, warning: `${ENGINE_NAMES[settings.engine]} 出错（${e.message}），已临时改用 Google 翻译` };
+    }
+  }
+  return { translations: await runChunks(texts, LIMITS.google, (b) => googleBatch(b, to)), cache: true };
+}
+
+async function translate({ texts, kind = "page", to = "zh-CN", context }) {
+  if (!Array.isArray(texts) || !texts.length) return { translations: [] };
+  if (texts.some((t) => typeof t !== "string")) throw new Error("texts must be strings");
+  const [settings, secrets] = await Promise.all([R.loadSettings(), R.loadSecrets()]);
+  const eid = engineId(settings, kind, to);
+  const ids = texts.map((t) => T.hash(eid + "\u0001" + t));
+  const out = await cache.get(ids);
+
+  const todo = [];
+  out.forEach((v, i) => { if (v == null) todo.push(i); });
+  let warning;
+  if (todo.length) {
+    // dedupe within the request: the same title often appears twice on one page
+    const uniq = [...new Set(todo.map((i) => texts[i]))];
+    const res = await runEngine(uniq, { settings, secrets, kind, to, context });
+    warning = res.warning;
+    const byText = new Map(uniq.map((t, j) => [t, res.translations[j]]));
+    const toStore = {};
+    for (const i of todo) {
+      out[i] = byText.get(texts[i]);
+      if (res.cache) toStore[ids[i]] = out[i];
+    }
+    cache.put(toStore);
+  }
+  return { translations: out, warning };
+}
+
+async function testEngine() {
+  const [settings, secrets] = await Promise.all([R.loadSettings(), R.loadSecrets()]);
+  const sample = ["Overwatch Gameplay Architecture and Netcode", "The quick brown fox jumps over the lazy dog."];
+  const started = Date.now();
+  const res = await runEngine(sample, { settings, secrets, kind: "page", to: "zh-CN" });
+  if (res.warning) throw new Error(res.warning);
+  return { engine: ENGINE_NAMES[settings.engine], ms: Date.now() - started, sample, translations: res.translations };
+}
+
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
+  const reply = (p) => {
+    p.then((data) => sendResponse({ ok: true, ...data }), (e) => sendResponse({ ok: false, error: String((e && e.message) || e) }));
+    return true; // async response
+  };
+  // translation requests come only from our own content scripts and pages
+  if (sender.id !== chrome.runtime.id) return false;
+  switch (msg && msg.type) {
+    case "translate": return reply(translate(msg));
+    case "testEngine": return reply(testEngine());
+    case "cacheStats": return reply(cache.count().then((entries) => ({ entries })));
+    case "clearCache": return reply(cache.clear().then((removed) => ({ removed })));
+    default: return false;
+  }
+});

package/bin/install.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// npx hackertube-zh — put the extension in a fixed folder Chrome can load it from, then walk the user through the
+// last two clicks. Chrome doesn't let scripts finish the job: release builds ignore chrome:// URLs passed on the
+// command line, and loading an unpacked extension needs Developer mode, which only the user can switch on.
+// Running it again updates the files in place; Chrome then needs one click on the extension's reload button.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PKG_ROOT = path.join(__dirname, "..");
+// everything the browser loads; scripts/check.js verifies this covers every file the manifest references
+const EXTENSION_FILES = ["manifest.json", "background.js", "lib", "content", "popup", "options", "ui", "icons"];
+const EXTENSIONS_URL = "chrome://extensions";
+const DEFAULT_DIR = path.join(os.homedir(), "hackertube-zh"); // visible, so the folder picker finds it easily
+
+const readManifest = (dir) => {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, "manifest.json"), "utf8")); } catch { return null; }
+};
+
+// Copy the extension into `dir`. Refuses to touch a non-empty folder that isn't a previous install.
+function install(dir, src = PKG_ROOT) {
+  const target = path.resolve(dir);
+  if (target === path.resolve(src)) throw new Error("目标文件夹就是扩展源码目录本身，请换一个 --dir");
+  const ours = readManifest(src);
+  const existing = fs.existsSync(target) ? fs.readdirSync(target) : [];
+  const previous = existing.length ? readManifest(target) : null;
+  if (existing.length && (!previous || previous.name !== ours.name)) {
+    throw new Error(`${target} 已存在且不是本扩展的安装目录，为避免覆盖你的文件，已停止。可以用 --dir 指定别的位置。`);
+  }
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of EXTENSION_FILES) {
+    // replace whole entries so files removed in a new version don't linger
+    fs.rmSync(path.join(target, entry), { recursive: true, force: true });
+    fs.cpSync(path.join(src, entry), path.join(target, entry), { recursive: true });
+  }
+  return { dir: target, version: ours.version, previousVersion: previous && previous.version };
+}
+
+// The desktop conveniences for each OS: put chrome://extensions on the clipboard, show the folder in the file
+// manager (so it can be dragged onto the extensions page), and bring Chrome to the front.
+function plan(platform, dir) {
+  if (platform === "darwin") {
+    return [
+      { what: "clipboard", cmd: "pbcopy", args: [], input: EXTENSIONS_URL },
+      { what: "reveal", cmd: "open", args: ["-R", dir] },
+      { what: "browser", cmd: "open", args: ["-a", "Google Chrome"] },
+    ];
+  }
+  if (platform === "win32") {
+    return [
+      { what: "clipboard", cmd: "clip", args: [], input: EXTENSIONS_URL },
+      { what: "reveal", cmd: "explorer", args: [`/select,${dir}`] },
+      { what: "browser", cmd: "cmd", args: ["/c", "start", "", "chrome"] },
+    ];
+  }
+  return [
+    { what: "clipboard", cmd: "wl-copy", args: [], input: EXTENSIONS_URL },
+    { what: "clipboard", cmd: "xclip", args: ["-selection", "clipboard"], input: EXTENSIONS_URL },
+    { what: "reveal", cmd: "xdg-open", args: [path.dirname(dir)] },
+  ];
+}
+
+// Best effort: a missing tool just means that convenience is skipped. Returns which conveniences worked.
+function runPlan(steps) {
+  const done = new Set();
+  for (const s of steps) {
+    if (done.has(s.what)) continue;
+    const r = spawnSync(s.cmd, s.args, { input: s.input, stdio: [s.input == null ? "ignore" : "pipe", "ignore", "ignore"], timeout: 5000 });
+    // explorer.exe exits with 1 even when it worked
+    if (!r.error && (r.status === 0 || (s.cmd === "explorer" && r.status === 1))) done.add(s.what);
+  }
+  return done;
+}
+
+function usage() {
+  return `用法：npx hackertube-zh [选项]
+
+把「HackerTube 中文助手」Chrome 扩展放到固定文件夹，并引导你在 Chrome 里加载它。
+再次运行即更新。
+
+选项：
+  --dir <路径>   安装到指定文件夹（默认 ${DEFAULT_DIR}）
+  --no-open      只复制文件：不写剪贴板、不打开文件夹和 Chrome
+  -h, --help     显示帮助`;
+}
+
+function parseArgs(argv) {
+  const opts = { dir: DEFAULT_DIR, open: true, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--no-open") opts.open = false;
+    else if (a === "--dir") {
+      if (!argv[i + 1]) throw new Error("--dir 需要一个路径");
+      opts.dir = argv[++i].replace(/^~(?=$|[\\/])/, os.homedir());
+    } else throw new Error(`不认识的参数：${a}\n\n${usage()}`);
+  }
+  return opts;
+}
+
+function main(argv = process.argv.slice(2), platform = process.platform) {
+  const opts = parseArgs(argv);
+  if (opts.help) return console.log(usage());
+
+  const res = install(opts.dir);
+  const done = opts.open ? runPlan(plan(platform, res.dir)) : new Set();
+  const tty = process.stdout.isTTY;
+  const b = (s) => (tty ? `\x1b[1m${s}\x1b[0m` : s);
+  const g = (s) => (tty ? `\x1b[32m${s}\x1b[0m` : s);
+  const urlHint = done.has("clipboard") ? `（已复制，粘贴即可）` : "";
+  const picker = platform === "darwin" ? "（文件选择框里按 ⌘⇧G 可以直接输入路径）" : "";
+  const lines = [];
+
+  if (res.previousVersion) {
+    const head = res.previousVersion === res.version
+      ? `✔ HackerTube 中文助手已是最新版本（${res.version}），文件已重新写入：`
+      : `✔ HackerTube 中文助手已更新：${res.previousVersion} → ${res.version}`;
+    lines.push(g(head), `  ${res.dir}`, "",
+      "让 Chrome 用上新版本：",
+      `  1. 在 Chrome 地址栏打开 ${b(EXTENSIONS_URL)}${urlHint}`,
+      `  2. 在「HackerTube 中文助手」卡片上点刷新按钮 ↻，再刷新 HackerTube 页面`);
+  } else {
+    lines.push(g(`✔ HackerTube 中文助手 ${res.version} 已放到：`), `  ${b(res.dir)}`, "",
+      "在 Chrome 里还差三步（只需做一次）：",
+      `  1. 在 Chrome 地址栏打开 ${b(EXTENSIONS_URL)}${urlHint}`,
+      `  2. 打开页面右上角的「开发者模式」`,
+      `  3. 点「加载已解压的扩展程序」，选择上面这个文件夹${picker}`,
+      done.has("reveal") ? `     也可以直接把刚弹出的 ${path.basename(res.dir)} 文件夹拖到扩展页面上` : "",
+      "",
+      "之后打开 https://hackertube.org 就是中文了。以后更新：再运行一次 npx hackertube-zh。",
+      "提示：如果之前从别的文件夹加载过这个扩展（比如源码目录），请先在扩展页移除旧的，否则会重复翻译。");
+  }
+  console.log(lines.filter((l, i) => l !== "" || lines[i - 1] !== "").join("\n"));
+}
+
+if (require.main === module) {
+  try { main(); } catch (e) { console.error(`✖ ${e.message}`); process.exit(1); }
+}
+
+module.exports = { EXTENSION_FILES, DEFAULT_DIR, install, plan, parseArgs, main };

package/content/player-main.js

@@ -0,0 +1,136 @@
+// Runs in the page's own JavaScript world inside the YouTube embed that HackerTube shows (youtube-nocookie.com).
+// YouTube's caption requests are signed by the player (a proof-of-origin token), so instead of fetching captions
+// ourselves we turn captions on through the player's API and copy the caption file the player downloads.
+// Everything found is handed to the extension's isolated script (player.js) with window.postMessage.
+(() => {
+  if (window.__htzMain) return;
+  window.__htzMain = true;
+
+  // only inside HackerTube's embeds; YouTube embeds on other sites are left completely alone
+  const anc = location.ancestorOrigins;
+  const origins = anc ? Array.from({ length: anc.length }, (_, i) => anc[i]) : [document.referrer];
+  const fromHackerTube = origins.some((o) => { try { return /(^|\.)hackertube\.org$/.test(new URL(o).hostname); } catch { return false; } });
+  if (!fromHackerTube) return;
+
+  const post = (type, data = {}) => window.postMessage({ source: "htz-main", type, ...data }, "*");
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const isTimedText = (u) => /\/api\/timedtext\b/.test(u);
+
+  let lastVid = null, lastTitle = "", gotFor = null;
+
+  function onTimedText(url, body) {
+    if (!body || body.length < 20) return;
+    let u;
+    try { u = new URL(url, location.href); } catch { return; }
+    // a tlang= request is YouTube's own machine translation of a track: we translate the source track ourselves
+    if (u.searchParams.get("tlang")) return;
+    const vid = u.searchParams.get("v") || lastVid;
+    gotFor = vid;
+    post("captions", { vid, title: lastTitle, lang: u.searchParams.get("lang") || "", kind: u.searchParams.get("kind") || "", body });
+  }
+
+  // ---------- copy caption downloads (fetch and XHR) ----------
+  const origFetch = window.fetch;
+  window.fetch = function (input) {
+    const url = typeof input === "string" ? input : input instanceof Request ? input.url : String(input);
+    const p = origFetch.apply(this, arguments);
+    if (isTimedText(url)) p.then((r) => r.clone().text()).then((body) => onTimedText(url, body)).catch(() => {});
+    return p;
+  };
+  const xhrOpen = XMLHttpRequest.prototype.open, xhrSend = XMLHttpRequest.prototype.send;
+  XMLHttpRequest.prototype.open = function (method, url) {
+    this.__htzUrl = String(url);
+    return xhrOpen.apply(this, arguments);
+  };
+  XMLHttpRequest.prototype.send = function () {
+    if (this.__htzUrl && isTimedText(this.__htzUrl)) {
+      this.addEventListener("load", () => {
+        try {
+          const rt = this.responseType;
+          const body = rt === "" || rt === "text" ? this.responseText
+            : rt === "json" ? JSON.stringify(this.response)
+            : rt === "arraybuffer" ? new TextDecoder().decode(this.response) : "";
+          onTimedText(this.__htzUrl, body);
+        } catch {}
+      });
+    }
+    return xhrSend.apply(this, arguments);
+  };
+
+  // ---------- turn captions on once the video plays ----------
+  const player = () => document.getElementById("movie_player");
+  const isEnglish = (t) => /^en\b/i.test(t.languageCode || "");
+  const isAsr = (t) => t.kind === "asr" || /^a\./.test(t.vss_id || t.vssId || "");
+  const choose = (list) => list.find((t) => isEnglish(t) && !isAsr(t)) || list.find(isEnglish)
+    || list.find((t) => !isAsr(t)) || list[0];
+
+  function responseTracks(p) {
+    try {
+      const r = p.getPlayerResponse && p.getPlayerResponse();
+      return (r && r.captions && r.captions.playerCaptionsTracklistRenderer
+        && r.captions.playerCaptionsTracklistRenderer.captionTracks) || [];
+    } catch { return []; }
+  }
+
+  async function enableCaptions(p, vid) {
+    if (gotFor === vid) return; // the player already loaded captions (user had CC on)
+    try { p.loadModule("captions"); } catch {}
+    let list = [];
+    for (let i = 0; i < 12 && !list.length; i++) {
+      try { list = p.getOption("captions", "tracklist", { includeAsr: true }) || []; } catch {}
+      if (!list.length) await sleep(300);
+    }
+    // subtitles were switched off while we waited: leave the player alone, and try again if they come back on
+    if (!wanted) { triedFor = null; return; }
+    const tracks = responseTracks(p);
+    if (!list.length && !tracks.length) return post("nocaptions", { vid });
+    if (list.length) { try { p.setOption("captions", "track", choose(list)); turnedOnFor = vid; } catch {} }
+    await sleep(3500);
+    if (gotFor === vid) return;
+    if (!wanted) { triedFor = null; return; }
+    // second route: the track's own URL (works for videos whose captions aren't token-gated)
+    const t = tracks.length && choose(tracks);
+    if (t && t.baseUrl) {
+      try {
+        const url = t.baseUrl + (t.baseUrl.includes("fmt=") ? "" : "&fmt=json3");
+        const body = await (await origFetch(url, { credentials: "include" })).text();
+        onTimedText(url, body);
+      } catch {}
+    }
+    await sleep(3000);
+    if (gotFor !== vid) post("captionsfailed", { vid });
+  }
+
+  // Our subtitles going off also turns off the YouTube captions we switched on to get the caption file, or they
+  // would show in their place. Captions the viewer turned on themselves are theirs and stay.
+  function restoreCaptions() {
+    const p = player();
+    if (!p || turnedOnFor === null || turnedOnFor !== lastVid) return;
+    turnedOnFor = null;
+    try { p.setOption("captions", "track", {}); } catch {}
+  }
+
+  let wanted = false, triedFor = null, turnedOnFor = null;
+  setInterval(() => {
+    const p = player();
+    if (!p || !p.getVideoData) return;
+    let vd = {};
+    try { vd = p.getVideoData() || {}; } catch {}
+    const vid = vd.video_id;
+    if (!vid) return;
+    if (vid !== lastVid) { lastVid = vid; lastTitle = vd.title || ""; post("video", { vid, title: lastTitle }); }
+    else if (!lastTitle && vd.title) { lastTitle = vd.title; post("video", { vid, title: lastTitle }); }
+    let state = -1;
+    try { state = p.getPlayerState(); } catch {}
+    if (wanted && triedFor !== vid && state === 1) { triedFor = vid; enableCaptions(p, vid); }
+  }, 700);
+
+  window.addEventListener("message", (e) => {
+    if (e.source !== window || !e.data || e.data.source !== "htz-iso") return;
+    if (e.data.type !== "config") return;
+    const was = wanted;
+    wanted = !!e.data.enabled;
+    if (was && !wanted) restoreCaptions();
+  });
+  post("hello");
+})();

package/content/player.css

@@ -0,0 +1,42 @@
+/* Subtitles drawn inside YouTube's player element, so they follow it into fullscreen. Sizes scale with the
+   player's height (--htz-h, set by a ResizeObserver) like YouTube's own captions do. */
+.htz-sub {
+  position: absolute; left: 50%; transform: translateX(-50%);
+  bottom: calc(var(--htz-bottom, 8) * 1%);
+  width: 92%; z-index: 38; pointer-events: none;
+  display: none; flex-direction: column; align-items: center; gap: .15em;
+  text-align: center; transition: bottom .2s ease;
+}
+.htz-sub.on { display: flex; }
+/* lift above the control bar while it is visible */
+#movie_player:not(.ytp-autohide) .htz-sub { bottom: calc(var(--htz-bottom, 8) * 1% + 52px); }
+
+/* Default: outlined text with no box, so the picture isn't covered. The layered shadows make a soft dark outline
+   that keeps white text readable on bright frames and slides. */
+.htz-line {
+  display: inline-block; max-width: 100%; padding: 0 .2em; color: #fff; line-height: 1.38; white-space: pre-wrap;
+  font-family: "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", "Source Han Sans SC", Roboto, Arial, sans-serif;
+  text-shadow:
+    0 0 1px rgba(0, 0, 0, .95), 0 0 2px rgba(0, 0, 0, .9),
+    1px 1px 1px rgba(0, 0, 0, .85), -1px -1px 1px rgba(0, 0, 0, .85),
+    1px -1px 1px rgba(0, 0, 0, .85), -1px 1px 1px rgba(0, 0, 0, .85),
+    0 2px 6px rgba(0, 0, 0, .55);
+}
+/* Optional: a compact translucent box, for videos with lots of white slides */
+.htz-style-box .htz-line {
+  padding: .06em .4em; border-radius: 6px; background: rgba(0, 0, 0, .55); text-shadow: 0 1px 2px rgba(0, 0, 0, .6);
+}
+.htz-line:empty { display: none; }
+.htz-zh { font-size: max(15px, calc(var(--htz-h, 360px) * .05 * var(--htz-scale, 1))); font-weight: 500; }
+.htz-en { font-size: max(12px, calc(var(--htz-h, 360px) * .036 * var(--htz-scale, 1))); color: #e8e8e8; }
+
+.htz-hide-native .ytp-caption-window-container { display: none !important; }
+
+.htz-badge {
+  position: absolute; top: 12px; left: 12px; z-index: 61; pointer-events: none;
+  padding: 4px 10px; border-radius: 999px; background: rgba(8, 8, 8, .75); color: #fff;
+  font: 500 13px/1.4 "PingFang SC", "Microsoft YaHei", Roboto, Arial, sans-serif;
+  opacity: 0; transition: opacity .25s;
+}
+.htz-badge.on { opacity: 1; }
+.htz-badge.err { background: rgba(198, 40, 40, .9); }