# 增强的 Skill 生成功能 - 使用指南

## 📋 概述

本次更新为 Creative Studio 添加了**文档驱动的 Skill 生成工作流**，完全集成到现有架构中。

---

## ✨ 新功能

### 1. 文档获取 API

| 端点 | 功能 |
|-----|------|
| `POST /api/v1/skills/fetch-doc` | 从 URL 获取文档内容 |
| `POST /api/v1/skills/fetch-github-doc` | 从 GitHub 获取 README/docs |

**请求示例：**
```json
// 获取网页文档
{
  "url": "https://docs.example.com",
  "selector": "article"  // 可选 CSS 选择器
}

// 获取 GitHub 文档
{
  "repo_url": "https://github.com/owner/repo",
  "docs_path": "README.md"
}
```

---

### 2. 文档驱动的 Skill 生成

**端点：** `POST /api/v1/skills/generate-from-docs`

**完整工作流：**
```
用户输入 → 文档获取 → LLM 生成 → 预览 → 调整 → 保存
   ↓           ↓          ↓       ↓       ↓      ↓
 名称/URL   自动爬取    AI生成   即时预览  AI/手动  统一管理
```

**请求示例：**
```json
{
  "skill_name": "React 开发助手",
  "description": "帮助开发者使用 React 框架",
  "category": "development",
  "tags": ["react", "frontend", "javascript"],
  "doc_urls": [
    "https://react.dev/learn",
    "https://react.dev/reference/react"
  ],
  "github_repos": [
    {
      "repo_url": "https://github.com/facebook/react",
      "docs_path": "README.md"
    }
  ],
  "uploaded_references": {
    "custom_notes.md": "# 自定义笔记\n..."
  },
  "temperature": 0.7,
  "include_doc_summary": true
}
```

**响应示例：**
```json
{
  "success": true,
  "preview_id": "550e8400-e29b-41d4-a716-446655440000",
  "skill_content": "---\nname: react-assistant\ndescription: ...\n\n# React 开发助手\n...",
  "skill_name": "React 开发助手",
  "suggested_id": "react-assistant",
  "category": "development",
  "tags": ["react", "frontend"],
  "doc_summary": "- React Learn (https://react.dev/learn)\n- README.md",
  "references_count": 5,
  "explanation": "已基于 React 官方文档生成 Skill"
}
```

---

### 3. Skill 预览

**端点：** `POST /api/v1/skills/preview`

在保存前预览和验证 Skill 内容。

**请求示例：**
```json
{
  "skill_content": "---\nname: my-skill\n...\n",
  "skill_name": "My Skill",
  "category": "通用",
  "tags": ["custom"]
}
```

**响应示例：**
```json
{
  "preview_id": "...",
  "skill_content": "...",
  "parsed_metadata": {
    "name": "my-skill",
    "description": "..."
  },
  "validation_warnings": [
    "缺少 description 字段"
  ],
  "word_count": 1250,
  "estimated_tokens": 1625
}
```

---

### 4. AI 调整/优化

**端点：** `POST /api/v1/skills/refine`

使用自然语言提示词让 AI 调整 Skill。

**请求示例：**
```json
{
  "skill_content": "---\nname: my-skill\n...",
  "refinement_prompt": "把行为指导改得更简洁，增加代码示例",
  "temperature": 0.5
}
```

**提示词示例：**
- "把行为指导改得更简洁"
- "增加一个快速开始部分"
- "添加更多代码示例"
- "优化描述，让它更清晰"
- "用更专业的语气重写"

**响应示例：**
```json
{
  "success": true,
  "refined_content": "---\nname: my-skill\n...",
  "changes_summary": "根据提示词「把行为指导改得更简洁，增加代码示例」进行了调整",
  "original_length": 2500,
  "new_length": 3200
}
```

---

### 5. 保存到系统

**端点：** `POST /api/v1/skills/save-from-preview`

将预览的 Skill 保存到系统（统一后端管理）。

**请求示例：**
```json
{
  "preview_id": "550e8400-e29b-41d4-a716-446655440000",
  "skill_id": "my-skill",
  "skill_content": "---\nname: my-skill\n...",
  "references": {
    "api_reference.md": "# API 参考\n...",
    "examples.md": "# 示例\n..."
  }
}
```

**保存位置：**
```
backend/skills_storage/user_skills/my-skill/
├── SKILL.md
└── references/
    ├── api_reference.md
    └── examples.md
```

---

## 🔄 完整工作流示例

### 前端流程

