企业级 Agent 平台集成最佳实践

企业或平台客户（如新东方、贝壳、Tapd）在向员工或下游用户分发云开发能力时，通常面临三大实际痛点：

用户没有腾讯云账号：无法通过扫码或开发者控制台完成授权。
密钥泄露与管理繁琐：不能要求用户手工复制粘贴明文 API Key，极易由于误提交代码仓库或对话历史存储导致凭据外泄。
Agent 行为不可控：大模型生成的资源配置常常脱离企业合规基线（例如，在内网办公环境下创建云函数，因缺少 VPC 配置导致无法访问内网数据库）。

为解决上述问题，企业应当建立统一的集成规范。本指南提供了一套以凭证静默交付与 Agent 行为约束为核心的集成最佳实践。

权责边界划分

企业自建 Agent 平台与云开发的基础设施具有明确的权责划分：

维度	云开发（CloudBase）负责什么	企业 / 平台负责什么
环境与算力	租户隔离的底层基础设施（云数据库、云函数、静态托管、云存储等）；高并发环境生命周期管理 API	员工/团队账号与隔离环境 ID（`envId`）的映射关系维护（“谁对应哪个环境”）
身份与鉴权	细粒度的环境 API Key 校验；临时安全凭证（STS）的生成与验证	统一登录态校验（如企业微信 OAuth、司内单点登录）；向终端用户分发或屏蔽密钥
工具与安全	底层通用的 MCP 协议实现（36 个核心 Tool）；数据库底层的行级安全（RLS）和安全规则	敏感/破坏性操作（如删除表、清空环境）的拦截与人工审批流；工具调用的合规审计日志
Agent 管控	支持加载自定义的 Skill、System Prompt 与模型优先级配置	司内专属 Experts 专家的编写、公共 Skill 包的治理、全局 System Prompt 约束的强制注入

一、双层网关与凭证静默交付

要解决「无云账号接入」和「不碰明文密钥」，企业集成方的标准架构是在客户端 Agent 与云开发之间架设一层双层网关，实现身份的静默置换。

1. 员工身份与环境凭证的解耦

员工在企业内部 IM 或工作台登录时，使用的是司内已有身份。平台通过外层网关拦截请求，根据内部账盘将「员工 ID」置换为对应的云开发 envId 和 apiKey：

长期 API Key 与 envId 由平台统一保管，自始至终不向终端用户暴露，彻底杜绝明文密钥在对话记录或客户端配置中泄露的可能。
客户端使用 设备码回调（Device Flow） 或内嵌服务，在用户点击「确认授权」后，由 Helper 进程静默接收 envId 和 apiKey，并直接落地于本机的凭证配置文件。

2. 本地临时换证（STS）机制

客户端工具（如本地 MCP 服务、CloudBase CLI）在拿到 apiKey 后，并不直接使用它进行日常工具调用，而是通过 exchangeApiKeyForCredential 机制，在本地向 capi 换取 30 分钟内有效的临时凭证：

curl -X POST "https://<envId>.ap-shanghai.tcb-api.tencentcloudapi.com/capi/credential" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <apiKey>" \
  -d '{"env": "<envId>"}'

临时凭证（包含 TmpSecretId、TmpSecretKey、Token）以如下结构写入本地 ~/.config/.cloudbase/auth.json，在未过期前直接使用，过期后自动重新换取：

{
  "credential": {
    "tmpSecretId": "AKID...",
    "tmpSecretKey": "...",
    "tmpToken": "...",
    "tmpExpired": 1787036755000,
    "envId": "env-xxx",
    "authSource": "api_key",
    "apiKey": "ak-xxx"
  }
}

二、经典案例：WorkBuddy 专属专家定制

为了让新上手的企业更直观地理解如何闭环落地这套方案，我们以在 WorkBuddy 中**定制一个「新东方全栈小程序开发专家」**为例，演示如何同时解决「静默交付」与「行为约束」两个核心诉求。

1. 专家设计与 Helper 逻辑（零明文授权）

新东方平台方将授权 Helper（一个自包含的 helper.js 脚本）打包进专属的专家包中。

new-oriental-webdev-expert/
├── skills/
│   └── auth-bootstrap/
│       ├── helper.js          # 本地回调 Helper 脚本
│       └── SKILL.md           # 专家技能声明
└── manifest.json              # 专家描述与 Prompt 配置

当员工对专家说 “我要连接云开发” 时：

