{"id":51152538,"url":"https://github.com/sun-praise/static-html","last_synced_at":"2026-06-26T07:03:09.611Z","repository":{"id":356732551,"uuid":"1187021573","full_name":"sun-praise/static-html","owner":"sun-praise","description":"A local HTML preview server with CLI for registering HTML files as browser-viewable sessions / 本地 HTML 预览服务器","archived":false,"fork":false,"pushed_at":"2026-06-13T08:04:42.000Z","size":304,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T09:25:00.886Z","etag":null,"topics":["cli","go","html","preview","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sun-praise.png","metadata":{"files":{"readme":"README.cn.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-20T08:52:12.000Z","updated_at":"2026-06-13T08:04:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sun-praise/static-html","commit_stats":null,"previous_names":["sun-praise/static-html"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/sun-praise/static-html","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun-praise%2Fstatic-html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun-praise%2Fstatic-html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun-praise%2Fstatic-html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun-praise%2Fstatic-html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sun-praise","download_url":"https://codeload.github.com/sun-praise/static-html/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sun-praise%2Fstatic-html/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34806448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","html","preview","sqlite"],"created_at":"2026-06-26T07:03:08.708Z","updated_at":"2026-06-26T07:03:09.592Z","avatar_url":"https://github.com/sun-praise.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# static-html\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go)](https://go.dev/)\n[![Go Report Card](https://goreportcard.com/badge/github.com/sun-praise/static-html)](https://goreportcard.com/report/github.com/sun-praise/static-html)\n[![GitHub release](https://img.shields.io/github/v/release/sun-praise/static-html?include_prereleases)](https://github.com/sun-praise/static-html/releases)\n[![License](https://img.shields.io/github/license/sun-praise/static-html)](https://github.com/sun-praise/static-html/blob/main/LICENSE)\n\n本地 HTML 预览服务器，提供 CLI 工具将 HTML 文件注册为可在浏览器中查看的会话。\n\n[English](README.md)\n\n## 环境要求\n\n- Go 1.24+\n\n## 构建\n\n```bash\ngo build -o dist/sth ./cmd/html-server\n```\n\n## 使用方法\n\n启动本地服务器：\n\n```bash\n./dist/sth start\n```\n\n默认情况下，会话存储在 SQLite 数据库中，路径为 `$XDG_STATE_HOME/sth/sessions.db` 或 `~/.local/state/sth/sessions.db`。\n会话存储使用 `github.com/mattn/go-sqlite3`，因此构建通常需要启用 CGO 并安装可用的 C 工具链。部分环境可能还需要安装 SQLite 开发库。\n\n注册 HTML 文件：\n\n```bash\n./dist/sth send ./fixtures/basic/index.html\n```\n\n`send` 命令会将 HTML 文件及其同目录下的所有常规文件打包为 zip 压缩包上传，然后输出一个会话 URL。在浏览器中打开该 URL 即可查看 HTML 文件，其关联的静态资源也会从服务器上传的快照中提供。\n\n## 命令\n\n```bash\nsth start [--host 127.0.0.1] [--port 3939] [--db /path/to/sessions.db]\nsth send \u003cfile.html\u003e [--server http://127.0.0.1:3939]\nsth tag [--rm] \u003csession-id\u003e \u003ctag...\u003e\nsth categorize \u003csession-id\u003e [category]\nsth project \u003csession-id\u003e [project]\nsth list [--tag \u003ctag\u003e] [--category \u003ccat\u003e] [--project \u003cproj\u003e]\nsth search \u003cquery\u003e [--tag \u003ctag\u003e] [--category \u003ccat\u003e] [--project \u003cproj\u003e]\n```\n\n所有命令均支持 `--db /path/to/sessions.db` 参数来覆盖数据库路径。\n\n### `sth tag` — 管理会话标签\n\n```bash\nsth tag \u003csession-id\u003e \u003ctag...\u003e\nsth tag --rm \u003csession-id\u003e \u003ctag...\u003e\n```\n\n为会话添加一个或多个标签。在会话 ID 前加 `--rm` 可移除指定标签。标签是与会话记录一起存储的自由格式字符串。\n\n### `sth categorize` — 设置或清除会话分类\n\n```bash\nsth categorize \u003csession-id\u003e [category]\n```\n\n为会话设置单个分类标签。省略 `[category]` 可清除已有的分类。\n\n### `sth project` — 设置或清除会话项目\n\n```bash\nsth project \u003csession-id\u003e [project]\n```\n\n为会话设置单个项目标签。省略 `[project]` 可清除已有的项目。\n\n### `sth list` — 按元数据筛选会话\n\n```bash\nsth list [--tag \u003ctag\u003e] [--category \u003ccat\u003e] [--project \u003cproj\u003e]\n```\n\n按给定元数据字段的精确匹配筛选会话，并以 JSON 格式输出结果。可组合多个标志来缩小范围（所有标志必须同时匹配）。不传标志则返回所有会话。\n\n### `sth search` — 全文搜索会话\n\n```bash\nsth search \u003cquery\u003e [--tag \u003ctag\u003e] [--category \u003ccat\u003e] [--project \u003cproj\u003e]\n```\n\n对会话元数据（标签、分类、项目、文件名）执行全文匹配。支持与 `list` 相同的 `--tag`、`--category` 和 `--project` 过滤条件来缩小结果范围，搜索和元数据过滤可以在一条命令中组合使用。\n\n#### `sth list` 与 `sth search` 的区别\n\n- `sth list` 按元数据字段精确值筛选（`--tag`、`--category`、`--project`）。\n- `sth search \u003cquery\u003e` 对会话内容进行全文匹配。\n- 可以组合使用：`sth search \u003cquery\u003e --tag \u003ctag\u003e` 将全文搜索结果限定到特定标签。\n\n## 测试\n\n```bash\ngo test ./...\n```\n\n## 故障排除\n\n### `sth send` 提示服务器无法访问 HTML 文件路径\n\n通常意味着运行 `send` 的客户端 CLI 版本与服务端不一致。\n\n检查清单：\n\n- 确保客户端的 `send` 命令路径指向正确的二进制文件：\n  ```bash\n  which sth\n  /path/to/sth send ...\n  ```\n- 确保客户端和服务端使用相同版本的构建。\n- 更新源码或二进制文件后，重启服务端的 systemd 服务：\n  ```bash\n  systemctl --user restart static-html.service\n  ```\n- 当客户端和服务端不在同一台机器时，显式指定 `--server`：\n  ```bash\n  sth send /absolute/path/to/index.html --server http://192.168.2.14:3939\n  ```\n\n如果客户端版本过旧，请替换后重试；旧客户端仍可能发送过时的 `entryFile` 元数据，即使服务端已更新也会触发跨主机路径错误。\n\n## Agent 技能\n\n本仓库附带了一个 agent 技能，位于 `skills/sth`，可以让编码助手（Claude Code、Codex、Cursor 等）自动使用 `sth`。\n\n使用 [npx skills](https://github.com/vercel-labs/skills) 安装：\n\n```bash\n# 安装到当前项目\nnpx skills add sun-praise/static-html\n\n# 全局安装\nnpx skills add sun-praise/static-html -g\n\n# 安装到指定 agent\nnpx skills add sun-praise/static-html -a claude-code -a cursor\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-praise%2Fstatic-html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsun-praise%2Fstatic-html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-praise%2Fstatic-html/lists"}