@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/docx/docs/acceptance.md

@@ -0,0 +1,139 @@
+# Acceptance profiles
+
+Read this after the route has executed or when you are preparing the final validation pass. This file
+defines post-write / pre-delivery gates, not first-hop dispatch.
+
+No DOCX task is complete until it passes the acceptance profile mapped to its task family.
+
+## Profiles
+
+### light
+Use for:
+- read-only tasks
+- trivial extraction or diagnosis
+
+Checks:
+- output exists and is readable
+- answer is grounded in the selected evidence type
+- for READ_RENDERED, artifact creation alone is insufficient; the answer must include a rendered issue summary
+
+### normal
+Use for:
+- ordinary create and edit/fill work
+
+Checks:
+- output opens successfully
+- builtin structure validation when a DOCX was written
+- diff or equivalent evidence that the intended change happened
+- rendered verification if the change obviously risks layout
+
+### strict
+Use for:
+- apply-template
+- repair-layout
+- multi-section create
+- header/footer, TOC, numbering, or section-sensitive edits
+
+Checks:
+- output opens successfully
+- builtin structural validation
+- business validation / gate-check where applicable
+- rendered verification
+- rendered issue summary or rendered report that names the affected pages and structure alignment
+- source-preservation sanity check
+- task-specific checklist under `acceptance-checklists/`
+
+### forensic
+Use for:
+- compare-two-docx
+- high-risk documents where the user wants an audit trail
+
+Checks:
+- content diff
+- structure diff
+- rendered diff or rendered issue summary
+- explicit risk classification
+
+## Task family mapping
+
+| Task family | Acceptance profile |
+| --- | --- |
+| READ_CONTENT | light |
+| READ_STRUCTURE | light |
+| READ_RENDERED | light |
+| CREATE_DOCX | normal or strict depending on structural complexity |
+| EDIT_FILL_DOCX | normal |
+| APPLY_TEMPLATE | strict |
+| REPAIR_LAYOUT | strict |
+| COMPARE_TWO_DOCX | forensic |
+
+## Strict reminders
+
+The following jobs are not finished without rendered verification:
+
+- template application
+- layout repair
+- multi-section document creation
+- header/footer changes
+- TOC changes
+- page-number system changes
+- table-overflow / blank-page fixes
+
+For READ_RENDERED and REPAIR_LAYOUT, rendered verification means:
+- the affected pages are named
+- the visual symptom is summarized
+- the structure cause alignment is delivered
+- the output is not merely a PDF / PNG artifact dump
+
+## Builtin validation path
+
+When a DOCX is written and backend `D` or `S` is involved, reuse the builtin validator:
+
+```bash
+$CLI merge-runs --input out.docx
+$CLI validate --input out.docx --xsd <skill_dir>/assets/xsd/wml-subset.xsd
+$CLI validate --input out.docx --business
+```
+
+For template work, add:
+
+```bash
+$CLI validate --input out.docx --gate-check <skill_dir>/assets/xsd/business-rules.xsd
+```
+
+## Output gates by task family
+
+These are the concrete gates. Prefer these over abstract schemas.
+
+### READ_STRUCTURE
+- `python3 <skill_dir>/scripts/read_docx_structure.py <input.docx> --json` must succeed
+- output JSON must contain top-level keys: `summary`, `sections`, `styles`, `numbering`, `fields`, `diagnostics`
+- if a focused read is requested, the answer must name the specific structure objects involved (styles / sections / fields / refs / diagnostics)
+
+### READ_RENDERED
+- rendered artifact command must succeed (`docx_to_pdf.py` and/or `render_docx_pages.py`)
+- `python3 <skill_dir>/scripts/rendered_report.py ... --format markdown` must succeed
+- rendered report markdown must contain:
+  - `# Rendered issue report`
+  - `## Artifact summary`
+  - `## Page issue summary`
+  - `## Completion checklist`
+- each reported issue must name pages, visual symptom, structure alignment, likely structural causes, and recommended checks
+
+### REPAIR_LAYOUT
+- all READ_RENDERED gates apply twice: before repair and after repair
+- both reports must use the same issue classes and page references unless the repair itself changes page topology
+- success is blocked unless the after-repair report shows the original complaint no longer reproduces
+
+### COMPARE_TWO_DOCX
+- final answer must contain four titled blocks:
+  - `Content differences`
+  - `Structure differences`
+  - `Rendered differences`
+  - `Risk classification`
+- the result must explicitly name the highest-risk difference
+
+### CREATE_DOCX / EDIT_FILL_DOCX / APPLY_TEMPLATE
+- when a DOCX is written, builtin validation commands must succeed
+- if layout-sensitive, rendered acceptance is required
+- deliverable must name changed files / commands run / why the chosen backend matches the task

