# 在本地运行 MoonCam

## 准备环境

安装 [MoonBit](https://www.moonbitlang.com/download/)，确保 moon 在 PATH 中。要求 moonc 不低于 0.10.16，仓库与 CI 使用固定版本 0.10.16+b1a0e846e。运行网页或命令行还需要 Node.js 22+；只调用 MoonBit 库不需要 Node.js。

```sh
git clone https://github.com/huahai29/mooncam.git
cd mooncam
```

检查实际使用的编译器：

```sh
moonc -v
npm run toolchain:check
```

构建会拒绝低于 0.10.16 的编译器；CI 使用 .moonbit-version 中的精确版本。安装新版后若仍显示旧版，请检查 PATH 和 MOON_HOME 是否指向同一套 SDK，避免混用编译器与标准库。

## 网页

```sh
npm run build
npm run serve
```

看到 MoonCam: http://127.0.0.1:4173/ 后，用同一台电脑的浏览器访问该地址。保持服务终端运行，Ctrl+C 会停止服务。首次构建后，重新打开只需 npm run serve；更新或修改源码后需要重新构建。运行网页不需要安装 npm 开发依赖。

如果修改了计算源码，构建会检查源码指纹。先执行 moon fmt，再执行 node scripts/version.mjs --write，然后 moon fmt --check、moon info 和 npm run build。详细含义见[版本追溯与性能护栏](版本追溯与性能护栏.md)。

| 问题 | 处理方法 |
| --- | --- |
| 浏览器无法连接 | 执行 npm run serve，确认终端出现监听地址且没有退出 |
| 重启后打不开 | 本地服务不会自动启动，重新执行 npm run serve |
| 提示 EADDRINUSE | 4173 端口被占用；先确认是否已有 MoonCam 服务，或处理占用该端口的程序 |
| 页面打开但引擎加载失败 | 执行 npm run build，再通过 HTTP 地址刷新页面 |
| 其他电脑不能访问 | 127.0.0.1 指访问者自己的电脑；本地服务只监听本机，分享请使用在线工作台 |

## 命令行

构建后执行：

```sh
node bin/mooncam.mjs examples/workshop.json --out artifacts/workshop
```

目录中会生成 profile.svg、profile.csv、profile.dxf、report.json 和 input.json。输入配置用于复算，报告保留摘要、生成版本与文件引用。

| 退出码 | 含义 |
| --- | --- |
| 0 | 局部采样条件满足，折线检查完成且确定零交叉 |
| 2 | 采样检查拒绝 |
| 3 | 搜索未找到候选 |
| 4 | 检查未完成或无法确定 |
| 1 | 输入或运行错误 |

拒绝方案仍可以导出，便于检查原因。报告和退出码的完整约定见[接口契约](接口契约.md)。

## 配套算例

| 输入 | 用途与预期结果 |
| --- | --- |
| [workshop.json](../examples/workshop.json) | 20 mm 升程、40 mm 基圆、4 mm 滚轮；最大压力角约 27.61° |
| [pressure-limit.json](../examples/pressure-limit.json) | 5 mm 基圆；压力角超限，退出码 2 |
| [pressure-adjusted.json](../examples/pressure-adjusted.json) | 36 mm 基圆；三档采样比较，退出码 0 |
| [crossing-profile.json](../examples/crossing-profile.json) | 诊断反例；2 组确定交叉边对，退出码 2 |
| [offset-follower.json](../examples/offset-follower.json) | 10 mm 偏置；观察压力角与轮廓变化 |
| [size-search.json](../examples/size-search.json) | 5～100 mm、1 mm 间隔搜索；得到 36 mm 候选，复核压力角约 29.52° |

36 mm 是有限网格的首个通过候选，不代表连续参数空间中的最小尺寸。操作过程和实测对照见[完整案例](完整操作案例.md)。

## 只运行 MoonBit 示例

```sh
moon test --target wasm-gc
moon run examples/library --target wasm-gc
```

示例直接调用核心库，输出最大压力角、最小局部偏置因子与点数。核心 API 使用弧度、rad/s 和一致的长度单位；JSON 与网页使用毫米、角度和 rpm。