# skill-web

**Repository Path**: fgai/skill-web

## Basic Information

- **Project Name**: skill-web
- **Description**: skill-web-app 是一个全栈 Web 应用，提供基于浏览器的交互式终端界面，用于执行和管理 AI skill技能（如博客写作、代码审查等），当前主要基于 Claude code 执行 skill。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# skill-web

基于浏览器的交互式终端界面，用于执行和管理 AI Skill 技能（如博客写作、代码审查等），当前主要基于 Claude Code 执行 Skill。

## 功能特性

- **Web 终端** — 基于 xterm.js 的浏览器内终端，通过 WebSocket 实时交互
- **Skill 管理** — 可配置的技能注册表，支持自定义技能扩展
- **用户认证** — JWT 认证体系，支持注册、登录及会话管理
- **会话记录** — 记录每次 Skill 执行的用户、时间和状态
- **安全防护** — 多层输入过滤与命令白名单，防止危险操作
- **一键启动** — 脚本自动安装依赖并启动前后端服务

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 + Vite + React Router + xterm.js |
| 后端 | FastAPI + Uvicorn + WebSocket |
| 数据库 | SQLite（SQLAlchemy ORM） |
| 认证 | JWT（PyJWT + Passlib/bcrypt） |

## 项目结构

```
skill-web/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── main.py          # FastAPI 入口
│   │   ├── config.py        # 配置管理
│   │   ├── database.py      # 数据库连接
│   │   ├── models.py        # 数据模型（User, SessionHistory）
│   │   ├── schemas.py       # 请求/响应 Schema
│   │   ├── auth/            # 认证模块（注册/登录/JWT）
│   │   ├── skills/          # 技能模块（注册表/列表接口）
│   │   └── terminal/        # 终端模块（WebSocket/PTY/安全）
│   ├── data/                # SQLite 数据文件
│   └── requirements.txt     # Python 依赖
├── frontend/                # 前端应用
│   ├── src/
│   │   ├── App.jsx          # 路由配置
│   │   ├── context/         # AuthContext 认证状态
│   │   ├── api/             # HTTP 客户端
│   │   ├── pages/           # 页面组件
│   │   └── components/      # 通用组件（TerminalView, SkillCard, Header）
│   ├── package.json         # Node 依赖
│   └── vite.config.js       # Vite 配置（含 API/WS 代理）
├── outputs/                 # Skill 输出目录
├── skills.json              # 技能注册配置
├── start.sh                 # 一键启动脚本
└── README.md
```

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+
- Claude Code CLI（已安装并配置）

### 启动服务

```bash
chmod +x start.sh
./start.sh
```

脚本将自动完成以下步骤：

1. 安装 Python 后端依赖（`pip install -r requirements.txt`）
2. 安装 Node 前端依赖（`npm install`）
3. 启动后端服务（端口 8000）
4. 启动前端服务（端口 3000）

启动后访问 http://localhost:3000 即可使用。

### 手动启动

**后端：**

```bash
cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**前端：**

```bash
cd frontend
npm install
npm run dev
```

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/register` | 用户注册 |
| POST | `/api/auth/login` | 用户登录 |
| GET | `/api/auth/me` | 获取当前用户信息 |
| GET | `/api/skills` | 获取技能列表 |
| GET | `/api/skills/{name}` | 获取技能详情 |
| WS | `/ws/{session_id}?token=JWT` | 终端 WebSocket 连接 |
| GET | `/health` | 健康检查 |

## 技能配置

在 `skills.json` 中注册技能：

```json
{
  "skills": [
    {
      "name": "blog-writing",
      "display_name": "博客写作",
      "description": "专业博客写作，支持结构规划、受众定位、SEO优化和AI配图",
      "icon": "pencil",
      "color": "#3b8eea",
      "category": "内容创作",
      "working_directory": "/path/to/skills"
    }
  ]
}
```

| 字段 | 说明 |
|------|------|
| `name` | 技能标识（对应 Claude Code 中的 Skill 名称） |
| `display_name` | 前端显示名称 |
| `description` | 技能描述 |
| `icon` | 图标类型（pencil / search / code / terminal） |
| `color` | 主题色 |
| `category` | 分类标签 |
| `working_directory` | Skill 执行时的工作目录 |

## 工作原理

```
浏览器 (xterm.js)  ←— WebSocket —→  FastAPI  ←— PTY —→  Claude Code CLI
```

1. 用户在前端选择一个 Skill 并提交参数
2. 前端通过 WebSocket 连接后端，发送 `start_skill` 消息
3. 后端创建 PTY（伪终端），启动 Claude Code CLI 进程
4. 终端输入/输出通过 WebSocket 实时双向传输
5. 前端使用 xterm.js 渲染终端输出，用户可直接交互

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DATABASE_URL` | `sqlite:///./data/skill_web_app.db` | 数据库连接地址 |
| `SECRET_KEY` | 内置默认值 | JWT 签名密钥（生产环境务必修改） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440` | Token 过期时间（分钟） |

## 贡献指南

1. Fork 本仓库
2. 创建功能分支（`git checkout -b feat/your-feature`）
3. 提交代码（`git commit -m 'feat: add some feature'`）
4. 推送分支（`git push origin feat/your-feature`）
5. 创建 Pull Request

## 许可证

[AGPL-3.0](LICENSE)