# LinuxCNC Web/WASM

本仓库的目标是将 LinuxCNC `2.10.0~pre0` 的仿真行为移植到浏览器。当前已完成 posemath/TP、rs274ngc interpreter 和 fixed-tick motion queue 核心切片；这仍不是 LinuxCNC 全功能完成声明。

恢复或开始工作时，首先读取 [`nextTask.md`](nextTask.md)。它是唯一接续入口，刻意限制在 8 KiB 以内，不包含聊天记录、完整日志或历史证据。只有定位旧证据时才按需读取 [`docs/task-history.md`](docs/task-history.md) 和其中引用的产物。

## 当前状态

- LinuxCNC 来源基线：`linuxcnc/VERSION` 与 `context-lock.json`。
- 来源索引：`coverage/source-index.jsonl`，由 `scripts/generate_source_inventory.py` 生成。
- 覆盖种子：`coverage/manifest.jsonl`。所有条目初始为 `planned/needs_owner`，没有来源会被静默忽略。
- WASM ABI 骨架：`wasm-core/include/sim_api.h`；当前实现只验证生命周期、固定 tick、快照和状态导入导出。
- 前端、Worker、HAL、解释器、TP、Python、OPFS 和 UI 功能仍须按文档里程碑实现。
- `K0-INV-01`、`K0-INV-02`、`K0-ORACLE-01`、`K1-CONTRACT-01`、`K1-CONTRACT-02`、`K1-NUM-01`、`K2-TRIV-01`、`K2-TRIV-02`、`K2-COUPLED-01`、`K2-HAL-01`、`K3-5AXIS-01`、`K3-TRT-01`、`K3-ROBOT-01` 和 `K3-GENSER-01` 已完成；Genser melfa/puma560 DH、迭代 residual、固定上限和 native/WASM 对照见 `coverage/genser-kinematics.report.json`；其它运动学证据保持在对应 `coverage/*-kinematics.report.json`。旧 `M2-CORE-04` 因锁定来源缺少声明的 `linuxcnc/unit_tests/kinematics/**` 输入而保留为 blocked 证据。
- `K4-DELTA-01` 已完成 linear/rotary Delta 的统一解析 FK/IK、XYZ/extra-joint mapping、默认/alternate root、工作空间/限位/奇异边界和 native/WASM 对照；四个真实配置候选、缺失 HAL 资源和官方 oracle blocked 清单见 `coverage/delta-kinematics.report.json`。旧 `M2-CORE-04` 因锁定来源缺少声明的 `linuxcnc/unit_tests/kinematics/**` 输入而保留为 blocked 证据。
- `K4-TRIPOD-01` 已完成 point-vertex tripod 的统一 FK/IK/mapping；真实 `tripod.ini`/`tripodsim.hal`、XYZ/AD-BD-CD 映射、above/below 根分支、无解/基面奇异/限位/退化几何和 native/WASM state hash 对照见 `coverage/tripod-kinematics.report.json`。`nextTask.md` 当前进入 `K4-HEX-01`；官方 oracle 因锁定来源缺少 `linuxcnc/unit_tests/kinematics/**` 继续显式 blocked。
- `K4-HEX-01` 已完成 genhex 六腿 Stewart 平台的统一 FK/IK/mapping；真实 `hexapod.ini`/`kinematics.hal`、Newton 6x6 正解、闭式逆解、迭代/奇异/限位边界和 native/WASM 对照见 `coverage/genhex-kinematics.report.json`。`nextTask.md` 当前进入 `K4-PENTA-01`；官方 oracle 继续显式 blocked。

## 重建 M0

```bash
python3 scripts/generate_source_inventory.py
python3 scripts/validate_baseline.py
python3 -m unittest discover -s scripts -p 'test_*.py' -v
python3 scripts/validate_task_pointer.py
```

模型请求也必须先经过预算门禁：用 `scripts/context_packet.py` 生成固定 profile 的 packet，再运行 `scripts/validate_model_budget.py packet.json --context-window <window> --overhead-tokens <current-request-overhead>`。覆盖值只能缩小 profile；请求外开销不得包含上一轮聊天。请求返回后用 `validate_provider_response` 校验 provider usage，流式响应交给 `scripts/model_stream.py` 消费；断流、上下文超限、usage 缺失或截断只写 metadata-only checkpoint，并从更小的 packet 重建，绝不把旧响应拼回上下文。

## 编译 ABI 骨架

需要 Emscripten。该命令同时运行原生 ABI 单测并生成 `build-wasm/linuxcnc-sim-core.js`/`.wasm`：

```bash
scripts/build-wasm.sh
```

完整路线、功能完整性和退出门禁见 [`docs/linuxcnc-web-wasm-implementation-readiness.md`](docs/linuxcnc-web-wasm-implementation-readiness.md)。面向“完整移植仿真机床”的启动闭环、运行时依赖、固定 tick、资源闭包和分阶段产物见 [`docs/linuxcnc-web-wasm-full-port-implementation.md`](docs/linuxcnc-web-wasm-full-port-implementation.md)；运动学正逆解、机床类型分族、分支/奇异性和 K0-K8 主线见 [`docs/linuxcnc-web-wasm-kinematics-migration-plan.md`](docs/linuxcnc-web-wasm-kinematics-migration-plan.md)。专项设计仍分别位于 `docs/` 下的 roadmap、source map、coverage、communication、execution 和 playbook 文档。

依赖下载允许使用中国大陆镜像；请先阅读 `context-lock.json` 的 `downloads` 策略。镜像只改变传输位置，不能改变版本、文件字节或校验记录。