.pouch/skills/previewer/references/contract.md

Previewer 调用契约

输入

python3 scripts/serve_file.py FILE [--mount-path PATH] [--port PORT]

• FILE：必须是存在的普通文件，建议使用绝对路径。
• --mount-path：以 / 开头的 URL 路径，不能包含 ?、#、空段或 ..；不提供时按父目录名生成。
• --port：HTTP 端口，默认 80。

脚本服务 FILE 的父目录，而不是把文件复制到其它地方。这样 HTML 可以加载同目录的 CSS、 图片和其它资源，但也意味着同目录其它文件会对 tailnet 可见。

输出

成功时输出单个 JSON 对象：

{
  "file": "/workspace/docs/prd-v002.html",
  "directory": "/workspace/docs",
  "mountPath": "/preview/billing",
  "ip": "100.101.102.103",
  "port": 80,
  "url": "http://100.101.102.103/preview/billing/prd-v002.html",
  "stopCommand": "tailscale serve --http=80 --set-path=/preview/billing off"
}

失败时输出到 stderr，退出码非 0；调用方不能把部分 stdout 当成有效 URL。

状态和冲突

脚本先读取 tailscale serve status --json。如果相同 mount path 已指向相同目录，可以复用；如果 指向其它目录，必须失败并要求新的 mount path。没有该路由时追加 --set-path 配置，不重置已有 Serve 配置。

Serve 配置由 Tailscale 持久保存；--bg 路由会在 Tailscale 重启后恢复。停止时只能使用输出的 同端口、同 mount path 的 off 命令，不能使用 tailscale serve reset，因为 reset 会清除该节点 的全部 Serve 配置。