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

功能门禁（manifest 契约 §9B，仅 auth="api_key"）：调用方 team 不具备要求的 feature 时，gateway 直接回 403 feature_required，请求不会下落到其它路由，handler 无需再判断。feature 名不超过 64 个字符，每条路由合计不超过 4096 个。带门禁的 manifest 自动声明 schema_version: 2：先升级 gateway 再发布（旧 gateway 会拒绝 v2 manifest，而不是不设门禁地服务它）。

@app.post("/v1/tts-pro")
@edge_route(auth="api_key", protocol="bytes",
            requires_features=["tts-pro"],                     # 全部需要
            requires_any_of=[["voice-clone", "enterprise"]])   # 每组至少一个
async def tts_pro(...): ...

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 直接编译。

形态按 Accept 协商的端点（protocol="negotiated"）

一个端点这次回 SSE、下次回裸音频或 JSON 时声明 protocol="negotiated"，gateway 按每个响应的 Content-Type 计费（manifest 契约 §9）。两条约束：

• WebSocket 形态是独立的 ws 路由：FastAPI WebSocket 端点上只接受 protocol="ws"（negotiated 会在 mount_edge 时报错），且要放在不同的 path 上——同 path + GET 的两条声明只有先声明的生效。完整例子见 examples/negotiated_demo.py。
• 免费形态显式报 0：不收费的响应发 usage_header(0)；什么都不发 = usage 缺失，gateway 计入 gateway_usage_missing_total 并告警（usage 契约 §8）。

上线顺序：所有 DC 的 gateway 升级到支持 negotiated 的版本之后，服务才能发布带 negotiated 的 manifest——旧 gateway 会拒掉整份 manifest（manifest 契约 §9 Rollout）。

环境变量

开发

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