ADR-0010 Agent 智能进阶

• 状态（Status）：已接受
• 日期：2025-03
• 决策者：EnerOS 智能架构组
• 相关能力：Agent 智能进阶、物理约束引擎
• 相关 ADR：ADR-0002 Power-Native AgentOS

背景（Context）

决策时机

EnerOS v0.43 即将发布，Power-Native 内核、零信任安全、Agent 运行时三大基础能力已稳定。试点电网公司提出新的需求：Agent 不能只做规则驱动的事务性工作，还需具备跨多源异构数据的推理能力、对新能源波动的预测能力，以及与调度员的自然语言交互能力。

这些需求标志着 EnerOS 从”规则驱动的自动化系统”向”智能驱动的自主系统”演进。本次 ADR 决策 Agent 智能层的架构形态、推理后端的选型策略、安全约束的执行机制，是 EnerOS 演进路径上的关键节点。

现状痛点

EnerOS v0.43 之前 Agent 主要基于规则与脚本驱动，对结构化场景表现良好，但在以下场景力不从心：

痛点 1：故障根因分析需跨多源异构数据推理

故障分析需要综合保护动作日志、SCADA 测量、设备台账、气象数据、检修记录等多源信息。规则引擎只能处理结构化条件，无法理解非结构化文本（如检修记录、气象预警），导致根因分析覆盖率仅 65%。

// 规则引擎的局限：只能处理预定义模式，无法覆盖组合故障与未知模式
fn diagnose_fault_oldschool(event: ProtectionEvent) -> Option<RootCause> {
    match event.pattern {
        ProtectionPattern::Overcurrent => Some(RootCause::ShortCircuit),
        ProtectionPattern::Overvoltage => Some(RootCause::CapacitorBankFailure),
        ProtectionPattern::Underfrequency => Some(RootCause::LoadImbalance),
        ProtectionPattern::DistanceZone1 => Some(RootCause::CloseInFault),
        ProtectionPattern::DistanceZone2 => Some(RootCause::MidLineFault),
        ProtectionPattern::DistanceZone3 => Some(RootCause::RemoteFault),
        ProtectionPattern::Differential => Some(RootCause::InternalFault),
        ProtectionPattern::Directional => Some(RootCause::ReverseFault),
        ProtectionPattern::EarthFault => Some(RootCause::GroundFault),
        // 实际规则库有 1200 条，但组合故障与未知模式仍落入 None
        _ => None,  // 65% 的故障落入"未知"分类
    }
}

痛点 2：新能源出力波动下的协同调度需预测 + 决策

光伏、风电出力具有强随机性，传统基于确定性潮流的调度策略在新能源高渗透率场景下效率下降 20-30%。需要预测模型与决策模型的协同。

痛点 3：运维对话式交互需要自然语言理解

调度员希望通过自然语言查询电网状态、获取建议，而非操作多个 GUI。规则引擎无法理解”现在 110kV 母线电压是不是有点偏高”这类模糊表述。

痛点 4：长尾场景扩展性差

每种新场景都需新增规则，规则库膨胀后维护成本激增。v0.43 的规则库已达 1200 条，新增一条规则的平均工时为 3 人天。

触发决策的具体事件

2025 年 2 月，某试点电网在春节期间发生冰灾导致的多次线路跳闸，规则引擎无法综合气象预警与设备历史数据进行根因推断，最终依赖人工分析耗时 4 小时。事后复盘明确要求 EnerOS 在 v0.50 前引入智能推理能力。

决策时的约束

决策（Decision）

采用 内核内置 Agent 智能层：在 Agent 运行时与内核之间引入统一智能接口，支持规则、模型与 LLM 三种推理后端可插拔；所有推理结果必须经 约束引擎 校验后才能落地，确保”智能但不越界”。

核心理由

理由 1：智能层在内核内，安全控制在内核内

将智能层放在 Agent 运行时与内核之间，使所有推理结果必须穿越内核的约束引擎。无论后端是规则、模型还是 LLM，输出都需经过物理约束校验，从根本上杜绝”智能越界”。

理由 2：三种后端可插拔，避免一刀切