package/server/assets/skills/docx/docs/anti-patterns.md

@@ -0,0 +1,14 @@
+# Anti-patterns
+
+These are known bad behaviors. Do not do them.
+
+1. Treat every WRITE task as a dotnet task
+2. Route formal CREATE_DOCX through pandoc because the source started as Markdown / LaTeX / HTML
+3. Mutate zipped OOXML with raw string replace
+4. Deliver template work without rendered inspection
+5. Fill placeholders before checking anchor atomicity
+6. Use `<skill_dir>` docs with `$0` or `readlink` path tricks
+7. Silently switch backend after a gate fails
+8. Insert content with a non-unique locator
+9. Use local XML patching for section/header/footer/numbering graph work
+10. Say “looks fine” without the acceptance profile that the task requires

package/server/assets/skills/docx/docs/backends.md

@@ -0,0 +1,116 @@
+# Execution backends
+
+Read this only after the route is clear. For generation routes, recipe / template-mode choice comes
+first; backend arbitration comes second.
+
+Execution is a routing decision, not a personal preference. Choose the backend from input shape and
+preservation requirements, not from what feels strongest.
+
+Shared roots:
+
+```bash
+# macOS / Linux / WSL
+DOCX_ROOT="<skill_dir>"
+CLI="dotnet run --project $DOCX_ROOT/scripts/dotnet/MiniMaxAIDocx.Cli --"
+```
+
+```powershell
+# Windows
+$env:DOCX_ROOT = "<skill_dir>"
+$CLI = "dotnet run --project $env:DOCX_ROOT\scripts\dotnet\MiniMaxAIDocx.Cli --"
+```
+
+## Backend D — builtin dotnet CLI
+
+**Use when**:
+- creating DOCX from structured config
+- editing an existing DOCX while preserving it as the same document
+- placeholder fill, table fill, replace-text, header/footer update
+- applying CJK 公文 / 学位论文 / institutional templates
+- running builtin analyze / diff / merge-runs / validate / gate-check
+
+**Hard no**:
+- pretending it can ingest raw Markdown / LaTeX directly without an explicit normalization step
+- pretending it resolves citations or converts bibliography sources by itself
+
+**Gate**:
+```bash
+# macOS / Linux / WSL
+test -d "$DOCX_ROOT" || { echo "FATAL: docx skill root missing" >&2; exit 1; }
+bash "$DOCX_ROOT/scripts/env_check.sh" | grep -E "^\[OK\][[:space:]]+dotnet\b" || {
+  echo "FATAL: dotnet SDK not available" >&2
+  exit 1
+}
+```
+
+```powershell
+# Windows
+if (-not (Test-Path $env:DOCX_ROOT)) { Write-Error "FATAL: docx skill root missing"; exit 1 }
+$check = & powershell -ExecutionPolicy Bypass -File "$env:DOCX_ROOT\scripts\env_check.ps1" -Level Full
+if (-not ($check | Select-String -Pattern '^\[OK\]\s+dotnet\b')) {
+    Write-Error "FATAL: dotnet SDK not available"; exit 1
+}
+```
+
+**Escalation**:
+- if the command surface is insufficient but the job is still DOCX-graph work, stop using `D` and reroute to `S`
+- if the input is still raw Markdown / LaTeX, stop and normalize it into a document plan / structured config first; do not reroute CREATE to `P`
+
+## Backend S — direct OpenXML SDK
+
+**Use when**:
+- the task is structurally beyond the builtin dotnet CLI surface
+- you need direct control over `document.xml`, `styles.xml`, `numbering.xml`, header/footer parts,
+  comments, fields, or relationships
+- you must rebuild a graph, not just call a builtin command
+
+**Hard no**:
+- using S because you forgot that P or D already solves the job
+- writing SDK code from memory without reading the matching builtin samples first
+
+**Gate**:
+Same as `D`, plus read the relevant sample under:
+
+```bash
+$DOCX_ROOT/scripts/dotnet/MiniMaxAIDocx.Core/Samples/*.cs
+```
+
+## Backend X — local XML patch runtime
+
+**Use when**:
+- you need deterministic local XML inspection or low-topology patching
+- you need anchor atomicity validation
+- you need a patch plan, dry-run, or local unpack/pack flow
+- you need to strip direct formatting, merge runs locally, or perform a constrained local replace
+
+**Hard no**:
+- section break topology changes
+- header/footer graph rewrites
+- numbering graph rebuilds
+- image relationship insertion or repair
+- arbitrary cross-part dependency rewrites
+
+**Gate**:
+No heavy toolchain gate. X uses bundled Python scripts only. But it is only valid for operations that
+fit the X safety boundary. If topology risk appears, stop using `X` and reroute to `D` or `S`.
+
+## Selection table
+
+For `CREATE_DOCX` / `APPLY_TEMPLATE`, use this table only after recipe family or template mode is already chosen.
+
+| Input shape | Output requirement | Pick |
+| --- | --- | --- |
+| Markdown / LaTeX / HTML / RST | formal DOCX creation after normalization into document plan / structured config | D |
+| Markdown / LaTeX / HTML / RST + complex graph requirements | normalized create, but CLI surface insufficient | S |
+| Existing DOCX | content edits preserving styles/headers/sections | D |
+| Existing DOCX + institutional template DOCX | template apply / section-aware formatting | D |
+| Structured config | create styled DOCX | D |
+| Existing DOCX | deterministic local low-risk XML patch | X |
+| Any DOCX graph task beyond D surface | byte-level control | S |
+
+## What never happens
+
+- A chosen backend never silently falls back to another backend with a different input contract.
+- CREATE_DOCX is never routed to pandoc as a formal generation backend.
+- X is never stretched into a fake full OpenXML editor.
+- S is never the first instinct when D already matches the task.

