SKILL.md

name

experiment-report

description

Write Chinese university lab reports and course-design reports, or fit report content into WPS, Word, or docx templates. Use in Codex, OpenClaw, or other local agent workflows when the user asks for an experiment report, lab report, course design report, experiment summary, screenshot insertion, captions, PDF preview, or template filling from topics, requirements, code, data, tutorial pages, screenshots, or results.

When this skill applies

• The user asks to write or complete an experiment report from zero.
• The user asks for a course design report that follows a fixed school-style structure.
• The user has a blank WPS, Word, or docx template and wants it filled.
• The user provides an experiment title, requirements, screenshots, code, data, outputs, or conclusions and wants a report draft or filled report.
• The user provides a tutorial article or CSDN page as the main procedural reference.

Core workflow

1. Collect the minimum useful inputs:
   • course name
   • experiment name
   • template path or screenshots if formatting matters
   • experiment requirements or task description
   • actual steps, code, screenshots, outputs, data, or conclusions
   • whether the user wants a factual report or a clearly labeled sample version
   • If the user already provides enough facts to write the report body, do not stop to ask for optional metadata such as name, class, date, or template files.
   • For a DOCX or other template-controlled deliverable, if the user has not said whether a preferred template exists, ask once: 你有老师、学校或自己认可的优秀 DOCX/DOC 模板吗？有的话请上传，我会优先保持原格式；没有的话，我会从十套不含学校标识的内置模板中选择。
   • Do not ask this template question when the user only wants report-body text. Do not ask it again after the user says no, chooses an internal template, or provides a template.
2. Write the full report content before touching template formatting.
3. If critical facts are missing, do not fabricate exact data, screenshots, or measurements.
4. If a local docx template exists and shell execution is available, run scripts/analyze-docx-template.ps1 -TemplatePath <template.docx> first. Use scripts/extract-docx-template.ps1 -Path <template.docx> when a readable outline is also useful. If the user has no template, run python -m universal_report select-template --repo-root <repo> --report-type <type> --course <course> or choose from the ten entries in examples/report-templates/catalog.json.
5. Treat the generated TemplateStyleContract and extracted structure as the source of truth. The contract includes effective style inheritance, page setup, title/body/caption roles, table geometry, headers, footers, sections, image placeholders, and structural risks.
6. If a template exists, adapt the finished content to the template order and field names.
7. If the user explicitly wants a filled local docx output and the template matches common report patterns, generate a field map with scripts/generate-docx-field-map.ps1 and then run scripts/apply-docx-field-map.ps1.
   • Use label keys for normal blank-field filling.
   • Use paragraphs arrays for section-body content.
   • Use mode: "after" when the template keeps a fixed heading paragraph and the actual content should go into the following blank paragraph.
   • Use location keys such as P2 or T1R1C2 only when explicit overwrite is needed.
8. If the user also provides screenshots or experiment photos and wants them embedded into the final docx, prefer scripts/generate-docx-image-map.ps1 on the filled copy and then run scripts/insert-docx-images.ps1.
9. Preserve user-template formatting by default. Run scripts/format-docx-report-style.ps1 only when there is no user template, or when the user explicitly asks for normalization or a repository style profile.
10. Prefer content-first completion over fragile GUI wandering.
11. If screenshots are provided, treat them as factual evidence and layout assets.
12. If a tutorial page is provided, treat it as procedural reference and rewrite it into report-style Chinese instead of copying it.
13. When a local workflow should fetch tutorial references before generation, prefer scripts/prepare-report-prompt.ps1 with -ReferenceUrls or -ReferenceTextPaths.
14. When the user provides local file paths in a direct chat workflow, inspect those files first if tool access is available; if a path cannot actually be opened, explicitly say which path was inaccessible instead of pretending it was read.
15. When the user asks for a final local docx result and the required paths are already present, prefer finishing the end-to-end local workflow over stopping at a body-only draft.
16. On Windows PowerShell, do not chain shell commands with &&; use separate executions or ; so the command remains valid in legacy PowerShell hosts.
17. When intermediate JSON or text files contain Chinese paths, captions, or section names, prefer writing them through PowerShell with explicit UTF-8 encoding or through the bundled scripts; do not rely on generic editor-style writes that may corrupt non-ASCII content.
18. When direct chat already has a template path, screenshots, identity metadata, and either a finished report body or tutorial references, prefer the one-shot local wrapper scripts/build-report-from-feishu.ps1 over ad-hoc multi-step shell orchestration.
19. If direct chat includes uploaded image attachments and the user also provides local image paths, use the uploaded images to understand the visible content and use the local image paths as the actual files for deterministic docx embedding.
20. If direct chat includes uploaded image attachments but no manual local image paths, check whether the runtime injected attachment note lines such as [media attached ...] into the prompt. If those lines contain usable image file paths, extract them and pass them into -ImagePaths for the local wrapper instead of stopping at body-only output.

