page-serve

page-serve：把一个 URL 交给人类

当智能体为人类渲染了一个页面，就需要一种把页面交付出去的方式。会话中逐渐形成的旧模式是手工输入 python3 -m http.server 8991 再加上 portless alias <name> 8991：没有进程记录、没有停止方式、服务器会超出会话存活，而且据记录在 2026-09-06 的一个晚上，同一会话做了两次，服务器到第二天早上还在运行。本技能就是把这个模式加上状态文件、停止、状态查询，以及在无法满足 URL 约定时的大声失败。

约定

URL 形如 https://<name>.localhost/<file>。永远不带端口。portless 的 443 服务拥有该端口；URL 中出现 :1355 或 :8991 属于服务出现之前的回退做法，本技能会拒绝而不是输出这样的 URL。

每个名称一个静态服务器，绑定空闲回环端口，根目录为文件所在目录（以便同级资源可解析）或你传入的目录。

状态保存在 .claude/state/page-serve/<name>.json：root、file、port、pid、url、time。status 每次调用都会重新测量 pid、路由和 HTTP，从不信任文件内容。

按名称幂等：相同名称加相同根目录会复用运行中的服务器；不同根目录会替换它；alias 上的 --force 会用同名覆盖过期路由。

用法

page-serve docs/playgrounds/roadmap-2026-09-07.html page-serve docs/playgrounds/ --name playgrounds page-serve <path> --screenshot # agent-browser，返回 png 路径 page-serve status [--json] page-serve stop <name> page-serve stop --all

serve.sh 会打印 url=、name=、port=、pid=、http=、可选的 screenshot=，以及可直接粘贴的 stop= 行。把 url= 行放进回复的 Open 部分。

模式

调用方式 / 脚本 / 发生什么

<path> [flags] / scripts/serve.sh / 前置检查、服务器、alias、状态、curl 检查、可选截图

status [--json] / scripts/status.sh / 每个已服务页面一行：服务器 up/dead、路由 registered/missing、HTTP 状态码

stop <name> 或 stop --all / scripts/stop.sh / 移除 alias、杀掉服务器、删除状态和截图；每一步都会报告

失败模式，全部大声报错

条件 / 退出码 / 输出内容

portless 未安装 / 2 / 安装命令，然后 portless service install

443 服务无响应 / 2 / portless service status、操作者的 launchctl kickstart 命令，以及“不要回退到 :port URL”

服务器未绑定 / 3 / 端口和日志路径

alias 注册失败 / 2 / portless 自己的消息，服务器已清理

路由已起但 URL 不是 200 / 4 / 状态码、curl 返回码和 portless list；服务器保留运行以便检查

截图失败 / 0 / 在 stderr 报告，页面仍被服务，省略 screenshot= 行

一个“已服务”但通过代理不返回 200 的页面是退出码 4，而不是 0，因此只读退出码的调用方无法把死链报告为完成。

截图

安装了 agent-browser 时默认会截一张图（--no-screenshot 跳过；--screenshot 强制要求，缺失时输出 stderr 行）。png 落在状态文件旁边。截图是页面已渲染的证据，不是渲染正确的证明：在声称页面看起来正确之前先读图片（glyph 技能的第 1 条规则）。

这不是什么

不是开发服务器。对于带热重载的框架应用，请使用 dev，它把应用自己的 dev 命令包装在 portless 中。本技能服务静态文件。

不是发布器。任何东西都不离开本机；.localhost 只在本地解析。

不是文档站点部署。docs/site/public/lab/ 下的实验页面仍通过文档站点构建发布；本技能用于在此之前或与之并行的交付。

退役旧模式（#3900）

任何告诉智能体运行 python3 -m http.server 或手工输入 portless alias 的技能或页面，都应改为说 page-serve <path>。截至本技能首次发布，grep -rln 'http.server' src/skills 为空；该模式存在于会话习惯和 hq-ext 中，因此清理范围是 glyph、playground、visualize-plan 和 expect（这四个会把页面交给人类）以及 hq-ext 的 glyph。

技能介绍