_{所有主指标均由版本化公开数据、验证集冻结对照和SHA-256绑定代码复算；同时公开更严格基线下的边际收益与峰值权衡。
Every headline metric is recomputed from versioned public data, a validation-frozen comparator, and SHA-256-bound code—with the harder comparator and peak trade-off disclosed.}

截图来自增强公开数据包的留出测试轨迹和浏览器实测按钮联动。图中数值是可复现的离线场景输出，不是实时码头遥测、生产绩效或监管核证结果。
The screenshots show held-out replay from the enhanced public package and browser-verified button linkage. Values are reproducible offline scenario outputs—not live terminal telemetry, production performance, or regulatory assurance.

训练中心在同一画面展示四种 RL、MPC 控制基线、当前数据集、观测/动作契约，以及“训练不渲染、测试集才回放”的执行边界。

小懿训练顾问保留项目原有 Q 版海事形象，并把五算法、增强数据集、训练配置、真实进度与策略测试入口放在同一个联动中枢。浏览器验收实际点击“小懿 → 低碳”，动作网关返回成功并同步高亮对应按钮；执行详情保留识别、按钮/接口、确认、执行和结果证据。

本项目把港口能耗、岸电、设备资源、延误、成本与碳排放放进同一个约束环境，连接数据校验、强化学习训练、控制理论对照、独立测试、轨迹回放、模型治理与双语驾驶舱。重点不是制造一张“看起来在线”的大屏，而是让每个关键数字都能回到数据分区、物理假设、算法动作和证据文件。

This project places port energy use, shore power, equipment allocation, delay, cost, and emissions inside one constrained environment. It connects dataset validation, reinforcement-learning training, a control-theory baseline, held-out evaluation, trajectory replay, model governance, and a bilingual cockpit. Its central goal is evidence: every important number should trace back to a split, a declared physical assumption, an algorithm action, and a persisted artifact.

• 24 步测试轨迹、吞吐、岸桥/场内车辆动作、峰值负荷、能耗、范围一与范围二排放、成本与安全越界。

• 基线与策略对比来自同一环境、同一数据包与同一测试分区。

• 缺失的气象、AIS、TOS、堆场占用、AGV 电池与可再生能源结构直接显示“未接入”，不会生成展示性数字。

• A 24-step held-out trajectory with throughput, crane and yard-vehicle actions, peak load, energy, Scope 1/2 emissions, cost, and safety violations.

• Baseline and policy comparisons share the same environment, dataset package, and test partition.

• Missing weather, AIS, TOS, yard occupancy, AGV battery, and renewable-mix fields remain visibly unavailable instead of being fabricated.

治理面板区分驾驶舱、真实 learner 运行时、小懿 AI、本地航行模拟器和 Godot 执行环境。首次克隆时，只有仓库内能力显示就绪；未配置的外部桌面项目会明确离线。
The governance panel separates the cockpit, real learner runtime, Xiaoyi AI, the local sailing simulator, and the Godot runtime. On a clean clone, only repository-owned capabilities report ready; unconfigured desktop integrations remain explicitly offline.

flowchart LR
  subgraph Data["Data and provenance / 数据与血缘"]
    CSV["Canonical CSV"]
    META["Metadata, units, assumptions"]
    HASH["Schema + split + SHA-256 gates"]
    CSV --> HASH
    META --> HASH
  end

  subgraph Experiment["Experiment plane / 实验平面"]
    TRAIN["Train split\nrender_mode=None"]
    ENV["PortEnergyDispatchEnv\nv1 · v2 · v3"]
    RL["PPO · SAC · TD3 · DQN"]
    MPC["Constrained MPC"]
    TEST["Held-out test\ntrajectory rendering"]
    HASH --> TRAIN --> ENV
    ENV --> RL --> TEST
    ENV --> MPC --> TEST
  end

  subgraph Evidence["Evidence plane / 证据平面"]
    RUN["Run manifest + metrics"]
    ART["Checkpoints + artifact hashes"]
    REG["Offline model registry"]
    TEST --> RUN --> REG
    RL --> ART --> REG
    MPC --> ART
  end

  subgraph Product["Product plane / 产品平面"]
    API["FastAPI + role gates + audit"]
    UI["React bilingual cockpit"]
    OPT["Optional Xiaoyi and Godot connectors"]
    REG --> API --> UI
    OPT -. "explicitly optional" .-> API
  end

