1
┌─────────────────────────────────────────────────────────┐│                   前端 · 技能中心页面                      ││  (Vue 3 + Naive UI · skill-center.vue)                  ││                                                         ││  ┌─────────┐  ┌──────────┐  ┌───────────┐  ┌────────┐  ││  │GitHub   │  │Zip上传   │  │技能列表    │  │使用教程 │  ││  │安装面板  │  │安装      │  │管理面板    │  │抽屉    │  ││  └────┬────┘  └────┬─────┘  └─────┬─────┘  └───┬────┘  │└───────┼────────────┼──────────────┼─────────────┼───────┘│            │              │             │▼            ▼              ▼             ▼┌─────────────────────────────────────────────────────────┐│              后端 · REST API (Sanic Blueprint)           ││  (controllers/skill_api.py)                             ││                                                         ││  POST /install/github  POST /install/upload             ││  GET  /list            POST /uninstall                  ││  POST /toggle          GET  /content                    ││  GET  /preview         POST /tutorial (SSE)             │└───────────────────────┬─────────────────────────────────┘│▼┌─────────────────────────────────────────────────────────┐│            核心服务 · SkillService                       ││  (services/skill_service.py)                            ││                                                         ││  - YAML Front Matter 解析                                ││  - GitHub zip 下载与解压                                  ││  - 独立虚拟环境创建 (_setup_skill_venv)                    ││  - 技能启用/禁用（.disabled 标记文件）                      ││  - 双 scope 目录管理（common / deep）                     │└─────────────────────────────────────────────────────────┘

1
2
3
# 两个技能目录，彼此隔离  COMMON_SKILLS_DIR = Path("agent/common/skills")      # docx, pdf, pptx, xlsx, web-access...  DEEP_SKILLS_DIR   = Path("agent/deepagent/skills")    # query-writing, report-generation...  

1
用户输入仓库地址 → 预览技能列表 → 勾选要安装的 → 一键安装  

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
async def preview_github_repo(cls, repo: str) -> list[dict]:      """预览 GitHub 仓库中的技能"""    branches = ["main", "master"]  # 自动尝试两个分支      for branch in branches:        try:            skills, temp_dir = await cls._download_github_skills(repo, branch)            if skills:                shutil.rmtree(temp_dir, ignore_errors=True)                  return skills        except Exception:              continue    return []```  ❝ 🔍 说明：  - 自动兼容 `main` 和 `master` 两种分支命名，无需用户手动指定  - 预览阶段只解析 `SKILL.md` 的 YAML Front Matter，不执行安装  - 支持仓库中包含多个技能（每个子目录一个 `SKILL.md`）  **Step 2：下载与解析**  ```python  async def _download_github_skills(cls, repo, branch, skill_names=None):      zip_url = f"https://github.com/{repo}/archive/refs/heads/{branch}.zip"    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:          response = await client.get(zip_url)        response.raise_for_status()        skills, temp_dir = cls._extract_skills_from_zip(response.content, skill_names)    return skills, temp_dir```  ❝ 🔍 说明：  - 通过 GitHub Archive API 下载 zip 包，无需 git clone，速度更快  - 使用 `httpx.AsyncClient` 异步下载，不阻塞 Sanic 事件循环  - 解压后递归扫描 `SKILL.md` 文件，自动识别技能边界  **Step 3：选择性安装**  前端展示预览结果后，用户可以勾选需要的技能，点击安装：  ```typescript  // 前端：全选 / 部分选择  const allPreviewSelected = computed({    get: () => previewList.value.length > 0    && selectedForInstall.value.length === previewList.value.length,  set: (val: boolean) => {    selectedForInstall.value = val ? previewList.value.map(s => s.name) : []  },})  

