mihomo-ai-failover: Instructions file for Claude Code

Repository instructions

Scope

• This repository provides Provider-scoped AI failover for Mihomo-compatible clients. The public templates cover OpenAI/ChatGPT/Codex, WorkBuddy (China), Kimi, MiniMax, and Mavis. Version 0.x supports macOS and Clash Verge Rev.
• Preserve the Provider-only routing boundary. Never switch a global proxy group, enable TUN, disable the system proxy, or alter unrelated traffic.
• Keep the failover engine usable without an AI agent. The CLI and daemon are authoritative; MCP and skills are adapters.
• Public code and local personalization use the same engine. Machine-specific domains and enablement belong in the private providers.local.yaml overlay, not in a fork, source file, example, test fixture, or commit.

Safety and privacy

• Never commit subscription URLs, controller secrets, proxy passwords, node server addresses, private node inventories, exit IPs, or runtime logs.
• Never commit locally observed Provider hostnames. Public Provider templates contain only conservative, documented product roots. Additional exact domains require local evidence, review, and an explicit overlay write.
• Read the Mihomo controller secret only at runtime from a local config file.
• Prefer a Unix-domain controller socket. Never make an external controller listen on a non-loopback address.
• Never hard-code a username, home directory, application data path, or local repository path.
• MCP tools are read-only by default. State-changing tools must accurately set MCP safety annotations and require an explicit confirmation token enforced by the server, not merely by model instructions.
• Tests must use fake nodes, fake IPs, temporary directories, and fake controller responses.

Failover invariants

• A healthy selected node stays selected. Latency differences alone never trigger a switch.
• Switching requires two guarded aggregate hard-failure rounds on the verified route only when at least two distinct critical targets fail across those rounds. A single failing target requires at least three rounds and a 30-second observation window.
• Each enabled Provider has an independent select group, state file, health history, pools, cooldowns, switch episode, and log. One Provider's failure must never increment another Provider's counters or move another group.
• Providers share only the read-only subscription node catalog. Background deep scans are serialized across Providers to bound local CPU/network load.
• A local-network failure, stopped Mihomo process, or controller failure must not trigger blind switching.
• Candidate ranking prioritizes current health, success history, a distinct exit IP, ASN diversity, cooldown state, and stability before latency.
• Deep candidate evidence needs two usable samples with at least one retry-free result. A retry-assisted live acceptance must pass a mandatory retry-free follow-up before a newly selected route can commit.
• After switching, preserve old Provider connections by default. Optional cleanup may close an old connection only after a newer same-process, same-host replacement exists on the newly selected node.
• Notify "当前机场全部不可用" once per outage episode and use backoff.