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

企业或平台客户在向员工或下游用户分发云开发（CloudBase）能力时，通常面临三大实际痛点：

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

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

核心集成路径

平台客户无需修改云开发底层架构，只需通过以下三种灵活的技术手段组合，即可适配企业内部的个性化业务场景与安全规范：

自定义 Agent 专家（Expert）：将身份认证（Helper）、常用 Skill 及专属提示词打包为「企业专属专家」，员工只需一键加载，即可开箱即用。
自定义 System Prompt / Skill 约束：在大模型调用底层工具前，通过系统提示词或 Skill 强行注入企业合规基线（如 VPC 配置、资源命名规范等），确保 Agent 生成的云资源天然合规。
封装 / 代理云开发 MCP（Model Context Protocol）：代理云开发的核心 MCP 工具，把云数据库、云函数、云存储等算力接入企业自建平台。网关层负责鉴权，也可以在网关层禁用某些工具，或审计每次调用的入参与出参。实操教程：封装企业专属 MCP。

使用 AI 快捷集成

复制以下提示词给你的 AI 编程助手（如 Cursor、Windsurf、Copilot 或企业自建 Agent），由 AI 引导并协助你完成接入：

AI 集成提示词：

我想在当前项目中集成腾讯云开发（CloudBase）的企业级 Agent 平台能力。

请先阅读以下参考文档：

https://docs.cloudbase.net/skill.md

https://docs.cloudbase.net/solutions/cloudbase-platform-edition/enterprise-integration

结合文档，请先向我了解我们目前的系统架构、鉴权方式及合规要求，与我澄清并评估最合适的集成方案（如：自定义 Expert 专家、修改 System Prompt / Skill，或是封装 MCP 工具）。方案确认后，再一步步指导或协助我完成落地实施。

权责边界划分

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

维度	云开发（CloudBase）负责什么	企业 / 平台负责什么
环境与算力	租户隔离的底层基础设施（云数据库、云函数、静态托管、云存储等）；高并发环境生命周期管理 API	员工 / 团队账号与隔离环境 ID（`envId`）的映射关系维护（「谁对应哪个环境」）
身份与鉴权	细粒度的环境 API Key 校验；临时安全凭证（STS）的生成与验证	统一登录态校验（如企业微信 OAuth、企业单点登录）；向终端用户分发或屏蔽密钥
工具与安全	底层通用的 MCP 协议实现；数据库底层的行级安全（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"
  }
}

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

为了让企业更直观地理解如何通过自定义专家与 Prompt / Skill 闭环落地这套方案，下面以在企业自建或集成客户端中定制一个「全栈小程序开发专家」为例演示。

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

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

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

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

启动本地服务：helper.js 在本机起一个一次性的 HTTP 服务，监听本地随机端口（例如 127.0.0.1:4001）。
引导授权：Helper 自动打开浏览器跳转至平台统一授权端点 https://auth.enterprise.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. Prompt 与 Skill 行为约束（实现特定合规注入）

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

平台方通过在专家的 manifest.json 或自定义 Skill 中配置 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 平台，还是第三方的集成客户端，最佳实践都是强制推行「一个项目、一个独立工作区、对应一个隔离环境」的物理隔离规范，利用云开发平台版高并发、免运维的 API 快速开通新环境，实现生产级的多租户安全硬隔离。

核心集成路径​

使用 AI 快捷集成​

权责边界划分​

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

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

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

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

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

2. Prompt 与 Skill 行为约束（实现特定合规注入）​

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

1. 物理隔离的底层逻辑​

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