208 lines
12 KiB
Markdown
Executable File
208 lines
12 KiB
Markdown
Executable File
# Route: Create New Document
|
||
|
||
## Workflow
|
||
|
||
```
|
||
0. Check if user provided a reference template (PDF/docx) → if yes, use Template-Following Mode below
|
||
1. Load `references/design-system.md` → select palette and cover recipe
|
||
2. Load `references/common-rules.md` → shared layout, font, placeholder rules
|
||
3. Check user keywords → load scene file if applicable
|
||
4. Load `references/docx-js-core.md`
|
||
5. If complex → also load `references/docx-js-advanced.md`
|
||
6. Plan document structure (outline)
|
||
7. Write JS/TS using docx library
|
||
⚠️ **BEFORE writing any string**: scan ALL Chinese text for curly quotes `""''` and replace with `\u201c \u201d \u2018 \u2019` — bare curly quotes break JS syntax (see docx-js-advanced.md § Quotes Escaping)
|
||
8. Run with `bun run generate.js` (or `node generate.js`)
|
||
9. If TOC → run `python3 "$DOCX_SCRIPTS/add_toc_placeholders.py" output.docx --auto`
|
||
10. Run post-generation checklist (see SKILL.md)
|
||
```
|
||
|
||
## Template-Following Mode
|
||
|
||
When the user provides a reference document (PDF/docx) as a **formatting template** (e.g., "generate following this template format", "refer to this sample"), switch to template-following mode instead of the standard recipe-based workflow:
|
||
|
||
1. **Extract the template's structure** — cover layout, section order, heading hierarchy, page breaks, special pages (e.g., advisor comments page, approval form)
|
||
2. **Replicate structure exactly** — every major structural unit becomes a **separate section** (cover, body, appendix/form pages) with appropriate margins and page breaks
|
||
3. **Fill content** from the user's content source, or generate per user instructions
|
||
4. **Preserve template-specific elements** — school-specific forms, signature areas, stamp placeholders, advisor comment blocks → reproduce as-is with placeholder text (e.g., "Advisor (signature):")
|
||
5. **Maintain formatting fidelity** — font choices, table layouts, spacing, and alignment should match the template, not the standard design-system palettes
|
||
|
||
⚠️ **Do NOT apply standard cover recipes (R1–R7) when a user-provided template defines its own cover format.** Follow the template's cover layout instead. Standard `common-rules.md` constraints (e.g., `WidthType.PERCENTAGE`, `allNoBorders` for cover wrapper, `Rule 8` line spacing) still apply for cross-engine compatibility.
|
||
|
||
⚠️ **Each distinct page type = separate section.** Cover section (margin: 0), body section (standard margins), appendix/form pages (may need different margins or orientation). Never place cover + body + appendix in a single section.
|
||
|
||
---
|
||
|
||
## Decision Tree
|
||
|
||
### Cover Page?
|
||
- **YES**: Reports, theses, proposals, plans, or 3+ page docs with clear title/author
|
||
- **NO**: Resumes, contracts, official documents, exam papers, short memos
|
||
|
||
### Cover Style Selector — Recipe Router
|
||
|
||
Covers use **7 validated layout recipes (R1–R7)**, auto-selected by `selectCoverRecipe()` in `references/design-system.md` (the **authoritative source** — do NOT duplicate the function).
|
||
|
||
**Quick Reference:**
|
||
|
||
| docType | Recipe | Default Palette |
|
||
|---------|--------|-----------------|
|
||
| contract / official / exam / resume | null (no cover) | — |
|
||
| academic | R5 (Clean White) | ACADEMIC |
|
||
| proposal_report (thesis proposal) | R5 (Clean White) | ACADEMIC |
|
||
| lesson_plan (STEM) | R4 (Top Color Block) | DM-1 |
|
||
| lesson_plan (arts/general) | R6 (Editorial Warm) | ED-1 |
|
||
| creative / branding / design | R3 (Centered Card Frame) | SN-2 |
|
||
| cultural / newsletter / internal | R6 (Editorial Warm) | ED-1 |
|
||
| activity / event | R6 (Editorial Warm) | ED-1 |
|
||
| trend/research (cultural/creative/brand) | R7 (Swiss Tech) | ST-1 |
|
||
| whitepaper | R2 (Double-Rule Frame) | IG-1 / CM-2 |
|
||
| consulting | R2 (Double-Rule Frame) | MIN-1 |
|
||
| proposal / plan | R4 (Top Color Block) | GO-1 |
|
||
| report | R1 (Pure Paragraph Left) | by industry |
|
||
| default | R1 (Pure Paragraph Left) | DS-1 |
|
||
|
||
⚠️ **Long title routing:** After selecting recipe, apply `applyLongTitleOverride(result, titleLength)`. Titles >20 chars on R3/R4/R6 → fall back to R1. Titles >30 chars on R2 → fall back to R1. R5 is never overridden.
|
||
|
||
⚠️ **Academic thesis cover:** Use `buildAcademicCover()` from `scenes/academic.md`.
|
||
|
||
⚠️ **Thesis proposal report (开题报告):** Use `buildProposalCover()` from `scenes/academic.md`. Cover MUST be an independent section. Keywords: "开题报告" (Chinese), "thesis proposal", "research proposal" — NOT the same as business proposals (which use R4).
|
||
|
||
### Table of Contents?
|
||
- **YES**: 3+ major sections (H1 headings)
|
||
- **NO**: Resumes, exam papers, short docs, contracts (<20 clauses)
|
||
|
||
→ See `references/toc.md` for the complete TOC reference (3-step process, code examples, common bugs).
|
||
|
||
### Headers/Footers?
|
||
- **YES** by default (page numbers minimum)
|
||
- **NO**: cover page section, official docs (special format)
|
||
|
||
### Load Math Formulas?
|
||
When: exam papers, academic papers, physics/math/chemistry → load `references/math-formulas.md`
|
||
|
||
### Load Chart Templates?
|
||
When: data visualization, reports with charts → load `references/chart-templates.md`
|
||
|
||
## Outline Rules
|
||
|
||
**User provides outline** → Follow EXACTLY. No additions, deletions, or reordering.
|
||
|
||
**No outline** → Create from scene template:
|
||
- **Academic:** Abstract → TOC → Body → References
|
||
- **Report:** Use `selectReportType()` to determine type, then follow template A–F:
|
||
- analysis → Template A (Executive Summary → Background → Scope & Method → Findings → Diagnosis → Conclusions)
|
||
- experiment → Template B (Abstract → Objective & Hypothesis → Environment → Procedure → Results → Error Analysis → Conclusions)
|
||
- testing → Template C (Overview → Scope & Environment → Test Plan → Results → Defects → Risks → Conclusions)
|
||
- research → Template D (Summary → Background → Subjects & Method → Sample → Findings → Synthesis → Recommendations)
|
||
- review → Template E (Overview → Goals → Review → Results → Issues → Lessons → Action Plan)
|
||
- proposal → Template F (Summary → Status → Goals → Solution → Roadmap → Resources → Risks → Benefits)
|
||
- **Contract:** Use `selectContractType()` then follow template A–E:
|
||
- bilateral → Template A (Header → Parties → Recitals → Definitions → Subject → Price → Rights → Delivery → Tax → IP → Breach → Force Majeure → Termination → Notices → Dispute → Miscellaneous → Signature)
|
||
- transfer → Template B (Header → Recitals → Definitions → Subject → Consideration → Closing → Representations → Tax → Breach → Dispute → Signature)
|
||
- nda → Template C (Header → Recitals → Definition → Obligations → Use Restrictions → Return/Destroy → Exceptions → Duration → Breach → Dispute → Signature)
|
||
- framework → Template D (Header → Recitals → Purpose → Scope → Division → Mechanism → Commercial → Confidentiality → Term → Breach → Dispute → Signature)
|
||
- terms → Template E (Title → Definitions → Services → Rights → Liability → Fees → IP → Termination → Notices → Dispute → Miscellaneous)
|
||
- **Official:** Use `selectOfficialType()` + `needsRedHeader()`:
|
||
- notice → Template A ([Red header] → [Doc number] → Title → Addressee → Reason → Items → Requirements → [Attachments] → [Signature] → [Date] → [Colophon])
|
||
- letter → Template B ([Red header] → [Doc number] → Title → Addressee → Reason → Negotiation/Reply → Closing → [Signature] → [Date])
|
||
- reply → Template C ([Red header] → [Doc number] → Title → Addressee → Reference → Reply → "This is the reply." → Signature → Date)
|
||
- minutes → Template D (Title → Meeting Overview → Agreed Items → Responsibilities → [Distribution]) — typically no red header
|
||
- Present outline to user before generating when possible
|
||
|
||
## Scene Completeness
|
||
|
||
Include ALL elements a scene specifies:
|
||
- **Academic thesis:** Cover (`buildAcademicCover()` in its own section), abstract, TOC, references
|
||
- **Thesis proposal report (thesis proposal / 开题报告):** Cover (`buildProposalCover()` in its own section), body sections per proposal template. Cover MUST be a separate section.
|
||
- **Report:** Cover, executive summary, conclusions
|
||
- **Contract:** Party info, recitals, complete clause closure, signature block, uniform `【】` placeholders
|
||
- **Official:** Correct document type, specific title, closing phrase matching type, proper numbering hierarchy, red header only when requested
|
||
- **Exam:** Student info area, scoring criteria
|
||
|
||
Generate complete, substantive content — not skeletons.
|
||
|
||
## Content Guidelines
|
||
|
||
- **Length**: "detailed report" = 3000+ words. "brief summary" = 500–1000.
|
||
- **Data**: Use user's data, or generate realistic placeholders
|
||
- **Charts**: Use `references/chart-templates.md` matplotlib templates → PNG → embed
|
||
- **Math**: Use `references/math-formulas.md` LaTeX → docx-js Math mapping
|
||
- **Tables**: For structured data, not layout
|
||
- **Numbering**: Figures, tables numbered sequentially with cross-references
|
||
|
||
## Code Architecture
|
||
|
||
### Heading Style Rule (Mandatory)
|
||
|
||
**All body chapter headings MUST use `heading: HeadingLevel.HEADING_X`** — never simulate with bold + large font (TOC cannot detect simulated headings).
|
||
|
||
**Exception:** Cover title and TOC title ("目录") heading MUST NOT use Heading style.
|
||
|
||
### Blank Page Prevention
|
||
|
||
→ See SKILL.md § Post-Generation checklist for the full set of rules.
|
||
|
||
Key rules:
|
||
1. No double page breaks (SectionType.NEXT_PAGE + PageBreak = blank page)
|
||
2. PageBreak paragraphs should have visible text content
|
||
3. No more than 3 consecutive empty paragraphs
|
||
4. Cover section: ≤2 trailing empty paragraphs, no trailing PageBreak
|
||
|
||
### Builder Pattern Example
|
||
|
||
```js
|
||
const { Document, Packer, Paragraph, TextRun, Header, Footer,
|
||
AlignmentType, HeadingLevel, PageNumber } = require("docx");
|
||
const fs = require("fs");
|
||
|
||
// 1. Palette
|
||
const P = { primary: "#101820", body: "#182030", secondary: "#506070", accent: "#8090A0" };
|
||
const c = (hex) => hex.replace("#", "");
|
||
|
||
// 2. Component builders
|
||
function heading(text, level = HeadingLevel.HEADING_1) {
|
||
return new Paragraph({
|
||
heading: level,
|
||
spacing: { before: level === HeadingLevel.HEADING_1 ? 360 : 240, after: 120 },
|
||
children: [new TextRun({ text, bold: true, color: c(P.primary), font: { ascii: "Calibri", eastAsia: "SimHei" } })]
|
||
});
|
||
}
|
||
|
||
function body(text) {
|
||
return new Paragraph({
|
||
alignment: AlignmentType.JUSTIFIED,
|
||
indent: { firstLine: 480 },
|
||
spacing: { line: 312 },
|
||
children: [new TextRun({ text, size: 24, color: c(P.body) })],
|
||
});
|
||
}
|
||
|
||
// 3. Assembly — cover + body in separate sections
|
||
const doc = new Document({
|
||
styles: { default: { document: {
|
||
run: { font: { ascii: "Calibri", eastAsia: "Microsoft YaHei" }, size: 24, color: c(P.body) },
|
||
paragraph: { spacing: { line: 312 } },
|
||
}}},
|
||
sections: [
|
||
{ properties: { page: { margin: { top: 0, bottom: 0, left: 0, right: 0 } } },
|
||
children: buildCoverR1(config) }, // ← use recipe from design-system.md
|
||
{ properties: { page: { margin: { top: 1440, bottom: 1440, left: 1701, right: 1417 } } },
|
||
footers: { default: new Footer({ children: [new Paragraph({ alignment: AlignmentType.CENTER,
|
||
children: [new TextRun({ children: [PageNumber.CURRENT], size: 18 })] })] }) },
|
||
children: [heading("Chapter 1"), body("Content...")] },
|
||
],
|
||
});
|
||
|
||
Packer.toBuffer(doc).then(buf => { fs.writeFileSync("output.docx", buf); });
|
||
```
|
||
|
||
## Post-Generation
|
||
|
||
→ See SKILL.md § Post-Generation for the complete two-layer verification checklist.
|
||
|
||
```bash
|
||
python3 "$DOCX_SCRIPTS/postcheck.py" output.docx
|
||
```
|
||
⚠️ **Running postcheck.py is MANDATORY.** Fix all ❌ errors before delivering.
|