> ## Documentation Index
> Fetch the complete documentation index at: https://blockscope.linvin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Service

# 服务模式

`serve` 在 stdin/stdout 上使用 newline-delimited JSON，不监听网络端口。它适合
由受信任的上层服务、批处理工具或自动化管线作为子进程启动。

## 启动 worker

```bash theme={null}
blockscope serve --client-jar client.jar --threads 4 --cache 2
```

* `--threads`：请求未指定 `threads` 时使用的默认线程数；最多 256
* `--cache`：缓存的 scene/mesh 数量
* `--force-limits`：提高资源上限；只应对可信输入使用
* `--ignore-block-entity-nbt`：跳过容器 NBT

worker 在资源包准备完成后输出一行 `hello`，之后才接受 job。

## 请求示例

```json theme={null}
{
  "type": "render",
  "id": "job-1",
  "input": {
    "path": "/data/model.litematic"
  },
  "views": [45, 225],
  "width": 1024,
  "height": 1024,
  "supersample": 2,
  "outputDir": "/data/out"
}
```

* `input.path` 和 `outputDir` 必须是绝对路径
* 输入必须是普通文件
* `input.hash` 可选，用于校验 SHA-256
* `views` 为空时默认 `[45]`
* 输出文件为 `{id}.png` 或 `{id}-{yaw}.png`
* 完整字段、结果和错误码见 [引擎协议 v1](https://blockscope.linvin.net/engine-protocol.md)

## Supervisor

`supervise` 管理 worker 池、队列、超时和内存上限：

```bash theme={null}
blockscope supervise \
  --client-jar client.jar \
  --workers 2 \
  --threads 4 \
  --timeout 120 \
  --memory 2048 \
  --queue 4 \
  --cache 2
```

| 选项 | 说明 |
| - | - |
| `--workers` | worker 进程数；`0` 使用 `capacity` 建议值 |
| `--threads` | 每个 worker 的线程数；`0` 使用 `capacity` 建议值 |
| `--timeout` | 每个 job 的超时秒数；`0` 关闭 |
| `--memory` | 每个 worker 的内存上限（MiB）；`0` 根据可用内存推导 |
| `--queue` | 等待队列长度；`0` 使用 `workers * 2` |
| `--cache` | 每个 worker 缓存的 scene/mesh 数量 |

## 安全边界

`serve` 和 `supervise` 只应被可信调用方使用。输入路径、输出目录和资源包路径由
调用方控制；不要把 stdio 服务直接暴露给不可信网络客户端。

## 相关文档

* [引擎协议 v1](https://blockscope.linvin.net/engine-protocol.md)
* [Docker](https://blockscope.linvin.net/user/docker.md)
* [故障排查](https://blockscope.linvin.net/user/troubleshooting.md)
* [English](https://blockscope.linvin.net/user/en/service.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.