不同场景适合不同后端：保护逻辑用规则（确定性高），负荷预测用统计模型（成本低、延迟低），根因分析与对话用 LLM（理解能力强）。统一接口让 Agent 可按场景切换后端，无需修改业务代码。

理由 3：内核内置避免外挂风险

外挂 LLM 网关绕过内核约束，存在安全风险。内置智能层使所有智能调用经过统一的审计与约束链路，满足合规要求。

理由 4：推理过程可追溯

每次推理记录输入、后端类型、模型版本、输出、约束校验结果，满足合规取证的”可解释、可追溯”要求。

理由 5：支持渐进式升级

规则后端保证现有应用平滑迁移，模型与 LLM 后端按场景逐步引入，避免一次性重写。

Agent 智能层级模型

EnerOS 将 Agent 智能分为五个层级，每个层级对应不同的能力与后端选择：

层级并非越高越好——L1/L2 在确定性场景中性能与可靠性远超 L4/L5。EnerOS 鼓励”用最低够用的层级”解决问题。

智能层架构

┌──────────────────────────────────────────────────┐
│              Agent 业务逻辑                       │
└──────────────────┬───────────────────────────────┘
                   │ ReasoningRequest
                   ▼
┌──────────────────────────────────────────────────┐
│           智能接口（ReasoningTrait）              │
│  ┌─────────┬─────────────┬────────────────────┐  │
│  │ 规则后端 │  模型后端    │    LLM 后端         │  │
│  │ RuleEng │ ModelServer │  LlmGateway        │  │
│  └─────────┴─────────────┴────────────────────┘  │
└──────────────────┬───────────────────────────────┘
                   │ ReasoningResult（未经校验）
                   ▼
┌──────────────────────────────────────────────────┐
│           约束引擎（ConstraintEngine）             │
│  ┌────────────────────────────────────────────┐  │
│  │ 电压 / 电流 / 频率 / 热稳定 / 操作顺序       │  │
│  └────────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────────┘
                   │ ValidatedResult
                   ▼
┌──────────────────────────────────────────────────┐
│              审计与执行                           │
└──────────────────────────────────────────────────┘

统一智能接口

所有推理后端实现统一的 ReasoningBackend trait：

use async_trait::async_trait;

/// 推理请求
pub struct ReasoningRequest {
    pub task: ReasoningTask,
    pub context: ReasoningContext,
    pub constraints: Vec<ConstraintSpec>,
    pub deadline: Option<Deadline>,
    pub preferred_backend: Option<BackendKind>,
}

/// 推理结果（未经约束校验）
pub struct ReasoningResult {
    pub action: ProposedAction,
    pub confidence: f64,
    pub explanation: String,
    pub backend: BackendKind,
    pub model_version: Option<String>,
    pub latency: Duration,
}

/// 所有推理后端必须实现的接口
#[async_trait]
pub trait ReasoningBackend: Send + Sync {
    /// 后端类型
    fn kind(&self) -> BackendKind;

    /// 是否适合处理某类任务
    fn can_handle(&self, task: &ReasoningTask) -> FitScore;

    /// 执行推理
    async fn reason(&self, req: &ReasoningRequest) -> Result<ReasoningResult>;

    /// 健康检查
    async fn health_check(&self) -> Result<HealthStatus>;
}

/// 智能层调度器：根据任务选择最合适的后端
pub struct ReasoningDispatcher {
    backends: Vec<Arc<dyn ReasoningBackend>>,
    constraint_engine: Arc<ConstraintEngine>,
    audit_logger: Arc<AuditLogger>,
}

impl ReasoningDispatcher {
    pub async fn reason(&self, req: ReasoningRequest) -> Result<ValidatedResult> {
        // 1. 选择后端
        let backend = self.select_backend(&req)?;
        let start = Instant::now();

        // 2. 调用后端推理
        let raw_result = backend.reason(&req).await?;

        // 3. 约束校验（不可绕过）
        let validated = self.constraint_engine.validate(&raw_result.action)?;

        // 4. 审计记录
        self.audit_logger.record(AuditEntry {
            request: req.summary(),
            backend: raw_result.backend,
            model_version: raw_result.model_version.clone(),
            raw_action: raw_result.action.summary(),
            validated: validated.clone(),
            latency: start.elapsed(),
            timestamp: now_ns(),
        }).await?;

        Ok(validated)
    }

