> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.
# 特性开关
> 使用特性开关配置可选功能和企业扩展
## 概述
Shannon 使用**特性开关**来控制可选功能、实验性功能和企业扩展，无需修改代码。这实现了以下功能的清晰分离：
* **开源核心功能**（所有用户可用）
* **企业/私有功能**（通过开关控制）
* **实验性功能**（可切换以进行测试）
启用/禁用功能无需重新构建服务
开发/预发布/生产环境使用不同的开关配置
企业功能与开源核心隔离
在全面部署前测试新功能
## 配置
### 配置文件
特性开关在 `config/shannon.yaml` 的 `features` 部分定义：
```yaml theme={null}
# config/shannon.yaml
features:
# 企业工作流功能
ads_research: false # 广告研究工作流（企业版）
advanced_synthesis: false # 高级综合模板
# 实验性功能
parallel_streaming: true # 多代理并行流式传输
enhanced_memory: false # 增强向量内存
# 自定义集成
vendor_tools_enabled: false # 启用供应商特定工具
```
### 环境变量
可通过环境变量覆盖特性开关：
```bash theme={null}
# .env
SHANNON_FEATURE_ADS_RESEARCH=true
SHANNON_FEATURE_PARALLEL_STREAMING=false
```
**命名约定**：`SHANNON_FEATURE_<开关名称大写>`
### 优先级顺序
1. **环境变量**（最高优先级）
2. **配置覆盖层**（`config/overlays/shannon.{env}.yaml`）
3. **基础配置**（`config/shannon.yaml`）
4. **代码默认值**（最低优先级）
## 使用模式
### 在 Go 代码中（Orchestrator）
```go theme={null}
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）
```python theme={null}
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()
```
### 条件导入模式
使用特性开关与条件导入实现清晰分离：
```python theme={null}
# 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`：
```yaml theme={null}
# config/shannon.yaml
features:
new_feature: false # ✅ 安全的默认值
```
### 2. 使用环境覆盖层
为不同部署创建特定于环境的覆盖层：
```yaml theme={null}
# config/overlays/shannon.production.yaml
features:
ads_research: true
parallel_streaming: true
enhanced_memory: false # 仍在测试中
```
加载方式：
```bash theme={null}
SHANNON_CONFIG_PATH=config/overlays/shannon.production.yaml
```
### 3. 使用 Try/Except 保护
始终为企业/可选功能使用优雅降级：
```python theme={null}
if config.features.vendor_tools_enabled:
try:
from .vendor import CustomVendorTool
except ImportError:
logger.warning("供应商工具不可用，使用标准工具")
```
### 4. 记录功能要求
```yaml theme={null}
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/ # 供应商工具（由开关控制）
```
### 条件工作流路由
```go theme={null}
// 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()
}
```
## 使用特性开关进行测试
### 单元测试
```go theme={null}
func TestAdsResearchWorkflow(t *testing.T) {
cfg := &config.Shannon{
Features: config.FeatureFlagsConfig{
AdsResearch: true, // 为测试启用
},
}
workflow := SelectWorkflow(context.Background(), cfg, testReq)
assert.IsType(t, &AdsResearchWorkflow{}, workflow)
}
```
### 集成测试
```bash theme={null}
# 启用功能运行测试
SHANNON_FEATURE_ADS_RESEARCH=true go test ./...
# 禁用功能运行测试（开源模式）
SHANNON_FEATURE_ADS_RESEARCH=false go test ./...
```
## 部署策略
### 金丝雀部署
为部分用户启用功能：
```go theme={null}
func isFeatureEnabled(userID string, featureName string) bool {
// 检查用户特定的特性开关（例如，从数据库）
if userHasAccess(userID, featureName) {
return true
}
// 回退到全局配置
return cfg.Features.Get(featureName)
}
```
### A/B 测试
基于特性开关路由流量：
```go theme={null}
if experimentGroup(userID) == "variant_a" && cfg.Features.EnhancedMemory {
return useEnhancedMemory(ctx, req)
}
return useStandardMemory(ctx, req)
```
## 监控与可观测性
记录特性开关使用情况以便调试：
```go theme={null}
logger.Info("特性开关检查",
zap.String("feature", "ads_research"),
zap.Bool("enabled", cfg.Features.AdsResearch),
zap.String("user_id", userID),
)
```
添加指标：
```go theme={null}
featureFlagGauge.WithLabelValues("ads_research").Set(
boolToFloat64(cfg.Features.AdsResearch),
)
```
## 迁移指南
### 添加新特性开关
添加到 `config/shannon.yaml`：
```yaml theme={null}
features:
my_new_feature: false # 默认禁用
```
在 `go/orchestrator/internal/config/shannon.go` 中添加字段：
```go theme={null}
type FeatureFlagsConfig struct {
// ... 现有开关
MyNewFeature bool `json:"my_new_feature" yaml:"my_new_feature"`
}
```
控制功能：
```go theme={null}
if cfg.Features.MyNewFeature {
return newFeatureBehavior()
}
return existingBehavior()
```
测试启用/禁用两种状态：
```go theme={null}
func TestMyNewFeature_Enabled(t *testing.T) { /* ... */ }
func TestMyNewFeature_Disabled(t *testing.T) { /* ... */ }
```
更新本页和环境变量文档。
## 相关文档
完整的配置选项列表
构建供应商特定集成
Shannon 配置概述
添加自定义功能和工作流