Blade Agent 环境变量整理

2026-07-09 · chore/env-cleanup 分支

本文档记录了对 .env.example 的完整审计过程、发现的问题、以及每个分组的整理决策。

1. 审计结果总览

对项目中所有 Python / Go / TypeScript 源码进行全量搜索，与 .env.example 交叉比对，发现三类问题：

2
已死亡
源码无引用
30+
缺失
源码在用但 .env.example 没有
6
噪音
赋值为空 / 等于默认值

2. 已死亡的变量

变量 状态 说明
AGENT_STREAM_DEBUG 已删除 源码中已无引用，仅残留在 docs/specs
AGENT_EVENT_LOG 已删除 同上
过时但保留兼容： SKILL_REGISTRY_URL 已被 BLADE_HUB_URL 取代， 代码中仅作 fallback。在 .env.example 中注释掉并标注"旧名兼容"。

3. 缺失的变量（已补齐）

LLM 相关
FAST_MODEL FAST_BASE_URL FAST_API_KEY DROP_PARAMS AGENT_MAX_TURNS COMPACTION_RATIO
鉴权 / License
BLADE_ENV BLADE_ADMIN_EMAILS DISABLE_PASSWORD_AUTH BLADE_OAUTH_URL BLADE_AGENT_LICENSE_SERVICE_TOKEN
技能中心
BLADE_HUB_URL SKILL_REGISTRY_SERVICE_TOKEN
Gitea
GITEA_URL GIT_PASSWORD GIT_ACCESS_TOKEN GITEA_TOKEN BLADE_SANDBOX_GITEA_URL
部署集成 / Blade OS
BLADE_PUBLIC_API_URL BLADE_PUBLIC_SHARING BLADE_BO_INTERNAL_URL BLADE_BO_INTERNAL_SECRET
其他
BLADE_SOCKETIO_TRACE VIBE_CODING_SANDBOX_IMAGE BLADE_EXAMPLE_SESSION_PATHS BLADE_ENFORCE_NO_SPACE_PATHS

4. 观测配置拆分决策

问题

观测相关环境变量约 15+ 个（Langfuse、Helicone、Sentry、PostHog、OTEL、Pyroscope...）， 配置复杂，普通运维难以理解，且大部分部署场景用不到。

否决方案：YAML 文件

思路：像 OAuth 一样，用 YAML 文件统一管理观测配置。

否决原因：观测变量大多是行业标准 env var，外部 SDK 直接从 os.environ 读取：

  • LANGFUSE_* — Langfuse SDK 自动读取
  • OTEL_* — OpenTelemetry 标准规范
  • SENTRY_DSN — Sentry SDK 自动读取
  • PYROSCOPE_* — Pyroscope SDK 自动读取

如果放进 YAML，要么需要"读 YAML → 回写 os.environ"的桥接（两个 source of truth），要么放弃 SDK 自动初始化改手动传参（fragile）。OAuth 能用 YAML 是因为它完全是自己的逻辑，没有外部 SDK 按固定名字读取。

采纳方案：env 模板文件

在 configs/ 下放两个 .env 片段文件作为参考模板：

server
configs/observability.server.env.example

Langfuse + Helicone + Sentry + PostHog + OTEL + Pyroscope 全开

box
configs/observability.box.env.example

仅 JSONL 本地诊断日志，无外网依赖

.env.example 中观测部分从 ~20 行缩减为 5 行引导注释，指向这两个模板。运维按场景复制粘贴即可。

5. 逐组分析与建议

LLM Provider

35 行 → 建议拆分

问题

  • 太长（35 行），包含了普通用户不需要碰的高级调参
  • SSL_VERIFY=false — 代码默认值已经是 false，写在这里等于重复
  • 命名太通用（API_KEY、BASE_URL）容易冲突，但改名影响面大

建议

  • 把高级调参（LLM_BACKEND、DROP_PARAMS、AGENT_MAX_TURNS、COMPACTION_RATIO、TOOL_RESULT_IMAGE_MODE、SSL_VERIFY）和快速模型一起归到"LLM 高级配置"区块
  • SSL_VERIFY=false 改为注释

Builtin Tools + Checkpoints

各 1 个变量 → 建议合并