四种 RL 算法均通过 Stable-Baselines3 的实际 learn() 路径运行；仓库测试对每个 learner 执行最小 smoke run。smoke run 只证明管线可执行，不代表策略已收敛或优于基线。
All four RL algorithms execute the actual Stable-Baselines3 learn() path, and the test suite performs a minimal smoke run for each learner. A smoke run proves pipeline executability—not convergence or superiority.

v1 的 19 维观测覆盖需求/预测、碳因子、电价、积压、电网余量、储能、时间、货类及累计指标；v2 再加入锚泊、靠泊、离港和在港时间等 6 项官方港口活动信号；实港 v3 继续加入天气、泊位/设备/电网可用率、岸电兼容和可再生能源 10 项强制输入。4 维动作控制岸电比例、岸桥启用比例、场内车辆启用比例和储能充放电功率。每一步显式计算处理量、队列、负荷、峰值越界、储能退化、辅助燃油、范围一/范围二排放、能耗与延误成本，并由动作屏蔽器约束电网容量、设备可用率、岸电兼容、SOC 与终端 SOC 可达性。

v1 exposes 19 energy-dispatch observations; v2 adds six official vessel-activity signals; the real-port v3 contract adds ten mandatory weather, availability, shore-compatibility and renewable-power inputs. Four actions control shore power, active crane and yard fleets, and battery charge/discharge. Each step computes throughput, queue, load, peak violations, degradation, auxiliary fuel, Scope 1/2 emissions, energy and delay costs; action shields enforce grid, availability, compatibility, SOC and terminal-SOC reachability constraints.

dataset validation
  -> immutable train/validation/test split
  -> non-rendering fit on train
  -> validation-only tuning + checkpoints
  -> artifact SHA-256
  -> one-way held-out test rollout
  -> drift, integrity, and safety gates
  -> candidate / validated_offline / verified_offline / blocked
  -> production_eligible = false

每个新 run 写入 backend/app/data/runs/<job-id>/，但运行目录和二进制模型默认不进入 Git。源码仓库保持轻量；需要公开的 benchmark 模型与结果应作为独立 release artifact 发布。
Each new run is written to backend/app/data/runs/<job-id>/, while run outputs and binary models are ignored by Git. The source repository stays lightweight; benchmark models and results should be published as separate release artifacts.

仓库保留两个互补数据包。52,608 小时长周期基准组合了四类公开来源：

1. Port of Los Angeles 2020–2025 container statistics：72 条官方月度 TEU；2020–2023 年训练、2024 年验证、2025 年全年留出测试。
2. U.S. EIA monthly retail electricity prices：同期加州商业部门月均电价，作为每月均值锚点。
3. EIA Hourly Electric Grid Monitor：LADWP 2020–2025 小时用电与消费侧碳强度；52,608 小时中 51,726 小时为报告值，882 小时按月-小时中位数插补并保留质量码，原始覆盖率 98.32%。
4. U.S. EPA eGRID CAMX：作为年度区域因子交叉检查。

The default benchmark combines four public-source families:

1. Port of Los Angeles 2020–2025 container statistics: 72 official monthly TEU observations, with 2020–2023 for training, 2024 for validation, and all of 2025 held out for testing.
2. U.S. EIA monthly retail electricity prices: California commercial-sector monthly means used as price anchors.
3. EIA Hourly Electric Grid Monitor: LADWP hourly demand and consumed carbon intensity for 2020–2025; 51,726 of 52,608 hours are reported and 882 are quality-coded month-hour median imputations, for 98.32% source coverage.
4. U.S. EPA eGRID CAMX: an annual regional cross-check.