1
2
3
@bp.post("/install/upload")  async def install_from_upload(request: Request):      file = request.files["file"][0]    zip_bytes = file.body    installed = SkillService.install_from_zip(zip_bytes, filename, scope=scope)  

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@classmethod  def _setup_skill_venv(cls, skill_dir: Path) -> bool:      """为 skill 创建独立虚拟环境并安装依赖"""    requirements_file = skill_dir / "requirements.txt"    if not requirements_file.exists():        return True  # 无依赖，跳过      venv_dir = skill_dir / ".venv"    # 创建虚拟环境      subprocess.run(        [sys.executable, "-m", "venv", str(venv_dir)],          check=True, capture_output=True, timeout=300,      )      # 确定 pip 路径（跨平台兼容）      pip_path = (        venv_dir / "bin" / "pip"        if venv_dir.joinpath("bin").exists()        else venv_dir / "Scripts" / "pip.exe"    )      # 安装依赖      subprocess.run(        [str(pip_path), "install", "-r", str(requirements_file), "-q"],          check=True, capture_output=True, timeout=600,      )    return True```  ❝ 🔍 说明：  - **环境隔离**：每个技能拥有独立的 `.venv`，避免不同技能之间的包版本冲突  - **跨平台兼容**：自动适配 Linux/macOS（`bin/pip`）和 Windows（`Scripts/pip.exe`）  - **超时保护**：虚拟环境创建 5 分钟超时，依赖安装 10 分钟超时，防止卡死  - **无依赖跳过**：没有 `requirements.txt` 的技能直接安装，不额外消耗时间  

1
2
3
4
5
6
7
8
9
10
11
12
技能目录结构（安装后）：  agent/common/skills/  ├── docx/  │   ├── SKILL.md           # 技能定义文档  │   ├── requirements.txt   # Python 依赖声明（可选）  │   └── .venv/             # 自动创建的虚拟环境（可选）  ├── pdf/  │   ├── SKILL.md  │   └── .disabled          # 禁用标记文件  └── web-access/      └─ SKILL.md  

1
2
3
def toggle_skill(cls, skill_name, enabled, scope="common"):      disabled_file = skill_dir / ".disabled"    if enabled:        disabled_file.unlink()       # 删除标记 = 启用      else:        disabled_file.touch()        # 创建标记 = 禁用  

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---  name: query-writing  description: >    SQL 查询编写技能，支持复杂 JOIN、子查询、窗口函数等高级 SQL 生成  ---  ## 技能说明  本技能用于辅助大模型生成高质量 SQL 查询...  ## 使用场景  - 多表关联查询  - 聚合分析  - ...  

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
TUTORIAL_PROMPT = """你是一个技能使用指南专家。请仔细阅读以下技能文档，然后以中文输出详细的使用教程。  ## 技能文档  {skill_content}  ## 输出要求  # {skill_name} 使用教程  ## 技能简介  ## 何时使用  ## 使用步骤  ## 场景示例（2-3个）  ## 注意事项  """  async def stream_fn(response):      llm = get_llm(temperature=0.7)    prompt = TUTORIAL_PROMPT.format(skill_name=name, skill_content=skill_content)      async for chunk in llm.astream(prompt):        content = chunk.content if hasattr(chunk, "content") else str(chunk)
if content:            data = json.dumps({"content": content})            await response.write(f"data: {data}\n\n")      await response.write(f"data: {json.dumps({'done': True})}\n\n")  return ResponseStream(stream_fn, content_type="text/event-stream")  

1
2
3
4
5
const transformStream = new TransformStream({    transform(chunk, controller) {    buffer += decoder.decode(chunk, { stream: true })    const lines = buffer.split('\n')    buffer = lines.pop() || ''    for (const line of lines) {      if (line.startsWith('data: ')) {        const data = JSON.parse(line.slice(6))        if (data.content) {          const formatted = JSON.stringify({            messageType: 'continue',            content: data.content          })          controller.enqueue(new TextEncoder().encode(formatted + '\n'))        }      }    }  }})  const reader = res.body?.pipeThrough(transformStream).getReader()  

1
2
3
// useSlashCommand.ts - 懒加载技能列表  async function ensureSkillsLoaded() {    if (skillsLoaded) return  const res = await fetch_skill_list('common')  const data = await res.json()  if (data?.code === 200 && Array.isArray(data?.data)) {    allSkills.value = data.data.filter((s: SkillInfo) => s.enabled)  }  skillsLoaded = true}  

发现技能            安装技能           管理技能           使用技能│                  │                 │                 │▼                  ▼                 ▼                 ▼GitHub 仓库 ──→ 预览并选择 ──→ 一键安装 ──→ 列表管理Zip 包上传 ──→ 自动解析   ──→ 依赖安装 ──→ 启用/禁用──→ 查看详情──→ AI 使用教程──→ 聊天框 / 调用──→ 批量卸载──→ 技能市场（规划中）──→ 安全检测（规划中）──→ 自动测评（规划中）──→ 版本管理（规划中）──→ 批量卸载