html-report-stable-base

中文说明

Codex skill for building stable, editable HTML reports from supplied content or existing HTML. It supports long scrolling reports and fixed 16:9 HTML decks, with a shared style drawer, per-element editing, browser QA, click-triggered exports, and bundled ECharts / word-cloud helper skills.

Visual Examples

Single-Page Mode

Use single-page when the report should read as a long, vertically scrolling page with section navigation, responsive width, auto height, and HTML / 图片 / PDF export.

PPT Mode

Use ppt when the output should behave like a slide deck with a fixed 1440 × 810 canvas, page navigation, stable object geometry, and HTML / PDF / PPTX export.

What This Skill Provides

• A right-side editable style drawer with global typography and per-element controls.
• Independent editing for text, shapes, charts, and images.
• HEX color text inputs paired with native color swatches.
• Single-page section navigation or PPT slide navigation.
• ECharts-friendly chart resizing.
• Bundled echarts-charts and generate-word-clouds skills for chart HTML/options and PNG word-cloud assets.
• Standalone HTML export that can keep editing controls or export view-only output.
• Local preview service for high-fidelity image, PDF, and PPTX generation after user action.

Dependencies

For a newly installed environment, run the bootstrap once before browser QA, image/PDF/PPTX export, or word-cloud generation:

node scripts/bootstrap_html_report_deps.mjs

It installs Node dependencies (playwright, sharp), creates .venv for Python dependencies from requirements.txt, and installs Playwright Chromium. The repository tracks lockfiles and dependency manifests, not node_modules/, .venv/, or browser binaries. If the system python lacks dependencies after bootstrapping, run Python scripts with .venv/bin/python.

Quick Start

Create a model JSON with an explicit mode, then build with the matching template.

python scripts/build_html_report_from_model.py model.json \
  --template assets/template/html-report-single-base.html \
  --out output/index.html

Run the checks:

python scripts/check_html_report.py output/index.html
node scripts/qa_html_report.mjs output/index.html
node scripts/qa_editor_enhancements.mjs output/index.html
node scripts/qa_preview_export.mjs output/index.html

Start local preview and click export buttons in the browser:

node scripts/start_html_report_preview.mjs output 5300

Build the bundled external-facing single-page demo:

python scripts/build_html_report_from_model.py fixtures/single-page-demo.json \
  --template assets/template/html-report-single-base.html \
  --out output/demo

Install From GitHub

This repository is public, so other users can install the skill directly by giving Codex the GitHub URL:

$skill-installer install from https://github.com/Lucas-Fong/html-report-stable-base

If the installer asks for a repo path, use the repository root because SKILL.md lives at the top level.

Public GitHub search can also find this repository through topics such as codex, codex-skills, openai-codex, agent-skills, html-report-stable-base, and report-generator.

Install As A Codex Plugin

This repository also includes a plugin manifest at .codex-plugin/plugin.json, so it can be distributed as a Codex plugin. The plugin exposes html-report-stable-base, echarts-charts, and generate-word-clouds through skills/, while keeping the report templates, scripts, references, fixtures, and examples at the repository root.

Use this path when you want Codex plugin discovery, plugin cards, default prompts, metadata, and marketplace distribution instead of only direct skill installation.

Discovery In Codex

Public GitHub visibility does not automatically place a skill into Codex's curated skill list. For broad discoverability inside Codex, add this plugin to a marketplace source. A marketplace can be personal, team-owned, or public depending on the Codex environment.

Short-term distribution:

• Share this GitHub URL and ask users to install it with $skill-installer.
• Keep the README, topics, and examples clear so GitHub search works.

Plugin distribution:

• Share this GitHub URL as a plugin source.
• Add the plugin to a personal, team, or public marketplace source.
• Keep .codex-plugin/plugin.json metadata, default prompts, keywords, screenshots, and README examples current.

Minimal Models

Single-Page

{
  "mode": "single-page",
  "title": "Market Audit",
  "sections": [
    {
      "id": "summary",
      "title": "Executive Summary",
      "html": "<h1 class=\"editable\" data-editable-element=\"text\">Executive Summary</h1><p class=\"editable\" data-editable-element=\"text\">...</p>"
    }
  ]
}

PPT

{
  "mode": "ppt",
  "title": "Strategy Deck",
  "slides": [
    {
      "title": "Page 1",
      "html": "<h1 class=\"editable\" data-editable-element=\"text\">Page 1</h1>",
      "objects": []
    }
  ]
}

Editable Element Markup

Every independently editable element must declare exactly one type.

<h2 class="editable" data-editable-element="text">Title</h2>
<div data-editable-element="shape">Card</div>
<div class="chart" data-editable-element="chart"></div>
<img data-editable-element="image" src="..." alt="...">

Repository Structure

• SKILL.md: full skill contract and workflow.
• .codex-plugin/plugin.json: Codex plugin metadata for discovery and marketplace distribution.
• skills/html-report-stable-base/: plugin-facing wrapper skill entry.
• skills/echarts-charts/: bundled ECharts chart generation skill.
• skills/generate-word-clouds/: bundled PNG word-cloud generation skill.
• assets/examples/: README and skill documentation visuals.
• assets/template/: single-page and PPT templates plus shared editor assets.
• fixtures/: acceptance fixtures for editor behavior.
• references/: supporting contracts, including drawer and element rules.
• scripts/: builder, validators, QA checks, preview server, and export utilities.
• requirements.txt: Python dependency list used by the bootstrap script.

Versioning Notes

Track source files, templates, fixtures, examples, scripts, references, and lockfiles. Do not commit node_modules/, generated exports, local report outputs, or temporary QA artifacts.