|
|
---
|
|
|
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
|
|
|
```
|