# CPS 新手入门手册

> 从零到跑通"设计 → 校验 → 试跑 → 运行监控"的完整上手指南。约 30 分钟。
> 前置知识：无需数字孪生经验；会用浏览器、会开命令行即可入门，会 React/Python 可做二次开发。


## 0. 先看全局：一条流水线，四个动作

<svg viewBox="0 0 860 150" fill="none" xmlns="http://www.w3.org/2000/svg">
  <defs><marker id="gs" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M0 0 L9 4.5 L0 9 Z" fill="#1c4fe8"/></marker></defs>
  <rect x="18" y="38" width="168" height="64" rx="12" fill="#eef2ff" stroke="#1c4fe8" stroke-width="1.6"/>
  <text x="102" y="64" text-anchor="middle" font-size="14" font-weight="700" fill="#1a1a2e">① 设计</text>
  <text x="102" y="86" text-anchor="middle" font-size="11" fill="#5a6280">Studio 2D/3D 摆布局</text>
  <rect x="244" y="38" width="168" height="64" rx="12" fill="#eef2ff" stroke="#1c4fe8" stroke-width="1.6"/>
  <text x="328" y="64" text-anchor="middle" font-size="14" font-weight="700" fill="#1a1a2e">② 校验</text>
  <text x="328" y="86" text-anchor="middle" font-size="11" fill="#5a6280">权威规则 · 拦截导出</text>
  <rect x="470" y="38" width="168" height="64" rx="12" fill="#1c4fe8"/>
  <text x="554" y="64" text-anchor="middle" font-size="14" font-weight="700" fill="#ffffff">③ 试跑</text>
  <text x="554" y="86" text-anchor="middle" font-size="11" fill="rgba(255,255,255,.9)">一键拉起引擎</text>
  <rect x="696" y="38" width="146" height="64" rx="12" fill="#eef2ff" stroke="#00a8d6" stroke-width="1.6"/>
  <text x="769" y="64" text-anchor="middle" font-size="14" font-weight="700" fill="#1a1a2e">④ 运行/推演</text>
  <text x="769" y="86" text-anchor="middle" font-size="11" fill="#5a6280">LIVE KPI · 影子对拍</text>
  <path d="M186 70 H236" stroke="#1c4fe8" stroke-width="2" marker-end="url(#gs)"/>
  <path d="M412 70 H462" stroke="#1c4fe8" stroke-width="2" marker-end="url(#gs)"/>
  <path d="M638 70 H688" stroke="#1c4fe8" stroke-width="2" marker-end="url(#gs)"/>
</svg>

---

## 1. 环境要求

| 软件 | 版本 | 用途 |
|---|---|---|
| Node.js | ≥ 20（开发用 22） | studio 前端 + contracts 管道 |
| Python | ≥ 3.11（开发用 3.14） | 双域引擎 / 校验器 / design-server |
| 浏览器 | Chrome / Edge 均可 | studio 界面 |

一次性安装（在 `CPS/` 目录下）：

```bash
cd apps/studio && npm install
```

> 3D 资产（工艺单元/机械臂/货架 glTF）已随仓库内置于 `apps/studio/public/assets/models/`，无需额外安装。

Python 依赖（首次）：
```bash
pip install fastapi uvicorn pydantic websockets python-dotenv pyyaml httpx pytest
```

