docs: precipitate HTML report contract for data management

scripts/service/html_page_service.py

@@ -0,0 +1,77 @@
+"""技能 HTML 报告页：写入 `{skill_data}/html/*.html`（宿主扫描预览）。
+
+契约要点（权威说明见 `references/ACTIONS.md`「HTML 页面报告」）：
+
+- 目录：仅一层 `html/*.html`（非递归）
+- 重新生成 Action id 必须为 `render-html`（宿主硬编码）
+- 成功后建议 `steps: refreshCatalog` 以重扫侧栏
+- 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Mapping
+
+from util.logging_config import get_skill_logger
+from util.runtime_paths import get_html_dir, get_skill_root
+
+# Host Data Management looks up this exact Skill Action id for「重新生成」.
+HOST_HTML_RENDER_ACTION_ID = "render-html"
+
+_UNSAFE_NAME = re.compile(r"[\\/]|^\.\.|\.\.$")
+
+
+def _log():
+    try:
+        return get_skill_logger()
+    except RuntimeError:
+        return None
+
+
+def assert_html_filename(filename: str) -> str:
+    name = (filename or "").strip()
+    if not name.lower().endswith(".html"):
+        raise ValueError(f"html filename must end with .html: {filename!r}")
+    if _UNSAFE_NAME.search(name) or "/" in name or "\\" in name:
+        raise ValueError(f"html filename must be a basename only: {filename!r}")
+    if len(name) > 200:
+        raise ValueError(f"html filename too long: {filename!r}")
+    return name
+
+
+def html_page_path(filename: str, *, create_dir: bool = True) -> str:
+    return os.path.join(get_html_dir(create=create_dir), assert_html_filename(filename))
+
+
+def load_html_template(relative_under_skill_root: str) -> str:
+    """Load UTF-8 template from skill root (e.g. ``assets/html/example-report.html``)."""
+    rel = (relative_under_skill_root or "").strip().replace("\\", "/")
+    if not rel or rel.startswith("/") or ".." in rel.split("/"):
+        raise ValueError(f"invalid template path: {relative_under_skill_root!r}")
+    path = os.path.join(get_skill_root(), *rel.split("/"))
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def render_html_placeholders(template: str, mapping: Mapping[str, str]) -> str:
+    """Replace ``{{KEY}}`` tokens. Unknown keys are left as-is."""
+    page = template
+    for key, value in mapping.items():
+        page = page.replace("{{" + str(key) + "}}", str(value))
+    return page
+
+
+def write_html_page(filename: str, html: str) -> str:
+    """Atomically write UTF-8 HTML under ``html/``. Returns absolute path."""
+    dest = html_page_path(filename, create_dir=True)
+    tmp = dest + ".tmp"
+    text = html if isinstance(html, str) else str(html)
+    with open(tmp, "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+    os.replace(tmp, dest)
+    log = _log()
+    if log:
+        log.info("html_page_written path=%s bytes=%s", dest, len(text.encode("utf-8")))
+    return dest

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.78"
+SKILL_VERSION = "1.0.80"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

scripts/util/runtime_paths.py

@@ -10,10 +10,13 @@ from util.constants import SKILL_SLUG
 
 _SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
-# 用户可见的上行/下行目录（数据管理侧栏只挂这两个）
+# 用户可见的上行/下行目录（数据管理「输入/输出」文件浏览器）
 STANDARD_SUBDIR_INPUT = "input"
 STANDARD_SUBDIR_OUTPUT = "output"
 
+# 宿主扫描的 HTML 报告页（数据管理侧栏 htmlPages，非 input/output 文件浏览器）
+STANDARD_SUBDIR_HTML = "html"
+
 # 内部/可选目录（不上侧栏）
 STANDARD_SUBDIR_UPLOADS = "uploads"
 STANDARD_SUBDIR_CACHE = "cache"
@@ -130,12 +133,21 @@ def get_videos_dir(*, create: bool = True) -> str:
     return path
 
 
+def get_html_dir(*, create: bool = True) -> str:
+    """HTML 报告页目录：宿主扫描 `{skill_data}/html/*.html`（一层、非递归）。"""
+    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_HTML)
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
 def list_resolved_data_paths() -> dict[str, str]:
     """供 health / config-path 输出已解析的数据子目录（不创建目录）。"""
     return {
         "skill_data_dir": get_skill_data_dir(),
         "input_dir": get_input_dir(create=False),
         "output_dir": get_output_dir(create=False),
+        "html_dir": get_html_dir(create=False),
         "uploads_dir": get_uploads_dir(create=False),
         "cache_dir": get_cache_dir(create=False),
         "temp_dir": get_temp_dir(create=False),