add description in 'README'.

fix a little bug.
2025-10-26 10:52:21 +00:00 · 2019-11-18 21:02:20 +08:00
parent a68363e108
commit 6217918b9b
7 changed files with 1646 additions and 5 deletions
--- a/README-cn.md
+++ b/README-cn.md
@@ -0,0 +1,268 @@
+# subconverter
+
+在各种订阅格式之间进行转换的实用程序.
+
+[![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)
+
+- [subconverter](#subconverter)
+  - [支持类型](#支持类型)
+  - [用法](#用法)
+      - [旧接口](#旧接口)
+  - [**推荐阅读**](#推荐阅读)
+  - [pref.ini](#prefini)
+    - [common](#common)
+      - [api_mode](#api_mode)
+      - [default_url](#default_url)
+      - [exclude_remarks](#exclude_remarks)
+      - [include_remarks](#include_remarks)
+      - [clash_rule_base](#clash_rule_base)
+      - [surge_rule_base](#surge_rule_base)
+      - [surfboard_rule_base](#surfboard_rule_base)
+      - [rename_node](#rename_node)
+    - [managed_config](#managed_config)
+    - [emojis](#emojis)
+    - [ruleset](#ruleset)
+    - [clash_proxy_group](#clash_proxy_group)
+    - [server](#server)
+      - [listen](#listen)
+      - [port](#port)
+    - [advanced](#advanced)
+  - [gist](#gist)
+
+
+
+## 支持类型
+
+| 类型         | 作为源类型 | 作为目标类型 | 参数        |
+| ------------ | :--------: | :----------: | ----------- |
+| clash        |     ✔      |      ✔       | clash       |
+| clashr       |     ✔      |      ✔       | clashr      |
+| surge2       |     ✔      |      ✔       | surge?ver=2 |
+| surge3       |     ✔      |      ✔       | surge?ver=3 |
+| surge4       |     ✔      |      ✔       | surge?ver=4 |
+| quantumult   |     ✔      |      ✔       | quan        |
+| quantumult X |     ✔      |      ✔       | quanx       |
+| surfboard    |     ✔      |      ✔       | surfboard   |
+| ss           |     ✔      |      ✔       | ss          |
+| ssr          |     ✔      |      ✔       | ssr         |
+| ssd          |     ✔      |      ✔       | ssd         |
+| v2ray        |     ✔      |      ✔       | v2ray       |
+
+
+
+## 用法
+
+```
+http://127.0.0.1:25500/sub?target=clash&url=%URL_ENCODED_LINKS%
+
+http://127.0.0.1:25500/sub?target=surge&ver=4&url=%URL_ENCODED_LINKS%
+
+http://127.0.0.1:25500/sub?target=v2ray&url=%URL_ENCODED_LINKS%
+```
+
+#### 旧接口
+
+```
+http://127.0.0.1:25500/clash?url=%URL_ENCODED_LINKS%
+```
+
+如果你有多个订阅, 在url encode之前使用 '|' 来分隔链接. <br>
+
+e.g. <br>
+> 我有以下两个订阅: <br>
+`https://dler.cloud/subscribe/ABCDE?clash=vmess`
+`https://rich.cloud/subscribe/ABCDE?clash=vmess`
+<br> <br>
+使用'|'分隔: <br>
+`https://dler.cloud/subscribe/ABCDE?clash=vmess|https://rich.cloud/subscribe/ABCDE?clash=vmess`
+<br> <br>
+url encode后: <br>
+`https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
+<br> <br>
+添加到链接后面: <br>
+`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
+<br> <br>
+&nbsp;&nbsp;&#127830; 食用 &#127830;
+<br> <br>
+
+
+- 想学更多姿势? 来瞅瞅[pref.ini](./pref.ini).
+
+
+
+## **推荐阅读**
+
+> - [&#128220; 正则表达式 &#128220;](https://zh.wikipedia.org/zh-hans/%E6%AD%A3%E5%88%99%E8%A1%A8%E8%BE%BE%E5%BC%8F)
+> - [&#128221; yaml语法介绍 &#128221;](https://zh.wikipedia.org/wiki/YAML#%E8%AA%9E%E6%B3%95)
+> - [&#10068; 提问的智慧 &#10068;](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)
+
+
+
+## pref.ini
+
+### common
+
+#### api_mode
+
+> API模式，设置为true以防止直接加载本地订阅或直接提供本地文件.
+
+当值为`false`时, 每次更新配置都会读取`pref.ini`, 为`true`时则仅启动时读取.
+
+
+
+#### default_url
+
+> 无url参数时默认链接. 如果有多个链接, 使用 "|" 分隔, 支持`文件`/`url`.
+
+这种用法:
+```ini
+default_url=https://dler.cloud/subscribe/ABCDE?clash=vmess
+```
+
+`http://127.0.0.1:25500/clash`
+
+相当于:
+<br>
+`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
+
+
+
+#### exclude_remarks
+
+> 排除匹配到的节点, 支持正则.
+
+e.g.
+```ini
+exclude_remarks=(流量|时间|官网|产品)
+```
+
+
+
+#### include_remarks
+
+> 仅保留匹配到的节点, 支持正则.
+
+e.g.
+```ini
+include_remarks=(?<=美).*(BGP|GIA|IPLC)
+```
+
+
+
+#### clash_rule_base
+
+> 生成的clash配置文件基础. 支持`文件`/`url`.
+
+e.g.
+```ini
+clash_rule_base=clash.yaml
+
+clash_rule_base=https://raw.githubusercontent.com/ConnersHua/Profiles/master/Clash/Pro.yaml
+```
+
+
+
+#### surge_rule_base
+
+> 生成的surge配置文件基础. 用法同上.
+
+
+
+#### surfboard_rule_base
+
+> 生成的surfboard配置文件基础. 用法同上.
+
+
+
+#### rename_node
+
+> 重命名节点, 支持正则.
+
+e.g.
+```ini
+rename_node=中国@中
+rename_node=深圳@深
+```
+
+
+
+### managed_config
+
+> 将'＃！MANAGED-CONFIG'信息附加到Surge配置.
+
+
+
+### emojis
+
+> 添加识别到的第一个国家国旗在节点名称前, 支持正则.
+
+e.g.
+```ini
+rule=(流量|时间|应急),⌛time
+rule=(美|美国|United States),🇺🇸
+```
+
+
+
+### ruleset
+
+> 规则片段.
+
+e.g.
+<img src="./doc/imgs/Snipaste_2019-11-18_14-11-52.png">
+
+```ini
+ruleset=🌹 YouTube,https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Media/YouTube.list
+```
+
+效果图:
+
+<img src="./doc/imgs/Snipaste_2019-11-18_14-15-54.png">
+
+
+
+### clash_proxy_group
+
+> clash的策略组, 可用正则来筛选节点.
+
+e.g.
+```ini
+custom_proxy_group=🇺🇸US`url-test`(美|美国|United States)`http://www.gstatic.com/generate_204`300
+```
+
+效果图:
+
+<img src="./doc/imgs/Snipaste_2019-11-18_14-47-30.png">
+
+
+ssr/v2订阅默认没有组名, 可以使用这个方法来添加组名.
+
+```ini
+custom_proxy_group=g1`select`!!GROUPID=0
+custom_proxy_group=g2`select`!!GROUPID=1
+custom_proxy_group=v2ray`select`!!GROUP=V2RayProvider
+```
+
+
+### server
+
+#### listen
+
+> 绑定到Web服务器的地址, 将地址设为0.0.0.0, 则局域网内设备均可使用.
+
+#### port
+
+> 绑定到Web服务器地址的端口.
+
+
+### advanced
+
+> 无需描述.
+
+
+
+## gist
+
+> 自动上传gist.
+
+在[gistconf.ini](./gistconf.ini)中添加personal access token, 在链接后加上`upload=true`就会在更新好后自动上传gist.
--- a/README.md
+++ b/README.md
@@ -1,11 +1,270 @@
 # subconverter
-Utility to convert between various subscription format
+
+Utility to convert between various subscription format.
+
 [![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)

+[中文文档](./README-cn.md)
+
+- [subconverter](#subconverter)
+  - [Support Type](#support-type)
+  - [Usage](#usage)
+      - [Old interface](#old-interface)
+  - [**Recommended reading**](#recommended-reading)
+  - [pref.ini](#prefini)
+    - [common](#common)
+      - [api_mode](#api_mode)
+      - [default_url](#default_url)
+      - [exclud_remarks](#exclud_remarks)
+      - [include_remarks](#include_remarks)
+      - [clash_rule_base](#clash_rule_base)
+      - [surge_rule_base](#surge_rule_base)
+      - [surfboard_rule_base](#surfboard_rule_base)
+      - [rename_node](#rename_node)
+    - [managed_config](#managed_config)
+    - [emojis](#emojis)
+    - [ruleset](#ruleset)
+    - [clash_proxy_group](#clash_proxy_group)
+    - [server](#server)
+      - [listen](#listen)
+      - [port](#port)
+    - [advanced](#advanced)
+  - [gist](#gist)
+
+
+
+## Support Type
+
+| Type         | As Source Type | As Target Type | Parameters  |
+| ------------ | :------------: | :------------: | ----------- |
+| clash        |       ✔        |       ✔        | clash       |
+| clashr       |       ✔        |       ✔        | clashr      |
+| surge2       |       ✔        |       ✔        | surge?ver=2 |
+| surge3       |       ✔        |       ✔        | surge?ver=3 |
+| surge4       |       ✔        |       ✔        | surge?ver=4 |
+| quantumult   |       ✔        |       ✔        | quan        |
+| quantumult X |       ✔        |       ✔        | quanx       |
+| surfboard    |       ✔        |       ✔        | surfboard   |
+| ss           |       ✔        |       ✔        | ss          |
+| ssr          |       ✔        |       ✔        | ssr         |
+| ssd          |       ✔        |       ✔        | ssd         |
+| v2ray        |       ✔        |       ✔        | v2ray       |
+
+
+
 ## Usage
+
+```
+http://127.0.0.1:25500/sub?target=clash&url=%URL_ENCODED_LINKS%
+
+http://127.0.0.1:25500/sub?target=surge&ver=4&url=%URL_ENCODED_LINKS%
+
+http://127.0.0.1:25500/sub?target=v2ray&url=%URL_ENCODED_LINKS%
+```
+
+#### Old interface
+
 ```
-http://127.0.0.1:25500/clashr?url=%URL_ENCODED_LINKS%
 http://127.0.0.1:25500/clash?url=%URL_ENCODED_LINKS%
 ```
-* Use '|' to separate multiple links before URL Encode.  
-* For more preference options, please check pref.ini.
+
+If you have multiple subscriptions, use '|' to separate the links before url encode. <br>
+
+e.g. <br>
+> I have the following two subscriptions: <br>
+`https://dler.cloud/subscribe/ABCDE?clash=vmess`
+`https://rich.cloud/subscribe/ABCDE?clash=vmess`
+<br> <br>
+separated by '|': <br>
+`https://dler.cloud/subscribe/ABCDE?clash=vmess|https://rich.cloud/subscribe/ABCDE?clash=vmess`
+<br> <br>
+after url encode: <br>
+`https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
+<br> <br>
+add to the back of the link: <br>
+`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess `
+<br> <br>
+&nbsp;&nbsp;&#127830; Edible &#127830;
+<br> <br>
+
+
+- Want to learn more postures? Come to [pref.ini](./pref.ini).
+
+
+
+## **Recommended reading**
+
+> - [&#128220; Regular Expression &#128220;](https://en.wikipedia.org/wiki/Regular_expression)
+> - [&#128221; yaml syntax introduction &#128221;](https://en.wikipedia.org/wiki/YAML)
+> - [&#10068; Wisdom to ask questions &#10068;](http://www.catb.org/~esr/faqs/smart-questions.html)
+
+
+
+## pref.ini
+
+### common
+
+#### api_mode
+
+> API mode, set to true to prevent loading local subscriptions or serving local files directly.
+
+When the value is `false`, `pref.ini` is read every time the configuration is updated. When it is `true`, it is read only at startup.
+
+
+
+#### default_url
+
+> Default URLs, used when no URL is provided in request, use "|" to separate multiple subscription links, supports local files/URL.
+
+This usage:
+```ini
+default_url=https://dler.cloud/subscribe/ABCDE?clash=vmess
+```
+
+`http://127.0.0.1:25500/clash`
+
+equivalent to:
+<br>
+`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
+
+
+
+#### exclud_remarks
+
+> Exclude nodes which remarks match the following patterns. Supports regular expression.
+
+e.g.
+```ini
+exclude_remarks=(Traffic|Time|Official Website|Products)
+```
+
+
+
+#### include_remarks
+
+> Only include nodes which remarks match the following patterns. Supports regular expression.
+
+e.g.
+```ini
+include_remarks=(?<=美).*(BGP|GIA|IPLC)
+```
+
+
+
+#### clash_rule_base
+
+> Clash config base used by the generator, supports local `files`/`URL`.
+
+e.g.
+```ini
+clash_rule_base=clash.yaml
+
+clash_rule_base=https://raw.githubusercontent.com/ConnersHua/Profiles/master/Clash/Pro.yaml
+```
+
+
+
+#### surge_rule_base
+
+> Surge config base used by the generator, supports local `files`/`URL`.
+
+
+
+#### surfboard_rule_base
+
+> Surfboard config base used by the generator, supports local `files`/`URL`.
+
+
+
+#### rename_node
+
+> Rename remarks with the following patterns. Supports regular expression.
+
+e.g.
+```ini
+rename_node=中国@中
+rename_node=深圳@深
+```
+
+
+
+### managed_config
+
+> Append a '#!MANAGED-CONFIG' info to Surge configurations.
+
+
+
+### emojis
+
+> Rule to add emojis. Supports regular expression.
+
+e.g.
+```ini
+rule=(流量|时间|应急),⌛time
+rule=(美|美国|United States),🇺🇸
+```
+
+
+
+### ruleset
+
+> Enable generating rules with rulesets.
+
+e.g.
+<img src="./doc/imgs/Snipaste_2019-11-18_14-11-52.png">
+
+```ini
+ruleset=🌹 YouTube, https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Media/YouTube.list
+```
+
+effect chart:
+
+<img src="./doc/imgs/Snipaste_2019-11-18_14-15-54.png">
+
+
+
+### clash_proxy_group
+
+> Generate Clash Proxy Group with the following patterns. Node filterting rule supports regular expression.
+
+e.g.
+```ini
+custom_proxy_group=🇺🇸US`url-test`(United States|United States|United States)`http://www.gstatic.com/generate_204`300
+```
+
+effect chart:
+
+<img src="./doc/imgs/Snipaste_2019-11-18_14-47-30.png">
+
+
+The ssr/v2 subscription does not have a group name by default. You can use this method to add a group name.
+
+```ini
+custom_proxy_group=g1`select`!!GROUPID=0
+custom_proxy_group=g2`select`!!GROUPID=1
+custom_proxy_group=v2ray`select`!!GROUP=V2RayProvider
+```
+
+
+### server
+
+#### listen
+
+> Address to bind on for Web Server.
+
+#### port
+
+> Port to bind on for Web Server.
+
+
+### advanced
+
+> No description required.
+
+
+
+## gist
+
+> Automatically upload gist.
+
+Add personal access token in [gistconf.ini](./gistconf.ini), add `upload=true` after the link will automatically upload gist after updating.
--- a/doc/imgs/Snipaste_2019-11-18_14-11-52.png
+++ b/doc/imgs/Snipaste_2019-11-18_14-11-52.png
--- a/doc/imgs/Snipaste_2019-11-18_14-15-54.png
+++ b/doc/imgs/Snipaste_2019-11-18_14-15-54.png
--- a/doc/imgs/Snipaste_2019-11-18_14-47-30.png
+++ b/doc/imgs/Snipaste_2019-11-18_14-47-30.png
--- a/doc/resources/emoji.html
+++ b/doc/resources/emoji.html
--- a/pref.ini
+++ b/pref.ini
@@ -180,7 +180,7 @@ surge_ruleset=🐟 漏网之鱼,[]MATCH
 ;custom_proxy_group=v2ray`select`!!GROUP=V2RayProvider

 ;for forcerule.yml
-;custom_proxy_group=Proxy`select`.*[]AUTO`[]DIRECT`.*
+;custom_proxy_group=Proxy`select`.*`[]AUTO`[]DIRECT`.*
 ;custom_proxy_group=AUTO`url-test`.*`http://www.gstatic.com/generate_204`300
 ;custom_proxy_group=google`select`.*
 ;custom_proxy_group=netflix`select`.*