特性开关 - Shannon

概述

Shannon 使用特性开关来控制可选功能、实验性功能和企业扩展，无需修改代码。这实现了以下功能的清晰分离：

开源核心功能（所有用户可用）
企业/私有功能（通过开关控制）
实验性功能（可切换以进行测试）

无需重新编译

启用/禁用功能无需重新构建服务

基于环境

开发/预发布/生产环境使用不同的开关配置

清晰分离

企业功能与开源核心隔离

渐进式发布

在全面部署前测试新功能

配置

配置文件

特性开关在 config/shannon.yaml 的 features 部分定义：

# config/shannon.yaml
features:
  # 企业工作流功能
  ads_research: false              # 广告研究工作流（企业版）
  advanced_synthesis: false        # 高级综合模板

  # 实验性功能
  parallel_streaming: true         # 多代理并行流式传输
  enhanced_memory: false           # 增强向量内存

  # 自定义集成
  vendor_tools_enabled: false      # 启用供应商特定工具

环境变量

可通过环境变量覆盖特性开关：

# .env
SHANNON_FEATURE_ADS_RESEARCH=true
SHANNON_FEATURE_PARALLEL_STREAMING=false

命名约定：SHANNON_FEATURE_<开关名称大写>

优先级顺序

环境变量（最高优先级）
配置覆盖层（config/overlays/shannon.{env}.yaml）
基础配置（config/shannon.yaml）
代码默认值（最低优先级）

使用模式

在 Go 代码中（Orchestrator）

package main

import (
    "github.com/Kocoro-lab/Shannon/go/orchestrator/internal/config"
)

func routeWorkflow(ctx context.Context, req *pb.Request) error {
    cfg, _ := config.LoadShannon()

    // 检查特性开关
    if cfg.Features.AdsResearch {
        return routeToAdsResearchWorkflow(ctx, req)
    }

    return routeToStandardWorkflow(ctx, req)
}

在 Python 代码中（LLM Service）

from llm_service.config import load_shannon_config

config = load_shannon_config()

# 检查特性开关
if config.get("features", {}).get("vendor_tools_enabled"):
    from llm_service.tools.vendor import register_vendor_tools
    register_vendor_tools()

条件导入模式

使用特性开关与条件导入实现清晰分离：

# roles/presets.py
_PRESETS = {
    "general": GENERAL_PRESET,
    "research": RESEARCH_PRESET,
}

# 条件加载企业角色
if config.get("features", {}).get("ads_research"):
    try:
        from .enterprise.ads_analyst import ADS_ANALYST_PRESET
        _PRESETS["ads_analyst"] = ADS_ANALYST_PRESET
    except ImportError:
        pass  # 没有企业模块，Shannon 仍可正常工作

常用特性开关

开关名称	类型	描述	默认值
`ads_research`	企业版	带市场分析的广告研究工作流	`false`
`parallel_streaming`	实验性	多代理并行 SSE 流式传输	`true`
`advanced_synthesis`	企业版	自定义综合模板	`false`
`vendor_tools_enabled`	集成	启用供应商特定工具适配器	`false`
`enhanced_memory`	实验性	具有混合搜索的高级向量内存	`false`

最佳实践

1. 默认禁用

新功能应在基础配置中默认为 false：

# config/shannon.yaml
features:
  new_feature: false  # ✅ 安全的默认值

2. 使用环境覆盖层

为不同部署创建特定于环境的覆盖层：

# config/overlays/shannon.production.yaml
features:
  ads_research: true
  parallel_streaming: true
  enhanced_memory: false  # 仍在测试中

加载方式：

SHANNON_CONFIG_PATH=config/overlays/shannon.production.yaml

3. 使用 Try/Except 保护

始终为企业/可选功能使用优雅降级：

if config.features.vendor_tools_enabled:
    try:
        from .vendor import CustomVendorTool
    except ImportError:
        logger.warning("供应商工具不可用，使用标准工具")

4. 记录功能要求

features:
  # 需要：GA4_SERVICE_ACCOUNT_KEY 环境变量
  # 供应商模块：llm_service/tools/vendor_adapters/ga4/
  ga4_integration: false

企业功能模式

Shannon 使用特性开关将开源核心与企业扩展分离：

文件结构

Shannon/
├── config/
│   ├── shannon.yaml                    # 基础配置（开源）
│   └── overlays/
│       └── shannon.enterprise.yaml     # 企业开关
├── go/orchestrator/
│   └── internal/workflows/
│       ├── standard_workflow.go        # 开源工作流
│       └── enterprise/                 # 企业工作流
│           └── ads_research.go         # 由开关控制
└── python/llm-service/
    └── llm_service/
        ├── roles/
        │   ├── presets.py              # 开源角色 + 条件加载
        │   └── enterprise/             # 企业角色
        │       └── ads_analyst.py      # 由开关控制
        └── tools/
            └── vendor_adapters/        # 供应商工具（由开关控制）