```javascript
// 步骤 1: 用户输入并生成
const response = await fetch('/api/v1/skills/generate-from-docs', {
  method: 'POST',
  body: JSON.stringify({
    skill_name: 'React 助手',
    description: 'React 开发辅助',
    doc_urls: ['https://react.dev/learn'],
    temperature: 0.7
  })
});
const { preview_id, skill_content } = await response.json();

// 步骤 2: 显示预览
// 显示 skill_content，让用户查看

// 步骤 3: 用户调整（可选）
// 方式 A: 手动编辑
let editedContent = skill_content;

// 方式 B: AI 调整
const refineResponse = await fetch('/api/v1/skills/refine', {
  method: 'POST',
  body: JSON.stringify({
    skill_content: editedContent,
    refinement_prompt: '增加代码示例',
    temperature: 0.5
  })
});
const { refined_content } = await refineResponse.json();

// 步骤 4: 保存到系统
await fetch('/api/v1/skills/save-from-preview', {
  method: 'POST',
  body: JSON.stringify({
    preview_id: preview_id,
    skill_id: 'react-assistant',
    skill_content: refined_content
  })
});
```

---

## 🎨 前端页面建议

### Skill 创建页面布局

```
┌─────────────────────────────────────────────────────────────┐
│  创建新 Skill                                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  基础信息                                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Skill 名称: [React 开发助手                    ]    │   │
│  │ 描述:       [帮助开发者使用 React 框架         ]    │   │
│  │ 分类:       [development ▼]  标签: [+ Add tag]    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  文档来源                                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ URLs:                                               │   │
│  │   [+ Add URL]                                       │   │
│  │   • https://react.dev/learn              [×]        │   │
│  │   • https://react.dev/reference/react    [×]        │   │
│  │                                                     │   │
│  │ GitHub:                                             │   │
│  │   [+ Add GitHub Repository]                         │   │
│  │   • facebook/react (README.md)           [×]        │   │
│  │                                                     │   │
│  │ 上传 References:                                    │   │
│  │   [Drag & drop files or click to upload]           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  选项                                                       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Temperature: [━━●━━] 0.7                            │   │
│  │ ☑ 包含文档摘要                                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│                    [生成 Skill]                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 预览/编辑页面

```
┌─────────────────────────────────────────────────────────────┐
│  预览 Skill: React 开发助手                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  元数据                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ✅ name: react-assistant                             │   │
│  │ ✅ description: 帮助开发者使用 React 框架           │   │
│  │ ✅ category: development                             │   │
│  │ ✅ tags: react, frontend, javascript                │   │
│  │ ⚠️ 内容较长 (3200 tokens)                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  内容编辑器                                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ---                                                │   │
│  │ name: react-assistant                              │   │
│  │ description: 帮助开发者使用 React 框架             │   │
│  │ ---                                                │   │
│  │                                                    │   │
│  │ # React 开发助手                                    │   │
│  │                                                    │   │
│  │ ## 使用场景                                         │   │
│  │ ...                                                │   │
│  │                    [Markdown 编辑器]               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  AI 调整                                                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 提示词: [让内容更简洁              ]                 │   │
│  │         [AI 调整]                                      │   │
│  │                                                     │   │
│  │ 快捷提示词:                                          │   │
│  │ • [增加代码示例]  • [添加快速开始]  • [优化描述]    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  References (5 个文件)                                      │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ • react_learn.md (1250 词)                    [查看] │   │
│  │ • react_reference.md (800 词)                  [查看] │   │
│  │ • github_readme.md (450 词)                  [查看] │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│           [取消]              [保存 Skill]                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 🔧 依赖安装

确保安装以下依赖：

```bash
cd backend
pip install httpx beautifulsoup4
```

更新 `requirements.txt`：
```
httpx>=0.27.0
beautifulsoup4>=4.12.0
```

---

## 📝 API 端点总览

| 端点 | 方法 | 功能 |
|-----|------|------|
| `/api/v1/skills/fetch-doc` | POST | 获取网页文档 |
| `/api/v1/skills/fetch-github-doc` | POST | 获取 GitHub 文档 |
| `/api/v1/skills/generate-from-docs` | POST | 基于文档生成 Skill |
| `/api/v1/skills/preview` | POST | 预览 Skill |
| `/api/v1/skills/refine` | POST | AI 调整 Skill |
| `/api/v1/skills/save-from-preview` | POST | 保存 Skill |
| `/api/v1/skills/preview/{preview_id}` | GET | 获取预览数据 |
| `/api/v1/skills/preview/{preview_id}` | DELETE | 删除预览 |

---

## 🚀 后续优化建议

1. **预览存储优化**
   - 当前使用内存存储（`_preview_storage`）
   - 生产环境建议使用 Redis 或数据库

2. **异步处理**
   - 文档获取可以异步进行
   - 大文档处理可以返回任务 ID

3. **缓存机制**
   - 缓存已获取的文档
   - 避免重复获取相同 URL

4. **批量处理**
   - 支持批量生成 Skills
   - 批量导入文档

---

## 🐛 故障排除

### httpx 未安装

```bash
pip install httpx beautifulsoup4
```

### 文档获取失败

- 检查 URL 是否正确
- 确认目标网站是否允许爬取
- 尝试使用 CSS 选择器指定主内容区域

### LLM 生成质量不佳

- 调整 `temperature` 参数
- 提供更详细的描述
- 添加更多文档来源

---

生成时间：2025-01-26