# convenient-skill

**Repository Path**: masterkgw/convenient-skill

## Basic Information

- **Project Name**: convenient-skill
- **Description**: 一个支持上传、下载和通过 HTTP 直链获取 Skill 的 Web 平台，便于在 Cursor、Claude Code 等 AI 开发工具中复用。


- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# convenient-skill - AI Skill 共享平台

一个支持上传、下载和通过 HTTP 直链获取 Skill 的 Web 平台，便于在 Cursor、Claude Code 等 AI 开发工具中复用。

## 核心功能

- ✅ **Skill 托管** - 支持 Markdown 文本和文件上传
- ✅ **HTTP 直链** - `/raw/:slug` 接口，AI 工具可直接引用
- ✅ **分类检索** - 主分类 + 标签的多维度筛选
- ✅ **公开访问** - 无需登录即可浏览和使用 Skill
- ✅ **GitHub 登录** - 一键创建和管理自己的 Skill
- ✅ **私有/公开切换** - Skill 作者可随时控制可见性
- ✅ **管理员权限** - 管理员可管理所有 Skill（包括私有）

## 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 语言 | Python | 3.11+ |
| Web 框架 | FastAPI | 0.109+ |
| ORM | SQLAlchemy | 2.0+ |
| 数据库 | SQLite (MVP) | - |
| 模板 | Jinja2 | 3.1+ |
| 认证 | GitHub OAuth | - |
| 部署 | Render | - |

## 项目结构

```
convenient-skill/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 入口
│   ├── config.py               # 配置管理
│   ├── database.py             # 数据库连接
│   ├── models.py               # SQLAlchemy 模型
│   ├── schemas.py              # Pydantic 模型
│   ├── dependencies.py         # 依赖注入
│   ├── routers/
│   │   ├── pages.py            # 页面路由
│   │   ├── api/
│   │   │   ├── skills.py       # Skill API
│   │   │   └── auth.py         # 认证 API
│   │   └── raw.py              # /raw 直链
│   ├── services/
│   │   ├── skill_service.py    # Skill 业务逻辑
│   │   ├── file_service.py     # 文件上传处理
│   │   └── auth_service.py     # 认证逻辑
│   └── templates/              # Jinja2 模板
├── static/                     # 静态文件
├── uploads/                    # 临时上传目录
├── migrations/                 # 数据库迁移
├── requirements.txt
└── README.md
```

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <repository-url>
cd convenient-skill

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填写：

```bash
# 应用配置
APP_NAME=SkillHub
DEBUG=true
SECRET_KEY=your-secret-key-here

# 数据库
DATABASE_URL=sqlite:///./convenient-skill.db

# GitHub OAuth (在 GitHub Settings > Developer settings > OAuth Apps 创建)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# 部署后修改为实际域名
BASE_URL=http://localhost:8000
```

### 3. 初始化数据库

```bash
# 创建迁移
alembic revision --autogenerate -m "init"

# 执行迁移
alembic upgrade head
```

### 4. 运行开发服务器

```bash
# 本地访问（仅本机可访问）
uvicorn app.main:app --reload

# 局域网访问（允许同一网络其他设备访问）
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**访问地址**：

| 用途 | 本地访问 | 局域网访问 | 说明 |
|------|---------|-----------|------|
| **应用首页** | http://localhost:8000 | http://<你的IP>:8000 | Skill 浏览、搜索、管理 |
| API 文档 | http://localhost:8000/docs | http://<你的IP>:8000/docs | Swagger UI 接口文档 |
| 备选文档 | http://localhost:8000/redoc | http://<你的IP>:8000/redoc | ReDoc 接口文档 |
| 健康检查 | http://localhost:8000/health | http://<你的IP>:8000/health | 服务状态检测 |

**获取本机 IP 地址**：
```bash
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Windows
ipconfig
```

## 数据模型

### Skill 模型

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| slug | String(100) | URL 标识，唯一 |
| title | String(200) | 标题 |
| description | String(500) | 描述 |
| content | Text | Markdown 内容 |
| category | String(50) | 主分类 |
| tags | String(200) | 逗号分隔的标签 |
| **is_public** | **Boolean** | **是否公开（可在首页一键切换）** |
| views | Integer | 浏览次数 |
| author_id | String(50) | GitHub 用户 ID |
| author_name | String(100) | 作者名 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

**私有 Skill 规则**：
- 作者本人：可在首页列表看到自己的私有 Skill
- 其他用户：无法看到或访问（返回 404）
- 管理员：可以看到所有私有 Skill 并进行管理

## API 接口

### 公开接口（无需认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/skills` | 列表（支持筛选） |
| GET | `/skills/:slug` | 详情 |
| GET | `/raw/:slug` | **原始内容直链** |
| GET | `/search` | 搜索 |
| GET | `/api/skills/by-tag/:tag` | 按标签查询（空标签返回空） |

### 需认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/skills` | 创建 Skill |
| PUT | `/api/skills/:id` | 更新 Skill |
| DELETE | `/api/skills/:id` | 删除 Skill |
| GET | `/api/auth/github` | GitHub 登录 |
| GET | `/api/auth/callback` | 登录回调 |
| GET | `/api/auth/logout` | 登出 |

### 核心接口：/raw/:slug

这是最重要的接口，用于 AI 工具直接获取 Skill 内容：

```bash
# 获取原始 Markdown 内容
curl https://convenient-skill.vercel.app/raw/python-expert

# 返回纯文本，可直接用于 .cursorrules 或 system prompt
```

## 分类体系

### 主分类（单选）