package/server/assets/skills/docx/docs/evidence.md

@@ -0,0 +1,73 @@
+# Evidence router
+
+DOCX tasks fail when the wrong truth source is treated as authoritative. This skill uses three evidence
+classes and requires you to choose deliberately.
+
+## The three truths
+
+### Content truth
+What the document says in readable text order.
+Use for:
+- summary
+- retrieval
+- quoting
+- content diff
+- finding a heading by text
+
+### Structure truth
+How Word/OpenXML represents the document.
+Use for:
+- styles
+- sections
+- numbering
+- TOC mechanics
+- header/footer references
+- comments, revisions, fields, bookmarks
+- template internals
+- relationship and part topology
+
+The structure-truth oracle is `scripts/read_docx_structure.py`. It is the primary
+implementation; the dotnet `analyze` command is an optional independent confirmation
+shot, not the source. See `task-read-structure.md` for the full report contract.
+
+### Rendered truth
+What the user actually sees on pages.
+Use for:
+- blank pages
+- cover / TOC / abstract / body layout
+- pagination and page-number issues
+- overflow and clipping
+- table split defects
+- header/footer visual mismatch
+- visual template fidelity
+
+## Default evidence posture by task family
+
+| Task family | Default evidence |
+| --- | --- |
+| READ_CONTENT | content |
+| READ_STRUCTURE | structure |
+| READ_RENDERED | rendered + structure |
+| CREATE_DOCX | source content + optional template structure + rendered acceptance when visual fidelity matters |
+| EDIT_FILL_DOCX | content + structure; add rendered when visual risk exists |
+| APPLY_TEMPLATE | source structure + template structure + output rendered |
+| REPAIR_LAYOUT | rendered -> structure -> rendered again |
+| COMPARE_TWO_DOCX | content + structure + rendered |
+
+## Rules
+
+- If the user asks a page question, rendered truth wins.
+- If the user asks a TOC / section / numbering question, structure truth wins.
+- If the user asks for summary or quote, content truth wins.
+- If you are about to modify a template-driven DOCX, structure truth comes before mutation.
+- If you finish a template or layout task without rendered truth, the task is not finished.
+- If you only generated artifacts and did not produce a page issue summary, rendered truth is still not finished.
+- Rendered truth delivery means visual symptom + page reference + structure alignment, not artifact path only.
+
+## Evidence mistakes to avoid
+
+- Using extracted text to answer section topology questions
+- Using XML alone to declare a visual bug fixed
+- Using screenshots alone to rewrite numbering or TOC rules
+- Skipping structure read before applying an institutional template
+- Treating a PDF/PNG directory as the final rendered answer without a rendered report