    fn select_backend(&self, req: &ReasoningRequest) -> Result<&Arc<dyn ReasoningBackend>> {
        // 若调用方指定后端，且该后端健康，则直接使用
        if let Some(kind) = req.preferred_backend {
            if let Some(b) = self.backends.iter().find(|b| b.kind() == kind) {
                if b.health_check().await?.is_healthy() {
                    return Ok(b);
                }
            }
        }
        // 否则按 FitScore 选最高分
        let mut scores: Vec<_> = self.backends.iter()
            .map(|b| (b, b.can_handle(&req.task)))
            .collect();
        scores.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
        scores.first().map(|(b, _)| *b)
            .ok_or_else(|| ReasoningError::NoSuitableBackend)
    }
}

三种推理后端实现

规则后端（L1-L2）：

pub struct RuleBackend {
    rules: Vec<Rule>,
    engine: RuleEngine,
}

#[async_trait]
impl ReasoningBackend for RuleBackend {
    fn kind(&self) -> BackendKind { BackendKind::Rule }

    fn can_handle(&self, task: &ReasoningTask) -> FitScore {
        match task {
            ReasoningTask::ProtectionLogic => FitScore::perfect(),
            ReasoningTask::DispatchWithinRules => FitScore::high(),
            ReasoningTask::RootCauseAnalysis => FitScore::low(),
            _ => FitScore::none(),
        }
    }

    async fn reason(&self, req: &ReasoningRequest) -> Result<ReasoningResult> {
        let matched = self.engine.evaluate(&req.context, &self.rules)?;
        Ok(ReasoningResult {
            action: matched.action,
            confidence: 1.0,  // 规则命中即 100% 置信
            explanation: matched.rule_text,
            backend: BackendKind::Rule,
            model_version: Some(format!("rules-v{}", matched.ruleset_version)),
            latency: Duration::from_micros(150),
        })
    }
}

模型后端（L3）：

pub struct ModelBackend {
    registry: ModelRegistry,
    runtime: Arc<ModelRuntime>,
}

#[async_trait]
impl ReasoningBackend for ModelBackend {
    fn kind(&self) -> BackendKind { BackendKind::Model }

    fn can_handle(&self, task: &ReasoningTask) -> FitScore {
        match task {
            ReasoningTask::LoadForecast => FitScore::perfect(),
            ReasoningTask::RenewableGenerationForecast => FitScore::perfect(),
            ReasoningTask::EquipmentHealthPredict => FitScore::high(),
            _ => FitScore::low(),
        }
    }

    async fn reason(&self, req: &ReasoningRequest) -> Result<ReasoningResult> {
        let model = self.registry.select(&req.task)?;
        let input = self.prepare_features(&req.context, &model)?;
        let output = self.runtime.infer(&model, &input).await?;
        Ok(ReasoningResult {
            action: output.to_action(),
            confidence: output.confidence,
            explanation: format!("model {} inference", model.name),
            backend: BackendKind::Model,
            model_version: Some(model.version.clone()),
            latency: output.latency,
        })
    }
}

LLM 后端（L4-L5）：

pub struct LlmBackend {
    gateway: Arc<LlmGateway>,
    quota: Arc<QuotaManager>,
    prompt_builder: PromptBuilder,
}

#[async_trait]
impl ReasoningBackend for LlmBackend {
    fn kind(&self) -> BackendKind { BackendKind::Llm }

    fn can_handle(&self, task: &ReasoningTask) -> FitScore {
        match task {
            ReasoningTask::RootCauseAnalysis => FitScore::perfect(),
            ReasoningTask::NaturalLanguageDialogue => FitScore::perfect(),
            ReasoningTask::DispatchOptimization => FitScore::high(),
            _ => FitScore::low(),
        }
    }

