用途
Intercom Multi-Environment Setup 用于为开发、预发布（staging）和生产环境分别配置独立的 Intercom 工作区，并管理各环境专属的访问令牌、Webhook URL 与安全守卫。其目标是让同一套代码库在每个环境中都能正确运行，避免开发令牌误用于生产、破坏性任务误触生产数据等问题。
主要能力
- 环境配置加载：通过单一的
loadConfig()读取NODE_ENV，将共享密钥与各环境默认值（debug、缓存 TTL、限流并发数）合并。 - 环境感知客户端工厂：提供惰性初始化的
getClient()，当令牌缺失时抛出带有环境名称的明确错误。 - 按平台管理密钥：本地使用被 git 忽略的
.env.<environment>文件，CI/生产环境可存入 GitHub Actions、AWS Secrets Manager、GCP Secret Manager 或 HashiCorp Vault。 - 生产安全守卫：
EnvironmentGuard提供requireProduction()/preventProduction()，防止破坏性任务在错误的工作区执行。 - 按环境映射 Webhook URL：将
NODE_ENV映射到正确的公开 Webhook URL，部署之间无需修改代码。 - 启动时环境校验：启动时探测工作区，生产环境快速失败，其他环境仅警告并继续。
使用方式
技能按六个步骤推进：
- 环境配置——
loadConfig()读取NODE_ENV并合并共享密钥与环境默认值。 - 环境感知客户端工厂——惰性初始化的
getClient()。 - 按平台管理密钥——本地
.env.<environment>文件与 CI/生产密钥存储。 - 生产安全守卫——
EnvironmentGuard接入破坏性与仅生产操作。 - 按环境映射 Webhook URL。
- 启动时环境校验——
validateIntercomSetup()打印校验信息，生产环境失败时抛出异常，开发/预发布仅警告。
配置骨架示例：
// src/config/intercom.ts
function loadConfig(): IntercomEnvironmentConfig {
const env = (process.env.NODE_ENV || "development") as IntercomEnvironmentConfig["environment"];
const shared = {
accessToken: process.env.INTERCOM_ACCESS_TOKEN!,
webhookSecret: process.env.INTERCOM_WEBHOOK_SECRET!,
environment: env,
baseUrl: "https://api.intercom.io",
};
const envDefaults = {
development: { debug: true, cache: { enabled: false, ttlSeconds: 0 }, rateLimit: { maxConcurrency: 2 } },
staging: { debug: false, cache: { enabled: true, ttlSeconds: 60 }, rateLimit: { maxConcurrency: 5 } },
production: { debug: false, cache: { enabled: true, ttlSeconds: 300 }, rateLimit: { maxConcurrency: 10 } },
};
return { ...shared, ...envDefaults[env] } as IntercomEnvironmentConfig;
}
export const intercomConfig = loadConfig();
守卫破坏性任务示例：
const guard = new EnvironmentGuard(intercomConfig.environment);
async function nightlyCleanup() {
guard.preventProduction("nightlyCleanup"); // throws if NODE_ENV=production
await deleteAllTestContacts();
}
适用场景
- 需要将 Intercom 集成部署到开发、预发布和生产多个环境的团队。
- 希望统一管理各环境访问令牌与 Webhook URL 的项目。
- 需要防止破坏性任务误触生产工作区的场景。
- 使用 CI/CD 流水线并需要按环境选择正确令牌与 Webhook URL 的部署流程。
限制
- 需要准备独立的 Intercom 工作区（或至少在 Developer Hub 中创建独立应用）。
- 需要密钥管理方案（Vault、AWS Secrets Manager、GCP Secret Manager 等）。
- 需要支持环境变量的 CI/CD 流水线。
- 完整的分步代码位于
references/implementation.md，示例位于references/examples.md，本技能文件仅包含工作流与第一步骨架。 - 关于可观测性配置，需参考 intercom-observability 技能。