kai-report-creator

Generate single-file HTML reports from source notes or .report.md IR. Keep this file as a thin router: load only the references needed for the current path.

Core Principles

Zero Dependencies — generated reports are self-contained HTML, with CDN or bundled assets only when needed.
User Provides Data, AI Provides Structure — never fabricate facts or numbers; use [数据待填写] / [INSERT VALUE] when data is missing.
Plan Before Generate — complex reports should become .report.md IR first, then HTML.
Progressive Disclosure for AI — output keeps report-summary, section annotations, and component data machine-readable.
Thin Routing Over Prompt Growth — SKILL.md routes work; detailed rules live in references.
Contracts and Gates Beat Prompt Soup — prefer IR, guard validation, shell tests, and post-render review over adding more prose to this hot path.

Command Routing

When invoked as /report [flags] [content], parse flags first:

| Flag | Action | |------|--------| | --plan "topic" | Write .report.md IR only. Stop after saving it. | | --generate [file] | Render one .report.md IR to HTML. With no file given, treat as IR from context: extract exactly one valid IR block from context. Never render the surrounding conversation. | | --review [file] | Refine an existing HTML report with references/review-checklist.md. | | --themes | Write the themes preview HTML. | | --from <file> | If the file starts with frontmatter, treat as IR; otherwise create IR, then render. | | --theme <name> | Override the theme. Built-ins: corporate-blue, minimal, dark-tech, dark-board, data-story, newspaper, regular-lumen, fangsong. | | --template <file> | Use a custom HTML template. See references/toc-and-template.md. | | --output <file> | Save to this path instead of the default. | | --bundle | Inline CDN assets where supported. | | --export-image [mode] | After HTML generation, run scripts/export-image.py; mode is im, mobile, desktop, or all. | | no flags + text | Create IR internally, then render HTML. | | no flags + IR in context | Treat as --generate from context. |

Default output filename: report-<YYYY-MM-DD>-<slug>.html. Slug: lowercase ASCII, non-alphanumeric to hyphens, collapse hyphens, trim, max 30 chars.

Reference Loading

Load reference files minimally by route; do not read every reference by default. In short: load only the references that materially help the current render path.

