元数据块

2. 元数据块: 脚本的“身份证”

您的 bundle.js 文件必须在文件顶部包含一个元数据块。这是平台识别您脚本能力和意图的唯一方式。

2.1 格式

// ==AnbaoScript==
// @id          com.bilibili.video-uploader
// @name        Bilibili 视频发布助手
// @version     1.0.1
// @author      Anbao Team
// @description 自动将本地视频发布到 Bilibili。
// @tags        bilibili, video, uploader, automation
// @keywords    bilibili
// @engine      patchright
// @launchOptions { "headless": false, "slowMo": 50 }
//
// @schema
// {
//   "title": "视频发布脚本参数",
//   "type": "object",
//   "properties": {
//     "video_title": {
//       "type": "string",
//       "title": "1. 视频标题"
//     },
//     "video_file_path": {
//       "type": "string",
//       "format": "file",
//       "title": "2. 本地视频文件"
//     }
// }
// ==/AnbaoScript==

// ... (esbuild 打包后的代码) ...

2.2 支持的标签

@id (必需): 脚本的全局唯一标识符。这是聚合所有版本的唯一依据。
- 格式: 强烈推荐使用反向域名 (reverse-domain name) 格式，例如 com.author.script-name，以从根本上避免冲突。
- 不变性: 一旦设定，一个逻辑脚本的 @id 永远不应改变。
@name (必需): 脚本的名称。
@version (必需): 脚本的版本号, 遵循 SemVer。
@description (可选): 脚本的简短描述。
@author (必需): 脚本的作者或团队名称。
@tags (可选): 用于市场展示和搜索的标签。这是一个逗号分隔的列表，用于用户发现脚本。
@keywords (必需): 用于平台内部凭证匹配的功能性关键词。这是一个逗号分隔的列表，用于在创建调度任务时，智能过滤出兼容的凭证，防止误操作。
- 核心思想: 关键词用于简单的包含匹配。例如，关键词 douyin 会匹配 base_url 为 https://www.douyin.com 的平台。
- 特殊通配符: 你可以使用 * 作为通配符，表示该脚本与所有平台兼容。
- 最佳实践: 使用平台域名中最核心、最不易变的部分作为关键词，例如 douyin, bilibili, zhihu。
- 示例:
  - // @keywords douyin, bilibili
  - // @keywords *
@engine (可选): 选择用于执行脚本的浏览器自动化引擎。这对于需要增强反检测能力的场景非常有用。
- 可选值:
  - playwright: (默认值) 使用标准的 Playwright 引擎。
  - patchright: 使用 patchright 引擎，它是一个带有反检测补丁的 Playwright 分支。
- 示例: // @engine patchright
@launchOptions (可选): 定义浏览器启动时使用的 Playwright LaunchOptions。值必须是一个单行的、合法的 JSON 对象。这允许开发者精细控制浏览器行为。
- 核心功能:
  - 调试: 通过设置 "headless": false，可以在“有头”模式下运行脚本，便于观察和调试。
  - 切换浏览器: 通过设置 "channel": "chrome"，可以指示平台使用系统上安装的 Google Chrome 浏览器来运行此脚本，而不是使用内置的、独立的 Chromium。这对于需要特定 Chrome 功能或扩展的场景非常有用。
- 优先级: 当 @launchOptions 中包含 "channel": "chrome" 时，平台将优先使用系统 Chrome。如果未指定 channel，则默认使用内置的、独立的 Chromium 浏览器。
- 示例:
  - 调试模式: // @launchOptions { "headless": false, "slowMo": 100 }
  - 使用系统 Chrome: // @launchOptions { "channel": "chrome" }
- 重要提示：参数覆盖规则
  - 系统会使用您在 @launchOptions 中提供的 JSON 对象来覆盖系统预设的默认启动参数。
  - 这对于 headless, slowMo 等普通参数是安全的。
  - 但是，对于 args (启动参数数组) 这个特殊的键，您的设置会完全替换系统预设的数组，而不是合并。
  - 最佳实践：除非您完全清楚所有必需的启动参数，否则请勿在您的 @launchOptions 中包含 args 字段。如果必须自定义 args，您必须在您的设置中手动包含所有系统预设的默认参数，以确保功能正常。当前系统预设的 args 为：['--start-maximized', '--no-sandbox', '--disable-setuid-sandbox']。
@schema (可选): 标记一个多行块的开始，其内容为一个 JSON 对象，用于定义脚本的输入参数。平台将根据它为用户动态生成输入表单。请注意，@schema 标签和 JSON 的 { 之间需要换行。

2.3 `@keywords` vs `@tags` (重要区别)

@keywords (功能性): 给机器读的。它的唯一用途是在创建调度任务时，将脚本与具有匹配 base_url 的平台凭证进行关联。例如，// @keywords bilibili 会匹配所有 base_url 包含 bilibili 的平台。
@tags (展示性): 给人读的。它的唯一用途是在脚本市场中作为可点击的标签，方便用户进行分类浏览和搜索。

元数据块

2. 元数据块: 脚本的“身份证”

2.1 格式

2.2 支持的标签

2.3 @keywords vs @tags (重要区别)

2.3 `@keywords` vs `@tags` (重要区别)