两个独立 section 各只有 1 个变量（BLADE_ENABLE_HTML_RENDER_TOOL 和 BLADE_CHECKPOINTS_ENABLED）。建议合并为一个"功能开关"分组。

Memory

内联 YAML 示例冗余

内联的 YAML 示例有 10 行，和 configs/memory.example.yaml 完全重复。建议删掉内联示例，只留一行指向 yaml 文件的引导——与观测的处理方式一致。

散落变量

未归组

以下变量散在各 section 之间没有归属：

变量 问题 建议归组
BLADE_SKILL_PATHS 空值 = 不设置 Skill Registry / Hub
BLADE_GIS_MAP_URL 空值 = 不设置 功能开关 或 Blade OS 集成
BLADE_AGENT_MCP_ENABLED 总开关，逻辑上属功能开关 功能开关
BLADE_OS_PATH 和 BLADE_OS_BASE_URL 容易混淆 Blade OS 集成（加注释区分）
BLADE_SKILL_DOWNLOAD_CACHE 空值 = 不设置 Skill Registry / Hub

噪音变量（赋值 = 默认值）

建议全部注释掉
变量 当前值 代码默认
SSL_VERIFY=falsefalsefalse
DOCUMENT_READER=lightlightlight
BLADE_HUB_URL=空空
BLADE_SKILL_PATHS=空空
BLADE_GIS_MAP_URL=空空
BLADE_SKILL_DOWNLOAD_CACHE=空空

复制 .env.example 的人会以为这些是"必须填写"的，实际效果和不写一样。

MULTICA_SERVER_URL

默认不应启用

MULTICA_SERVER_URL=http://localhost:8080 是 uncommented 且带默认值，意味着复制 .env.example 就会连 Multica。如果 Multica 不是默认必须的，应该注释掉。

BLADE_OS_PATH vs BLADE_OS_BASE_URL

容易混淆

两个名字很像，但用途不同：

  • BLADE_OS_PATH — 前端跳转地址（"安装到 BladeOS"按钮的目标 URL）
  • BLADE_OS_BASE_URL — 后端 API 地址（服务间调用，推送桌面图标）

改名影响面大，这次至少在注释里说清楚区别。

过于冷门的变量

建议从 .env.example 移除
变量 原因
BLADE_ENFORCE_NO_SPACE_PATHS 路径空格检查，极其冷门
BROWSER_EXTENSION_OAUTH_* 有内置默认值，几乎没人需要改
PUBLISHED_APP_RECONCILE_INTERVAL_SECONDS 运维也不需要改这个定时间隔
BLADE_OBSERVABILITY_SERVICE_NAME 已在 observability 模板文件中
BLADE_DEPLOYMENT 同上

6. 待执行改动清单

按优先级排序：

✓
观测配置拆分为模板文件
已完成 — configs/observability.{server,box}.env.example
1
空值变量全部注释掉
SSL_VERIFY, DOCUMENT_READER, BLADE_HUB_URL, BLADE_SKILL_PATHS, BLADE_GIS_MAP_URL, BLADE_SKILL_DOWNLOAD_CACHE, MULTICA_SERVER_URL
2
Memory 删内联 YAML 示例，改指向 configs/memory.example.yaml
与观测的处理方式一致，减少重复
3
Builtin Tools + Checkpoints 合并为"功能开关"
加入 BLADE_AGENT_MCP_ENABLED、BLADE_GIS_MAP_URL
4
散落变量归组
BLADE_SKILL_PATHS/DOWNLOAD_CACHE → Skill Hub；BLADE_OS_PATH → Blade OS 集成（加注释区分 PATH vs BASE_URL）
5
LLM 拆出"高级配置"子区块
LLM_BACKEND、DROP_PARAMS、AGENT_MAX_TURNS、COMPACTION_RATIO、TOOL_RESULT_IMAGE_MODE、SSL_VERIFY + 快速模型
6
删除过于冷门的变量
BLADE_ENFORCE_NO_SPACE_PATHS、BROWSER_EXTENSION_OAUTH_*、PUBLISHED_APP_RECONCILE_INTERVAL_SECONDS、部署/运维区块（已在 observability 模板中）