这个仓库存放可直接安装到 Tampermonkey、Violentmonkey、Greasemonkey 等脚本管理器的浏览器 userscript，也包含少量本地辅助工具。
| 脚本 | 适用页面 | 用途 | 安装入口 |
|---|---|---|---|
| Web Page Assistant / 网页助手 | *://*/* |
管理网页自动刷新，并可按需解除复制、选择、右键菜单、拖拽和离开确认限制。 | dist/web-page-assistant.user.js |
| Codex Quota Compass | https://chatgpt.com/* |
查看 Codex 用量、保存本地快照、远程同步、导出 / 导入用量归档。 | dist/codex-quota-compass.user.js |
| JavDB Recommend Archive / JavDB 佳片推荐 · 历史期数 | https://javdb.com/* 等 |
在 JavDB 导航栏加入「佳片推荐」入口，打开独立页面浏览全部历史期数（每周一/四更新），支持翻期、搜索与全期关键词搜索。 | javdb-recommend.user.js |
| Feishu Preview Image Export | https://mi.feishu.cn/file/* |
从飞书文件预览页导出当前最大可见图片。 | feishu-preview-image-export.user.js |
安装方式：
- 安装一个 userscript 管理器，例如 Tampermonkey、Violentmonkey 或 Greasemonkey。
- 打开上表里的
.user.js文件。 - 在 GitHub 文件页点
Raw，或把脚本内容复制到脚本管理器的新建脚本里。 - 安装前检查脚本管理器提示的
@match和@grant是否符合预期。
更完整的安装列表和迁移说明见 docs/scripts/installable-userscripts.md。
网页助手是一个通用网页辅助脚本；页面右下角常驻浮动控件，有匹配的刷新规则时显示倒计时，未启用刷新时显示可打开设置的圆钮。设置也可经脚本管理器菜单打开，配置支持“当前页面”和“整个站点”两个范围。
主要能力：
- 自动刷新：为当前页面或整个站点设置刷新间隔，支持预设时间和自定义时间。
- 刷新控制：浮动控件显示倒计时，可暂停、继续或删除当前刷新规则。
- 网页限制解除：可按需允许文本选择、复制 / 剪切、右键菜单、拖拽，并可抑制离开页面确认。
- 持久设置：优先使用 userscript manager storage；运行环境不支持时回退到页面
localStorage。
使用注意：
- 脚本运行范围是
*://*/*，安装时会看到较宽的授权提示；不需要时可以在脚本管理器里禁用。 - “限制解除”只影响浏览器页面事件，不绕过登录、权限、付费墙或服务端限制。
- 安装入口是
dist/下打包好的单文件；src/目录下的*.entry.ts与*.lib.ts(x)是 TypeScript 模块源码，不能直接安装。
Codex Quota Compass 运行在 chatgpt.com，通过悬浮按钮或 userscript 菜单命令读取当前 Codex 用量并保存历史。
它会把每次成功运行的结果保存为一条 Quota Snapshot，并维护本地 Snapshot Archive。面板还会展示按模型汇总、可用重置券，以及由 Cost Ledger 派生的日 / 周 / 月 / 全量已结算消耗视图。脚本管理器的 WebDAV 同步只能保证脚本代码和管理器设置同步，不作为 Codex 用量历史的可靠跨设备通道。
跨设备自动同步走 GitHub Gist：用户配置自己的 GitHub token 后，脚本会在用户自己的 GitHub 账号里查找或创建一个 secret gist，并把 Snapshot Archive 保存为 JSON 文件。不同设备使用同一个 GitHub 账号和 token 后，会按 Snapshot ID 合并归档。你也可以从面板导出完整归档，或通过 userscript 菜单导出 / 导入 JSON，作为手动备份或迁移路径。
注意事项：
- 归档里保存的是经过整理的用量信息，不保存 Cookie、Token 或原始私有接口响应。
- 导入是 merge 语义，会跳过重复快照，不会覆盖整个本地归档。
- GitHub token 保存在脚本管理器存储中，不写入仓库；建议使用 fine-grained token，并只授予 Gists read/write 权限。
- Gist 使用
public: false创建，是 unlisted secret gist，不应保存 Cookie、Token 或其他真正敏感信息。 - 本地归档优先保存在 GM storage，同时在当前页面的
localStorage保留一份非敏感镜像；读取时会合并两端，GM storage 不可用时则直接使用该镜像。Gist 同步设置和 token 只保存在 GM storage 中，不会写入页面存储；仅有localStorage时不能启用 Gist 同步。
Gist 同步设置说明见 docs/scripts/codex-quota-gist-sync.md。
领域词汇见 GLOSSARY.md。
Feishu Preview Image Export 运行在飞书文件预览页，用 userscript 菜单命令从当前页面找最大的可见图片并下载。它适合处理飞书文件页里“预览图可见但原图入口不好找”的场景。
本仓库还提供两个本地浏览器工具：
scripts/browser-tools/login-qr.mjs：默认适配小米飞书，也可配置其他网站；导出登录二维码并保存浏览器登录态。scripts/browser-tools/export-image.mjs：使用已有登录态打开飞书文件页并导出当前最大可见图片。
使用说明见 docs/scripts/feishu-tools.md。
安装入口为 dist/javdb-recommend.user.js；旧 src 安装地址保留逐字节相同的完整 Bridge File。源码由 Entry、数据、请求、Period Section、Site Chrome 及展示 Lib Module 组成。
JavDB Recommend Archive 运行在 JavDB 官网（javdb.com 及 javdb575.com、javdb.today 等镜像域名），在顶部导航栏加入「佳片推荐」入口，点击打开独立页面 /recommend-archive 浏览「佳片推荐」栏目的全部历史期数。归档页从官网首页动态发现样式表与导航；资源在 12 秒内全部加载并通过基础计算样式检查后才启用官网外观，否则使用完整内置样式：
- 瀑布流浏览：从上次浏览的期数开始按期流式渲染，期数选择框同步显示恢复的期数；可选择最新一期直接跳转。滚动到底自动加载更早的期数；相邻未加载期会沿当前流追加，远距离或反向跳转则直接以目标期重建流，不再请求中间期，并记住浏览位置。刷新期数与清缓存均保留浏览位置。
- 影片列表：横版封面完整显示（不裁切），卡片展示番号、评分与发售日期，点击直达官网影片详情页。
- 多脚本适配：若其他 JavDB 增强脚本接管影片列表，后续未接管列表会同步其实际列数、间距和封面模式；列表后来被接管时会释放本脚本复制的 inline 值。兼容范围按 Tampermonkey 与
JAV老司机-新2.8.4.8 的公开 DOM 表现核对，不依赖第三方内部函数。 - 本地缓存：期数目录缓存 6 小时，过期后从最新页读取到首个已知期即停止并复用历史尾部，每 30 天做一次完整校验；最新一期详情缓存 2 小时，历史详情缓存 30 天，逐期存入页面 IndexedDB，并最多保留最近使用的 48 期。全期搜索使用独立的紧凑索引，不挤占浏览缓存，首次补全后同一目录可纯本地搜索。
- 性能与韧性：搜索结果按期增量追加，屏外期区块延迟渲染，内存详情按最近使用保留 24 期（分代淘汰，最多暂留 48 期）；详情请求按期单飞并按消费者取消，超时或可重试错误最多尝试 3 次。工具栏可手动刷新期数或清除本脚本缓存。
- 搜索：已加载内容即时过滤，以及全期关键词搜索（逐期扫描、可随时停止）。
- 数据来自官网自身的
/api/v1/movies/recommend_periods与/api/v1/movies/recommend接口（同域请求，无需额外授权）；封面统一改写为官网页面使用的c0.jdbstatic.com图床（接口默认返回 App 图床，网页端常被拦截）。
脚本无需登录即可使用；@grant none，不使用任何脚本管理器特权 API，以页面 localStorage 保存上次浏览期数、期数目录与搜索索引，以页面 IndexedDB 保存期详情缓存，均为非敏感数据；旧版存于 localStorage 的详情缓存会在启动时清除。已配置 @downloadURL / @updateURL，推送新版本后脚本管理器会自动检查更新。
.
├── dist/ # 打包产物：多模块脚本的单文件安装入口（构建生成并提交）
├── docs/ # 脚本说明、运行手册和项目约定
├── scripts/ # 本地辅助脚本与构建脚本
├── src/userscripts/ # userscript 源码（ESM entry + lib 模块，或单文件脚本）
└── test/ # Node 测试
日常开发与 CI 使用 .node-version 指定的 Node.js 24 LTS。最低兼容版本为 Node.js 22.18
（scripts/browser-tools/export-image.mjs 直接导入 src/ 下的 .ts 模块，依赖 Node 默认开启的类型擦除）。
npm ci
npm run test:prepare # 项目锁定的 Playwright CLI 安装对应 Chromium 和系统依赖
npm run verify # 一次构建、产物一致性、metadata lint、tsc 类型检查、ESLint、全部测试npm run lint 与 npm test 可独立运行，会先自动构建；npm run lint 依次跑 metadata 检查、tsc（strict，只做类型检查）与 ESLint，单独类型检查用 npm run typecheck。
src/ 源码是 TypeScript：类型由 esbuild 擦除，影响产出的编译选项固定在 scripts/lib/jsx-build-options.mjs，tsconfig.json 只管类型检查，收紧类型不会改变安装产物。完整入口要求所有测试通过，
并核对五项浏览器验收的稳定名称和文件；缺失、跳过或过滤掉必需用例都会失败。
项目在 package.json devDependencies 精确锁定 Playwright，测试脚本从那里读取版本；测试只加载本项目依赖和该版本的默认 Chromium，
缺依赖或浏览器直接报错。日常 browser-tools 的兼容加载器优先使用项目依赖，其次读取本机 npm 缓存。
聚焦调试使用 node --import ./scripts/jsx-loader.mjs --test test/<name>.test.mjs（加载器让测试直接导入 .ts/.tsx 源码）；它不代表完整验收。
原生 JSON 报告、准备时间和人工验收边界见 测试说明。
提交前运行 scripts/format.sh：prettier（版本锁在 package.json devDependencies）重排
JS/TS、Markdown、YAML 与 JSON，shfmt（脚本内固定版本与 sha256）重排 Shell；
scripts/format.sh --check 只检查，npm run verify 的检查阶段会运行它，格式不一致即失败。dist/、src/ 下与 dist 逐字节相同的桥接文件、
package-lock.json 是生成物或锁文件，不参与重排。
纯格式重排提交登记在 .git-blame-ignore-revs，本地可用
git config blame.ignoreRevsFile .git-blame-ignore-revs 让 blame 跳过它们。
脚本的 raw @downloadURL / @updateURL 直接读取 master，因此合并带新
@version 的提交就是外部发布。修改版本前先运行
git fetch origin master 刷新基线，再运行
node scripts/version-plan.mjs plan --target '<安装身份>=<目标版本>'（多个目标重复传参），
在不写文件的情况下查看全部可安装脚本从 origin/master 基线到目标版本的完整计划。
目标版本按 PRODUCT.md「Version Policy」：默认 patch；minor（有用户能感知的新能力）
与 major（含 0.x→1.0）须先经维护者确认。改 metadata、
重建后用全局 land --no-recut 命令推候选。
CI 在候选上按当时的 origin/master 基线校验版本计划；master 在合入前前进时，
land --no-recut 停止。先变基或更新候选并重新验证，再通过同一 SHA 的提交门禁后合入。
首次发版、基线未知、脚本集合不完整、孤立 dist、降级或生成副本版本不一致
都会暂停；其余递增直接通过。
发版候选在任务分支上递增版本并重建产物，然后用 land --no-recut 推成
candidate/** 分支：CI 在候选上运行，ci-ok 通过后
land --no-recut 把 master 快进到该同一提交。master 的 ruleset 要求每个提交都带绿色
ci-ok 检查并禁止非快进，因此没有「先推再看 CI」的路径，也无需 pull request。
已进入 master 的版本视为不可变，后续修复使用下一个 patch。若维护者明确选择
暂不发版，可以不递增版本，但已安装脚本也不会自动获得这次变更。
新建脚本可从 src/userscripts/example/example.user.js 开始，并参考 docs/script-template.md。有注入 UI 的脚本先看 DESIGN.md。
- PRODUCT.md：产品上下文、用户、边界、数据原则和版本策略。
- DESIGN.md：注入式 userscript UI 的设计上下文和组件规则。
- docs/index.md：仓库文档地图和职责边界。
- docs/adr/index.md：架构决策记录（打包与桥接、PR 发布门、存储策略、Gist 同步、入口文件不入库）。
- GLOSSARY.md：四个脚本与构建/发布机制的领域术语表。
- docs/scripts/installable-userscripts.md：可安装 userscript 列表和迁移说明。
- docs/scripts/codex-quota-gist-sync.md：Codex Quota Compass GitHub Gist 同步说明。
- docs/scripts/feishu-tools.md：二维码登录态捕获、飞书工具和飞书主图 userscript 说明。
- docs/script-template.md：新建或迁移 userscript 时需要维护的 metadata。
- GLOSSARY.md：稳定领域词汇表。