# Previewer 调用契约

## 输入

```text
node scripts/serve_file.js FILE [--host IP] [--port PORT] [--ttl SECONDS]
```

- FILE：存在的普通文件；解析为规范绝对路径，服务其父目录。
- --host：默认 127.0.0.1；支持 IP 或 localhost（等价于 127.0.0.1）。0.0.0.0 表示所有 IPv4 接口。
- --port：默认 0，自动选择空闲端口；显式端口范围为 1..65535。
- --ttl：默认 3600 秒，允许 1..2147483；过期关闭该服务。

旧的 --mount-path、--local-port、--tailscale-port 参数不再接受。--port 现在仅表示 Node
静态服务的监听端口。脚本不读取或改写任何外部网络配置。

## 输出

成功时 stdout 输出单个 JSON，退出码为 0：

```json
{
  "file": "/workspace/preview/index.html",
  "directory": "/workspace/preview",
  "host": "127.0.0.1",
  "port": 43721,
  "pid": 12345,
  "ttl": 3600,
  "expiresAt": "2026-10-19T13:00:00.000Z",
  "url": "http://127.0.0.1:43721/index.html",
  "urls": ["http://127.0.0.1:43721/index.html"],
  "reused": false,
  "stopCommand": "kill -TERM 12345"
}
```

url 是该服务器的本地可访问入口。绑定所有接口时，urls 还列出系统网络接口的 IPv4 候选链接；
脚本不判断访问者在哪个网络，也不保证远端可达。路径含空格和中文时 URL 自动编码。
根路径 / 同样返回输入文件；HTML 的相对 CSS/JS/图片按原目录提供。

失败时 stderr 输出单个 JSON，例如：

```json
{ "code": "PORT_IN_USE", "message": "listen EADDRINUSE ..." }
```

错误码包括 ARGUMENT、FILE_INVALID、PORT_IN_USE、START_FAILED、START_TIMEOUT、
VERIFY_FAILED、BUSY；退出码为 2。成功 JSON 不包含认证探测 token。

## 重复调用和生命周期

脚本按规范化文件路径、host、请求端口和 ttl 建立服务标识。在系统临时目录内保存当前用户
的进程记录，启动通过目录锁串行化。调用时会以服务标识和探测 token 验证原进程；仍可用则
返回 reused: true，且不续期。否则重新启动并更新记录，不凭 PID 盲目停止进程。

服务在 ttl 到期或接到 SIGTERM/SIGINT 后停止。重复调用不意味着续期；要改变有效期可使用
新的 --ttl 参数或先停止原服务。调用方保存一次成功结果，之后直接使用 URL。