funchub-sdk 0.1.0__py3-none-any.whl

funchub/__init__.py

@@ -0,0 +1,3 @@
+from funchub.client import FuncHub
+
+__all__ = ["FuncHub"]

funchub/cli.py

@@ -0,0 +1,204 @@
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+import yaml
+
+from funchub.client import FuncHub
+from funchub.exceptions import ConflictError, FuncHubError, ToolNotFoundError, VersionNotFoundError
+from funchub.github_client import load_config, save_config
+from funchub.models import ToolDefinition, ToolVersion
+
+
+@click.group()
+@click.option("--registry", "-r", envvar="FUNCHUB_REGISTRY", help="中央索引 URL")
+@click.option("--token", envvar="GITHUB_TOKEN", help="GitHub PAT")
+@click.pass_context
+def cli(ctx: click.Context, registry: Optional[str], token: Optional[str]) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["hub"] = FuncHub(registry=registry, token=token)
+
+
+@cli.command()
+@click.option("--token", required=True, help="GitHub Personal Access Token")
+def login(token: str) -> None:
+    cfg = load_config()
+    cfg["github_token"] = token
+    save_config(cfg)
+    click.echo("GitHub Token 已保存到 ~/.funchub/config.yaml")
+
+
+@cli.command()
+@click.argument("key")
+@click.argument("value")
+def config(key: str, value: str) -> None:
+    cfg = load_config()
+    cfg[key] = value
+    save_config(cfg)
+    click.echo(f"配置项 {key} 已设置为 {value}")
+
+
+@cli.command()
+@click.option("--version", "ver", required=True, help="发布的版本号")
+@click.option("--force", is_flag=True, help="覆盖同名工具")
+@click.option("--dry-run", is_flag=True, help="预览不实际提交")
+@click.pass_context
+def publish(ctx: click.Context, ver: str, force: bool, dry_run: bool) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    tool_file = Path("funchub-tool.yaml")
+    if not tool_file.exists():
+        click.echo("错误: 当前目录未找到 funchub-tool.yaml", err=True)
+        sys.exit(1)
+    raw = tool_file.read_text(encoding="utf-8")
+    data = yaml.safe_load(raw)
+    is_prerelease = any(tag in ver.lower() for tag in ("alpha", "beta", "rc", "pre"))
+    tv = ToolVersion(
+        version=ver,
+        source_repo=data.get("source_repo", ""),
+        source_ref=data.get("source_ref", f"v{ver}"),
+        dependencies=data.get("dependencies", []),
+        is_prerelease=is_prerelease,
+    )
+    tool_def = ToolDefinition(
+        name=data["name"],
+        description=data.get("description", ""),
+        parameters=data.get("parameters", {"type": "object", "properties": {}}),
+        author=data.get("author", "anonymous"),
+        entry_point=data.get("entry_point", "index:main"),
+        versions=[tv],
+    )
+    try:
+        result = hub.publish(tool_def, force=force, dry_run=dry_run)
+        if dry_run:
+            click.echo(f"[DRY RUN] {result}")
+        else:
+            click.echo(f"发布成功: {result}")
+    except ConflictError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("query")
+@click.pass_context
+def search(ctx: click.Context, query: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    results = hub.search(query)
+    if not results:
+        click.echo("未找到匹配的工具")
+        return
+    for t in results:
+        click.echo(f"{t.name} - {t.description}")
+
+
+@cli.command()
+@click.argument("tool_spec")
+@click.option("--prerelease", is_flag=True, help="包含预发布版本")
+@click.option("--yes", is_flag=True, help="跳过安全确认")
+@click.pass_context
+def install(ctx: click.Context, tool_spec: str, prerelease: bool, yes: bool) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    constraint: Optional[str] = None
+    tool_name = tool_spec
+    if "@" in tool_spec:
+        tool_name, constraint = tool_spec.split("@", 1)
+    try:
+        hub.install(
+            tool_name,
+            constraint=constraint,
+            include_prerelease=prerelease,
+            yes=yes,
+        )
+        click.echo(f"✅ 工具 {tool_name} 安装成功")
+    except (ToolNotFoundError, VersionNotFoundError) as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command("list")
+@click.pass_context
+def list_tools(ctx: click.Context) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    items = hub.list_installed()
+    if not items:
+        click.echo("未安装任何工具")
+        return
+    for item in items:
+        click.echo(f"{item['name']}@{item['version']} ({item['source_repo']})")
+
+
+@cli.command()
+@click.argument("name", required=False)
+@click.option("--all", "update_all", is_flag=True, help="更新所有工具")
+@click.option("--prerelease", is_flag=True, help="包含预发布版本")
+@click.option("--yes", is_flag=True, help="跳过安全确认")
+@click.pass_context
+def update(
+    ctx: click.Context,
+    name: Optional[str],
+    update_all: bool,
+    prerelease: bool,
+    yes: bool,
+) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    if update_all:
+        results = hub.update_all(include_prerelease=prerelease, yes=yes)
+        if not results:
+            click.echo("所有工具已是最新")
+        for r in results:
+            click.echo(r)
+        return
+    if not name:
+        click.echo("请指定工具名称或使用 --all", err=True)
+        sys.exit(1)
+    try:
+        result = hub.update(name, include_prerelease=prerelease, yes=yes)
+        click.echo(f"✅ 工具 {name} 已更新到 {result}")
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("name")
+@click.pass_context
+def info(ctx: click.Context, name: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    tool_def = hub.info(name)
+    if tool_def is None:
+        click.echo(f"工具 '{name}' 未找到")
+        return
+    click.echo(f"名称: {tool_def.name}")
+    click.echo(f"描述: {tool_def.description}")
+    click.echo(f"作者: {tool_def.author}")
+    click.echo(f"入口: {tool_def.entry_point}")
+    click.echo("版本:")
+    for v in tool_def.versions:
+        pre = " (预发布)" if v.is_prerelease else ""
+        click.echo(f"  - {v.version}{pre}")
+
+
+@cli.command()
+@click.argument("name")
+@click.pass_context
+def uninstall(ctx: click.Context, name: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    if hub.uninstall(name):
+        click.echo(f"✅ 工具 {name} 已卸载")
+    else:
+        click.echo(f"工具 {name} 未安装")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

funchub/client.py

@@ -0,0 +1,224 @@
+import json
+import shutil
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from funchub.exceptions import (
+    FuncHubError,
+    ToolNotFoundError,
+    VersionNotFoundError,
+)
+from funchub.github_client import (
+    GitHubRegistryClient,
+    load_config,
+    resolve_registry,
+    resolve_token,
+    retry_request,
+)
+from funchub.loader import Loader
+from funchub.models import ToolDefinition, ToolVersion
+from funchub.version_parser import resolve_version
+
+
+class FuncHub:
+    def __init__(
+        self,
+        registry: Optional[str] = None,
+        token: Optional[str] = None,
+    ) -> None:
+        self._registry_url = resolve_registry(registry)
+        self._token = resolve_token(token)
+        self._cache_base = Path.home() / ".funchub" / "cache"
+        self._registry_cache_path = Path.home() / ".funchub" / "registry_cache.json"
+        self._funcs: Dict[str, Callable] = {}
+
+    def _fetch_registry(
+        self, use_cache: bool = True
+    ) -> Dict[str, ToolDefinition]:
+        now = time.time()
+        if use_cache and self._registry_cache_path.exists():
+            raw = self._registry_cache_path.read_text(encoding="utf-8")
+            try:
+                cached = json.loads(raw)
+                cache_time = cached.get("_cached_at", 0)
+                if now - cache_time < 300:
+                    tools_raw = cached.get("tools", {})
+                    return {
+                        k: ToolDefinition(**v)
+                        for k, v in tools_raw.items()
+                    }
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        resp = retry_request("GET", self._registry_url)
+        resp.raise_for_status()
+        data = resp.json()
+
+        tools_raw: Dict[str, Any] = {}
+        if "tools" in data:
+            tools_raw = data["tools"]
+        else:
+            tools_raw = data
+
+        tools: Dict[str, ToolDefinition] = {}
+        for k, v in tools_raw.items():
+            if isinstance(v, dict):
+                tools[k] = ToolDefinition(**v)
+
+        cache_data = {
+            "_cached_at": now,
+            "tools": {k: v.model_dump() for k, v in tools.items()},
+        }
+        self._registry_cache_path.parent.mkdir(parents=True, exist_ok=True)
+        self._registry_cache_path.write_text(
+            json.dumps(cache_data, indent=2), encoding="utf-8"
+        )
+
+        return tools
+
+    def search(self, query: str) -> List[ToolDefinition]:
+        registry = self._fetch_registry()
+        q = query.lower()
+        results = []
+        for tool_def in registry.values():
+            if q in tool_def.name.lower() or q in tool_def.description.lower():
+                results.append(tool_def)
+        return results
+
+    def get_tool(self, name: str) -> Optional[ToolDefinition]:
+        registry = self._fetch_registry()
+        return registry.get(name)
+
+    def install(
+        self,
+        tool_name: str,
+        constraint: Optional[str] = None,
+        include_prerelease: bool = False,
+        yes: bool = False,
+    ) -> Callable:
+        if "@" in tool_name and constraint is None:
+            parts = tool_name.split("@", 1)
+            tool_name = parts[0]
+            constraint = parts[1]
+        registry = self._fetch_registry()
+        tool_def = registry.get(tool_name)
+        if tool_def is None:
+            raise ToolNotFoundError(tool_name)
+
+        available = [v.version for v in tool_def.versions]
+        target_version = resolve_version(
+            available, constraint or "latest", include_prerelease=include_prerelease
+        )
+        if target_version is None:
+            raise VersionNotFoundError(constraint or "latest")
+
+        cache_dir = self._cache_base / tool_name
+        version_file = cache_dir / ".version"
+
+        if version_file.exists():
+            cached_version = version_file.read_text(encoding="utf-8").strip()
+            if cached_version == target_version:
+                func = self._funcs.get(tool_name)
+                if func is not None:
+                    return func
+
+        func = Loader.load_function(
+            tool_def, target_version, self._cache_base, yes=yes
+        )
+        self._funcs[tool_name] = func
+        return func
+
+    def publish(
+        self,
+        tool_def: ToolDefinition,
+        force: bool = False,
+        dry_run: bool = False,
+    ) -> str:
+        if self._token is None:
+            raise FuncHubError(
+                "请先运行 funchub login 配置 GitHub Token"
+            )
+        client = GitHubRegistryClient(self._token)
+        return client.publish_tool(tool_def, force=force, dry_run=dry_run)
+
+    def list_installed(self) -> List[Dict[str, str]]:
+        if not self._cache_base.exists():
+            return []
+        result = []
+        for child in self._cache_base.iterdir():
+            if child.is_dir():
+                version_file = child / ".version"
+                source_file = child / ".source_repo"
+                version = ""
+                source = ""
+                if version_file.exists():
+                    version = version_file.read_text(encoding="utf-8").strip()
+                if source_file.exists():
+                    source = source_file.read_text(encoding="utf-8").strip()
+                result.append({
+                    "name": child.name,
+                    "version": version,
+                    "source_repo": source,
+                })
+        return result
+
+    def update(
+        self,
+        tool_name: str,
+        include_prerelease: bool = False,
+        yes: bool = False,
+    ) -> Optional[str]:
+        registry = self._fetch_registry()
+        tool_def = registry.get(tool_name)
+        if tool_def is None:
+            raise ToolNotFoundError(tool_name)
+
+        available = [v.version for v in tool_def.versions]
+        latest = resolve_version(
+            available, "latest", include_prerelease=include_prerelease
+        )
+        if latest is None:
+            raise VersionNotFoundError("latest")
+
+        cache_dir = self._cache_base / tool_name
+        version_file = cache_dir / ".version"
+
+        if version_file.exists():
+            current = version_file.read_text(encoding="utf-8").strip()
+            if current == latest:
+                return current
+
+        self.install(tool_name, constraint=latest, include_prerelease=include_prerelease, yes=yes)
+        return latest
+
+    def update_all(
+        self,
+        include_prerelease: bool = False,
+        yes: bool = False,
+    ) -> List[str]:
+        updated = []
+        installed = self.list_installed()
+        for item in installed:
+            try:
+                new_ver = self.update(
+                    item["name"],
+                    include_prerelease=include_prerelease,
+                    yes=yes,
+                )
+                if new_ver and new_ver != item["version"]:
+                    updated.append(f"{item['name']}: {item['version']} -> {new_ver}")
+            except FuncHubError:
+                pass
+        return updated
+
+    def info(self, tool_name: str) -> Optional[ToolDefinition]:
+        return self.get_tool(tool_name)
+
+    def uninstall(self, tool_name: str) -> bool:
+        cache_dir = self._cache_base / tool_name
+        if cache_dir.exists():
+            shutil.rmtree(str(cache_dir))
+            self._funcs.pop(tool_name, None)
+            return True
+        return False

funchub/decorators.py

@@ -0,0 +1,84 @@
+import inspect
+from typing import Any, Callable, Dict, List, Optional, Type, get_type_hints
+
+from funchub.models import ToolDefinition, ToolVersion
+
+_TYPE_MAP: Dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+    type(None): "null",
+}
+
+
+def _py_type_to_json_type(py_type: Type) -> str:
+    return _TYPE_MAP.get(py_type, "string")
+
+
+def _infer_parameters(func: Callable) -> Dict[str, Any]:
+    sig = inspect.signature(func)
+    hints = get_type_hints(func)
+    properties: Dict[str, Dict[str, Any]] = {}
+    required: List[str] = []
+
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+        param_type = hints.get(name, str)
+        json_type = _py_type_to_json_type(param_type)
+        prop: Dict[str, Any] = {"type": json_type}
+
+        if param.default is not inspect.Parameter.empty:
+            prop["default"] = param.default
+            default_str = str(param.default)
+            if json_type == "string":
+                prop["description"] = f"Default: {default_str}"
+        else:
+            required.append(name)
+
+        properties[name] = prop
+
+    schema: Dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def tool(
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    author: str = "anonymous",
+    version: str = "1.0.0",
+    source_repo: str = "",
+    source_ref: str = "",
+    dependencies: Optional[List[str]] = None,
+):
+    def decorator(func: Callable) -> Callable:
+        tool_name = name or func.__name__
+        tool_desc = description or (func.__doc__ or "").strip() or tool_name
+        parameters = _infer_parameters(func)
+        tool_version = ToolVersion(
+            version=version,
+            source_repo=source_repo,
+            source_ref=source_ref,
+            dependencies=dependencies or [],
+            is_prerelease="alpha" in version or "beta" in version or "rc" in version,
+        )
+        tool_def = ToolDefinition(
+            name=tool_name,
+            description=tool_desc,
+            parameters=parameters,
+            author=author,
+            entry_point=f"{func.__module__}:{func.__name__}",
+            versions=[tool_version],
+        )
+        func.__funchub_tool__ = tool_def
+        return func
+
+    return decorator

funchub/exceptions.py

@@ -0,0 +1,42 @@
+class FuncHubError(Exception):
+    pass
+
+
+class ToolNotFoundError(FuncHubError):
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(f"工具 '{tool_name}' 未在中央索引中找到")
+        self.tool_name = tool_name
+
+
+class VersionNotFoundError(FuncHubError):
+    def __init__(self, constraint: str) -> None:
+        super().__init__(f"未找到满足约束 '{constraint}' 的版本")
+        self.constraint = constraint
+
+
+class ConflictError(FuncHubError):
+    def __init__(self, tool_name: str, author: str) -> None:
+        super().__init__(f"工具 {tool_name} 已被 {author} 占用，使用 --force 覆盖")
+        self.tool_name = tool_name
+        self.author = author
+
+
+class RegistryError(FuncHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"注册表错误: {message}")
+
+
+class NetworkError(FuncHubError):
+    def __init__(self, message: str, attempts: int = 3) -> None:
+        super().__init__(f"网络请求失败 (已重试 {attempts} 次): {message}")
+        self.attempts = attempts
+
+
+class ConfigError(FuncHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"配置错误: {message}")
+
+
+class LoadError(FuncHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"加载失败: {message}")

funchub/github_client.py

@@ -0,0 +1,244 @@
+import base64
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import requests
+import yaml
+
+from funchub.exceptions import ConfigError, ConflictError, FuncHubError, NetworkError
+from funchub.models import ToolDefinition
+
+
+def get_config_dir() -> Path:
+    return Path.home() / ".funchub"
+
+
+def get_config_path() -> Path:
+    return get_config_dir() / "config.yaml"
+
+
+def load_config() -> Dict[str, Any]:
+    config_path = get_config_path()
+    if config_path.exists():
+        raw = config_path.read_text(encoding="utf-8")
+        return yaml.safe_load(raw) or {}
+    return {}
+
+
+def save_config(cfg: Dict[str, Any]) -> None:
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path = get_config_path()
+    config_path.write_text(yaml.dump(cfg), encoding="utf-8")
+
+
+def resolve_registry(cli_registry: Optional[str] = None) -> str:
+    if cli_registry:
+        return cli_registry
+    env_reg = os.environ.get("FUNCHUB_REGISTRY")
+    if env_reg:
+        return env_reg
+    cfg = load_config()
+    file_reg = cfg.get("registry")
+    if file_reg:
+        return file_reg
+    return "https://raw.githubusercontent.com/funchub-registry/registry/main"
+
+
+def resolve_token(cli_token: Optional[str] = None) -> Optional[str]:
+    if cli_token:
+        return cli_token
+    env_token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if env_token:
+        return env_token
+    cfg = load_config()
+    return cfg.get("github_token")
+
+
+def retry_request(
+    method: str,
+    url: str,
+    *,
+    headers: Optional[Dict[str, str]] = None,
+    json_data: Optional[Dict[str, Any]] = None,
+    max_retries: int = 3,
+) -> requests.Response:
+    last_exc: Optional[Exception] = None
+    for attempt in range(max_retries):
+        try:
+            resp = requests.request(
+                method, url, headers=headers, json=json_data, timeout=30
+            )
+            if resp.status_code in (502, 503, 504):
+                raise NetworkError(f"HTTP {resp.status_code}", attempts=attempt + 1)
+            return resp
+        except (requests.ConnectionError, requests.Timeout) as exc:
+            last_exc = exc
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)
+        except NetworkError as exc:
+            last_exc = exc
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)
+    raise NetworkError(str(last_exc), attempts=max_retries) from last_exc
+
+
+class GitHubRegistryClient:
+    API_BASE = "https://api.github.com"
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+        self.headers = {
+            "Authorization": f"token {token}",
+            "Accept": "application/vnd.github.v3+json",
+        }
+        self.registry_repo = "funchub-registry/registry"
+        self.registry_branch = "main"
+
+    def _api_url(self, path: str) -> str:
+        return f"{self.API_BASE}{path}"
+
+    def _check_write_permission(self) -> bool:
+        url = self._api_url(f"/repos/{self.registry_repo}")
+        resp = retry_request("GET", url, headers=self.headers)
+        if resp.status_code == 200:
+            data = resp.json()
+            permissions = data.get("permissions", {})
+            return permissions.get("push", False)
+        return False
+
+    def _get_user_login(self) -> str:
+        url = self._api_url("/user")
+        resp = retry_request("GET", url, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()["login"]
+
+    def _fork_repository(self) -> Dict[str, Any]:
+        url = self._api_url(f"/repos/{self.registry_repo}/forks")
+        resp = retry_request("POST", url, headers=self.headers, json_data={})
+        if resp.status_code in (200, 201, 202):
+            return resp.json()
+        raise FuncHubError(f"Fork 失败: HTTP {resp.status_code} {resp.text}")
+
+    def _fetch_file(
+        self, repo: str, path: str, branch: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        url = self._api_url(f"/repos/{repo}/contents/{path}")
+        params: Dict[str, str] = {}
+        if branch:
+            params["ref"] = branch
+        qs = "&".join(f"{k}={v}" for k, v in params.items())
+        full_url = f"{url}?{qs}" if qs else url
+        resp = retry_request("GET", full_url, headers=self.headers)
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        data = resp.json()
+        if isinstance(data, dict) and "content" in data:
+            decoded = base64.b64decode(data["content"]).decode("utf-8")
+            result = json.loads(decoded)
+            result["_gh_sha"] = data.get("sha")
+            return result
+        return None
+
+    def _get_default_branch_sha(self, repo: str) -> str:
+        url = self._api_url(f"/repos/{repo}/git/refs/heads/{self.registry_branch}")
+        resp = retry_request("GET", url, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()["object"]["sha"]
+
+    def _create_branch(self, repo: str, branch_name: str) -> None:
+        sha = self._get_default_branch_sha(repo)
+        url = self._api_url(f"/repos/{repo}/git/refs")
+        body = {"ref": f"refs/heads/{branch_name}", "sha": sha}
+        resp = retry_request("POST", url, headers=self.headers, json_data=body)
+        if resp.status_code not in (201, 200):
+            existing = retry_request(
+                "GET",
+                self._api_url(f"/repos/{repo}/git/refs/heads/{branch_name}"),
+                headers=self.headers,
+            )
+            if existing.status_code == 200:
+                return
+            raise FuncHubError(
+                f"创建分支失败: HTTP {resp.status_code} {resp.text}"
+            )
+
+    def _commit_file(
+        self, repo: str, branch: str, path: str, content_b64: str
+    ) -> None:
+        existing = self._fetch_file(repo, path, branch=branch)
+        url = self._api_url(f"/repos/{repo}/contents/{path}")
+        body: Dict[str, Any] = {
+            "message": f"发布工具 {path.split('/')[-1].replace('.json', '')}",
+            "content": content_b64,
+            "branch": branch,
+        }
+        if existing and "_gh_sha" in existing:
+            body["sha"] = existing["_gh_sha"]
+        resp = retry_request("PUT", url, headers=self.headers, json_data=body)
+        if resp.status_code not in (200, 201):
+            raise FuncHubError(
+                f"提交文件失败: HTTP {resp.status_code} {resp.text}"
+            )
+
+    def _create_pr(
+        self, repo: str, branch: str, title: str
+    ) -> str:
+        url = self._api_url(f"/repos/{self.registry_repo}/pulls")
+        body = {
+            "title": title,
+            "head": branch,
+            "base": self.registry_branch,
+        }
+        resp = retry_request("POST", url, headers=self.headers, json_data=body)
+        if resp.status_code in (200, 201):
+            return resp.json()["html_url"]
+        raise FuncHubError(f"创建 PR 失败: HTTP {resp.status_code} {resp.text}")
+
+    def publish_tool(
+        self,
+        tool_def: ToolDefinition,
+        force: bool = False,
+        dry_run: bool = False,
+    ) -> str:
+        if dry_run:
+            return f"[DRY RUN] 将提交到 {self.registry_repo}: tools/{tool_def.name}.json"
+        has_write = self._check_write_permission()
+
+        if not has_write:
+            fork_data = self._fork_repository()
+            fork_full_name = fork_data["full_name"]
+            target_repo = fork_full_name
+        else:
+            target_repo = self.registry_repo
+
+        current_content = self._fetch_file(
+            target_repo, f"tools/{tool_def.name}.json"
+        )
+
+        if current_content and current_content.get("author") != tool_def.author:
+            if not force:
+                raise ConflictError(tool_def.name, current_content.get("author", "unknown"))
+
+        new_content_json = tool_def.model_dump_json(indent=2)
+        encoded = base64.b64encode(new_content_json.encode()).decode()
+
+        branch = f"publish-{tool_def.name}"
+        self._create_branch(target_repo, branch)
+        self._commit_file(
+            target_repo, branch, f"tools/{tool_def.name}.json", encoded
+        )
+
+        if not has_write:
+            pr_url = self._create_pr(
+                target_repo,
+                f"{self._get_user_login()}:{branch}",
+                f"发布工具: {tool_def.name}",
+            )
+            return pr_url
+        return f"https://github.com/{self.registry_repo}/tree/{branch}/tools/{tool_def.name}.json"

funchub/loader.py

@@ -0,0 +1,151 @@
+import importlib
+import importlib.util
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from funchub.exceptions import LoadError, NetworkError
+from funchub.models import ToolDefinition, ToolVersion
+from funchub.version_parser import resolve_version
+
+
+class Loader:
+    _instances: Dict[str, Any] = {}
+
+    @staticmethod
+    def _git_retry(cmd: list, cwd: Optional[Path] = None, max_retries: int = 3) -> None:
+        last_exc: Optional[Exception] = None
+        for attempt in range(max_retries):
+            try:
+                result = subprocess.run(
+                    cmd,
+                    cwd=str(cwd) if cwd else None,
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                )
+                if result.returncode == 0:
+                    return
+                last_exc = subprocess.CalledProcessError(
+                    result.returncode, cmd, result.stdout, result.stderr
+                )
+            except (subprocess.TimeoutExpired, FileNotFoundError) as exc:
+                last_exc = exc
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)
+        raise NetworkError(str(last_exc), attempts=max_retries) from last_exc
+
+    @staticmethod
+    def ensure_tool(
+        tool_def: ToolDefinition,
+        target_version_str: str,
+        cache_base: Path,
+        yes: bool = False,
+    ) -> Path:
+        version_meta: Optional[ToolVersion] = None
+        for v in tool_def.versions:
+            if v.version == target_version_str:
+                version_meta = v
+                break
+        if version_meta is None:
+            raise LoadError(
+                f"版本 {target_version_str} 在工具 {tool_def.name} 中未找到"
+            )
+
+        tool_cache = cache_base / tool_def.name
+        version_file = tool_cache / ".version"
+        source_repo_file = tool_cache / ".source_repo"
+
+        if version_file.exists():
+            cached_version = version_file.read_text(encoding="utf-8").strip()
+            if cached_version == target_version_str:
+                return tool_cache
+
+        import warnings
+        repo_url = version_meta.source_repo
+        warnings.warn(
+            f"安全警告: 此工具将从远程仓库 {repo_url} 下载并执行代码。\n"
+            f"请确保您信任该仓库的作者，并在隔离环境中使用。\n"
+            f"若要查看源码，请访问: {repo_url}"
+        )
+
+        if not yes:
+            try:
+                answer = input("继续安装请按 Y，取消请按 N: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                raise LoadError("安装已取消")
+            if answer != "y":
+                raise LoadError("安装已取消")
+
+        source_ref = version_meta.source_ref
+
+        if tool_cache.exists():
+            Loader._git_retry(
+                ["git", "fetch", "--tags", "--depth", "1"],
+                cwd=tool_cache,
+            )
+            Loader._git_retry(
+                ["git", "checkout", source_ref],
+                cwd=tool_cache,
+            )
+        else:
+            tool_cache.mkdir(parents=True, exist_ok=True)
+            Loader._git_retry(
+                [
+                    "git", "clone", "--depth", "1",
+                    "--branch", source_ref,
+                    version_meta.source_repo,
+                    str(tool_cache),
+                ]
+            )
+
+        if version_meta.dependencies:
+            deps = version_meta.dependencies
+            pip_cmd = [sys.executable, "-m", "pip", "install"] + deps
+            Loader._git_retry(pip_cmd)
+
+        version_file.write_text(target_version_str, encoding="utf-8")
+        source_repo_file.write_text(version_meta.source_repo, encoding="utf-8")
+
+        return tool_cache
+
+    @staticmethod
+    def load_function(
+        tool_def: ToolDefinition,
+        target_version: str,
+        cache_base: Path,
+        yes: bool = False,
+    ) -> Callable:
+        tool_cache = Loader.ensure_tool(
+            tool_def, target_version, cache_base, yes=yes
+        )
+
+        entry = tool_def.entry_point
+        if ":" not in entry:
+            raise LoadError(f"entry_point 格式必须为 'module.sub:func_name'，got: {entry}")
+
+        module_path, func_name = entry.split(":", 1)
+
+        sys.path.insert(0, str(tool_cache))
+        try:
+            mod = importlib.import_module(module_path)
+        except ImportError as exc:
+            sys.path.pop(0)
+            raise LoadError(f"无法加载模块 '{module_path}': {exc}") from exc
+
+        if not hasattr(mod, func_name):
+            sys.path.pop(0)
+            raise LoadError(
+                f"模块 '{module_path}' 中没有函数 '{func_name}'"
+            )
+
+        func = getattr(mod, func_name)
+
+        if not callable(func):
+            sys.path.pop(0)
+            raise LoadError(f"'{module_path}:{func_name}' 不是可调用对象")
+
+        sys.path.pop(0)
+        return func

funchub/models.py

@@ -0,0 +1,33 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class ToolVersion(BaseModel):
+    version: str = Field(..., description="语义化版本，如 '2.1.0'")
+    source_repo: str = Field(..., description="完整 Git 仓库地址，含协议")
+    source_ref: str = Field(..., description="Tag 或分支名，如 'v2.1.0'")
+    dependencies: List[str] = Field(default_factory=list)
+    released_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    is_prerelease: bool = Field(
+        default=False, description="是否为 alpha/beta/rc 版本"
+    )
+
+
+class ToolDefinition(BaseModel):
+    name: str = Field(
+        ...,
+        pattern=r"^[a-z][a-z0-9_\-]{1,50}$",
+        description="仅小写字母、数字、下划线、连字符",
+    )
+    description: str = Field(..., max_length=200)
+    parameters: Dict[str, Any] = Field(
+        ..., description="标准 OpenAI 格式 JSON Schema"
+    )
+    author: str
+    entry_point: str = Field(
+        ..., description="'module.sub:func_name' 格式"
+    )
+    versions: List[ToolVersion] = Field(default_factory=list)

funchub/version_parser.py

@@ -0,0 +1,99 @@
+from typing import List, Optional
+from packaging.version import Version, parse, InvalidVersion
+from packaging.specifiers import SpecifierSet
+
+
+def convert_caret_to_specifier(constraint: str) -> Optional[SpecifierSet]:
+    if not constraint.startswith("^"):
+        return None
+    ver_str = constraint[1:]
+    try:
+        ver = parse(ver_str)
+    except InvalidVersion:
+        return None
+    if ver.major == 0:
+        if ver.minor is not None and ver.minor > 0:
+            upper = f"0.{ver.minor + 1}.0"
+        elif ver.minor == 0 and ver.micro is not None and ver.micro > 0:
+            upper = f"0.0.{ver.micro + 1}"
+        else:
+            upper = f"{ver.major + 1}.0.0"
+    else:
+        upper = f"{ver.major + 1}.0.0"
+    return SpecifierSet(f">={ver_str},<{upper}")
+
+
+def convert_tilde_to_specifier(constraint: str) -> Optional[SpecifierSet]:
+    if not constraint.startswith("~"):
+        return None
+    ver_str = constraint[1:]
+    try:
+        ver = parse(ver_str)
+    except InvalidVersion:
+        return None
+    if ver.minor is not None:
+        upper = f"{ver.major}.{ver.minor + 1}.0"
+    else:
+        upper = f"{ver.major + 1}.0.0"
+    return SpecifierSet(f">={ver_str},<{upper}")
+
+
+def resolve_version(
+    available_versions: List[str],
+    constraint: Optional[str] = None,
+    include_prerelease: bool = False,
+) -> Optional[str]:
+    if constraint in ("main", "master", "dev") or (
+        constraint is not None and constraint.startswith("branch:")
+    ):
+        if constraint is not None and constraint.startswith("branch:"):
+            return constraint.replace("branch:", "")
+        return constraint
+
+    parsed: List[Version] = []
+    version_map: dict = {}
+    for v in available_versions:
+        try:
+            ver = parse(v)
+        except InvalidVersion:
+            continue
+        if not include_prerelease and ver.is_prerelease:
+            continue
+        parsed.append(ver)
+        version_map[ver] = v
+
+    if not parsed:
+        return None
+
+    if constraint is None or constraint == "latest":
+        best = max(parsed)
+        return version_map.get(best, str(best))
+
+    if constraint in available_versions:
+        return constraint
+
+    spec: Optional[SpecifierSet] = None
+    if constraint.startswith("^"):
+        spec = convert_caret_to_specifier(constraint)
+    elif constraint.startswith("~"):
+        spec = convert_tilde_to_specifier(constraint)
+    elif constraint.startswith(">") or constraint.startswith("<") or constraint.startswith("=") or constraint.startswith("!"):
+        try:
+            spec = SpecifierSet(constraint)
+        except Exception:
+            spec = None
+    elif constraint.endswith(".x") or constraint.endswith(".X"):
+        major_str = constraint[:-2].strip()
+        try:
+            major = int(major_str)
+        except ValueError:
+            return None
+        spec = SpecifierSet(f">={major}.0.0,<{major + 1}.0.0")
+
+    if spec is not None:
+        matched = [v for v in parsed if spec.contains(v)]
+        if matched:
+            best = max(matched)
+            return version_map.get(best, str(best))
+
+    return None

funchub_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: funchub-sdk
+Version: 0.1.0
+Summary: FuncHub - A tool registry and dynamic loader for AI agents
+Author: FuncHub Team
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: packaging>=23.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+
+# FuncHub
+
+> ⚠️ **Security Warning**: FuncHub dynamically loads and executes code from remote Git repositories. **Only install tools from sources you trust**, and use in isolated environments.
+
+FuncHub is a bilingual (Python + NestJS) tool registry and dynamic loader designed for AI Agents. It allows developers to publish, discover, install, and dynamically invoke tool functions.
+
+## Features
+
+- **Dual SDKs**: Python SDK + NestJS SDK, sharing the same design philosophy
+- **Semver version management**: Supports `^1.2.3`, `1.x`, `latest`, branch names, etc.
+- **GitHub publishing integration**: Automatic Fork + PR workflow via GitHub API v3
+- **Cache management**: `.version` file tracks installed versions; expired cache auto-refetches
+- **Private registry support**: Supports custom indexes and mirrors via config
+- **Safety confirmation**: Interactive confirmation on install; `--yes` to bypass
+
+---
+
+## Installation
+
+### Python
+
+```bash
+pip install funchub-sdk
+```
+
+### NestJS
+
+```bash
+npm install funchub-nestjs
+```
+
+---
+
+## Quick Start
+
+### 1. Configure GitHub Token
+
+```bash
+# Python
+funchub login --token ghp_xxxxxxxxxxxx
+
+# NestJS
+npx funchub login --token ghp_xxxxxxxxxxxx
+```
+
+### 2. Search for Tools
+
+```bash
+funchub search scraper
+funchub search web
+```
+
+### 3. Install a Tool
+
+```bash
+# Install latest version
+funchub install web_scraper
+
+# Install with version constraint
+funchub install web_scraper@^1.0
+
+# Install development branch
+funchub install web_scraper@main
+```
+
+### 4. List Installed Tools
+
+```bash
+funchub list
+```
+
+### 5. Use a Tool in Code
+
+**Python:**
+```python
+from funchub import FuncHub
+
+hub = FuncHub()
+scraper = hub.load("web_scraper")
+result = scraper(url="https://example.com")
+```
+
+**NestJS:**
+```typescript
+import { FuncHub } from '@funchub/nestjs';
+
+const hub = new FuncHub();
+const scraper = await hub.load('web_scraper');
+const result = await scraper({ url: 'https://example.com' });
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `funchub login --token <PAT>` | Save GitHub Personal Access Token |
+| `funchub config set <key> <value>` | Set configuration (e.g., custom registry) |
+| `funchub publish --version v1.0.0` | Publish current directory as a tool |
+| `funchub publish --version v1.0.0 --force` | Overwrite existing tool with same name |
+| `funchub publish --version v1.0.0 --dry-run` | Preview without actual submission |
+| `funchub search <query>` | Search for tools in the registry |
+| `funchub install <name>@<constraint>` | Install a tool |
+| `funchub list` | List locally installed tools |
+| `funchub update <name>` | Update a tool to latest version |
+| `funchub update --all` | Update all installed tools |
+| `funchub info <name>` | Show tool details |
+| `funchub uninstall <name>` | Remove local tool cache |
+
+---
+
+## Publishing a Tool
+
+1. Create a `funchub.json` or `funchub.yaml` tool definition file in your project root:
+
+```json
+{
+  "name": "my_tool",
+  "description": "My awesome tool",
+  "version": "1.0.0",
+  "entry_point": "src/index:handler",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string" }
+    }
+  }
+}
+```
+
+2. Publish:
+
+```bash
+funchub publish --version v1.0.0
+```
+
+If you have write access to the registry repo, the tool is committed directly. Otherwise, a Fork + PR is automatically created.
+
+---
+
+## Decorator Usage (Python)
+
+```python
+from funchub import funchub_tool
+
+@funchub_tool(
+    name="web_scraper",
+    description="Scrape web page title",
+    version="1.0.0"
+)
+def scrape_url(url: str) -> str:
+    """Scrape the title from a URL."""
+    import requests
+    from bs4 import BeautifulSoup
+    resp = requests.get(url)
+    soup = BeautifulSoup(resp.text, 'html.parser')
+    return soup.title.string if soup.title else "No title found"
+```
+
+---
+
+## License
+
+Apache License 2.0

funchub_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+funchub/__init__.py,sha256=ojWRucfsMbUrOh6yAPUXrGHmxWRyxmkkRCyi94kOlxQ,58
+funchub/cli.py,sha256=5w3STpXTBdrJ5tjKwe0jaXeX0CT9nbIST2YDQbZWjwU,6446
+funchub/client.py,sha256=aiZRwLN5wofkYhBRMJibpdKPYn5alYhSVRIRcvFc_zQ,7420
+funchub/decorators.py,sha256=VNFWhTJ46Az1CcM0Pj3BkFBLZTdeTNfcI_8l45ejcMM,2461
+funchub/exceptions.py,sha256=oda8Nb7cpmNDeQr6tHDZ3XV730GK5gRJDs9XhciVbgA,1330
+funchub/github_client.py,sha256=hKx7B9Ayo6U_pJErvOMv28Uih1XR3dlb_m2XUjwiyW8,8593
+funchub/loader.py,sha256=1BWB2psEiOC3-f6E2r8NfOLs_HQWOhGwImXjpt7pbwM,5056
+funchub/models.py,sha256=6hYFFFa-ZtCAL4Ze14fv4IIa35ii4-8exdZFR6d2wCU,1188
+funchub/version_parser.py,sha256=igPRN6EU-Dbh8jx1r_pUw3M621VqScS_1R9ChOZn8ng,3125
+funchub_sdk-0.1.0.dist-info/METADATA,sha256=ZrVDI_2-ZaCqXVjRdzhR53cUIY_3XNthbAEnYIyxWvA,4742
+funchub_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+funchub_sdk-0.1.0.dist-info/entry_points.txt,sha256=3UfvorTYeyl4hBpeyWaLGltZLkWvf9V1cUKI16vlQK0,45
+funchub_sdk-0.1.0.dist-info/top_level.txt,sha256=5mYr-7A4qWwr2zn_hmP4y5nyJy8ikU0olTHRqCnfX8E,8
+funchub_sdk-0.1.0.dist-info/RECORD,,

funchub_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

funchub_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+funchub = funchub.cli:main

funchub_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+funchub