feat: group prototype journeys and simplify HTML preview

skills/previewer/README.md

@@ -1,42 +1,34 @@
 # previewer
 
-用 Node 启动默认存活 1 小时的轻量静态服务，再通过 Tailscale Serve 把本机的 HTML、PRD、报告
-或其它静态文件暴露给 tailnet，并返回应该使用的 Tailscale IP 和 HTTP URL。
+用 Node 直接预览已有 HTML 和静态文件，返回可打开的 HTTP URL。只需要 Node.js，无需安装
+npm 依赖，也不配置隧道或代理。
 
-## 什么时候使用
+## 用法
 
-- 想在手机、平板或另一台电脑查看本机生成的 HTML。
-- 可以直接说“把这个 HTML 渲染出来，并告诉我用哪个 IP”。
-- 其它 skill 需要把某个文件交给通用预览服务。
-
-只面向 Tailscale tailnet，不提供公网访问，也不启动动态 Web 服务。
-
-## 使用前准备
-
-- 本机已安装 Node.js、已登录 Tailscale，且访问者也在允许访问的 tailnet 中。
-- 提供要展示的文件路径；文件所在目录会被作为静态目录服务。
-
-## 使用示例
-
-```text
-用 previewer 展示这个文件：/workspace/docs/prd-v002.html，挂载到 /preview/billing。
+```bash
+node ~/.pouch/skills/previewer/scripts/serve_file.js /workspace/preview/index.html
 ```
 
-```text
-把 /workspace/docs/prd-v002.html 渲染出来，告诉我用哪个 IP 和 URL 查看。
+默认只允许同机访问，自动选择空闲端口，一小时后关闭。需要局域网访问时：
+
+```bash
+node ~/.pouch/skills/previewer/scripts/serve_file.js /workspace/preview/index.html --host 0.0.0.0 --port 8088
 ```
 
-## Agent 会做什么
+输出包含 URL、监听地址、端口、PID、过期时间和停止命令。绑定所有接口时还会列出本机网卡
+的候选 URL，实际可达性取决于访问者所在网络。
 
-1. 检查 Tailscale 是否在线，以及 Serve 状态是否可读取。
-2. 用 Node 在 localhost 启动文件所在目录的静态服务。
-3. 将指定 Tailscale 路径代理到本地端口。
-4. 返回 Tailscale IPv4、完整 HTTP URL、Node PID、过期时间和停止命令，并明确告诉用户
-   应该使用哪个 IP。
+## 复用方式
 
-默认 1 小时后自动关闭 Node 服务和对应的 Tailscale 路由；需要其它时长时可传 `--ttl` 秒数。
+其它 skill 生成文件后，直接执行上面的同一份脚本，读取 JSON，不需要再次委派 Agent。
+相同文件和参数的连续或并发调用会复用仍存活的服务，端口与过期时间保持不变。
+HTML、CSS 或 JavaScript 更新后刷新页面即可；React 等项目需先由调用方构建成静态文件。
 
-## 如何判断完成
+文件父目录作为服务目录，相对资源可以正常加载；不提供目录列表，也不允许访问目录外的文件。
+本工具提供文件，页面由浏览器渲染；不执行模板生成或截图。
 
-- 得到一个 HTTP URL，并能从 tailnet 内的另一台设备打开目标文件。
-- 失败时明确说明是 Tailscale 未安装、未登录、路由冲突还是 Serve 命令失败。
+## 验证
+
+```bash
+node --test ~/.pouch/skills/previewer/tests/serve_file.test.js
+```