启动本地服务：helper.js 在本机起一个一次性的 HTTP 服务，监听本地随机端口（例如 127.0.0.1:4001）。
引导授权：Helper 自动打开浏览器跳转至平台统一授权端点 https://auth.new-oriental.com/login?cliAuth=1&_redirect_uri=...&port=4001。
静默回写：员工登录并选好项目环境后，授权页回调重定向至 http://127.0.0.1:4001/?authSource=api_key&envId=env-xxx&apiKey=ak-xxx。
换证写盘：Helper 接收到参数，调用 capi 换取临时 STS 凭证，直接写入本机 ~/.config/.cloudbase/auth.json。

员工只需完成一次「点击网页授权」动作，密钥自动分发完成，全过程无需人工复制粘贴任何明文凭证。

2. 行为约束与安全注入（以 VPC 配置为例）

大模型在使用 createFunction 等工具创建云函数时，由于通用知识的局限，默认不会主动配置企业内网 VPC，这会导致函数无法连通司内的线下数据库。

平台方通过在专家的 manifest.json 中配置 System Prompt（系统提示词） 来实施硬约束。

系统提示词配置示例（System Prompt）：

# 腾讯云开发合规注入规则（必须遵守）：
你现在是【新东方全栈小程序开发专家】，当前正在企业内网网络环境下运行。
任何时候你代表用户使用工具创建或更新云开发函数（如调用 createFunction）时，你必须强制为函数注入统一的 VPC 配置。

你必须静默填充以下参数，不要向用户询问这些 ID，也不得遗漏：
- vpcId: "vpc-5a6b7c8d"
- subnetId: "subnet-1a2b3c4d"

示范调用结构：
{
  "name": "createFunction",
  "arguments": {
    "name": "my-internal-api",
    "vpcId": "vpc-5a6b7c8d",
    "subnetId": "subnet-1a2b3c4d",
    "code": "..."
  }
}

通过这一层 Prompt 约束，即使模型生成的原始方案不带网络参数，也会被强制纠偏，保证创建出来的所有云产物天然符合企业的网络合规标准。

三、多应用多环境的物理隔离原则

在企业级集成中，如何合理规划环境和目录，直接关系到开发效率和数据安全。企业应当遵循**「一个应用一个环境」**的物理隔离原则：

对的：一个应用 = 一个项目目录 = 一个工作区
workspace/
├── app-student-portal/        ➜ 对应环境 env-student-prd
│   └── .cloudbase/
└── app-teacher-ledger/        ➜ 对应环境 env-teacher-prd
    └── .cloudbase/

不对：多个应用混在同一个目录下
workspace/
└── school-systems/
    ├── student-portal/        ❌ 共用同一个目录
    └── teacher-ledger/        ❌ 共用同一个环境，无法区分

1. 物理隔离的底噪

Agent 是由工具在启动时自动把「当前工作区（Workspace）」的位置传递给它，它不具备主动向下钻取或区分同目录下其他文件夹的能力。因此：

换应用必须换目录：只有不同的目录，AI 读写到的 .cloudbase/ 登录信息才是独立的，才能做到「打开哪个项目，就自动连对哪个环境」，避免张冠李戴。
换环境必须换 Key：一把 API Key 仅对应一个租户环境，环境之间彻底隔离。

2. 共用单一环境的代价矩阵

如果企业试图将多个独立的系统混在同一个云开发环境中开发，将面临以下严重的架构风险：

资源维度	共用环境的代价与风险
静态托管 / 网页部署	只能靠子路径（如 `/student/`、`/teacher/`）区分，极易因为一次错误的部署把其他应用的静态文件全局覆盖覆盖。
云函数	函数命名空间全局共享。若不同应用定义了同名函数（如 `login`），部署时会直接发生硬覆盖冲突。
云数据库	集合与表混在一起，必须人工依靠集合前缀（如 `t_` / `s_`）区分；极难做数据库备份、恢复与部分导出。
数据安全性	无法做到「最小特权原则」。一把 API Key 具有对该环境所有资源的读写权限，无法约束甲应用只能动甲的数据。
额度与计量	平台无法统计每个子应用的实际资源消耗、网络用量和 AI Token 占用，无法进行财务对账或用量分摊。

因此，无论是自建的 Agent，还是像 WorkBuddy 这类集成客户端，最佳实践均是**强制推行「一个项目、一个独立工作区、对应一个隔离环境」**的物理隔离规范，利用云开发平台版高并发、免运维的 API 快速开通新环境，来实现生产级的多租户安全硬隔离。

权责边界划分​

一、双层网关与凭证静默交付​

1. 员工身份与环境凭证的解耦​

2. 本地临时换证（STS）机制​

二、经典案例：WorkBuddy 专属专家定制​

1. 专家设计与 Helper 逻辑（零明文授权）​

2. 行为约束与安全注入（以 VPC 配置为例）​

三、多应用多环境的物理隔离原则​

1. 物理隔离的底噪​

2. 共用单一环境的代价矩阵​