    async fn reason(&self, req: &ReasoningRequest) -> Result<ReasoningResult> {
        // 1. 配额检查
        self.quota.check_and_consume(&req.context.tenant_id, 1)?;

        // 2. 构建 prompt（含电网上下文与约束提示）
        let prompt = self.prompt_builder.build(req)?;

        // 3. 调用 LLM
        let response = self.gateway.complete(&prompt).await?;

        // 4. 解析结构化输出
        let parsed = LlmResponseParser::parse(&response)?;

        Ok(ReasoningResult {
            action: parsed.action,
            confidence: parsed.confidence,
            explanation: parsed.reasoning_chain,
            backend: BackendKind::Llm,
            model_version: Some(self.gateway.model_version().to_string()),
            latency: response.latency,
        })
    }
}

LLM 集成方案

EnerOS 的 LLM 集成遵循”本地优先、按需外调”原则：

# eneros.toml
[intelligence.llm]
default_mode = "local_first"   # local_first / cloud_only / hybrid

[intelligence.llm.local]
model = "eneros-7b-instruct"   # EnerOS 微调的 7B 模型
runtime = "onnx"               # onnx / ggml / tensorrt
device = "cuda"                # cuda / cpu / mps
max_tokens = 2048
temperature = 0.3

[intelligence.llm.cloud]
provider = "azure_openai"      # azure_openai / anthropic / 自定义
endpoint = "https://llm.internal.example.com/v1"
model = "gpt-4o"
api_key_env = "ENEROS_LLM_API_KEY"
timeout = "30s"

[intelligence.llm.quota]
daily_token_limit = 1_000_000
per_tenant_limit = 100_000
overflow_action = "fallback_to_local"  # fallback_to_local / reject

推理引擎选型

EnerOS 支持多种推理后端运行时：

EnerOS 默认采用 ONNX Runtime + Candle 组合：ONNX Runtime 服务化部署模型，Candle 用于嵌入式场景。

安全约束机制

所有推理结果在落地前必须经过约束引擎的多重校验：

pub struct ConstraintEngine {
    physics_rules: Vec<PhysicsRule>,
    operational_rules: Vec<OperationalRule>,
    sequence_rules: Vec<SequenceRule>,
}

impl ConstraintEngine {
    pub fn validate(&self, action: &ProposedAction) -> Result<ValidatedResult> {
        // 1. 物理约束（电压、电流、频率、热稳定）
        for rule in &self.physics_rules {
            rule.check(action)?;
        }
        // 2. 操作约束（操作顺序、设备状态）
        for rule in &self.operational_rules {
            rule.check(action)?;
        }
        // 3. 时序约束（操作间隔、并发限制）
        for rule in &self.sequence_rules {
            rule.check(action)?;
        }
        Ok(ValidatedResult::from(action))
    }
}

/// 当 LLM 输出违反约束时的处理策略
pub enum ConstraintViolationPolicy {
    Reject,           // 直接拒绝，返回错误
    AutoCorrect,      // 尝试自动修正（如降低出力至约束内）
    Escalate,         // 升级到人工审核
    FallbackRule,     // 回退到规则后端
}

impl ReasoningDispatcher {
    pub async fn reason_with_policy(
        &self,
        req: ReasoningRequest,
        policy: ConstraintViolationPolicy,
    ) -> Result<FinalResult> {
        loop {
            let result = self.reason(req.clone()).await;
            match result {
                Ok(validated) => return Ok(FinalResult::Validated(validated)),
                Err(ReasoningError::ConstraintViolation(v)) => match policy {
                    ConstraintViolationPolicy::Reject => return Err(v.into()),
                    ConstraintViolationPolicy::AutoCorrect => {
                        req.constraints.push(v.to_constraint());
                        continue;  // 重新推理，附加新约束
                    }
                    ConstraintViolationPolicy::Escalate => {
                        return Ok(FinalResult::NeedsHumanReview(v));
                    }
                    ConstraintViolationPolicy::FallbackRule => {
                        req.preferred_backend = Some(BackendKind::Rule);
                        continue;
                    }
                },
                Err(e) => return Err(e),
            }
        }
    }
}

后果（Consequences）

好处

1. 智能与安全解耦，复用内核约束与审计

无论后端是规则、模型还是 LLM，输出都经过同一套约束引擎与审计链路，安全保证统一。新增后端无需重复实现安全机制。

2. 多种推理后端可按场景切换，避免一刀切