条件工作流路由

// orchestrator/internal/workflows/router.go
func SelectWorkflow(ctx context.Context, cfg *config.Shannon, req *pb.Request) Workflow {
    // 检查企业特性开关
    if cfg.Features.AdsResearch && req.Context["workflow_type"] == "ads_research" {
        return NewAdsResearchWorkflow()
    }

    // 回退到开源工作流
    return NewStandardWorkflow()
}

使用特性开关进行测试

单元测试

func TestAdsResearchWorkflow(t *testing.T) {
    cfg := &config.Shannon{
        Features: config.FeatureFlagsConfig{
            AdsResearch: true,  // 为测试启用
        },
    }

    workflow := SelectWorkflow(context.Background(), cfg, testReq)
    assert.IsType(t, &AdsResearchWorkflow{}, workflow)
}

集成测试

# 启用功能运行测试
SHANNON_FEATURE_ADS_RESEARCH=true go test ./...

# 禁用功能运行测试（开源模式）
SHANNON_FEATURE_ADS_RESEARCH=false go test ./...

部署策略

金丝雀部署

为部分用户启用功能：

func isFeatureEnabled(userID string, featureName string) bool {
    // 检查用户特定的特性开关（例如，从数据库）
    if userHasAccess(userID, featureName) {
        return true
    }

    // 回退到全局配置
    return cfg.Features.Get(featureName)
}

A/B 测试

基于特性开关路由流量：

if experimentGroup(userID) == "variant_a" && cfg.Features.EnhancedMemory {
    return useEnhancedMemory(ctx, req)
}
return useStandardMemory(ctx, req)

监控与可观测性

记录特性开关使用情况以便调试：

logger.Info("特性开关检查",
    zap.String("feature", "ads_research"),
    zap.Bool("enabled", cfg.Features.AdsResearch),
    zap.String("user_id", userID),
)

添加指标：

featureFlagGauge.WithLabelValues("ads_research").Set(
    boolToFloat64(cfg.Features.AdsResearch),
)

迁移指南

添加新特性开关

在配置中定义开关

添加到 config/shannon.yaml：

features:
  my_new_feature: false  # 默认禁用

更新 Go 结构

在 go/orchestrator/internal/config/shannon.go 中添加字段：

type FeatureFlagsConfig struct {
    // ... 现有开关
    MyNewFeature bool `json:"my_new_feature" yaml:"my_new_feature"`
}

在代码中使用

控制功能：

if cfg.Features.MyNewFeature {
    return newFeatureBehavior()
}
return existingBehavior()

添加测试

测试启用/禁用两种状态：

func TestMyNewFeature_Enabled(t *testing.T) { /* ... */ }
func TestMyNewFeature_Disabled(t *testing.T) { /* ... */ }

更新文档

更新本页和环境变量文档。

环境变量

完整的配置选项列表

供应商适配器

构建供应商特定集成

配置指南

Shannon 配置概述

扩展 Shannon

添加自定义功能和工作流

Documentation Index

​概述

无需重新编译

基于环境

清晰分离

渐进式发布

​配置

​配置文件

​环境变量

​优先级顺序

​使用模式

​在 Go 代码中（Orchestrator）

​在 Python 代码中（LLM Service）

​条件导入模式

​常用特性开关

​最佳实践

​1. 默认禁用

​2. 使用环境覆盖层

​3. 使用 Try/Except 保护

​4. 记录功能要求

​企业功能模式

​文件结构

​条件工作流路由

​使用特性开关进行测试

​单元测试

​集成测试

​部署策略

​金丝雀部署

​A/B 测试

​监控与可观测性

​迁移指南

​添加新特性开关

​相关文档

环境变量

供应商适配器

配置指南

扩展 Shannon

概述

配置

配置文件

环境变量

优先级顺序

使用模式

在 Go 代码中（Orchestrator）

在 Python 代码中（LLM Service）

条件导入模式

常用特性开关

最佳实践

1. 默认禁用

2. 使用环境覆盖层

3. 使用 Try/Except 保护

4. 记录功能要求

企业功能模式

文件结构

条件工作流路由

使用特性开关进行测试

单元测试

集成测试

部署策略

金丝雀部署

A/B 测试

监控与可观测性

迁移指南

添加新特性开关

相关文档