Sub-Store Node Management, Operator Pipelines, and Script Customization Guide

This Skill is purpose-built for interactive operation with Copilot and targets Sub-Store instances that are already running. It accesses and operates on instances exclusively via HTTP REST APIs, with zero environment intrusion and no involvement of Docker, host installation, or external environment variable configuration, helping users perform node lifecycle management, multi-source aggregation, additional operator pipeline assembly, and on-demand authoring of JavaScript node-processing scripts.

[!NOTE] This Skill focuses on producing clean, standardized, optimized pure node sets or Proxy Provider subscriptions; it does not cover generating complete client configuration documents that include full DNS and complex routing rules. Reject rigid workflows: In practice, most requests involve temporary, one-off changes. Every capability is designed as an atomic operation, can be triggered independently at any time, and can also be freely combined as needed.

I. Core Principles and Architectural Understanding

1. Core Positioning: Pure HTTP REST API Interaction (Zero Environment Intrusion)

Target an existing instance: This Skill communicates with a running Sub-Store instance solely through standard HTTP REST APIs (such as
```
/api/subs
```
,
```
/api/collections
```
,
```
/api/file
```
,
```
/api/settings
```
, and
```
/api/sync/artifacts
```
) to execute node cleanup, pipeline orchestration, and global parameter tuning.
Zero environment intrusion guarantee: It never includes environment deployment, Docker installation, container lifecycle management, system daemon configuration, or host environment variable injection.
Immediate effect and platform neutrality: All configuration and data are dynamically read and hot-written through HTTP requests, with no service restart or access to the underlying host environment.

2. Two Operating Modes and Architectural Topologies

Sub-Store has two mutually exclusive operating modes in real-world networks:

Mode 1: Standalone Server

Sub-Store runs as an independent HTTP process or service—for example, on a LAN server, VPS, or local standalone service port such as

127.0.0.1:3000

or a specified domain—and exposes standard HTTP/HTTPS REST API endpoints.

Communication characteristics: Direct communication over standard TCP/IP networks, with no external proxy client required.
Secure path prefix (Prefix URL): Sub-Store natively lacks multi-user password authentication, so in standalone server mode it commonly uses the environment variable
```
SUB_STORE_FRONTEND_BACKEND_PATH
```
to configure an unpredictable, high-entropy random path prefix such as
```
/<SECRET_PATH>
```
. All API and download requests must carry this path prefix, such as
```
https://sub.example.com/<SECRET_PATH>/api/...
```
. Requests without the prefix or with an incorrect path directly receive a 404 or static decoy page, thereby blocking public internet scans and unauthorized access.

Mode 2: Proxy MITM Script Hijacking

Sub-Store is hosted within the built-in JavaScript script engine of a rule-routing proxy client such as Surge, Loon, Quantumult X, or Shadowrocket. It intercepts and handles specific virtual domains such as

http://sub.store

through the client’s man-in-the-middle decryption (MITM), URL rewriting, and script-rule hijacking.

Communication characteristics: No independent server process listening on a physical port exists. All HTTP requests sent to the virtual domain must be intercepted by the proxy client and handed to its internal script engine.
Traffic interception constraints: If
```
sub.store
```
is requested directly in an environment where proxy interception is not enabled, the system network stack will query public DNS and inevitably receive an
```
NXDOMAIN
```
failure, causing DNS leakage. Management requests must therefore be routed through the proxy client, such as through system TUN/enhanced-mode interception or an explicitly configured proxy port (
```
http_proxy
```
). If HTTPS is used, the client-generated self-signed certificate must also be allowed.

text

======================= 形态一：独立服务器形态 (Standalone Server) =======================

+------------------------------+     HTTP / HTTPS REST API     +------------------------------+
| 管理端 (curl / Python /      | ============================> | Sub-Store 独立服务器         |
| Copilot / 客户端拉取)        | <============================ | (独立 HTTP 服务 / 反代端点) |
+------------------------------+                               +------------------------------+
                                                                              |
                                                                              | 直连拉取
                                                                              v
                                                               +------------------------------+
                                                               | 外部机场与自建节点上游源     |
                                                               +------------------------------+

================= 形态二：代理 MITM 下的脚本劫持形态 (Proxy MITM Script Hijack) =================

+------------------------------+
| 管理端 (curl / Python /      |
| Copilot / 浏览器)            |
+------------------------------+
               |
               | 1. 发起请求: http://sub.store/api/... (必须经由代理客户端捕获接管)
               v
+--------------------------------------------------------------+
| 代理客户端 (Surge / Loon / Quantumult X / Shadowrocket)      |
|                                                              |
|   +--------------------------------------------------------+ |
|   | 流量接管层 (TUN 增强模式 / 操作系统代理 / 本地代理端口) | |
|   +--------------------------------------------------------+ |
|                                |                             |
|                                | 2. 匹配虚拟域名 sub.store   |
|                                v                             |
|   +--------------------------------------------------------+ |
|   | 内置 MITM 拦截与 JS 脚本引擎 (执行 Sub-Store 模块)     | |
|   +--------------------------------------------------------+ |
+--------------------------------------------------------------+
               |
               | 3. 直连或代理分流拉取
               v
+------------------------------+
| 外部机场与自建节点上游源     |
+------------------------------+

3. Core Iron Rule: Strict Compatibility with Frontend Web UI Forms (Two-Way-Bound Complete Schema)

