添加协议层数据统计结构，日志文件保存在 Logs 下

openspec/specs/kcp-transport/spec.md

@@ -1,4 +1,4 @@
-# kcp-transport Specification
+# kcp-transport Specification
 
 ## Purpose
 TBD - created by archiving change introduce-kcp-transport. Update Purpose after archive.
@@ -61,3 +61,15 @@ The codebase SHALL NOT keep a directly instantiable `ReliableUdpTransport` entry
 - **WHEN** developers inspect the transport implementations available to runtime code
 - **THEN** they do not find a usable `ReliableUdpTransport` class representing reliable delivery
 - **THEN** the remaining transport naming makes the reliable-versus-unreliable boundary explicit
+### Requirement: KCP transport can emit structured metrics through an optional module
+`KcpTransport` SHALL allow callers to provide an optional transport metrics module without changing the shared `ITransport` contract. While running, `KcpTransport` MUST publish transport lifecycle, session creation and disposal, logical payload traffic, UDP datagram traffic, and transport-stage errors into that module, and it MUST expose a current metrics snapshot query for diagnostics and tests.
+
+#### Scenario: Injected metrics module receives KCP traffic statistics
+- **WHEN** a caller starts a `KcpTransport`, sends and receives payloads, and then stops the transport
+- **THEN** the injected metrics module receives enough events to aggregate the run's payload, datagram, session, and error statistics
+- **THEN** diagnostics code can query the current snapshot without reading the exported report file
+
+#### Scenario: Default metrics module exports on KCP transport shutdown
+- **WHEN** a caller uses `KcpTransport` without providing a custom metrics module and later calls `Stop()`
+- **THEN** the transport uses its built-in metrics module to finalize the run summary during shutdown
+- **THEN** the transport emits the final JSON report and compact console summary exactly once for that run

openspec/specs/transport-metrics-reporting/spec.md

@@ -0,0 +1,29 @@
+# transport-metrics-reporting Specification
+
+## Purpose
+Define the shared transport metrics contract and final-run reporting behavior that transport implementations can use without depending on Unity or a concrete transport implementation.
+
+## Requirements
+### Requirement: Transport metrics module is transport-agnostic and host-agnostic
+The project SHALL provide a transport metrics module contract and snapshot model that do not depend on Unity runtime types or a specific `ITransport` implementation. Transport implementations MUST be able to publish lifecycle, traffic, session, and error events through that contract without exposing Unity-specific dependencies.
+
+#### Scenario: KCP transport can publish into a shared metrics contract
+- **WHEN** `KcpTransport` is constructed with a metrics module implementation
+- **THEN** it can report start, shutdown, payload, datagram, session, and error events through that contract
+- **THEN** the metrics module remains reusable outside Unity-specific hosts
+
+### Requirement: Metrics summaries include global and per-peer transport statistics
+The metrics module SHALL aggregate one run summary from transport start to transport stop, including global totals and per-peer totals keyed by remote endpoint. The summary MUST include at least payload counts and bytes, datagram counts and bytes, session lifecycle totals, and error counts.
+
+#### Scenario: Multi-session traffic is preserved per remote endpoint
+- **WHEN** a server transport communicates with multiple remote endpoints during one run
+- **THEN** the final summary contains transport totals for the whole run
+- **THEN** it also contains separate per-peer summaries so one endpoint's traffic and errors do not overwrite another's
+
+### Requirement: Metrics module can finalize and export one run summary
+The metrics module SHALL support end-of-run finalization that produces one durable summary per run and MUST make repeated finalization idempotent. The default reporting path MUST write a JSON report and emit a compact console summary when finalization occurs.
+
+#### Scenario: Transport stop exports a single final summary
+- **WHEN** a transport run reaches shutdown and triggers metrics finalization
+- **THEN** one JSON summary is written for that run and one compact console summary is printed
+- **THEN** a repeated shutdown call does not create a duplicate report for the same run