first commit

2026-05-10 13:52:46 +08:00
commit ccc63d1e70
4583 changed files with 584341 additions and 0 deletions
--- a/minimax-pdf/SKILL.md
+++ b/minimax-pdf/SKILL.md
@@ -0,0 +1,472 @@
+---
+name: minimax-pdf
+description: HTML-first PDF production skill for reports, papers, and structured documents. Must be applied before generating PDF deliverables from HTML.
+---
+
+## A. Scope and Operating Contract
+
+This skill governs **authoring and converting HTML into print-quality PDF**.
+
+Primary output goals:
+- Stable pagination and predictable layout on Linux runtime.
+- Searchable/selectable text (no screenshot-based fallback).
+- Professional, citation-safe long-form documents.
+
+## B. Hard Constraints (Do Not Violate)
+
+### B1. Conversion entrypoint
+
+For HTML->PDF, use `html_to_pdf` only.
+
+Forbidden:
+- Screenshot/print hacks or manual browser printing
+- Direct invocation of low-level local scripts for conversion
+
+Reason: image-stitch paths degrade text quality and create pagination discontinuity.
+
+### B2. Rendering safety rules
+
+- Do not inject Paged.js manually. The runtime pipeline handles loading.
+- Do not rely on CSS counters (`counter-reset`, `counter-increment`, `counter()`).
+- Do not use runtime charting engines (ECharts, Chart.js, D3, Plotly, etc.).
+- Charts should be pre-rendered as static images and prefer landscape aspect ratio.
+- Decorative emoji/icon glyphs are disallowed unless explicitly requested.
+
+## C Intent Parsing
+
+Classify the task before execution:
+
+| Intent | Typical user request | Pipeline |
+|---|---|---|
+| Build | "写一份报告并导出 PDF" | `build-pdf` |
+| Transform | "把这篇内容翻译后做成 PDF" | `transform-pdf` |
+| Existing PDF ops | "提取/合并/拆分 PDF" | `process-existing-pdf` |
+| LaTeX explicit | "请用 LaTeX/.tex/Tectonic" | `latex-compile` |
+
+Clarification policy:
+- If request is clear, execute directly.
+- If ambiguous, ask once with a compact checklist:
+  - 文档类型/主题
+  - 是否要封面
+  - 字数或页数边界
+  - 语言与格式偏好
+
+Important clarification behavior:
+- Ask at most one clarification round for intent.
+- After that, execute with explicit assumptions rather than repeatedly asking.
+
+## D. Content Governance
+
+### D1. Language policy
+- Chinese user query -> Chinese content
+- English user query -> English content
+- User-specified language -> obey exactly
+
+### D2. Outline policy
+- User provides outline -> preserve hierarchy/order, no silent restructuring
+- No outline -> choose structure by document type and keep narrative flow consistent
+
+### D3. Citation integrity
+- Never invent references.
+- Every citation must be verifiable (author/title/year/source).
+- Reused source should keep the same citation index.
+
+Recommended citation style for this skill: **IEEE numeric**.
+
+Sample reference list:
+```text
+[1] R. Patel and L. Chen, "A comparative study on model routing," Journal of Applied AI, vol. 8, no. 3, pp. 44-58, 2025.
+[2] M. Rivera, Systems Design Handbook, 2nd ed. New York, NY, USA: Northbridge Press, 2024.
+[3] T. Huang, "Model evaluation checklist," Research Notes, https://example.org/eval (accessed Feb. 14, 2026).
+```
+
+## E. Conversion Fidelity Checklist
+
+When transforming existing material (translation/rewrite/reformat), preserve source fidelity:
+
+### E1. Links
+- Keep original destination URL in `href`.
+- Do not replace links with plain text.
+- Ensure conversion uses `preserve_links=true`.
+
+### E2. Images
+Use a three-pass check:
+1. Count extracted image assets
+2. Count `<img>` tags in HTML
+3. Validate post-conversion image statistics
+
+### E3. Structure
+- Preserve source section sequence and anchor semantics.
+- Keep figure/table placement and numbering intent.
+- Do not add synthetic cover if source had none.
+
+## F. Implementation Blueprint
+
+### F1. Forbidden patterns
+
+| Pattern | Why unstable | Replacement |
+|---|---|---|
+| CSS content counters for numbering | pagination DOM shifts can break numbering | explicit labels in markup |
+| Dynamic JS chart libraries at render-time | print pagination conflicts | pre-rendered static charts |
+| Emoji/icon-heavy typography | Linux fallback inconsistency | plain text labels |
+
+Chart image policy:
+- Prefer landscape charts (`width > height`) to reduce page-break artifacts.
+
+### F2. Overflow guards (required baseline)
+
+```css
+/* Keep printable blocks inside page width */
+pre, table, figure, img, svg, .diagram, blockquote, .eq-block {
+  max-inline-size: 100%;
+  box-sizing: border-box;
+}
+
+pre {
+  overflow-x: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+figure img, figure svg {
+  max-inline-size: 82%;
+  max-block-size: 42vh;
+  height: auto;
+}
+
+table { overflow-x: auto; }
+.katex-display { overflow-x: auto; }
+code { overflow-wrap: anywhere; }
+a { overflow-wrap: anywhere; }
+tr { break-inside: avoid; }
+
+body {
+  text-align: justify;
+  text-align-last: start;
+}
+```
+
+### F3. Page model setup
+
+```css
+@page {
+  size: A4;
+  margin: 2.4cm 1.9cm;
+  @top-center { content: string(doc_title); }
+  @bottom-center { content: counter(page); }
+}
+
+@page :first {
+  @top-center { content: none; }
+  @bottom-center { content: none; }
+}
+
+@page titlepage {
+  @top-center { content: none; }
+  @bottom-center { content: none; }
+}
+
+@page contents {
+  @top-center { content: none; }
+  @bottom-center { content: none; }
+}
+
+body { string-set: doc_title ""; }
+h1 { string-set: doc_title content(); }
+.cover-page { page: titlepage; }
+.toc-sheet { page: contents; }
+```
+
+Pagination notes:
+- Apply `break-inside: avoid` only to compact units (single figure, single row, callout box).
+- Never apply it to large wrappers (chapter/section container).
+- Use `thead { display: table-header-group; }` for multi-page table headers.
+
+### F4. Visual direction
+
+Default target is **print-academic**, not dashboard aesthetics.
+
+Avoid:
+- heavy card shells
+- KPI tile walls
+- dark decorative title bars
+- oversized rounded/shadowed ornaments
+
+Prefer:
+- plain headings + thin dividers
+- data-dense tables
+- restrained grayscale palette
+- simple, high-contrast typography
+
+Type scale suggestion:
+- Body: 11pt
+- Subheading: 14pt
+- Primary heading: 18-20pt
+- Line height: 1.6-1.7
+
+### F. Cover page rules
+
+Full-bleed baseline:
+```css
+*,
+*::before,
+*::after { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+}
+
+@page :first {
+  margin: 0;
+}
+
+.cover-page {
+  inline-size: 210mm;
+  block-size: 297mm;
+  position: relative;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  break-after: page;
+}
+```
+
+Cover variants:
+- **Minimal**: white background, centered title/meta, no decoration
+- **Designed**: low-saturation geometry/gradient, keep center area clear for title
+
+If using image background, do not use CSS `background-image`. Use absolute `<img>`:
+
+```html
+<section class="cover-page">
+  <img class="cover-photo" src="cover.jpg" alt="">
+  <div class="cover-layer">...</div>
+</section>
+```
+
+```css
+.cover-photo {
+  position: absolute;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+  object-position: center;
+  z-index: 0;
+}
+
+.cover-layer {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 1;
+}
+```
+
+### F5. Numbering, references, TOC
+
+Use explicit labels in markup, not CSS counters.
+
+```html
+<figure id="arch-overview">
+  <img src="system-overview.png" alt="System overview">
+  <figcaption data-caption="Figure 1">Architecture Overview</figcaption>
+</figure>
+
+<table id="latency-table">
+  <caption data-caption="Table 1">Latency by Scenario</caption>
+  ...
+</table>
+
+<div class="eq-block" data-eq="(1)">$$f(x)=x^2+1$$</div>
+```
+
+```css
+figcaption::before {
+  content: attr(data-caption) " ";
+  font-weight: 700;
+}
+
+caption::before {
+  content: attr(data-caption) " ";
+  font-weight: 700;
+}
+
+.eq-block::after {
+  content: attr(data-eq);
+  float: right;
+}
+```
+
+Anchor placement rule:
+- Put `id` on the highest logical container (`figure`, `table`, section wrapper), not on inline caption text.
+
+TOC example with computed page numbers:
+
+```html
+<nav class="toc-sheet" aria-label="Contents">
+  <ul class="toc-list">
+    <li><a href="#sec-intro">1 Intro</a></li>
+    <li><a href="#sec-method">2 Method</a></li>
+  </ul>
+</nav>
+```
+
+```css
+.toc-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.toc-list li { margin: 0.45em 0; }
+
+.toc-list a {
+  display: flex;
+  gap: 0.5em;
+  color: inherit;
+  text-decoration: none;
+}
+
+.toc-list a::after {
+  margin-inline-start: auto;
+  content: target-counter(attr(href url), page);
+}
+```
+
+Optional in-text page reference:
+```css
+a.page-ref::after {
+  content: " (p." target-counter(attr(href url), page) ")";
+  opacity: 0.72;
+  font-size: 0.86em;
+}
+```
+
+### F6. Formula and diagram policy
+
+- For math, use KaTeX with auto-render.
+- Keep formula color neutral and print-safe.
+- For Mermaid, keep topology simple; if rendering becomes unstable, replace with static image.
+
+### F7. Reusable layout patterns
+
+Definition block:
+```css
+.definition {
+  border-inline-start: 3px solid #475569;
+  padding-inline-start: 1rem;
+  margin: 1rem 0;
+}
+
+.definition-title { font-weight: 700; }
+.definition-body { font-style: italic; }
+```
+
+Procedure block:
+```css
+.procedure {
+  border: 1px solid #cbd5e1;
+  padding: 0.75rem;
+  background: #f8fafc;
+}
+```
+
+Fixed-size centered badges must use flexbox:
+```css
+.badge-index {
+  inline-size: 1.7em;
+  block-size: 1.7em;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid #cbd5e1;
+  border-radius: 999px;
+}
+```
+
+### F8. Citation anchors and footnotes
+
+Reference anchor consistency:
+- Every `<a href="#ref-n">[n]</a>` must map to one `<li id="ref-n">`.
+- No dangling reference IDs.
+
+```css
+a.citation {
+  color: #1f2937;
+  text-decoration: none;
+  vertical-align: super;
+  font-size: 0.78em;
+}
+
+.ref-list li {
+  padding-inline-start: 2em;
+  text-indent: -2em;
+}
+```
+
+Paged footnote pattern:
+```css
+.fn {
+  float: footnote;
+}
+
+.fn::footnote-call {
+  content: counter(footnote);
+  vertical-align: super;
+  font-size: 0.78em;
+}
+
+.fn::footnote-marker {
+  content: counter(footnote) ". ";
+}
+
+@page {
+  @footnote {
+    margin-top: 1.1em;
+    border-top: 1px solid #d1d5db;
+    padding-top: 0.55em;
+  }
+}
+```
+
+### F9. Layout tuning guide
+
+When page count or layout does not meet targets, adjust in this priority order:
+
+| Symptom | First move | Second move | Avoid |
+|---|---|---|---|
+| Page count exceeds target | reduce heading sizes | reduce line-height slightly | aggressive body font shrink |
+| Page count below target | increase line-height | increase page margins slightly | adding low-value filler text |
+| Table overflows page width | reduce cell padding | allow word wrapping on long tokens | forcing fixed table widths |
+| Figure breaks layout | reduce figure max-width/max-height | move figure near paragraph boundary | `avoid` on large parent containers |
+| Text looks cramped | raise line-height | increase side margins slightly | oversized heading jumps |
+| Resume too sparse/dense | tune margins first | then adjust heading scale | changing section order silently |
+
+## G Fidelity Gates
+
+Run all gates before final delivery.
+
+### G1. Hyperlinks
+
+- Ensure external links keep original `href`.
+- In conversion call, enforce `preserve_links=true`.
+
+### G2. Images (3-pass)
+
+1. Source extraction count (baseline)
+2. HTML `<img>` count and mapping
+3. Post-conversion result check
+
+### G3. Anchor integrity
+
+- Cross-references must point to real IDs.
+- Place `id` on top-level containers (`figure`, section wrapper), not inner text nodes.
+- For TOC and page refs, use print-aware links with page target resolution (`target-counter`).
+
+### G4. Structure parity (for transforms)
+
+- Keep source section order unless user requests restructuring.
+- Do not inject a cover page when source had none (unless user requests one).