# LinuxCNC Web/WASM

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

完整仿真功能范围、任务分解和 M0-M8 里程碑见 [`完整仿真移植实施计划`](docs/linuxcnc-web-wasm-complete-simulation-plan.md)；技术实施接续入口为 [`nextTask1.md`](nextTask1.md)。

五轴 XYZAC TRT Web/WASM 源码对标轨道的独立接续入口为 [`nextTask-rtcp.md`](nextTask-rtcp.md)，详细设计和实施资料位于 [`doc-rtcp`](doc-rtcp/README.md)。

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

项目整体流程、LinuxCNC 案例到 WASM/Worker/前端的映射，以及后续任务起点见
[`系统流程与后续执行基线`](docs/linuxcnc-web-wasm-system-flow-and-execution-baseline.md)。
持续认领、依赖顺序、阻塞转移和逐项验收规则见
[`连续执行计划`](docs/linuxcnc-web-wasm-continuation-plan.md)。
持续执行时只需输入“按 `nextTask1.md` 接续执行”；完整操作提示词和停止边界见
[`持续执行提示词`](docs/linuxcnc-web-wasm-autonomous-execution-prompt.md)。

## 当前状态

- LinuxCNC 来源基线：`linuxcnc/VERSION` 与 `context-lock.json`。
- 来源索引：`coverage/source-index.jsonl`，由 `scripts/generate_source_inventory.py` 生成。
- 覆盖种子：`coverage/manifest.jsonl`。所有条目都必须保留来源、实现状态、测试和差异记录；没有来源的条目进入仿真 `BLOCKED`，不会静默忽略。
- WASM 核心和 Worker 已支持生命周期、固定 tick、快照/恢复、G-code `PROGRAM_LOAD/RUN/PAUSE/RESUME/ABORT/STEP/SEEK` 以及 `MDI_EXECUTE`；G-code 行通过 WASM `sim_interpreter_*` 执行，程序状态随 tick 返回。完整 LinuxCNC 仿真（配置全量启动、完整 TP/IK/motion 串联、HAL/Python/remap、恢复和 UI 融合）仍在持续移植，硬件驱动保持浏览器虚拟设备边界。
- 前端 AppShell、真实 WorkerClient、配置/HAL preflight、虚拟设备、Python bridge、恢复、浏览器兼容和全量回归均已有独立仿真证据。后续仿真任务只按 [`nextTask1.md`](nextTask1.md) 接续，不等待 owner 或发布审批。
- K0-K6 运动学实现主线已完成代码、ABI、固定边界和 native/WASM 回归，覆盖 trivkins、耦合运动学、5 轴/TRT、机器人、GenSer、Delta、Tripod、Hexapod、Pentapod、switchkins、userk/registry、TP→IK→motion、FK feedback、home/limit。缺少官方 oracle 的项目保留为 `BLOCKED_ORACLE`，不伪造结果，但不阻止其它仿真实现继续执行。
- 配置批量 runtime 已生成 264 个配置注册入口、233 个 sim entrypoint 和 16,093 条资源边；缺失、未解析和未索引资源均输出可定位诊断并继续作为仿真输入闭包处理。
- 路线对齐的 React 前端位于 `web/react`：React + TypeScript + Vite + Tailwind + Radix UI + Three.js，React 只通过 protocol.v1/WorkerClient 访问 Dedicated Worker；FE-M1 构建证据见 `coverage/react-frontend-m1.report.json`。
- AXIS 主界面完全对标的源程序功能清单、菜单/工具栏/状态门控、严格差异流程、任务分解和 M0-M7 验收门槛见 [`LinuxCNC AXIS 完全对标规范与执行计划`](docs/linuxcnc-axis-complete-parity-spec.md)。该文档以锁定的 `linuxcnc/share/axis/tcl/axis.tcl`、Gremlin/GLCanon、原始 bitmap 和 `configs/sim/axis` 为唯一 source oracle。

## 当前发布范围

`coverage/release-authorized-gate.report.json` 是当前 selected-case Web/WASM
仿真包的主动发布 gate，必须通过 `python3 scripts/validate_publish_gate.py`。
它由用户明确授权的风险豁免驱动，允许发布固定
`3axis-tutorial` 案例；历史 K8/T7 `STOP_RELEASE` 报告仍保留为技术审计证据，
不被重写成全量 LinuxCNC parity、官方 oracle、Safari 支持、完整配置资源或全仓
license closure。

React 前端构建和预览：

```bash
cd web/react
npm install --registry=https://registry.npmmirror.com
npm run typecheck
npm run build
npm run preview -- --port 5174
```

## 重建 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` 策略。镜像只改变传输位置，不能改变版本、文件字节或校验记录。