新训练默认使用 port_la_2020_2024_vessel_activity_hourly：在同一版本化能碳底座上加入洛杉矶港 Wharfinger Division 2020–2024 年 1,238 条官方工作日锚泊、靠泊、离港与在港时间记录。它包含 43,848 个连续小时；2020–2022 训练、2023 验证、2024 留出测试。非报告日明确标记为线性插值，不冒充逐小时港口遥测。旧数据包和原指标完整保留，作为更长的能碳证据基线。完整比较见 dataset credibility report。

New training defaults to port_la_2020_2024_vessel_activity_hourly, which adds 1,238 official Port of Los Angeles Wharfinger Division business-day anchor, berth, departure, and dwell observations to the versioned energy-carbon base. Its 43,848 contiguous hours use 2020–2022 for training, 2023 for validation, and 2024 for held-out testing. Non-reporting days are explicitly marked interpolations, not hourly terminal telemetry. The original package and metrics remain intact as the longer energy-carbon baseline.

月度 TEU 通过公开的确定性曲线分配到小时；LADWP 商业分时电价时段只用于形成日内形状，并归一回 EIA 月均电价。该价格仍是情景代理而非港口账单，设备容量、负荷、储能与延误成本是元数据中声明的模型参数。完整来源、单位、插补、转换与哈希见 数据卡 和 dataset metadata。
Monthly TEU is allocated to hours through a disclosed deterministic profile. LADWP commercial time-of-use periods provide only the intraday shape, rescaled to each EIA monthly mean. Prices remain scenario proxies rather than terminal bills; equipment, storage and delay parameters are declared model assumptions. See the data card and dataset metadata.

在覆盖 2025 全年的 48 个确定性留出窗口、共 1,152 个小时仿真步上，四步约束 MPC 相对“全岸电+固定满配装卸资源”强基线降低能耗 8.4%、碳排 8.7%、情景成本 7.9%、峰值负荷 3.2%，设备平均启用比例降低 28.8%，吞吐保持率 99.97%、约束满足率 100%；三组预声明目标权重下碳排改善区间为 8.69%–8.74%。这是公开数据离线情景结果，不是港口实测 KPI，也不证明 RL 优于 MPC；完整分母、采样索引、限制和哈希见 benchmark report。

Across 48 deterministic held-out windows spanning 2025—1,152 simulated hourly steps—the four-step constrained MPC reduces energy by 8.4%, carbon by 8.7%, scenario cost by 7.9%, and peak load by 3.2% against the strong “full shore power + fixed fully staffed cargo resources” baseline. Mean equipment activation falls 28.8%, throughput retention is 99.97%, and constraint satisfaction is 100%. Three predeclared objective-weight settings yield a carbon-improvement range of 8.69%–8.74%. These are public-data offline scenario results, not measured terminal KPIs, and they do not show RL superiority over MPC. See the benchmark report for denominators, sample indices, limits, and hashes.

报告同时给出更严格的对照：仅用 2024 验证集从 9 个静态资源配置中选择 80%/80% 岸桥与场内车辆比例，冻结后在 2025 测试。MPC 相对该基线仍降低 碳排 2.84%、能耗 2.52%、成本 2.08%，吞吐提高 0.85%， 但峰值负荷增加 3.38%。这组结果用于披露算法边际收益与多目标代价，不替代 上方“减少固定满配冗余”的场景口径。

The report also publishes a harder comparator: select an 80%/80% crane/yard-vehicle static configuration from nine candidates using only 2024 validation data, freeze it, and test in 2025. Against that comparator, MPC still reduces carbon by 2.84%, energy by 2.52%, and cost by 2.08%, while increasing throughput by 0.85%—but peak load rises 3.38%. This result discloses marginal algorithm benefit and the multi-objective trade-off; it does not replace the full-resource redundancy scenario above.

