fish-edge-gateway-sdk (Python)

接入 apex-edge-gateway 的服务侧 SDK：manifest 声明与暴露、internal auth、trace 透传。协议契约见仓库 docs/contracts/。

安装（不发布 PyPI，直接 git 依赖）

# requirements.txt / pyproject dependency（锁 tag 或 commit，不要追 main）
fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@<tag-or-sha>#subdirectory=sdk-python

# 本地开发
pip install "fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@main#subdirectory=sdk-python"

# uv
uv add "fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@main#subdirectory=sdk-python"

# CI / Docker（https + token，避免挂 ssh key）
pip install "fish-edge-gateway-sdk @ git+https://${GITHUB_TOKEN}@github.com/fishaudio/apex-edge-gateway.git@<sha>#subdirectory=sdk-python"

版本锁定约定：SDK 变更打 sdk-python/vX.Y.Z 形式的 git tag，服务锁 tag 升级；紧急验证可锁 commit sha。

集成

from fastapi import Depends, FastAPI
from fish_edge_gateway_sdk import edge_route, mount_edge, require_gateway

app = FastAPI()

@app.post("/internal/asr", dependencies=[Depends(require_gateway)])
@edge_route(auth="internal")
async def asr(payload: dict) -> dict: ...

mount_edge(app, service="omni-asr")   # 挂载 GET /.edge/manifest

k8s Service 侧标注（manifest 契约 §2.1）：

metadata:
  annotations:
    fish.audio/edge-discovery: enable
    # 可选：manifest 端点与业务端口分离时
    # fish.audio/edge-discovery-port: "9090"
    # fish.audio/edge-discovery-url: /.edge/manifest

gateway 侧无需额外授权：发现 namespace 的成员资格就是信任边界（manifest 契约 §11），被发现的 manifest 其 route 直接编译。

环境变量

开发

pip install -e "sdk-python[dev]"
pytest sdk-python/tests -q