From d3b6732d40f4d0c1e0ab21b752b3d297429f191a Mon Sep 17 00:00:00 2001 From: laily Date: Tue, 13 Oct 2026 00:21:22 +0800 Subject: [PATCH] docs: clarify HTML previewer integration --- README.md | 2 +- skills/previewer/README.md | 10 ++++++++-- skills/previewer/SKILL.md | 22 ++++++++++++++++------ skills/previewer/agents/openai.yaml | 6 +++--- skills/previewer/references/contract.md | 4 ++++ skills/specifier/README.md | 3 ++- skills/specifier/SKILL.md | 9 ++++++--- 7 files changed, 40 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a6c058e..12325a0 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ AGENTS.md # 详细规范与架构说明 | [note-style](skills/note-style/README.md) | 把材料整理成可长期查阅的知识笔记 | | [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill | | [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill | -| [previewer](skills/previewer/README.md) | 通过 Tailscale Serve 将静态文件暴露为 tailnet 内 HTTP 预览 | +| [previewer](skills/previewer/README.md) | 用 Node 渲染 HTML/静态文件，并通过 Tailscale 返回访问 IP 和 HTTP 预览 | | [releaser](skills/releaser/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release | | [specifier](skills/specifier/README.md) | 把复杂需求整理成多轮评审的 HTML PRD，并在批准后生成 ACK handoff | | [manage-release](skills/manage-release/README.md) | 已弃用：`releaser` 的旧名兼容占位，不含流程 | diff --git a/skills/previewer/README.md b/skills/previewer/README.md index a1572f0..3dd31dc 100644 --- a/skills/previewer/README.md +++ b/skills/previewer/README.md @@ -1,11 +1,12 @@ # previewer 用 Node 启动默认存活 1 小时的轻量静态服务，再通过 Tailscale Serve 把本机的 HTML、PRD、报告 -或其它静态文件暴露给 tailnet，并返回可访问的 HTTP URL。 +或其它静态文件暴露给 tailnet，并返回应该使用的 Tailscale IP 和 HTTP URL。 ## 什么时候使用 - 想在手机、平板或另一台电脑查看本机生成的 HTML。 +- 可以直接说“把这个 HTML 渲染出来，并告诉我用哪个 IP”。 - 其它 skill 需要把某个文件交给通用预览服务。 只面向 Tailscale tailnet，不提供公网访问，也不启动动态 Web 服务。 @@ -21,12 +22,17 @@ 用 previewer 展示这个文件：/workspace/docs/prd-v002.html，挂载到 /preview/billing。 ``` +```text +把 /workspace/docs/prd-v002.html 渲染出来，告诉我用哪个 IP 和 URL 查看。 +``` + ## Agent 会做什么 1. 检查 Tailscale 是否在线，以及 Serve 状态是否可读取。 2. 用 Node 在 localhost 启动文件所在目录的静态服务。 3. 将指定 Tailscale 路径代理到本地端口。 -4. 返回包含 Tailscale IPv4 的 HTTP URL、Node PID、过期时间和停止命令。 +4. 返回 Tailscale IPv4、完整 HTTP URL、Node PID、过期时间和停止命令，并明确告诉用户 + 应该使用哪个 IP。 默认 1 小时后自动关闭 Node 服务和对应的 Tailscale 路由；需要其它时长时可传 `--ttl` 秒数。 diff --git a/skills/previewer/SKILL.md b/skills/previewer/SKILL.md index 26b5c9a..e78c487 100644 --- a/skills/previewer/SKILL.md +++ b/skills/previewer/SKILL.md @@ -1,20 +1,21 @@ --- name: previewer description: >- - 提供通用的 Tailscale tailnet 内静态文件预览能力。用户要通过 HTTP 展示 HTML、PRD、报告、 - 截图或其它静态文件，要求检查 Tailscale Serve、挂载文件所在目录并返回可访问 URL 时使用； + 将本地 HTML、PRD、报告、截图或其它静态文件用 Node 渲染成 HTTP 预览，并通过 Tailscale + tailnet 暴露；用户说“把这个 HTML 渲染出来”“给我访问 IP/URL”或要求远程查看文件时使用； 不用于公网发布、动态应用部署或业务服务反向代理。 --- -# Previewer：Tailnet 静态文件预览 +# Previewer：HTML/静态文件渲染预览 -调用方只提供一个要展示的文件。Previewer 检查 Tailscale 是否在线和 Serve 状态，启动一个 -Node 本地静态服务，再让 `tailscale serve` 代理这个 localhost 端口，最后返回 tailnet 内 -HTTP URL。 +调用方只提供一个要展示的文件。Previewer 用 Node 启动本地静态服务，再让 +`tailscale serve` 代理这个 localhost 端口，最后返回 tailnet 内 HTTP URL。它是独立的通用 +HTML 渲染能力，specifier、report 或其它 skill 都可以调用。 ## 何时使用 - 展示本机生成的 HTML、PRD、报告、截图或其它静态文件。 +- 用户直接说“把这个 HTML 渲染出来”，并希望从手机或另一台机器打开。 - 其它 skill 需要一个通用的“给我文件，返回可访问链接”能力。 - 用户明确要求通过 Tailscale 访问预览内容。 @@ -43,6 +44,12 @@ node /scripts/serve_file.js \ 如果调用方没有提供 `--mount-path`，脚本按文件父目录名生成 `/preview/`；不同 预览应显式使用稳定且唯一的 mount path。 +也可以直接对 Agent 说： + +```text +用 previewer 把这个 HTML 渲染出来，并告诉我应该使用哪个 IP 和 URL 访问： +``` + 详细契约见 [contract.md](references/contract.md)。脚本执行逻辑和 Tailscale CLI 兼容性只在需要 排查调用失败时读取，不要把用户文件内容当作命令。 @@ -53,6 +60,9 @@ node /scripts/serve_file.js \ - Node 只监听 `127.0.0.1`，用 `tailscale serve --bg --http= --set-path=` 代理这个本地端口；不执行 `tailscale serve reset`。 - Node 服务默认只存活 1 小时，到期自动关闭本地进程和对应 Serve 路由；脚本也返回可提前停止的精确命令。 +- 回复用户时必须明确给出 Tailscale IPv4、完整 HTTP URL 和过期时间；说明访问地址中的 + `` 就是用户应使用的 IP。不要只给本机回环地址，也不要把 Tailscale hostname 当成 + 必填项。 - 只使用 Tailscale tailnet 地址，不使用 Funnel，不上传文件，不启动 Python HTTP 服务。 - 文件所在目录会对 tailnet 暴露目录列表和同目录文件；调用方应使用专门的预览目录，不要传项目根目录。 diff --git a/skills/previewer/agents/openai.yaml b/skills/previewer/agents/openai.yaml index 9004339..da9fead 100644 --- a/skills/previewer/agents/openai.yaml +++ b/skills/previewer/agents/openai.yaml @@ -1,6 +1,6 @@ interface: - display_name: "Previewer" - short_description: "Serve static files over the Tailscale tailnet" - default_prompt: "Use $previewer to expose this HTML file over Tailscale and return its HTTP URL." + display_name: "HTML Previewer" + short_description: "Render local HTML over Tailscale and return the access IP" + default_prompt: "Use $previewer to render this HTML over Tailscale and tell me which IP and HTTP URL to use." policy: allow_implicit_invocation: true diff --git a/skills/previewer/references/contract.md b/skills/previewer/references/contract.md index 052a717..75e6eea 100644 --- a/skills/previewer/references/contract.md +++ b/skills/previewer/references/contract.md @@ -37,6 +37,10 @@ Tailscale Serve 负责把指定路径代理到这个本地端口。 } ``` +调用方应把 `ip` 字段和 `url` 一起展示给用户：`ip` 是访问这次预览时应使用的 Tailscale +IPv4，`url` 是可直接打开的完整 HTTP 地址。不要把 `127.0.0.1` 当成远程访问地址，也不 +要求用户必须使用 Tailscale hostname。 + 失败时输出到 stderr，退出码非 0；调用方不能把部分 stdout 当成有效 URL。 ## 状态和冲突 diff --git a/skills/specifier/README.md b/skills/specifier/README.md index c2732d4..745a408 100644 --- a/skills/specifier/README.md +++ b/skills/specifier/README.md @@ -30,7 +30,8 @@ 3. 生成可离线打开的版本化 HTML PRD；保留每个历史版本并记录本轮变更。 4. 根据用户意见反复修改，直到用户明确批准指定版本。 5. 仅在批准后生成 `handoff.yaml`，供 `/ack` 创建和执行任务。 -6. 用户需要远程查看时，可调用 `previewer` 将当前 HTML 通过 Tailscale 暴露为 HTTP URL。 +6. 用户需要远程查看，或说“把 HTML 渲染出来”时，可调用独立的 `previewer` skill；它用 Node + 渲染并通过 Tailscale 暴露为 HTTP URL，同时返回应该使用的 Tailscale IP。 Specifier 只负责需求规格，不修改业务代码，也不替代 ACK 的开发和独立测试。 diff --git a/skills/specifier/SKILL.md b/skills/specifier/SKILL.md index 6f8144b..cda9f29 100644 --- a/skills/specifier/SKILL.md +++ b/skills/specifier/SKILL.md @@ -73,8 +73,10 @@ description: >- 6. 按可独立验证的垂直切片拆任务，写出依赖、关键路径、`expected` 和 `verification`， 但不要写入 `.pouch/ack/tasks.yaml`。 7. 按模板生成自包含 HTML PRD，并在回复中说明文件路径、版本、待确认问题和下一步。 -8. 用户需要在其它设备查看 HTML 时，调用已安装的 `previewer` 能力传入该文件；不要在 - `specifier` 内复制 Tailscale Serve 逻辑。previewer 返回 URL 后，把 URL 和对应 PRD 版本一起给出。 +8. 用户需要在其它设备查看 HTML，或说“把这个 HTML 渲染出来”时，调用已安装的 + `previewer` 能力传入该文件；不要在 `specifier` 内复制 Node/Tailscale Serve 逻辑。 + previewer 返回结果后，必须把对应 PRD 版本、Tailscale IPv4、完整 HTTP URL、过期时间 + 和停止命令一起给出，并明确说明应使用返回的哪个 IP 访问。 如果调研发现需求边界、目标或关键依赖存在两种互相冲突的解释，停止在 `review`，明确列出 冲突，不能自行替用户拍板。 @@ -93,7 +95,8 @@ description: >- 按 [review-loop.md](references/review-loop.md) 记录状态和审计信息。 如果需要远程预览，读取 `previewer` 的调用契约并把 PRD 文件路径交给它；previewer 不改变 -需求评审状态，HTML 被展示不等于用户批准。 +需求评审状态，HTML 被展示不等于用户批准。回复中要同时给出 Tailscale IP 和 URL，不能只 +说“已经渲染”或只返回本机 `127.0.0.1`。 ## 批准和 ACK 交接