sth

name	sth
description	Start or use the `sth` local HTML preview server from sun-praise/static-html. Use when the user mentions `sth`, wants `sth start`, `sth send`, `sth tag`, `sth categorize`, `sth project`, `sth list`, or `sth search`, needs to preview a local HTML file in a browser, manage session metadata, or register preview sessions from the CLI.

STH Preview

Use this skill when a user wants a quick local preview for an HTML file and its relative assets, manage metadata (tags, categories, projects), or search sessions.

Workflow

1. Bootstrap or locate the repo:

bash scripts/bootstrap-repo.sh

This script:

• uses STATIC_HTML_REPO_DIR if it already points at a checkout
• otherwise clones or updates sun-praise/static-html
• builds dist/sth when the Go source fingerprint changes

2. Start the preview server only if not already running:

If STATIC_HTML_SERVER_URL is set (e.g. the server is already deployed elsewhere), skip this step entirely.

Otherwise start locally:

bash scripts/start-server.sh [port]

Defaults:

• host: auto-detected LAN IP (e.g. 192.168.2.14), override with STATIC_HTML_HOST
• port: 3939

3. Register an HTML file:

python3 scripts/send-file.py /absolute/or/relative/file.html --tag TAG --category CAT --project PROJ [--server URL]

The command copies the HTML file to an isolated temporary directory (avoiding packaging unrelated files), uploads it, and prints a session URL like http://192.168.2.14:3939/s/<id>/.

If you need to include sibling resources (CSS, JS, images) alongside the HTML file, use sth send directly with the directory containing those resources instead of send-file.py:

sth send ./my-project-dir --tag demo --category preview --project myproj [--server URL]

When calling sth send directly, --tag accepts multiple comma-separated values:

sth send file.html --tag tag1,tag2,tag3 --category cat --project proj

4. Manage session metadata:

# Add tags (supports multiple tags at once)
sth tag <session-id> <tag1> [tag2] ...

# Remove tags (supports multiple tags at once)
sth tag --rm <session-id> <tag1> [tag2] ...

# Set category (omit [category] to clear)
sth categorize <session-id> [category]

# Set project (omit [project] to clear)
sth project <session-id> [project]

# List sessions (with optional filters)
sth list [--tag <tag>] [--category <cat>] [--project <proj>]

# Search sessions (with optional metadata filters)
sth search <query> [--tag <tag>] [--category <cat>] [--project <proj>]

All metadata commands accept --db /path/to/sessions.db to override the database path.

sth list vs sth search

• sth list filters by exact metadata field values (--tag, --category, --project).
• sth search <query> does full-text matching across session metadata (tags, category, project, filename). Filters and search can be combined, e.g. sth search <query> --tag <tag>.

Environment overrides

• STATIC_HTML_REPO_DIR: existing checkout to reuse
• STATIC_HTML_REPO_REF: branch or ref to clone/update, default main
• STATIC_HTML_SKIP_UPDATE: default 1 (skip fetch/pull). Set to 0 to enable auto-update on each invocation
• STATIC_HTML_HOST: server host, default auto-detected LAN IP (e.g. 192.168.2.14)
• STATIC_HTML_PORT: default port for start-server.sh
• STATIC_HTML_SERVER_URL: default server URL for send-file.py

FAQ

Tag 可以有一个还是多个？

支持多个。 系统设计上每个 session 可以关联多个 tag：

• sth send 用逗号分隔：--tag tag1,tag2,tag3
• sth tag 用空格分隔多个位置参数：sth tag <session-id> tag1 tag2 tag3
• Web UI 也会把多个 tag 渲染成独立的标签 pill

为什么页面上某个 session 只显示一个 tag，而且看起来像 JSON（如 ["日报"]）？

这是因为创建该 session 的客户端把 tag 作为 JSON 字符串发送了，而不是 JSON 数组。服务器把这个 JSON 字符串当作单个 tag 存入了数据库。

例如，客户端错误地发送了：

{"tags": "[\"日报\"]"}

服务器会将其反序列化为 ["[\"日报\"]"]，最终页面上只显示一个内容为 ["日报"] 的 tag。

正确做法：发送 JSON 数组或直接使用 sth send --tag（内部会自动处理为多个值）。

为什么 sth send 报错 "Failed to parse multipart form upload" 或上传很慢？

如果 HTML 文件放在一个大目录里（如 home 目录 /home/user/report.html），sth send 会把父目录下的所有相关文件打包上传，可能导致超时或体积过大。

解决方法：把文件放到一个单独的目录再发送：

mkdir /tmp/report-dir && cp report.html /tmp/report-dir/
sth send /tmp/report-dir/report.html --tag test --category cat --project proj

或者直接使用 send-file.py，它会自动处理隔离：

python3 scripts/send-file.py report.html --tag test --category cat --project proj

如果 HTML 文件有同目录的兄弟资源（CSS/JS/图片），sth send 会自动检测并一起打包，无需手动处理。

Notes

• This skill expects git, go, and a working Go toolchain.
• The GitHub repo is private; authenticated gh or git access is required.
• The server renders the HTML as-is and serves relative assets from the uploaded directory snapshot for that file.