[XnLemon]

背景

企业落地 Agent 应用时，通常需要同时服务多个租户、业务线、Agent、IM 入口和数据后端。平台不仅要能运行一次对话，还需要解决配置发布、租户隔离、运行时装配、连接生命周期、故障恢复、测试验证和生产部署等问题。

本 PR 将主仓库已经合并的多租户 WebUI、Telegram/WeCom AI Bot 连接能力和 0.1.1 发布内容同步到当前平台仓库，使系统形成一条从配置、发布、连接到真实对话验收的完整链路。

来源 PR：

• [XnLemon/trpc-agent-service#165](release: prepare tRPC Agent Service v0.1.1 XnLemon/trpc-agent-service#165)
• Merge commit：204faa4de9b25787ed22f019ad49ef37399a07f0

变更概览

本 PR 主要包含以下内容：

• 新增多租户 WebUI setup flow；
• 支持通过 WebUI 创建租户、Agent、Model Profile、Backend Profile 和 Agent Revision；
• 支持 Agent 发布、默认 Agent 设置和租户切换；
• 新增 Telegram 与 WeCom AI Bot 的租户级连接管理；
• 新增连接状态查询、断开和生命周期管理；
• 新增按租户懒加载的 TenantRuntimeRegistry；
• 将 tenant、app、revision、model/backend profile 纳入运行时计划缓存身份；
• 加强审计、Secret、Channel Binding 和运行时隔离；
• 补充 Admin API、Bootstrap、Runtime、Web Connection 和 WebUI 测试；
• 完善部署文档、真实渠道验收文档和 0.1.1 发布配置。

核心工程设计

多租户运行时隔离

• Tenant、Agent App、Revision、Model Profile、Backend Profile 和 Channel Binding 均具有明确的租户边界。
• 新租户和新 Agent 创建后可以在第一次请求时懒加载，不需要重启服务。
• Runtime Plan 的缓存身份包含：

tenant_id
app_id
revision_id
model_profile_version
backend_profile_version
content_digest

避免不同租户、不同 Agent 或不同配置版本之间复用错误的 Runner。

• Channel 消息不能自行声明 tenant_id 或 app_id，可信路由始终从服务端维护的 Binding 和控制面配置中解析。
• 审计事件按照事件自身的 tenant_id 动态路由，避免固定租户的审计 writer 导致跨租户请求失败。

WebUI 配置闭环

管理员可以通过 WebUI 完成：

1. 登录管理员账号；
2. 创建或选择租户；
3. 创建 Agent；
4. 配置模型、Endpoint 和指令；
5. 创建并发布 Model Profile、Backend Profile 和 Agent Revision；
6. 设置默认 Agent；
7. 连接 Telegram 或 WeCom AI Bot；
8. 发送第一条真实消息并验证回复。

这条路径把原本需要手动调用多个 Admin API 的流程收敛成了可执行、可验收的配置闭环。

Channel Connection 生命周期

新增租户级连接接口：

• POST /admin/v1/tenants/{tenant_id}/connections
• GET /admin/v1/tenants/{tenant_id}/connections
• DELETE /admin/v1/tenants/{tenant_id}/connections/{binding_id}

连接凭据只在认证后的连接请求中进入进程内 Secret Registry，不写入：

• Control Plane；
• Agent Revision；
• Runtime Plan；
• 日志；
• Trace；
• 审计事件；
• HTTP 响应。

Telegram 连接使用真实 Bot API 身份校验和 long polling。WeCom AI Bot 使用官方 WebSocket 长连接协议，覆盖认证回执、心跳、重连、回复确认和 Outbox 投递。

测试驱动的工程闭环

本次实现过程中针对 Codecov、gocyclo 和 gosec 反馈进行了专项修正：

• 拆分高复杂度的路由和 Web Connection 场景测试；
• 将测试中的敏感凭据样例替换为安全 fixture；
• 补充 Runtime Materialization、Bootstrap、Environment、Plan Resolver 和 Channel Lifecycle 分支；
• 将关键错误路径、清理路径和并发边界纳入测试。

CI 与质量门禁

主仓库合并后的 main 分支 CI 已全部通过：

[主仓库 CI Run](https://github.com/XnLemon/trpc-agent-service/actions/runs/34445046749)

通过的主要门禁包括：

• Format & Lint；
• Commit Secret Scan；
• Build、Test & Coverage；
• Race Tests；
• Deployment Validation；
• Deterministic fault-injection E2E；
• Telegram live long-polling E2E；
• WeCom deterministic callback E2E；
• MkDocs strict documentation build；
• GitHub Pages deployment。

CI 使用 PostgreSQL 16、MySQL 8.0 服务容器执行数据库迁移、Repository、初始化和控制面相关测试，并通过独立的 Race Tests 验证并发访问和资源生命周期。

部署验证还会实际完成：

• Docker 镜像构建；
• Docker Compose 启动；
• /healthz 和 /readyz 检查；
• 离线 Demo 初始化；
• 第一条 /v1/chat 请求。

Test Coverage

最终 Codecov 结果：

• Project coverage：89.07%
• Project lines：23,391 / 26,260
• Patch coverage：85.40773%
• Patch missing lines：102
• Project 和 Patch 门禁目标：85%
• Codecov 状态：pass

报告入口：

[Codecov PR #165 Report](https://app.codecov.io/gh/XnLemon/trpc-agent-service/pull/165)

覆盖率脚本使用单次原生 Go -coverpkg profile，同时统计跨包执行路径，避免不同测试二进制之间重复初始化或产生不一致的覆盖率结果。

本次新增和强化的测试重点包括：

• Admin Connection Routes；
• Telegram / WeCom Connection Lifecycle；
• Tenant Runtime Materialization；
• Runtime Plan Resolver；
• Bootstrap 和 Environment 构建分支；
• Web Connection 错误、清理和替换路径；
• HTTP/WebUI 嵌入和健康检查；
• WeCom AI Bot 认证及重连边界；
• 多租户审计和运行时隔离。

真实验收情况

离线部署验收

主仓库 CI 已通过 Docker Compose Golden Path：

./scripts/quickstart.sh --demo

该流程从空数据库开始，完成 Tenant、Agent、Model、Backend 和 Revision 的幂等初始化，并实际调用 /v1/chat 返回确定性响应。

Telegram Live E2E

主仓库包含真实 Telegram Bot API 的长轮询验收：

[Telegram Live E2E Run](https://github.com/XnLemon/trpc-agent-service/actions/runs/34445046627)

该流程使用受保护的 Telegram credentials，验证：

• Bot 身份获取；
• long polling；
• 入站消息接收；
• Agent 执行；
• Reply Outbox；
• 回复发送；
• durable outbox runner。

WeCom AI Bot 验收

主仓库 CI 通过了确定性的 WeCom callback/outbox E2E：

[WeCom Deterministic E2E Run](https://github.com/XnLemon/trpc-agent-service/actions/runs/34445046659)

该测试重点验证协议边界、回调处理、数据库状态和 Outbox 投递，不依赖公开的企业微信账号凭据。

同时，仓库中已经沉淀了真实 AI Bot WebSocket 的人工验收路径，包括：

• AI Bot ID/Secret 配置；
• WebSocket 认证；
• 连接状态确认；
• 企业微信客户端真实发消息；
• tenant/app 路由检查；
• Agent 回复确认；
• 两个租户之间的会话隔离；
• 服务重启后的重新连接。

完整验收文档：

[多租户多 Agent Telegram / WeCom 验收链路](https://github.com/XnLemon/trpc-agent-service/blob/main/docs/docs/multitenant-telegram-acceptance.md)

仓库还保留了 Telegram、企业微信自建应用和企业微信 AI Bot 的实际接入截图及 GIF，作为人工验收材料。

工程化亮点

• 通过不可变 Revision 和版本化 Runtime Plan 保证执行配置稳定；
• 通过 tenant/app/revision/profile/digest 组合缓存键防止跨租户复用；
• 通过 Server-side Binding 保证可信路由，不信任外部消息中的租户字段；
• 通过 Secret Registry、日志脱敏和 Secret Scan 保护模型及渠道凭据；
• 通过 PostgreSQL、Redis、Outbox、lease/fencing 支撑多节点运行和故障恢复；
• 通过单元测试、数据库集成测试、Race Test、故障注入、Live E2E 和人工验收形成分层质量体系；
• 通过 Docker Compose Golden Path 和 Deployment Validation 验证部署可用性；
• 通过 MkDocs strict build 保证文档、导航和链接保持有效；
• 通过 Codecov 设定项目级和 Patch 级 85% 覆盖率门禁；
• 将真实验收步骤、日志证据、故障定位和已知边界固化到仓库文档中。

已知边界

• Telegram 和 WeCom AI Bot Secret 当前保存在进程内，服务重启后需要通过 WebUI 重新连接；
• GitHub Actions 中的 WeCom E2E 是 deterministic callback 测试，真实公网 AI Bot 账号验收需要在受保护部署环境执行；