SwiftMesh

1. 📌 Skill基础信息

Skill名称：SwiftMesh

简称：SwiftMesh

来源：社区第三方（zjinhu）

运行宿主：Cursor、Claude-Code CLI 等支持 MCP（Model Context Protocol）的 AI 开发工具

核心定位：基于 Alamofire5 的 Combine 封装，提供流畅配置链式语法，支持 SwiftUI 和 async/await，用于 Swift 项目中快速发起网络请求并处理响应数据。

2. 🧩 内部核心组成

核心文件结构

Mesh.swift：核心构建器类，包含所有属性配置
Config.swift：流畅链式设置器与全局配置
Request.swift：async/await 请求执行逻辑
Handle.swift：URL 构造、错误处理、响应处理和重试策略
Upload.swift：文件上传功能（文件、数据、流、多部分）
Download.swift：文件下载功能（标准、可恢复）
KeyPath.swift：JSON 键路径解码器，用于嵌套提取
Codable+.swift：弹性属性包装器（@Default、@IgnoreError、@ConvertTo*）
Log.swift：网络日志记录器（cURL、状态、时间、JSON）

主要功能方法表

方法名	功能简述
`.request(of: Model.self)`	解码响应到 Codable 模型
`.request(of: Model.self, modelKeyPath:)`	提取嵌套 JSON 数据
`.upload(of: Result.self)`	上传文件/数据/流/多部分
`.download()`	下载或恢复下载
`.requestData()`	获取原始响应数据
`.requestString()`	获取响应字符串
`.setInterceptor(RetryPolicy())`	设置自动重试策略
`.enableLog()`	启用网络日志记录

3. 🛠 安装与启用方式

安装命令：

skills install --user zjinhu/SwiftMesh

前置依赖：

iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+
Alamofire 5.0+
Swift 5.5+（支持 async/await）

API/工具要求：

需要网络访问权限
支持 Combine 框架
支持 SwiftUI（可选）

启动方式：在 Swift 项目中导入 SwiftMesh 模块后即可使用链式语法发起网络请求。

4. 📋 标准工作流

配置阶段：用户通过链式调用配置请求参数（URL、方法、头信息、参数等）
执行阶段：调用 .request()、.upload() 或 .download() 方法发起网络请求
处理阶段：

- 自动处理 JSON 解析（支持键路径提取）

- 弹性处理异常数据（通过属性包装器）

- 统一错误处理（网络错误标准化）

响应阶段：返回解码后的模型对象或原始数据

典型使用链路：配置 → 执行 → 处理 → 响应，全程支持 async/await 异步编程模式。

5. ⚠️ 关键限制、缺陷、注意事项

平台限制：

仅支持 Apple 平台（iOS/macOS/tvOS/watchOS）
不支持 Android、Web 或其他跨平台框架

Token 消耗：无特定 token 消耗，但网络请求会消耗设备资源和数据流量

适合项目：

Swift 原生应用开发
使用 Alamofire 的网络请求场景
需要 Combine 或 async/await 集成的项目

不适合项目：

跨平台应用（Flutter、React Native 等）
非 Apple 生态系统项目
需要极简网络库的小型项目

已知坑点：

强依赖 Alamofire，版本兼容性需要注意
学习曲线较陡，需要熟悉 Combine 和 async/await
全局配置需在应用启动时设置

生产环境适用性：可用于生产环境，但需要充分测试网络异常情况和边缘案例。

6. ✅ 适用场景 & ❌ 不适合场景

✅ 适用场景：

SwiftUI 应用开发需要网络请求封装
需要优雅处理 API 响应不一致性的项目
希望使用现代 Swift 并发特性（async/await）的开发者
需要文件上传下载功能的 iOS/macOS 应用
追求代码简洁和链式语法的开发团队

❌ 不适合场景：

非 Apple 平台的跨平台开发
只需要简单网络请求的微型项目
不使用 Alamofire 的项目
对第三方依赖极其敏感的项目
需要极高性能网络处理的应用（游戏等）

如何安装

skills install --user zjinhu/SwiftMesh

通用安装教程：在哪里输入上面的命令

上面的命令本质是在「终端 / 命令行」中调用技能管理器，把该 Skill 下载并注册到你的 AI 工具。各主流工具打开终端的位置不同，按下面操作即可：

打开工具自带的终端面板，或系统终端（macOS「终端」、Windows「PowerShell」、Linux「Terminal」）。
把上面的安装命令复制进去，回车运行，等待下载与注册完成。
重启或重新加载 AI 工具，让新安装的 Skill 被识别。
新建对话并触发：直接描述用途，或通过该工具的技能 / 斜杠菜单选中此 Skill。

Claude 桌面版（macOS / Windows）

桌面版没有内置命令行，Skill 需通过 Claude Code CLI 安装。打开系统终端，先执行 npm install -g @anthropic-ai/claude-code，再运行上面的安装命令；完成后完全退出并重新打开 Claude。

Claude Code（终端 CLI）

直接在项目目录的终端里运行上面的命令即可。也可先输入 claude 启动交互界面，再在对话中引用该 Skill（/ 斜杠菜单或直接描述用途）。

VS Code（含 GitHub Copilot）

打开终端面板：菜单「终端 → 新建终端」，或快捷键 Ctrl+`（macOS 为 ⌃+`）。在终端里运行上面的命令；装完后执行「重新加载窗口」（Ctrl+Shift+P → Reload Window），让 Copilot 等扩展识别新技能。

Cursor

底部「终端」面板（Ctrl+`）即是内置终端。粘贴运行上面的命令，完成后在命令面板执行「Reload Window」刷新，再开始对话。

Windsurf

底部「终端」面板运行命令；也可直接使用其内置 Agent 终端，在对话侧执行安装。

其他工具（ChatGPT、本地脚本等）

不支持本地终端的产品，可先在本机终端完成安装，再在对话中描述该 Skill 的能力让其调用；不同工具的命令格式请以其官方文档为准。

风险提示

✅ 低风险

自动扫描未发现高危命令、隐私抓取或数据外传行为。仍建议安装前快速浏览仓库代码。