loon-plugin

Files (7)

• SKILL.md
• examples.md · references/
• rewrite-legacy.md · references/
• rewrite-v2.md · references/
• rules.md · references/
• script-api.md · references/
• script-types.md · references/

SKILL.md (first lines)

# Loon 插件开发技能

## 何时使用

- 编写或修改 Loon 插件（`.plugin` 文件）
- 编写 Loon 复写（Rewrite）规则，尤其是新版 `if ... then ...` 语法
- 编写 Loon 脚本（去广告、签到、解锁、定时任务）
- 排查插件不生效、参数读不到、Rewrite 报错、MitM 未解密
- 把旧语法插件迁移到新语法

## 核心原则

1. **先确认目标 Loon 版本**。本技能覆盖的多数能力有明确的版本门槛，写错 `#!loon_version` 会导致用户端直接不可用。
2. **优先使用新版 Rewrite 语法**。旧语法仅作输入兼容，Loon 的生成、保存和配置展示统一输出新语法。
3. **不要凭记忆写 Action 名和参数顺序**。Action 使用严格的位置参数，写错会在加载时被拒绝整条规则。动手前查 `references/rewrite-v2.md`。
4. **HTTPS 必须配 MitM**。Rewrite 和 http 脚本只对 HTTP 以及经 MitM 解密的 HTTPS 生效，漏写 `[Mitm] hostname` 是最常见的「不生效」原因。

## 插件骨架

```
#!name = 示例插件
#!desc = 展示插件信息和用户参数
#!author = Loon
#!homepage = https://example.com
#!icon = https://example.com/icon.png
#!system = iOS,iPadOS,tvOS,macOS
#!system_version = 15
#!loon_version = 3.5.1(978)
#!tag = 示例,工具
#!type = normal

[Argument]
name = input,"Loon",tag=名称,desc=输入一个名称
region = select,"CN","US","JP",tag=地区
enabled = switch,true,tag=启用

[General]
bypass-tun =
skip-proxy =
real-ip =
dns-server =

[Rule]

[Rewrite]

[Host]

[Script]
http-response ^https?:\/\/example\.com\/conf\/server-mapping script-path=remove_ads.js,requires-body=true,tag=移除广告,argument=[{name},{region},{enabled}]

[Mitm]
hostname = example.com
```

模块都是可选的，按需保留。写插件时不要保留空的 `[General]` 占位键（`bypass-tun =` 等），会覆盖用户的通用配置。

## 元信息字段

| 字段 | 说明 |
|---|---|
| `#!name` | 插件名称 |
| `#!desc` | 功能说明 |
| `#!author` | 作者 |
| `#!homepage` | 主页地址 |
| `#!icon` | 图标地址 |
| `#!system` | 支持的系统，不区分大小写；未填写表示全部支持 |
| `#!system_version` | 最低系统版本，如 `15.0` |
| `#!loon_version` | 最低 Loon 版本，如 `3.5.1(978)` |
| `#!tag` | 分类标签 |
| `#!type` | 插件类型 |

`#!type` 从 Loon 3.5.0 (969) 起支持：

- `normal`：普通插件
- `parser`：资源解析器，可在节点、规则和配置订阅页面中选择

## [Argument] 用户参数

需要 Build 733+。Loon 会据此自动生成设置界面。

```
参数名 = 控件类型,默认值或可选值,tag=标题,desc=说明
```

| 控件 | 说明 | 支持类型 | 默认类型 |
|---|---|---|---|
| `input` | 文本输入；默认值可省略 | String、Number | String |
| `select` | 单选列表；第一个值为默认值 | String、Number | String |
| `switch` | 开关；默认值为 `false` | Boolean | Boolean |

需要数字类型时显式声明 `type=number`：

```
price = input,9.99,type=number,tag=价格
level = select,1,2,3,type=number,tag=等级
```

未声明 `type` 的旧插件保持原行为（`input`/`select` 按 String，`switch` 按 Boolean）。

### 引用语法在两处不同 —— 最高频错误

| 使用位置 | 写法 | 示例 |
|---|---|---|
| `[Script]` 的 `argument` | `{参数名}` | `argument=[{name},{region}]` |
| `[Script]` 的其他字段 | `{参数名}` | `enable={enabled}`、`cron {cronExpression}` |
| 新版 `[Rewrite]` | `${参数名}` | `${region}`、`${price}` |

脚本内通过 `$argument.name` 读取。`switch` 参数可直接控制脚本开关：`enable={enabled}`。

本地 Rewrite 没有 `[Argument]` 来源，本地编辑页只能用内置变量和当前 Rewrite 的正则捕获。

## 插件内规则的策略限制 —— 第二高频错误

插件 `[Rule]` 里**只能**使用这三类策略：

- `DIRECT`
- `REJECT` 系列
- `PROXY`

From cikichen/skills, MIT.

More from cikichen/skills