feat: 优化 proxy-deploy 和 release 技能描述

- 更主动的触发描述，提高技能调用准确性 - 添加完整的执行流程和故障排查指南 - 修正端口信息 (3000 → 80) - 补充版本命名规范和 CI/CD 说明 Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
2026-03-20 14:21:42 +00:00
parent bc6eaa905b
commit 4037d89392
2 changed files with 119 additions and 84 deletions
--- a/.claude/skills/proxy-deploy/SKILL.md
+++ b/.claude/skills/proxy-deploy/SKILL.md
@@ -1,27 +1,29 @@
 ---
 name: proxy-deploy
-description: 部署 Claude API 代理服务到 K8S ECI。当用户要求部署代理服务、创建新的代理实例、查看代理状态、删除代理服务时使用。触发词: deploy, 部署, 代理, proxy, k8s, eci, 服务状态, 删除服务。
+description: 部署 Claude API 代理服务到 K8S ECI。只要用户提到部署、代理服务、K8S、ECI、容器实例、服务状态、删除服务等相关操作就必须使用此技能。触发词包括: deploy, 部署, 代理, proxy, k8s, eci, 服务状态, 删除服务, 启动服务, 容器, pod, ingress。即使用户没有明确说"deploy"，只要意图是管理代理服务，就应该使用此技能。
 ---

 # Claude API 代理服务部署

-用于管理 Claude API 代理服务在 K8S ECI 环境中的部署。
+管理 Claude API 代理服务在阿里云 K8S ECI 环境中的完整生命周期。

-## 可用命令
+## 执行流程

-### 部署代理服务
+当用户要求部署或管理代理服务时，按以下步骤操作：
+
+### 1. 部署新服务

 ```bash
 pnpm deploy <name> <image> [options]
 ```

-**参数:**
- `name` - 服务名称（唯一标识）
+**必须参数:**
+- `name` - 服务名称（唯一标识，如 claude-proxy-1）
 - `image` - Docker 镜像地址

-**选项:**
+**可选参数:**
 - `--replicas <n>` - 副本数（默认: 1）
- `--port <port>` - 容器端口（默认: 3000）
+- `--port <port>` - 容器端口（默认: 80）
 - `--eip-bandwidth <n>` - EIP 带宽 Mbps（默认: 5）

 **示例:**
@@ -29,64 +31,74 @@ pnpm deploy <name> <image> [options]
 # 部署单个代理实例
 pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1

-# 部署 3 个副本
-pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1 --replicas 3
-
-# 自定义端口
-pnpm deploy claude-proxy-2 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.2 --port 80
+# 部署多个副本
+pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.2 --replicas 2
 ```

-### 删除代理服务
-
-```bash
-pnpm deploy delete <name>
-```
-
-### 查询服务状态
+### 2. 查询服务状态

 ```bash
 pnpm deploy status <name>
 ```

-## 环境配置
+返回服务的 Pod 状态、访问地址等关键信息。

-部署前需要确保 `.env` 文件包含以下配置:
+### 3. 删除服务
+
+```bash
+pnpm deploy delete <name>
+```
+
+删除指定的代理服务及其关联资源（Deployment、Service、Ingress）。
+
+## 环境配置要求
+
+部署前必须确保 `.env` 文件包含以下配置，否则部署会失败：

 ```env
-# K8S API 配置
+# K8S API 配置（必须）
 K8S_API_URL=http://10.0.0.52:23972
 K8S_API_TOKEN=your_fixed_token_here

-# 域名配置
+# 域名配置（必须）
 DEV_HOST="*.dev.d8d.fun"
 DEV_TLS_SECRET_NAME="d8d-proxy-tls"

-# 上游 API（会注入到容器）
+# 上游 API 地址（会注入到容器环境变量）
 ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
 ```

-## 部署特性
+## 部署特性说明

- **ECI 实例**: 使用阿里云 ECI 弹性容器实例
- **Spot 实例**: 自动使用抢占式实例降低成本
- **自动 EIP**: 自动分配公网 IP
- **TLS**: 自动配置 HTTPS 域名访问
- **健康检查**: 自动配置就绪探针和存活探针
+这些特性会在部署时自动配置，无需手动指定：

-## 访问地址格式
+- **ECI 弹性容器** - 使用阿里云 Serverless 容器实例
+- **Spot 抢占式实例** - 自动使用低成本抢占实例（通过注解 `k8s.aliyun.com/eci-spot-instance: "true"`）
+- **自动 EIP** - 自动分配公网 IP 用于外部访问
+- **TLS/HTTPS** - 自动配置域名证书，支持 HTTPS 访问
+- **健康检查** - 自动配置就绪探针和存活探针

-部署成功后，服务可通过以下地址访问:
+## 访问地址
+
+部署成功后，服务访问地址格式：

 ```
 https://<name>-<port>.<host-suffix>
 ```

-例如: `https://claude-proxy-1-80.dev.d8d.fun`
+示例: `https://claude-proxy-1-80.dev.d8d.fun`

-## 工作流程
+## 故障排查

-1. 确认 `.env` 配置正确
-2. 运行 `pnpm deploy <name> <image>` 部署服务
-3. 等待 Pod 启动（通常需要 1-2 分钟）
-4. 使用 `pnpm deploy status <name>` 检查状态
-5. 通过返回的 HTTPS 地址访问服务
+如果部署失败或服务不可用：
+
+1. **检查 Pod 状态**: `pnpm deploy status <name>`
+2. **检查环境变量**: 确认 `.env` 配置正确
+3. **检查镜像**: 确认镜像版本存在且可访问
+4. **检查 K8S 连接**: 确认 K8S_API_URL 和 K8S_API_TOKEN 有效
+
+## 典型工作流
+
+```
+1. 确认 .env 配置 → 2. 运行 deploy 命令 → 3. 等待 Pod 启动(1-2分钟) → 4. 检查 status → 5. 通过 HTTPS 访问
+```
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -1,86 +1,109 @@
 ---
 name: release
