procproxy 0.1.0__tar.gz → 0.1.1__tar.gz

{procproxy-0.1.0/src/procproxy.egg-info → procproxy-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.0
+Version: 0.1.1
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -68,8 +68,24 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 
 需要 **Python 3.10+**。
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install procproxy
+procproxy init          # 生成 ~/.procproxy/config.yaml
+procproxy doctor        # 环境自检
+procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+```
+
+安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
+
+非管理员：WinDivert 抓包必须管理员；可以用 `--backend null` 做转发链路联调，
+或在服务已启动、且配置了 `service.ipc_allow_group` 时读取状态。
+
+### 源码开发安装
+
 ```bash
-pip install -e .
+pip install -e ".[dev]"
 # 或者不装（零依赖方式，往 site-packages 写一个 .pth，让 python -m proxycore 全局可用）
 python procproxy.py install-path
 ```
@@ -77,7 +93,7 @@ python procproxy.py install-path
 数据面依赖（要用真抓包就必需）：
 
 ```bash
-pip install pydivert psutil
+pip install "procproxy[windivert]"
 ```
 
 > `pydivert` 自带**已签名**的 `WinDivert64.sys` —— 所以**不需要**开测试签名、不需要自己签驱动。

{procproxy-0.1.0 → procproxy-0.1.1}/README.md

@@ -29,8 +29,24 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 
 需要 **Python 3.10+**。
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install procproxy
+procproxy init          # 生成 ~/.procproxy/config.yaml
+procproxy doctor        # 环境自检
+procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+```
+
+安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
+
+非管理员：WinDivert 抓包必须管理员；可以用 `--backend null` 做转发链路联调，
+或在服务已启动、且配置了 `service.ipc_allow_group` 时读取状态。
+
+### 源码开发安装
+
 ```bash
-pip install -e .
+pip install -e ".[dev]"
 # 或者不装（零依赖方式，往 site-packages 写一个 .pth，让 python -m proxycore 全局可用）
 python procproxy.py install-path
 ```
@@ -38,7 +54,7 @@ python procproxy.py install-path
 数据面依赖（要用真抓包就必需）：
 
 ```bash
-pip install pydivert psutil
+pip install "procproxy[windivert]"
 ```
 
 > `pydivert` 自带**已签名**的 `WinDivert64.sys` —— 所以**不需要**开测试签名、不需要自己签驱动。

{procproxy-0.1.0 → procproxy-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "procproxy"
-version = "0.1.0"
+version = "0.1.1"
 description = "ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -51,6 +51,9 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"proxycore" = ["data/*.yaml"]
+
 # ---------------------------------------------------------------- pytest ----
 [tool.pytest.ini_options]
 minversion = "7.4"

{procproxy-0.1.0 → procproxy-0.1.1/src/procproxy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.0
+Version: 0.1.1
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -68,8 +68,24 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 
 需要 **Python 3.10+**。
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install procproxy
+procproxy init          # 生成 ~/.procproxy/config.yaml
+procproxy doctor        # 环境自检
+procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+```
+
+安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
+
+非管理员：WinDivert 抓包必须管理员；可以用 `--backend null` 做转发链路联调，
+或在服务已启动、且配置了 `service.ipc_allow_group` 时读取状态。
+
+### 源码开发安装
+
 ```bash
-pip install -e .
+pip install -e ".[dev]"
 # 或者不装（零依赖方式，往 site-packages 写一个 .pth，让 python -m proxycore 全局可用）
 python procproxy.py install-path
 ```
@@ -77,7 +93,7 @@ python procproxy.py install-path
 数据面依赖（要用真抓包就必需）：
 
 ```bash
-pip install pydivert psutil
+pip install "procproxy[windivert]"
 ```
 
 > `pydivert` 自带**已签名**的 `WinDivert64.sys` —— 所以**不需要**开测试签名、不需要自己签驱动。

{procproxy-0.1.0 → procproxy-0.1.1}/src/procproxy.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ src/proxycore/backend/windivert/__init__.py
 src/proxycore/backend/windivert/filter.py
 src/proxycore/backend/windivert/pidmap.py
 src/proxycore/backend/windivert/pkt.py
+src/proxycore/data/default.yaml
 src/proxycore/dns/__init__.py
 src/proxycore/dns/cache.py
 src/proxycore/dns/modes.py

{procproxy-0.1.0 → procproxy-0.1.1}/src/proxycore/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = ["__version__"]

{procproxy-0.1.0 → procproxy-0.1.1}/src/proxycore/__main__.py

@@ -2,16 +2,16 @@
 
 目标是让"用 Python 启动"最省事：
 
-    python -m proxycore                                   # 起服务（默认配置）
+    python -m proxycore                                   # 首次使用指引
+    python -m proxycore init                              # 生成配置
     python -m proxycore --config 你的.yaml                # 起服务（等价于 run）
     python -m proxycore --config 你的.yaml --backend null # 联调
     python -m proxycore rules --config 你的.yaml           # 子命令原样转给 CLI
     python -m proxycore --help / --version
 
-也就是说：没写子命令时默认补 `run`（只对 run 支持的参数生效），
-写了子命令就原样透传。子命令清单取自 `cli` 的单一来源，不在这里再抄一遍
-（两边各抄一份的话，新增 `forward` / `can-proxy` 之后这里会漏，
-`python -m proxycore forward` 就会被误补成 `run forward`）。
+没写参数时打印首次使用指引（不启动服务）；顶层给 `--config` 等 run 选项时
+自动补 `run`；写了子命令就原样透传。子命令清单取自 `cli` 的单一来源，
+不在这里再抄一遍。
 """
 
 from __future__ import annotations
@@ -32,7 +32,7 @@ RUN_OPTIONS = (
 )
 
 #: 自带 argparse 的原生子命令。
-NATIVE_SUBCOMMANDS = ("rules", "config", "status", "sessions", "run", "doctor", "stop")
+NATIVE_SUBCOMMANDS = ("rules", "config", "status", "sessions", "run", "doctor", "init", "stop")
 
 
 def known_subcommands() -> tuple[str, ...]:
@@ -45,7 +45,7 @@ def known_subcommands() -> tuple[str, ...]:
 def normalize_args(argv: list[str]) -> list[str]:
     """把顶层选项补成 `run <选项>`；其它情况原样返回。"""
     if not argv:
-        return ["run", "--config", "samples/profiles/dev.yaml"]
+        return []  # 交给 cli.main 打印首次使用指引
     # 显式子命令、或 -h/--help/--version：原样交给 CLI
     if argv[0] in known_subcommands() or argv[0] in ("-h", "--help", "--version"):
         return argv

{procproxy-0.1.0 → procproxy-0.1.1}/src/proxycore/canproxy.py

@@ -109,10 +109,13 @@ def main(argv: list[str] | None = None) -> int:
 
     config: Config | None = None
     config_error = ""
+    from .cli import default_config_path
+
+    path = default_config_path(args.config) or resolve_config_path(args.config)
     try:
-        config = Config.load(resolve_config_path(args.config))
+        config = Config.load(path)
     except (ConfigError, OSError) as exc:
-        config_error = str(exc)
+        config_error = f"{exc}（首次使用请运行 procproxy init）"
 
     backend = args.backend or (config.service.backend if config else "windivert")
     sink_host = config.service.sink.host if config else "127.0.0.1"

{procproxy-0.1.0 → procproxy-0.1.1}/src/proxycore/checkroute.py

@@ -28,6 +28,7 @@ from collections import Counter
 from pathlib import Path
 
 from proxycore.backend.windivert.pidmap import PortPidTable, is_supported
+from proxycore.cli import default_config_path
 from proxycore.config import Config, ConfigError
 from proxycore.proc import get_proc_info, iter_pids
 from proxycore.rules import GuardSet, decide
@@ -176,13 +177,17 @@ def main(argv: list[str] | None = None) -> int:
         return 2
     proc_name = args.proc or target
 
+    path = default_config_path(args.config)
+    if path is None:
+        print(f"配置文件不存在: {args.config}；首次使用请运行 procproxy init", file=sys.stderr)
+        return 2
     try:
-        config = Config.load(args.config)
+        config = Config.load(path)
     except ConfigError as exc:
         print(f"配置无效：{exc}", file=sys.stderr)
         return 2
 
-    print(f"# check_route  target={target} expect={args.expect} config={args.config}")
+    print(f"# check_route  target={target} expect={args.expect} config={config.path or args.config}")
     print(f"# 规则复算：{proc_name} -> {args.dst}:{args.port}/{args.proto}")
 
     actual_action, replay_note = replay_rule(config, proc_name, args.dst, args.port, args.proto)

{procproxy-0.1.0 → procproxy-0.1.1}/src/proxycore/cli.py

@@ -16,6 +16,8 @@ import time
 from pathlib import Path
 from typing import Any
 
+import yaml
+
 from proxycore import __version__
 from proxycore.config import Config, ConfigError, ConfigManager, port_in_use
 from proxycore.log import LEVELS, build_logger, enable_trace_payload, get_logger, redact
@@ -24,6 +26,7 @@ from proxycore.types import ConnRequest, Endpoint, ProcInfo, Proto
 
 DEFAULT_CONFIG = "samples/profiles/dev.yaml"
 RUNTIME_DIR_ENV = "PROCPROXY_RUNTIME_DIR"
+USER_CONFIG_ENV = "PROCPROXY_CONFIG"
 
 
 # ============================================================ 运行时目录 ====
@@ -38,6 +41,12 @@ def runtime_dir() -> Path:
     return Path.home() / ".procproxy"
 
 
+def user_config_path() -> Path:
+    """用户配置的默认路径（非管理员可写；可用 `PROCPROXY_CONFIG` 覆盖）。"""
+    override = os.environ.get(USER_CONFIG_ENV)
+    return Path(override) if override else Path.home() / ".procproxy" / "config.yaml"
+
+
 def state_path() -> Path:
     return runtime_dir() / "state.json"
 
@@ -113,15 +122,48 @@ def resolve_config_path(raw: str) -> Path:
     return path
 
 
+def packaged_default_config() -> Path | None:
+    """安装包内置的最小默认配置（PyPI 安装后也能首次运行）。"""
+    try:
+        from importlib.resources import files
+
+        path = Path(str(files("proxycore").joinpath("data/default.yaml")))
+    except (ImportError, ModuleNotFoundError, TypeError, ValueError):
+        return None
+    return path if path.is_file() else None
+
+
+def default_config_path(raw: str) -> Path | None:
+    """用户指定的配置 → 仓库样例 → 安装包内置默认配置。"""
+    path = resolve_config_path(raw)
+    if path.exists():
+        return path
+    if raw == DEFAULT_CONFIG:
+        return packaged_default_config()
+    return None
+
+
 def _load_config(args: argparse.Namespace) -> Config:
     raw = getattr(args, "config", DEFAULT_CONFIG) or DEFAULT_CONFIG
     path = resolve_config_path(raw)
+    using_packaged = False
+    if not path.exists() and raw == DEFAULT_CONFIG:
+        packaged = packaged_default_config()
+        if packaged is not None:
+            path = packaged
+            using_packaged = True
     if not path.exists():
-        hint = ""
-        root = repo_root()
-        if root is not None:
-            hint = f"\n提示：仓库根是 {root}，可用 --config {root / 'samples' / 'profiles' / 'dev.yaml'}"
-        raise SystemExit(f"配置文件不存在: {path}{hint}")
+        raise SystemExit(
+            f"配置文件不存在: {path}\n"
+            "首次使用请运行: procproxy init\n"
+            "或指定配置: procproxy doctor --config <你的.yaml>"
+        )
+    if using_packaged:
+        print(
+            "[i] 未找到用户配置，使用内置默认配置（backend=null，不抓包）。"
+            "运行 `procproxy init` 生成可编辑配置。",
+            file=sys.stderr,
+        )
     try:
         return Config.load(path, check_sink=bool(getattr(args, "check_sink", False)))
     except ConfigError as exc:
@@ -219,6 +261,51 @@ def cmd_config(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_init(args: argparse.Namespace) -> int:
+    """生成一份可编辑的启动配置（PyPI 安装后首次使用）。"""
+    target = Path(args.path) if args.path else user_config_path()
+    if target.exists() and not args.force:
+        print(f"配置文件已存在: {target}（加 --force 覆盖）", file=sys.stderr)
+        return 2
+    if not 1024 <= args.sink_port <= 65535:
+        print("--sink-port 必须在 1024-65535", file=sys.stderr)
+        return 2
+    packaged = packaged_default_config()
+    if packaged is None:
+        print("安装包缺少内置默认配置，请重新安装 procproxy", file=sys.stderr)
+        return 2
+
+    doc = yaml.safe_load(packaged.read_text(encoding="utf-8")) or {}
+    service = doc.setdefault("service", {})
+    service["backend"] = args.backend
+    sink = service.setdefault("sink", {})
+    sink.setdefault("host", "127.0.0.1")
+    sink["port"] = args.sink_port
+    target.parent.mkdir(parents=True, exist_ok=True)
+    header = "# ProcProxy 配置（由 `procproxy init` 生成）\n"
+    target.write_text(
+        header + yaml.safe_dump(doc, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+    try:
+        Config.load(target)
+    except ConfigError as exc:
+        with contextlib.suppress(OSError):
+            target.unlink()
+        print(f"生成的配置未通过校验：{exc.code} — {exc.message}", file=sys.stderr)
+        return 2
+
+    print(f"已生成配置: {target}")
+    print("下一步:")
+    print(f"  procproxy doctor --config \"{target}\"")
+    print(f"  procproxy run --config \"{target}\"")
+    if args.backend == "windivert":
+        print("  提示: backend=windivert 需要管理员权限；非管理员请加 --backend null 只做联调。")
+    else:
+        print("  提示: backend=null 不抓包；真实抓包请用 `procproxy forward ...` 或 --backend windivert。")
+    return 0
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     state = _read_json(state_path())
     config: Config | None = None
@@ -473,6 +560,24 @@ def cmd_stop(args: argparse.Namespace) -> int:
     return 0
 
 
+def _quickstart() -> int:
+    """无参数时的首次使用指引（不依赖配置文件）。"""
+    print(f"ProcProxy {__version__}")
+    print()
+    print("首次使用:")
+    print("  procproxy init                              生成配置")
+    print("  procproxy doctor                            环境自检")
+    print("  procproxy forward WeChat.exe --port 8848    把进程流量转发给抓包工具")
+    print()
+    print("其他:")
+    print("  procproxy run --config <path>               前台运行数据面")
+    print("  procproxy rules --config <path>             查看规则")
+    print("  procproxy --help                            全部命令")
+    print()
+    print("非管理员: --backend null 只联调不抓包；真实抓包需要管理员。")
+    return 0
+
+
 # ============================================================ 参数解析 ====
 
 # ====================================================== 外包子命令（透传）====
@@ -568,6 +673,13 @@ def build_parser() -> argparse.ArgumentParser:
     p_doctor.add_argument("--backend", choices=["null", "windivert"], default="")
     p_doctor.set_defaults(func=cmd_doctor)
 
+    p_init = sub.add_parser("init", help="生成一份可编辑的启动配置")
+    p_init.add_argument("--path", default="", help="输出路径（默认 ~/.procproxy/config.yaml）")
+    p_init.add_argument("--backend", choices=["null", "windivert"], default="null")
+    p_init.add_argument("--sink-port", type=int, default=19080)
+    p_init.add_argument("--force", action="store_true", help="覆盖已存在的配置")
+    p_init.set_defaults(func=cmd_init)
+
     p_stop = sub.add_parser("stop", help="停止服务（--panic 为紧急全量放行）")
     add_common(p_stop)
     p_stop.add_argument("--panic", action="store_true", help="紧急停止：尽快停掉数据面并退出")
@@ -579,6 +691,8 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> int:
     _force_utf8_console()
     argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        return _quickstart()
     handled = _dispatch_passthrough(argv)
     if handled is not None:
         return handled

procproxy-0.1.1/src/proxycore/data/default.yaml

@@ -0,0 +1,15 @@
+# ProcProxy 内置默认配置
+# backend=null：不抓包、不改道，只用于首次自检/联调。
+# 真实使用请运行 `procproxy init` 或 `procproxy forward <进程名> --port <端口>`。
+version: 1
+service:
+  sink: { host: 127.0.0.1, port: 19080 }
+  backend: null
+  on_unknown_pid: direct
+  on_decide_error: block
+profile:
+  name: default
+  default_action: direct
+  dns_mode: remote
+upstreams: []
+rules: []