Template fidelity and visual standards

• A user-supplied DOCX template has the highest formatting priority. Default to -TemplateStyleMode preserve; do not replace its page setup, fonts, paragraph spacing, title hierarchy, tables, borders, headers, footers, sections, or caption style with repository defaults.
• A user upload always wins over a selected internal template. Do not blend the uploaded template with an internal design.
• When no user template exists, choose exactly one of the ten catalog entries: neutral-classic-lab, neutral-bordered-lab, neutral-engineering-lab, neutral-course-design, neutral-modern-minimal, neutral-compact-header-lab, neutral-review-panel-lab, neutral-code-notebook-lab, neutral-data-analysis-lab, or neutral-project-dossier. Use -BuiltInTemplateId for local wrappers when the choice is explicit.
• Prefer neutral-code-notebook-lab for programming, algorithm, code, test, and debug experiments; neutral-data-analysis-lab for measurement, statistics, raw-data, and error-analysis work; neutral-compact-header-lab for short weekly records; and neutral-review-panel-lab when teacher comments, score, or signature fields are required.
• Prefer neutral-engineering-lab for computer-network, operating-system, database, Web, Android, and software-engineering experiments. Prefer neutral-project-dossier for long-form system projects and neutral-course-design for ordinary course-design reports. Otherwise default to neutral-classic-lab; use the bordered or modern template when the requested visual direction calls for it.
• Internal templates must pass python -m universal_report audit-template-catalog --repo-root <repo>. They may not contain real school/college names, logos, watermarks, example student identities, embedded third-party media, or copied sample report content.
• Treat the internal DOCX files as original neutral reconstructions under the repository license. Public templates and GitHub projects are design references only; do not copy their branding, sample text, media, or restricted assets into the internal files.
• Before rendering, create or reuse a TemplateStyleContract. After rendering, run scripts/validate-docx-format.ps1 and report the exact failed contract items instead of saying only that formatting is wrong.
• Use -TemplateStyleMode normalize -StyleFinalDocx only for the repository default template, demo output, or an explicit user request to unify styling.
• Default image layout is one image per line with a concrete caption below it. Preserve aspect ratio, keep the image and caption together when practical, and use row/grid layouts only when explicitly requested.
• Honor an exact requested image count. Deduplicate by content hash and record selected, rejected, and duplicate files plus selection reasons in image-manifest.json; never duplicate an image merely to reach the count.
• Course-design flowcharts, generated structure tables, large fixed image widths, and other profile enhancements are allowed only for a default/normalized template. Do not inject them automatically into an unrelated user template.
• Fast mode must still run structural, layout, and format validation. Strict mode must export DOCX to PDF, render every page, and run visual checks; if that chain cannot complete, return needs-fix rather than success.
• LibreOffice is the preferred PDF converter. WPS/Microsoft Word COM is opt-in only, must have a timeout, and may clean up only Office processes started by the current automation run.
• Keep these rules scoped to structured experiment and course-design reports. Do not claim support for arbitrary office documents whose template structures have not been analyzed.

Writing rules

