Add managed runtime accounting and probe APIs

[yiguodev]

概述

• 使用出站 tag 作为分享节点名称；统一分享解析，始终返回 config、usableCount 和 failedCount，支持 age 加密订阅。
• TestXray 仅通过 core.LoadConfig 验证配置，不创建或启动实例，也不保证配置能够启动或连接成功；移除 ProbeXray 和 CheckRoute。
• 批量测速支持延迟和出口位置请求，保留输入顺序与逐节点失败隔离；位置响应以原始 locationJson 返回，由 App 解析。
• 持久化本次连接的入站累计流量，通过带鉴权的 loopback HTTP 接口读取已保存快照；实时数值使用 Xray metrics，累计总量与重置由 App 管理。
• 保持现有功能，简化分享转换和运行统计中的重复流程、中间状态及内部错误处理；保留校验、文件锁、原子写入和关闭保护。
• 删除 native build-input metadata 记录，保留构建期间 go.mod / go.sum 的恢复逻辑。
• LibXrayAPIVersion 固定为 3，不在本版本内递增。

验证

• go test ./... -count=1
• go test -race ./xray -run 'TestRuntimeHTTP|TestRuntimeStoresRawCountersWithoutResetOrTotals|TestRuntimeWriteFailuresPreserveSavedFile|TestManagedRuntimeStartFailureAndStop' -count=1
• python3 build/test_build.py
• git diff --check

以上检查已在 macOS（darwin/arm64，Go 1.27.1）通过。本轮未重新打包 Android / Apple 原生产物，也未执行 Windows / Linux 平台运行验证。

[Copilot]

🔵 Needs a closer look

It introduces a broad API version bump and significant runtime/probing/persistence behavior changes across many subsystems that warrant final human verification.

Pull request overview

This PR expands libXray’s capabilities around draft validation/probing and managed runtime accounting, while updating the typed Invoke wire contract to API v4 and aligning documentation accordingly.

Changes:

• Add managed runtime accounting: periodic persistence of inbound counters and an optional authenticated loopback HTTP endpoint for reading the saved snapshot.
• Add/extend draft operations: build-only validation, isolated route checking, URL probing, and optional location probing for pingBatch.
• Update share parsing/export behavior (use outbound tag as the node name) and introduce build-input metadata recording for reproducible builds.

File summaries

File	Description
xray/xray.go	Adds managed runtime lifecycle alongside the managed core instance (start/stop integration).
xray/xray_test.go	Adds coverage ensuring temporary operations reject overlap with an active managed instance.
xray/validation.go	Introduces build-only config validation and overlap rejection for testXray execution.
xray/runtime.go	Implements runtime snapshot sampling, persistence, and ownership locking.
xray/runtime_test.go	Adds tests for snapshot semantics (raw counters, save behavior, ownership, restart behavior).
xray/runtime_http.go	Implements authenticated loopback HTTP snapshot serving with timeouts and header constraints.
xray/runtime_http_test.go	Tests auth, snapshot serving behavior, symlink rejection behavior, and concurrent reads.
xray/runtime_file.go	Adds non-Windows file locking and atomic replace with directory sync.
xray/runtime_file_windows.go	Adds Windows file locking and atomic replace semantics via Win32 APIs.
xray/probe.go	Adds a draft URL probe that routes/dials through a constructed draft instance without listening.
xray/probe_test.go	Tests probe routing/DNS behavior and URL safety constraints.
xray/ping_location_test.go	Adds tests for PingBatch location probing and probeLocation behavior.
xray/ping_batch.go	Extends ping batch results with optional location probing, and preserves latency behavior.
xray/check_route.go	Adds draft route checking using the real Router without starting the instance or dispatching the target.
xray/check_route_test.go	Adds tests for route evidence correctness, side-effect avoidance, timeouts, and invalid inputs.
share/xray_json.go	Switches outbound display naming to tag (instead of sendThrough).
share/validate_outbound.go	Removes legacy sendThrough nulling since it’s no longer used as name metadata.
share/parse_stats.go	Adds stats-enabled share parsing that returns usable/failed counts plus projected config.
share/parse_stats_test.go	Adds tests for candidate counting, error redaction, and legacy config equivalence.
share/parse_share_test.go	Updates expectations to reflect tag-based node naming and sendThrough preservation.
share/marshal_share.go	Refactors marshal to return projected count and support stats mode.
share/marshal_share_test.go	Updates expectations for tag vs sendThrough semantics in projected outputs.
share/generate_share_test.go	Updates tests to ensure outbound naming ignores sendThrough for node name selection.
share/clash_meta_test.go	Updates tests to validate tag is used for Clash-derived node names.
share/age.go	Refactors age decryption path to return plaintext + encrypted flag, enabling stats mode reuse.
readme/README.zh_CN.md	Updates Chinese docs for API v4, probes, ping location, runtime accounting, and build metadata.
README.md	Updates English docs for API v4, probes, ping location, runtime accounting, and build metadata.
invoke.go	Wires new API v4 methods/fields: stats conversion, ping location, testXray buildOnly/url probe, checkRoute, runtime metadata.
invoke_test.go	Adds tests for build-only semantics, checkRoute wiring/shape, runtime metadata typing, API version updates.
invoke_probes_test.go	Adds tests for share stats response shape, URL probe behavior, and ping location field encoding.
invoke_model.go	Updates typed Invoke contract to API v4 and adds new request/response models for new features.
desktop_bin/main.go	Adds optional -runtime host metadata file support for the desktop session core.
desktop_bin/main_test.go	Extends option parsing tests to cover the new -runtime flag.
build/test_build_metadata.py	Adds unit tests for build input metadata capture behavior and failure modes.
build/app/build.py	Implements build input metadata recording (commit, dirty state, modules, hashes, gomobile details).
AGENTS.md	Updates the repo’s documented API contract and runtime semantics to v4 and new features.
.gitignore	Ignores generated build input metadata JSON files.

Review details

• Files reviewed: 36/37 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The new test xray/runtime_http_test.go uses sync.WaitGroup.Go(...), which is not a standard sync.WaitGroup API and will fail to compile unless corrected.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 36/37 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It introduces broad, cross-cutting API/runtime/build changes (including a wire-contract version bump) that warrant careful human validation despite strong test coverage.

Review details

• Files reviewed: 41/42 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

xray/runtime_file_windows.go is missing a //go:build windows constraint, which will break non-Windows builds.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

invoke_model.go:14

• The PR description says the typed Invoke contract is updated to API v5, but the code (and updated docs) define and enforce LibXrayAPIVersion = 3. Please reconcile this by updating the PR description (or, if v5 is truly intended, adjusting the code/docs/tests consistently—note AGENTS.md explicitly says to keep the version fixed at 3 for this release).

type LibXrayMethod string

const LibXrayAPIVersion = 3

• Files reviewed: 37/38 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Significant new runtime persistence/HTTP surface and contract-adjacent behavior changes warrant final human review, and the PR description’s API version claim currently conflicts with the implemented v3 contract.

Review details

Suppressed comments (1)

invoke_model.go:15

• PR description says the typed Invoke contract is updated to API v5, but the implementation and docs in this PR keep the wire version fixed at 3 (LibXrayAPIVersion = 3; AGENTS/README examples use apiVersion: 3). Please reconcile by updating the PR description (or, if v5 is actually intended, aligning the constant/tests/docs accordingly).

type LibXrayMethod string

const LibXrayAPIVersion = 3

const (

• Files reviewed: 42/42 changed files
• Comments generated: 0 new
• Review effort level: Lite