---
name: netx-coding
description: Use when implementing code changes in the netx repository across Rust crates, controller/core runtime, protocol DTOs, Admin Console, Desktop Core UI, build scripts, or verification flows.
---

# netx 编码

## 使用场景

在 `/root/Projects/Mine/netx` 中写代码、修 bug、改构建、改 API、改 UI 时使用。

## 先读

按任务读取：

- 通用编码：`docs/specs/coding-guide.md`
- 架构边界：`docs/specs/architecture.md`
- 协议字段：`docs/specs/protocol.md`
- UI：`docs/specs/ui-design.md`
- 需求状态：`docs/specs/traceability.md`

## 当前边界

只维护：

- `netx-controller`
- `netx-core`
- `apps/netx-desktop`
- `web/admin`

新增入口必须归入这些产品边界。

## 修改位置

| 任务 | 位置 |
| --- | --- |
| 控制 API、状态投影、任务、controller state/bootstrap/metrics/API DTO 聚合 | `crates/netx-controller/src/state.rs`、`bootstrap_plan.rs`、`runtime_metrics.rs`、`control_api_models.rs`、其它 `control_api_*` 模块 |
| Controller audit/session API、managed session 执行和 system metrics/diagnostics | `crates/netx-controller/src/sessions.rs`、`sessions_diagnostics.rs` |
| Controller core plan、gateway assignment helper 和 service projection | `crates/netx-controller/src/core_planner.rs`、`core_planner_gateway.rs`、`core_planner_http.rs`、`core_planner_services.rs` |
| Controller embedded gateway handler、bridge accept、hosted service supervisor、public/mixed entry、HTTP entry、HTTP3、HTTPS passthrough/terminate、routing/http/body/backend/connection 适配 | `crates/netx-controller/src/gateway_http_entry.rs`、`gateway_bridge_accept.rs`、`gateway_hosted_services.rs`、`gateway_public_entry.rs`、`gateway_mixed_entry.rs`、`gateway_http3.rs`、`gateway_https_passthrough.rs`、`gateway_https_terminate.rs`、`gateway_routing.rs`、`gateway_http.rs`、`gateway_body.rs`、`gateway_backend.rs`、`gateway_connection.rs` |
| Core 运行编排、heartbeat loop state、DeliveredConfig managed client/service/proxy/overlay runtime config selection、initial service/proxy selection、NAT probe binding snapshot、peer engine tick/requested-attempt TTL state、punch ready/候选排序/端口扫描策略和 punch attempt 到 peer identity 映射 | `crates/netx-core-runtime` |
| 共享路由、执行计划、path selection | `crates/netx-core-engine` |
| 本机 Local API | `crates/netx-core-local` |
| Core service 命令、低阶 CLI runtime、Controller API 命令、解析和报告 | `apps/netx-core/src/cli_service.rs`、`cli_local_runtime.rs`、`cli_controller_api.rs`、`cli_parse.rs`、`cli_reports.rs` |
| Core app session 前置/attached/bootstrap/startup/overlay/loop | `apps/netx-core/src/client_session.rs`、`client_session_attached.rs`、`client_session_bootstrap.rs`、`client_session_startup.rs`、`client_session_overlay.rs`、`client_session_loop.rs` |
| Core overlay hosts/DNS/resolved/NRPT 和 Linux transparent TCP intercept 执行胶水 | `apps/netx-core/src/overlay_integration.rs`、`overlay_transparent_proxy.rs` |
| Core local proxy 监听、协议 helper、NETX path、上游 TLS 和 proxy chain helper | `apps/netx-core/src/local_proxy.rs`、`local_proxy_protocol.rs`、`local_proxy_netx.rs`、`local_proxy_tls.rs`、`local_proxy_chain.rs` |
| Core NAT probe、punch poll、UDP/TCP punch 执行和直连/relay 隧道循环 | `apps/netx-core/src/punch_nat_probe.rs`、`punch.rs`、`punch_tunnel.rs` |
| 配置 | `crates/netx-config` |
| Wire DTO | `crates/netx-proto/src/wire.rs` |
| UI DTO | `crates/netx-ui-api` |
| 存储 service 注册/加载、service row mapping 和 overlay relay port 分配 | `crates/netx-control/src/service_store.rs` |
| 存储 service validation、service parse/normalize helper 和 service auth JSON helper | `crates/netx-control/src/service_validation.rs` |
| 存储控制面入口、overview、core state 聚合和剩余共享 validation/helper 方法 | `crates/netx-control/src/lib.rs` |
| StoreExecutor async wrapper | `crates/netx-control/src/executor.rs` |
| 存储 schema/open/migration/backfill | `crates/netx-control/src/schema.rs` |
| 存储 kv/singleton JSON helper | `crates/netx-control/src/kv.rs` |
| 存储 service token 生命周期 | `crates/netx-control/src/service_tokens.rs` |
| 存储 task/audit 持久层 | `crates/netx-control/src/audit_tasks.rs` |
| 存储 admin principal/token | `crates/netx-control/src/admin_store.rs` |
| 存储节点接入、心跳、NAT/overlay probe、enrollment 和 blocked identity | `crates/netx-control/src/node_store.rs` |
| 存储 Network/resource/membership、overlay subnet routes、node service capability 和 service gateway assignment KV store | `crates/netx-control/src/network_store.rs` |
| 存储 service config、local proxy config、managed client config、overlay policy 和 setup draft | `crates/netx-control/src/config_store.rs` |
| 存储公共记录/错误类型 | `crates/netx-control/src/models.rs` |
| Admin API client | `web/admin/src/lib/api/*` |
| Desktop 状态编排 | `apps/netx-desktop/src/composables/use-client-workbench.ts` |
| Desktop Tauri 命令/DTO/IPC/local/profile/projection/runtime/service/remote 边界 | `apps/netx-desktop/src-tauri/src/core_control.rs`、`core_control_models.rs`、`core_control_ipc.rs`、`core_control_local.rs`、`core_control_profile.rs`、`core_control_projection.rs`、`core_control_runtime.rs`、`core_control_service.rs`、`core_control_remote.rs` |

## 实现规则

- Handler 做编排，不堆业务内核。
- SQLite 访问走 `StoreExecutor`。
- 协议新增先落 `netx-proto`。
- UI 不自己推导 runtime plan。
- 会话路径要同时看 Controller、Core、bridge executor、CLI/UI。
- 拆模块时同步修测试显式 import。
- 大验证分层跑，先轻后重。

## 重构期间

本 skill 描述当前有效工程结构，不用于阻止已确认的重构。

当重构改变以下内容时，同步更新本 skill 和 `docs/specs/coding-guide.md`、`docs/specs/architecture.md`：

- 产品边界。
- app / crate / module 责任。
- 前端目录归属。
- API 真相源。
- 构建命令。
- 验证命令。
- 运行入口。

若本 skill 与当前源码或已确认重构目标冲突，以当前源码和重构目标为准，并在同次修改中修正本 skill。

## 验证

轻量：

```bash
cargo check --workspace --all-targets
pnpm -C web/admin exec vue-tsc --noEmit
pnpm -C apps/netx-desktop exec vue-tsc --noEmit
```

仓库：

```bash
make verify-workspace
make verify-linux
make verify-windows
```

前端：

```bash
pnpm -C web/admin check:design-contracts
pnpm -C web/admin test
pnpm -C web/admin build
pnpm -C apps/netx-desktop check:design-contracts
pnpm -C apps/netx-desktop test
pnpm -C apps/netx-desktop build
```