Sub-Store has a classic pitfall: the backend execution engine is highly tolerant of input parameters, but the frontend Web console components strictly depend on specific reactive form fields.

Analysis of the core pitfall: If only the backend invocation is satisfied—such as passing
```
url
```
/
```
path
```
rather than
```
mode
```
+
```
content
```
to Script Operator, or omitting the
```
action
```
and
```
keep
```
linkage from Regex Filter—the backend can apply downward-compatible behavior when downloading and executing node cleanup. However, when a user opens the collection in the Web console, the frontend Vue form lacks key driving fields, causing radio buttons to lose focus and become desynchronized while input fields appear blank. If the user subsequently edits and saves the collection in the Web UI, the frontend submits these blank forms, overwrites the backend, and causes configuration corruption or loss!
Global principle—not limited to Script Operator: This issue affects all core Sub-Store objects and operators, including Script Operator (which must include
```
mode: "link"|"script"
```
and
```
content
```
), Regex Filter (which must include the linked
```
action: "keep"|"drop"
```
and
```
keep: true|false
```
), Rename, Flag, Sort, Deduplicate, and Manual/Remote subscription sources. Every API request and script must use a complete field format strictly aligned with the frontend UI, ensuring “100% effective backend execution + perfect visibility and safe interactive editing in the frontend Web UI”.

4. Core Iron Rule: Incremental Modification (Strictly Prohibit Destructive Overwrites)

In actual Sub-Store operations, blindly performing a full overwrite is the most dangerous high-risk operation:

Risk of appending nodes: If a user asks to “add a node” and a new object is submitted directly with POST, all other nodes in the existing subscription will be cleared and erased.
Risk of fine-tuning operators: If a user asks to “adjust an operator parameter” or “add a script operator” and a
```
process
```
array containing only one operator is submitted directly, all existing operators—such as Quick Setting, Flag, Regex Filter, and Sort—will be overwritten and lost.
Risk of fine-tuning settings: If a JSON payload containing only a few fields is submitted directly to
```
/api/settings
```
, unsubmitted credentials such as
```
gistToken
```
, the outbound
```
proxy
```
, or timeout settings may be overwritten, lost, or reset.
Loss of metadata: If existing
```
subscriptions
```
,
```
remark
```
,
```
tag
```
, and
```
ignoreFailedRemoteSub
```
metadata are not preserved, a full overwrite clears multi-source associations and advanced settings.

Three-Step Incremental Pattern: Regardless of whether the task involves node maintenance, operator adjustment, or global configuration tuning, the standard three-step pattern must be followed:

Read (read/fetch first): Use a
```
GET
```
endpoint (
```
/api/sub/...
```
,
```
/api/collection/...
```
, or
```
/api/settings
```
) to fetch the target’s current complete JSON object.
Mutate (incrementally modify/merge in memory): Perform a targeted local operation in memory or in a pipeline stream, such as appending a new node line to
```
content
```
, appending a new operator to the
```
process
```
array, updating the
```
args
```
of a specific operator, or modifying specific settings keys, while strictly preserving every other property, existing operator, and credential.
Write-back (write back the complete object): Save the merged complete object through POST, or use PATCH when supported by the endpoint.

II. Step One: Identify the Operating Mode and Probe Endpoints

Before performing any operation on Sub-Store, first probe and confirm its current operating mode and available base endpoint.

1. Endpoint Identification Logic

Standalone server determination:
- If the
```
SUB_STORE_PREFIX_URL
```
  environment variable is configured, use that URL directly, including any
```
/<SECRET_PATH>
```
  secure prefix.
- If the environment variable is not explicitly configured, first probe the local loopback service without a prefix at
```
http://127.0.0.1:3000
```
  .
Proxy MITM script-hijacking determination:
- Try a direct or proxied request to the virtual domain at
```
http://sub.store/api/subs
```
  or
```
https://sub.store/api/subs
```
  .
- In a proxy-interception environment such as TUN enhanced mode or a local proxy-port forward, bind the base endpoint to
```
http://sub.store
```
  after a successful probe.

2. Automated Endpoint-Probing Script

Run the following probing script to quickly identify the available endpoint and communication parameters:

bash

if [ -n "$SUB_STORE_PREFIX_URL" ]; then
  SUB_STORE_URL="${SUB_STORE_PREFIX_URL%/}"
  echo "使用指定的独立服务器端点 (Prefix URL): <SECRET_PATH>"
elif curl -s --max-time 1.5 "http://127.0.0.1:3000/api/subs" > /dev/null 2>&1; then
  SUB_STORE_URL="http://127.0.0.1:3000"
  echo "已探测到本地独立服务器: $SUB_STORE_URL"
elif curl -s --max-time 1.5 "http://sub.store/api/subs" > /dev/null 2>&1; then
  SUB_STORE_URL="http://sub.store"
  echo "已探测到代理客户端 MITM 虚拟域名 (直连接管 HTTP): $SUB_STORE_URL"
elif curl -k -s --max-time 1.5 "https://sub.store/api/subs" > /dev/null 2>&1; then
  SUB_STORE_URL="https://sub.store"
  echo "已探测到代理客户端 MITM 虚拟域名 (直连接管 HTTPS): $SUB_STORE_URL"
elif curl -x "http://127.0.0.1:6152" -s --max-time 1.5 "http://sub.store/api/subs" > /dev/null 2>&1; then
  SUB_STORE_URL="http://sub.store"
  export http_proxy="http://127.0.0.1:6152"
  export https_proxy="http://127.0.0.1:6152"
  echo "已通过本地代理端口 (6152) 接入代理客户端 MITM 虚拟域名: $SUB_STORE_URL"