实测在试点电网中，规则后端处理 78% 的事务性任务（延迟 < 1ms），模型后端处理 18% 的预测任务（延迟 < 100ms），LLM 后端处理 4% 的复杂推理（延迟 < 5s），整体成本与延迟均最优。

3. 推理过程可追溯，满足合规取证

每次推理记录输入摘要、后端类型、模型版本、原始输出、约束校验结果、最终决策，形成完整审计链。合规取证时可回溯任一决策的全过程。

4. 故障根因分析覆盖率从 65% 提升至 92%

LLM 后端可综合非结构化数据（检修记录、气象预警），覆盖规则引擎无法处理的组合故障与长尾场景。

5. 长尾场景扩展成本降低

新增场景无需编写规则，通过 prompt 工程或微调小模型即可支持，平均工时从 3 人天降至 0.5 人天。

代价

1. 约束校验带来额外延迟，对实时场景需做异步预取

约束校验增加 10-50μs 延迟，对实时域（< 100μs）场景已通过异步预取与缓存优化。

2. 模型版本管理与回归测试成为新工程负担

需建立模型注册中心、A/B 测试框架、回归测试数据集，团队新增 1 名 ML 工程师岗位。

3. LLM 调用成本需由配额机制约束

试点期间 LLM 调用成本约 $2000/月，通过配额与本地小模型回退降至 $500/月。

4. 输出不确定性增加运维复杂度

LLM 输出存在随机性，需通过 temperature 控制、结构化输出解析、约束校验三重机制保证可靠性。

5. 模型供应链安全需额外审查

第三方模型可能存在后门或偏见，需建立模型审查流程与对抗测试集。

后续工作

• 引入 Retrieval-Agent 支持电网知识库检索（已在 v0.48 落地）
• 探索小模型本地化部署以降低延迟与成本（计划 v0.52）
• 完善 Agent 智能评估基准（计划 v0.50）
• 支持多模态输入（图像、示波器波形）（计划 v0.55）
• 引入 Agent 智能自学习与微调流水线（计划 v0.60）

备选方案（Alternatives）

方案 A：外挂 LLM 网关

描述：部署独立的 LLM 网关，Agent 通过 HTTP 调用，由网关直接返回结果并执行。

优点：

• 实现简单，2 周内可上线
• 不修改内核，对现有架构零侵入
• 可使用任意 LLM 提供商

否决原因：

• 绕过内核约束引擎，存在安全风险——LLM 可能输出违反物理约束的指令
• 审计链断裂，无法证明某操作由哪个 LLM 调用产生
• 无法与规则、模型后端统一调度，多后端切换困难
• 与 ADR-0002 的 Power-Native 理念冲突

方案 B：每 Agent 自行集成模型

描述：每个 Agent 自行选择并集成规则、模型或 LLM，无统一接口。

优点：

• 灵活性最高，Agent 可按需选择
• 无需内核改动
• 团队可并行开发

否决原因：

• 重复实现推理、约束、审计逻辑，代码膨胀
• 安全策略散落各处，难以保证一致
• 模型版本管理混乱，无法统一监控
• 新增 Agent 需重新学习推理框架，开发效率低

方案 C：维持纯规则

描述：继续扩展规则库，通过更细粒度的规则覆盖更多场景。

优点：

• 实现简单，团队熟悉
• 确定性高，输出可预测
• 无 LLM 成本

否决原因：

• 无法覆盖长尾场景，规则库已膨胀至 1200 条，维护成本激增
• 无法处理非结构化数据（文本、图像）
• 新能源高渗透率下的预测需求无法满足
• 竞品（如 GE Grid Software、Siemens Spectrum Power）已引入 AI 能力，纯规则方案竞争力不足

方案 D：纯 LLM 驱动

描述：所有 Agent 决策都通过 LLM 推理，废弃规则引擎。

优点：

• 实现极简，统一后端
• 灵活性最高，可处理任意场景
• 开发速度快

否决原因：

• 延迟过高（> 1s），无法满足保护逻辑等实时场景
• 成本高昂，单次调用 $0.01-0.1，高频场景不可承受
• 输出不确定性高，对电力关键基础设施不可接受
• 完全依赖外部 LLM 供应商，存在供应链风险