| 分类 | 图标 | 说明 |
|------|------|------|
| 前端开发 | 💻 | React, Vue, CSS 等 |
| 后端开发 | ⚙️ | Python, Java, Go 等 |
| 移动开发 | 📱 | iOS, Android, Flutter |
| AI/ML | 🤖 | LLM, 深度学习, Prompt |
| 数据库 | 🗄️ | MySQL, Redis, Mongo |
| DevOps | ☁️ | Docker, K8s, CI/CD |
| 设计 | 🎨 | UI, UX, 原型 |
| 业务分析 | 📊 | 需求分析, 数据洞察 |
| 写作 | 📝 | 技术文档, 博客 |
| 工具 | 🔧 | Git, IDE, 命令行 |
| 通用 | 🌐 | 跨领域技能 |

### 标签（多选）

- **上传者自定义**，多个标签用逗号分隔
- **默认为空**，不强制要求填写
- 用于**分组和筛选**相同标签的 Skill

**标签查询规则**：
- 查询指定标签时，返回包含该标签的所有 Skill
- **查询空标签时，不返回数据**（避免无意义的全量查询）

**常用标签**：
- **技术**: `python`, `java`, `react`, `vue`, `fastapi`
- **场景**: `crud`, `api-design`, `testing`, `refactoring`
- **角色**: `junior`, `senior`, `architect`, `fullstack`
- **项目**: `convenient-skill-official`（项目官方推荐）

## 权限控制

| 角色 | 可见范围 | 操作权限 |
|------|---------|---------|
| **访客** | 公开 Skill | 浏览、搜索、使用 /raw 直链 |
| **登录用户** | 公开 Skill + 自己的私有 Skill | 创建、编辑、删除自己的 Skill；切换私有/公开状态 |
| **管理员** | **所有 Skill**（公开 + 所有私有） | 管理任意 Skill（编辑、删除、切换状态） |

## 部署

### Render（推荐）

```yaml
# render.yaml
services:
  - type: web
    name: convenient-skill
    runtime: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT
    envVars:
      - key: PYTHON_VERSION
        value: 3.11.0
```

### Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

## 开发规范

### 代码风格

- 使用 Black 格式化代码
- 类型提示必需
- 异步函数使用 `async/await`
- 依赖注入管理数据库会话

### 提交规范

```
feat: 新功能
fix: 修复
docs: 文档
style: 格式调整
refactor: 重构
test: 测试
chore: 构建/工具
```

## 使用场景示例

### 场景 1：在 Cursor 中使用

```bash
# 获取 skill 并添加到 .cursorrules
curl -fsSL https://convenient-skill.vercel.app/raw/python-expert >> .cursorrules
```

### 场景 2：在 Claude Code 中使用

```bash
# 获取 skill 并设置为 system prompt
claude config set system_prompt "$(curl -fsSL https://convenient-skill.vercel.app/raw/python-expert)"
```

### 场景 3：在 AI 对话中引用 URL

直接在 AI 编程工具的对话中粘贴 Skill URL，让 AI 自动获取并遵循：

```
用户: 请根据这个规范开发：https://convenient-skill.vercel.app/raw/fastapi-expert

AI: 我已获取 FastAPI 专家规范，将按照以下原则进行开发：
     - 使用异步函数和类型提示
     - 遵循 RESTful API 设计
     - 使用依赖注入管理数据库会话
     - ...

用户: 创建一个用户注册的 API 接口

AI: [按照获取的 skill 规范生成代码]
```

**支持的 AI 工具**：
- ✅ Cursor Chat (需配合插件或手动粘贴)
- ✅ Claude Code / Claude Desktop
- ✅ ChatGPT (粘贴 URL 后让 AI fetch 内容)
- ✅ 任何支持 URL 引用的 AI 编程助手

### 场景 4：批量导入同标签的 Skill

**第一步：查询标签下的所有 Skill**

```bash
# 查询带有 "convenient-skill-official" 标签的所有 Skill
curl https://convenient-skill.vercel.app/api/skills/by-tag/convenient-skill-official

# 返回结果：
# [
#   {"slug": "python-code-style", "title": "Python 代码规范专家", "tags": "python,pep8,convenient-skill-official"},
#   {"slug": "fastapi-expert", "title": "FastAPI 项目开发专家", "tags": "python,fastapi,convenient-skill-official"},
#   {"slug": "python-testing", "title": "Python 调试与测试专家", "tags": "python,testing,convenient-skill-official"}
# ]
```

**第二步：批量下载这些 Skill**

```bash
# 导入所有带有 convenient-skill-official 标签的 Skill
for skill in python-code-style fastapi-expert python-testing; do
  curl -fsSL https://convenient-skill.vercel.app/raw/$skill >> .cursorrules
done
```

**使用场景：**
- 团队成员统一使用公司/项目的标准 Skill 集合
- 新成员快速配置开发环境
- 项目初始化时一键导入所有相关规范

### 场景 5：在对话中直接使用

用户将 `/raw/:slug` 的内容复制粘贴到 AI 对话中作为上下文。

## 路线图

### MVP（1周）
- [x] 基础 CRUD
- [x] GitHub 登录
- [x] 文件上传
- [x] /raw 直链
- [x] 基础搜索

### Phase 2
- [ ] 版本管理
- [ ] 评分评论
- [ ] 收藏功能
- [ ] CLI 工具

### Phase 3
- [ ] Elasticsearch 搜索
- [ ] 组织/团队
- [x] ~~私有仓库~~（已实现 Skill 私有/公开切换）
- [ ] VS Code 插件

## 贡献指南

1. Fork 项目
2. 创建分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 许可证

MIT License