# Changelog

本文件记录 cps-twin 标准版（PyPI 包）的对外可见变更。版本号单一来源：
`scripts/pypi_assets/cps_twin/__init__.py` 的 `__version__`（同 ADR-0010）。
服务端/前端的专业版演进见 `docs/BACKLOG.md` 执行日志。

## [0.2.1] — 2026-11-11

- **CLI 体验对齐 quickstart 标准（家族实施计划：产品级体验批）**：
  - `simulate-warehouse` / `simulate-factory` 非 `--json` 模式改人读摘要
    （此前打印缩进 JSON——名"摘要"实为机读，风格割裂）；`--json` 口径不变；
  - `simulate-factory --params` 改可选：缺省用**包内样例参数**（此前 required
    且指引指向仓库 config/——wheel 用户没有仓库，是死路）；
  - `validate --layout` 改可选：缺省校验**包内内置仓储样例**（样例资产打包了
    却"不可发现"的收口）；
  - 顶层 `--version`；`validate` 文件不存在/JSON 损坏改优雅报错 + 修法提示
    （此前裸 FileNotFoundError 回溯）。
  - build 冒烟同步：人读/机读双确定性对拍 + 缺省样例路径覆盖。
- 确定性输出不受影响（人读摘要同样不含墙钟时间戳）。

## [0.2.0] — 2026-11-10

- **`cps-twin quickstart`（零参数一键体验）**：双域引擎内置样例各推一段 →
  人读摘要 + 下一步指引；`--json` 机读。缺省 3600 拍（实测选定下限：
  600/1800 拍两域尚在投料预热期、输出全 0；3600 拍约 20 秒，仓库 7.8 单/分、
  产线 OEE 0.5——一键体验必须看到真实节拍）。输出不含墙钟时间戳，同
  `--seed` 重跑逐位一致（ADR-0001 承诺变成用户当场可验证）；build 冒烟
  增 quickstart 两次连跑字节对拍 + 仓库级 CI 测试 `test_cps_twin_quickstart.py`。

## [未发布]

- 修复产线 / 仓储 WebSocket 子协议回显（不改变 wheel 行为）：accept 改读
  ASGI `scope["subprotocols"]`，不再依赖原始 header——`uvicorn --ws wsproto`
  下浏览器不再因握手未回显 `bearer.<jwt>` 而报 1006；演示脚本与文档统一
  `--ws websockets` 口径。
- 对外品牌口径更新（不改变 wheel 行为）：ILESP 统一称 **Hermes 同枢**，
  家族 Slogan 统一为 **同衡 · 谋序 · 同枢，智造同频**（替代“海神双芯”旧口径）；
  README / PyPI 页面 / 官网同步。产品包名与导入名仍为 `cps-twin`。
- 文档纠偏（不改变 wheel 行为）：README/CLI 的“逐位一致”限定为
  **同 seed + 同参数 + 同一 Python 运行时**（仓储域 mulberry32 跨运行时亦一致；
  产线域基于 CPython `random.Random`，不跨 Python 版本承诺位级一致）；
  并明示标准版不含实时运行循环（Live 倍速/追赶/实时性指标属专业版服务层）。
- 内核新增 `twin_runtime_core.pace.PaceAccumulator`（纯计算、无墙钟依赖，随包分发）：
  把“经过时间 × 倍速”折算成整数 tick，余数留到下一轮——专业版侧 2026-10-19
  用它修掉了“0.5× 被静默按 1× 跑”的倍速口径缺陷，并补上实时性指标
  （`cps_sim_realtime_factor` / `cps_sim_pace_clipped_ticks`）。

- 文本规范化（繁→简）：注释/文档/字符串字面量统一为简体中文（系统默认简体）。
  ⚠️ 附带影响：provenance.layout_hash 随之变化——该哈希覆盖整份布局 JSON
  （含 description 等中文文本），文本改字即改哈希。已实测引擎数值行为逐位一致
  （3600 拍 hashable 投影 5141 个路径中仅 layout_hash 一项不同），
  对拍基线按既有 CPS_REGEN 程序重生成。

## [0.1.3] — 2026-10-11

- 版权署名统一为 123AIoT（wheel 元数据 authors + LICENSE 文件随包分发）；
  仓库根补 LICENSE 文件（此前 MIT 声明仅见于文档，无许可证文件）。

## [0.1.2] — 2026-10-11

- 产品品牌定名：**Nereus 同衡**（万物同衡，虚实相应 · 体系：海神双芯，智造同频）。
  本版仅更新 PyPI 页面文案与 README 品牌横幅（官网 cps.123aiot.com 同步）；
  包名 `cps-twin`、导入名、CLI 与全部代码保持不变（`nereus` 在 PyPI 已被占用，
  见 ADR-0011——品牌为宣传名，非代码/包名变更）。
## [0.1.1] — 2026-10-11

- 修复：`load_params()` 在 wheel 内缺省路径不可达——`simulation_parameters.yaml` 随包分发
  （与 0.1.0 的 `factory_layout.json` 同款三级解析：环境覆盖 > 包内 > 仓库 config/），
  标准版 README 的库用法示例（`load_params()`）现在开箱即用。
## [0.1.0] — 2026-10-11

首个公共版本（标准版，MIT）。

- 确定性内核：`twin_runtime_core`（RngService 具名流 / SimulationClock 固定 tick / 事件总线 / 审计）
- 仓储引擎：`warehouse_twin.sim`（AMR/提升机/任务派工，mulberry32 位级可复现）
- 产线引擎：`domain_factory`（工位/输送带/返修，物料守恒不变式 + parameter_hash 溯源）
- 布局权威校验器：`twin_validator`（越界/重叠/接入点被封/连通性）
- headless CLI：`cps-twin simulate-warehouse / simulate-factory / validate`
- 发布形态：纯 Python 通用 wheel（py3-none-any），PyPI Trusted Publisher；
  3D 设计器/Copilot/网关等服务能力属专业版（GHCR 镜像 + compose 本地部署）
