# 脚本清单与使用说明

本目录位于 `~/download/artifacts/skillhub-offline/scripts`，包含用于构建、加载、部署和发布 SkillHub 离线技能包的各类 Bash 脚本以及少量 Python 辅助脚本。下面按功能分类列出所有脚本，提供简要功能说明、常用调用方式及关键参数。

---

## 📦 构建（Build）
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `build-addyosmani-agent-skills-pack.sh` | 打包 **AddyOSMani** 代理技能为离线 tar.gz 包，并生成 SHA256 校验文件。 | `./build-addyosmani-agent-skills-pack.sh` （默认使用当前日期生成文件名） |
| `build-clawhub-cli-image.sh` | 构建 ClawHub CLI Docker 镜像。 | `./build-clawhub-cli-image.sh` |
| `build-devops-testing-skill-pack.py` | 使用 Python 脚本收集、整理 DevOps 测试相关技能并输出到 `seed-skills/`。 | `python3 build-devops-testing-skill-pack.py` |
| `build-devops-testing-skill-pack.sh` | 包装 `build-devops-testing-skill-pack.py`，提供统一入口。 | `./build-devops-testing-skill-pack.sh` |
| `build-github-skill-offline-pack.sh` | 打包 GitHub 相关离线技能（包括源码、报告、下载文件）。 | `./build-github-skill-offline-pack.sh` |

## 📥 收集（Collect）
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `collect-github-skills.py` | 调用 GitHub API 下载指定仓库的技能源码，生成 `seed-skills/` 目录结构并写入报告。 | `python3 collect-github-skills.py --sources config/…json --output seed-skills/… --downloads downloads/github --reports reports` |

## 🚀 部署（Deploy）
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `deploy-offline-skills.sh` | 代理脚本，实际执行 `deploy-offline-skills-docker.sh`（Docker‑Compose 部署离线 SkillHub）。 | `./deploy-offline-skills.sh` |
| `deploy-offline-skills-docker.sh` | 使用 Docker‑Compose 启动离线 SkillHub（后台服务）。 | `./deploy-offline-skills-docker.sh` |
| `deploy-skillhub-oneclick.sh` | 一键部署脚本：加载 Docker 镜像 → 启动容器 → 检查健康状态 → 发布默认种子技能。适用于本地快速演示。 | `./deploy-skillhub-oneclick.sh` （可通过环境变量自定义 `.env`、`docker-compose.yaml`、端口等） |

## 📦 加载（Load）
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `load-clawhub-cli-image.sh` | 将本地构建好的 ClawHub CLI 镜像加载到 Docker 本地镜像库。 | `./load-clawhub-cli-image.sh` |
| `load-github-skills-offline-pack.sh` | 将离线 GitHub 技能包（tar.gz）导入到本地 `seed-skills/` 目录。 | `./load-github-skills-offline-pack.sh <tarball>` |
| `load-images.sh` | 批量拉取 SkillHub 运行所需的 Docker 镜像（包括 backend、frontend、数据库等）。 | `./load-images.sh` |
| `load-offline-skill-pack.sh` | 将通用离线技能包解压并放置到 `seed-skills/`。 | `./load-offline-skill-pack.sh <tarball>` |

## 📤 发布（Publish）
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `publish-seed-skills.sh` | 将本地 `seed-skills/` 中的技能通过 REST API 注册到运行中的 SkillHub 实例。支持单个目录或全量种子。 | `./publish-seed-skills.sh <source_dir> <namespace>` |

## 📦 其它工具
| 脚本 | 说明 | 常用用法 |
|---|---|---|
| `pull-save-images.sh` | 拉取并保存所有 SkillHub 相关 Docker 镜像到本地 tar 包，以便离线迁移。 | `./pull-save-images.sh` |

---

# 使用说明（How‑to‑Use）

## 1. 环境准备
```bash
# 确保已安装 Docker & Docker‑Compose（>=2.0）
# 推荐使用 Bash 4.4+，脚本已声明 set -euo pipefail
# 若需执行 Python 脚本，请确保系统已装 Python3（>=3.8）
```