package/server/assets/skills/docx/docs/failure-taxonomy.md

@@ -0,0 +1,71 @@
+# Failure taxonomy
+
+Use this doc when a DOCX task fails. Diagnose the failure class first; do not immediately switch
+backend or guess at a fix.
+
+## 1. Input failures
+
+Examples:
+- source file missing
+- template file missing
+- malformed instruction
+- unsupported input format
+- backend toolchain missing
+
+Recovery:
+- stop and report the missing requirement
+- do not switch backend just because a tool is absent
+
+## 2. Template failures
+
+Examples:
+- anchor split across runs
+- duplicate anchors where uniqueness was assumed
+- template manifest and actual template disagree
+- required styleId missing
+- section topology of template not understood
+
+Recovery:
+- run anchor verification or manifest validation
+- fix the template / manifest mismatch before mutation
+
+## 3. XML / graph failures
+
+Examples:
+- invalid element order
+- missing required child
+- broken rel target
+- id collision
+- orphaned comment or footnote ref
+
+Recovery:
+- if builtin validator can repair order, try builtin fix-order path
+- if topology is complex, reroute to `S`
+
+## 4. Rendered failures
+
+Examples:
+- extra blank page introduced
+- header/footer visually lost
+- page numbers reset incorrectly
+- table collapsed across pages
+- image missing or overflowed
+
+Recovery:
+- rerender
+- inspect structure cause
+- patch with `D` or `S`
+- rerender again before declaring success
+
+## 5. Routing failures
+
+Examples:
+- wrong task family chosen
+- wrong evidence type trusted
+- wrong backend chosen for preservation requirement
+- missing acceptance profile
+- raw Markdown / LaTeX was sent directly into CREATE without normalization
+
+Recovery:
+- restart from `router.md`
+- do not “patch over” a bad route with ad-hoc edits

package/server/assets/skills/docx/docs/index.md

@@ -0,0 +1,50 @@
+# docx — index
+
+Start here only after reading `../SKILL.md`.
+
+## Fast dispatch
+
+Pick the first matching route and go there immediately:
+
+- new formal Word deliverable -> `task-create.md`
+- same content, new template / institutional visual system -> `task-apply-template.md`
+- in-place content mutation on an existing DOCX -> `task-edit-fill.md`
+- read meaning -> `task-read-content.md`
+- inspect structure -> `task-read-structure.md`
+- inspect pages -> `task-read-rendered.md`
+- fix visible defects -> `task-repair-layout.md`
+- compare two DOCX files -> `task-compare-two-docx.md`
+
+## What to read only when needed
+
+- `router.md` — if route choice is ambiguous
+- `evidence.md` — if the chosen route needs truth-source arbitration
+- `backends.md` — if backend choice is genuinely ambiguous after route + recipe/mode selection
+- `acceptance.md` — when you are ready to validate output
+
+## Generation-first rule
+
+For `CREATE_DOCX` and `APPLY_TEMPLATE`, do not start with a backend debate. Start with the recipe /
+visual system:
+
+- `references/typography_guide.md`
+- `references/design_principles.md`
+- `references/cjk_typography.md`
+- `scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.cs`
+
+Then choose backend and execute.
+
+## Specialized docs
+
+- `rendered-delivery.md`
+- `template-dsl.md`
+- `xml-patch-dsl.md`
+- `track-changes.md`
+- `tables-and-numbering.md`
+- `failure-taxonomy.md`
+- `anti-patterns.md`
+
+## Core idea
+
+This index exists to shorten dispatch. Route first, hit the generation/read/repair core quickly, then
+open deeper policy docs only when the selected route actually needs them.

package/server/assets/skills/docx/docs/rendered-delivery.md

