creative_studio/backend/docs/SKILL_GENERATION_GUIDE.md

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

📋 概述

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

---

✨ 新功能

1. 文档获取 API

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

请求示例：

// 获取网页文档
{
  "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/手动  统一管理

请求示例：

{
  "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
}

响应示例：

{
  "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 内容。

请求示例：

{
  "skill_content": "---\nname: my-skill\n...\n",
  "skill_name": "My Skill",
  "category": "通用",
  "tags": ["custom"]
}

响应示例：

{
  "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。

请求示例：

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

提示词示例：

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

响应示例：

{
  "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 保存到系统（统一后端管理）。

请求示例：

{
  "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

---

🔄 完整工作流示例

前端流程

// 步骤 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]                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

🔧 依赖安装

确保安装以下依赖：

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 未安装

pip install httpx beautifulsoup4

文档获取失败

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

LLM 生成质量不佳

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

---

生成时间：2025-01-26