49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
---
|
||
name: previewer
|
||
description: >-
|
||
用 Node 将已有 HTML、PRD、报告、截图或其它静态文件提供为 HTTP 预览。
|
||
用户说“把这个 HTML 渲染出来”“预览这个文件”“给我预览 URL”时使用；
|
||
不生成页面内容，不执行构建，不配置代理、隧道或动态业务服务。
|
||
---
|
||
|
||
# Previewer：HTML/静态文件预览
|
||
|
||
调用方提供一个文件，脚本启动静态 HTTP 服务并返回 JSON。HTML 的实际排版和 JavaScript
|
||
由浏览器执行，previewer 不编译模板、不构建 React，也不生成截图。
|
||
|
||
## 调用方式
|
||
|
||
前置条件只有 Node.js。读取 [contract.md](references/contract.md)，执行：
|
||
|
||
```bash
|
||
node <previewer-skill-dir>/scripts/serve_file.js <absolute-file-path>
|
||
```
|
||
|
||
默认监听 127.0.0.1、自动分配端口、运行 3600 秒；用 --host、--port、--ttl 显式覆盖。
|
||
跨设备访问时可按用户要求指定 --host 0.0.0.0，脚本返回本机网络接口的候选 URL，
|
||
不配置防火墙、代理或隧道。
|
||
|
||
## 其它 skill 如何复用
|
||
|
||
- 直接执行同一份 scripts/serve_file.js，以退出码和 JSON 为准；不再次用自然语言委派一个
|
||
Agent 来重新解释预览步骤，不复制启动代码。
|
||
- 调用前固定文件、host、port 和 ttl；成功后保存返回值，不为拿 URL 再启动一次。
|
||
- 相同规范化文件路径和参数的重复/并发调用会复用仍存活的服务，返回相同 PID、端口和过期时间，
|
||
并带 reused: true。复用不延长有效期；内容更新后刷新即可。
|
||
- 参数改变、服务停止或已过期时允许创建新进程；固定端口被其它服务占用时返回错误，不停止它。
|
||
- 项目需要构建时由调用方先构建，再传构建产物的 HTML；开发热更新仍用项目自己的开发服务器。
|
||
|
||
## 行为边界
|
||
|
||
- 只接受存在的普通文件，服务其父目录以支持相对 CSS、图片和脚本。
|
||
- 根 URL 返回输入文件；目录请求不提供目录列表；拒绝通过路径或符号链接逃出服务目录。
|
||
- 同目录的其它文件仍可按文件名访问，调用方应传专门的产物目录。
|
||
- 只处理 GET/HEAD，默认一小时后退出；返回精确停止命令，不配置任何外部网络服务。
|
||
- 回复提供实际 URL 和有效期；127.0.0.1 仅用于同机访问，候选网络 URL 不代表已从远端验证。
|
||
|
||
## 验证
|
||
|
||
执行 node --test <previewer-skill-dir>/tests/serve_file.test.js。
|
||
成功要求退出码为 0、stdout 是一个 JSON、HTTP 服务可用；失败写 stderr JSON 并非零退出。
|
||
无需安装依赖。文件错误、参数错误、端口冲突和启动失败必须明确返回错误码。
|