getskills/PROJECT_SUMMARY.md

# GetSkill 项目总结

## 项目概述

**GetSkill** 是一个用于管理 OpenClaw 技能的命令行工具，支持从 getskill.work 搜索、安装和更新技能文件。

## 核心特性

### 1. 零外部依赖
- 仅使用 Node.js 内置模块
- 轻量级，安装快速
- 无需担心依赖冲突

### 2. Git 集成
- 自动检测 Git 安装状态
- Windows 平台自动下载 Git 安装程序
- macOS/Linux 提供安装指南
- 通过 Git 管理技能版本

### 3. 跨平台支持
- Windows (32/64位)
- macOS
- Linux (多发行版)
- 自动适配操作系统路径

### 4. 双目录架构
```
~/.claude/
├── skills/         # 技能文件（.md）
└── skills-cache/   # Git 仓库缓存
```

## 技术架构

### 依赖模块（全部为 Node.js 内置）

| 模块 | 用途 |
|------|------|
| `https/http` | API 请求和文件下载 |
| `fs` | 文件系统操作 |
| `path` | 路径处理 |
| `os` | 系统信息获取 |
| `child_process` | 执行 Git 命令 |

### 核心函数

| 函数 | 功能 |
|------|------|
| `searchSkills()` | 从 API 搜索技能 |
| `downloadSkill()` | 安装技能（Git clone） |
| `updateSkill()` | 更新技能（Git pull） |
| `checkGitInstalled()` | 检测 Git |
| `ensureGitInstalled()` | 确保 Git 可用 |
| `cloneOrUpdateRepo()` | Git 仓库管理 |
| `copySkillFiles()` | 复制技能文件 |

## API 接口设计

### 搜索接口
```
GET https://getskill.work/api/skills/search?q=<关键词>

Response:
{
  "skills": [
    {
      "id": "skill-id",
      "name": "skill-name",
      "description": "描述",
      "git_url": "https://github.com/...",
      "author": "作者"
    }
  ]
}
```

### 详情接口
```
GET https://getskill.work/api/skills/<技能ID>

Response:
{
  "id": "skill-id",
  "name": "skill-name",
  "git_url": "https://github.com/...",
  "description": "描述",
  "files": ["skill.md"],
  ...
}
```

## 命令行界面

```bash
# 搜索
getskill search <关键词>

# 安装
getskill install <技能名称>

# 更新
getskill update <技能名称>

# 列出
getskill list

# 路径
getskill path

# 清理
getskill clean
```

## 文件结构

```
getskill/
├── index.js              # 主程序（578 行）
├── package.json          # 项目配置
├── README.md             # 使用文档
├── EXAMPLES.md           # 使用示例
├── CONTRIBUTING.md       # 贡献指南
├── CHANGELOG.md          # 变更日志
├── LICENSE               # MIT 许可证
├── verify.js             # 验证脚本
├── .gitignore           # Git 忽略文件
└── .npmignore           # NPM 忽略文件
```

## 开发统计

- **总代码行数**: ~580 行（index.js）
- **函数数量**: 15+ 个
- **支持的命令**: 6 个
- **支持的平台**: 3 个（Windows/macOS/Linux）
- **外部依赖**: 0 个

## 工作流程

### 安装流程
```
用户执行: getskill install commit-helper
    ↓
检查 Git 是否安装
    ↓
调用 API 获取技能详情（含 git_url）
    ↓
执行 git clone 到缓存目录
    ↓
复制 .md 文件到 skills 目录
    ↓
完成
```

### 更新流程
```
用户执行: getskill update commit-helper
    ↓
检查缓存目录是否存在仓库
    ↓
进入仓库目录
    ↓
执行 git pull
    ↓
重新复制 .md 文件
    ↓
完成
```

## 特殊处理

### Git 自动安装

#### Windows
1. 检测系统架构（32/64位）
2. 下载对应的 Git 安装程序
3. 显示下载进度
4. 启动安装向导
5. 提示用户完成安装后重新运行

#### macOS
- 提示使用 Homebrew: `brew install git`
- 提供 Homebrew 安装链接

#### Linux
- 根据发行版提供对应命令
- 支持 apt、yum、dnf、pacman

## 错误处理

- 网络错误：捕获并提示
- Git 未安装：自动引导安装
- API 失败：显示错误信息
- 文件不存在：创建目录
- 仓库克隆失败：显示 Git 错误

## 使用场景

1. **开发者**: 快速安装和更新技能
2. **团队**: 统一技能版本管理
3. **CI/CD**: 自动化技能部署
4. **学习者**: 探索可用技能

## 性能特点

- 轻量级：无外部依赖
- 快速：直接使用 Git
- 可靠：Git 版本控制
- 缓存：避免重复下载

## 安全考虑

- 仅使用 HTTPS 连接
- 不存储敏感信息
- Git URL 验证
- 沙箱化技能目录

## 未来计划

- [ ] 技能版本管理
- [ ] 依赖解析
- [ ] 离线模式
- [ ] 配置文件支持
- [ ] Shell 自动补全
- [ ] 技能备份/恢复
- [ ] 交互式安装
- [ ] 单元测试

## 发布清单

- [x] 核心功能实现
- [x] Git 自动检测
- [x] 跨平台支持
- [x] 文档完善
- [x] 验证脚本
- [x] 示例文档
- [ ] 单元测试
- [ ] CI/CD 集成
- [ ] NPM 发布

## 贡献者

- workskills.store - 初始开发

## 许可证

MIT License - 详见 LICENSE 文件

---

**项目状态**: ✅ 功能完整，准备发布 v1.0.0

**最后更新**: 2026-03-21