逐日船舶活动增强集的独立报告同样覆盖 48×24 个 2024 留出小时窗口：相对固定满配强基线，MPC 碳排降低 8.90%、情景成本降低 8.22%、吞吐保持 100.00%、约束满足 100%；相对验证集选择的 80%/80% 更严格基线，碳排仍降低 2.77%、成本降低 2.11%，但峰值增加 3.61%。见 enhanced benchmark。

The vessel-activity enhanced report evaluates 48×24 held-out hours from 2024. MPC reduces carbon by 8.90% and scenario cost by 8.22% versus the fixed full-resource comparator, with 100.00% throughput retention and 100% constraint satisfaction. Against the harder validation-selected 80%/80% comparator, carbon still falls 2.77% and cost 2.11%, while peak load rises 3.61%. These remain offline scenario results.

要求：Python 3.11+、Node.js 20+、pnpm。首次安装 PyTorch 可能需要数分钟。
Requirements: Python 3.11+, Node.js 20+, and pnpm. The first PyTorch installation may take several minutes.

git clone https://github.com/wenjiayi123/port-energy-carbon-cockpit.git
cd port-energy-carbon-cockpit
make bootstrap
make demo

• 驾驶舱 / Cockpit: http://127.0.0.1:5173/
• OpenAPI: http://127.0.0.1:8808/docs
• Readiness: http://127.0.0.1:8808/api/health/ready
• Metrics: http://127.0.0.1:8808/api/metrics

export OPERATOR_API_KEY="$(openssl rand -hex 24)"
make docker-up

Compose 将前后端绑定到 loopback，后端生产模式强制 API key；容器使用非 root 用户、只读文件系统、全部 capability drop 和独立 run/audit volume。面向互联网时仍应在前面配置 TLS、企业 SSO、每用户授权和集中式审计。
Compose binds both services to loopback and enforces an API key in backend production mode. Containers use non-root users, read-only filesystems, dropped capabilities, and dedicated run/audit volumes. Internet-facing deployments still need TLS, enterprise SSO, per-user authorization, and centralized audit retention.

cd backend

# 列出四种 RL 与 MPC / list four RL algorithms plus MPC
.venv/bin/python -m app.rl.cli algorithms

# 验证数据契约和哈希 / validate dataset contract and hashes
.venv/bin/python -m app.rl.cli validate-data port_la_2020_2024_vessel_activity_hourly

# 仅在 train 上训练，不渲染 / fit on train only, without rendering
.venv/bin/python -m app.rl.cli train \
  --algorithm sac \
  --dataset port_la_2020_2024_vessel_activity_hourly \
  --total-steps 120000 \
  --seed 20260720

# 训练完成后才在 test 上评估并生成轨迹 / held-out evaluation after fitting
.venv/bin/python -m app.rl.cli evaluate --strategy auto:latest

# 仅用validation选型 / tune on validation only; short runs must be marked smoke
PYTHONPATH=. .venv/bin/python -m app.rl.tuning \
  --algorithm all \
  --dataset port_la_2020_2024_vessel_activity_hourly \
  --steps 10000 \
  --final-seeds 11,29,47 \
  --output ../reports/rl_tuning_vessel_activity_10k.json

# 重算公开MPC报告 / recompute and verify the publishable MPC report
PYTHONPATH=. .venv/bin/python -m app.rl.benchmark run
PYTHONPATH=. .venv/bin/python -m app.rl.benchmark \
  verify ../reports/offline_benchmark_v3.json

# 在仓库根目录重建逐日船舶活动数据并复算增强报告
cd ..
make data-enhanced
make benchmark-enhanced
make verify-benchmark-enhanced

