feat: group prototype journeys and simplify HTML preview

skills/previewer/SKILL.md

@@ -1,73 +1,48 @@
 ---
 name: previewer
 description: >-
-  将本地 HTML、PRD、报告、截图或其它静态文件用 Node 渲染成 HTTP 预览，并通过 Tailscale
-  tailnet 暴露；用户说“把这个 HTML 渲染出来”“给我访问 IP/URL”或要求远程查看文件时使用；
-  不用于公网发布、动态应用部署或业务服务反向代理。
+  用 Node 将已有 HTML、PRD、报告、截图或其它静态文件提供为 HTTP 预览。
+  用户说“把这个 HTML 渲染出来”“预览这个文件”“给我预览 URL”时使用；
+  不生成页面内容，不执行构建，不配置代理、隧道或动态业务服务。
 ---
 
-# Previewer：HTML/静态文件渲染预览
+# Previewer：HTML/静态文件预览
 
-调用方只提供一个要展示的文件。Previewer 用 Node 启动本地静态服务，再让
-`tailscale serve` 代理这个 localhost 端口，最后返回 tailnet 内 HTTP URL。它是独立的通用
-HTML 渲染能力，specifier、report 或其它 skill 都可以调用。
-
-## 何时使用
-
-- 展示本机生成的 HTML、PRD、报告、截图或其它静态文件。
-- 用户直接说“把这个 HTML 渲染出来”，并希望从手机或另一台机器打开。
-- 其它 skill 需要一个通用的“给我文件，返回可访问链接”能力。
-- 用户明确要求通过 Tailscale 访问预览内容。
-
-## 不适用
-
-- 公网访问：不使用 Funnel，也不替用户开放公网入口。
-- 动态服务、API、WebSocket 或需要构建/运行的应用：交给部署或开发工具。
-- 不需要远程访问的本地预览：直接用本地浏览器或文件路径。
+调用方提供一个文件，脚本启动静态 HTTP 服务并返回 JSON。HTML 的实际排版和 JavaScript
+由浏览器执行，previewer 不编译模板、不构建 React，也不生成截图。
 
 ## 调用方式
 
-前置条件：本机安装 Node.js 和 Tailscale，并已登录目标 tailnet。找到本 skill 目录
-`<previewer-skill-dir>`，执行：
+前置条件只有 Node.js。读取 [contract.md](references/contract.md)，执行：
 
 ```bash
-node <previewer-skill-dir>/scripts/serve_file.js \
-  <absolute-file-path> \
-  --mount-path /preview/<stable-name>
+node <previewer-skill-dir>/scripts/serve_file.js <absolute-file-path>
 ```
 
-脚本默认使用 Tailscale HTTP 80 端口，并为本地 Node 服务自动选择空闲端口；可用 `--port`
-指定 Tailscale 对外端口、`--local-port` 指定本地端口。Node 服务默认 1 小时后自动关闭，
-到期时同时关闭对应 Serve 路由；可用 `--ttl` 以秒覆盖。它输出一个 JSON，包含文件、挂载目录、
-本地进程 PID、过期时间、Tailscale IPv4 和最终 URL，适合被其它 skill 读取。
+默认监听 127.0.0.1、自动分配端口、运行 3600 秒；用 --host、--port、--ttl 显式覆盖。
+跨设备访问时可按用户要求指定 --host 0.0.0.0，脚本返回本机网络接口的候选 URL，
+不配置防火墙、代理或隧道。
 
-如果调用方没有提供 `--mount-path`，脚本按文件父目录名生成 `/preview/<directory-name>`；不同
-预览应显式使用稳定且唯一的 mount path。
+## 其它 skill 如何复用
 
-也可以直接对 Agent 说：
+- 直接执行同一份 scripts/serve_file.js，以退出码和 JSON 为准；不再次用自然语言委派一个
+  Agent 来重新解释预览步骤，不复制启动代码。
+- 调用前固定文件、host、port 和 ttl；成功后保存返回值，不为拿 URL 再启动一次。
+- 相同规范化文件路径和参数的重复/并发调用会复用仍存活的服务，返回相同 PID、端口和过期时间，
+  并带 reused: true。复用不延长有效期；内容更新后刷新即可。
+- 参数改变、服务停止或已过期时允许创建新进程；固定端口被其它服务占用时返回错误，不停止它。
+- 项目需要构建时由调用方先构建，再传构建产物的 HTML；开发热更新仍用项目自己的开发服务器。
 
-```text
-用 previewer 把这个 HTML 渲染出来，并告诉我应该使用哪个 IP 和 URL 访问：<file>
-```
+## 行为边界
 
-详细契约见 [contract.md](references/contract.md)。脚本执行逻辑和 Tailscale CLI 兼容性只在需要
-排查调用失败时读取，不要把用户文件内容当作命令。
-
-## 行为和边界
-
-- 只接受存在且为普通文件的输入；解析为绝对路径后，服务它的父目录，以支持 HTML 的相对资源。
-- 运行 `tailscale ip -4` 和 `tailscale serve status --json` 检查当前节点与 Serve 状态。
-- Node 只监听 `127.0.0.1`，用 `tailscale serve --bg --http=<port> --set-path=<mount-path>`
-  代理这个本地端口；不执行 `tailscale serve reset`。
-- Node 服务默认只存活 1 小时，到期自动关闭本地进程和对应 Serve 路由；脚本也返回可提前停止的精确命令。
-- 回复用户时必须明确给出 Tailscale IPv4、完整 HTTP URL 和过期时间；说明访问地址中的
-  `<ip>` 就是用户应使用的 IP。不要只给本机回环地址，也不要把 Tailscale hostname 当成
-  必填项。
-- 只使用 Tailscale tailnet 地址，不使用 Funnel，不上传文件，不启动 Python HTTP 服务。
-- 文件所在目录会对 tailnet 暴露目录列表和同目录文件；调用方应使用专门的预览目录，不要传项目根目录。
+- 只接受存在的普通文件，服务其父目录以支持相对 CSS、图片和脚本。
+- 根 URL 返回输入文件；目录请求不提供目录列表；拒绝通过路径或符号链接逃出服务目录。
+- 同目录的其它文件仍可按文件名访问，调用方应传专门的产物目录。
+- 只处理 GET/HEAD，默认一小时后退出；返回精确停止命令，不配置任何外部网络服务。
+- 回复提供实际 URL 和有效期；127.0.0.1 仅用于同机访问，候选网络 URL 不代表已从远端验证。
 
 ## 验证
 
-调用成功必须同时满足：脚本退出码为 0；输出 URL 使用 Tailscale IPv4、HTTP 和指定 mount path；
-Tailscale Serve 命令成功。Tailscale 或 Node 未安装、节点离线、Serve 状态无法读取、Node 服务
-启动失败或 Serve 命令失败都必须返回非零退出码和可行动错误。
+执行 node --test <previewer-skill-dir>/tests/serve_file.test.js。
+成功要求退出码为 0、stdout 是一个 JSON、HTTP 服务可用；失败写 stderr JSON 并非零退出。
+无需安装依赖。文件错误、参数错误、端口冲突和启动失败必须明确返回错误码。