80835138e9
- README: orientation, doc map, target package layout (pointers only, no duplicated architecture content) - CLAUDE.md: agent operating manual — invariants as code-review rules, conventions, do-not list, task reading order - ROADMAP: M1-M5 with verifiable acceptance criteria, phase-2 fence - GLOSSARY: canonical Chinese-term → code-name mapping - docs/adr/: eight ADRs recording settled decisions and rejected alternatives - docs/open-questions.md: consolidated TODO(业务) tracker by owner and blocking milestone - .gitignore; untrack .DS_Store Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr 🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh
3.6 KiB
3.6 KiB
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, starting with M1.
Orientation
| You are… | Start with |
|---|---|
| A coding agent about to implement | CLAUDE.md, then docs/00, 01, 09, 11 |
| New to the project | docs/00-overview.md → docs/07-scenario-walkthrough.md (the end-to-end reference scenario) |
| Reviewing the business case | proposal.md (申报材料, source of requirements) |
| Looking for a settled decision | docs/adr/ |
| Wondering what's still undecided | docs/open-questions.md |
Document map (docs are in Chinese; implementation-facing files in English)
| Doc | Content |
|---|---|
| 00-overview | System context, two-plane architecture, business objects |
| 01-principles | 9 principles + 8 hard invariants (binding for all code) |
| 02-cognitive-plane | Five agents, Runtime, memory, Case Desk |
| 03-safety-chain | Proposal state machine, envelopes, permits, staleness |
| 04-control-plane | Execution engine, edge autonomy, time/space cascades |
| 05-skills-and-data | Skill contracts, five-store data layer, policy packs |
| 06-integration | External system boundaries and degraded channels |
| 07-scenario-walkthrough | Day-ahead spot bidding, D-1 → D → D+1 |
| 08-implementation | Stack, LLM abstraction, deployment, milestones |
| 09-runtime-implementation | Runtime on Mastra: workflows, suspend/resume, lineage |
| 10-federation | Cross-province boundary: signed artifacts only |
| 11-contracts | Ports, canonical objects, TS↔Python contract pipeline |
| 12-evaluation | Four-layer evals, change gates, KPI definitions |
| 13-risks-failure-modes | FMEA, top-5 risks, kill-switch hierarchy |
Supporting: brainstorming.md is an independent peer review whose findings were integrated (see docs/01 invariants note); 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)