diff --git a/.codex/skills/grill-me/README.md b/.codex/skills/grill-me/README.md new file mode 100644 index 0000000..2748ba9 --- /dev/null +++ b/.codex/skills/grill-me/README.md @@ -0,0 +1,71 @@ +# grill-me + +A relentless interviewer skill for any AI coding assistant that supports the [open agent skills](https://github.com/vercel-labs/skills) format — Claude Code, Cursor, Codex, OpenCode, Continue, Windsurf, and 40+ others. + +`/grill-me` does not hunt for bugs. It expands your understanding of what you actually want by surfacing intent, constraints, hidden assumptions, and unstated alternatives — across coding, marketing, personal branding, SOPs, systems thinking, process design, and tough business decisions. + +## Install + +```bash +# Project-local install (default) — committed with your project +npx skills@latest add satya-janghu/agent-skills/skills/grill-me + +# Global install — available across all your projects +npx skills@latest add satya-janghu/agent-skills/skills/grill-me -g + +# Non-interactive, Claude Code only, global +npx skills@latest add satya-janghu/agent-skills/skills/grill-me -g -a claude-code -y +``` + +The `skills` CLI prompts you for which AI agent to install for (Claude Code, Cursor, Codex, etc.) and whether to install project-locally or user-globally. + +If you don't want to use the CLI, see [Manual install](#manual-install) below. + +## Usage + +Inside any AI agent that supports skills: + +``` +/grill-me +``` + +Or trigger by phrase: "grill me on…", "interview me about…", "pressure-test this…", "help me think through…". + +The skill ends when the next concrete action becomes possible (writing code, drafting a brief, editing an SOP, making a commit). Before that action, it writes a distilled session log to `/.grill/.md`. + +## What makes it different + +Most AI assistants ask too few questions and declare "I have enough to start" too early. `grill-me` is engineered to fight that: + +- **One question at a time, with a recommended answer attached** — gives you something to react to instead of a blank prompt. +- **Drills the last answer before moving sideways** — the depth comes from following one thread to the bottom, not from breadth. +- **Pulls from a menu of lenses** without naming them — first-principles, pre-mortem, steelman, reversibility, five-whys, audience, hidden-assumption excavation, second-best, sustainability, plus established mental-model frames (Naval permissionless leverage, Thiel "what do you believe…", Hormozi value equation, Christensen JTBD, Munger inversion, Bezos regret minimization). The conversation feels natural; the structure is hidden. +- **Pushes back on vague answers, deflections, and contradictions** rather than accepting fog. +- **Strawmans half-answers by default** — easier to disagree with a draft than invent from blank. +- **Adapts the lens to the domain** (coding vs. marketing vs. SOPs vs. business decisions), but does not bug-hunt. The goal is expanding the user's understanding of what they want, not finding flaws in execution. +- **Writes a session log to `/.grill/.md`** — Intent, Constraints, Key decisions, Surfaced assumptions, Open questions, Out of scope. The log is the distilled output, not a transcript. + +See [SKILL.md](SKILL.md) for the full instruction set. + +## Manual install + +If you prefer not to use the `skills` CLI, drop `SKILL.md` directly into the right location for your agent: + +| Agent | Location | +|---|---| +| Claude Code (global) | `~/.claude/skills/grill-me/SKILL.md` | +| Claude Code (project) | `/.claude/skills/grill-me/SKILL.md` | +| Cursor | `/.cursor/skills/grill-me/SKILL.md` | +| Codex | `/.codex/skills/grill-me/SKILL.md` | + +A one-liner using `curl`: + +```bash +mkdir -p ~/.claude/skills/grill-me && \ + curl -fsSL https://raw.githubusercontent.com/satya-janghu/agent-skills/main/skills/grill-me/SKILL.md \ + -o ~/.claude/skills/grill-me/SKILL.md +``` + +## License + +MIT — see [LICENSE](../../LICENSE). diff --git a/.codex/skills/grill-me/SKILL.md b/.codex/skills/grill-me/SKILL.md new file mode 100644 index 0000000..880871d --- /dev/null +++ b/.codex/skills/grill-me/SKILL.md @@ -0,0 +1,96 @@ +--- +name: grill-me +description: Interview the user relentlessly to expand context and surface intent, constraints, hidden assumptions, and unstated alternatives. Use whenever the user invokes `/grill-me`, says "grill me", "interview me", "pressure-test this", "help me think through", or whenever the user's first message is more decision than task — across coding, business, marketing, personal branding, SOPs, systems thinking, process design, and tough decisions. +--- + +# grill-me + +Your job is to **expand the user's context and understanding of what they actually want** through relentless, high-quality questioning. This is not bug-hunting. It is not a checklist. You are surfacing intent, constraints, hidden assumptions, and unstated alternatives that the user has not yet made explicit — even to themselves. + +## Core loop + +1. Ask **one question at a time**. +2. Provide your **recommended answer** alongside each question, so the user has something to react to rather than a blank prompt. +3. After each answer, **drill into the answer you just got** before moving sideways to a new branch. Most premature exits happen because you moved on too soon. +4. If a question can be answered by reading code, files, or the project itself — **investigate instead of asking**. +5. End when the next concrete action (writing code, editing an SOP, drafting a brief, making a commit, etc.) becomes possible — and only then. Before taking that action, write the session log (see "Logging" below). + +## How to ask better questions than you normally would + +Your default behavior is to ask too few questions and declare convergence too early. Counteract that: + +- **When you feel you have enough to act, ask three more questions.** That feeling is the surface, not the bottom. +- **Do not summarize as progress.** "So what I'm hearing is X, Y, Z" ends grilling — it does not advance it. Ask, don't paraphrase. +- **Push back on vague answers.** "I'll figure it out later", "probably X", "something like Y" are signals to drill, not move on. +- **You are allowed — and expected — to call out contradictions, deflections, and hand-waving.** Politely, but without softening to the point of accepting fog. +- **Adapt the questioning lens to the domain** (coding, marketing, branding, SOPs, business decisions). Read the project — what files exist, what the user just said, what the work actually is — and let that shape what you probe. The lens shapes the *kind* of question, not whether you ask it. + +## Question lenses to draw from + +You have a menu of lenses. **Do not name the lens out loud** — keep the conversation natural. Pull from these dynamically, mixing freely. There is no required count and no domain-locked subset. Use what fits. + +- **First-principles.** Strip the problem to fundamentals. "If you started from zero — no existing tools, audience, or code — would you still do it this way?" +- **Intent and desired outcome.** What does *winning* look like for the user personally, not the project's stated success criteria? +- **Constraint surfacing.** What is non-negotiable? Time, money, energy, values, identity. The real design lives in the constraints. +- **Hidden assumption excavation.** "You said X — what has to be true for X to hold?" +- **Second-best alternative.** What's the path they're *not* taking? If they can't name it, they haven't actually chosen. +- **Pre-mortem.** "It's 12 months from now and this failed. Walk me through why." +- **Steelman the opposite.** Make the strongest case *against* their plan. If they can't, conviction is shallow. +- **Audience / stakeholder lens.** Who is this *for*, specifically — name a single person. What do they think, fear, want? +- **Reversibility.** One-way door or two-way door? They are designed differently. +- **Five-whys / root cause.** "Why does that matter?" recursively until you hit a value, identity, or non-negotiable. +- **Boundary testing.** What is *out of scope*? Naming what you will not do is often more clarifying than what you will. +- **Sustainability.** Would they still do this if it took 3x as long as expected? If not, the plan is fragile. + +You may also draw from established mental-model frames — Naval's permissionless leverage, Thiel's "what do you believe that nobody agrees with", Hormozi's value equation, Christensen's jobs-to-be-done, Bezos's regret minimization, Munger's inversion, Kahneman's pre-commitment, Drucker's "what does the customer value?", Andy Grove's "what are we trying to optimize for?", and similar — without naming the source. Adopt the frame, not the brand. + +## Handling half-answers + +When the user gives a hedge or a placeholder ("I dunno, maybe X"): + +- **Default: propose a strawman they can react to.** "Here's an answer — tell me where it's wrong: …" This is higher-leverage than open-ended pushing because disagreement is easier than invention. +- **When the user pushes back on the question itself** (i.e., they think the question is wrong, not the answer): reframe — "what would you need to know to make this answerable?" — and follow that thread. + +## Logging + +When grilling converges and the next action is possible, **before taking that action**, write a markdown log to: + +``` +/.grill/.md +``` + +where `` is a kebab-case summary of the topic. Create the directory if it does not exist. + +Use this structure. **Delete any section that ended up empty** — do not leave "TBD" placeholders. + +```markdown +# Grill: +Date: + +## Intent +What the user is actually trying to achieve, in their words, refined. + +## Constraints +Non-negotiables surfaced during grilling. + +## Key decisions +- Decision: . Reason: . Alternative considered: . + +## Surfaced assumptions +Things the user was implicitly assuming, now made explicit. + +## Open questions +Things the user could not answer yet, deferred for later. + +## Out of scope +Things the user explicitly chose not to do. +``` + +The log is the *distilled* output, not a transcript. Capture conclusions and the reasoning behind them, not the back-and-forth. + +## What this skill is not + +- **Not a bug hunt.** You are not looking for race conditions, broken positioning, or weak SOP steps. You are expanding the user's understanding of what they want and why. +- **Not a checklist.** No mandatory questions, no required count, no fixed order. Adapt to what the user just said. +- **Not a summary tool.** Summarizing is the opposite of grilling. Save synthesis for the log at the end. +- **Not a coach.** Don't motivate. Don't validate. Probe. diff --git a/.codex/skills/mcp-builder/SKILL.md b/.codex/skills/mcp-builder/SKILL.md new file mode 100644 index 0000000..2dc79f1 --- /dev/null +++ b/.codex/skills/mcp-builder/SKILL.md @@ -0,0 +1,255 @@ +--- +name: mcp-builder +description: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力 +--- + +# MCP 服务器构建 + +系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。 + +## 1. 协议核心概念 + +MCP 定义三种原语： + +- **Tools（工具）**：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。 +- **Resources（资源）**：AI 助手只读访问的数据源，用 URI 标识。如 `users://{id}/profile`。 +- **Prompts（提示词模板）**：预定义交互模板，引导用户触发工作流。 + +**选择原则：** 执行操作 → Tool | 读取数据 → Resource | 引导交互 → Prompt + +## 2. 项目结构规范 + +### TypeScript +``` +my-mcp-server/ +├── src/ +│ ├── index.ts # 入口，注册 tools/resources +│ ├── tools/ # 按功能拆分 +│ ├── resources/ +│ └── lib/ # 客户端封装、校验逻辑 +├── tests/ +├── package.json +└── tsconfig.json +``` + +关键依赖：`@modelcontextprotocol/sdk` + `zod` + +### Python +``` +my-mcp-server/ +├── src/my_mcp_server/ +│ ├── server.py +│ ├── tools/ +│ └── lib/ +├── tests/ +└── pyproject.toml +``` + +关键依赖：`mcp` + `pydantic` + +## 3. Tool 设计原则 + +### 命名 +- `snake_case` 格式，动词开头：`search_users`、`create_issue`、`delete_file` +- 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用 + +### 参数 +- 每个参数有类型约束和 `.describe()` 描述 +- 可选参数给默认值，减少 AI 决策负担 +- 用枚举代替布尔开关 + +```typescript +server.tool("search_issues", { + query: z.string().describe("搜索关键词"), + status: z.enum(["open", "closed", "all"]).default("open").describe("状态筛选"), + limit: z.number().min(1).max(100).default(20).describe("返回上限"), +}, async ({ query, status, limit }) => { /* ... */ }); +``` + +### 描述 +说明**用途 + 返回内容 + 限制**，这是 AI 选择工具的关键依据： + +```typescript +server.tool("search_users", + "根据姓名或邮箱搜索用户。返回 ID、姓名、邮箱列表。模糊匹配，最多 50 条。", + schema, handler); +``` + +### 输出 +- 结构化数据 → JSON，人类可读内容 → Markdown +- 始终用 `content: [{ type: "text", text: "..." }]` 格式返回 + +## 4. 输入验证和错误处理 + +用 Zod/Pydantic 做 Schema 级校验，业务级校验放 handler 开头： + +```typescript +server.tool("get_user", { id: z.string() }, async ({ id }) => { + try { + const user = await db.getUser(id); + if (!user) { + return { + content: [{ type: "text", text: `用户 ${id} 不存在，请检查 ID。` }], + isError: true, + }; + } + return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] }; + } catch (err) { + return { + content: [{ type: "text", text: `查询失败：${err.message}` }], + isError: true, + }; + } +}); +``` + +**错误处理四原则：** +1. 永远不让服务器崩溃 — try/catch 包裹所有外部调用 +2. 返回可操作的错误信息 — 告诉 AI 问题是什么、能做什么 +3. 使用 `isError: true` — 让 AI 知道调用失败 +4. 区分错误类型 — 参数错误、权限不足、资源不存在、服务不可用 + +## 5. 资源管理和生命周期 + +```typescript +// 资源注册 +server.resource("user-profile", "users://{userId}/profile", async (uri) => { + const profile = await db.getProfile(extractId(uri)); + return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(profile) }] }; +}); + +// 生命周期：先初始化 → 再 connect → 监听关闭信号 +const db = await Database.connect(config.dbUrl); +await server.connect(new StdioServerTransport()); +process.on("SIGINT", async () => { await db.disconnect(); await server.close(); process.exit(0); }); +``` + +关键点：使用连接池、所有外部调用设超时、优雅关闭清理资源。 + +## 6. 测试策略 + +### 单元测试 — 业务逻辑与 MCP 注册分离 +```typescript +// tools/search.ts 导出纯函数 +export async function searchUsers(query: string, limit: number) { /* ... */ } + +// search.test.ts 独立测试 +test("返回匹配结果", async () => { + const results = await searchUsers("alice", 10); + expect(results[0].name).toContain("Alice"); +}); +``` + +### 集成测试 — 用 SDK Client 做端到端验证 +```typescript +const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); +await server.connect(serverTransport); +const client = new Client({ name: "test", version: "1.0.0" }); +await client.connect(clientTransport); +const result = await client.callTool("search_users", { query: "test" }); +expect(result.isError).toBeFalsy(); +``` + +### MCP Inspector — 交互式调试 +```bash +npx @modelcontextprotocol/inspector node dist/index.js +``` + +在浏览器中查看所有 tools/resources，手动调用并查看结果。 + +**测试要点：** 每个 Tool 覆盖正常 + 异常路径、边界值、外部服务失败模拟。 + +## 7. 安全考虑 + +**权限控制：** +- 最小权限原则，读写 Tool 分离 +- 危险操作要求确认参数（如 `confirm: true`） + +**输入安全：** +- SQL 注入 → 参数化查询，绝不拼接 +- 路径遍历 → 校验路径，禁止 `../` +- 命令注入 → 用 `execFile` 而非 `exec` + +**敏感数据：** +- 密钥通过环境变量传入，不硬编码 +- 日志不打印完整敏感信息 +- 返回数据做脱敏处理 + +**沙箱：** 文件操作限制目录、网络请求限制白名单、设置资源配额。 + +## 8. 部署和分发 + +### npm 发布 +```json +{ "bin": { "mcp-server-myservice": "dist/index.js" }, "files": ["dist"] } +``` + +用户配置： +```json +{ "mcpServers": { "myservice": { "command": "npx", "args": ["@yourorg/mcp-server-myservice"], "env": { "API_KEY": "xxx" } } } } +``` + +### pip 发布 +```toml +[project.scripts] +mcp-server-myservice = "my_mcp_server.server:main" +``` + +### Docker — 适用于复杂依赖或隔离场景 +```dockerfile +FROM node:20-slim +WORKDIR /app +COPY package*.json ./ && RUN npm ci --production +COPY dist ./dist +ENTRYPOINT ["node", "dist/index.js"] +``` + +## 9. 调试技巧 + +**关键：MCP 用 stdio 通信，不能用 `console.log`，会破坏协议流。** + +```typescript +// 错误 +console.log("debug"); +// 正确 +console.error("[DEBUG]", info); +// 更好 +server.sendLoggingMessage({ level: "info", data: "处理中" }); +``` + +**常见问题：** + +| 症状 | 原因 | 解决 | +|------|------|------| +| 启动无响应 | transport 未连接 | 检查 `server.connect()` | +| Tool 不出现 | 注册在 connect 之后 | 先注册再 connect | +| AI 不调用 Tool | 描述不清晰 | 改善名称和描述 | +| 参数总错 | Schema 不明确 | 添加 `.describe()` | +| 调用超时 | 外部服务慢 | 加超时和缓存 | + +**调试流程：** Inspector 验证基本功能 → 手动调用确认输入输出 → 连接真实 AI 客户端观察调用模式 → 根据实际行为调整设计。 + +## 10. 构建检查清单 + +### 设计 +- [ ] 明确 Tools vs Resources vs Prompts 分工 +- [ ] Tool 命名 `动词_名词`，描述说明用途和返回内容 +- [ ] 参数简洁，可选参数有合理默认值 + +### 实现 +- [ ] 输入用 Zod/Pydantic 校验 +- [ ] 外部调用有 try/catch 和超时 +- [ ] 错误返回 `isError: true` 并附可操作信息 +- [ ] 不用 `console.log`（用 stderr 或 SDK 日志） +- [ ] 敏感数据走环境变量 + +### 测试 +- [ ] 核心逻辑有单元测试 +- [ ] 有集成测试验证 MCP 协议交互 +- [ ] 用 MCP Inspector 手动验证过 +- [ ] 用真实 AI 客户端测试过 + +### 部署 +- [ ] README 含安装和配置说明 +- [ ] 提供客户端配置 JSON 示例 +- [ ] 遵循 semver，无硬编码密钥 diff --git a/.codex/skills/netx-coding/SKILL.md b/.codex/skills/netx-coding/SKILL.md new file mode 100644 index 0000000..80525a6 --- /dev/null +++ b/.codex/skills/netx-coding/SKILL.md @@ -0,0 +1,122 @@ +--- +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 +``` diff --git a/.codex/skills/netx-design/SKILL.md b/.codex/skills/netx-design/SKILL.md new file mode 100644 index 0000000..b093716 --- /dev/null +++ b/.codex/skills/netx-design/SKILL.md @@ -0,0 +1,91 @@ +--- +name: netx-design +description: Use when changing or reviewing netx Web Admin, Desktop Core UI, visual design contracts, navigation, components, page layout, copy, or frontend interaction behavior. +--- + +# netx UI 设计 + +## 使用场景 + +在 `/root/Projects/Mine/netx` 中处理这些内容时使用： + +- `web/admin` +- `apps/netx-desktop` +- 导航信息架构。 +- 页面布局。 +- 组件复用。 +- UI 文案。 +- 设计契约检查失败。 + +## 先读 + +按顺序读取： + +1. `docs/specs/ui-design.md` +2. `web/admin/src/app/routes.ts` +3. `web/admin/src/components/netx/*` +4. `web/admin/src/components/common/DataWorkbench.vue` +5. `apps/netx-desktop/src/App.vue` +6. `apps/netx-desktop/src/components/client/*` + +视觉资产在 `docs/design/netx-ui-dev-assets`。页面源码不得直接引用该目录。 + +## Admin 规则 + +- Admin 是高信息密度控制台。 +- 一级导航固定走 `Overview / Nodes / Networks / Gateways / Services / Routes / DNS / Security / Diagnostics / Settings`。 +- `Gateways` 是具有 Gateway capability 的节点视图。 +- `Services` 覆盖 HTTP、HTTPS、TCP、UDP、SOCKS5、Shadowsocks。 +- HTTP、Tunnel、SOCKS5、Shadowsocks 都归入 `Services`。 +- 页面优先复用 `components/netx` 和 `DataWorkbench`。 + +## Desktop 规则 + +- Desktop 是本机 Core 工作台。 +- 交互按 PC 分屏处理。 +- Desktop 不承载网络逻辑。 +- 通过 Local API / IPC 管理 `netx-core`。 +- 使用分屏工作台壳。 + +## 重构期间 + +本 skill 描述当前 UI 结构，不用于阻止已确认的 UI 或产品重构。 + +当重构改变以下内容时，同步更新本 skill 和 `docs/specs/ui-design.md`： + +- Admin 目录归属。 +- Desktop 目录归属。 +- 导航信息架构。 +- 组件入口。 +- 设计资产路径。 +- 设计检查命令。 +- 页面交互主模式。 + +若本 skill 与当前源码或已确认重构目标冲突，以当前源码和重构目标为准，并在同次修改中修正本 skill。 + +## 必跑检查 + +改 Admin： + +```bash +pnpm -C web/admin check:design-contracts +pnpm -C web/admin test +pnpm -C web/admin build +``` + +改 Desktop： + +```bash +pnpm -C apps/netx-desktop check:design-contracts +pnpm -C apps/netx-desktop test +pnpm -C apps/netx-desktop build +``` + +## 禁止项 + +- 不用原生 `