iTi-Flask-IOT/.codex/skills/netx-coding/SKILL.md

name	description
netx-coding	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。

验证

轻量：

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

仓库：

make verify-workspace
make verify-linux
make verify-windows

前端：

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