@aizigao/pi-proxy-fetch

Chinese: README-CN.md

A Pi extension package that patches globalThis.fetch inside a Pi session and routes requests through SwitchyOmega-style switchRules and proxy profiles.

Features

• Multiple profiles: define multiple proxy servers such as Clash or Whistle
• autoSwitch: match requests by rules and route them to a target profile
• Built-in targets: direct and system (http_proxy / HTTP_PROXY env)
• Remote rule lists: ruleListURL downloads a local cached rule file and participates in matching
• Custom CA cert: proxy_server supports optional caCertPath for tools like Whistle
• Interactive menu: switch profiles, toggle enable/disable, inspect stats, refresh rule lists, reload config

Requirements

• Node.js 20+
• Pi coding agent installed

Installation

pi install npm:@aizigao/pi-proxy-fetch

npm package

• Package: @aizigao/pi-proxy-fetch
• npm: https://www.npmjs.com/package/@aizigao/pi-proxy-fetch

Configuration

Recommended project-local config: ./.pi/proxy.json

Global config is also supported: ~/.pi/agent/proxy.json

If neither config exists, a default global config is created at ~/.pi/agent/proxy.json.

{
  "$schema": "https://raw.githubusercontent.com/aizigao/pi-proxy-fetch/master/schema.json",
  "version": 1,
  "enabled": true,
  "profileName": "auto-switch",
  "profileConfig": [
    {
      "name": "my-clash",
      "type": "proxy_server",
      "server": "socks5://127.0.0.1:7890"
    },
    {
      "name": "whistle",
      "type": "proxy_server",
      "server": "http://127.0.0.1:8899",
      "caCertPath": "~/.WhistleAppData/.whistle/certs/root.crt"
    },
    {
      "name": "auto-switch",
      "type": "autoSwitch",
      "ruleListURL": "https://raw.githubusercontent.com/gfwlist/gfwlist/master/gfwlist.txt",
      "switchRules": [
        {
          "note": "OpenAI direct",
          "conditions": [
            { "type": "host", "pattern": "api.openai.com" }
          ],
          "profileName": "direct"
        },
        {
          "note": "Anthropic direct",
          "conditions": [
            { "type": "host", "pattern": "api.anthropic.com" }
          ],
          "profileName": "direct"
        },
        {
          "note": "GitHub via Clash",
          "conditions": [
            { "type": "host", "pattern": "*.github.com" }
          ],
          "profileName": "my-clash"
        },
        {
          "note": "Google via Clash",
          "conditions": [
            { "type": "url", "pattern": "*://*.google.com/*" }
          ],
          "profileName": "my-clash"
        }
      ]
    }
  ]
}

Config path priority

1. ./.pi/proxy.json (project-local, preferred)
2. ~/.pi/agent/proxy.json (global)

Only configs with version: 1 are treated as the current format. If the file is not the current format, the current file is backed up as proxy.bak.json and a default config is generated.

Top-level fields

Field	Type	Description
version	1	Current config schema version
enabled	boolean	Master on/off switch. false bypasses all proxy logic
profileName	string	Active profile name. Reserved values: direct, system; custom names must match ^[A-Za-z_-]+$
profileConfig	Profile[]	Profile list

proxy_server fields

Field	Type	Description
name	string	Profile name; must match ^[A-Za-z_-]+$
type	"proxy_server"	Fixed value
server	string	Required proxy URL, e.g. socks5://127.0.0.1:7890
caCertPath	string?	Optional CA certificate path, useful for Whistle-style self-signed proxies

autoSwitch fields

Field	Type	Description
name	string	Profile name; must match ^[A-Za-z_-]+$
type	"autoSwitch"	Fixed value
ruleListURL	string?	Remote rule list URL
switchRules	SwitchRule[]	Local rules

SwitchRule fields

Field	Type	Description
note	string?	Note
conditions	Condition[]?	Condition list with OR logic; empty means always match
profileName	string	Target profile. Reserved: direct, system; custom names must match ^[A-Za-z_-]+$

Condition fields

Field	Type	Description
type	host / url / regex / disabled	Condition type
pattern	string?	Match pattern

Condition types

type	Matches	Notes
host	request hostname	Supports * / ?; *.example.com matches both example.com and subdomains; **.example.com matches subdomains only
url	full request URL	Supports * / ?; no special *. behavior
regex	full request URL	JavaScript regular expression
disabled	-	Never matches

If no rule matches, the request goes direct by default. No explicit catch-all rule is required.

ruleListURL behavior

• ruleListURL is useful when you want to reuse a remote ruleset such as gfwlist / AutoProxy
• Project configs save downloaded content next to the project config file
• Global configs save downloaded content under ~/.pi/agent
• Filename format:

proxy-rulelist-file--{profile_name_safe}.txt

Example:

./.pi/proxy-rulelist-file--auto_switch.txt
~/.pi/agent/proxy-rulelist-file--auto_switch.txt

Behavior:

• On session_start, if the local file already exists, it is loaded directly
• If the local file is missing, it is downloaded once automatically
• You can also refresh it manually from the /proxy menu via Refresh rule list files
• Downloaded remote rules are merged into memory at runtime only and are not written back into your original switchRules
• Profile switching, reload, and menu actions never directly rewrite your original rules

Commands

Run inside Pi:

/proxy            # open interactive menu
/proxy stats      # show stats
/proxy reload     # reload config
/proxy name       # switch directly to a profile

The /proxy menu includes:

• Select profile
• Enable/Disable proxy
• Show stats
• Refresh rule list files
• Reload config

Development

npm install
npm run check
npm run lint
npm run schema

License

MIT