diff --git a/brainstorming.md b/brainstorming.md new file mode 100644 index 0000000..5717e0d --- /dev/null +++ b/brainstorming.md @@ -0,0 +1,597 @@ +# VPP AI Platform Architecture Brainstorming + +## 1. Purpose + +This document develops the technical architecture proposed for the virtual power +plant multi-timescale collaborative operations platform. It is intended for +business architects, platform engineers, algorithm teams, control-system +engineers, security teams, and project stakeholders. + +The goal is not to select products or implementation frameworks yet. The +immediate goal is to agree on: + +- The system's major trust and responsibility boundaries. +- The role AI and large language models should play. +- How decisions become approved external actions. +- How the platform should divide work across time and spatial scales. +- Which architecture should be taken into detailed design. + +## 2. Executive Recommendation + +The proposal has a strong business vision, but the platform should not be +implemented literally as five autonomous agents coordinated by a single +all-purpose runtime. + +The recommended direction is: + +1. Use a deterministic, event-driven VPP operating kernel as the operational + foundation. +2. Present work to operators through durable operation and decision cases. +3. Expose a small decision-case lifecycle API to external systems. +4. Treat the five agents as business-facing roles and replaceable contributors, + not as trust boundaries or direct controllers. +5. Allow AI to create, compare, and explain draft decisions, but never to + authorize or directly execute consequential actions. + +In short: + +> The operational domain should remain correct, auditable, and usable when the +> LLM is unavailable. + +## 3. What Is Already Strong + +The proposal establishes several sound principles: + +- It covers the full operational loop from monitoring and planning to execution + feedback and review. +- It explicitly states that AI must not directly control terminal equipment. +- It includes rule validation, simulation, human approval, rollback, and audit. +- It builds on existing business processes, algorithms, data, and resource + access. +- It evaluates success through operational and financial outcomes rather than + model capability alone. +- It recognizes that annual, monthly, day-ahead, intraday, and real-time + decisions require coordination. + +These principles should be preserved as architectural invariants. + +## 4. Architectural Questions in the Current Proposal + +Several aspects need to be resolved before detailed system design begins. + +### 4.1 Agent taxonomy is inconsistent + +The proposal alternates between five agent roles and six business stages. Names +also change between analysis, resource dispatch or organization, transaction +gaming or decision-making, transaction service or user interaction, and load +control or load management. + +If these names become public APIs or independently deployed services, normal +changes in the business model will cause expensive coupling. They are better +treated as product personas or internal capability compositions. + +### 4.2 The LLM appears too foundational + +The diagrams place the Guangming power model at the bottom of the architecture. +This suggests that normal operation depends on LLM availability and behavior. + +Forecasting, flexibility calculation, optimization, rule enforcement, approval, +market submission, and device control must remain available without an LLM. The +LLM should be an advisory and orchestration participant above a deterministic +operating foundation. + +### 4.3 The runtime owns too much + +The proposed Agent Runtime includes workflow orchestration, context +construction, memory, tools, security, and state synchronization. This risks +becoming a platform-wide bottleneck and a single failure domain. + +Workflow durability, operational state, model execution, policy enforcement, +approval authority, and control execution should have separate responsibilities +and contracts. + +### 4.4 Time scales are not separated operationally + +Second-level equipment control and day-ahead reasoning appear in the same +logical workflow. They have different availability, latency, determinism, and +safety requirements. + +Real-time control should live at the site or edge and use prevalidated policies. +Cloud or provincial AI workflows should produce bounded plans and control +envelopes rather than participate in a fast control loop. + +### 4.5 Knowledge and executable rules are conflated + +RAG is useful for retrieving regulations, operating procedures, explanations, +and historical cases. It must not be the authoritative mechanism for enforcing a +market rule, safety limit, or device constraint. + +Consequential rules should be stored as versioned, testable, executable policy +packs. RAG may explain a policy or locate its source, while a deterministic +policy engine enforces it. + +### 4.6 Decision provenance is underspecified + +The architecture needs canonical, versioned representations of forecasts, +constraints, flexibility, plans, approvals, commands, execution receipts, and +settlement outcomes. Without these, simulation, approval, replay, and audit +cannot reliably refer to the same decision. + +### 4.7 Cross-province operation needs a federation boundary + +Cross-province collaboration should not imply a single central platform with +unrestricted access to raw telemetry or terminal control. The exchanged objects +should normally be signed flexibility envelopes, commitments, bids, awards, and +settlement facts. + +## 5. Non-Negotiable Architecture Invariants + +The following invariants should guide all designs: + +- AI cannot approve its own proposal. +- AI cannot directly call a market-submission or device-control endpoint. +- Every consequential action is bound to an immutable artifact digest and a + validity window. +- Approval is invalidated when material evidence, constraints, or the proposed + effect changes. +- Operational decisions retain their input data snapshot, rule version, model + version, solver version, and approvals. +- External effects are idempotent and produce durable receipts. +- The platform supports replay from recorded evidence. +- Degraded operation remains possible without the LLM. +- Edge control remains safe during provincial-platform or wide-area network + outages. +- Operational truth is stored in authoritative domain stores, not in agent + memory. + +## 6. Three Architecture Alternatives + +The following alternatives are intentionally different rather than variations of +the same agent-runtime design. + +### 6.1 Alternative A: Minimal Decision Platform + +This design exposes only three lifecycle operations: + +```ts +interface VppDecisionPlatform { + start(request: DecisionRequest): Promise; + act(action: CaseAction): Promise; + observe(query: CaseQuery): Promise; +} +``` + +Human requests, scheduled jobs, and operational events all create a versioned +decision case. The caller never selects an agent, prompt, model, skill, or +solver. + +A day-ahead planning case may produce: + +- Load, renewable-generation, and market-price forecasts. +- A resource portfolio and flexibility envelope. +- Candidate market bids. +- A customer response plan. +- A dispatch envelope. +- Rule and simulation results. +- Separate approval gates for market submission, outreach, and dispatch. + +An authorized user approves an exact proposal version and digest. Approval does +not grant the AI direct access to an external system; it allows a guarded +adapter to process the authorized effect. + +This design hides orchestration, retries, agent topology, model selection, tool +invocation, and integration protocols very effectively. Its main risk is that +`DecisionCase` and the service behind it become generic containers with +insufficient domain boundaries. + +### 6.2 Alternative B: Event-Driven VPP Operating Kernel + +This design makes the deterministic operational domain the foundation and treats +AI as a replaceable adapter. + +Representative ports are: + +```ts +interface ObservationIngestPort { + record(observation: Observation): Promise; +} + +interface CommandPort { + execute(command: DomainCommand): Promise; +} + +interface ControlAuthorityPort { + authorize( + plan: CandidatePlan, + simulation: SimulationResult, + approvals: Approval[], + ): Promise; +} + +interface ControlGateway { + dispatch(permit: ExecutionPermit): Promise; +} +``` + +The core invariant is: + +> Evidence can trigger decisions; decisions can propose effects; only the +> authority plane can authorize effects. + +For a demand-response operation, the system records the request as evidence, +calculates a forecast and flexibility envelope, creates candidate plans, runs +safety simulation, collects approval, and requests an execution permit. The +control gateway accepts a permit, not a raw plan. + +This alternative offers the strongest replayability, auditability, safety +isolation, and AI replaceability. Its cost is conceptual complexity: teams must +handle commands, observations, events, idempotency, revisions, projections, and +eventual consistency correctly. + +### 6.3 Alternative C: Operations Case Desk + +This design optimizes the product around the operator's unit of accountability: +a bounded operational case. + +Examples include: + +- Prepare tomorrow's market bid. +- Deliver a 20 MW demand-response event. +- Resolve an execution deviation. +- Review a completed dispatch. + +The operator-facing interface is: + +```ts +interface OperationsDesk { + open(kind: CaseKind, input: CaseInput): Promise; + read(caseId: CaseId): Promise; + apply(command: CaseCommand): Promise; + watch(caseId: CaseId): AsyncIterable; +} +``` + +Each case contains its objective, owner, horizon, evidence, assumptions, +scenario branches, recommendations, approvals, execution receipts, and outcome. +An advanced operator can fork a high-price or low-solar scenario without +directly invoking an agent. + +This design produces the strongest operator experience and naturally organizes +audit and collaboration. Its principal risk is turning a case into a permanent +collection of unrelated activity. Each case therefore needs one accountable +objective, an explicit deadline, an owner, and a completion contract. + +## 7. Comparison and Recommended Hybrid + +The Minimal Decision Platform has the smallest learning and misuse surface for +external callers. It is a deep interface, but its simplicity can conceal an +overly centralized implementation. + +The Event-Driven Operating Kernel is the strongest internal architecture for a +safety-sensitive and heavily audited system. It makes evidence, authority, and +external effects explicit. It is less convenient as the operator's primary +mental model. + +The Operations Case Desk best matches how business users collaborate and accept +responsibility for decisions. It is not, by itself, sufficient as the low-level +operating and control architecture. + +The recommended hybrid is therefore: + +- Event-driven deterministic kernel inside. +- Operations Case Desk for operators. +- Minimal decision-case API for external systems. + +The layers complement one another instead of duplicating responsibilities. + +## 8. Recommended Logical Architecture + +```mermaid +flowchart TB + T[Operators / Schedules / Operational Events] --> C[Operations Case Desk and Decision API] + C --> P[Durable Process Manager and Decision Ledger] + + P --> F[Forecasting Services] + P --> R[Flexibility and Resource Portfolio Services] + P --> M[Market and Dispatch Optimization] + P --> U[Customer Response Planning] + P --> S[Settlement and Review] + + A[LLM Advisor and Agent Roles] --> P + A --> F + A --> R + A --> M + A --> U + + F --> G[Policy Validation] + R --> G + M --> G + U --> G + + G --> V[Simulation and Fresh-State Verification] + V --> H[Human Approval] + H --> E[Execution Authority] + E --> X[Market / Messaging / Control Gateways] + X --> D[Site and Edge Controllers] + D --> O[Execution Observations] + O --> P +``` + +### 8.1 Experience plane + +The experience plane provides the operations desk, dashboards, AI-assisted +investigation, scenario comparison, approval inbox, and operational reports. +Pages are projections over cases and the decision ledger rather than independent +workflow silos. + +### 8.2 Orchestration plane + +The orchestration plane owns durable process state, deadlines, retries, +compensation, correlation, and case progression. It invokes domain capabilities +but does not perform forecasting, optimization, authorization, or control +itself. + +### 8.3 Decision-services plane + +Domain services provide deterministic or bounded capabilities: + +- Load, generation, and price forecasting. +- Resource capability and flexibility assessment. +- Portfolio aggregation and commitment management. +- Market bidding and dispatch optimization. +- Customer segmentation and response planning. +- Simulation, deviation analysis, settlement, and attribution. + +These services accept complete, versioned inputs and return typed artifacts with +provenance. + +### 8.4 AI advisory plane + +The AI layer provides intent understanding, task decomposition, retrieval, +explanation, report generation, tool selection, and candidate strategy +generation. The five proposed agents can exist here as business-specific +contributors. + +There should be no `executeDeviceCommand` or unrestricted `submitMarketBid` tool +available to an agent. + +### 8.5 Authority and execution plane + +This plane enforces executable policies, separation of duties, approval +requirements, current-state verification, permit expiry, and effect limits. It +is the only route to market, messaging, and control gateways. + +### 8.6 Evidence and data plane + +This plane records raw observations, normalized telemetry, business events, +reference data, feature values, forecasts, model outputs, decisions, and +execution outcomes. It supports point-in-time reconstruction and replay. + +## 9. Decision and Execution Lifecycle + +A consequential artifact should follow an explicit lifecycle: + +```text +DRAFT + -> VALIDATED + -> SIMULATED + -> APPROVED + -> AUTHORIZED + -> ISSUED + -> ACKNOWLEDGED + -> COMPLETED / FAILED / ROLLED_BACK +``` + +The LLM may create or explain a `DRAFT`. It cannot advance an artifact to +`AUTHORIZED`. + +Approval should bind to: + +- The exact artifact digest. +- The approved effect scope. +- Financial and quantity limits. +- A validity window. +- The approver's identity and role. +- The evidence and policy versions used for evaluation. + +If material telemetry, constraints, rules, or proposed effects change, the +approval becomes stale. + +## 10. Separation by Time Scale + +### Seconds + +Site and edge controllers own equipment protection, local interlocks, fast +feedback control, and prevalidated fallback behavior. There is no LLM dependency +in this loop. + +### One to fifteen minutes + +Streaming services perform telemetry processing, state estimation, deviation +detection, rolling forecasts, and bounded corrective optimization. Any automatic +response must be preauthorized and constrained. + +### Intraday and day-ahead + +The provincial platform performs market analysis, portfolio planning, scenario +comparison, operator review, and approval. This is the main operating range for +AI-assisted decision workflows. + +### Monthly and annual + +Planning services support contract strategy, resource acquisition, capacity +planning, model training, policy analysis, and long-horizon simulation. + +## 11. Separation by Spatial Scale + +### Device and site + +The site retains device protocols, protection constraints, local control, and +detailed telemetry. It exposes a controlled resource capability interface +upward. + +### Aggregation unit + +The aggregation layer calculates site or resource-group flexibility envelopes, +manages local commitments, and translates bounded dispatch envelopes into site +plans. + +### Provincial platform + +The provincial layer manages portfolios, markets, operator decisions, approval, +reporting, and province-wide optimization. + +### Cross-province federation + +Federated platforms should exchange signed and versioned business artifacts such +as: + +- Flexibility envelopes. +- Available capacity and reserve. +- Commitments and constraints. +- Bids and awards. +- Delivery and settlement facts. + +Raw device control authority and unrestricted customer-level telemetry should +not cross this boundary by default. + +## 12. Canonical Domain Contracts + +Before selecting implementation frameworks, the project should define and +version the following objects: + +- `Resource` +- `ResourceCapability` +- `Portfolio` +- `Commitment` +- `FlexibilityEnvelope` +- `ForecastBundle` +- `MarketOpportunity` +- `DecisionCase` +- `CandidatePlan` +- `ConstraintSet` +- `ValidationResult` +- `SimulationResult` +- `Approval` +- `ExecutionPermit` +- `DispatchOrder` +- `ExecutionReceipt` +- `Settlement` +- `PolicyPack` + +Every material plan should contain: + +- Its validity window. +- The input-data snapshot or evidence references. +- Market-rule and policy versions. +- Model and solver versions. +- Objectives and constraints. +- Uncertainty and confidence information. +- Expected physical and financial effects. +- An immutable digest. +- Current validation and approval state. + +## 13. Data, Knowledge, Rules, and Memory + +These four concepts should remain distinct. + +### Operational data + +Telemetry, market facts, commitments, user responses, and execution observations +are authoritative domain data. They require quality indicators, timestamps, +lineage, retention, and access controls. + +### Knowledge + +Regulations, procedures, manuals, historical reports, and operating experience +can be indexed for retrieval and explanation. Retrieved content is evidence for +a user or model, not automatically an executable rule. + +### Rules + +Market rules, approval rules, equipment constraints, financial limits, and +security policies should be versioned, executable, testable, and auditable. + +### Memory + +Agent memory should contain convenience context and curated lessons, not +authoritative operational state. Feedback should enter a controlled evaluation +and promotion process before it changes a model, policy, or operating template. + +## 14. Reliability and Security Considerations + +The detailed design should account for: + +- Idempotent handling of repeated events, approvals, submissions, and commands. +- Optimistic concurrency to reject stale approvals and conflicting actions. +- Late, missing, duplicated, or low-quality telemetry. +- Model and solver timeouts with deterministic fallbacks. +- Network partition between provincial and site systems. +- Partial device acceptance and compensating dispatch. +- Permit expiry and revocation. +- Segregation of operator, approver, and administrator duties. +- Field-level authorization for customer, market, and infrastructure-sensitive + data. +- Immutable audit records and tamper evidence. +- Tenant, portfolio, site, and provincial data boundaries. +- Observability for every decision and external effect. + +## 15. Recommended First Vertical Slice + +The first implementation should be one complete operational flow rather than +five partially connected agents: + +> Day-ahead portfolio plan -> forecast -> flexibility assessment -> candidate +> bids -> simulation -> operator approval -> simulated market submission -> +> execution replay -> settlement review. + +The slice should initially run in shadow mode using historical and live data +without producing real external effects. It should prove: + +- Canonical domain contracts. +- Evidence and decision lineage. +- Durable orchestration and case state. +- Rule and model versioning. +- Scenario comparison. +- Approval bound to immutable artifacts. +- External-effect simulation and receipts. +- Replay and outcome attribution. +- Operation without the LLM. + +Once this foundation works, the proposed analysis, resource, trading, +customer-interaction, and load-management agents can be introduced as +contributors to the same case lifecycle. + +## 16. Decisions Required Next + +The following decisions materially affect the detailed architecture: + +1. Is the new platform an AI overlay on the existing 3060 platform, a gradual + replacement, or a separate system of engagement? +2. Which existing system remains the source of truth for resources, customers, + market positions, dispatch instructions, and settlement? +3. Is the first release recommendation-only, capable of controlled market + submission, or capable of controlled dispatch? +4. Which actions may eventually become automatically authorized within + predefined limits? +5. Which functions and data must remain at the site, provincial, or dedicated + security zone? +6. What protocols and latency guarantees currently exist between the provincial + platform, aggregation units, and edge terminals? +7. Which province-specific rules must become executable policy packs in the + first release? +8. What is the acceptable behavior when forecasts, telemetry, the LLM, an + optimizer, or a downstream system is unavailable? + +## 17. Suggested Next Architecture Work + +After the decisions above are answered, the next design artifacts should be: + +1. A system-context diagram showing existing systems and ownership boundaries. +2. A source-of-truth matrix for all major domain entities. +3. A canonical domain vocabulary and schema definitions. +4. A detailed day-ahead decision-case sequence. +5. A dispatch authority and execution threat model. +6. A latency, availability, recovery, and data-retention requirements matrix. +7. A deployment-zone and cross-province federation design. +8. An incremental roadmap built from end-to-end vertical slices. diff --git a/docs/00-overview.md b/docs/00-overview.md index e553ab7..52acfe0 100644 --- a/docs/00-overview.md +++ b/docs/00-overview.md @@ -98,8 +98,11 @@ flowchart TB | `SituationReport` 态势报告 | 运行状态、异常、风险研判 | 智能分析 → 全体 | | `ResourceProfile` 资源画像 | 容量、约束、可调潜力、可靠性评分 | 资源调度 → 交易博弈 / 负荷控制 | | `PositionLedger` 持仓账本 | 各时间尺度的持仓与约束级联 | 交易博弈 ↔ Runtime（共享账本） | -| `Proposal` 建议 | 一切拟执行动作的载体（申报、邀约、控制计划） | 各 Agent → 可信执行链 | -| `Envelope` 运行包络 | 人工预批准的自治边界 | 人工审批 → 可信执行链 | +| `Proposal` 建议 | 一切拟执行动作的载体（申报、邀约、控制计划），带不可变摘要 | 各 Agent → 可信执行链 | +| `Envelope` 运行包络 | 人工预批准的自治边界（授权，向下） | 人工审批 → 可信执行链 | +| `FlexibilityEnvelope` 灵活性包络 | 资源/聚合单元的可调能力（能力，向上；省间交换的核心工件） | 资源调度 → 交易博弈 / 省间联邦 | +| `ExecutionPermit` 执行许可 | 现势复核后签发的短时效执行凭证，网关只认许可 | 授权环节 → 网关 | +| `DecisionCase` 运营工单 | 运营人员的问责单元，聚合一件事的证据/建议/审批/结果 | 触发源 → 运营工单台 | | `ExecutionReport` 执行报告 | 指令执行结果与偏差 | 控制平面 → 偏差复盘 | | `ReviewFinding` 复盘结论 | 结构化经验教训，回写记忆与策略库 | 复盘流程 → Runtime 记忆 | @@ -114,4 +117,6 @@ flowchart TB | 05-skills-and-data | 专业模型工具契约、数据分层存储 | 2.3 建设内容 02/03 | | 06-integration | 外部系统接口边界 | 2.1 业务系统 | | 07-scenario-walkthrough | 日前现货申报端到端场景 | 全部（验证用） | -| 08-implementation | Mastra 映射、LLM 抽象层、部署形态 | 2.5 基础条件 | +| 08-implementation | Mastra 映射、LLM 抽象层、部署形态、影子运行 | 2.5 基础条件 | +| 09-runtime-implementation | Runtime 实现设计（Mastra 落地细节） | 2.3 建设内容 05 | +| 10-federation | 省间协同联邦边界 | 3.3 二期推广 | diff --git a/docs/01-principles.md b/docs/01-principles.md index 8b62702..ca01553 100644 --- a/docs/01-principles.md +++ b/docs/01-principles.md @@ -70,6 +70,25 @@ --- +## 硬性不变式（Invariants） + +原则是设计导向，以下不变式是**可测试的硬约束**——违反任何一条即为缺陷， +每条都应有对应的自动化测试或审计检查： + +| # | 不变式 | 落点 | +|---|---|---| +| I1 | AI 不得批准自己的建议；审批人身份与发起链路强制分离 | 03 篇状态机权限校验 | +| I2 | 操作、审批、管理三类职责在权限体系中分离（separation of duties） | 06 篇权限对接 | +| I3 | 审批绑定 Proposal 的不可变摘要（digest）与有效窗口；实质证据、约束或预期效果变化后审批自动失效 | 03 篇审批绑定 | +| I4 | 任何外部效果（申报/控制）只凭执行许可（ExecutionPermit）受理，许可有时效、可吊销 | 03 篇授权环节、04 篇网关 | +| I5 | 外部效果幂等（重发不重执行）并产生持久回执 | 04/06 篇适配器与执行引擎 | +| I6 | LLM 不可用时系统降级可运行：预测、优化、校核、审批、申报、控制全链路不依赖 LLM 存活 | P1/P2 的运行时验证 | +| I7 | 任何历史决策可从留存证据完整重放（输入快照 + 规则版本 + 模型/求解器版本 + 审批记录） | P5、05 篇快照机制 | +| I8 | 运营事实的权威存储是领域数据库，不是智能体记忆 | 02 篇记忆体系 | + +> 注：本节不变式与另一份独立评审（brainstorming.md）的结论互相印证—— +> 两份独立设计收敛于同一组约束，是架构方向正确性的有力佐证。 + ## 原则间的张力与取舍备忘 | 张力 | 取舍 | diff --git a/docs/02-cognitive-plane.md b/docs/02-cognitive-plane.md index 0a38986..f853a35 100644 --- a/docs/02-cognitive-plane.md +++ b/docs/02-cognitive-plane.md @@ -105,8 +105,33 @@ D+1 结算数据到达 复盘本质是分析任务，其结论的权威数据源是持仓账本与事件日志（P5/P7）， 单独设 Agent 会造成与分析 Agent 的职责重叠。 -## 5. 人机交互面 +## 5. 人机交互面：运营工单台（Case Desk） -- 自由文本只存在于「人 ↔ 平台」界面：智能问答、专题分析、报告生成（AI 交互与分析引擎） -- 业务页面嵌入 AI 结论卡片，卡片与页面双向联动（点卡片定位数据，选数据追问 AI） -- 每张 AI 卡片必须可展开血缘：结论 → 引用的工具输出 → 数据来源（P5 在 UI 层的体现） +运营人员的工作单元不是「某个 Agent 的输出」，而是**运营工单（DecisionCase）**—— +一件有明确目标、责任人、期限和完结条件的业务事项： + +```yaml +DecisionCase: + kind: DAY_AHEAD_BID | DR_EVENT | DEVIATION_RESOLUTION | REVIEW | ... + objective: "完成 D 日现货申报" # 一单一目标，禁止杂物箱化 + owner: string # 责任人（问责单元） + deadline: ts # 期限（如申报截止） + contents: # 工单聚合的全部工作产物（引用，非复制） + evidence: [...] # 态势报告、预测、画像快照 + proposals: [...] # 关联 Proposal 及其状态 + approvals / permits: [...] + scenarios: [...] # 情景分支（高价情景、低光伏情景的对比测算） + outcome: ... # 执行回执与复盘结论（完结条件） +``` + +- 工单由三类触发源随流程模板**自动开单**（周期申报单、事件偏差单），人工也可开专题单； +- 审批收件箱、看板、报告都是工单与账本/事件日志之上的**投影**，不是独立功能烟囱； +- 运营人员可在工单内叉分情景（「如果明日出现高价时段？」）——由 Agent 重跑测算工具 + 生成对比分支，但不产生新 Proposal，纯分析用途； +- 自由文本只存在于「人 ↔ 平台」界面：智能问答、专题分析、报告生成，均挂在工单上下文内； +- 业务页面嵌入 AI 结论卡片，卡片与页面双向联动；每张卡片可展开血缘： + 结论 → 引用的工具输出 → 数据来源（P5 在 UI 层的体现）。 + +**工单 vs 工作流**：工作流（Runtime 内部）是机器的执行单元，工单是人的问责单元； +一张工单通常聚合多条工作流的产物（申报单 = 态势流程 + 画像流程 + 申报流程 + 生命周期流程）。 +两者通过 case_id 关联，禁止互相替代。 diff --git a/docs/03-safety-chain.md b/docs/03-safety-chain.md index b02fbd3..0106631 100644 --- a/docs/03-safety-chain.md +++ b/docs/03-safety-chain.md @@ -23,6 +23,7 @@ Proposal: data_refs: [string] # 引用的数据快照 ledger_version: string # 读取的持仓账本版本 envelope_ref: string | null # 命中的包络（null = 必走人工） + digest: string # 载荷 + 血缘的不可变内容摘要（审批与许可的绑定对象） status: <状态机，见 §2> audit: [...] # 状态迁移全记录：时间、执行者(系统/人)、依据 ``` @@ -43,8 +44,12 @@ stateDiagram-v2 ENVELOPE_CHECK --> PENDING_HUMAN: 包络外 / 无包络 PENDING_HUMAN --> APPROVED: 人工批准（可多级） PENDING_HUMAN --> REJECTED: 人工驳回 - AUTO_APPROVED --> RELEASED: 下发 - APPROVED --> RELEASED: 下发 + AUTO_APPROVED --> FRESH_CHECK: 执行前现势复核 + APPROVED --> FRESH_CHECK: 执行前现势复核 + FRESH_CHECK --> AUTHORIZED: 复核通过，签发 ExecutionPermit + FRESH_CHECK --> STALE: 实质状态已变化，审批失效 + STALE --> RULE_CHECK: 重新走链（视变化幅度沿用或重批） + AUTHORIZED --> RELEASED: 网关凭许可受理 RELEASED --> EXECUTING: 控制平面 / 外部接口受理 EXECUTING --> COMPLETED: 执行完成，反馈回传 EXECUTING --> ROLLED_BACK: 异常触发回退 @@ -57,8 +62,49 @@ stateDiagram-v2 - **规则校核**（确定性规则引擎）：合规性（交易规则、申报格式）、约束校验（资源约束、合同边界、账本一致性）、权限校验（发起 Agent 是否有权发起该类型）、血缘完整性； - **仿真验证**：按类型选择——申报类走收益/风险情景回测，控制类走功率平衡/潮流仿真；仿真告警**一票升级**人工，没有例外； +- **权限校验**（规则校核内含，落实 I1/I2）：审批人不得出现在该 Proposal 的发起链路中；AI 无任何通往「批准」迁移的路径； - **实现形态**：持久化工作流（durable workflow）。审批可能悬挂数小时，状态机必须可恢复、超时可配（如申报截止前 30 分钟未批自动升级告警）。 +### 2.1 审批绑定与失效（Staleness，落实 I3） + +审批的对象不是「这个 Proposal」，而是「**这个摘要版本**的 Proposal 在**这个窗口内**生效」： + +```yaml +Approval: + proposal_digest: string # 绑定不可变摘要——载荷任何改动即另一次审批 + approver: {id, role} # 来自既有权限系统（I2 职责分离） + scope: {effect_type, limits} # 批准的效果范围与金额/电量上限 + validity: {from, to} # 有效窗口 + evidence_versions: # 审批时所依据的证据版本 + policy_pack: string + ledger_version: string + data_snapshot_refs: [...] +``` + +**失效条件**：有效窗口过期；或依据的实质证据发生变化（引用资源离线、账本持仓变动、 +政策包升版、遥测显著偏离审批时快照）。失效检测由执行前**现势复核（FRESH_CHECK）**承担。 + +### 2.2 授权与执行许可（AUTHORIZED / ExecutionPermit，落实 I4） + +人工/自动批准 ≠ 可以执行。批准与执行之间可能相隔数小时，物理世界会变。 +下发前由授权环节做**现势复核**：重跑关键校验（资源在线、约束仍满足、审批未失效）， +通过后签发执行许可： + +```yaml +ExecutionPermit: + proposal_digest: string # 与批准的摘要一致 + issued_at / expires_at: ts # 短时效（如控制类分钟级、申报类至截止时刻） + effect_limits: {...} # 从 Approval.scope 继承收窄 + revocable: true # 可吊销（吊销 = 网关拒收 + 边缘回退策略） +``` + +**网关只认许可，不认计划**：交易平台适配器与执行引擎的受理入口只接受 +`(Proposal, ExecutionPermit)` 且验证摘要一致、许可未过期未吊销。 +即使一个已批准的计划被泄露或重放，没有有效许可也无法产生外部效果。 + +*典型场景*：08:30 申报获批 → 09:00 某 10 MW 储能站离线 → 09:30 适配器请求许可 +→ 现势复核发现核定容量已失效 → STALE，回到规则校核重走（容量核减后的新摘要需重批或落在包络内自动通过）。 + ## 3. 包络（Envelope）模型 ```yaml @@ -93,6 +139,8 @@ Envelope: ## 4. 异常回退 +- **许可吊销**是最高优先级的回退手段：吊销后网关立即拒收后续指令， + 边缘终端按断连策略退回上一批准计划或安全曲线（04 篇 §3）； - 执行中任何环节异常（校核失败、执行偏差超阈、通道故障）→ 回退至 Runtime 安全控制： 控制类回退到上一批准计划或安全停机曲线（边缘终端本地持有，见 04 篇）； 申报类在截止前可撤单重报，截止后转入偏差管理流程。 diff --git a/docs/04-control-plane.md b/docs/04-control-plane.md index 7768a16..4459738 100644 --- a/docs/04-control-plane.md +++ b/docs/04-control-plane.md @@ -19,7 +19,8 @@ | 设备 | 设定值执行 | 秒级 | 设备保护自主 | **分解原则**：省级只下发到聚合单元粒度的**目标 + 包络**，单元内的设备级分配由聚合层 -本地完成。省级不做设备级微观管理——既降低通信与时延要求，也符合「分区隔离」安全要求。 +本地完成；聚合单元向上以 `FlexibilityEnvelope`（灵活性包络）上报可调能力—— +该工件与省间联邦交换用同一 schema（10 篇）。省级不做设备级微观管理——既降低通信与时延要求，也符合「分区隔离」安全要求。 ## 2. 执行引擎（省级） diff --git a/docs/05-skills-and-data.md b/docs/05-skills-and-data.md index 72da07a..0a33bc9 100644 --- a/docs/05-skills-and-data.md +++ b/docs/05-skills-and-data.md @@ -70,11 +70,32 @@ flowchart LR - **快照与引用**：Proposal 血缘引用的数据是不可变快照（按版本/时间戳），保证任何历史决策可复现； - **脱敏分级**：用户行为数据按敏感级分级，跨区流动（如上送省级）经脱敏策略。 -## 4. 知识库运营（容易被低估的持续成本） +## 4. 政策包（Policy Pack）与知识库运营 -规则库不是一次性建设：交易规则年年修订、政策频繁更新。设计上： +**知识（可检索）与规则（可执行）严格分开**：RAG 用于解释规则、定位出处、支撑问答； +任何有后果的校核（市场规则、安全限值、设备约束、财务上限）由**政策包**强制执行。 + +### 4.1 政策包 + +规则校核引擎的规则不是散落的代码，而是**版本化、可测试、可部署的政策包**： + +```yaml +PolicyPack: + id: hubei-spot-bidding + version: 2026.03 # 随规则修订升版，旧版本保留（历史决策重放需要，I7） + effective: {from, to} + rules: [...] # 可执行规则（申报格式、价格限值、持仓偏差带…） + tests: [...] # 每条规则附正/反用例，升版必须全绿 + source_refs: [...] # 指向知识库原文条目（可解释性：规则 → 出处） +``` + +- Proposal 血缘固化**政策包版本**（03 篇 `evidence_versions.policy_pack`）—— + 「当时按哪版规则校核的」永远可查、可重放； +- 政策包升版触发影响分析工作流：扫描悬挂中/包络内的存量 Proposal，标记需重校核者。 + +### 4.2 知识库运营（容易被低估的持续成本） - 知识条目带**生效期与版本**，RAG 检索默认过滤失效条目； -- 规则校核引擎中的硬规则与知识库中的文本规则**双轨维护**， - 文本规则变更触发硬规则同步评审的工作流（避免「文档更新了、校核引擎还是旧规则」）； -- 每次申报被交易平台驳回的原因，强制回流为知识条目候选（复盘流程的一部分）。 +- 知识条目（文本规则）变更触发对应政策包同步评审的工作流 + （避免「文档更新了、校核引擎还是旧规则」的双轨漂移）； +- 每次申报被交易平台驳回的原因，强制回流为知识条目候选 + 政策包规则候选（复盘流程的一部分）。 diff --git a/docs/07-scenario-walkthrough.md b/docs/07-scenario-walkthrough.md index 403c515..9655a52 100644 --- a/docs/07-scenario-walkthrough.md +++ b/docs/07-scenario-walkthrough.md @@ -38,8 +38,10 @@ D 日执行与监测，D+1 复盘。 1. **规则校核**：申报格式 ✓、价格限值 ✓、账本一致性 ✓、血缘完整性 ✓； 2. **仿真验证**：收益情景回测——千组价格情景，极端亏损在容忍带内 ✓； 3. **包络检查**：本日申报曲线落在已批准的申报包络内（价格偏离预测基准 < 容差、电量在持仓偏差带内）→ `AUTO_APPROVED`； - - *对照分支*：若明日有极端天气、优化结果越出包络 → `PENDING_HUMAN`，交易员在审批界面看到申报说明 + 血缘展开 + 仿真结果，批准/修改/驳回； -4. `RELEASED` → 交易平台适配器提交申报；回执写入事件日志。 + - *对照分支*：若明日有极端天气、优化结果越出包络 → `PENDING_HUMAN`，交易员在工单台看到申报说明 + 血缘展开 + 仿真结果，批准/修改/驳回； +4. 提交前**现势复核**：重验资源在线与账本一致 → 签发 `ExecutionPermit` → `AUTHORIZED`； + - *对照分支*：若批准后某储能站离线 → `STALE`，容量核减后重走校核（03 篇 §2.2）； +5. `RELEASED` → 交易平台适配器凭许可提交申报；回执写入事件日志。 *验证构件：状态机全路径、包络自治、降级路径（若接口故障 → 导出文件人工上传）。* diff --git a/docs/08-implementation.md b/docs/08-implementation.md index be35365..87b9277 100644 --- a/docs/08-implementation.md +++ b/docs/08-implementation.md @@ -24,7 +24,8 @@ | 意图解析 | 路由 Agent → 选择 Workflow 模板并填参 | **需自建、框架不提供的部分**（工作量估算时别漏）： -规则校核引擎、包络模型与检查器、持仓账本服务、审批工作台（多级审批 UI）、 +政策包引擎（规则校核）、包络模型与检查器、现势复核与执行许可服务（ExecutionPermit）、 +持仓账本服务、运营工单台（Case Desk，含多级审批收件箱）、 交易平台/调度/计量适配器、执行引擎与边缘协议、审计血缘组装。 ——这些恰恰是本平台的差异化资产；智能体框架只解决约 1/3 的问题。 @@ -76,10 +77,14 @@ Agent 代码 → 能力接口（complete / plan / extract / explain, 统一消 1. **M1**：数据接入管道 + 时序/关系库 + 持仓账本服务（数据先行）； 2. **M2**：Skill 服务群 v1（负荷/光伏/电价预测 + 报价优化 MILP）+ 评测基线； -3. **M3**:Runtime + 智能分析/交易博弈两个 Agent + 规则校核 + 审批工作台 +3. **M3**：Runtime + 智能分析/交易博弈两个 Agent + 政策包引擎 + 运营工单台 （此时即可跑通 07 篇 06:00→08:30 的申报链路，申报走文件导出人工上传）； -4. **M4**：资源调度 Agent + 包络模型 + 复盘流程 + AI 卡片嵌入既有页面； -5. 交互服务/负荷控制 Agent 与边缘控制链路放二期（依赖现场资源接入与外部联调）。 +4. **M4**：资源调度 Agent + 包络模型 + 现势复核/执行许可 + 复盘流程 + AI 卡片嵌入既有页面； +5. **M5 影子运行（一期验收形态）**：全链路接实时数据，外部效果全部仿真 + （申报只生成不提交、指令只投递仿真网关），逐日对比影子决策与人工实际决策—— + 既是最有说服力的验收演示，也是包络初值设定的数据依据； +6. 交互服务/负荷控制 Agent 与边缘控制链路放二期（依赖现场资源接入与外部联调）； + 二期上线路径：影子运行 → 受控实报（人工逐笔批）→ 包络自治逐步放宽。 **排序理由**：M1–M3 不依赖任何外部单位排期，最快形成端到端演示与真实历史回测能力； 回测结果（用历史行情验证报价优化收益）是二期扩大授权（包络放宽）与评审汇报的最强证据。 diff --git a/docs/10-federation.md b/docs/10-federation.md new file mode 100644 index 0000000..1e4b1d9 --- /dev/null +++ b/docs/10-federation.md @@ -0,0 +1,79 @@ +# 10 · 省间协同联邦边界 + +> 对应 proposal 二期目标「省间余缺互补、华中推广、跨省复制」与省间协同业务组的工作范畴。 +> 核心结论：**省间协同是联邦（federation），不是集中（centralization）**。 + +## 1. 边界原则 + +跨省协同**不意味着**一个中心平台可以访问另一省的原始遥测或终端控制权。 +每个省级平台是独立的信任域与责任域；省间交换的是**签名的、版本化的业务工件**， +而非数据管道或控制通道。 + +**默认不出省的**： + +- 原始设备遥测与用户级用电数据（隐私 + 商业敏感 + 数据出域合规）； +- 终端控制权（任何一省的许可/网关体系不受他省指令）； +- 用户档案、合同细节、内部收益分摊。 + +**可跨省交换的（签名工件）**： + +| 工件 | 内容 | 方向 | +|---|---|---| +| `FlexibilityEnvelope` | 分时段可调能力（容量、爬坡、持续时间、价格意向），不含构成明细 | 双向发布 | +| `Commitment` | 对某时段某容量的承诺及约束 | 协商达成 | +| 报价 / 中标 | 省间市场交易工件（经国分调交易体系） | 按市场规则 | +| 交付与结算事实 | 计量口径的交付确认、结算单 | 事后 | + +*类比：* 省内「聚合单元向省级平台上报灵活性包络、接受调度包络」的模式（04 篇）， +在省间以对等联邦形式复用——**同一套工件语义，不同的信任关系**（上下级 → 对等）。 + +## 2. 联邦交互模型 + +```mermaid +flowchart LR + subgraph HB["湖北省级平台（本项目）"] + HBk[运营内核 + 可信执行链] + HBf[联邦网关] + end + subgraph OTHER["他省平台 / 华中区域协调"] + OTf[联邦网关] + OTk[对方运营内核] + end + HBk --> HBf + HBf <-->|签名工件：灵活性包络 · 承诺 · 报价/中标 · 结算事实| OTf + OTf --> OTk +``` + +- **联邦网关**是唯一的省间通道：工件签名/验签、版本协商、幂等去重、留痕； +- 收到的他省工件进入本省平台时按「外部证据」处理——进事件日志、可触发本省流程， + 但**不直接进入**本省可信执行链（他省的承诺请求也要走本省完整的校核-审批-许可链）； +- 跨省承诺在双方各自的账本上记账（各记各的 `PositionLedger`），结算事实到达后对账。 + +## 3. 跨省场景示例：省间余缺互补 + +1. 湖北平台按周期发布次日 `FlexibilityEnvelope`（富余可调能力，已脱敏聚合）； +2. 他省（缺口方）发起承诺请求 → 湖北联邦网关验签、入事件日志； +3. 事件触发湖北侧交易博弈 Agent：测算履约能力与收益 → 生成省间承诺 `Proposal`； +4. 走湖北本省可信执行链（规则校核用省间政策包、现势复核、审批/包络、许可）； +5. 承诺工件签名回传；执行期由湖北自己的控制平面在省内组织履约； +6. 交付事实与结算单交换，双方复盘。 + +**要点**：他省全程只看到工件（包络 → 承诺 → 交付事实）， +看不到湖北用哪些资源、哪个用户履约——「跨区域资源匹配准确率 ≥ 85%」的指标 +在工件层面衡量，不需要跨省数据穿透。 + +## 4. 信任与安全 + +- 工件签名：省级平台各持机构密钥，工件带摘要与时间戳，防篡改可追责； +- 版本化：工件 schema 版本协商（联邦各方升级不同步是常态）； +- 政策包分层：省内政策包 + 省间政策包（国分调规则、区域协议）分开维护与升版； +- 最小披露：灵活性包络的聚合粒度是合规参数（可配到不低于聚合单元级）。 + +## 5. 对一期的要求（避免二期返工） + +一期不建联邦，但要**预留三个不返工点**： + +1. `FlexibilityEnvelope` 作为一等业务对象进入 domain 包（省内聚合单元上报即用它， + 省间复用同一 schema）； +2. 账本支持「对外承诺」条目类型（区别于市场持仓）； +3. 政策包引擎支持多包并存与按场景选包（省内包 / 省间包）。