elif curl -x "http://127.0.0.1:7890" -s --max-time 1.5 "http://sub.store/api/subs" > /dev/null 2>&1; then
  SUB_STORE_URL="http://sub.store"
  export http_proxy="http://127.0.0.1:7890"
  export https_proxy="http://127.0.0.1:7890"
  echo "已通过本地代理端口 (7890) 接入代理客户端 MITM 虚拟域名: $SUB_STORE_URL"
else
  echo "未探测到可用 Sub-Store 端点。请根据运行形态处理："
  echo "1. 独立服务器：请执行 export SUB_STORE_PREFIX_URL=\"https://domain.com/<SECRET_PATH>\""
  echo "2. 代理 MITM 劫持：请确保代理客户端（Surge/Loon 等）已启动且当前环境流量已交由代理捕获"
fi

III. Atomic Action Toolbox

All capabilities are independent atomic actions and can be invoked individually for specific requirements at any time.

1. Node and Subscription Management (Create/Delete/Update/Read)

At any time, enter, query, and incrementally fine-tune a single self-hosted node or commercial provider subscription:

Query all existing subscriptions and nodes:

bash

curl -s "${SUB_STORE_URL}/api/subs" | jq .

Enter a self-hosted node subscription for the first time (Manual local mode): Put node links (vmess, vless, ss, trojan, hysteria2, etc.) separated by line breaks into

content

, and leave

url

empty:

bash

curl -s -X POST "${SUB_STORE_URL}/api/subs" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My-Manual-Nodes",
    "type": "manual",
    "source": "local",
    "url": "",
    "enabled": true,
    "content": "trojan://password@1.1.1.1:443#%E6%97%A5%E6%9C%AC-01\nhysteria2://user:pass@3.3.3.3:443/?sni=example.com#%E7%BE%8E%E5%9B%BD-01"
  }'

Incrementally append a self-hosted node (never directly overwrite and clear existing nodes): When appending a new node link, first read the existing

content

and concatenate the new link at the end using the line-break separator

\n

, then write it back:

bash

SUB_NAME="My-Manual-Nodes"
NEW_NODE="hysteria2://user:pass@4.4.4.4:443/?sni=example.com#%E6%96%B0%E8%8A%82%E7%82%B9-02"

curl -s "${SUB_STORE_URL}/api/sub/${SUB_NAME}" | jq --arg n "$NEW_NODE" '
  .content = (if .content and (.content | length > 0) then (.content + "\n" + $n) else $n end)
' | curl -s -X POST "${SUB_STORE_URL}/api/subs" \
  -H "Content-Type: application/json" \
  --data-binary @-

Connect to or update a remote provider subscription (Remote URL mode):

bash

curl -s -X POST "${SUB_STORE_URL}/api/subs" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airport-Main",
    "type": "subscription",
    "source": "remote",
    "url": "https://airport.example.com/sub?token=<SECRET>",
    "enabled": true
  }'

2. On-Demand JavaScript Authoring and One-Click Push

For specific cleanup, field-overwrite, or property-repair requirements, author a standard JavaScript script on demand and push it to the virtual file store.

[!IMPORTANT]
Unified storage directory: All ad hoc JavaScript processing scripts and temporary Python helper scripts must be stored under
/tmp/sub-store-copilot/
; never create files indiscriminately in the main workspace, and keep the project environment clean.
File naming format:
/tmp/sub-store-copilot/<capability-name>.js
.
Self-explanatory naming principle:
<capability-name>
must have clear, self-explanatory semantics that accurately reflect the script’s specific capability, such as
optimize-udp-tfo.js
,
clean-ads-expire.js
,
inject-singbox-tags.js
, or
rename-region-flags.js
. Meaningless names such as
test.js
,
temp.js
, and
1.js
are strictly prohibited.
Standard workflow: Author and validate the script locally at
/tmp/sub-store-copilot/<capability-name>.js
→ upload it in binary form to Sub-Store’s virtual storage pool at
/api/file/<capability-name>.js
using
curl --data-binary
→ reference it in the operator pipeline.

Script function specification: The

operator(proxies, targetPlatform, context)

function must be exported:

javascript

function operator(proxies = [], targetPlatform) {
  return proxies.map(p => {
    p.udp = true;
    p.tfo = true;
    if (p.port === 443 || p.tls === true) p["skip-cert-verify"] = true;
    if (p.type === "hysteria2") p.alpn = p.alpn || ["h3"];
    return p;
  });
}

Standard workflow: local authoring and one-click push (recommended mode with zero workspace pollution):

bash

# 1. 创建规范临时目录并写入自解释命名的处理脚本
mkdir -p /tmp/sub-store-copilot
cat << 'EOF' > /tmp/sub-store-copilot/optimize-udp-tfo.js
function operator(proxies = [], targetPlatform) {
  return proxies.map(p => {
    p.udp = true;
    p.tfo = true;
    if (p.port === 443 || p.tls === true) p["skip-cert-verify"] = true;
    if (p.type === "hysteria2") p.alpn = p.alpn || ["h3"];
    return p;
  });
}
EOF

