feat: upadte

skills/previewer/SKILL.md

@@ -8,8 +8,9 @@ description: >-
 
 # Previewer：Tailnet 静态文件预览
 
-调用方只提供一个要展示的文件。Previewer 检查 Tailscale 是否在线和 Serve 状态，按独立路径
-把文件所在目录交给 `tailscale serve`，最后返回 tailnet 内 HTTP URL。
+调用方只提供一个要展示的文件。Previewer 检查 Tailscale 是否在线和 Serve 状态，启动一个
+Node 本地静态服务，再让 `tailscale serve` 代理这个 localhost 端口，最后返回 tailnet 内
+HTTP URL。
 
 ## 何时使用
 
@@ -25,19 +26,22 @@ description: >-
 
 ## 调用方式
 
-找到本 skill 目录 `<previewer-skill-dir>`，执行：
+前置条件：本机安装 Node.js 和 Tailscale，并已登录目标 tailnet。找到本 skill 目录
+`<previewer-skill-dir>`，执行：
 
 ```bash
-python3 <previewer-skill-dir>/scripts/serve_file.py \
+node <previewer-skill-dir>/scripts/serve_file.js \
   <absolute-file-path> \
   --mount-path /preview/<stable-name>
 ```
 
-脚本默认使用 HTTP 80 端口；可用 `--port` 指定其它端口。它输出 JSON，包含文件、挂载目录、
-mount path、Tailscale IPv4 和最终 URL，适合被其它 skill 读取。
+脚本默认使用 Tailscale HTTP 80 端口，并为本地 Node 服务自动选择空闲端口；可用 `--port`
+指定 Tailscale 对外端口、`--local-port` 指定本地端口。Node 服务默认 1 小时后自动关闭，
+到期时同时关闭对应 Serve 路由；可用 `--ttl` 以秒覆盖。它输出一个 JSON，包含文件、挂载目录、
+本地进程 PID、过期时间、Tailscale IPv4 和最终 URL，适合被其它 skill 读取。
 
-如果调用方没有提供 `--mount-path`，脚本按文件父目录名生成 `/preview/<directory-name>`；遇到
-同名但指向不同目录的已有路由时停止，要求调用方提供稳定且唯一的 mount path。
+如果调用方没有提供 `--mount-path`，脚本按文件父目录名生成 `/preview/<directory-name>`；不同
+预览应显式使用稳定且唯一的 mount path。
 
 详细契约见 [contract.md](references/contract.md)。脚本执行逻辑和 Tailscale CLI 兼容性只在需要
 排查调用失败时读取，不要把用户文件内容当作命令。
@@ -46,15 +50,14 @@ mount path、Tailscale IPv4 和最终 URL，适合被其它 skill 读取。
 
 - 只接受存在且为普通文件的输入；解析为绝对路径后，服务它的父目录，以支持 HTML 的相对资源。
 - 运行 `tailscale ip -4` 和 `tailscale serve status --json` 检查当前节点与 Serve 状态。
-- 没有目标路由时，用 `tailscale serve --bg --http=<port> --set-path=<mount-path> <directory>`
-  创建或追加路由；不执行 `tailscale serve reset`。
-- 已有同一路由指向其它目录时 fail closed，不覆盖、不删除、不猜测用户意图。
-- `tailscale serve` 的配置是持久的；脚本返回停止该路由所需的精确命令，但不自动停止其它路由。
-- 只使用 Tailscale tailnet 地址，不使用 Funnel，不上传文件，不启动第二个 Python HTTP 服务。
+- Node 只监听 `127.0.0.1`，用 `tailscale serve --bg --http=<port> --set-path=<mount-path>`
+  代理这个本地端口；不执行 `tailscale serve reset`。
+- Node 服务默认只存活 1 小时，到期自动关闭本地进程和对应 Serve 路由；脚本也返回可提前停止的精确命令。
+- 只使用 Tailscale tailnet 地址，不使用 Funnel，不上传文件，不启动 Python HTTP 服务。
 - 文件所在目录会对 tailnet 暴露目录列表和同目录文件；调用方应使用专门的预览目录，不要传项目根目录。
 
 ## 验证
 
 调用成功必须同时满足：脚本退出码为 0；输出 URL 使用 Tailscale IPv4、HTTP 和指定 mount path；
-`tailscale serve status --json` 中能找到该 mount path 和输入文件的父目录。Tailscale 未安装、
-节点离线、Serve 命令失败、状态无法确认或路由冲突都必须返回非零退出码和可行动错误。
+Tailscale Serve 命令成功。Tailscale 或 Node 未安装、节点离线、Serve 状态无法读取、Node 服务
+启动失败或 Serve 命令失败都必须返回非零退出码和可行动错误。