feat: upadte

skills/previewer/references/contract.md

@@ -3,15 +3,19 @@
 ## 输入
 
 ```text
-python3 scripts/serve_file.py FILE [--mount-path PATH] [--port PORT]
+node scripts/serve_file.js FILE [--mount-path PATH] [--port PORT] [--local-port PORT] [--ttl SECONDS]
 ```
 
 - `FILE`：必须是存在的普通文件，建议使用绝对路径。
 - `--mount-path`：以 `/` 开头的 URL 路径，不能包含 `?`、`#`、空段或 `..`；不提供时按父目录名生成。
-- `--port`：HTTP 端口，默认 `80`。
+- `--port`：Tailscale 对外 HTTP 端口，默认 `80`。
+- `--local-port`：Node 监听的 localhost 端口，默认自动选择空闲端口。
+- `--ttl`：服务存活时间，单位为秒，默认 `3600`（1 小时）；到期同时关闭 Node 服务和对应
+  Tailscale Serve 路由。
 
-脚本服务 `FILE` 的父目录，而不是把文件复制到其它地方。这样 HTML 可以加载同目录的 CSS、
-图片和其它资源，但也意味着同目录其它文件会对 tailnet 可见。
+Node 服务 `FILE` 的父目录，而不是把文件复制到其它地方。这样 HTML 可以加载同目录的 CSS、
+图片和其它资源，但也意味着同目录其它文件会对 tailnet 可见。Node 只监听 `127.0.0.1`，
+Tailscale Serve 负责把指定路径代理到这个本地端口。
 
 ## 输出
 
@@ -24,8 +28,12 @@ python3 scripts/serve_file.py FILE [--mount-path PATH] [--port PORT]
   "mountPath": "/preview/billing",
   "ip": "100.101.102.103",
   "port": 80,
+  "localPort": 43721,
+  "pid": 12345,
+  "ttl": 3600,
+  "expiresAt": "2026-10-11T13:00:00.000Z",
   "url": "http://100.101.102.103/preview/billing/prd-v002.html",
-  "stopCommand": "tailscale serve --http=80 --set-path=/preview/billing off"
+  "stopCommand": "kill 12345 2>/dev/null || true; tailscale serve --http=80 --set-path=/preview/billing off"
 }
 ```
 
@@ -33,10 +41,9 @@ python3 scripts/serve_file.py FILE [--mount-path PATH] [--port PORT]
 
 ## 状态和冲突
 
-脚本先读取 `tailscale serve status --json`。如果相同 mount path 已指向相同目录，可以复用；如果
-指向其它目录，必须失败并要求新的 mount path。没有该路由时追加 `--set-path` 配置，不重置已有
-Serve 配置。
+脚本先读取 `tailscale serve status --json`，确认当前 Tailscale Serve 可用，然后启动 Node 本地
+服务并追加指定 `--set-path` 路由。应为不同预览使用不同 mount path；脚本不会执行全量重置。
 
-Serve 配置由 Tailscale 持久保存；`--bg` 路由会在 Tailscale 重启后恢复。停止时只能使用输出的
-同端口、同 mount path 的 `off` 命令，不能使用 `tailscale serve reset`，因为 reset 会清除该节点
-的全部 Serve 配置。
+Serve 配置由 Tailscale 持久保存，但 Node 服务默认在 1 小时后自动关闭并清理对应路由。需要
+提前停止时使用输出的命令，不能使用 `tailscale serve reset`，因为 reset 会清除该节点的全部
+Serve 配置。