• Use clear Chinese suitable for university reports.
• Keep claims consistent with the provided requirements, code, data, screenshots, and outputs.
• Avoid empty filler and generic AI phrasing.
• If the user provides the course name or experiment name, write them explicitly into the final report instead of assuming the surrounding chat context is enough.
• If the user already supplied the experiment topic, environment, steps, results, and required headings, write the report immediately instead of asking for more materials.
• Ask follow-up questions only when missing facts would make the result materially wrong, or when the user explicitly wants template filling but no template is available.
• If the user only wants the report body, missing personal identity fields must not block generation.
• If direct chat is being used with local file paths, avoid optimistic assumptions about file access; either read the files or clearly state that file access was not available.
• When the experiment is software-related, include environment, implementation steps, results, analysis, and conclusion.
• When the template has fixed headings, preserve them exactly.
• If webpage instructions and user screenshots differ, trust the user screenshots and outputs.
• If both uploaded image attachments and local image paths are available, use the attachments as the semantic reference for what each image shows, but use the local paths for the final docx image insertion workflow.
• If uploaded image attachments are present without manual local paths, prefer the prompt-injected attachment paths from [media attached ...] notes as the ImagePaths input for scripts/build-report-from-feishu.ps1 or scripts/generate-docx-image-map.ps1. If the runtime does not expose any real attachment path, say that clearly instead of pretending direct docx insertion succeeded.
• When screenshots are provided without explicit grouping, infer 实验环境, 实验步骤, 实验结果, or 问题分析 from filenames and visible content, but do not invent unseen details.
• If a local workflow needs temporary JSON such as field maps or image maps and those files include Chinese text, write them in explicit UTF-8 and retry from that stage if parsing fails.

Output modes

• Default: final report content with headings ready to paste.
• Template mode: exact field-to-content mapping in template order.
• Template mode can include block values such as {"section-body": ["paragraph one", "paragraph two"]} when the template body has multi-paragraph sections.
• Image mode: when screenshots should be embedded into a docx, prefer image specs or an image insertion map that can be passed to scripts/generate-docx-image-map.ps1 or scripts/insert-docx-images.ps1. Stable section anchors such as 实验步骤 or 实验结果 are preferred over fragile paragraph numbers when the filled docx may add or move paragraphs.
• Completion mode: if the user explicitly asks to complete the template, first finish the content, then attempt template filling only if tooling is actually available.

Optional helpers

• For local docx templates, run scripts/extract-docx-template.ps1 to capture the actual field order before producing a field mapping.
• For local docx templates that should be machine-filled, run scripts/generate-docx-field-map.ps1 after the report body is ready, then run scripts/apply-docx-field-map.ps1.
• For local screenshots or experiment photos that should be embedded into the filled docx, prefer scripts/generate-docx-image-map.ps1 first and then run scripts/insert-docx-images.ps1 on the already-filled copy.
• For a cleaner normalized copy, optionally run scripts/format-docx-report-style.ps1 only when the user explicitly wants repository styling or no user template exists.
• Use scripts/plan-report-content.ps1 to create a structured content plan before body rendering when materials come from multiple sources.
• Use scripts/analyze-docx-template.ps1 and scripts/validate-docx-format.ps1 for template-contract analysis and post-render fidelity checks.
• Use scripts/run-visual-validation.ps1 for strict PDF and per-page preview validation.
• Use python -m universal_report list-templates --repo-root <repo> to show the five internal options, select-template to select one, and audit-template-catalog to enforce neutrality and provenance.
• For chat-driven local execution, prefer scripts/build-report-from-feishu.ps1 so the wrapper can keep the final deliverable in the output root and move intermediate files into an artifacts/ subdirectory.
• The image pipeline can resolve staged relative attachment paths such as media/inbound/example.png from OpenClaw-style prompts; when those paths appear in prompt-injected media notes, reuse them directly in -ImagePaths.
• When the template has fixed section headings plus blank paragraphs, prefer block mappings over flattening long body content into a single field.
• For public tutorial pages, prefer scripts/fetch-web-article.ps1; keep scripts/fetch-csdn-article.ps1 as the compatibility wrapper for CSDN-specific workflows.
• When a tutorial page should flow directly into report generation, prefer scripts/prepare-report-prompt.ps1 so the extracted reference text is appended to the final request deterministically.
• The helpers are optional. If they are unavailable, still finish the report from the information already provided.

Read references as needed

• Read references/common-structures.md when choosing a report outline.
• Read references/template-fit.md when the user provides a WPS, Word, or docx template path or template screenshots.
• Read references/image-handling.md when the user provides experiment screenshots or process images.