FEAT: 添加skills_hub 模块

Author: leeyyi

docs/mkdocs/en/skill.md

@@ -2143,6 +2143,62 @@ The **Dynamic Tool Selection** mechanism has been fully implemented and verified
 - ❌ All tools need to be available simultaneously
 - ❌ Token cost is not a primary concern
 
+## Skill Hub — Discovering & Fetching Skills from Remote Sources
+
+Everything above assumes a skill already exists on disk under a directory served by `BaseSkillRepository`. **Skill Hub** (`trpc_agent_sdk.skills.hub`) is a separate, standalone layer that answers a different question: *where do skills come from before they're on disk?* It gives you a uniform way to search, inspect, and download skills from public registries, so you (or a harness built on top of the SDK) can install them into a directory that `create_default_skill_repository` then serves as usual.
+
+### The `SkillSource` contract
+
+Every adapter implements the same four-method interface:
+
+```python
+from trpc_agent_sdk.skills.hub import SkillSource, SkillMeta, SkillBundle
+
+class SkillSource(ABC):
+    def source_id(self) -> str: ...
+    def search(self, query: str, limit: int = 10) -> list[SkillMeta]: ...
+    def inspect(self, identifier: str) -> SkillMeta | None: ...
+    def fetch(self, identifier: str) -> SkillBundle | None: ...
+```
+
+- `SkillMeta` — lightweight search/inspect result (`name`, `description`, `source`, `identifier`, optional `repo`/`path`/`tags`/`extra`).
+- `SkillBundle` — the downloaded skill (`name`, `files: dict[str, str | bytes]`, `source`, `identifier`, `metadata`).
+
+**Important:** `fetch()` only returns a `SkillBundle` in memory. Writing it to disk (including overwrite policy, atomic staging, and concurrency safety) is intentionally left to the caller, since different harnesses need different install semantics. The SDK also exports three path validators for that purpose:
+
+```python
+from trpc_agent_sdk.skills.hub import validate_skill_name, validate_category_name, validate_bundle_rel_path
+```
+
+Use them to reject unsafe paths (absolute paths, `..` traversal, Windows drive prefixes) before writing any hub-returned file to disk. See [examples/skills_hub/agent/hub.py](../../../examples/skills_hub/agent/hub.py) for a minimal reference implementation.
+
+### Built-in adapters
+
+| Adapter | Source | Identifier format |
+| --- | --- | --- |
+| `GitHubSource` | GitHub repos, via the Contents / Git Trees API | `"owner/repo/path/to/skill-dir"` |
+| `WellKnownSkillSource` | Any domain exposing `/.well-known/skills/index.json` | `well-known:{base_url}/{skill_name}` or a raw HTTPS URL |
+| `HermesIndexSource` | A centralized, pre-crawled skills catalog | Same identifiers as the underlying `GitHubSource` entries |
+| `SkillsShSource` | [skills.sh](https://skills.sh) | `skills-sh/{owner}/{repo}/{skill_path}` |
+| `ClawHubSource` | [ClawHub](https://clawhub.ai) | slug, e.g. `"notion"` |
+| `ClaudeMarketplaceSource` | Claude Code marketplace repos (`.claude-plugin/marketplace.json`) | Resolves to a `GitHubSource` identifier |
+| `LobeHubSource` | LobeHub agent marketplace (converted to synthetic `SKILL.md`) | `lobehub/{agent_id}` |
+
+`GitHubAuth` provides GitHub API authentication via an explicitly injected personal access token (60 req/hr unauthenticated, 5,000 req/hr with a token). No token auto-detection from the environment or a local `gh` CLI is performed, since the SDK may run multi-tenant.
+
+### Minimal usage
+
+```python
+from trpc_agent_sdk.skills.hub import GitHubAuth, GitHubSource
+
+source = GitHubSource(GitHubAuth())  # unauthenticated is fine for public repos
+meta = source.inspect("anthropics/skills/skills/skill-creator")
+bundle = source.fetch("anthropics/skills/skills/skill-creator")
+# bundle.files: {"SKILL.md": "...", "scripts/...": "...", ...}
+```
+
+Combine `fetch()` with your own install helper and `create_default_skill_repository` to make a hub-fetched skill available to an agent exactly like a bundled one — see [examples/skills_hub](../../../examples/skills_hub/README.md) for the full pipeline (fetch → validate paths → write to disk → `create_default_skill_repository` → `SkillToolSet`).
+
 ## References and Examples
 
 - Background:
@@ -2152,6 +2208,7 @@ The **Dynamic Tool Selection** mechanism has been fully implemented and verified
 - This repository:
   - Interactive demo: [examples/skills/run_agent.py](../../../examples/skills/run_agent.py)
   - Dynamic tool selection full example: [examples/skills_with_dynamic_tools/run_agent.py](../../../examples/skills_with_dynamic_tools/run_agent.py)
+  - Skill Hub full example (fetch from GitHub, then run): [examples/skills_hub/run_agent.py](../../../examples/skills_hub/run_agent.py)
   - Example structure guide: [examples/skills/README.md](../../../examples/skills/README.md)
   - Example skills:
     - [examples/skills/skills/python-math/SKILL.md](../../../examples/skills/skills/python-math/SKILL.md)

docs/mkdocs/zh/skill.md

@@ -2141,6 +2141,58 @@ Tools:
 - ❌ 所有工具都需要同时可用
 - ❌ Token 成本不是主要考虑因素
 
+## Skill Hub —— 从远程来源发现并获取 Skill
+
+**Skill Hub**（`trpc_agent_sdk.skills.hub`）是一组用于从远程来源发现和获取 skill 的适配器（`SkillSource`）。它能做三件事：搜索某个来源（GitHub、ClawHub、skills.sh 等）上有哪些 skill、查看某个 skill 的元信息、下载它的完整文件内容。用户也可以实现SkillSource 接口来对接自己的skill source. 
+
+### `SkillSource` 契约
+
+每个适配器都实现同样的四方法接口：
+
+```python
+from trpc_agent_sdk.skills.hub import SkillSource, SkillMeta, SkillBundle
+
+class SkillSource(ABC):
+    def source_id(self) -> str: ...
+    def search(self, query: str, limit: int = 10) -> list[SkillMeta]: ...
+    def inspect(self, identifier: str) -> SkillMeta | None: ...
+    def fetch(self, identifier: str) -> SkillBundle | None: ...
+```
+
+- `SkillMeta` —— 轻量的 search/inspect 结果（`name`、`description`、`source`、`identifier`，以及可选的 `repo`/`path`/`tags`/`extra`）
+- `SkillBundle` —— 下载到的 skill（`name`、`files: dict[str, str | bytes]`、`source`、`identifier`、`metadata`）
+
+`fetch()` 只会返回内存中的 `SkillBundle`。把它写到磁盘（包括覆盖策略、原子写入、并发安全）是**调用方**自己的职责，因为不同 harness 对安装语义的要求各不相同。为此 SDK 也导出了三个路径校验函数：
+
+```python
+from trpc_agent_sdk.skills.hub import validate_skill_name, validate_category_name, validate_bundle_rel_path
+```
+
+在把 hub 返回的文件写到磁盘之前，用它们拒绝不安全的路径（绝对路径、`..` 路径穿越、Windows 盘符前缀）。最小化的参考实现见 [examples/skills_hub/agent/hub.py](../../../examples/skills_hub/agent/hub.py)。
+
+### 内置适配器
+
+| 适配器 | 来源 | 标识符格式 |
+| --- | --- | --- |
+| `GitHubSource` | GitHub 仓库，通过 Contents / Git Trees API | `"owner/repo/path/to/skill-dir"` |
+| `WellKnownSkillSource` | 任何暴露 `/.well-known/skills/index.json` 的站点 | `well-known:{base_url}/{skill_name}` 或原始 HTTPS URL |
+| `HermesIndexSource` | 集中式、预先爬取好的 skill 目录索引 | 与底层 `GitHubSource` 条目相同的标识符 |
+| `SkillsShSource` | [skills.sh](https://skills.sh) | `skills-sh/{owner}/{repo}/{skill_path}` |
+| `ClawHubSource` | [ClawHub](https://clawhub.ai) | slug，例如 `"notion"` |
+| `ClaudeMarketplaceSource` | Claude Code marketplace 仓库（`.claude-plugin/marketplace.json`） | 解析为 `GitHubSource` 标识符 |
+| `LobeHubSource` | LobeHub agent marketplace（转换为合成的 `SKILL.md`） | `lobehub/{agent_id}` |
+
+### 最小用法
+
+```python
+from trpc_agent_sdk.skills.hub import GitHubAuth, GitHubSource
+
+source = GitHubSource(GitHubAuth())  # 拉取公开仓库无需认证
+meta = source.inspect("anthropics/skills/skills/skill-creator")
+bundle = source.fetch("anthropics/skills/skills/skill-creator")
+# bundle.files: {"SKILL.md": "...", "scripts/...": "...", ...}
+```
+
 ## 参考和示例
 
 - 背景：
@@ -2150,6 +2202,7 @@ Tools:
 - 本仓库：
   - 交互式演示：[examples/skills/run_agent.py](../../../examples/skills/run_agent.py)
   - 动态工具选择完整示例：[examples/skills_with_dynamic_tools/run_agent.py](../../../examples/skills_with_dynamic_tools/run_agent.py)
+  - Skill Hub 完整示例（从 GitHub 拉取后运行）：[examples/skills_hub/run_agent.py](../../../examples/skills_hub/run_agent.py)
   - 示例结构说明：[examples/skills/README.md](../../../examples/skills/README.md)
   - 示例技能：
     - [examples/skills/skills/python-math/SKILL.md](../../../examples/skills/skills/python-math/SKILL.md)

examples/skills_hub/.env

@@ -0,0 +1,8 @@
+# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME
+TRPC_AGENT_API_KEY=your-api-key
+TRPC_AGENT_BASE_URL=your-base-url
+TRPC_AGENT_MODEL_NAME=your-model-name
+
+# Optional: a GitHub personal access token (raises the unauthenticated
+# 60 req/hr GitHub API limit to 5,000/hr). Not required to run this demo.
+# GITHUB_TOKEN=

examples/skills_hub/.gitignore

@@ -0,0 +1 @@
+data

examples/skills_hub/README.md

@@ -0,0 +1,52 @@
+# Skill Hub 示例
+
+本示例演示 `trpc_agent_sdk.skills.hub`（Skill Hub）：在启动 `LlmAgent` 之前，通过 `GitHubSource` 从 GitHub 上按需拉取一个技能（Anthropic 官方的 `skill-creator`），写入本地技能目录，再像本地技能一样交给 `SkillToolSet` 使用。
+
+## 什么是 Skill Hub
+
+Skill Hub（`trpc_agent_sdk.skills.hub`）把"从各种来源发现并获取 skill"统一到同一个接口后面。每个来源都是一个 `SkillSource` 适配器，对外提供一致的 `search` / `inspect` / `fetch` 三种能力：
+
+| 适配器 | 来源 |
+| --- | --- |
+| `GitHubSource` | GitHub 仓库目录（本示例使用） |
+| `WellKnownSkillSource` | 站点 `.well-known/skills` |
+| `HermesIndexSource` | Hermes 内置 skill index |
+| `SkillsShSource` | skills.sh |
+| `ClawHubSource` | ClawHub registry |
+| `ClaudeMarketplaceSource` | Claude Skills Marketplace |
+| `LobeHubSource` | LobeHub |
+
+`SkillSource.fetch()`只返回内存中的 `SkillBundle`（`name` + `files` + `metadata`），**把它写到磁盘、决定是否覆盖已有版本，都是调用方自己的策略**——SDK 本身不内置"安装"逻辑，因为不同 harness（本示例、trpc-hermes 的 `SkillSpec`/`preinstall_skills_to_dir`，或你自己的服务）对覆盖策略、原子写入、并发安全的要求都不一样。本示例里最小化的这部分逻辑在 `agent/hub.py` 的 `install_skill_from_github()`。
+
+## 关键特性
+
+- `GitHubSource(GitHubAuth(token))` 无需认证即可拉取公开仓库（60 次/小时限额，足够本示例使用；设置 `GITHUB_TOKEN` 可提升到 5000 次/小时）
+- 用 SDK 导出的 `validate_skill_name` / `validate_bundle_rel_path` 校验 hub 返回的路径，避免恶意 `SkillBundle` 写出到目标目录之外
+- 已安装的技能会被跳过，重复运行示例不会重复下载
+- 拉取完成后，技能通过标准的 `create_default_skill_repository` + `SkillToolSet` 链路对 agent 可见，和本地技能没有区别
+
+## Agent 层级结构说明
+
+- 根节点：`LlmAgent`（`skill_hub_demo_agent`），挂载 `SkillToolSet` 与 `skill_repository`
+- 无子 Agent；单智能体通过 `skill_load` / `skill_list_docs` 等技能工具完成任务
+
+## 关键代码解释
+
+- `agent/hub.py`：
+  - `install_skill_from_github()`：若目标目录已存在则跳过；否则用 `GitHubSource.fetch(identifier)` 拉取 `SkillBundle`，校验并写出每个文件
+  - `create_skill_tool_set()`：用安装好的目录构造 `create_default_skill_repository` + `SkillToolSet`
+- `agent/agent.py`：`create_agent(skills_dir)` 先调用 `install_skill_from_github`，再把返回的 `skill_repository` / `skill_tool_set` 绑定到 `LlmAgent`
+- `run_agent.py`：清空 `data/` 目录（保证每次都重新走一遍 Skill Hub 拉取流程），创建 agent，跑一轮 `skill_load` + 总结的对话，并打印实际下载到的文件列表
+
+## 环境与运行
+
+- Python 3.10+；仓库根目录执行 `pip install -e .`
+- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（可用 `.env`）
+- 可选：`GITHUB_TOKEN`，用于提高 GitHub API 限额（本示例只读取公开仓库，不设置也能跑）
+
+```bash
+cd examples/skills_hub
+python3 run_agent.py
+```
+
+运行后会在 `data/skills/skill-creator/` 下看到从 GitHub 拉取的真实文件（`SKILL.md`、`scripts/`、`references/` 等）。

examples/skills_hub/agent/__init__.py

@@ -0,0 +1,5 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.

examples/skills_hub/agent/agent.py

@@ -0,0 +1,50 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent that demonstrates fetching a skill from the Skill Hub before running. """
+
+from pathlib import Path
+
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel
+from trpc_agent_sdk.models import OpenAIModel
+
+from .config import get_model_config
+from .hub import GITHUB_SKILL_IDENTIFIER
+from .hub import GITHUB_SKILL_NAME
+from .hub import create_skill_tool_set
+from .hub import install_skill_from_github
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """ Create a model"""
+    api_key, url, model_name = get_model_config()
+    model = OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+    return model
+
+
+def create_agent(skills_dir: Path) -> LlmAgent:
+    """Fetch a skill from GitHub via the Skill Hub, then build an agent that can use it.
+
+    Args:
+        skills_dir: Local directory to install fetched skills into. Populated
+            with `skills_dir/skill-creator/` before the agent is constructed.
+    """
+    install_skill_from_github(
+        skills_dir=skills_dir,
+        skill_name=GITHUB_SKILL_NAME,
+        identifier=GITHUB_SKILL_IDENTIFIER,
+    )
+    skill_tool_set, skill_repository = create_skill_tool_set(skills_dir)
+
+    return LlmAgent(
+        name="skill_hub_demo_agent",
+        description="An assistant that fetches skills on demand from the Skill Hub.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[skill_tool_set],
+        skill_repository=skill_repository,
+    )

examples/skills_hub/agent/config.py

@@ -0,0 +1,19 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent config module"""
+
+import os
+
+
+def get_model_config() -> tuple[str, str, str]:
+    """Get model config from environment variables"""
+    api_key = os.getenv('TRPC_AGENT_API_KEY', '')
+    url = os.getenv('TRPC_AGENT_BASE_URL', '')
+    model_name = os.getenv('TRPC_AGENT_MODEL_NAME', '')
+    if not api_key or not url or not model_name:
+        raise ValueError('''TRPC_AGENT_API_KEY, TRPC_AGENT_BASE_URL,
+                         and TRPC_AGENT_MODEL_NAME must be set in environment variables''')
+    return api_key, url, model_name

examples/skills_hub/agent/hub.py

@@ -0,0 +1,75 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Skill Hub glue: fetch a skill from GitHub and install it into a local
+skills directory before the agent starts.
+
+`trpc_agent_sdk.skills.hub.SkillSource.fetch()` only returns a `SkillBundle`
+in memory -- writing it to disk (and deciding on overwrite/skip semantics) is
+intentionally left to the caller, since that policy is harness-specific. This
+module shows the minimal version of that glue; a real harness (e.g.
+trpc-hermes's `SkillSpec` + `preinstall_skills_to_dir`) typically adds atomic
+staging and richer error handling on top of the same `SkillSource` adapters.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from trpc_agent_sdk.code_executors import create_local_workspace_runtime
+from trpc_agent_sdk.skills import BaseSkillRepository
+from trpc_agent_sdk.skills import SkillToolSet
+from trpc_agent_sdk.skills import create_default_skill_repository
+from trpc_agent_sdk.skills.hub import GitHubAuth
+from trpc_agent_sdk.skills.hub import GitHubSource
+from trpc_agent_sdk.skills.hub import validate_bundle_rel_path
+from trpc_agent_sdk.skills.hub import validate_skill_name
+
+# `skill-creator` is Anthropic's own skill for building and iterating on
+# skills -- a fitting "meta" skill to fetch through the Skill Hub for a demo.
+GITHUB_SKILL_IDENTIFIER = "anthropics/skills/skills/skill-creator"
+GITHUB_SKILL_NAME = "skill-creator"
+
+
+def install_skill_from_github(*, skills_dir: Path, skill_name: str, identifier: str) -> None:
+    """Fetch `identifier` via `GitHubSource` and write it into `skills_dir/skill_name/`.
+
+    Skips the fetch entirely if the skill directory already exists, so
+    re-running the demo doesn't re-download the skill every time.
+    """
+    safe_name = validate_skill_name(skill_name)
+    target_dir = skills_dir / safe_name
+    if target_dir.exists():
+        return
+
+    # Unauthenticated requests are capped at 60 req/hr, which is plenty for
+    # this demo. Set GITHUB_TOKEN to raise that limit for repeated runs.
+    source = GitHubSource(GitHubAuth(os.getenv("GITHUB_TOKEN") or None))
+    bundle = source.fetch(identifier)
+    if bundle is None:
+        raise RuntimeError(
+            f"Could not fetch skill {identifier!r} from GitHub via the Skill Hub "
+            "(hit the rate limit? set GITHUB_TOKEN in .env)."
+        )
+
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    target_dir.mkdir(parents=True)
+    for rel_path, content in bundle.files.items():
+        safe_rel_path = validate_bundle_rel_path(rel_path)
+        dest = target_dir / safe_rel_path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(content, bytes):
+            dest.write_bytes(content)
+        else:
+            dest.write_text(content, encoding="utf-8")
+
+
+def create_skill_tool_set(skills_dir: Path) -> tuple[SkillToolSet, BaseSkillRepository]:
+    """Build a `SkillToolSet` backed by whatever has been installed into `skills_dir`."""
+    workspace_runtime = create_local_workspace_runtime()
+    repository = create_default_skill_repository(str(skills_dir), workspace_runtime=workspace_runtime)
+    skill_toolset = SkillToolSet(repository=repository)
+    return skill_toolset, repository

examples/skills_hub/agent/prompts.py

@@ -0,0 +1,19 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" prompts for agent"""
+
+INSTRUCTION = """
+Be a concise, helpful assistant that can use Agent Skills.
+
+A skill named "skill-creator" was just fetched on demand from GitHub via the
+Skill Hub (`trpc_agent_sdk.skills.hub`) and installed locally before you were
+started, so it is available like any other local skill.
+
+When asked about a skill, call skill_load to load its documentation, then
+skill_list_docs to see what documentation and files are available. Summarize
+what you find concisely; do not run any of the skill's scripts unless
+explicitly asked to.
+"""