procproxy 0.1.2__tar.gz → 0.1.3__tar.gz

{procproxy-0.1.2/src/procproxy.egg-info → procproxy-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.2
+Version: 0.1.3
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -74,7 +74,7 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 pip install procproxy
 procproxy init          # 生成 ~/.procproxy/config.yaml
 procproxy doctor        # 环境自检
-procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+procproxy forward --process WeChat.exe --port 8848   # 真实转发（需管理员）
 ```
 
 安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
@@ -250,7 +250,7 @@ python procproxy.py Weixin.exe WeChatAppEx.exe --port 8848
 ⚠️ 只有 ① 没有 ② → 端口填错了（**要填抓包工具的 MITM 监听口，不是它的 Web 管理口**）。
 ① ② 都正常但内容看不懂 → 那是 TLS，不是转发的问题。
 
-完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](docs/14-把进程流量转发给抓包工具.md)。
+完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](https://github.com/Longersking/procproxy/blob/master/docs/14-%E6%8A%8A%E8%BF%9B%E7%A8%8B%E6%B5%81%E9%87%8F%E8%BD%AC%E5%8F%91%E7%BB%99%E6%8A%93%E5%8C%85%E5%B7%A5%E5%85%B7.md)。
 
 ---
 
@@ -340,14 +340,14 @@ rules:                                      # 自上而下，**首个命中生
 7. 都没命中     → profile.default_action
 ```
 
-完整语义见 [`docs/07-规则引擎与Profile格式.md`](docs/07-规则引擎与Profile格式.md)。
+完整语义见 [`docs/07-规则引擎与Profile格式.md`](https://github.com/Longersking/procproxy/blob/master/docs/07-%E8%A7%84%E5%88%99%E5%BC%95%E6%93%8E%E4%B8%8EProfile%E6%A0%BC%E5%BC%8F.md)。
 
 ---
 
 ## 编程接口
 
 `proxycore.api` 是与 CLI 共用同一套配置、规则引擎和会话表的 SDK。
-完整教程见 [`docs/15-编程接口与SDK.md`](docs/15-编程接口与SDK.md)。
+完整教程见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
 
 ### 30 秒：零配置启动
 
@@ -373,6 +373,52 @@ with start_proxy() as ppx:          # 不需要任何配置文件
 状态查询和联调；要真实抓包请用 `backend="windivert"`（需管理员）或
 `procproxy init` 生成自己的配置。
 
+### 初始化：生成一份可编辑配置
+
+```python
+from proxycore.api import init_config
+
+path = init_config(
+    "D:/cfg/procproxy.yaml",   # 省略则用 PROCPROXY_CONFIG 或 ~/.procproxy/config.yaml
+    backend="windivert",       # 真抓包需管理员；联调用 "null"
+    sink_port=19080,
+)
+print(path)                    # 绝对路径；等价于 procproxy init
+```
+
+生成的是最小模板，`upstreams` / `rules` 仍为空，需要按下面的案例补上。
+
+### 代理一个进程（最小完整配置）
+
+```yaml
+version: 1
+service:
+  sink: { host: 127.0.0.1, port: 19080 }
+  backend: windivert            # 真抓包；联调改 null
+profile:
+  name: chrome-via-socks
+  default_action: direct
+  dns_mode: remote
+upstreams:
+  - { alias: socks, kind: socks5, host: 127.0.0.1, port: 1080, auth: none }
+rules:
+  - { id: r-private, action: direct, targets: "*",
+      dst_ip: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8" }
+  - { id: r-chrome, action: proxy, upstream: socks,
+      targets: "chrome.exe", dst_port: "*" }
+```
+
+```python
+from proxycore.api import start_proxy
+
+with start_proxy("D:/cfg/chrome.yaml") as ppx:   # 管理员终端
+    print(ppx.status())
+    print(ppx.sessions(limit=20))
+```
+
+规则自上而下、首个命中生效；启动后只影响**新建立**的连接。
+完整步骤、验证方法与常见坑见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
+
 ### 显式配置与测试转发
 
 ```python
@@ -541,7 +587,7 @@ src/proxycore/          核心包
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（619 passed / 4 skipped）
+tests/                  测试套件（624 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -562,7 +608,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ## 排错
 
-见 [`docs/11-调试排错手册.md`](docs/11-调试排错手册.md)（症状 → 定位 → 解决）。
+见 [`docs/11-调试排错手册.md`](https://github.com/Longersking/procproxy/blob/master/docs/11-%E8%B0%83%E8%AF%95%E6%8E%92%E9%94%99%E6%89%8B%E5%86%8C.md)（症状 → 定位 → 解决）。
 
 最常见的一条：**`[WinError 5] 拒绝访问` = 不是管理员**。
 
@@ -572,7 +618,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 619 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 624 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.2 → procproxy-0.1.3}/README.md

@@ -35,7 +35,7 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 pip install procproxy
 procproxy init          # 生成 ~/.procproxy/config.yaml
 procproxy doctor        # 环境自检
-procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+procproxy forward --process WeChat.exe --port 8848   # 真实转发（需管理员）
 ```
 
 安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
@@ -211,7 +211,7 @@ python procproxy.py Weixin.exe WeChatAppEx.exe --port 8848
 ⚠️ 只有 ① 没有 ② → 端口填错了（**要填抓包工具的 MITM 监听口，不是它的 Web 管理口**）。
 ① ② 都正常但内容看不懂 → 那是 TLS，不是转发的问题。
 
-完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](docs/14-把进程流量转发给抓包工具.md)。
+完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](https://github.com/Longersking/procproxy/blob/master/docs/14-%E6%8A%8A%E8%BF%9B%E7%A8%8B%E6%B5%81%E9%87%8F%E8%BD%AC%E5%8F%91%E7%BB%99%E6%8A%93%E5%8C%85%E5%B7%A5%E5%85%B7.md)。
 
 ---
 
@@ -301,14 +301,14 @@ rules:                                      # 自上而下，**首个命中生
 7. 都没命中     → profile.default_action
 ```
 
-完整语义见 [`docs/07-规则引擎与Profile格式.md`](docs/07-规则引擎与Profile格式.md)。
+完整语义见 [`docs/07-规则引擎与Profile格式.md`](https://github.com/Longersking/procproxy/blob/master/docs/07-%E8%A7%84%E5%88%99%E5%BC%95%E6%93%8E%E4%B8%8EProfile%E6%A0%BC%E5%BC%8F.md)。
 
 ---
 
 ## 编程接口
 
 `proxycore.api` 是与 CLI 共用同一套配置、规则引擎和会话表的 SDK。
-完整教程见 [`docs/15-编程接口与SDK.md`](docs/15-编程接口与SDK.md)。
+完整教程见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
 
 ### 30 秒：零配置启动
 
@@ -334,6 +334,52 @@ with start_proxy() as ppx:          # 不需要任何配置文件
 状态查询和联调；要真实抓包请用 `backend="windivert"`（需管理员）或
 `procproxy init` 生成自己的配置。
 
+### 初始化：生成一份可编辑配置
+
+```python
+from proxycore.api import init_config
+
+path = init_config(
+    "D:/cfg/procproxy.yaml",   # 省略则用 PROCPROXY_CONFIG 或 ~/.procproxy/config.yaml
+    backend="windivert",       # 真抓包需管理员；联调用 "null"
+    sink_port=19080,
+)
+print(path)                    # 绝对路径；等价于 procproxy init
+```
+
+生成的是最小模板，`upstreams` / `rules` 仍为空，需要按下面的案例补上。
+
+### 代理一个进程（最小完整配置）
+
+```yaml
+version: 1
+service:
+  sink: { host: 127.0.0.1, port: 19080 }
+  backend: windivert            # 真抓包；联调改 null
+profile:
+  name: chrome-via-socks
+  default_action: direct
+  dns_mode: remote
+upstreams:
+  - { alias: socks, kind: socks5, host: 127.0.0.1, port: 1080, auth: none }
+rules:
+  - { id: r-private, action: direct, targets: "*",
+      dst_ip: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8" }
+  - { id: r-chrome, action: proxy, upstream: socks,
+      targets: "chrome.exe", dst_port: "*" }
+```
+
+```python
+from proxycore.api import start_proxy
+
+with start_proxy("D:/cfg/chrome.yaml") as ppx:   # 管理员终端
+    print(ppx.status())
+    print(ppx.sessions(limit=20))
+```
+
+规则自上而下、首个命中生效；启动后只影响**新建立**的连接。
+完整步骤、验证方法与常见坑见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
+
 ### 显式配置与测试转发
 
 ```python
@@ -502,7 +548,7 @@ src/proxycore/          核心包
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（619 passed / 4 skipped）
+tests/                  测试套件（624 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -523,7 +569,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ## 排错
 
-见 [`docs/11-调试排错手册.md`](docs/11-调试排错手册.md)（症状 → 定位 → 解决）。
+见 [`docs/11-调试排错手册.md`](https://github.com/Longersking/procproxy/blob/master/docs/11-%E8%B0%83%E8%AF%95%E6%8E%92%E9%94%99%E6%89%8B%E5%86%8C.md)（症状 → 定位 → 解决）。
 
 最常见的一条：**`[WinError 5] 拒绝访问` = 不是管理员**。
 
@@ -533,7 +579,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 619 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 624 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.2 → procproxy-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "procproxy"
-version = "0.1.2"
+version = "0.1.3"
 description = "ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理"
 readme = "README.md"
 requires-python = ">=3.10"

{procproxy-0.1.2 → procproxy-0.1.3/src/procproxy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.2
+Version: 0.1.3
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -74,7 +74,7 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 pip install procproxy
 procproxy init          # 生成 ~/.procproxy/config.yaml
 procproxy doctor        # 环境自检
-procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+procproxy forward --process WeChat.exe --port 8848   # 真实转发（需管理员）
 ```
 
 安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
@@ -250,7 +250,7 @@ python procproxy.py Weixin.exe WeChatAppEx.exe --port 8848
 ⚠️ 只有 ① 没有 ② → 端口填错了（**要填抓包工具的 MITM 监听口，不是它的 Web 管理口**）。
 ① ② 都正常但内容看不懂 → 那是 TLS，不是转发的问题。
 
-完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](docs/14-把进程流量转发给抓包工具.md)。
+完整指南（含排错与参数表）见 [`docs/14-把进程流量转发给抓包工具.md`](https://github.com/Longersking/procproxy/blob/master/docs/14-%E6%8A%8A%E8%BF%9B%E7%A8%8B%E6%B5%81%E9%87%8F%E8%BD%AC%E5%8F%91%E7%BB%99%E6%8A%93%E5%8C%85%E5%B7%A5%E5%85%B7.md)。
 
 ---
 
@@ -340,14 +340,14 @@ rules:                                      # 自上而下，**首个命中生
 7. 都没命中     → profile.default_action
 ```
 
-完整语义见 [`docs/07-规则引擎与Profile格式.md`](docs/07-规则引擎与Profile格式.md)。
+完整语义见 [`docs/07-规则引擎与Profile格式.md`](https://github.com/Longersking/procproxy/blob/master/docs/07-%E8%A7%84%E5%88%99%E5%BC%95%E6%93%8E%E4%B8%8EProfile%E6%A0%BC%E5%BC%8F.md)。
 
 ---
 
 ## 编程接口
 
 `proxycore.api` 是与 CLI 共用同一套配置、规则引擎和会话表的 SDK。
-完整教程见 [`docs/15-编程接口与SDK.md`](docs/15-编程接口与SDK.md)。
+完整教程见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
 
 ### 30 秒：零配置启动
 
@@ -373,6 +373,52 @@ with start_proxy() as ppx:          # 不需要任何配置文件
 状态查询和联调；要真实抓包请用 `backend="windivert"`（需管理员）或
 `procproxy init` 生成自己的配置。
 
+### 初始化：生成一份可编辑配置
+
+```python
+from proxycore.api import init_config
+
+path = init_config(
+    "D:/cfg/procproxy.yaml",   # 省略则用 PROCPROXY_CONFIG 或 ~/.procproxy/config.yaml
+    backend="windivert",       # 真抓包需管理员；联调用 "null"
+    sink_port=19080,
+)
+print(path)                    # 绝对路径；等价于 procproxy init
+```
+
+生成的是最小模板，`upstreams` / `rules` 仍为空，需要按下面的案例补上。
+
+### 代理一个进程（最小完整配置）
+
+```yaml
+version: 1
+service:
+  sink: { host: 127.0.0.1, port: 19080 }
+  backend: windivert            # 真抓包；联调改 null
+profile:
+  name: chrome-via-socks
+  default_action: direct
+  dns_mode: remote
+upstreams:
+  - { alias: socks, kind: socks5, host: 127.0.0.1, port: 1080, auth: none }
+rules:
+  - { id: r-private, action: direct, targets: "*",
+      dst_ip: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8" }
+  - { id: r-chrome, action: proxy, upstream: socks,
+      targets: "chrome.exe", dst_port: "*" }
+```
+
+```python
+from proxycore.api import start_proxy
+
+with start_proxy("D:/cfg/chrome.yaml") as ppx:   # 管理员终端
+    print(ppx.status())
+    print(ppx.sessions(limit=20))
+```
+
+规则自上而下、首个命中生效；启动后只影响**新建立**的连接。
+完整步骤、验证方法与常见坑见 [`docs/15-编程接口与SDK.md`](https://github.com/Longersking/procproxy/blob/master/docs/15-%E7%BC%96%E7%A8%8B%E6%8E%A5%E5%8F%A3%E4%B8%8ESDK.md)。
+
 ### 显式配置与测试转发
 
 ```python
@@ -541,7 +587,7 @@ src/proxycore/          核心包
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（619 passed / 4 skipped）
+tests/                  测试套件（624 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -562,7 +608,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ## 排错
 
-见 [`docs/11-调试排错手册.md`](docs/11-调试排错手册.md)（症状 → 定位 → 解决）。
+见 [`docs/11-调试排错手册.md`](https://github.com/Longersking/procproxy/blob/master/docs/11-%E8%B0%83%E8%AF%95%E6%8E%92%E9%94%99%E6%89%8B%E5%86%8C.md)（症状 → 定位 → 解决）。
 
 最常见的一条：**`[WinError 5] 拒绝访问` = 不是管理员**。
 
@@ -572,7 +618,7 @@ tests/                  测试套件（619 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 619 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 624 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.2 → procproxy-0.1.3}/src/procproxy.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/proxycore/canproxy.py
 src/proxycore/checkroute.py
 src/proxycore/cli.py
 src/proxycore/config.py
+src/proxycore/config_init.py
 src/proxycore/config_source.py
 src/proxycore/forward.py
 src/proxycore/ipc.py

{procproxy-0.1.2 → procproxy-0.1.3}/src/proxycore/__init__.py

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

{procproxy-0.1.2 → procproxy-0.1.3}/src/proxycore/api.py

@@ -50,6 +50,7 @@ from pathlib import Path
 from typing import Any
 
 from .config import Config, ConfigError, ConfigManager
+from .config_init import create_config_file
 from .config_source import ORIGIN_EXPLICIT, ORIGIN_OBJECT, normalize_config_path, resolve_config_source
 from .log import EventLogger, build_logger, get_logger
 from .runtime import Runtime
@@ -90,6 +91,34 @@ def load_config(
     return config
 
 
+def init_config(
+    path: str | os.PathLike[str] | None = None,
+    *,
+    backend: str = "null",
+    sink_port: int = 19080,
+    force: bool = False,
+) -> Path:
+    """从内置模板生成一份可编辑配置，返回绝对路径。
+
+    等价于 `procproxy init`，但可以在 Python 里调用：
+
+    ```python
+    from proxycore.api import init_config
+
+    path = init_config(backend="windivert", sink_port=19080)
+    # 之后编辑 path 里的 upstreams / rules，再用 start_proxy(path) 启动
+    ```
+
+    * `path=None` → `PROCPROXY_CONFIG` 或 `~/.procproxy/config.yaml`；
+    * 目标已存在时默认拒绝覆盖（`config_exists`），`force=True` 才覆盖；
+    * 失败抛 `ProxyStartError`，`code` 同底层 `ConfigError.code`。
+    """
+    try:
+        return create_config_file(path, backend=backend, sink_port=sink_port, force=force)
+    except ConfigError as exc:
+        raise _wrap_config_error(exc) from exc
+
+
 def _resolve_and_load(
     config: Config | str | os.PathLike[str] | None, *, check_sink: bool = False
 ) -> Config:
@@ -308,6 +337,7 @@ def run_forever(config: Config | str | os.PathLike[str] | None = None, **kwargs:
 __all__ = [
     "ProxyHandle",
     "ProxyStartError",
+    "init_config",
     "load_config",
     "make_runtime",
     "run_forever",

{procproxy-0.1.2 → procproxy-0.1.3}/src/proxycore/cli.py

@@ -16,10 +16,17 @@ import time
 from pathlib import Path
 from typing import Any
 
-import yaml
-
 from proxycore import __version__
-from proxycore.config import E_CONFIG_NOT_FOUND, Config, ConfigError, ConfigManager, port_in_use
+from proxycore.config import (
+    E_CONFIG_ARGUMENT_INVALID,
+    E_CONFIG_EXISTS,
+    E_CONFIG_NOT_FOUND,
+    E_SINK_PORT_UNAVAILABLE,
+    Config,
+    ConfigError,
+    ConfigManager,
+    port_in_use,
+)
 from proxycore.config_source import (
     DEFAULT_CONFIG,
     ORIGIN_ENV,
@@ -243,36 +250,25 @@ def cmd_config(args: argparse.Namespace) -> int:
 
 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
+    from proxycore.config_init import create_config_file
 
-    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)
+        target = create_config_file(
+            args.path or None,
+            backend=args.backend,
+            sink_port=args.sink_port,
+            force=args.force,
+        )
     except ConfigError as exc:
-        with contextlib.suppress(OSError):
-            target.unlink()
-        print(f"生成的配置未通过校验：{exc.code} — {exc.message}", file=sys.stderr)
+        if exc.code in {
+            E_CONFIG_EXISTS,
+            E_CONFIG_NOT_FOUND,
+            E_SINK_PORT_UNAVAILABLE,
+            E_CONFIG_ARGUMENT_INVALID,
+        }:
+            print(exc.message, file=sys.stderr)
+        else:
+            print(f"生成的配置未通过校验：{exc.code} — {exc.message}", file=sys.stderr)
         return 2
 
     print(f"已生成配置: {target}")

{procproxy-0.1.2 → procproxy-0.1.3}/src/proxycore/config.py

@@ -44,6 +44,8 @@ E_PROFILE_OPTION_UNSUPPORTED = "profile_option_unsupported"
 E_CONFIG_NOT_FOUND = "config_not_found"
 E_CONFIG_UNREADABLE = "config_unreadable"
 E_CONFIG_PARSE_INVALID = "config_parse_invalid"
+E_CONFIG_EXISTS = "config_exists"
+E_CONFIG_ARGUMENT_INVALID = "config_invalid_argument"
 # 运行时错误码
 E_BACKEND_UNAVAILABLE = "E_BACKEND_UNAVAILABLE"
 

procproxy-0.1.3/src/proxycore/config_init.py

@@ -0,0 +1,85 @@
+"""生成一份可编辑的启动配置（CLI `init` 与 Python `api.init_config` 共用）。
+
+模板来自安装包里的 `data/default.yaml`，只覆盖 backend 与 sink 端口；
+upstreams / rules 留空，由用户或调用方按需填写。写入后立刻用
+`Config.load` 校验，失败则删除半成品文件。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+from .config import (
+    E_CONFIG_ARGUMENT_INVALID,
+    E_CONFIG_EXISTS,
+    E_CONFIG_NOT_FOUND,
+    E_CONFIG_UNREADABLE,
+    E_SINK_PORT_UNAVAILABLE,
+    Config,
+    ConfigError,
+)
+from .config_source import packaged_default_config, user_config_path
+
+VALID_BACKENDS = ("null", "windivert")
+
+
+def create_config_file(
+    path: str | os.PathLike[str] | None = None,
+    *,
+    backend: str = "null",
+    sink_port: int = 19080,
+    force: bool = False,
+) -> Path:
+    """从内置模板生成配置文件，返回绝对路径。
+
+    * `path=None`：写到 `PROCPROXY_CONFIG` 或 `~/.procproxy/config.yaml`；
+    * `force=False`：目标已存在时抛 `config_exists`，绝不覆盖；
+    * `backend`：`null`（联调）或 `windivert`（真抓包，需管理员）；
+    * 生成后立即校验，校验失败会删除文件并抛出原始 `ConfigError`。
+    """
+    target = (Path(path) if path else user_config_path()).expanduser()
+    target = (Path.cwd() / target).resolve() if not target.is_absolute() else target.resolve()
+
+    if target.exists() and not force:
+        raise ConfigError(E_CONFIG_EXISTS, f"配置文件已存在: {target}（force=True 覆盖）")
+    if backend not in VALID_BACKENDS:
+        raise ConfigError(
+            E_CONFIG_ARGUMENT_INVALID,
+            f"未知 backend {backend!r}（可选：{', '.join(VALID_BACKENDS)}）",
+        )
+    if not 1024 <= sink_port <= 65535:
+        raise ConfigError(
+            E_SINK_PORT_UNAVAILABLE,
+            f"sink 端口必须在 1024-65535，当前 {sink_port}",
+        )
+
+    packaged = packaged_default_config()
+    if packaged is None:
+        raise ConfigError(E_CONFIG_NOT_FOUND, "安装包缺少内置默认配置，请重新安装 procproxy")
+
+    doc = yaml.safe_load(packaged.read_text(encoding="utf-8")) or {}
+    service = doc.setdefault("service", {})
+    service["backend"] = backend
+    sink = service.setdefault("sink", {})
+    sink.setdefault("host", "127.0.0.1")
+    sink["port"] = sink_port
+
+    header = "# ProcProxy 配置（由 procproxy init / proxycore.api.init_config 生成）\n"
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            header + yaml.safe_dump(doc, allow_unicode=True, sort_keys=False),
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        raise ConfigError(E_CONFIG_UNREADABLE, f"无法写入配置 {target}: {exc}") from exc
+
+    try:
+        Config.load(target)
+    except ConfigError:
+        target.unlink(missing_ok=True)
+        raise
+    return target