proxyctl 0.1.0__py3-none-any.whl

proxyctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: proxyctl
+Version: 0.1.0
+Summary: Proxy configuration lifecycle management for macOS and Linux
+Project-URL: Homepage, https://github.com/crhan/proxyctl
+Project-URL: Issues, https://github.com/crhan/proxyctl/issues
+Author-email: crhan <crhan123@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: clash,cli,lifecycle,mihomo,proxy,sing-box
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# proxyctl
+
+**Proxy configuration lifecycle management** — 不是静态配置，而是配置演进框架。
+
+## 定位
+
+proxyctl 是一套 macOS 代理管理工具，核心价值在于提供**配置生命周期管理**：
+
+```
+配置变更 → 验证 (check) → 调试 (trace) → 优化 (audit) → 回滚
+```
+
+它不告诉你"用什么配置"，而是帮你"管好配置"。
+
+## 核心功能
+
+### 状态面板
+```bash
+proxyctl status
+```
+- 引擎状态、端口监听、TUN 接口
+- DNS 状态、系统代理、网络环境
+- Tailscale 内网连通性
+
+### 健康检查
+```bash
+proxyctl check
+```
+四阶段检查：
+1. 基础状态（daemon、端口）
+2. 代理组状态（节点延迟、存活率）
+3. 连通性测试（google/github/国内网站）
+4. 出口 IP 验证（分流是否正确）
+
+### 链路诊断
+```bash
+proxyctl trace example.com
+```
+- DNS 解析（fakeip/realip）
+- 规则匹配预测
+- 连通性测试
+- 实际连接验证
+
+### 配置审计
+```bash
+proxyctl audit 7          # 扫描最近 7 天日志
+proxyctl audit apply      # 自动应用优化建议
+```
+找出"走代理但实际是国内 IP"的域名，建议添加到直连规则。
+
+### 节点测速
+```bash
+proxyctl bench                    # 测所有组
+proxyctl bench proxy claude       # 测指定组
+```
+
+## 安装
+
+### 快速安装
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/crhan/proxyctl.git
+cd proxyctl
+
+# 2. 运行安装脚本
+./install.sh
+
+# 3. 配置 API
+nano ~/.config/proxyctl/config.yaml
+# 填入 api_secret: your-clash-api-secret
+
+# 4. 验证
+proxyctl --help
+proxyctl status
+```
+
+### 手动安装
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/crhan/proxyctl.git
+cd proxyctl
+
+# 2. 复制文件
+cp bin/proxyctl ~/.local/bin/
+chmod +x ~/.local/bin/proxyctl
+
+# 3. 配置
+mkdir -p ~/.config/proxyctl
+cp config.yaml.example ~/.config/proxyctl/config.yaml
+# 编辑 config.yaml，填入 api_secret
+```
+
+### 安装后端
+
+```bash
+# Mihomo 后端（首发支持）
+brew install mihomo
+
+# 或者 Sing-box 后端（预留）
+brew install sing-box
+```
+
+详细安装指南请参考 [docs/INSTALL.md](docs/INSTALL.md)
+
+## 配置示例
+
+```yaml
+# ~/.config/proxyctl/config.yaml
+
+# 后端选择：mihomo (默认) | singbox
+backend: mihomo
+
+# Clash API 配置
+api_base: http://127.0.0.1:9090
+api_secret: your-clash-api-secret
+
+# 配置目录
+config_dir: /Users/yourname/.config
+
+# DNS 看门狗配置
+dns_lock_label: com.proxyctl.dns-lock
+```
+
+## 命令速查
+
+| 命令 | 功能 |
+|---|---|
+| `proxyctl start/stop/restart` | 启停后端 |
+| `proxyctl status` | 系统状态面板 |
+| `proxyctl check` | 全面健康检查 |
+| `proxyctl trace <domain>` | 域名链路诊断 |
+| `proxyctl audit [days]` | 代理链路审计 |
+| `proxyctl bench [groups]` | 代理组测速 |
+| `proxyctl fix` | 修复 DNS/代理 |
+| `proxyctl recover` | 切网后软恢复 |
+| `proxyctl mode tun\|proxy` | 切换模式 |
+| `proxyctl dns-lock` | 启动 DNS 看门狗 |
+
+## 架构设计
+
+### 后端抽象
+```
+Backend (接口)
+├── MihomoBackend (首发实现)
+└── SingboxBackend (预留)
+```
+
+### DNS 防线体系
+三层修复对抗 DNS 覆盖：
+1. `networksetup` — 对抗 DHCP
+2. 劫持 AnyConnect DNS 条目 — 对抗 VPN
+3. scutil 兜底注入 — 对抗其他覆盖源
+
+### 配置即代码
+- 版本控制 (git)
+- CI/CD (`proxyctl check` 当测试)
+- 回滚机制 (config.bak)
+- 变更日志
+
+## 后端支持
+
+| 功能 | Mihomo | Sing-box |
+|---|---|---|
+| status | ✅ | ✅ |
+| check | ✅ | ✅ |
+| trace | ✅ | ✅ |
+| audit | ✅ | ✅ |
+| bench | ✅ | ⚠️ |
+| recover | ✅ | ❌ |
+| mode 切换 | ✅ | ✅ |
+
+## 开发
+
+```bash
+# 本地测试
+python3 bin/proxyctl status
+
+# 调试模式
+export PROXYCTL_DEBUG=1
+```
+
+## License
+
+MIT
+
+## 致谢
+
+- [Mihomo](https://github.com/MetaCubeX/mihomo) - Clash Meta 内核
+- [Sing-box](https://github.com/SagerNet/sing-box) - 下一代代理内核

proxyctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+proxyctl/__init__.py,sha256=kMwX2ctr2ag1nZ-ngxnaIs_a645rw9iJEiBqnUQUqW8,84
+proxyctl/audit.py,sha256=bjNRgdm0Egc7_Eg-xdJV0vWzNbOUgrycYvYNr_5T1FI,13251
+proxyctl/check.py,sha256=uCDj3wrL0-UjvBXfqs7LVIFSyj13ZL1wG5CNP8ktTsQ,30475
+proxyctl/cli.py,sha256=d5ptumo89tgPB-tn44Ju7kZH1Mm1GnQ679x0hQrVsrQ,57295
+proxyctl/status.py,sha256=h9OCQEZwFRm1URxc1C1kpWAnGcayTSWJLmq1TXeKpn4,19745
+proxyctl/trace.py,sha256=y0cZQvZMbNRd_3L6_KRkzkmcrk1ppWC3lDARbtfvxKQ,21362
+proxyctl/builtin_plugins/__init__.py,sha256=743TULYZxX2p6vtBhGONjuaioFyYuGp-y0BhL21-adk,205
+proxyctl/builtin_plugins/connectivity_basic.py,sha256=SvpMNc6pSv5C08vgkU-Vw5qWPpBWzO9a6Rr3sCGdRso,1391
+proxyctl/builtin_plugins/corp_network.py,sha256=ZZASxJZRomRE7Oza57feN1x5TIV7sdOZBl1kyIMjKh8,1942
+proxyctl/core/__init__.py,sha256=1bSr06TiWSHDnG7wCjZqtSPnYDhEB0jLvwfl0oKu7XA,73
+proxyctl/core/plugin.py,sha256=98aUkMNGQUjZUycY-3HtB7UgXdo4_jiKxmTNk7smY7s,11708
+proxyctl/engine/__init__.py,sha256=BbYI6e7G3AgZZUDAcCSQ5WbJxFNfWzoDwx5aM5yH6dY,272
+proxyctl/engine/base.py,sha256=QZLfDetPssGF5EKiIbIyeqjUT43T5OH9-WQLO3v_Qbw,1929
+proxyctl/engine/mihomo.py,sha256=OMsClLFSwb4ZwcbdQ0YT2HDxfWQguOf_7qzzD91Mt9o,3752
+proxyctl/engine/singbox.py,sha256=J77bQ_PJ7rIbnt6YSU-WV4u_VH8re4KG5ytNHJ4ky9U,3915
+proxyctl-0.1.0.dist-info/METADATA,sha256=8tOe9_6BEdB1p-mKLsdGwqGjnzoRK5ZCqM0hxs7SsG8,4959
+proxyctl-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+proxyctl-0.1.0.dist-info/entry_points.txt,sha256=9HShIth5D1f7ECPnxYLXMCNW4jiqjpraJmN4QB-Gpug,47
+proxyctl-0.1.0.dist-info/licenses/LICENSE,sha256=scC-b_caxbJBCkr0ioJkMF_8fTKUNDEcR463CD0TWhQ,1062
+proxyctl-0.1.0.dist-info/RECORD,,

proxyctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

proxyctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proxyctl = proxyctl.cli:main

proxyctl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.