# 2. 二进制上传推送至虚拟文件存储
curl -s -X POST "${SUB_STORE_URL}/api/file/optimize-udp-tfo.js" \
  -H "Content-Type: text/javascript" \
  --data-binary @/tmp/sub-store-copilot/optimize-udp-tfo.js

Quick pipeline-stream upload (no intermediate file; push directly from a single command):

bash

curl -s -X POST "${SUB_STORE_URL}/api/file/optimize-udp-tfo.js" \
  -H "Content-Type: text/javascript" \
  --data-binary @- << 'EOF'
function operator(proxies = [], targetPlatform) {
  return proxies.map(p => {
    p.udp = true;
    p.tfo = true;
    return p;
  });
}
EOF

3. Operator Pipeline Adjustment and Parameter Fine-Tuning

Create an aggregated collection or incrementally adjust an existing pipeline containing Script Operator, Regex Filter, Rename, Flag, Sort, and Deduplicate:

[!CAUTION] Never submit a single-operator array blindly: When appending or adjusting an operator in an existing collection, directly POSTing a
process
array containing only one new operator will completely overwrite and erase every other existing operator—such as Quick Setting, Flag, Regex, and Sort—as well as subscription associations. The operator must always be incrementally appended or precisely patched onto the existing
process
array.

Create a multi-source aggregation collection and initial pipeline for the first time:

bash

curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clean-Nodes",
    "type": "collection",
    "subscriptions": ["Airport-Main", "My-Manual-Nodes"],
    "process": [
      { "type": "Script Operator", "args": { "mode": "link", "content": "/api/file/optimize-udp-tfo.js", "arguments": {} } },
      { "type": "Regex Filter", "args": { "pattern": "(?i)官网|到期|剩余|通知", "action": "drop", "keep": false } },
      { "type": "Flag", "args": { "mode": "add" } },
      { "type": "Sort", "args": { "field": "name", "order": "asc" } },
      { "type": "Deduplicate", "args": { "field": "name" } }
    ]
  }'

Incrementally append an operator to an existing collection (safely preserving existing operators and subscription metadata): First read the existing configuration, append the new operator to the end of the

process

array, and write it back:

bash

COLL_NAME="Clean-Nodes"
NEW_OP='{"type": "Script Operator", "args": {"mode": "link", "content": "/api/file/optimize-udp-tfo.js", "arguments": {}}}'