## 2. 常见工作流
### 2.1 本地快速演示（One‑Click）
```bash
# 一键加载镜像、启动容器、发布默认种子技能
cd ~/download/artifacts/skillhub-offline/scripts
chmod +x *.sh
./deploy-skillhub-oneclick.sh
```
> **提示**：可以通过环境变量自定义配置文件路径，例如：
> ```bash
> ENV_FILE=./my.env COMPOSE_FILE=./docker-compose.override.yaml ./deploy-skillhub-oneclick.sh
> ```

### 2.2 离线构建技能包
```bash
# 以 AddyOSMani 代理技能为例
./build-addyosmani-agent-skills-pack.sh
# 打包完成后会在 artifacts/ 生成类似：
#   addyosmani-agent-skills-offline-20260703.tar.gz
#   同名 .sha256 校验文件
```

### 2.3 将离线包导入并发布
```bash
# 加载 tar 包到本地工作区
./load-github-skills-offline-pack.sh artifacts/addyosmani-agent-skills-offline-20260703.tar.gz
# 将技能注册到已经运行的 SkillHub 实例（假设 API 地址为 http://127.0.0.1:8080）
export CLAWHUB_REGISTRY="http://127.0.0.1:8080"
./publish-seed-skills.sh seed-skills/addyosmani-agent-skills addyosmani-agent-skills
```

### 2.4 自定义 Docker 镜像
```bash
# 构建自定义 ClawHub CLI 镜像
./build-clawhub-cli-image.sh
# 加载到本地 Docker 仓库（可选）
./load-clawhub-cli-image.sh
```

## 3. 参数与环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
| `ROOT_DIR` | 脚本根目录（自动计算） | 脚本所在目录的上级 |
| `ENV_FILE` | Docker‑Compose 使用的 `.env` 文件路径 | `${ROOT_DIR}/.env.release` |
| `COMPOSE_FILE` | Docker‑Compose 主配置文件 | `${ROOT_DIR}/docker-compose.yaml` |
| `API_PORT` | SkillHub 后端对外端口 | `8080` |
| `CLAWHUB_REGISTRY` | 后端 API 基础 URL | `http://127.0.0.1:${API_PORT}` |
| `WEB_PORT` | 前端 Web 端口（仅用于打印） | `80` |

> **注意**：多数脚本在开头均使用 `set -euo pipefail`，任何错误都会导致脚本立即退出，请确保所有必需的环境变量已正确定义。

---

# 清理脚本（cleanup.sh）
如需删除不再需要的脚本，可使用以下自动化清理脚本。先在 `retain_files` 数组中列出 **需要保留** 的文件名（完整文件名），脚本会安全删除其余文件。

```bash
#!/usr/bin/env bash
set -euo pipefail

# ------------------- 配置区 -------------------
# 将需要保留的脚本文件名放入数组（无需路径，只要文件名）
retain_files=(
  "deploy-offline-skills.sh"
  "deploy-skillhub-oneclick.sh"
  "load-images.sh"
)
# ------------------- 代码区 -------------------
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# 将数组转为正则模式，用于匹配需要保留的文件
retain_pattern=$(printf "|%s" "${retain_files[@]}")
retain_pattern=${retain_pattern:1}   # 去掉首个 '|'

echo "清理目录: $SCRIPT_DIR"
for file in "$SCRIPT_DIR"/*; do
  filename=$(basename "$file")
  if [[ -f "$file" ]]; then
    if [[ ! "$filename" =~ ^($retain_pattern)$ ]]; then
      echo "删除: $filename"
      rm -f "$file"
    else
      echo "保留: $filename"
    fi
  fi
done

echo "清理完成。"
```

**使用方法**：
1. 将上述内容保存为 `cleanup.sh`（与其他脚本同目录）。
2. `chmod +x cleanup.sh` 并执行 `./cleanup.sh`。
3. 如需修改保留列表，只编辑脚本顶部的 `retain_files` 数组即可。

---

# 小结
- 本文提供了完整的 **脚本清单** 与 **使用说明**，帮助您快速上手 SkillHub 离线部署与技能打包。
- `cleanup.sh` 可帮助您一键删除不需要的脚本，保持工作目录整洁。
- 如需进一步自定义或扩展，请参考各脚本内部的 `ENV_*` 环境变量说明。

如有其他需求或需要对保留列表进行微调，请告诉我！