API 启动训练需要 confirm=true。训练进度来自 model.num_timesteps、callback 指标和实际耗时；ETA 使用已测 step rate 推导，不使用固定时长计时器。
API training requires confirm=true. Progress comes from model.num_timesteps, callback metrics, and measured elapsed time; ETA is derived from observed step rate, not a fixed-duration timer.

The enhanced package also includes a reproducible 10k multi-seed RL matrix: all four learners completed real fit/validation/test execution with zero modeled safety violations across the reported seeds. It is explicitly labelled short-budget comparative evidence, not convergence or production performance.

A separate 100k TD3 run is intentionally retained as rejected evidence: its split/artifact/safety checks passed, but it underperformed both constrained-control and fixed-resource comparators on carbon and scenario cost. It is not used as a positive metric.

算法不绑定洛杉矶港。使用稳定 canonical schema 和相邻 metadata 即可替换数据，而不改 learner 或驾驶舱。完整字段、单位与时序模式见 docs/DATASETS.md，模板见 docs/examples/port_dataset_template.csv。
Algorithms are not hard-coded to Los Angeles. Replace the data through the stable canonical schema and adjacent metadata without modifying the learner or cockpit. See docs/DATASETS.md and the CSV template.

python scripts/prepare_port_dataset.py \
  --input /path/to/tos_ems_export.csv \
  --output backend/app/data/datasets/my_port.csv \
  --temporal-mode sequential_rows \
  --time-col observed_at_utc \
  --environment-id PortEnergyDispatchEnv-v3 \
  --port-id my_port \
  --timezone Asia/Kuala_Lumpur \
  --currency MYR \
  --source-id my_port_snapshot \
  --source-url https://data-owner.example/evidence/snapshot \
  --license proprietary-authorized

cd backend
.venv/bin/python -m app.rl.cli validate-data my_port

• v3 的字段映射选项见 python scripts/prepare_port_dataset.py --help；缺少天气、泊位/设备/电网可用率、岸电兼容或可再生能源字段会 fail closed。完整流程见 实港接入蓝图。 / See the mapper help and the real-port blueprint; missing v3 deployment fields fail closed.
• profiled_period：适合公开月度/聚合 benchmark，按声明曲线构造 episode。 / for aggregate public benchmarks with a declared profile.
• sequential_rows：适合只读 TOS/EMS 小时快照，环境按不可变行推进。 / for immutable hourly TOS/EMS snapshots advanced row by row.
• CLI 可读取操作者明确提供的外部 CSV；HTTP API 只允许仓库已注册的数据集 ID，阻断任意文件路径访问。 / The CLI may read operator-supplied external CSV files; HTTP endpoints accept only registered dataset IDs and reject arbitrary filesystem paths.

完整交互 schema 以运行时 OpenAPI 为准。 / The runtime OpenAPI document is the authoritative interactive schema.

在接入真实港口前，必须完成 TOS/EMS 只读适配、参数校准、计量血缘、身份权限、shadow mode、回滚演练、人工验收和独立安全联锁。完整门槛见 生产就绪说明 与 威胁模型。
Before a real-port integration, provide read-only TOS/EMS adapters, parameter calibration, meter lineage, identity controls, shadow mode, rollback drills, operator acceptance, and an independent safety interlock. See production readiness and the threat model.

• 生产模式拒绝无 API_AUTH_MODE=api_key 的启动，key 最少 24 字符；viewer/operator/admin 分级。

• 变更请求写入 mutation-only JSONL 审计；所有请求有 request ID、结构化访问日志和基础安全头。

• HTTP 数据集参数限制在注册目录，策略 ID 使用格式白名单，避免路径穿越。

• CI 包含 Ruff、backend/RL 测试、数据校验、前端构建、依赖审计与容器构建。

• CodeQL、Dependency Review 与 OpenSSF Scorecard 在仓库公开后启用；私有预审阶段保持跳过，避免 GitHub Free 私有功能门槛造成假失败。

• Actions 使用完整 commit SHA；Dependabot 按月分组，控制更新噪声。

