adding-env-variables

添加环境变量指南

关于如何为 Inkeep Agent Framework 添加新环境变量的全面指南，确保所有包中的配置保持一致、文档齐全且类型安全。

---

CI 强制检查

CI 会强制检查环境变量描述。 check:env-descriptions 脚本会在 CI 中运行；如果任何 env.ts 文件中的变量缺少 .describe() 调用，检查就会失败。

在本地运行检查：

pnpm check:env-descriptions

---

环境变量架构

该框架在多个 env.ts 文件中定义环境变量：

包	文件	用途
agents-api	agents-api/src/env.ts	主 API 服务配置
agents-core	packages/agents-core/src/env.ts	共享核心配置
agents-cli	agents-cli/src/env.ts	CLI 工具配置

注意： 以下文件由程序自动生成，不应编辑：

• packages/agents-mcp/src/lib/env.ts（由 Speakeasy 生成）

---

添加环境变量的必需步骤

步骤 1：添加到 .env.example

位置：.env.example（仓库根目录）

添加变量，并附上描述性注释：

# ============ SECTION NAME ============
# Description of what this variable does
# Additional context if needed (e.g., where to get API keys)
MY_NEW_VARIABLE=default-value-or-empty

示例：

# ============ AI PROVIDERS ============
# Required for agent execution
# Get your API keys from:
# Anthropic: https://console.anthropic.com/
# OpenAI: https://platform.openai.com/
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

步骤 2：添加到相关的 env.ts 文件

将变量添加到 Zod schema，并调用 .describe()，描述内容应与 .env.example 中的注释一致：

const envSchema = z.object({
  // ... existing variables ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('Description of what this variable does'),
});

步骤 3：描述要求

每个环境变量都必须有 .describe() 调用，并提供清晰、简洁的描述，以便：

1. 说明变量的用途
2. 与 .env.example 中的注释一致
3. 提供有帮助的上下文（例如 API 密钥的获取方式、默认行为）

好的描述示例：

// AI Provider keys
ANTHROPIC_API_KEY: z
  .string()
  .describe('Anthropic API key for Claude models (required for agent execution). Get from https://console.anthropic.com/'),

// Database configuration
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('PostgreSQL connection URL for the management database (Doltgres with Git version control)'),

// Authentication
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('Secret key for Better Auth session encryption (change in production)'),

// Feature flags
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable Langfuse LLM observability (set to "true" to enable)'),

---

Zod Schema 模式

必需变量

MY_REQUIRED_VAR: z
  .string()
  .describe('This variable is required for the application to function'),

可选变量

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('Optional configuration for feature X'),

带默认值的变量

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('Configuration with a sensible default'),

枚举变量

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('Logging verbosity level'),

数值变量

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('Maximum number of connections in the pool'),

布尔变量（以字符串形式表示）

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable feature X (set to "true" to enable)'),

带验证的变量

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET must be at least 32 characters')
  .optional()
  .describe('Secret key for signing JWT tokens (minimum 32 characters)'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: 'Invalid email address',
  })
  .describe('Admin email address for notifications'),

---

类别组织

在 .env.example 和 env.ts 中使用注释对相关变量进行分组：

在 .env.example 中：

# ============ DATABASE ============
INKEEP_AGENTS_MANAGE_DATABASE_URL=...
INKEEP_AGENTS_RUN_DATABASE_URL=...

# ============ AI PROVIDERS ============
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

在 env.ts 中：

const envSchema = z.object({
  // Database
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the management database'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the runtime database'),

  // AI Providers
  ANTHROPIC_API_KEY: z
    .string()
    .describe('Anthropic API key for Claude models'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('OpenAI API key for GPT models'),
});

---

应使用哪个 env.ts 文件？

根据变量的使用位置选择合适的文件：

使用场景	文件
API 服务配置	agents-api/src/env.ts
在多个包之间共享	packages/agents-core/src/env.ts
CLI 专用	agents-cli/src/env.ts
多个包	添加到 agents-core，并在需要的地方导入

---

添加环境变量检查清单

完成任何环境变量添加前，请确认：

• 已将变量添加到 .env.example，并附上描述性注释
• 已将变量添加到相关的 env.ts 文件
• 已添加 .describe() 调用，并提供清晰的描述
• 描述与 .env.example 中的注释一致
• 使用了合适的 Zod 类型（字符串、数字、枚举等）
• 如果变量不是必需的，已添加 optional()
• 如果存在合理的默认值，已添加 default()
• 如有需要，已添加验证（min、max、refine 等）
• 已使用注释将变量与相关变量分组
• 在本地运行 pnpm check:env-descriptions 并通过检查

---

应避免的常见错误

1. 缺少 .describe() 调用 - 每个变量都需要描述（否则 CI 会失败！）
2. 描述不一致 - 保持 .env.example 和 .describe() 中的描述同步
3. 文件选错 - 将变量添加到实际使用它的包中
4. 缺少验证 - 为敏感值添加约束（如密钥的最小长度、电子邮件验证等）
5. 编辑自动生成的文件 - 切勿编辑 agents-mcp 环境变量文件