| Route | Always load | Conditional load | |-------|-------------|------------------| | --plan | references/spec-loading-matrix.md, references/plan-flow.md, references/theme-routing.md | references/regular-report-content-rules.md for periodic reports | | --generate | references/generate-flow.md, references/html-shell-template.md + every references/html-shell/*.md, references/theme-css.md, references/review-checklist.md | references/rendering-rules.md then only the references/rendering/*.md files required by the IR; references/anti-patterns.md for visual anchors; references/diagram-decision-rules.md for diagrams; references/regular-report-content-rules.md for periodic reports | | --review | references/review-checklist.md | references/review-report-template.md if a structured change summary is requested | | custom theme/template | references/theme-css.md, references/toc-and-template.md | custom theme reference.md or theme.css |

Load references/spec-loading-matrix.md before --plan and --generate as a silent classifier. It covers optional archetypes: brief, research, comparison, update.

Always load references/anti-patterns.md before --generate. Load references/diagram-decision-rules.md whenever a diagram or diagram-like structure is being considered.

IR Contract

Load references/ir-contract.md for the full frontmatter spec, validity terms, and compatibility anchors.

Quick reference:

Three parts: YAML frontmatter, Markdown prose (##/###), component fences :::tag [param=value].
:::kpi uses items:; Use ECharts for ALL charts.
Badges are optional visual enhancements, not a first-class IR tag.
Validity taxonomy: invalid_syntax, invalid_semantics, contract_conflict, auto_downgrade_target.
Timeline details live in rendering references; Allowed Date tokens must be real time markers, not decorative labels.
Canonical component routing: references/rendering-rules.md; component details: references/rendering/*.md.

Minimal frontmatter example:

theme: corporate-blue                  # Optional. Default: corporate-blue
report_class: mixed                    # Optional. Values: narrative, mixed, data
archetype: research                    # Optional lightweight archetype hint for silent classification.

Supported archetypes: brief, research, comparison, update.

Language And Theme

Load references/theme-routing.md for the full theme-selection table and report-class rules.

Quick reference: auto-detect zh when CJK is material; apply to placeholders, TOC labels, date display, and shell labels.

`--plan` Flow

Load references/plan-flow.md for the full 10-step procedure and narrative rhythm rules.

Key gates: save as report-<slug>.report.md; do not generate HTML; use real quantitative KPI values only.

Poster summary mode is opt-in. Do not infer poster_title or poster_subtitle from punctuation in title.

Narrative cadence blocks (lead-block, section-quote, action-grid) follow claim -> explanation -> scan anchor. These are optional prose upgrades, not default required blocks. If uncertain, keep normal paragraphs and add one clearer scan anchor instead of forcing a cadence block. Do not add more than one of lead-block / section-quote / action-grid by default inside the same section unless the source material clearly warrants it.

`--generate` Flow

Load references/generate-flow.md for steps 1-8 (input parsing, guard validation, render, shell assembly, CSS).

Then run these quality gates in sequence — do not skip:

Run pre-write validation and fix all violations:
- no raw ::: in HTML
- valid ir-hash
- no generic/template h2 headings
- short, real quantitative .kpi-value and report-summary KPI values; no placeholder or status-only KPI values
- .number body numerals use tabular lining numerals
- badges clarify status/category/entity, never quota-fill
- timeline dates are real time markers
- no U+FE0F
- no text-align: justify, black-background flood, body letter-spacing > 0.05em, or mobile-hidden critical controls
Run the final HTML quality gate with scripts/html_quality_gate.py on the rendered HTML. It must pass standard shell IDs, theme fidelity, and KPI value checks. If it fails, fix the HTML and rerun it before reporting success.
Run L2 shell checks. Required: data-template="kai-report-creator", data-version, data-theme, id="toc-toggle-btn", id="toc-sidebar", id="card-mode-btn", id="sc-overlay", id="export-btn", id="export-menu", id="export-print", id="export-png-desktop", id="export-png-mobile", id="export-im-share", id="report-summary", plus the JS bindings for print/desktop/mobile/IM export. If any export item or binding is missing, rebuild the whole export block from references/html-shell/export.md.
Run the silent final review pass from references/review-checklist.md, then write the HTML and report the path.

When the report is explicitly comparing named vendors, models, or tools, set data-report-mode="comparison" on the outer report container and use .badge--entity-a/.badge--entity-b/.badge--entity-c only for entity identity.

`--review` Flow

Read the HTML file.
Load references/review-checklist.md.
Apply hard rules automatically; apply AI-advised rules only when confidence is high and factual accuracy is preserved.
One-pass automatic refinement; no confirmation window.
Use references/review-report-template.md when the user wants a structured summary.
Write back unless the user asked for diagnosis only.
Tell the user what changed and what was intentionally left untouched.

`--themes` And `--export-image`

For --themes, read the theme preview template and write report-themes-preview.html verbatim.

For --export-image, after HTML generation run:

python <skill-dir>/scripts/export-image.py <output.html> --mode <mode>

If Playwright is unavailable, print install instructions and skip image export without failing HTML generation.

Shell And Template Boundary

Generate complete self-contained HTML. Shell entry contract: references/html-shell-template.md; full shell structure, inline JS, export behavior, summary card, edit mode, TOC, print rules, Shell metadata, version/theme metadata, duplicate-date guard, and footer/watermark degradation rules: references/html-shell/*.md.

All scripts are inline in the shell template. Never load nonexistent files such as templates/scripts/*.js.

For custom templates and TOC slug rules, use references/toc-and-template.md.

Final Output

Always end with the file path and a one-sentence summary. If a validation, guard, or export step could not run, say exactly which step was skipped and why.