procproxy 0.1.2__tar.gz → 0.1.4__tar.gz

procproxy-0.1.4/MANIFEST.in

@@ -0,0 +1,2 @@
+graft docs
+graft examples

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.2
+Version: 0.1.4
 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,16 @@ 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)。
+**以下全部只用 `import proxycore`，不需要运行 `procproxy` 命令。**
+完整教程见 [`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)，
+可执行契约见 [`examples/verify_sdk.py`](https://github.com/Longersking/procproxy/blob/master/examples/verify_sdk.py)。
 
 ### 30 秒：零配置启动
 
@@ -373,6 +375,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
@@ -540,8 +588,9 @@ src/proxycore/          核心包
   ├── canproxy.py / checkroute.py / probe.py / pathsetup.py  ← 其余子命令
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
+examples/               纯 Python 示例（proxy_process.py / verify_sdk.py）
 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 +611,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 +621,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.4}/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,16 @@ 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)。
+**以下全部只用 `import proxycore`，不需要运行 `procproxy` 命令。**
+完整教程见 [`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)，
+可执行契约见 [`examples/verify_sdk.py`](https://github.com/Longersking/procproxy/blob/master/examples/verify_sdk.py)。
 
 ### 30 秒：零配置启动
 
@@ -334,6 +336,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
@@ -501,8 +549,9 @@ src/proxycore/          核心包
   ├── canproxy.py / checkroute.py / probe.py / pathsetup.py  ← 其余子命令
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
+examples/               纯 Python 示例（proxy_process.py / verify_sdk.py）
 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 +572,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 +582,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.4/docs/00-/346/236/266/346/236/204/344/270/216/351/230/205/350/257/273/350/267/257/347/272/277.md

@@ -0,0 +1,152 @@
+# 00 · 架构与阅读路线
+
+> 这份文档写给**想读源码的人**。
+> 只用工具看 `README.md`；想程序化调用看 [`15-编程接口与SDK.md`](15-编程接口与SDK.md) 和 `AGENTS.md`。
+
+---
+
+## 1. 一句话
+
+ProcProxy 只做一件事：认出某个进程发出的 TCP 连接，把它**改道**到本机的一个
+**sink** 端口，再由 sink 经你指定的**上游代理**转发出去。目标进程全程不知道。
+
+用比喻说：保安认出这是微信寄的信，把收件地址改成"本小区代收点"（sink），
+代收点再按你的吩咐让快递公司（上游代理）寄出去。回信时保安把信封改回原样。
+不拆信（不解密）、不问微信要密码（不注入 DLL）。
+
+---
+
+## 2. 五个概念
+
+| 术语 | 是什么 | 代码位置 |
+|---|---|---|
+| **sink** | 本机的一个监听端口（默认 19080）。被改道的连接都落到这里 | `tunnel/sink.py` |
+| **改道** | 改写报文的目的地址到 sink，再重新注入网络栈 | `backend/windivert/` |
+| **回注** | 把改写后的包"送回去"。必须同时翻方向标志，否则内核会丢弃 | `windivert/__init__.py:415` |
+| **上游** | 你指定的代理出口（SOCKS5 / SOCKS4 / HTTP CONNECT） | `upstream/` |
+| **路线 A** | 本仓库唯一的数据面方案：用户态 WinDivert。历史上的内核方案（路线 B）已移除 | `backend/windivert/` |
+
+两个容易混的：
+
+* **`backend_id`**：路线 A 里它就是**客户端源端口**。sink 靠它反查原始目标。
+* **环路熔断**：拦截器自己连上游时会被自己再抓一遍，所以有一套守卫 + 熔断防止无限循环。
+  规则匹配顺序里的 G1–G4 就是这四道守卫。
+
+---
+
+## 3. 一条连接的完整路径
+
+按代码的**实际调用顺序**排，不是按目录顺序。
+
+### 第一段：抓包与决策（WinDivert 捕获线程）
+
+```
+WinDivertBackend._capture_loop             backend/windivert/__init__.py:292
+  └─ _handle_packet                        backend/windivert/__init__.py:316
+       ├─ 解析 IP/TCP → 构造 ConnRequest    backend/windivert/__init__.py:485
+       ├─ self.decide(conn)                backend/windivert/__init__.py:492
+       │    └─ BaseBackend.decide          backend/base.py:117
+       │         └─ Runtime.decide         runtime.py:208
+       │              ├─ rules.decide      runtime.py:224  →  rules.py:550
+       │              └─ record_decision   runtime.py:240  →  sessions.py:282
+       │                   └─ put_pending                        sessions.py:77
+       ├─ BLOCK  → 不回注（丢弃）           backend/windivert/__init__.py:495
+       ├─ DIRECT → 原样放行                backend/windivert/__init__.py:502
+       └─ PROXY  → 先记账，再改道           backend/windivert/__init__.py:510
+                    └─ _redirect_to_sink   backend/windivert/__init__.py:415
+```
+
+**为什么"先记账再改道"**：sink 收到连接时只能看到客户端源端口，必须靠这张表
+反查原始目标。顺序反了，在 TIME_WAIT 撞车时会查不到。
+
+### 第二段：sink 落地与转发（sink 工作线程）
+
+```
+Sink._accept_loop                          tunnel/sink.py:149
+  └─ _accept_one                           tunnel/sink.py:163
+       └─ _handle_client                   tunnel/sink.py:175
+            ├─ backend.lookup_original     tunnel/sink.py:186
+            │    用 backend_id 反查原始目标（查不到就关闭，不猜、不直连）
+            ├─ sessions.pop_pending        tunnel/sink.py:204
+            ├─ _make_dialer                tunnel/sink.py:212 / :300
+            ├─ dial_tcp_sync               tunnel/sink.py:238 → upstream/base.py:55
+            └─ relay_bidirectional         tunnel/sink.py:253 → tunnel/relay.py:93
+```
+
+### 反向路径
+
+sink 的应答要从 `127.0.0.1:<sink>` 改回"来自原始目标"，否则客户端三次握手完不成。
+这段在 `_reflect_sink_reply`（`backend/windivert/__init__.py:356`），
+由同一个 `_handle_packet` 按"源端口 == sink 端口"分流进入。
+
+> 注意：`BaseBackend.redirect()`（`backend/base.py:59`）是**后端契约里的方法**，
+> 只有契约测试与压测工具直接调用。生产路径是在 `_handle_packet` 里内联完成的。
+
+---
+
+## 4. 规则匹配顺序（不可调换）
+
+```
+1. 未知 PID        → 按 on_unknown_pid 兜底
+2. 守卫 G1         → 回环 / 私网 / 链路本地 → DIRECT
+3. 守卫 G2         → 自身进程 → DIRECT
+4. 守卫 G3         → 上游 / 本地 DNS 端点 → DIRECT
+5. 守卫 G4         → 同 (pid, dst) 熔断 → DIRECT + 告警
+6. 规则表          → 自上而下，首个命中生效
+7. 都没命中        → profile.default_action
+```
+
+守卫是**硬编码、不可配置**的，优先于任何用户规则。
+完整语义见 [`07-规则引擎与Profile格式.md`](07-规则引擎与Profile格式.md)。
+
+---
+
+## 5. 推荐阅读顺序
+
+不要按目录读。按这个顺序，每一步都能独立跑通验证。
+
+| 顺序 | 文件 | 为什么先读它 |
+|---|---|---|
+| 1 | `types.py` | 164 行、零逻辑，全是数据结构。搞懂 `ConnRequest` / `Decision` 就够了 |
+| 2 | `rules.py:550` 的 `decide()` | **纯函数**，不做 IO。整个项目的"大脑" |
+| 3 | `tunnel/sink.py:175` 的 `_handle_client()` | 88 行主流程，看懂"代收点怎么转寄" |
+| 4 | `tunnel/relay.py:93` | 只是搬字节，先看大框架 |
+| 5 | `upstream/` | 协议客户端，和本项目其余部分耦合最低 |
+| 6 | `backend/windivert/` | **最后看**。最难的一层，前面都懂了再回来 |
+
+配套的可执行材料：
+
+* `tests/unit/test_rules.py` —— `docs/07` 那 35 条规则矩阵的可执行版，按编号读；
+* `tests/tools/run_e2e.py` —— 2 秒跑通 sink → 上游 → 目标；
+* `tests/tools/api_demo.py` —— 三种编程式用法（完整说明见 `docs/15`）；
+* `learn_project.md` —— 一份 7 天读源码计划（按上面的顺序展开）。
+
+---
+
+## 6. 三十秒上手
+
+```bash
+pip install -e .
+python procproxy.py                    # 环境自检
+python tests/tools/run_demo.py         # 15 组免管理员自检
+python tests/tools/run_e2e.py          # 端到端链路
+python procproxy.py curl.exe --port 7890 --check-only   # 真用法的预演
+```
+
+真改道需要管理员：
+
+```bash
+python procproxy.py curl.exe --port 7890
+```
+
+---
+
+## 7. 边界（读代码前必须知道）
+
+* **只抓 TCP**。过滤器以 `tcp` 开头，UDP/QUIC 不进用户态，`udp_policy` 在路线 A 下空转。
+* **`dst_name` 规则永不命中**。抓到连接时应用早已 `getaddrinfo` 完成，只拿得到 IP。
+* **不改道就失败**。查不到原始目标一律关闭连接，绝不回落直连（那是一次真实 IP 泄漏）。
+* **上游端点必须写 IP 字面量**。环路守卫按 `(host, port)` 字面量比对，写域名护栏就失效。
+
+排错见 [`11-调试排错手册.md`](11-调试排错手册.md)；
+抓包工具场景见 [`14-把进程流量转发给抓包工具.md`](14-把进程流量转发给抓包工具.md)。

procproxy-0.1.4/docs/07-/350/247/204/345/210/231/345/274/225/346/223/216/344/270/216Profile/346/240/274/345/274/217.md

@@ -0,0 +1,197 @@
+# 07 · 规则引擎与 Profile 格式
+
+## 1. 规则语义（严格，实现必须与本文一致）
+
+### 1.1 匹配顺序（不可调整）
+
+```
+1. profile.rules 里 enabled=true 的规则，自上而下
+2. 首个命中的所有条件都满足的规则生效 → 返回其 action/upstream
+3. 未命中 → profile.default_action（默认 direct）
+```
+
+**前置守卫（在进入规则匹配前执行，优先于任何用户规则）**：
+
+| 顺序 | 守卫 | 结果 | 理由 |
+|---|---|---|---|
+| G1 | `dst` 属于回环/私网/链路本地，且未开 `keep_private_proxied` | DIRECT | 防止把内网流量送出去 + 防止环路 |
+| G2 | `pid ∈ self_pids`（服务自身、拦截器、上游代理进程） | DIRECT | 环路防护第一重 |
+| G3 | `dst ∈ upstream_endpoints ∪ local_dns_servers` | DIRECT | 环路防护第二重（上游地址变了要热更新此集合） |
+| G4 | 熔断：`(pid, dst)` 在 `window_s` 内命中次数 > `threshold` | DIRECT + 告警 | 环路防护第三重 |
+
+> 守卫要**可观测**：每条连接日志都带 `reason`：`guard-private` / `self-pid` / `upstream-endpoint` / `loop-breaker` / `rule:<id>` / `default`。
+
+### 1.2 字段语义
+
+| 字段 | 语法 | 说明 |
+|---|---|---|
+| `targets` | `curl.exe`、`fire*.exe`、`C:\path\app.exe`、多值 `a.exe;b.exe` | 大小写不敏感；`*`/`?` 通配；含 `\` 或 `/` 时按**完整路径**匹配，否则按**文件名**匹配 |
+| `dst_ip` | `1.2.3.4`、`10.0.0.0/8`、多值逗号分隔 | IPv4/IPv6 CIDR |
+| `dst_port` | `443`、`80,443`、`1000-2000`、`*` | 端口段含边界 |
+| `dst_name` | `*.corp.example`、`example.com` | **仅在域名已知时匹配**（见契约文档第 3 节的语义边界表） |
+| `proto` | `tcp`、`udp`、`*` | 默认 `*` |
+| `action` | `proxy`、`direct`、`block` | `proxy` 必须给 `upstream` |
+| `keep_private_proxied` | `true/false` | 显式代理私网（默认 false） |
+
+### 1.3 交互示例（顺序敏感，必须按此顺序理解）
+
+```yaml
+rules:
+  # ① 例外优先：公司内网即使规则②命中也直连
+  - {id: r1, action: direct, targets: "*", dst_ip: "10.20.0.0/16"}
+  # ② 浏览器走日本出口
+  - {id: r2, action: proxy, upstream: jp-http, targets: "chrome.exe;msedge.exe", dst_port: "443,80"}
+  # ③ curl 走 SOCKS5
+  - {id: r3, action: proxy, upstream: office-socks, targets: "curl.exe", dst_port: "*"}
+  # ④ 内网域名绕过
+  - {id: r4, action: direct, targets: "*", dst_name: "*.internal.corp"}
+  # ⑤ 默认拒绝所有 exe 的 53/UDP（防 DNS 泄漏，除非配置了代理 DNS）
+  - {id: r5, action: block, targets: "*.exe", dst_port: "53", proto: udp}
+```
+
+> 关键点：**"例外"必须写在"通用规则"之前**。这是与旧版工具兼容的行为约定：
+> 规则按从上到下的顺序处理，可通过上下移动调整顺序。
+> 规则编辑器必须支持上下移动，且拖动后自动重编号。
+
+### 1.4 粘性（`sticky_per_pid`）
+
+- `true`（默认）：同一 PID 的所有连接使用首次选定的上游（兼容旧版工具的行为约定）。
+  实现：`sessions.sticky[pid] = upstream_alias`，PID 退出（进程句柄失效）后清理。
+- `false`：每条连接独立按规则选上游。
+- 注意：粘性只影响**上游选择**，不影响规则匹配本身；规则命中改变时，粘性以**规则 id**
+  为键更新（`sticky[(pid, rule_id)] = upstream`），避免"规则改了但粘性还指向旧代理"。
+
+## 2. 旧版 Profile 字段映射（手工迁移）
+
+旧版工具的 Profile 使用 `.ppx`（v3）/`.prx`（v2）私有格式；本项目不解析该格式，
+只提供字段映射表，供用户手工迁移：
+
+| 旧版工具概念 | 本项目字段 | 备注 |
+|---|---|---|
+| Applications（进程） | `targets` | 支持 `fire*.exe` 通配语法（旧版工具使用相同语法） |
+| Target Hosts / Ports | `dst_ip` / `dst_port` | 旧版工具支持域名 → 对应 `dst_name`（注意其近似性） |
+| Action: Proxy/Direct/Block | `action` | 一一对应 |
+| Proxies（代理列表） | `upstreams[]` | 含类型/地址/认证/链式 |
+| Name Resolution | `dns_mode` | `local` = 本地 DNS 解析；`remote` = 通过上游远端解析 |
+| Services and Other Users | `handle_services` / `handle_other_users` | 尚未接入数据面：设为 `true` 会在校验期报 `profile_option_unsupported` |
+
+**导入器（未实现）**：本项目不提供 `.ppx/.prx` 自动解析；如需迁移，请按上表手工配置。
+
+## 3. 配置校验规则（`config.py` 必须实现，且每条都要有单测）
+
+| # | 校验 | 错误码 |
+|---|---|---|
+| V1 | `version == 1` | `config_version_unsupported` |
+| V2 | `action=proxy` 必须有 `upstream` 且别名存在 | `rule_upstream_missing` |
+| V3 | `chain` 不得成环，跳数 ≤ 8 | `upstream_chain_cycle` |
+| V4 | `dst_ip` 必须是合法 IP/CIDR；`dst_port` 段须 `lo<=hi` | `rule_match_invalid` |
+| V5 | `targets` 不能为空；长度 ≤ 1024 | `rule_targets_invalid` |
+| V6 | `sink.port` ∈ 1024–65535 且未被占用 | `sink_port_unavailable` |
+| V7 | `loop_breaker.threshold > 0 && window_s > 0` | `loop_breaker_invalid` |
+| V8 | `dns_mode ∈ {local, remote, bypass}`；`bypass` 时 `dns_bypass` 不能为空 | `dns_mode_invalid` |
+| V9 | 规则 id 唯一 | `rule_id_duplicate` |
+| V10 | 未知字段 → 警告（不报错，便于前向兼容） | `config_unknown_field` |
+
+### 3.1 热重载（原子）
+
+```python
+def reload(path) -> Profile:
+    doc = yaml.safe_load(open(path))
+    new = Profile.from_dict(doc)          # 校验失败抛 ConfigError
+    # 校验通过才替换
+    with lock:
+        old, CURRENT = CURRENT, new
+    log.info("config_reloaded", rules=len(new.rules), from_rules=len(old.rules))
+    return new
+```
+
+要求：
+- 重载**不得**断开已有会话；
+- 已建立会话的粘性保留（按 `rule_id` 与 `pid` 双键）；
+- 若 `sink.port` 变化 → 需要重建监听（本期直接禁止热改，要求重启服务，并给出明确提示）；
+- 若 `backend` 变化 → 明确报错要求重启。
+
+## 4. 规则测试矩阵
+
+| # | 输入（进程 / 目标 / 端口 / 协议） | 期望 | 覆盖点 |
+|---|---|---|---|
+| 1 | `curl.exe` / `1.1.1.1` / 443 / tcp | proxy(office-socks) | 基础命中 |
+| 2 | `CURL.EXE` / ... | proxy | 大小写不敏感 |
+| 3 | `curl.exe` / `1.1.1.1` / 22 | direct | 端口不匹配 |
+| 4 | `curl2.exe` / ... | direct | 通配不误命中（无 `*`） |
+| 5 | `firefox.exe` / `1.1.1.1` / 443 | proxy(jp-http) | 通配命中 `fire*.exe` |
+| 6 | 任一进程 / `127.0.0.1` / 80 | direct | 守卫 G1 回环 |
+| 7 | 任一进程 / `192.168.1.5` / 80 | direct | 守卫 G1 私网 |
+| 8 | 服务自身进程 / `8.8.8.8` / 443 | direct | 守卫 G2 |
+| 9 | 任一进程 / `<上游代理IP>` / 1080 | direct | 守卫 G3 |
+| 10 | `a.exe` / `8.8.8.8` / 53 / udp | block | 规则⑤ |
+| 11 | `a.exe` / `8.8.8.8` / 53 / tcp | direct(默认) | 协议区分 |
+| 12 | `x.exe` / `10.20.1.1` / 443 | direct | 规则①先于② |
+| 13 | 同 PID 二次连接不同目标 / 443 | 同上游 | 粘性 |
+| 14 | 同 PID 规则变更后再连接 | 用**新规则**的上游 | 粘性按 rule_id 键 |
+| 15 | 私网 + `keep_private_proxied=true` | proxy | 显式覆盖守卫 G1 |
+| 16 | 同 (pid,dst) 5s 内 60 次 | 第 51 次起 direct + 告警 | 熔断 |
+| 17 | `dst_name` 已知（从 DNS 缓存）匹配 `*.corp.example` | direct | 域名规则 |
+| 18 | `dst_name` 未知（只有 IP） | 不匹配域名规则 | 近似性边界 |
+| 19 | 端口 `1000-2000` 命中 1500 | proxy | 端口段 |
+| 20 | 端口段非法 `2000-1000` | 加载失败 | V4 |
+| 21 | 空 `targets` | 加载失败 | V5 |
+| 22 | `action=proxy` 缺 upstream | 加载失败 | V2 |
+| 23 | 上游链 A→B→A | 加载失败 | V3 |
+| 24 | 规则 id 重复 | 加载失败 | V9 |
+| 25 | `dns_mode=bypass` 但 bypass 列表为空 | 加载失败 | V8 |
+| 26 | IPv6 目标 `2001:db8::1` + `dst_ip: 2001:db8::/32` | proxy | v6 匹配 |
+| 27 | Unix 路径风格 targets（Linux 后端） `/usr/bin/curl` | proxy | 路径匹配 |
+| 28 | 受保护进程（path 为空）但名称可读 | 按名称规则命中 | 缺路径降级 |
+| 29 | 未知 PID（`pid=0`）+ `on_unknown_pid=proxy` | proxy | 未知处置策略 |
+| 30 | 未知 PID + `on_unknown_pid=direct`（默认） | direct + WARN | 默认安全 |
+| 31 | 规则 `enabled: false` | 跳过该规则 | 启停开关 |
+| 32 | 前向兼容：含未知字段 `future: 1` | 加载成功 + 警告 | V10 |
+| 33 | **决策路径抛异常** + `on_decide_error=block`（默认） | `block` + ERROR 日志 | 契约第 2 节：禁止静默直连 |
+| 34 | 决策路径抛异常 + `on_decide_error=direct` | `direct`（用户显式选择） | 可配置，非写死 |
+| 35 | 决策路径抛异常 + `on_decide_error=proxy` | 第一条 `action=proxy` 启用规则的上游；**一条都没有 → `block`** | 没有上游就没法建连，不能退回直连 |
+
+## 5. 规则引擎实现骨架（可直接抄）
+
+```python
+def decide(conn: ConnRequest, profile: Profile, sessions, guards) -> Decision:
+    # G1 私网/回环
+    if not guards.allow_private and is_private(conn.dst.addr):
+        return Decision(Action.DIRECT, reason="guard-private")
+    # G2 自身进程
+    if conn.proc.pid in guards.self_pids:
+        return Decision(Action.DIRECT, reason="self-pid")
+    # G3 上游/DNS 端点
+    if (conn.dst.addr, conn.dst.port) in guards.upstream_endpoints:
+        return Decision(Action.DIRECT, reason="upstream-endpoint")
+    # G4 熔断
+    if sessions.breaker.tripped(conn.proc.pid, conn.dst):
+        return Decision(Action.DIRECT, reason="loop-breaker")
+
+    name = guards.name_for_ip(conn.dst.addr)      # DNS 缓存，可能为 None
+    for r in profile.rules:
+        if not r.enabled:
+            continue
+        if not match_proc(r.targets, conn.proc):
+            continue
+        if not match_proto(r.proto, conn.proto):
+            continue
+        if not match_port(r.dst_port, conn.dst.port):
+            continue
+        if not match_ip(r.dst_ip, conn.dst.addr):
+            continue
+        if r.dst_name != "*":
+            if name is None:
+                continue                          # 域名未知 → 该规则不适用（不做近似猜测）
+            if not wildcard(r.dst_name, name):
+                continue
+        # 命中
+        up = r.upstream
+        if profile.sticky_per_pid and r.action is Action.PROXY:
+            up = sessions.sticky_upstream(conn.proc.pid, r.id, default=r.upstream)
+        return Decision(r.action, rule_id=r.id, upstream=up, reason=f"rule:{r.id}")
+    return Decision(profile.default_action, reason="default")
+```
+
+**性能要求**：`decide()` 必须 O(规则数)，单次 < 20µs（1000 条规则时 < 100µs）；
+禁止在 `decide()` 里做 DNS 解析、日志格式化（用惰性参数）、文件读取。