[hunter-xue]

概述

为 KsADK 增加面向顶层 Google ADK Agent / LlmAgent 的内网 Streamable HTTP MCP Tunnel。企业侧 connector 通过出站 WS/WSS 注册内网 MCP Server，云端 ADKRunner 在后续轮次发现并调用工具，无需企业侧开放入站端口。

同时补齐项目级 CLI 配置、部署环境变量契约、构建依赖、 lifecycle/鉴权处理和中英文文档。

主要改动

• 新增 ksadk.tunnel：connector、per-app registry、FastAPI 路由、动态 TunnelToolset 和 MCP protocol handler。
• 接入 Runtime factory、应用装配和 ADKRunner，保持用户 Agent 延迟加载；共享 app-owned registry 和 Toolset，并处理断连、超时、取消、流式错误及关闭清理。
• 分离 Tunnel token、内部代理凭证和本地 MCP 凭证；代理及查询端点均有鉴权，日志和 dry-run 不输出秘密。
• Code/Container 构建根据 Tunnel 配置收集 MCP Runtime 依赖，并在标准入口按实际端口推导 self URL。
• agentengine config 为 ADK 项目提供可选 Tunnel 配置；config set --global 对 Tunnel 等项目级变量返回 global_unsupported_env_keys 并给出提示，不写入全局配置。
• 固定项目 .env、shell、显式 --env/--env-file 的部署合并和优先级，以及 CreateAgent / UpdateAgent 环境变量 payload。
• 新增配置、部署、connector、registry、server、toolset、Runtime 和本地 MCP E2E 测试，并纳入公开测试/导出清单。
• 更新中英文 Tunnel 指南、CLI 配置说明和环境变量参考。

外层网关建联契约

无路径前缀时，完整建联 URL 为：

wss://<agent-host>/tunnel/connect

带 base path 时：

wss://<agent-host>/<base-path>/tunnel/connect

当网关已经占用 Authorization 时，网关凭证通过 TunnelConnector.extra_headers 传递，Tunnel token 使用 URL 编码后的 query：

wss://<agent-host>/<base-path>/tunnel/connect?token=<url-encoded-tunnel-token>

TunnelConnector.cloud_url 只接收 base URL，不能重复包含 /tunnel/connect。外层入口网关必须放行该路径和 WebSocket Upgrade；/tunnel/mcp/* 是 Runtime 内部 loopback 代理，不应为了 connector 建联暴露到公网。

首版仍限定单 worker、单副本或经过验证的 sticky 拓扑，不支持自动重连和非 ADK Runtime 的自动工具注入。

真实验证

• Tunnel、CLI 配置、部署环境变量、公开导出等定向回归：83 项通过。
• 打包相关回归：26 项通过，3 项排除；被排除的既有 dist 静态入口检查使用旧 wheel/sdist，因缺少 Web/Studio 静态入口而失败，未记为通过。
• 隔离 HOME、临时 ADK 项目和假凭证下执行真实 CLI config set -> deploy --dry-run 与 launch --dry-run：Tunnel 开关进入 payload，token 为 *** 且 IsSensitive=true，未生成 self URL；config set --global 的独立全局文件不包含 Tunnel 变量。
• Ruff 和 git diff --check 通过。
• 使用中英文文档静态构建和输出审计通过（隔离的 pnpm 9.15.9）。
• 变更文件定向 secret/public-content 检查、tracked secret audit 和公开 source audit 通过。
• 非重型全量回归取得 2298 项通过、117 项跳过、1 项 xfail、1 项 xpass，同时存在 37 项失败和 96 项错误，主要涉及 PostgreSQL/pgserver、前端静态资产和可选外部工具链，因此不宣称全量测试通过。

尚未完成的云端验收

真实云端部署 E2E 尚未执行：当前没有经授权的隔离云端 Agent、入口网关和测试凭证。外层 WSS 转发、idle timeout、最大帧、长连接和 sticky 拓扑仍需在隔离环境中验收；本地 MCP E2E 和 CLI dry-run 不替代该云端验收。

Rebase 更新（2026-11-13）

• 已 rebase 到上游 main 的 48b413779f1fca18d68f03afe4f2dae081ec05cf（PR chore(ci): 移除 Studio 桌面构建流水线 #119），新 head 为 17212f92dbd7dbc3bbf5eae9f3213c9d01d3d9aa。
• 冲突解决同时保留上游本地 MCP OAuth、A2UI、交互资源关闭逻辑和 Tunnel 装配/清理逻辑。
• 按新 uv.lock 同步项目环境后，Tunnel、Runtime 装配、A2UI、MCP OAuth、配置和部署相关回归：164 项通过，10 项跳过。
• 使用上游指定的 pnpm 10.33.2 完成中英文文档静态构建和输出审计。
• Rebase 后 Ruff（上游既有 E501 除外）、diff whitespace、secret audit 和公开 source audit 通过。