feat: 对接Python，暴露接口

README.md

@@ -7,26 +7,32 @@ This subtree is intentionally standalone. The Go code stays in place as the beha
 ## Build
 
 ```bash
-cd c
-make
+make -j$(nproc)
 ```
 
 Build outputs:
 
-- `c/bin/udpserver`
-- `c/bin/udppeer`
-- `c/bin/udpping`
-- `c/bin/udprelay`
-- `c/bin/kcpserver`
-- `c/bin/kcppeer`
-- `c/bin/kcpping`
+- `./bin/udpserver`
+- `./bin/udppeer`
+- `./bin/udpping`
+- `./bin/udprelay`
+- `./bin/kcpserver`
+- `./bin/kcppeer`
+- `./bin/kcpping`
+
+Python extension build:
+
+```bash
+make python-ext
+make python-install
+```
 
 ## Run On Different Machines
 
 Server `D` runs the KCP hub on `0.0.0.0:10909`:
 
 ```bash
-./c/bin/kcpserver -listen 0.0.0.0:10909 \
+./bin/kcpserver -listen 0.0.0.0:10909 \
   -kcp-ts-debug-log logs/d-kcp-ts.jsonl \
   -kcp-session-stats-log logs/d-kcp-stats.jsonl
 ```
@@ -34,13 +40,13 @@ Server `D` runs the KCP hub on `0.0.0.0:10909`:
 Relay `C` runs a raw UDP forwarder to `D`:
 
 ```bash
-./c/bin/kcpserver -mode=relay -listen 0.0.0.0:10909 -relay-remote 172.21.32.15:10909
+./bin/kcpserver -mode=relay -listen 0.0.0.0:10909 -relay-remote 172.21.32.15:10909
 ```
 
 Peer `A` dials `D` through relay `C`:
 
 ```bash
-./c/bin/kcppeer -id peer-a -server 172.21.32.15:10909 -relay-via 106.55.173.235:10909 \
+./bin/kcppeer -id peer-a -server 172.21.32.15:10909 -relay-via 106.55.173.235:10909 \
   -inbox-dir inbox/a \
   -latency-log logs/a-latency.jsonl \
   -kcp-ts-debug-log logs/a-kcp-ts.jsonl \
@@ -50,7 +56,7 @@ Peer `A` dials `D` through relay `C`:
 Peer `B` dials `D` directly:
 
 ```bash
-./c/bin/kcppeer -id peer-b -server 81.70.156.140:10909 \
+./bin/kcppeer -id peer-b -server 81.70.156.140:10909 \
   -inbox-dir inbox/b \
   -latency-log logs/b-latency.jsonl \
   -kcp-ts-debug-log logs/b-kcp-ts.jsonl \
@@ -60,13 +66,33 @@ Peer `B` dials `D` directly:
 Optional ping / echo tools:
 
 ```bash
-./c/bin/kcpping -id peer-a -server 106.55.173.235:10909 -echo
-./c/bin/kcpping -id peer-b -server 81.70.156.140:10909 -to peer-a -count 20 -interval 100ms
-./c/bin/udpserver -listen 0.0.0.0:9001
-./c/bin/udppeer -id peer-a -server 127.0.0.1:9001
-./c/bin/udpping -id pinger -server 127.0.0.1:9001 -to peer-a -count 20
+./bin/kcpping -id peer-a -server 106.55.173.235:10909 -echo
+./bin/kcpping -id peer-b -server 81.70.156.140:10909 -to peer-a -count 20 -interval 100ms
+./bin/udpserver -listen 0.0.0.0:9001
+./bin/udppeer -id peer-a -server 127.0.0.1:9001
+./bin/udpping -id pinger -server 127.0.0.1:9001 -to peer-a -count 20
 ```
 
+Python control/video demos use two KCP sessions:
+
+- `peer-a-ctrl <-> peer-b-ctrl` for small binary control packets
+- `peer-b-video -> peer-a-video` for larger binary video frames
+
+Example demo entry points:
+
+- `udp_keyboard_sender.py`
+- `udp_xbox_sender.py`
+- `udp_fsm_controller.py`
+- `omnisocket_video_sender.py`
+- `omnisocket_video_receiver.py`
+- `scripts/kcp_control_benchmark.py`
+
+Python `recv_into()` note:
+
+- The writable buffer must be large enough for the full incoming payload.
+- If the buffer is too small, `recv_into()` reports the required size but the current frame has already been consumed and is lost.
+- For the video demo, keep `video_receiver.buffer_bytes >= video_sender.frame_bytes`.
+
 ## Interactive Commands
 
 `udppeer` and `kcppeer` support the same interactive shell:
@@ -83,6 +109,8 @@ quit
 
 - The C project targets Linux only.
 - It preserves the Go wire format for UDP datagrams and KCP stream frames.
+- It now supports `binary` payload messages in addition to `text`, `file`, `register`, and `error`.
+- Python `Session.recv_into()` is a zero-copy receive helper for already-sized buffers; it does not retain oversized frames for a retry.
 - It keeps runtime JSONL logging, UDP TX timestamp debug, KCP packet debug, and KCP session stats.
 - Offline `latencysummary` and HTML chart generation are intentionally not migrated.
 - No automated C tests are included in this subtree; validation is expected to happen on Linux via `make` and manual smoke tests.