> ⭐ **推荐口径（2026-11-10 与 CI 对齐）**：装了 [uv](https://docs.astral.sh/uv/) 的话，
> 一条命令等价于 CI 的安装口径（含 ai 组——**不装 ai 组则 Copilot 真路径不可导入**，
> 只会走降级）：
> ```bash
> uv sync --all-groups
> ```
> 上面的手工 `pip install` 只覆盖最小组，适合只想快速跑通 ①② 的场景；
> 要跑测试/网关/Copilot，请用 `uv sync --all-groups`。

---

## 2. 三个进程（最简启动）

打开三个终端，都在 `CPS/` 下：

```bash
# ① 设计器前端（必须）
cd apps/studio && npm run dev
#    → http://localhost:5174

# ② 设计器后端（推荐：权威校验门禁 + 一键试跑编排 + 服务器布局库）
cd apps/design_server && python -m uvicorn main:app --port 8100

# ③ 引擎后端不用手动启动——点「▶ 试跑」时由 design-server 自动拉起
```

> 只启动 ① 也能用编辑器（保存时提示"按预览校验放行"）；② 在线则导出门禁、试跑编排、服务器布局库全部生效。

### 2.1 可选：引擎常驻（演示/联调用）

不想每次点试跑、或要做长时间演示时，可让引擎常驻。**注意导入方式**：
`factory_backend` 是包（`apps/` 下），必须按包导入；直接 `cd apps/factory_backend && uvicorn main:app`
会因相对导入崩掉（实测踩过）。推荐用演示脚本一键拉起（detached，不受终端关闭影响）：

```bash
python scripts/demo_up.py --factory   # warehouse(8000) + design(8100) + factory trial(8010)
python scripts/demo_up.py --stop      # 全部停止
# 演示账号：runtime/demo-auth.db（在 packages/ 下跑：cd packages && python -m auth.cli create-admin --user admin——auth 包不在 uv workspace 安装路径里，从仓库根跑会 ModuleNotFoundError）
# 日志：runtime/demo/*.log；studio: cd apps/studio && npm run dev
```

或手工（三个终端；**PYTHONPATH 分隔符平台不同**：Windows `;` / POSIX `:`，POSIX 下整串必须加引号）：

```bash
# Git Bash / Linux / macOS（冒号 + 引号）
cd apps/server && export PYTHONPATH="../../packages:../../services:../.." && python -m uvicorn main:app --port 8000
cd apps && export PYTHONPATH="../packages:../services:.." && python -m uvicorn factory_backend.main:app --port 8010 --ws websockets
```
```powershell
# PowerShell（分号；$env: 逐会话设置）
cd apps/server; $env:PYTHONPATH = "..\packages;..\services;.."; python -m uvicorn main:app --port 8000
```

> 一键试跑会占用 8000/8010 端口（防端口劫持门禁：带 trial 标记的实例可被新试跑安全顶替，
> 用户常驻无标记实例会被拒绝并提示）——常驻与试跑并存时用 `TWH_TRIAL_WH_PORT`/`TWH_TRIAL_RF_PORT` 错开端口。

---

## 2.5 三层上手路径与示例场景库（10 秒 → 5 分钟 → 30 分钟）

> **10 秒看到有意义的画面 / 5 分钟跑通一个场景 / 30 分钟看懂一次推演。**
> 示例库全部是**确定性仿真数据**（固定 `seed=7`、工艺参数为演示级工业假设），
> **不是现场实测值**；UI 上沿用 R5 演示数据横幅，禁止混入生产数据路径。

### L1 · 60 秒：一条命令起全栈

```bash
python scripts/demo_up.py --factory    # warehouse(8000) + design(8100) + factory trial(8010)
python scripts/demo_up.py --stop       # 收工时停全部
```

打开运行视图即看到 LIVE KPI / 机器人 / 事件流。演示回放横幅已标注"非实时数据"（R5）。
演示账号与常见问题见上文 §2.1。

### L2 · 5 分钟：加载一个示例，让洞察面板出数

```bash
python scripts/examples_cli.py list                              # 看 8 个示例
python scripts/examples_cli.py show factory-bottleneck-welding  # 看"演示什么 + 该问什么"
python scripts/examples_cli.py request factory-bottleneck-welding  # 生成可直接执行的 curl
```

`request` 生成带 `Authorization: Bearer $CPS_TOKEN` 的 curl 命令（令牌走环境变量，
不进 shell 历史），直接 POST 到 `/api/scenarios`（产线）或 `/api/whatif`（仓储），
回传 Baseline vs Scenario 的 KPI delta 与解释。**LIVE 引擎不受影响**——推演靠
复制状态而非 re-seed，这也是同 seed 结果逐位一致的原因（R6）。

**也可以完全走界面**：登录 studio 后，工作台顶栏点「示例场景」打开
`ExamplesPanel` —— 按 L2/L3 分组列出同一份示例库，展示域 / 标题 / 预计分钟数 /
演示什么 / 预期洞察 / Copilot 追问 / 关联联锁规则，并可「复制请求体」或
「问 Copilot」（后者会带着预置追问直接打开运行态 Copilot 面板）。示例清单是
**构建期生成物**（`scripts/export_examples.py` → `apps/studio/src/data/examples.ts`），
不新增后端端点、不扩大鉴权面；R5 仿真数据声明在面板内可见。

### L3 · 30 分钟：把一次推演问成一条证据链

每个示例都绑定 `copilot_prompt` 与 `copilot_followup`。跑完 L2 后把追问发给
Copilot，让它用只读工具（`query_kpis` / `query_events` / `query_zones` …）给出
证据链和 citations，再跑 what-if 对比或敏感度扫描——**推演链而不是图表是主角**。

两个最能体现"AI 原生确定性孪生"的示例：

- `factory-interlock-battery-trip`：引擎按确定性规则表自动发 `SAFETY_INTERLOCK`
  （WARN → TRIP → INFO clear），TRIP 级 Copilot **只能 `propose_action` 生成 HITL
  审批卡**，人工确认前引擎状态零变化（observe-only v1）；规则表可从
  `/api/capabilities` 的 `capabilities.interlocks` 读到，外部 AI 无需猜语义。
- `warehouse-task-burst`：20 次衍生 seed 给出 Δ 的 min/median/max 区间，用来区分
  **模型内部随机变异**与**真实世界不确定性**（诚实降级，R5）。

### 示例清单

| ID | 域 | 层级 | 演示什么 |
|---|---|---|---|
| `factory-bottleneck-welding` | factory | L2 | 瓶颈识别：焊接工位刀具故障 |
| `factory-interlock-battery-trip` | factory | L3 | 孪生自我预警 + HITL 提案 |
| `factory-conveyor-jam` | factory | L2 | 物料断供：段间输送线卡阻 |
| `factory-takt-miss` | factory | L3 | 节拍未达与敏感度推演 |
| `warehouse-zone-congestion` | warehouse | L2 | 拥堵对比与 `ZONE-CONG` TRIP |
| `warehouse-robot-battery` | warehouse | L3 | 电量临界联锁 + Copilot 追问 |
| `warehouse-robot-failure` | warehouse | L2 | 单机故障与确定性复跑 |
| `warehouse-task-burst` | warehouse | L3 | 任务洪峰与蒙特卡洛区间 |

### 新增示例怎么保证不漂移

`tests/test_examples.py` 是示例库的契约闸门：注入类型用 AST 直接从源码常量
（`FACTORY_INJECTION_KINDS` / `WAREHOUSE_INJECTION_KINDS`）读取，仓储 injections
交给引擎自己的 `TypeAdapter(ScenarioInjection)` 校验，并强制每个示例有固定 seed、
R5 数据源标注、Copilot 追问样例与 citations。新增示例只写 JSON + 在
`config/examples/index.json` 登记，然后跑 `pytest tests/test_examples.py -q`。
前端生成物另有 `apps/studio/tests/examplesData.test.ts` 与
`tests/test_examples_generated.py` 两道闸门，改了 JSON 必须跑 `npm run contracts`
重新生成（否则 `contracts:check` 会拦）。

### 文档站与离线演示编排

- `npm run docs:check`：校验 `mkdocs.yml` 的 13 个导航页与全仓 116 条内链；
  `npm run docs:serve` 本地起文档站（需先安装 `mkdocs` + Material）。
- `npm run demo:plan`：打印 X6 的 L1/L2/L3 离线演示编排（纯本地、不联网、不写文件）；
  `npm run demo:plan:check` 校验 8 个示例文件与 R5 标注，已串入 `npm run ci`。
  公网 Live Demo 仍待云资源 / Docker 实测 / 渗透测试等外部前置，见
  [LIVE_DEMO_READONLY.md](./LIVE_DEMO_READONLY.md)。

---

## 3. 界面导览（30 秒）

```
┌──────────────────────────────────────────────────────────────┐
│ 顶栏：新建▾ 打开… 保存/导出 ▶试跑 数据绑定 样例 布局库          │
│       [文件名] [域徽章] [#layout_hash]   ↶撤销 ↷重做 质量▾     │
├──────────────────────────────────────────────────────────────┤
│ 副栏：3D预览 | 2D编辑 | ▶运行   楼层切换   工具条（吸附/旋转/   │
│       复制/阵列/删除…）  提示文字                              │
├────────┬─────────────────────────────────┬───────────────────┤
│ 左面板  │          主视图                  │ 右面板             │
│ 对象库  │  3D 预览 / 2D 编辑 / ▶运行        │ 属性面板（选中     │
│ 对象树  │                                 │ 对象时）/场景设置   │
│ ⚠即时校验│                                 │                   │
├────────┴─────────────────────────────────┴───────────────────┤
│ 状态栏：布局摘要 · 对象计数 · 选中数 · 撤销/重做数              │
└──────────────────────────────────────────────────────────────┘
```

- **左面板**：对象库（点选后在 2D 画布放置；"点/框/线"=三种放置手势）、对象树（单击选中、Shift 加选）、⚠即时校验（违例点击定位）
- **2D 编辑**：主编辑视图——单击选中、拖拽移动（0.5m 吸附+对齐辅助线）、空白处拖拽=框选、Shift 加选
- **3D 预览**：实时渲染（编辑即时生效）；左键旋转/右键平移/滚轮缩放
- **▶ 运行**：试跑后出现——连接徽章/时钟/KPI/事件日志/模拟控制

![Studio 全景：3D 设计器 + 对象库 + 属性面板](guide-assets/studio-designer.png)

---

## 4. 核心工作流

### 工作流 A：从模板建一个仓库并试跑（最快出效果，5 分钟）

1. **新建 ▾ → 「📋 标准仓」**（4 排×10bay + 夹层，与上游样例同构）
2. 点 **「▶ 试跑」**——design-server 自动：权威校验 → 写契约 → 拉起引擎 → 健康检查
3. 自动切入 **▶ 运行** 视图：看 ● LIVE 徽章、KPI、事件日志、3D 里 20 台 AMR 跑任务
![运行视图：LIVE 徽章 + OEE/节拍/良品 KPI + 实时事件流](guide-assets/studio-run-live.png)

4. 试试控制条：⏸ 暂停 / 5× 加速 / ↺ 重置
5. 点「退出运行」回编辑器

> 模板生成的布局已通过全部权威校验（含 384 个接入点连通性）。

### 工作流 B：从零手摆一个仓库（体验编辑器核心）

1. **新建 ▾ → 空白仓储布局**
2. 左面板点「充电桩」→ 在 2D 画布下方点几下放置；点「货梯」放在场地东缘
3. 框选几个对象 → 工具条「阵列」→ 行×列+间距 → 生成
4. 拖动任意对象：注意粉色**对齐辅助线**与吸附
5. 点「保存/导出」：**权威校验通过 ✓** 后下载 JSON（未过会拦截并显示原因——试试把货架拖到重叠位置再导出）
6. **▶ 试跑**：你设计的布局正在引擎里运行

常用快捷键：`Ctrl+Z/Y` 撤销重做 · `Ctrl+D` 复制 · `R` 旋转 90° · `Delete` 删除 · `Esc` 退出放置/清空选择

### 工作流 C：产线域 + 工艺流向 + 参数（体验"通用"）

1. **新建 ▾ → 产线布局 → 样例**（载入上游产线样例：4 工艺单元/9 停靠点/走廊）
2. 内置参数已随「样例」自动载入（3 条工艺流向箭头已出现）；也可顶栏 **「导入参数」** 选择自定义参数 YAML
3. 副栏 **「工艺流向」**：依次点击两个工艺单元 = 连一条流向（链式，Esc 退出）；选中箭头可在右侧属性面板改起终点
4. 顶栏 **「参数」**：结构化编辑节拍/缓存区容量/派工策略/故障时长/能耗（每次编辑可撤销）
5. **「▶ 试跑」**：产线引擎按你的布局+参数运行（新页签打开产线控制台）

> 导出产线域 = 双文件：`factory_layout.json` + `simulation_parameters.yaml`（conveyors 由流向同步）。

### 工作流 D：数据绑定与前向推演（P3，体验"在线孪生"入口）

1. 先 **▶ 试跑**（要有 LIVE 引擎）
2. 顶栏 **「数据绑定」**：
   - 数据源选「模拟 PLC」→ 注册数据源
   - 点表已预填（`plc.r01.battery -> robots.R01.battery`）
   - 点「拉取并标定（poll）」——看三列：外部值 / 引擎值 / **偏差**（影子统计随之累计）
   - 点「推演」——**从当前（标定后）状态预测未来**的吞吐曲线
![数据绑定面板：数据源 → 点表 → 标定 → 前向推演 → 影子引擎](guide-assets/studio-gateway.png)

3. 白名单说明：只有标量遥测可标定（电池/统计/传感器）；机器人位置/FSM 不开放（引擎一致性保证）

---

## 5. 文件与数据在哪

| 内容 | 位置 |
|---|---|
| 导出的布局/参数文件 | 浏览器下载目录 |
| 服务器布局库 | `CPS/runtime/layouts/`（design-server 持久化） |
| 试跑写入的引擎契约 | 仓储 `packages/domain_warehouse/warehouse_twin/warehouse_layout.json`；产线 `CPS/config/`（双文件） |
| 草稿自动保存 | 浏览器 localStorage（刷新自动恢复，状态栏"●"表示未保存改动） |
| glTF 资产 | `apps/studio/public/assets/models/`（属性面板填 `/assets/models/xxx.glb`） |
| demo 回放缓存 | `CPS/runtime/demo/` |

---

## 6. 测试与质量门禁

```bash
npm run ci            # 全量：契约防漂移 → 双域校验 → 双域引擎对拍 → studio 136 项（18 文件）
npm run contracts     # 重新生成契约（Pydantic→Schema→TS）
npm run validate      # 双域样例权威校验
npm run test:parity   # 引擎黄金快照回归（自足，防漂移闸门）
cd apps/design_server && python -m pytest tests -q    # design-server 6 项
```

改了引擎/wire 模型 → `npm run contracts:check` 会拦截漂移；改了布局校验规则 → twin_validator 与 TS 预览件的 golden 对拍会要求两侧同步。

---

## 7. 故障排查（FAQ）

| 现象 | 原因与处理 |
|---|---|
| 页面黑屏 + "渲染异常" | 草稿由旧版本保存缺新字段——点「清除草稿并重载」（草稿内容仍可导出排查） |
| 「▶ 试跑」提示健康检查超时 | 引擎 pre-roll 需要时间（产线 144000 ticks）；或端口被占——`netstat -ano \| findstr :8000` 查占用并 kill；或看「停试跑」旁提示 |
| 试跑后运行视图一直"重连中…" | 后端只监听 IPv4——确认地址是 `127.0.0.1:8000` 而非 `localhost`；产线后端需 CORS 白名单含 studio 页地址（试跑编排已自动注入） |
| 保存/导出提示"校验未通过" | 看违例原因（左面板 ⚠ 列表有定位）；这是**门禁在工作**——修好再导出 |
| 属性面板数值改完弹回 | 超出字段范围（标红）——按 hint 修正 |
| 3D 里机械臂不动 | 运行视图才有动画；且只有 RUNNING/WAITING 状态会走姿势插值 |
| 想要真实设备外观 | 对象属性填 glTF 路径（见 `apps/studio/public/assets/models/README.md`） |

---

## 8. 下一步读什么

- 想理解系统怎么设计的 → [ARCHITECTURE.md](./ARCHITECTURE.md)
- 想给团队/领导演示 → [DEMO_SCRIPT.md](./DEMO_SCRIPT.md)
- 想了解为什么这样设计/演进路线 → [CPS_FEASIBILITY.md](./CPS_FEASIBILITY.md) 与 [CPS_ARCHITECTURE_ROADMAP.md](./CPS_ARCHITECTURE_ROADMAP.md)
- 想跟踪开发进度 → [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)
