# OpenCode Skills - MQTTS Certificate Management

这个目录包含了完整的 MQTTS (MQTT over TLS) 证书配置和管理技能库。

## 📚 Skills 列表

### 1. setup-mqtts-acme.md
**完整的 MQTTS 自动证书配置流程**

适用场景：
- 首次为 EMQX 配置 MQTTS
- 使用 acme.sh + DNS API 自动申请证书
- 需要证书自动续期
- 支持阿里云 DNS（可扩展到其他 DNS 提供商）

包含内容：
- 10 个阶段的详细执行步骤
- 环境检查和验证
- 证书申请和安装
- EMQX 容器重配置
- 文档和备份生成
- 故障排查指南

使用方式：
```
请帮我按照 setup-mqtts-acme skill 为域名 mq.example.com 配置 MQTTS
```

### 2. mqtts-quick-reference.md
**快速参考手册**

适用场景：
- 快速查找常用命令
- 紧急故障排查
- 日常维护操作
- 快速测试连接

包含内容：
- 快速启动命令
- 常用管理命令
- 测试命令
- 故障诊断一键脚本
- 关键概念速查

使用方式：
```
查看 mqtts-quick-reference，帮我测试 MQTTS 连接
```

### 3. mqtts-client-config.md
**客户端配置完整指南**

适用场景：
- 配置各种语言的 MQTT 客户端
- 解决客户端连接问题
- 选择合适的认证方式
- 多平台开发参考

包含内容：
- Python、Node.js、Java、C#、Go、ESP32 示例代码
- 系统 CA vs fullchain.pem 对比
- 单向 TLS 认证详解
- 客户端故障排查
- 安全最佳实践

使用方式：
```
根据 mqtts-client-config，帮我写一个 Python 客户端连接代码
```
```
我的 ESP32 连接 MQTTS 失败，参考 mqtts-client-config 帮我排查
```

## 🎯 使用场景示例

### 场景 1: 首次配置 MQTTS
```
我有一台运行 EMQX 5.8.8 的服务器，域名是 mqtt.mycompany.com，
已经配置了阿里云 DNS API。请按照 setup-mqtts-acme skill 帮我配置 MQTTS。
```

### 场景 2: 验证现有配置
```
根据 mqtts-quick-reference 中的诊断命令，
帮我检查 mq.example.com 的 MQTTS 配置是否正常。
```

### 场景 3: 客户端开发
```
我需要开发一个 Python MQTT 客户端连接到 mqtts://mq.example.com:8883。
参考 mqtts-client-config 帮我写代码，使用系统 CA 验证。
```

### 场景 4: 故障排查
```
我的 ESP32 连接 MQTTS 时出现 SSL handshake failed 错误。
根据 mqtts-client-config 的故障排查部分，帮我分析可能的原因。
```

### 场景 5: 证书更新
```
我的证书即将到期，根据 mqtts-quick-reference 帮我手动强制续期。
```

## 📖 Skill 使用最佳实践

### 1. 明确指定 Skill
在提问时明确提到 skill 名称，让 AI 知道参考哪个文档：
```
✅ 好：根据 setup-mqtts-acme skill 帮我...
✅ 好：参考 mqtts-client-config 中的 Python 示例...
❌ 差：帮我配置 MQTTS（不明确，AI 可能不使用 skill）
```

### 2. 提供必要参数
根据 skill 要求提供必要信息：
```
✅ 好：域名是 mq.example.com，使用阿里云 DNS，容器名是 emqx
❌ 差：帮我配置（缺少关键信息）
```

### 3. 分阶段执行
对于复杂流程，可以分阶段执行：
```
1. 先执行环境检查阶段
2. 确认无误后执行证书申请
3. 最后执行容器配置
```

### 4. 参考故障排查
遇到问题时先参考 skill 中的故障排查部分：
```
我遇到了 DNS 解析失败的错误，
根据 setup-mqtts-acme 的故障排查部分，应该如何处理？
```

## 🔄 Skill 更新和维护

### 当前版本
- setup-mqtts-acme: v1.0 (2026-01-07)
- mqtts-quick-reference: v1.0 (2026-01-07)
- mqtts-client-config: v1.0 (2026-01-07)

### 支持的配置
- EMQX: 5.8.8 (Docker)
- acme.sh: 最新版本
- DNS Provider: 阿里云 DNS (dns_ali)
- CA: ZeroSSL, Let's Encrypt
- TLS: TLSv1.2, TLSv1.3
- 认证: 单向 TLS + 用户名密码

### 扩展建议
可以基于这些 skills 创建新的变体：

1. **setup-mqtts-nginx.md**: Nginx 反向代理场景
2. **setup-mqtts-mtls.md**: 双向 TLS 认证配置
3. **mqtts-monitoring.md**: 证书监控和告警
4. **mqtts-ha-cluster.md**: 高可用集群配置

### 反馈和改进
如果发现 skill 有任何问题或改进建议：
1. 记录具体场景和问题
2. 建议改进方案
3. 更新对应的 skill 文件

## 📝 命名规范

Skill 文件命名遵循以下规范：
- 使用小写字母和连字符
- 清晰描述功能
- 使用 .md 扩展名
- 例如：`setup-mqtts-acme.md`, `mqtts-client-config.md`

## 🎓 学习路径

### 初学者
1. 先阅读 `mqtts-quick-reference.md` 了解基本概念
2. 使用 `setup-mqtts-acme.md` 完成首次配置
3. 参考 `mqtts-client-config.md` 开发客户端

### 进阶用户
1. 深入理解 `setup-mqtts-acme.md` 的每个阶段
2. 自定义配置参数（CA、DNS 提供商等）
3. 根据实际需求修改和扩展 skill

### 专家用户
1. 创建自定义 skill 变体
2. 集成到 CI/CD 流程
3. 开发自动化脚本

## 🔗 相关资源

- EMQX 官方文档: https://www.emqx.io/docs/
- acme.sh 项目: https://github.com/acmesh-official/acme.sh
- MQTT 协议规范: https://mqtt.org/
- TLS 最佳实践: https://wiki.mozilla.org/Security/Server_Side_TLS

## 💡 提示

1. **Token 节省**: 使用 skill 可以大幅减少 token 消耗，因为 AI 直接参考结构化的知识库
2. **一致性**: Skill 确保每次执行都遵循相同的最佳实践
3. **可维护**: 集中管理知识，便于更新和改进
4. **可重用**: 一次编写，多次使用，提高效率

## ⚠️ 注意事项

1. 这些 skills 基于特定版本和配置，使用前请确认环境兼容性
2. 生产环境操作前建议先在测试环境验证
3. 涉及证书和密钥的操作需要特别注意安全性
4. 自动化脚本执行前请仔细审查命令

## 🚀 快速开始

最简单的使用方式：
```
我需要为 EMQX 配置 MQTTS 自动证书，域名是 mq.example.com。
请使用 setup-mqtts-acme skill 帮我完成配置。
```

AI 将会：
1. 读取 setup-mqtts-acme.md skill
2. 检查必要参数和前置条件
3. 逐步执行配置流程
4. 验证配置结果
5. 生成文档和备份

享受自动化的便利！🎉