curl -s "${SUB_STORE_URL}/api/collection/${COLL_NAME}" | jq --argjson op "$NEW_OP" '
  .process = (.process // []) + [$op]
' | curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  --data-binary @-

4. Node Export and Cleanup Preview

Pull a specified subscription or collection at any time to quickly inspect the cleanup result or use it directly as a client Proxy Provider:

bash

# 1. 预览 Mihomo (Clash.Meta) YAML 纯节点列表（适合 proxy-provider 对接）
curl -s "${SUB_STORE_URL}/download/collection/Clean-Nodes?target=clash-meta" | head -n 30

# 2. 预览 Sing-Box JSON outbounds
curl -s "${SUB_STORE_URL}/download/collection/Clean-Nodes?target=singbox" | head -n 30

# 3. 预览 Surge [Proxy] 节点清单
curl -s "${SUB_STORE_URL}/download/collection/Clean-Nodes?target=surge" | head -n 30

# 4. 获取通用原始 URI / Base64 列表
curl -s "${SUB_STORE_URL}/download/collection/Clean-Nodes"

Example of using an external client as a Proxy Provider:

yaml

proxy-providers:
  Clean-Nodes-Provider:
    type: http
    url: "${SUB_STORE_URL}/download/collection/Clean-Nodes?target=clash-meta"
    path: ./providers/clean-nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 300

5. Global Configuration Management and Gist Backup Synchronization (Settings & Sync)

Use pure HTTP REST interfaces to read or fine-tune the global request configuration, cache parameters, and platform preferences of a running instance, and trigger Gist backup synchronization as needed:

Read the complete current settings:

bash

curl -s "${SUB_STORE_URL}/api/settings" | jq .

Incrementally update request settings and the outbound proxy (strictly preserving existing Gist credentials): First read the configuration, modify the target fields in memory, and write them back to avoid losing sensitive values through direct overwrites:

bash

curl -s "${SUB_STORE_URL}/api/settings" | jq '
  .proxy = "http://127.0.0.1:7890" |
  .timeout = 15000 |
  .concurrency = 5 |
  .concurrencyWaitTime = 200
' | curl -s -X POST "${SUB_STORE_URL}/api/settings" \
  -H "Content-Type: application/json" \
  --data-binary @-

Trigger a Gist backup synchronization with one curl command:

bash

# 调用备份端点立即触发全量配置上传（支持 GET 或 POST）
curl -s -X POST "${SUB_STORE_URL}/api/sync/artifacts"

Safe trigger command with status checking:

bash

mkdir -p /tmp/sub-store-copilot
HTTP_CODE=$(curl -s -o /tmp/sub-store-copilot/sync.log -w "%{http_code}" --max-time 15 "${SUB_STORE_URL}/api/sync/artifacts")
if [ "$HTTP_CODE" = "200" ]; then
  echo "Gist 备份同步成功"
else
  echo "Gist 备份同步失败 (HTTP $HTTP_CODE):"
  cat /tmp/sub-store-copilot/sync.log
fi

Minimal Python trigger script (zero dependencies, disposable after use):

python

import os, urllib.request

url = f"{os.environ.get('SUB_STORE_PREFIX_URL', 'http://127.0.0.1:3000').rstrip('/')}/api/sync/artifacts"
try:
    with urllib.request.urlopen(urllib.request.Request(url, method="POST"), timeout=15) as r:
        print(f"备份同步完成 [{r.status}]")
except Exception as e:
    print(f"备份同步异常: {e}")

Parameter checks and prerequisites:
- Prefix-path check: When a standalone server uses a secure prefix, request paths must include
```
/<SECRET_PATH>/api/sync/artifacts
```
  ; in Proxy MITM mode, requests must be forwarded and intercepted by the proxy client.
- GitHub Token scope: The Token must have
```
gist
```
  read/write permissions. The example uses the redacted
```
<GITHUB_TOKEN>
```
  placeholder; real values must never be disclosed.
- Gist association check: Ensure that the target
```
<GIST_ID>
```
  and username are correctly configured under Settings in the Web console.

IV. Common Combined Scenarios (Recipes for Reference Only, Never Mandatory)

Scenario 1: Make a Temporary One-Off Change—Fine-Tune an Existing Subscription’s Regex Filter or Rename Rule

When the user only needs to adjust a keyword or replacement prefix without affecting the overall subscription system:

Follow the three-step incremental pattern (read first → incrementally modify → write back the complete object): Locate the existing

Regex Filter

operator in the collection and update

args.pattern

, strictly preserving every other existing operator and

subscriptions

reference:

bash

COLL_NAME="Clean-Nodes"
curl -s "${SUB_STORE_URL}/api/collection/${COLL_NAME}" | jq '
  .process = (.process | map(
    if .type == "Regex Filter" then
      .args.pattern = "(?i)官网|到期|剩余|通知|重置|活动|公告"
    else . end
  ))
' | curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  --data-binary @-

The change takes effect immediately, while the collection’s original Script Operator, Flag, Sort, and other operators, as well as all subscription associations, remain completely unaffected.

Scenario 2: Make a Temporary One-Off Change—Write a Custom JS Script to Fix Specific Node Properties

When a specific node configuration has a defect—for example, missing ALPN, an SNI mismatch, or a required fingerprint:

Author a targeted JavaScript repair script on demand, write it to the standardized temporary directory, and upload it to virtual storage:

bash

mkdir -p /tmp/sub-store-copilot
cat << 'EOF' > /tmp/sub-store-copilot/fix-sni-domain.js
function operator(proxies = []) {
  return proxies.map(p => {
    if (p.name && p.name.includes("特殊")) p.sni = "custom.sni.com";
    return p;
  });
}
EOF
curl -s -X POST "${SUB_STORE_URL}/api/file/fix-sni-domain.js" \
  -H "Content-Type: text/javascript" \
  --data-binary @/tmp/sub-store-copilot/fix-sni-domain.js

Incrementally insert the operator at the beginning (never overwrite the existing pipeline): Read the existing collection, insert the

Script Operator

at the beginning of the

process

array, and write it back:

bash

NEW_OP='{"type": "Script Operator", "args": {"mode": "link", "content": "/api/file/fix-sni-domain.js", "arguments": {}}}'
curl -s "${SUB_STORE_URL}/api/collection/Clean-Nodes" | jq --argjson op "$NEW_OP" '
  .process = [$op] + (.process // [])
' | curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  --data-binary @-

Call

${SUB_STORE_URL}/download/collection/Clean-Nodes?target=clash-meta

to immediately validate the repair result.

Scenario 3: Make a Temporary One-Off Change—Append a New Self-Hosted Node to an Existing Subscription

When the user temporarily deploys a new VPS or obtains two node links that need to be inserted into an existing subscription:

Incremental append principle: Never directly POST an object containing only the new node, because doing so would erase all existing nodes.

Use an incremental pipeline stream: read the existing configuration → concatenate the new node line at the end of

content

→ write it back:

bash

SUB_NAME="My-Manual-Nodes"
NEW_NODE="hysteria2://user:pass@4.4.4.4:443/?sni=new.vps.com#%E6%96%B0%E8%8A%82%E7%82%B9"

curl -s "${SUB_STORE_URL}/api/sub/${SUB_NAME}" | jq --arg n "$NEW_NODE" '
  .content = (if .content and (.content | length > 0) then (.content + "\n" + $n) else $n end)
' | curl -s -X POST "${SUB_STORE_URL}/api/subs" \
  -H "Content-Type: application/json" \
  --data-binary @-

All downstream collections referencing this subscription update automatically, while the existing pipeline and nodes remain fully intact.

Scenario 4: Typical Complete Combination—Enter Nodes from Scratch and Configure Operators and Aggregation

A complete combination for initialization from scratch:

Run the endpoint-probing script to confirm the communication environment: standalone server or proxy MITM virtual domain.
Enter the self-hosted Manual nodes and the remote provider subscription separately.
Push the network-optimization script and configure a Regex Filter + Flag + Sort operator pipeline to aggregate them into a new collection.
Deliver
```
/download/collection/<name>?target=clash-meta
```
for reference by the client Proxy Provider.

Scenario 5: Make a Temporary One-Off Change—Dynamically Fine-Tune the Outbound Proxy, Request Timeout, and Concurrency Control

When an external provider subscription is fetched slowly, a relay proxy is required, or excessive concurrency needs to be prevented from triggering upstream rate limits:

Follow the three-step incremental modification pattern (read first → incrementally modify → write back the complete object): Use

GET /api/settings

to read the existing settings, precisely update

proxy

timeout

concurrency

, and

concurrencyWaitTime

in memory, and strictly preserve critical credentials such as the existing

gistToken

bash

curl -s "${SUB_STORE_URL}/api/settings" | jq '
  .proxy = "http://127.0.0.1:7890" |
  .timeout = 15000 |
  .concurrency = 5 |
  .concurrencyWaitTime = 200
' | curl -s -X POST "${SUB_STORE_URL}/api/settings" \
  -H "Content-Type: application/json" \
  --data-binary @-

The settings take effect immediately through hot updates. Subsequent Sub-Store requests for external provider subscriptions and external scripts automatically use the local proxy relay and smooth requests with a concurrency of 5. No service restart is required.

V. Complex Operations: Write Temporary Python Scripts as Needed (Use and Discard)

When managing Sub-Store, firmly reject maintaining a bulky, rigid, permanently full-featured CLI. Instead, switch tools flexibly according to operational complexity:

Simple one-off operations: Prefer
```
curl
```
+
```
jq
```
—the lightest option, with no external switching, for queries, single-subscription additions, or file uploads in a single command.
Complex batch operations and deep transformations: When the task involves messy multi-source data parsing, such as nested Base64 extraction and fingerprint deduplication; batch operator-pipeline injection across multiple collections; incremental node Diff comparison; or local JavaScript static preflight and push, author a lightweight, temporary, disposable Python script on demand.

[!TIP]
Unified storage directory: All temporary Python scripts and JavaScript processing scripts must be stored under
/tmp/sub-store-copilot/
; never create files indiscriminately in the main workspace.
Self-explanatory naming format: Name files
/tmp/sub-store-copilot/<capability-name>.py
.
<capability-name>
must accurately describe the script’s specific capability, such as
clean-and-dedup-nodes.py
,
batch-inject-pipeline.py
, or
diff-sync-nodes.py
. Vague names such as
test.py
and
temp.py
are strictly prohibited.
Zero-dependency guarantee: Temporary scripts use only the Python 3 standard library (
urllib.request
,
json
,
os
,
re
,
base64
, etc.), require no
pip install
, live in
/tmp/sub-store-copilot/
, and are discarded after use.

Minimal 10-Line Communication Template (Ready to Use)

python

import os, json, urllib.request

BASE_URL = os.environ.get("SUB_STORE_PREFIX_URL", "http://127.0.0.1:3000").rstrip("/")

def api(path, method="GET", data=None):
    headers = {"Content-Type": "application/json"} if data is not None else {}
    body = json.dumps(data).encode("utf-8") if data is not None else None
    req = urllib.request.Request(f"{BASE_URL}{path}", data=body, headers=headers, method=method)
    with urllib.request.urlopen(req) as resp:
        res = resp.read().decode("utf-8")
        return json.loads(res) if res and resp.headers.get_content_type() == "application/json" else res

For complete practical patterns covering five high-frequency scenarios—multi-source cleanup and deduplication, batch pipeline injection, incremental Diff comparison, local JavaScript syntax preflight and batch upload, and full inspection and repair of disconnected Web UI forms—see:

Guide to Writing Complex Temporary Python Operations

VI. Quick Reference to Core Objects and Common Operators

1. Quick Reference to Core Object Structures

Object Type	Endpoint	Required Core Fields	Key Notes
Self-hosted node	`/api/subs`	`name` , `type: "manual"` , `source: "local"` , `content`	Leave `url` empty and store all nodes in `content` , separated by line breaks
Remote subscription	`/api/subs`	`name` , `type: "subscription"` , `source: "remote"` , `url`	Leave `content` empty and provide the provider’s HTTP subscription URL
Aggregation collection	`/api/collections`	`name` , `type: "collection"` , `subscriptions` , `process`	Aggregates multiple subscriptions and executes the `process` operator pipeline in sequence
Processing script	`/api/file/:name`	Raw JavaScript text	Supports custom cleanup and is mounted in the operator pipeline through the `Script Operator`

2. Rapid Assembly of Common Operators

The operator

type

is strictly case-sensitive and is declared in the

process

array, where operators execute in a chain from top to bottom:

json

// 1. 挂载执行自定义 JS 脚本（Remote Link 模式，UI 与后端完全兼容）
{ "type": "Script Operator", "args": { "mode": "link", "content": "/api/file/optimize-udp-tfo.js", "arguments": {} } }

// 2. 正则保留特定地区（如港日新美）
{ "type": "Regex Filter", "args": { "pattern": "(?i)港|hk|日|jp|新|sg|美|us", "action": "keep", "keep": true } }

// 3. 正则剔除垃圾与广告节点
{ "type": "Regex Filter", "args": { "pattern": "(?i)官网|到期|剩余|通知|重置", "action": "drop", "keep": false } }

// 4. 正则替换重命名（统一加前缀）
{ "type": "Rename", "args": { "pattern": "^(.*)$", "replace": "[专线] $1" } }

// 5. 自动补全国旗 Emoji
{ "type": "Flag", "args": { "mode": "add" } }

// 6. 节点按名称升序排序
{ "type": "Sort", "args": { "field": "name", "order": "asc" } }

// 7. 按节点名称去重
{ "type": "Deduplicate", "args": { "field": "name" } }

3. Incremental Operation Pitfall Warning (Prevent Destructive Overwrites)

Operational Scenario	Destructive High-Risk Practice (Strictly Prohibited)	Incremental Safe Operation Standard
Append a new self-hosted node	Construct and POST JSON containing only the new node, causing all existing nodes to be lost	First GET the existing subscription, append the new link after a line break at the end of the existing `content` , and then write it back
Add a processing operator	Submit a `process` array containing only one new operator, causing all existing operators to be overwritten	First GET the existing collection, append or prepend the operator to `process` , and then write it back
Adjust an operator parameter	Reconstruct and overwrite the collection object, clearing `subscriptions` associations and advanced options	First GET the existing collection, locate the target operator and modify its corresponding `args` , preserve all other properties, and write it back
Modify global configuration ( `/api/settings` )	Submit JSON containing only the fields to be modified, causing the existing Gist Token, outbound proxy, and other settings to be overwritten and cleared	Strictly follow read-then-update: first GET the complete settings, incrementally merge the target fields in memory or with jq, and then write back the complete object
Author a temporary script	Casually create `test.js` / `temp.py` in the root directory and pollute the workspace	Use self-explanatory filenames under `/tmp/sub-store-copilot/` and discard the scripts after use

VII. Common Issues and UI Repair: One-Click Correction of Existing Script Operators and Operator Configurations

When collections have previously been created through third-party scripts or nonstandard APIs, the following symptoms commonly occur: “node cleanup and client retrieval work perfectly, but when the collection is opened in the Web console, the Script Operator Remote Link radio button is not selected, the input field is blank, or the Regex Filter radio controls are desynchronized.” If Save is accidentally clicked in the Web UI, the backend configuration can be overwritten and lost by empty forms.

The following approaches can be used for one-click diagnosis and lossless full repair:

1. Immediate Repair of a Single Collection (curl + jq Pipeline Stream)

Read the specified collection configuration, automatically map all nonstandard operator fields to the complete format strictly bound by the frontend Web UI, and overwrite it directly:

bash

# 1. 设定目标集合名称并执行一键转换覆写
COLL_NAME="Clean-Nodes"
curl -s "${SUB_STORE_URL}/api/collection/${COLL_NAME}" | jq '
  .process = (.process | map(
    if .type == "Script Operator" or .type == "Script" then
      .type = "Script Operator" |
      .args = {
        mode: (.args.mode // (if .args.content and (.args.content | contains("\n")) then "script" else "link" end)),
        content: (.args.content // .args.url // .args.path // "")
      }
    elif .type == "Regex Filter" then
      .args.action = (.args.action // (if .args.keep == false then "drop" else "keep" end)) |
      .args.keep = (if .args.keep != null then .args.keep elif .args.action == "drop" then false else true end)
    else . end
  ))
' | curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  --data-binary @-

# 2. 验证修复后的 process 结构
curl -s "${SUB_STORE_URL}/api/collection/${COLL_NAME}" | jq .process

2. Precise Overwrite Repair for a Single Collection (Direct curl Update)

If the script and rules required by a collection are already known, submit a complete standard JSON update directly:

bash

curl -s -X POST "${SUB_STORE_URL}/api/collections" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clean-Nodes",
    "type": "collection",
    "subscriptions": ["Airport-Main", "My-Manual-Nodes"],
    "process": [
      {
        "type": "Script Operator",
        "args": {
          "mode": "link",
          "content": "/api/file/optimize-udp-tfo.js",
          "arguments": {}
        }
      },
      {
        "type": "Regex Filter",
        "args": {
          "pattern": "(?i)官网|到期|剩余|通知",
          "action": "drop",
          "keep": false
        }
      }
    ]
  }'

3. One-Click Full Inspection and Repair of All Collections (Temporary Python Script, Disposable After Use)

When managing multiple collections, author and run the following minimal repair script on demand at

/tmp/sub-store-copilot/fix-ui-schema-doctor.py

. It automatically scans all collections and batch-corrects every incompatible operator format:

python

import os, json, urllib.request

BASE_URL = os.environ.get("SUB_STORE_PREFIX_URL", "http://127.0.0.1:3000").rstrip("/")

def api(path, data=None):
    headers = {"Content-Type": "application/json"} if data else {}
    body = json.dumps(data).encode("utf-8") if data else None
    req = urllib.request.Request(f"{BASE_URL}{path}", data=body, headers=headers, method="POST" if data else "GET")
    with urllib.request.urlopen(req) as resp:
        res = resp.read().decode("utf-8")
        return json.loads(res) if res else {}

collections = api("/api/collections")
print(f"开始巡检 {len(collections)} 个集合...")

for col in collections:
    name = col.get("name")
    process = col.get("process", [])
    changed = False

    for op in process:
        op_type = op.get("type", "")
        args = op.setdefault("args", {})
        
        # 1. 修复 Script Operator / Script 算子
        if op_type in ("Script Operator", "Script"):
            op["type"] = "Script Operator"
            if "mode" not in args or "content" not in args:
                content = args.get("content") or args.get("url") or args.get("path") or ""
                mode = args.get("mode") or ("script" if "\n" in content else "link")
                op["args"] = {"mode": mode, "content": content}
                changed = True
                
        # 2. 修复 Regex Filter 算子联动
        elif op_type == "Regex Filter":
            action = args.get("action")
            keep = args.get("keep")
            if action is None and keep is not None:
                args["action"] = "keep" if keep else "drop"
                changed = True
            elif keep is None and action is not None:
                args["keep"] = (action == "keep")
                changed = True

    if changed:
        api("/api/collections", data=col)
        print(f"已修复集合 [{name}] 中的非标准算子并写回 Sub-Store！")

print("全量集合巡检与修复完成。")

VIII. Complete Technical Manual Index

Consult the following standalone manuals for deeper specifications and dictionaries for specific functional modules:

Runtime Modes and Network Architecture

Runtime Mode and Server Detection Guide: An overview of the Standalone Server and Proxy MITM Script Hijacking modes, endpoint-probing priorities, and an automated probing script.

API and Operator Data Dictionary

Subscription Management API Specification: The
```
/api/subs
```
API specification, including fields and request bodies for inline self-hosted Manual nodes and remote provider subscriptions.
Aggregation Collection API Specification: The
```
/api/collections
```
API specification, covering multi-source aggregation and operator-pipeline configuration.
Built-in Operator Parameter Dictionary: Complete parameter specifications and chained-execution principles for Regex Filter, Rename, Flag, Sort, Deduplicate, and Script Operator.
Virtual File Storage API Specification: Specifications for
```
/api/file/:name
```
and
```
/api/files
```
, JavaScript script management, and curl pipeline uploads.
Node Export and Download API Specification: Specifications for
```
/download/...
```
endpoints,
```
target
```
parameter formats, and examples of external client Proxy Provider integration.
Global Settings and HTTP Configuration Specification: Alignment with the four frontend Web console configuration modules—Request Configuration / Cache Configuration / Gist Configuration / Other Configuration—and pure HTTP reads and writes through
```
GET /api/settings
```
and
```
POST /api/settings
```
, as well as backup synchronization through
```
POST /api/sync/artifacts
```
.

Complex Batch Operations and Temporary Scripts

Guide to Writing Complex Temporary Python Operations: A mental model for writing lightweight, temporary, disposable Python scripts for complex batch and deep-transformation scenarios, a standard-library connection pattern in fewer than 20 lines, and practical templates for five high-frequency scenarios: messy-text cleanup and deduplication, multi-collection batch pipeline injection, incremental Diff synchronization, local JavaScript syntax preflight with one-click push, and full inspection and repair of disconnected Web UI forms.

JavaScript Node-Processing Scripts

Proxy Schema Dictionary: A complete dictionary of attributes on Sub-Store’s internal
```
proxy
```
object, including common fields, protocol-specific fields, and function signatures.
JavaScript Node-Processing Script Cookbook: High-frequency practical scripts covering network-parameter optimization, standardized regional renaming, Sing-Box tag injection and cleanup, physical fingerprint hashing and deduplication, junk-node removal, and platform-aware TLS fingerprints.

sub-store-copilot

NPX Install

Tags

SKILL.md Content (Chinese)

Sub-Store Node Management, Operator Pipelines, and Script Customization Guide

I. Core Principles and Architectural Understanding

1. Core Positioning: Pure HTTP REST API Interaction (Zero Environment Intrusion)

2. Two Operating Modes and Architectural Topologies

Mode 1: Standalone Server

Mode 2: Proxy MITM Script Hijacking

3. Core Iron Rule: Strict Compatibility with Frontend Web UI Forms (Two-Way-Bound Complete Schema)

4. Core Iron Rule: Incremental Modification (Strictly Prohibit Destructive Overwrites)

II. Step One: Identify the Operating Mode and Probe Endpoints

1. Endpoint Identification Logic

2. Automated Endpoint-Probing Script

III. Atomic Action Toolbox

1. Node and Subscription Management (Create/Delete/Update/Read)

2. On-Demand JavaScript Authoring and One-Click Push

3. Operator Pipeline Adjustment and Parameter Fine-Tuning

4. Node Export and Cleanup Preview

5. Global Configuration Management and Gist Backup Synchronization (Settings & Sync)

IV. Common Combined Scenarios (Recipes for Reference Only, Never Mandatory)

Scenario 1: Make a Temporary One-Off Change—Fine-Tune an Existing Subscription’s Regex Filter or Rename Rule

Scenario 2: Make a Temporary One-Off Change—Write a Custom JS Script to Fix Specific Node Properties

Scenario 3: Make a Temporary One-Off Change—Append a New Self-Hosted Node to an Existing Subscription

Scenario 4: Typical Complete Combination—Enter Nodes from Scratch and Configure Operators and Aggregation

Scenario 5: Make a Temporary One-Off Change—Dynamically Fine-Tune the Outbound Proxy, Request Timeout, and Concurrency Control

V. Complex Operations: Write Temporary Python Scripts as Needed (Use and Discard)

Minimal 10-Line Communication Template (Ready to Use)

VI. Quick Reference to Core Objects and Common Operators

1. Quick Reference to Core Object Structures

2. Rapid Assembly of Common Operators

3. Incremental Operation Pitfall Warning (Prevent Destructive Overwrites)

VII. Common Issues and UI Repair: One-Click Correction of Existing Script Operators and Operator Configurations

1. Immediate Repair of a Single Collection (curl + jq Pipeline Stream)

2. Precise Overwrite Repair for a Single Collection (Direct curl Update)

3. One-Click Full Inspection and Repair of All Collections (Temporary Python Script, Disposable After Use)

VIII. Complete Technical Manual Index

Runtime Modes and Network Architecture

API and Operator Data Dictionary

Complex Batch Operations and Temporary Scripts

JavaScript Node-Processing Scripts