407 lines
14 KiB
Markdown
407 lines
14 KiB
Markdown
# 增强的 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
|