Userscript Development and Deployment Workflow Guide

Userscript 是指一种运行在浏览器环境中的用户脚本（通常通过 Tampermonkey 等扩展加载），能够通过操作 DOM 和注入逻辑来直接修改网页的功能或外观。因此，我们可以自主开发符合个人使用习惯的工具来实现特定网页的功能增强、数据提取或排版优化。下面是从本地开发到自动化分发的工作流程。

一、在 GitHub 上创建项目

首先，我们需要在 GitHub 上创建一个仓库来存放项目文件。

标准项目结构如下：

My-UserScript-Project/
├── src/
│   └── 脚本名称.user.js
├── README.md
└── LICENSE

GitHub 仓库不允许直接创建空文件夹，因此，可以在创建新文件时间接创建。例如，如果想在 test 文件夹下创建 test.js 文件，就可以输入 test/test.user.js，输入的 test/ 会自动变成 test.user.js 的父文件夹。

二、配置脚本 Metadata

在本地新建并打开 脚本名称.user.js，在编写脚本逻辑之前，需要先配置脚本头部的 Metadata 部分。脚本管理器（如 Tampermonkey）和脚本分发平台（如 Greasy Fork）需要靠脚本的 Metadata 来识别脚本信息。

以下是一个标准的脚本头部配置模板（以 Gemini Chat Exporter 为例）：

// ==UserScript==
// @name                 Gemini Chat Exporter
// @name:zh-CN           Gemini 对话导出工具
// @description          Export Gemini conversations as Markdown with accurate formatting and timestamps.
// @description:zh-CN    深度优化排版，高保真还原 Gemini 聊天的标题、代码块、表格和公式。
// @namespace            https://github.com/AstridStark25963/gemini-chat-exporter
// @version              1.0.0
// @author               AstridStark25963
// @license              MIT
// @icon                 data:image/svg+xml;base64,PHN2ZyB4bWx... (图片的 base64 编码)
// @include              *://gemini.google.com/*
// @run-at               document-idle
// @grant                GM_addStyle
// @downloadURL          https://raw.githubusercontent.com/AstridStark25963/gemini-chat-exporter/main/src/gemini-chat-exporter.user.js
// @updateURL            https://raw.githubusercontent.com/AstridStark25963/gemini-chat-exporter/main/src/gemini-chat-exporter.user.js
// ==/UserScript==

以下是例子中用到的参数解析：

参数	说明	用法分析
`@name`	脚本名称。显示在脚本管理列表中的名字。	默认英文名 `Gemini Chat Exporter`。
`@name:zh-CN`	本地化名称。针对特定语言环境（这里是简体中文）显示的名称。	当用户浏览器语言为中文时，显示为 `Gemini 对话导出工具`，对国内用户更友好。
`@description`	脚本描述。简短介绍脚本的功能。	英文描述。
`@description:zh-CN`	本地化描述。	中文描述。
`@namespace`	命名空间。用于区分同名脚本。如果两个脚本都叫 “Test”，但 namespace 不同，管理器会视为两个不同的脚本。	推荐使用 GitHub 仓库地址，这是最规范的写法，保证了唯一性。
`@version`	版本号。自动更新的核心依据。	`1.0.0`。每次发布新代码必须增加此数字，否则用户无法接收更新。
`@author`	作者。	作者 ID。
`@license`	许可证。	`MIT`。声明代码开源，允许他人修改和分发（在 Greasy Fork 上必填）。
`@icon`	图标。脚本列表左侧显示的小图片。	推荐使用 Base64 编码。优势：不依赖外部网络，图片永远不会挂，加载极快。
`@include`	匹配规则。指定脚本在哪些网址上运行。	`://gemini.google.com/`。表示匹配 HTTP 和 HTTPS 协议下的 Gemini 所有子路径。
`@run-at`	运行通过时机。决定脚本何时注入页面。	`document-idle`：在页面加载完成且空闲时运行。这对于 Gemini 这种动态加载内容的网站最安全，避免脚本跑太快找不到元素。
`@grant`	权限申请。脚本需要调用的特殊 API。	`GM_addStyle`：申请向页面注入 CSS 样式的权限（你用来画那个蓝色圆形按钮）。
`@downloadURL`	下载地址。管理器检测到新版本时，去哪里下载 `.user.js` 文件。	指向 GitHub Raw 直链。
`@updateURL`	更新检查地址。管理器定期去哪里检查 `@version` 是否变化。	指向 GitHub Raw 直链（通常与 `@downloadURL` 一致）。

其中，GitHub Raw 直链的获取可以通过在 GitHub 仓库对应文件页面点击 Raw 按钮得到。

通过此方法获取的链接为 https://github.com/用户名/仓库名/raw/refs/heads/main/src/脚本名.user.js 格式，这是 GitHub 网页端的重定向链接，但脚本管理器和脚本分发平台的规范更偏向于使用直接的 CDN 链接，因此需要改成 https://raw.githubusercontent.com/用户名/仓库名/main/src/脚本名.user.js 格式。

对于其他示例中没有用到的参数以及其他用法，可以在 Tampermonkey 文档中找到更详细的解释。

在 Metadata 配置完成后，即可开始进行脚本的编写和测试工作。脚本编写完成后，即可上传到 GitHub 仓库。

三、在 Greasy Fork 发布脚本

首先，由于脚本文件已经被存储在 GitHub 仓库中，我们无需将脚本代码复制粘贴到 Greasy Fork，只需访问 Greasy Fork 的导入脚本页面将脚本文件的 GitHub Raw 直链粘贴进去即可。

完成脚本导入后，可以通过设置 webhook 实现脚本的自动抓取和更新。

默认情况下，Greasy Fork 的自动同步是被动的（可能几小时才抓取一次）。为了实现“推送到 GitHub，Greasy Fork 立刻更新”，需要进行 webhook 的配置。

打开 GitHub 仓库的 Settings - Webhooks页面，点击 Add Webhook，并根据 Greasy Fork 设置 webhook 页面给出的配置填写所需参数。

配置成功后，GitHub 页面会向 Greasy Fork 发送一个 ping payload，如果双方握手成功会在配置好的 webhook 前打一个绿色对勾。

如果出现以下提示：Okay, that hook was successfully created. We sent a ping payload to test it out! Read more about it at https://docs.github.com/webhooks/#ping-event. 也说明双方握手成功。

如果在设置 GitHub 仓库的 webhook 时选择了 “Just the push event.” 选项，每一次对仓库内容的修改都会触发 Greasy Fork 的同步更新，因此，为了测试是否真正实现了自动化更新，可以尝试修改项目仓库的 README 文件并推送到仓库。如果 GitHub 的 Webhooks 页面显示✅，且 Greasy Fork 脚本页面的“最后更新于”变成了“现在”，则说明自动化更新流程已经搭建完成。

四、注意事项

在每次更新脚本时，应注意更新脚本文件 Metadata 部分的 @version 字段。如果只更新代码但不更改 @version 字段，Greasy Fork 会抓取到新代码，但不会提示用户更新。

此外，在 Greasy Fork 的脚本管理页面，会给出一些有关脚本的建议，如图所示。

根据 Greasy Fork 的建议进行脚本配置和详情页面的修改，能够提高脚本质量，使得脚本内容的编写更加规范。