@@ -0,0 +1,125 @@
+# Rendered delivery contract
+
+Rendered truth is not complete when the skill only emits a PDF or page PNG directory.
+Those are artifacts, not the final answer.
+
+`docx` closes the rendered-truth loop only when it delivers all four layers:
+
+1. rendered artifact exists
+2. problematic pages are named explicitly
+3. each page-level symptom is summarized in user-facing language
+4. each symptom is aligned to structure evidence and likely structural causes
+
+## Closure path
+
+```bash
+python3 <skill_dir>/scripts/docx_to_pdf.py --input in.docx --output /tmp/render.pdf
+python3 <skill_dir>/scripts/render_docx_pages.py in.docx --output-dir /tmp/render-pages
+python3 <skill_dir>/scripts/read_docx_structure.py in.docx --json > /tmp/structure.json
+python3 <skill_dir>/scripts/rendered_report.py \
+  --pdf /tmp/render.pdf \
+  --pages-dir /tmp/render-pages \
+  --structure-json /tmp/structure.json \
+  --issue-file /tmp/rendered-issues.json \
+  --format markdown > /tmp/rendered-report.md
+```
+
+The operator still has to inspect the rendered pages and write `rendered-issues.json`.
+That is intentional: rendered truth starts from what the user sees, not what the XML predicts.
+
+## `rendered-issues.json` input
+
+The issue file is a JSON array. Each item describes a single observed visual problem.
+
+```json
+[
+  {
+    "issueClass": "toc_layout_or_update",
+    "pages": [2, 3],
+    "severity": "high",
+    "visualSymptom": "TOC page numbers do not match the rendered body headings.",
+    "notes": "The rendered TOC still shows pre-edit pagination."
+  }
+]
+```
+
+Supported `issueClass` values:
+
+| Issue class | Use when |
+| --- | --- |
+| `toc_layout_or_update` | TOC looks stale, misaligned, missing entries, or paginates incorrectly |
+| `header_footer_mismatch` | header/footer appearance differs across pages or sections |
+| `page_number_wrong` | visible page numbers are missing, duplicated, restarted, or inconsistent |
+| `extra_blank_page` | a rendered page looks unexpectedly blank |
+| `template_fidelity` | the output no longer visually follows the target template system |
+| `layout_overflow_or_clipping` | body/table/image content clips, overflows, or collides visually |
+
+## Output contract
+
+`rendered_report.py` emits either JSON or Markdown. No schema file is required at runtime; the gate is
+the concrete output contract below.
+
+Use `--task-family READ_RENDERED` for inspection output and `--task-family REPAIR_LAYOUT` for
+before/after repair reports.
+
+When `--format json`, the top-level object must contain:
+
+- `artifactSummary` — PDF path, pages dir, page count, per-page PNG inventory
+- `structureCues` — section / TOC / page-number / contamination cues extracted from structure truth
+- `candidateIssueClasses` — issue classes suggested by structure cues when observation has not yet been written down
+- `pageIssueSummary` — one entry per observed problem
+- `completionChecklist` — explicit reminder that artifact creation alone is not enough
+
+Each `pageIssueSummary` entry must carry the same fields across READ_RENDERED and REPAIR_LAYOUT:
+
+- `issueClass`
+- `label`
+- `pages`
+- `severity`
+- `visualSymptom`
+- `renderedEvidence` — page -> PNG mapping
+- `structureCauseAlignment` — concrete structure signals and what they support
+- `likelyStructuralCauses`
+- `recommendedChecks`
+
+When `--format markdown`, the report must include these sections in order:
+
+1. `# Rendered issue report`
+2. `## Artifact summary`
+3. `## Structure cues`
+4. `## Candidate issue classes`
+5. `## Page issue summary`
+6. `## Completion checklist`
+
+Every issue block under `## Page issue summary` must contain:
+
+- issue label with `issueClass`
+- affected pages
+- severity
+- visual symptom
+- `Structure cause alignment:`
+- `Likely structural causes:`
+- `Recommended checks:`
+
+## Typical symptom -> structure alignment
+
+The report intentionally aligns visual problems to structure causes instead of treating them as two
+separate deliverables.
+
+| Symptom family | Typical structure alignment |
+| --- | --- |
+| TOC drift | TOC field count, heading outline-level risks, section transitions |
+| Header/footer mismatch | per-section header/footer references, titlePg, even/odd header flags |
+| Page-number issues | PAGE / NUMPAGES / SECTIONPAGES fields, section count, titlePg |
+| Blank page | section break types, title-page sections |
+| Template fidelity drift | section graph, missing styles, direct-format contamination |
+| Overflow / clipping | direct formatting, table density, drawing density |
+
+## REPAIR_LAYOUT usage
+
+For layout repair, generate the rendered report twice:
+
+1. before repair — to pin the failing pages and likely structural causes
+2. after repair — to prove the same pages no longer reproduce the complaint
+
+Do not declare REPAIR_LAYOUT complete without the second rendered report.