• Production refuses to start without API_AUTH_MODE=api_key; keys require at least 24 characters and support viewer/operator/admin roles.

• Mutation requests are written to a JSONL audit stream; every request receives an ID, structured access log, and baseline security headers.

• HTTP dataset references are confined to the registry and strategy IDs are format-allowlisted against path traversal.

• CI covers Ruff, backend/RL tests, dataset validation, frontend build, dependency audits, and container builds.

• CodeQL, Dependency Review, and OpenSSF Scorecard activate after the repository becomes public; they remain skipped during private review to avoid false failures from GitHub Free private-feature limits.

• Actions are pinned to full commit SHAs; Dependabot updates are grouped monthly to control noise.

安全问题请按 SECURITY.md 私下报告。 / Report vulnerabilities privately according to SECURITY.md.

make test       # backend API, accounting, Gymnasium and five-baseline smoke tests
make build      # TypeScript + Vite production build
make validate   # repository structure and default dataset contract

cd backend
.venv/bin/python -m ruff check app
.venv/bin/python -m pip_audit

cd ../frontend
pnpm audit --audit-level high

Intel macOS 仅能解析旧 PyTorch 2.2.2 wheel，当前已知漏洞使其只能作为兼容开发环境。安全发布门槛以 Linux CI/容器中解析的当前 PyTorch 版本为准，且不得加载不可信模型。
Intel macOS resolves only the legacy PyTorch 2.2.2 wheel; known vulnerabilities make it a compatibility-only development environment. The security release gate is the current Linux CI/container resolution, and untrusted model files must never be loaded.

backend/app/
  api/          FastAPI路由与信任边界 / routes and trust boundaries
  core/         配置、安全与可观测性 / configuration, security, observability
  rl/           数据契约、环境与训练服务 / contract, environment, training
  services/     能碳、市场、KPI与调度 / carbon, market, KPI, dispatch
  tests/        API、核算、环境与smoke测试 / API, accounting, environment, smoke
frontend/src/   双语React驾驶舱与小懿联动 / bilingual cockpit and Xiaoyi UI
configs/        能碳、KPI与港口默认参数 / declared carbon, KPI, port defaults
docs/           数据/模型卡、威胁与门禁 / cards, pipeline, threat, production gate
scripts/        安装、运行、校验与数据准备 / bootstrap, run, validation, data prep
.github/        CI、安全、模板与依赖策略 / security, templates, dependency policy

• RL pipeline / 强化学习管线
• Datasets and field contract / 数据与字段契约
• Data card / 数据卡
• Model card / 模型卡
• Module audit / 模块事实审计
• Production readiness / 生产就绪门槛
• Threat model / 威胁模型
• Asset provenance / 视觉资产来源
• Open-source release checklist / 开源发布清单

• 提交代码前阅读 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md。

• 路线图、维护者职责与决策流程见 GOVERNANCE.md。

• 使用问题与支持边界见 SUPPORT.md。

• 变更历史见 CHANGELOG.md。

• Read CONTRIBUTING.md and the CODE_OF_CONDUCT.md before contributing.

• Maintainer responsibilities and decisions are documented in GOVERNANCE.md.

• Support scope is documented in SUPPORT.md.

• Release history is tracked in CHANGELOG.md.

代码采用 MIT License。数据来源与 AI 辅助原创视觉资产的说明见 THIRD_PARTY_NOTICES.md 和 ASSET_PROVENANCE.md。Port of Los Angeles 名称与标识归其权利人所有；本项目与该港口不存在隶属或背书关系。
Code is licensed under the MIT License. Data attribution and AI-assisted original artwork provenance are documented in THIRD_PARTY_NOTICES.md and ASSET_PROVENANCE.md. Port of Los Angeles names and marks remain with their owners; this project is not affiliated with or endorsed by the Port.

引用信息见 CITATION.cff。 / Citation metadata is available in CITATION.cff.