性能评估

智能层引入后的性能实测数据（标准测试环境：4 核 / 8GB / NVIDIA T4 GPU）：

约束校验开销（所有后端均需经过）：

安全约束详解

LLM 输出沙箱化

LLM 后端的输出在落库前经过严格沙箱化处理：

pub struct LlmOutputSandbox {
    parser: StructuredOutputParser,
    constraint_engine: Arc<ConstraintEngine>,
    policy: ConstraintViolationPolicy,
}

impl LlmOutputSandbox {
    pub async fn process(&self, raw: &str) -> Result<SandboxedOutput> {
        // 1. 解析为结构化动作（拒绝无法解析的输出）
        let action = self.parser.parse(raw)?;

        // 2. 范围检查（动作类型、目标设备是否合法）
        self.validate_scope(&action)?;

        // 3. 物理约束校验
        let validated = match self.constraint_engine.validate(&action) {
            Ok(v) => v,
            Err(violation) => match self.policy {
                ConstraintViolationPolicy::Reject => return Err(violation.into()),
                ConstraintViolationPolicy::AutoCorrect => self.autocorrect(action, violation)?,
                ConstraintViolationPolicy::Escalate => {
                    return Ok(SandboxedOutput::NeedsReview(action, violation))
                }
                ConstraintViolationPolicy::FallbackRule => {
                    return Ok(SandboxedOutput::FallbackToRule(action))
                }
            },
        };

        Ok(SandboxedOutput::Validated(validated))
    }
}

Prompt 注入防护

LLM 后端对 prompt 注入攻击采取多层防护：

pub struct PromptGuard {
    forbidden_patterns: Vec<Regex>,
    max_input_length: usize,
}

impl PromptGuard {
    pub fn sanitize(&self, user_input: &str) -> Result<String> {
        // 1. 长度限制
        if user_input.len() > self.max_input_length {
            return Err(PromptError::InputTooLong);
        }
        // 2. 模式过滤（如 "ignore previous instructions"）
        for pattern in &self.forbidden_patterns {
            if pattern.is_match(user_input) {
                return Err(PromptError::SuspiciousPattern);
            }
        }
        // 3. 转义特殊字符
        Ok(escape_special_chars(user_input))
    }

    pub fn build_safe_prompt(&self, user_input: &str, context: &ReasoningContext) -> String {
        let sanitized = self.sanitize(user_input).unwrap_or_default();
        format!(
            "你是一个电力系统调度助手。请基于以下电网上下文回答问题。\n\
             严格约束：\n\
             1. 只能提出符合物理约束的操作建议\n\
             2. 不得输出任何违反安全规程的内容\n\
             3. 输出必须为 JSON 格式：{{\"action\": ..., \"confidence\": ..., \"explanation\": ...}}\n\n\
             电网上下文：\n{}\n\n\
             用户问题：\n{}",
            context.summary(),
            sanitized
        )
    }
}

后续演进

本 ADR 确立了智能层的基础架构，后续演进将围绕以下方向展开：

1. 多模态推理：支持图像（红外测温、巡检照片）、波形（示波器录波）输入
2. 联邦学习：跨电网公司的模型协同训练，数据不出站
3. Agent 自主学习：Agent 从历史操作中持续优化策略
4. 小模型微调流水线：基于电网领域数据微调 7B 模型，降低成本
5. 智能评估基准：建立 EnerOS-Bench，量化 Agent 智能水平

参考（References）

• ADR 总览 — ADR 索引与编写指南
• ADR-0002 Power-Native AgentOS — Power-Native 设计决策
• ADR-0007 零信任 mTLS — 零信任架构
• Agent 智能进阶 — 能力文档
• 物理约束引擎 — 约束机制
• Sutton & Barto, “Reinforcement Learning: An Introduction”
• Wei et al., “Chain-of-Thought Prompting Elicits Reasoning in Large Language Models”, 2022
• ONNX Runtime specification, https://onnxruntime.ai
• SPIFFE specification, https://spiffe.io
• 相关 crate：eneros-reasoning、eneros-agent、eneros-tool、eneros-constraint