diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 0a5d4fb..0000000 Binary files a/.DS_Store and /dev/null differ diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d927b38 --- /dev/null +++ b/.gitignore @@ -0,0 +1,22 @@ +# OS +.DS_Store + +# Node +node_modules/ +dist/ +*.tsbuildinfo +.env +.env.* + +# Python +__pycache__/ +*.pyc +.venv/ +.pytest_cache/ +.ruff_cache/ + +# Mastra / build +.mastra/ + +# Eval run artifacts (archived runs live in object storage, not git) +packages/evals/reports/runs/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..da300ed --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# CLAUDE.md — agent operating manual + +Design docs live in `docs/` (00–13, Chinese). They are the specification; this +file distills what is **binding** when writing code. When code and docs conflict, +docs win — or write an ADR changing the doc first. + +## Current phase + +Docs complete, implementation not started. Build order is ROADMAP.md (M1→M5). +Do not start a milestone's work before its predecessor's acceptance criteria are +testable, and do not build phase-2 items (edge control links, federation, +interaction/load-control agents) unless explicitly asked. + +## Hard rules (from docs/01 invariants — treat as review criteria) + +1. **LLM never computes numbers.** Any numeric field in a `Proposal` payload must + be a `{toolCallId, path}` reference into recorded tool-call lineage, + dereferenced by the assembler. If you find yourself parsing a number out of + LLM text into a payload, stop — that's the architecture's one forbidden move. +2. **No LLM in any control path.** Nothing under `services/` or the execution + path may import or await an LLM call. Periodic workflows must run with the + LLM backend down (invariant I6 — there is a test for this). +3. **External effects only via `(Proposal, ExecutionPermit)`.** Gateways/adapters + never accept a bare plan. Permits are short-lived and revocable. +4. **AI cannot approve.** No code path may transition a Proposal to + APPROVED/AUTHORIZED without either a matched envelope + passing checks, or a + human `resume()` with an approver identity distinct from the origination chain. +5. **Everything auditable.** State transitions, tool calls, approvals, permits, + and gateway receipts are event-sourced. Snapshots referenced by lineage are + immutable. +6. **Schemas live in `packages/domain` only.** Python models are generated from + `contracts/*.schema.json` — never hand-edit generated files, never define a + business object schema anywhere else. + +## Conventions + +- **Naming**: use the canonical code names in GLOSSARY.md. Do not invent new + English names for domain terms that already have one. +- **Language**: architecture docs Chinese; code, identifiers, comments, commit + messages, ADRs English. +- **Data representation** (docs/11 §3.3): money/energy/prices as fixed-point + decimal **strings**; units in field names (`power_mw`, `price_yuan_per_mwh`); + timestamps ISO8601 UTC; market intervals as `{date, interval_index}` with + `interval_minutes` explicit; all IDs strings; enums UPPER_SNAKE string literals. +- **Mastra**: do not trust memorized APIs — check `node_modules/@mastra/*/dist/docs/` + (or the mastra skill) against the installed version before writing framework code. +- **Testing floor**: every invariant above has at least one automated test; + schema changes run golden-fixture validation on both TS and Python sides; + policy pack changes require their rule tests green. + +## Do not + +- Do not invent business parameters (market deadlines, envelope bounds, loss + budgets, buffer coefficients). Check `docs/open-questions.md`; if a needed + parameter is listed there, wire it as named config with a placeholder value + and a `// OPEN-QUESTION:` comment, and say so in your summary. +- Do not relitigate decisions recorded in `docs/adr/`. If a decision must + change, propose a superseding ADR. +- Do not create root-level summary docs that duplicate `docs/` content + (no architecture.md / tech-stack.md — README points to the sources of truth). +- Do not add a sixth agent, merge the safety chain into business workflows, or + bypass the proposal lifecycle for "internal" effects — these were considered + and rejected (see ADRs 0005–0007). + +## Reading order for common tasks + +| Task | Read first | +|---|---| +| Domain schemas / contracts | docs/11, docs/00 §4, GLOSSARY.md | +| Runtime, workflows, agents | docs/09, docs/02 | +| Safety chain, approvals, permits | docs/03, docs/01 invariants | +| Skill services (Python) | docs/05 §1–2, docs/11 §3 | +| Anything touching money or bids | docs/07 (scenario), docs/13 §1 | +| Eval harness | docs/12 | diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..75a6b44 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,68 @@ +# GLOSSARY — 术语 → canonical code names + +Docs are Chinese, code is English. **Use these exact names**; do not coin +alternatives. Columns: term, code name (type/identifier), meaning, defining doc. + +## Core business objects + +| 中文 | Code name | Meaning | Doc | +|---|---|---|---| +| 建议 | `Proposal` | Any action the AI wants taken; carries digest + lineage | 03 | +| 运行包络（授权） | `Envelope` | Pre-approved autonomy bounds (authority, downward) | 03 | +| 灵活性包络（能力） | `FlexibilityEnvelope` | Adjustable capability report (capability, upward; federation artifact) | 04/10 | +| 执行许可 | `ExecutionPermit` | Short-lived revocable execution credential | 03 | +| 审批 | `Approval` | Human decision bound to a proposal digest + validity window | 03 | +| 持仓账本 | `PositionLedger` / `PositionUpdate` | Shared per-timescale position & constraint cascade | 00/04 | +| 运营工单 | `DecisionCase` | Operator's unit of accountability (one objective/owner/deadline) | 02 | +| 政策包 | `PolicyPack` | Versioned, tested, executable rule bundle | 05 | +| 态势报告 | `SituationReport` | Analysis agent output: state, anomalies, risk | 02 | +| 资源画像 | `ResourceProfile` | Capacity, constraints, reliability score | 02 | +| 预测集 | `ForecastBundle` | Curves + quantile intervals + model version | 05 | +| 承诺 | `Commitment` | User or inter-province delivery commitment | 10 | +| 执行回执 / 执行报告 | `ExecutionReceipt` / `ExecutionReport` | Idempotent effect receipt / execution outcome | 04 | +| 复盘结论 | `ReviewFinding` | Structured lesson from review, written back to memory | 02 | +| 调度指令 | `DispatchOrder` | Post-permit decomposed instruction | 04 | +| 结算 | `Settlement` | Settlement facts from metering | 06 | + +## Processes & components + +| 中文 | Code name | Meaning | Doc | +|---|---|---|---| +| 可信执行链 | safety chain, `proposal-lifecycle` workflow | Rule check → simulation → gate → permit → release | 03 | +| 规则校核 | rule check, `PolicyEnginePort` | Deterministic compliance/constraint validation | 03/11 | +| 仿真验证 | simulation, `SimulationPort` | Revenue backtest (bids) / power-balance (control) | 03 | +| 现势复核 | fresh-state check, `FRESH_CHECK` | Pre-release re-verification; failure → `STALE` | 03 | +| 包络检查 | envelope gate, `EnvelopePort.match` | Within-bounds → auto-approve | 03 | +| 授权 | `AuthorityPort.authorize` | Issues ExecutionPermit | 11 | +| 复盘 | review (not "replay", not "retrospective" in code) | D+1 deviation attribution loop | 02 | +| 血缘 | lineage | Tool-call provenance attached to proposals | 03/09 | +| 事件信封 | `EventEnvelope` | Typed event wrapper with schemaVersion/causation | 11 | +| 认知平面 / 控制平面 | cognitive plane / control plane | Slow LLM loop / fast deterministic loop | 00 | +| 聚合单元 | `AggregationUnit` | VPP aggregation layer between province and sites | 04 | +| 边缘控制终端 | edge terminal | Second-level local closed loop | 04 | +| 熔断 | circuit breaker / kill switch (L0–L4) | Graduated shutdown hierarchy | 13 | +| 影子运行 | shadow run/mode | Full loop, simulated external effects | 08 | + +## Market & domain terms + +| 中文 | Code name / abbrev | Meaning | +|---|---|---| +| 虚拟电厂 | VPP | Virtual power plant | +| 现货市场 | spot market | Hubei electricity spot market | +| 日前 / 日内 / 实时 | `DAY_AHEAD` / `INTRADAY` / `REALTIME` | Timescale enum values (also `ANNUAL`, `MONTHLY`) | +| 申报 | bid (submission: declaration) | Market bid/declaration; `Proposal{type: BID}` | +| 出清 / 中标 | clearing / award | Market clearing result | +| 96 点 | 96 intervals | 15-min intervals per day; `{date, interval_index}` | +| 需求响应 | DR, demand response | | +| 辅助服务 / 调频 | ancillary services / frequency regulation | | +| 可调资源 / 可调负荷 | flexible resource / flexible load | Adjustable capacity | +| 可中断负荷 | interruptible load | Contracted curtailable load | +| 邀约 / 履约 | invitation / fulfillment | User solicitation; commitment delivery | +| 基线 | baseline | DR measurement baseline | +| 偏差考核 | deviation assessment | Penalty regime for plan-vs-actual gaps | +| 代理购电 | proxy purchase / retail agency | Buying on behalf of contracted users | +| 源网荷储 | source-grid-load-storage | Coordinated optimization scope | +| 光明电力大模型 | GuangMing power LLM (`guangming` adapter id) | State Grid's foundation model | +| 等保 | MLPS | Multi-Level Protection Scheme (security compliance) | +| 电科院 | EPRI (Hubei) | State Grid Hubei Electric Power Research Institute | +| 3060 平台 | legacy `3060` platform | Existing platform being overlaid (docs/06 §4) | diff --git a/README.md b/README.md new file mode 100644 index 0000000..ca73864 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# VPP AI Platform · 虚拟电厂多时空协同智能运营平台 + +AI-assisted operations platform for a virtual power plant (VPP) in Hubei, China: +five LLM agents propose market bids, resource dispatch, and load-control plans; +a deterministic safety chain (rule check → simulation → envelope/human approval → +execution permit) governs everything before any external effect. **The LLM never +computes numbers and never touches the second-level control loop.** + +**Status: architecture/design phase.** No implementation code yet. The design is +complete and internally consistent (docs 00–13); implementation follows +[ROADMAP.md](ROADMAP.md), starting with M1. + +## Orientation + +| You are… | Start with | +|---|---| +| A coding agent about to implement | [CLAUDE.md](CLAUDE.md), then docs/00, 01, 09, 11 | +| New to the project | [docs/00-overview.md](docs/00-overview.md) → [docs/07-scenario-walkthrough.md](docs/07-scenario-walkthrough.md) (the end-to-end reference scenario) | +| Reviewing the business case | [proposal.md](proposal.md) (申报材料, source of requirements) | +| Looking for a settled decision | [docs/adr/](docs/adr/) | +| Wondering what's still undecided | [docs/open-questions.md](docs/open-questions.md) | + +## Document map (docs are in Chinese; implementation-facing files in English) + +| Doc | Content | +|---|---| +| [00-overview](docs/00-overview.md) | System context, two-plane architecture, business objects | +| [01-principles](docs/01-principles.md) | 9 principles + 8 hard invariants (binding for all code) | +| [02-cognitive-plane](docs/02-cognitive-plane.md) | Five agents, Runtime, memory, Case Desk | +| [03-safety-chain](docs/03-safety-chain.md) | Proposal state machine, envelopes, permits, staleness | +| [04-control-plane](docs/04-control-plane.md) | Execution engine, edge autonomy, time/space cascades | +| [05-skills-and-data](docs/05-skills-and-data.md) | Skill contracts, five-store data layer, policy packs | +| [06-integration](docs/06-integration.md) | External system boundaries and degraded channels | +| [07-scenario-walkthrough](docs/07-scenario-walkthrough.md) | Day-ahead spot bidding, D-1 → D → D+1 | +| [08-implementation](docs/08-implementation.md) | Stack, LLM abstraction, deployment, milestones | +| [09-runtime-implementation](docs/09-runtime-implementation.md) | Runtime on Mastra: workflows, suspend/resume, lineage | +| [10-federation](docs/10-federation.md) | Cross-province boundary: signed artifacts only | +| [11-contracts](docs/11-contracts.md) | Ports, canonical objects, TS↔Python contract pipeline | +| [12-evaluation](docs/12-evaluation.md) | Four-layer evals, change gates, KPI definitions | +| [13-risks-failure-modes](docs/13-risks-failure-modes.md) | FMEA, top-5 risks, kill-switch hierarchy | + +Supporting: [brainstorming.md](brainstorming.md) is an independent peer review +whose findings were integrated (see docs/01 invariants note); +[GLOSSARY.md](GLOSSARY.md) maps Chinese domain terms to canonical code names. + +## Target repository layout (from docs/09 §7) + +``` +packages/ +├── domain/ # zod schemas — single source of truth for all business objects +├── runtime/ # Mastra instance, workflows, agents, tool registry, triggers +├── services/ # deterministic services: policy engine, envelopes, ledger, authority +├── adapters/ # anti-corruption layers: trading platform, dispatch, metering +├── evals/ # eval harness, datasets, judges (docs/12 §5) +└── skills-py/ # Python skill services (forecasting, MILP optimization, simulation) +contracts/ # generated JSON Schema + golden fixtures (cross-language contract) +``` diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..bb23cf8 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,91 @@ +# ROADMAP + +Phase 1 (系统研发与省内能力落地, 2025.12–2026.5) as five milestones. Each has +acceptance criteria a coding agent can verify. Sequencing rationale: M1–M3 need +no external-party scheduling; the demo-able bidding loop lands earliest +(docs/08 §4). Phase 2 items are listed but **not to be built yet**. + +## M1 — Data foundation & contracts + +Deliverables: +- `packages/domain`: zod schemas for the 07-scenario object set — `Proposal` + (+digest), `Approval`, `ExecutionPermit`, `Envelope`, `PositionLedger`/`PositionUpdate`, + `ForecastBundle`, `SituationReport`, `ResourceProfile`, `DecisionCase`, `EventEnvelope`. +- `contracts/`: JSON Schema export pipeline + golden fixtures; pydantic codegen + wired for `skills-py`; dual-side contract tests in CI. +- Ingestion pipeline skeleton: time-series store + relational store + snapshot + store (immutable, checksummed); data-quality gate stub. +- Ledger service v1: read with version, append, per-timescale views. + +Accept when: golden fixtures validate identically in TS and Python CI; a ledger +constraint-cascade test passes (monthly position bounds a day-ahead write); +snapshots are content-addressed and immutable. + +## M2 — Skills v1 & eval baseline + +Deliverables: +- `skills-py`: load forecast, PV forecast, price forecast (all with quantile + intervals), bid-optimization MILP, report generator. HTTP/JSON per contracts. +- `packages/evals`: harness + L2 baselines (MAPE, interval coverage, backtest + revenue vs naive/hindsight bounds) on historical data. + +Accept when: forecasts return calibrated quantiles (coverage test); MILP output +respects ledger constraints in property tests; eval runs are reproducible and +archived; baseline report exists for each skill. + +## M3 — Runtime, two agents, safety chain, Case Desk + +Deliverables: +- `packages/runtime`: Mastra instance; trigger service (cron/event/manual); + router agent with template-enum output; `registerSkill` lineage wrapper; + outbox event bus. +- Workflows: `day-ahead-situation`, `day-ahead-bid`, `proposal-lifecycle` + (rule check → simulation → envelope gate with suspend/resume → fresh check → + permit → release). +- `packages/services`: policy engine v1 (+ first Hubei policy pack, from + open-questions once confirmed), envelope service, authority service (permits), + audit/lineage assembly. +- Case Desk v1: approval inbox (resume endpoint), case view, lineage expansion. +- Bid release path = file export for manual upload (degraded channel by design). + +Accept when: docs/07 timeline 06:00→08:30 runs end-to-end on historical data; +all eight invariant tests pass (incl. LLM-down degraded run and AI-self-approval +rejection); a suspended approval survives process restart; permit expiry blocks +a late release. + +## M4 — Resource agent, envelopes live, review loop + +Deliverables: +- Resource dispatch agent + potential-assessment skill + award-decomposition flow. +- Envelope model end-to-end: bounded auto-approval, deviation-streak suspension, + envelope re-approval workflow. +- Review (复盘) workflow: ledger plan-vs-actual per timescale, attribution, + `ReviewFinding` writebacks (semantic memory, reliability scores, envelope + recommendations). +- AI insight cards embedded in existing business pages (read-only projections). + +Accept when: docs/07 D-1 16:00 and D+1 sections run; a ReviewFinding measurably +updates a ResourceProfile reliability score; envelope suspension triggers on a +seeded deviation streak. + +## M5 — Shadow run (phase-1 acceptance form) + +Deliverables: +- Full loop on live data, all external effects simulated (bids generated, not + submitted; commands to a simulation gateway). +- Daily shadow-vs-human-vs-hindsight comparison report; KPI dashboard per + docs/12 §4 definitions. +- Loss circuit-breaker, abnormal-day protocol, kill-switch L0–L2 implemented + and drilled once. + +Accept when: 20+ consecutive shadow days with complete lineage; KPI report +auto-generated; one envelope-widening recommendation produced from shadow data +(not acted on — that's a phase-2 governance step). + +## Phase 2 (do not build in phase 1) + +Interaction-service & load-control agents; edge control links (real protocols); +trading-platform programmatic submission; dispatch/metering live interfaces; +federation gateway (build `FlexibilityEnvelope` schema in M1 — the three +no-rework reservations of docs/10 §5 are in scope for phase 1 schemas only); +controlled live bidding → gradual envelope widening. diff --git a/docs/adr/0001-typescript-mastra-core-python-skills.md b/docs/adr/0001-typescript-mastra-core-python-skills.md new file mode 100644 index 0000000..9afbf65 --- /dev/null +++ b/docs/adr/0001-typescript-mastra-core-python-skills.md @@ -0,0 +1,16 @@ +# ADR-0001: TypeScript + Mastra core, Python skills + +**Status**: accepted · 2026-09 + +**Context**: Runtime needs durable workflows with suspend/resume (hours-long +approvals), typed tool contracts, agent primitives. Forecasting/MILP/simulation +need the Python ecosystem and suit the partner teams (WHU, EPRI). + +**Decision**: Agent runtime, workflows, domain schemas, deterministic services +in TypeScript on Mastra. All numeric/ML skills as Python HTTP services. + +**Alternatives**: Python end-to-end (LangGraph) — weaker typed contracts, +one team owns everything; Java/Spring core — heavier, slower iteration. + +**Consequences**: Cross-language contract pipeline required (ADR-0002). +Mastra APIs must be verified against installed version (evolves fast). diff --git a/docs/adr/0002-zod-schema-source-of-truth.md b/docs/adr/0002-zod-schema-source-of-truth.md new file mode 100644 index 0000000..a437b42 --- /dev/null +++ b/docs/adr/0002-zod-schema-source-of-truth.md @@ -0,0 +1,20 @@ +# ADR-0002: zod as schema source of truth + +**Status**: accepted · 2026-09 + +**Context**: Business objects cross TS runtime ↔ Python skills; schema drift +between languages is the classic failure. Someone must own the truth. + +**Decision**: Hand-written zod schemas in `packages/domain` are the only +source. Build exports JSON Schema to `contracts/` (committed, versioned); +pydantic models are generated from those (never hand-edited). Golden fixtures +validated by both CIs. Data representation rules in docs/11 §3.3 are part of +the contract (decimal strings for money, units in field names, etc.). + +**Alternatives**: Hand-written JSON Schema as neutral source (revisit if +Python-side partners need co-ownership — the contracts/ layer stays identical); +protobuf/gRPC (rejected: call volume doesn't need it, lineage snapshots should +be human-readable, partner onboarding cost). + +**Consequences**: Python teams depend only on `contracts/`, never on TS +internals — org boundary = code boundary. diff --git a/docs/adr/0003-provider-abstracted-llm.md b/docs/adr/0003-provider-abstracted-llm.md new file mode 100644 index 0000000..9ed1d27 --- /dev/null +++ b/docs/adr/0003-provider-abstracted-llm.md @@ -0,0 +1,16 @@ +# ADR-0003: Provider-abstracted LLM + +**Status**: accepted · 2026-09 + +**Context**: Production mandates 光明电力大模型 (on-prem, spec unknown at design +time); development can't wait for access. + +**Decision**: All LLM calls go through a capability-oriented abstraction with a +model router: commercial API in dev, local open model in preprod, GuangMing +adapter in prod. Conservative assumptions until spec arrives: OpenAI-compatible, +8K context, no native tool calling (degrade to prompt+JSON+retry). Backend swap +is gated by the L1 eval suite plus L4 shadow comparison (docs/12 §3), not judgment. + +**Consequences**: No vendor-specific features in agent code; prompts and tool +definitions maintained provider-portable; phase-1 acceptance must not depend on +GuangMing access (docs/13 §7). diff --git a/docs/adr/0004-postgres-outbox-before-kafka.md b/docs/adr/0004-postgres-outbox-before-kafka.md new file mode 100644 index 0000000..7b66b1d --- /dev/null +++ b/docs/adr/0004-postgres-outbox-before-kafka.md @@ -0,0 +1,15 @@ +# ADR-0004: Postgres transactional outbox first, Kafka later + +**Status**: accepted · 2026-09 + +**Context**: Event bus carries business objects (P4) and is the audit backbone +(P5). Phase-1 volume is bid-frequency, not telemetry-frequency. + +**Decision**: Phase 1 uses a Postgres transactional outbox (business write + +event in one transaction) with polling/LISTEN consumers, behind a thin bus +interface. Phase 2 relays the outbox into Kafka when telemetry-scale events +arrive; consumer interface unchanged. + +**Consequences**: Exactly-once-ish semantics via same-DB transactionality in +phase 1; events reconcile trivially against business data. Bus abstraction must +not leak Postgres specifics. diff --git a/docs/adr/0005-single-proposal-lifecycle-workflow.md b/docs/adr/0005-single-proposal-lifecycle-workflow.md new file mode 100644 index 0000000..9a83531 --- /dev/null +++ b/docs/adr/0005-single-proposal-lifecycle-workflow.md @@ -0,0 +1,17 @@ +# ADR-0005: Safety chain as one proposal-lifecycle workflow + +**Status**: accepted · 2026-09 + +**Context**: Every proposal type (bid, invitation, control plan, dispatch plan) +must pass rule check → simulation → envelope gate → fresh check → permit. + +**Decision**: One `proposal-lifecycle` workflow implements the state machine for +all types. Business workflows end by submitting a Proposal; the lifecycle +workflow takes over. Approval resume, timeout escalation, and audit target this +single code path. + +**Alternatives**: Inline safety steps in each business workflow — rejected: +five slightly-divergent safety chains are how audit gaps are born. + +**Consequences**: Type-specific behavior (which simulation, which policy pack) +is data/config on the Proposal, not workflow structure. diff --git a/docs/adr/0006-envelope-tiered-autonomy.md b/docs/adr/0006-envelope-tiered-autonomy.md new file mode 100644 index 0000000..e46288c --- /dev/null +++ b/docs/adr/0006-envelope-tiered-autonomy.md @@ -0,0 +1,17 @@ +# ADR-0006: Envelope-based tiered autonomy + +**Status**: accepted · 2026-09 + +**Context**: Per-action human approval contradicts the ≤3-min decision KPI and +daily bidding cadence; full autonomy contradicts the mandate that AI never +directly controls. + +**Decision**: Humans approve *envelopes* (policy-level bounds with validity +windows, multi-level approval); in-envelope actions auto-pass after rule check + +simulation; out-of-envelope or simulation-flagged actions escalate to humans. +Envelopes start empty and widen only on L4 shadow/online evidence (docs/12 §3); +deviation streaks auto-suspend them. Precedent: AGC regulation-band delegation. + +**Consequences**: Autonomy growth is itself auditable. Approval queue shrinks to +genuine anomalies — also the main countermeasure to approval complacency +(docs/13 §3). diff --git a/docs/adr/0007-review-is-workflow-not-sixth-agent.md b/docs/adr/0007-review-is-workflow-not-sixth-agent.md new file mode 100644 index 0000000..5f553e3 --- /dev/null +++ b/docs/adr/0007-review-is-workflow-not-sixth-agent.md @@ -0,0 +1,15 @@ +# ADR-0007: Review (复盘) is a workflow, not a sixth agent + +**Status**: accepted · 2026-09 + +**Context**: The proposal alternates between five agents and six business stages +(review appearing as a sixth agent in some slides). + +**Decision**: Review is a cross-agent workflow template led by the analysis +agent, triggered by metering-data arrival. Its authoritative inputs are the +ledger and event log; its outputs are `ReviewFinding` writebacks (semantic +memory, reliability scores, envelope recommendations). + +**Rationale**: Review is an analysis task; a dedicated agent would duplicate the +analysis agent's role. Agent names are product personas, not service boundaries +(peer review §4.1). diff --git a/docs/adr/0008-cases-for-humans-workflows-for-machines.md b/docs/adr/0008-cases-for-humans-workflows-for-machines.md new file mode 100644 index 0000000..75a89c6 --- /dev/null +++ b/docs/adr/0008-cases-for-humans-workflows-for-machines.md @@ -0,0 +1,16 @@ +# ADR-0008: Cases for humans, workflows for machines + +**Status**: accepted · 2026-09 + +**Context**: Operators need a unit of accountability; the runtime needs a unit +of execution. Conflating them makes both worse (peer review, Alternative C). + +**Decision**: `DecisionCase` (one objective, owner, deadline, completion +contract) is the operator-facing aggregation; workflows are internal execution. +A case references the products of several workflows via `case_id`. Dashboards, +approval inboxes, and reports are projections over cases + ledger + event log, +not standalone feature silos. + +**Consequences**: UI work targets case views; a case must never become an +unbounded container (enforced: one objective per case, mandatory completion +contract). diff --git a/docs/open-questions.md b/docs/open-questions.md new file mode 100644 index 0000000..b7f431f --- /dev/null +++ b/docs/open-questions.md @@ -0,0 +1,59 @@ +# Open Questions — 业务参数与待决事项清单 + +Consolidates every `TODO(业务)` scattered in docs 03/07/12/13 plus unresolved +items from the peer review (brainstorming.md §16). **Coding agents: never invent +values for items on this list** — wire named config with placeholder + an +`// OPEN-QUESTION:` comment (see CLAUDE.md). + +## A. 湖北市场参数（owner: 运营/交易团队 · blocks M3 policy pack + 07 篇定稿） + +| # | Question | Config key (suggested) | +|---|---|---| +| A1 | 日前申报窗口开启/截止时间；出清发布时间 | `market.da.window` | +| A2 | 代理购电申报与虚拟电厂申报是否同一通道/分开建模 | `market.channels` | +| A3 | 日内市场机制（是否开、频次、截止） | `market.intraday` | +| A4 | 偏差考核规则：偏差带、考核价格机制（→ MILP 目标函数与风险口径） | `market.deviation` | +| A5 | 中长期持仓对日前申报的约束形式（分解曲线偏差带） | `ledger.da_bounds` | + +## B. 包络与风控参数（owner: 运营团队 · blocks M4 envelopes + M5 breakers） + +| # | Question | Config key | +|---|---|---| +| B1 | 申报包络：价格边界的基准（预测值?历史分位?）与初始容差 | `envelope.bid.*` | +| B2 | 控制包络：分资源类型的单点削减上限与恢复速率 | `envelope.control.*` | +| B3 | 包络审批层级 L1/L2/L3 对应岗位/会签流程 | `approval.levels` | +| B4 | 包络挂起条件：连续 N 次偏差超阈的 N 与阈值 | `envelope.suspension` | +| B5 | 单日亏损预算（L2 熔断阈值） | `breaker.daily_loss_budget` | +| B6 | 承诺缓冲系数 k 初值 | `bidding.commitment_buffer` | +| B7 | 极端日协议触发的气象条件 | `abnormal_day.triggers` | +| B8 | 各级熔断（L0–L4）授权岗位与恢复条件 | `breaker.authority` | +| B9 | 演习样本制度：频率与考核挂钩方式 | — (制度非配置) | + +## C. KPI 口径（owner: 运营 + 验收双方 · blocks M5 dashboard） + +| # | Question | +|---|---| +| C1 | docs/12 §4 全表口径确认，尤其「综合市场收益提升 15%」的对照基线定义与冻结 | +| C2 | 预测误差 8% 的统计层级（聚合级?分用户?）与光伏口径（nRMSE?） | + +## D. 外部依赖（owner: PMO/省间协同组 · blocks phase 2, start engagement in phase 1） + +| # | Question | +|---|---| +| D1 | 光明电力大模型接口规格：协议、上下文、工具调用、部署位置、网络分区（ADR-0003 假设待证实） | +| D2 | 交易平台程序化申报接口协议与联调排期 | +| D3 | 调度/负荷管理、计量结算接口协议与排期 | +| D4 | 省级↔聚合单元↔边缘现有协议与时延保证（peer review Q6） | +| D5 | 首批转为政策包的湖北规则清单（peer review Q7） | + +## E. 治理决策（owner: 项目领导小组） + +| # | Question | +|---|---| +| E1 | 一期验收形态确认：影子运行（推荐，见 ROADMAP M5）vs 受控实报（peer review Q3） | +| E2 | 既有 3060 平台各实体的 source-of-truth 矩阵签认（docs/11 §2 表为草案） | +| E3 | 边缘断连策略的「安全曲线」定义权与更新流程 | + +--- +*Process*: when an item is answered, move the value into config/docs, mark the +row `✓ resolved → `, and keep the row for audit.