-description: 创建和推送版本标签触发 CI/CD 发布流程。当用户要求发布新版本、创建标签、发布 release、触发构建时使用。触发词: release, 发布, 版本, tag, 标签, v0.0.x, 构建镜像, docker build。
+description: 创建和推送版本标签触发 CI/CD 构建 Docker 镜像。只要用户想要发布新版本、打标签、触发构建、更新镜像就必须使用此技能。触发词: release, 发布, 版本, tag, 标签, v0.0.x, 构建镜像, docker build, 推送镜像, 新版本, 更新版本, 打包发布。即使用户只说"发布一下"或"打个新版本"，也应使用此技能。
 ---

 # 版本发布管理

-用于创建和管理版本标签，触发 Gitea Actions 自动构建 Docker 镜像。
+创建和管理版本标签，通过 Gitea Actions 自动构建并推送 Docker 镜像。

-## 发布新版本
+## 核心命令

 ```bash
 ./scripts/release_tag.sh [version]
 ```

-### 使用方式
+## 使用方式

-1. **自动递增版本（推荐）**
-   ```bash
-   ./scripts/release_tag.sh
-   ```
-   自动检测最新版本并递增 PATCH 号。
+### 1. 自动递增版本（推荐日常使用）

-2. **指定版本号**
-   ```bash
-   # 以下格式都支持，会自动添加 release/v 前缀
-   ./scripts/release_tag.sh 1.0.0
-   ./scripts/release_tag.sh v1.0.0
-   ./scripts/release_tag.sh release/v1.0.0
-   ```
+```bash
+./scripts/release_tag.sh
+```

-3. **查看所有标签**
-   ```bash
-   ./scripts/release_tag.sh --list
-   # 或
-   ./scripts/release_tag.sh -l
-   ```
+自动检测最新版本并递增 PATCH 号（如 v0.0.1 → v0.0.2）。

-## 版本命名规则
+### 2. 指定版本号

- 标签格式: `release/v<major>.<minor>.<patch>`
- 示例: `release/v0.0.1`, `release/v0.0.2`, `release/v1.0.0`
- 从 `release/v0.0.1` 开始
+```bash
+# 以下格式都支持，脚本会自动标准化
+./scripts/release_tag.sh 1.0.0       # → release/v1.0.0
+./scripts/release_tag.sh v1.0.0      # → release/v1.0.0
+./scripts/release_tag.sh release/v1.0.0  # → release/v1.0.0
+```

-## 发布流程
+### 3. 查看现有标签

-执行发布脚本后会自动:
+```bash
+./scripts/release_tag.sh --list
+# 或
+./scripts/release_tag.sh -l
+```

-1. **检查工作目录** - 提示未提交的更改
+## 版本命名规范
+
+- **格式**: `release/v<major>.<minor>.<patch>`
+- **示例**: `release/v0.0.1`, `release/v0.0.2`, `release/v1.0.0`
+- **递增规则**:
+  - PATCH: Bug 修复、小改进
+  - MINOR: 新功能、向后兼容
+  - MAJOR: 重大变更、不兼容更新
+
+## 发布流程（执行脚本后自动进行）
+
+1. **检查工作目录** - 如果有未提交更改会提示
 2. **拉取最新代码** - `git pull gitea <branch>`
 3. **创建标签** - `git tag release/vX.X.X`
 4. **推送标签** - `git push gitea release/vX.X.X`
-5. **触发 CI** - Gitea Actions 自动构建 Docker 镜像
+5. **触发 CI** - Gitea Actions 自动开始构建

-## CI/CD 说明
+## CI/CD 自动化

-标签推送后，Gitea Actions 会自动:
+标签推送后，Gitea Actions 会自动：

 1. 构建多架构 Docker 镜像 (amd64, arm64)
 2. 推送到阿里云容器镜像仓库
 3. 镜像地址: `registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:vX.X.X`

-## 注意事项
-
- 发布前确保所有更改已提交
- 版本号格式必须符合语义化版本规范
- ECI 容器环境会自动配置 SSH 连接参数
- 如果推送失败，检查 `gitea` 远程仓库配置
-
 ## 完整发布工作流

 ```bash
-# 1. 确保代码已提交
+# 步骤 1: 确保代码已提交并推送
 git add .
 git commit -m "feat: 新功能描述"
 git push gitea main

-# 2. 发布新版本
+# 步骤 2: 发布新版本
 ./scripts/release_tag.sh

-# 3. 等待 CI 构建完成
-# 访问 Gitea Actions 页面查看构建状态
+# 步骤 3: 等待 CI 构建完成（约 3-5 分钟）
+# 可在 Gitea Actions 页面查看进度

-# 4. 部署新版本
+# 步骤 4: 部署新版本镜像
 pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:vX.X.X
 ```
+
+## 常见问题
+
+### 推送标签失败
+
+- 检查 `gitea` 远程仓库配置: `git remote -v`
+- 确认有推送权限
+- 检查网络连接
+
+### 标签已存在
+
+- 使用 `--list` 查看现有标签
+- 选择一个新的版本号
+
+### CI 构建失败
+
+- 检查 Gitea Actions 日志
+- 确认 Dockerfile 语法正确
+- 验证镜像仓库凭据配置
+
+## 注意事项
+
+- 发布前务必确保代码已推送到远程
+- 版本号一旦推送不可修改（需删除后重建）
+- ECI 环境会自动处理 SSH 相关配置