mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-10-20 23:24:56 +08:00

Files

xyx f7f4fcd035 fix: 内置 Office 技能离线资源与中文校验 / offline Office schemas and XML validation (#218 )

## 中文

内网环境显式使用 Office skill 校验含 `docProps/core.xml` 的文件时，Schema 仍引用远程 Dublin
Core XSD；Windows 默认 GBK 读取中文 UTF-8 XML 也会报错。本修改让 docx/pptx/xlsx 独立携带完整本地
Schema 闭包，并按 XML 编码声明读取文件，保留完整校验。

- 三个 Office skill 分别随包加入 Dublin Core 三份 XSD，复用本地
xml.xsd，补齐来源、原始摘要、许可与适配说明。
- 修正两个 Microsoft XSD 的 ST_String 类型引用，以及 presentation-forge 编辑器脚本路径。
- 市场版本 1.5.11；docx 1.0.4、pptx 1.0.5、xlsx 1.0.4、presentation-forge
0.1.1，同步目录元数据。
- 新增定向回归：遍历所有内置技能的 XSD，拒绝远程依赖并离线编译；模拟 GBK 校验中文 XML，确认非法 Word 节点仍被拒绝。

验证：126 份 XSD 离线编译、2 项回归通过；i18n/catalog 校验均为 0 errors / 105 既有
warnings；translate --check 与 git diff --check 通过。README
两种语言同步。工作树、路径、Git 元数据与发布正文隐私检查通过。

Windows x64 dev 10.0.181 已通过产品 prepare-static 准备随包依赖，并真实调用
Skill(docx)：创建、全校验、解包编辑、重新打包、再全校验均退出 0，两次校验各 18 valid / 0 skipped / 0
errors。该实验禁用 pip/npm 依赖索引，保留模型连接；不等同于正式包或全机断网验收。辅助 Grep
有一次旧参数错误，改正后成功；Python 缓存污染安装摘要另列真机测试跟踪。主仓 market.zip 尚未刷新，源 PR 合并后需通过
sync-market 纳入产品。

## English

Office validation in an intranet deployment still depended on remote
Dublin Core schemas, and reading Chinese UTF-8 XML with the Windows GBK
default could fail. Each Office skill now includes its local schema
dependency closure, and validators read XML as bytes so its declared
encoding is respected without weakening validation.

This also fixes two Microsoft schema type references and the
presentation-forge editor script path. Market version becomes 1.5.11;
skill versions become docx 1.0.4, pptx 1.0.5, xlsx 1.0.4 and
presentation-forge 0.1.1. Vendored schemas include attribution,
licensing, original hashes and adaptation notes.

Validation: 126 schemas compile offline; both targeted regression tests
pass, including GBK input and invalid-node rejection. Catalog/i18n
checks pass with 105 existing warnings each; translation freshness and
whitespace checks pass. Bilingual README and publication privacy checks
are complete.

The actual Windows x64 dev session passed explicit docx loading,
creation, full validation, editing, repacking and revalidation using
product-prepared dependencies. Dependency indexes were disabled while
model connectivity remained available. Packaged/cross-platform testing
and the observed Python-cache installation-digest drift remain
follow-ups. The product bootstrap ZIP will require sync-market after
this source PR merges.

真机测试与剩余验收 / Hardware testing and remaining acceptance:
https://github.com/desirecore/desirecore/issues/4819

---------

Co-authored-by: Johnson <yeslee1126@gmail.com>

2026-10-16 00:06:24 +08:00

28 KiB

Raw Blame History

license, name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market

license

name

description

version

type

risk_level

status

disable-model-invocation

docx Skill

L0: One-line Summary

Create, edit, and process Word documents (.docx), with end-to-end support for creation, XML editing, and format validation.

L1: Overview and Use Cases

Capability

docx is a Procedural Skill that provides full processing capabilities for Word documents. It supports creating new documents via docx-js (Node.js), editing existing documents by unpacking and modifying XML, plus format validation and PDF conversion.

Use Cases

The user needs to create a new Word document (report, memo, contract, letter, etc.)
The user needs to edit an existing .docx file (modify content, add comments, track changes)
The user needs to extract text or table data from a .docx file
The user needs to perform document format conversion (.doc → .docx, .docx → PDF)

L2: Detailed Specification

Script Path Rule (mandatory)

The Python scripts bundled with this skill live inside the skill installation directory. You MUST use full paths when invoking them — never use bare relative paths.

The skill directory is provided by the <skill-dir> tag in the context. Always run the office Python scripts through the cross-platform launcher scripts/with-deps.py, so they reuse the runtime-preinstalled libraries (defusedxml, and lxml for full validation) with no pip install. The launcher is pure Python and behaves identically on macOS / Linux / Windows — it does NOT require bash:

python "<skill-dir>/scripts/with-deps.py" office/unpack.py document.docx unpacked/
python "<skill-dir>/scripts/with-deps.py" office/pack.py unpacked/ output.docx

The launcher runs the target script under a runtime-bundled Python that has lxml/defusedxml preinstalled, and falls back to the system python3 if that bundled Python is unavailable (in which case full XSD validation is skipped gracefully). The script path is relative to scripts/ (e.g. office/unpack.py, comment.py).

NEVER invoke an office script with a bare relative path like python scripts/office/unpack.py — that path does not exist in the user's working directory, and it bypasses the preinstalled libraries. Always go through <skill-dir>/scripts/with-deps.py.

Prerequisites

Python 3 (required)

Before running any Python script, first check whether Python is available:

python3 --version 2>/dev/null || python --version 2>/dev/null

If the command fails (Python is unavailable), you must stop and instruct the user to install Python 3:

macOS: brew install python3 or download from https://www.python.org/downloads/
Windows: winget install Python.Python.3 or download from python.org (check "Add Python to PATH" during installation)
Linux (Debian/Ubuntu): sudo apt install python3 python3-pip
Linux (Fedora/RHEL): sudo dnf install python3 python3-pip

For more detailed environment setup help: for Python-related issues, load the python-runtime Skill; for everything else (containers / WSL / system tools), load the dev-environment-setup Skill.

Python Package Dependencies

The Python scripts in this Skill depend on defusedxml (XML parsing) and lxml (XSD validation). Both are pre-installed by the runtime — when you run the scripts through scripts/with-deps.py, the target runs under a runtime-bundled Python that has both, so no pip install and no network are needed (works offline, on every platform, without bash).

Fallback: if the runtime-bundled Python is unavailable (older client / build without it), the wrapper uses system python3. In that case defusedxml still resolves (pure-Python, bundled separately) but lxml may be missing — full XSD validation is then skipped gracefully (editing/packing still succeed). To enable full validation in that fallback case: pip install lxml.

Output Rule

When you create or modify a .docx file, you MUST tell the user the absolute path of the output file in your response. Example: "File saved to: /path/to/output.docx"

Overview

A .docx file is a ZIP archive containing XML files.

Quick Reference

Task	Approach
Read/analyze content	`pandoc` or unpack for raw XML
Create new document	Use `docx-js` - see Creating New Documents below
Edit existing document	Unpack → edit XML → repack - see Editing Existing Documents below

Converting .doc to .docx

Legacy .doc files must be converted before editing:

python "<skill-dir>/scripts/with-deps.py" office/soffice.py --headless --convert-to docx document.doc

Reading Content

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

# Raw XML access
python "<skill-dir>/scripts/with-deps.py" office/unpack.py document.docx unpacked/

Converting to Images

python "<skill-dir>/scripts/with-deps.py" office/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

Accepting Tracked Changes

To produce a clean document with all tracked changes accepted (requires LibreOffice):

python "<skill-dir>/scripts/with-deps.py" accept_changes.py input.docx output.docx

Creating New Documents

Generate .docx files with JavaScript, then validate. The docx (docx-js) library is pre-installed by the runtime — no npm install needed. You MUST run the generator through the Node preloader (scripts/preload-deps.cjs, see Run below) so require('docx') resolves the pre-installed library.

Authoring the script (CRITICAL — avoids quote/escaping failures)

You MUST create generate.js with the Write tool — write the file directly.

NEVER build the script through the shell: do NOT use bash heredocs (cat <<EOF), echo, or python3 -c "...open(...).write(...)" to emit JavaScript. Document content (especially manuals/reports) contains many " quotes, apostrophes, and CJK punctuation; routing it through the shell causes three layers of quoting to collide (shell quotes × JS string quotes × heredoc delimiter), which corrupts the script and triggers endless retries and command timeouts.

Use the Write tool → quotes in content are written verbatim, no shell escaping at all.
For long documents, keep content as plain JS strings/arrays inside the file; split into many Paragraphs. If a single document is very large, write it in multiple smaller Write/Edit steps rather than one giant command.

Setup

Write the generator to a file (e.g. generate.js) using the Write tool:

const fs = require('fs');
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* content */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Run

Run it with the cross-platform Node preloader (it injects NODE_PATH for the pre-installed docx; pure Node, works on macOS / Linux / Windows, no bash needed):

node -r "<skill-dir>/scripts/preload-deps.cjs" generate.js

Use CommonJS require('docx'), NOT ESM import — the pre-installed library is resolved via NODE_PATH, which Node ignores for ESM. Do not put a "type": "module" package.json in the working directory either, as it would force .js files to be treated as ESM and break require. If require('docx') still fails (e.g. the runtime pre-install is unavailable on an older client), fall back to npm install -g docx and re-run.

Validation

After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.

python "<skill-dir>/scripts/with-deps.py" office/validate.py doc.docx

Page Size

// CRITICAL: docx-js defaults to A4, not US Letter
// Always set page size explicitly for consistent results
sections: [{
  properties: {
    page: {
      size: {
        width: 12240,   // 8.5 inches in DXA
        height: 15840   // 11 inches in DXA
      },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
    }
  },
  children: [/* content */]
}]

Common page sizes (DXA units, 1440 DXA = 1 inch):

Paper	Width	Height	Content Width (1" margins)
US Letter	12,240	15,840	9,360
A4 (default)	11,906	16,838	9,026

Landscape orientation: docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:

size: {
  width: 12240,   // Pass SHORT edge as width
  height: 15840,  // Pass LONG edge as height
  orientation: PageOrientation.LANDSCAPE  // docx-js swaps them in the XML
},
// Content width = 15840 - left margin - right margin (uses the long edge)

Styles (Override Built-in Headings)

Use Arial as the default font (universally supported). Keep titles black for readability.

const doc = new Document({
  styles: {
    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
    paragraphStyles: [
      // IMPORTANT: Use exact IDs to override built-in styles
      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 32, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 28, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }),
    ]
  }]
});

Lists (NEVER use unicode bullets)

// ❌ WRONG - never manually insert bullet characters
new Paragraph({ children: [new TextRun("• Item")] })  // BAD
new Paragraph({ children: [new TextRun("\u2022 Item")] })  // BAD

// ✅ CORRECT - use numbering config with LevelFormat.BULLET
const doc = new Document({
  numbering: {
    config: [
      { reference: "bullets",
        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
      { reference: "numbers",
        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ numbering: { reference: "bullets", level: 0 },
        children: [new TextRun("Bullet item")] }),
      new Paragraph({ numbering: { reference: "numbers", level: 0 },
        children: [new TextRun("Numbered item")] }),
    ]
  }]
});

// ⚠️ Each reference creates INDEPENDENT numbering
// Same reference = continues (1,2,3 then 4,5,6)
// Different reference = restarts (1,2,3 then 1,2,3)

Tables

CRITICAL: Tables need dual widths - set both columnWidths on the table AND width on each cell. Without both, tables render incorrectly on some platforms.

// CRITICAL: Always set table width for consistent rendering
// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };

new Table({
  width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
  columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
  rows: [
    new TableRow({
      children: [
        new TableCell({
          borders,
          width: { size: 4680, type: WidthType.DXA }, // Also set on each cell
          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLID
          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)
          children: [new Paragraph({ children: [new TextRun("Cell")] })]
        })
      ]
    })
  ]
})

Table width calculation:

Always use WidthType.DXA — WidthType.PERCENTAGE breaks in Google Docs.

// Table width = sum of columnWidths = content width
// US Letter with 1" margins: 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360]  // Must sum to table width

Width rules:

Always use WidthType.DXA — never WidthType.PERCENTAGE (incompatible with Google Docs)
Table width must equal the sum of columnWidths
Cell width must match corresponding columnWidth
Cell margins are internal padding - they reduce content area, not add to cell width
For full-width tables: use content width (page width minus left and right margins)

Images

// CRITICAL: type parameter is REQUIRED
new Paragraph({
  children: [new ImageRun({
    type: "png", // Required: png, jpg, jpeg, gif, bmp, svg
    data: fs.readFileSync("image.png"),
    transformation: { width: 200, height: 150 },
    altText: { title: "Title", description: "Desc", name: "Name" } // All three required
  })]
})

Page Breaks

// CRITICAL: PageBreak must be inside a Paragraph
new Paragraph({ children: [new PageBreak()] })

// Or use pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("New page")] })

// CRITICAL: Headings must use HeadingLevel ONLY - no custom styles
new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })

Headers/Footers

sections: [{
  properties: {
    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch
  },
  headers: {
    default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
    })] })
  },
  children: [/* content */]
}]

Critical Rules for docx-js

Set page size explicitly - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
Landscape: pass portrait dimensions - docx-js swaps width/height internally; pass short edge as width, long edge as height, and set orientation: PageOrientation.LANDSCAPE
Never use \n - use separate Paragraph elements
Never use unicode bullets - use LevelFormat.BULLET with numbering config
PageBreak must be in Paragraph - standalone creates invalid XML
ImageRun requires type - always specify png/jpg/etc
Always set table width with DXA - never use WidthType.PERCENTAGE (breaks in Google Docs)
Tables need dual widths - columnWidths array AND cell width, both must match
Table width = sum of columnWidths - for DXA, ensure they add up exactly
Always add cell margins - use margins: { top: 80, bottom: 80, left: 120, right: 120 } for readable padding
Use ShadingType.CLEAR - never SOLID for table shading
TOC requires HeadingLevel only - no custom styles on heading paragraphs
Override built-in styles - use exact IDs: "Heading1", "Heading2", etc.
Include outlineLevel - required for TOC (0 for H1, 1 for H2, etc.)

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

python "<skill-dir>/scripts/with-deps.py" office/unpack.py document.docx unpacked/

Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (“ etc.) so they survive editing. Use --merge-runs false to skip run merging.

Step 2: Edit XML

Edit files in unpacked/word/. See XML Reference below for patterns.

Use "Claude" as the author for tracked changes and comments, unless the user explicitly requests use of a different name.

Use the Edit tool directly for string replacement. Do not write Python scripts. Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.

CRITICAL: Use smart quotes for new content. When adding text with apostrophes or quotes, use XML entities to produce smart quotes:

<!-- Use these entities for professional typography -->
<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>

Entity	Character
`‘`	‘ (left single)
`’`	’ (right single / apostrophe)
`“`	“ (left double)
`”`	” (right double)

Adding comments: Use comment.py to handle boilerplate across multiple XML files (text must be pre-escaped XML):

python "<skill-dir>/scripts/with-deps.py" comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;"
python "<skill-dir>/scripts/with-deps.py" comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
python "<skill-dir>/scripts/with-deps.py" comment.py unpacked/ 0 "Text" --author "Custom Author"  # custom author name

Then add markers to document.xml (see Comments in XML Reference).

Step 3: Pack

python "<skill-dir>/scripts/with-deps.py" office/pack.py unpacked/ output.docx --original document.docx

Validates with auto-repair, condenses XML, and creates DOCX. Use --validate false to skip.

Auto-repair will fix:

durableId >= 0x7FFFFFFF (regenerates valid ID)
Missing xml:space="preserve" on <w:t> with whitespace

Auto-repair won't fix:

Malformed XML, invalid element nesting, missing relationships, schema violations

Common Pitfalls

Replace entire <w:r> elements: When adding tracked changes, replace the whole <w:r>...</w:r> block with <w:del>...<w:ins>... as siblings. Don't inject tracked change tags inside a run.
Preserve <w:rPr> formatting: Copy the original run's <w:rPr> block into your tracked change runs to maintain bold, font size, etc.

XML Reference

Schema Compliance

Element order in <w:pPr>: <w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>, <w:rPr> last
Whitespace: Add xml:space="preserve" to <w:t> with leading/trailing spaces
RSIDs: Must be 8-digit hex (e.g., 00AB1234)

Tracked Changes

Insertion:

<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t>inserted text</w:t></w:r>
</w:ins>

Deletion:

<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>

Inside <w:del>: Use <w:delText> instead of <w:t>, and <w:delInstrText> instead of <w:instrText>.

Minimal edits - only mark what changes:

<!-- Change "30 days" to "60 days" -->
<w:r><w:t>The term is </w:t></w:r>
<w:del w:id="1" w:author="Claude" w:date="...">
  <w:r><w:delText>30</w:delText></w:r>
</w:del>
<w:ins w:id="2" w:author="Claude" w:date="...">
  <w:r><w:t>60</w:t></w:r>
</w:ins>
<w:r><w:t> days.</w:t></w:r>

Deleting entire paragraphs/list items - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add <w:del/> inside <w:pPr><w:rPr>:

<w:p>
  <w:pPr>
    <w:numPr>...</w:numPr>  <!-- list numbering if present -->
    <w:rPr>
      <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
    </w:rPr>
  </w:pPr>
  <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
    <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
  </w:del>
</w:p>

Without the <w:del/> in <w:pPr><w:rPr>, accepting changes leaves an empty paragraph/list item.

Rejecting another author's insertion - nest deletion inside their insertion:

<w:ins w:author="Jane" w:id="5">
  <w:del w:author="Claude" w:id="10">
    <w:r><w:delText>their inserted text</w:delText></w:r>
  </w:del>
</w:ins>

Restoring another author's deletion - add insertion after (don't modify their deletion):

<w:del w:author="Jane" w:id="5">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>
<w:ins w:author="Claude" w:id="10">
  <w:r><w:t>deleted text</w:t></w:r>
</w:ins>

Comments

After running comment.py (see Step 2), add markers to document.xml. For replies, use --parent flag and nest markers inside the parent's.

CRITICAL: <w:commentRangeStart> and <w:commentRangeEnd> are siblings of <w:r>, never inside <w:r>.

<!-- Comment markers are direct children of w:p, never inside w:r -->
<w:commentRangeStart w:id="0"/>
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted</w:delText></w:r>
</w:del>
<w:r><w:t> more text</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>

<!-- Comment 0 with reply 1 nested inside -->
<w:commentRangeStart w:id="0"/>
  <w:commentRangeStart w:id="1"/>
  <w:r><w:t>text</w:t></w:r>
  <w:commentRangeEnd w:id="1"/>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>

Images

Add image file to word/media/
Add relationship to word/_rels/document.xml.rels:

<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>

Add content type to [Content_Types].xml:

<Default Extension="png" ContentType="image/png"/>

Reference in document.xml:

<w:drawing>
  <wp:inline>
    <wp:extent cx="914400" cy="914400"/>  <!-- EMUs: 914400 = 1 inch -->
    <a:graphic>
      <a:graphicData uri=".../picture">
        <pic:pic>
          <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
        </pic:pic>
      </a:graphicData>
    </a:graphic>
  </wp:inline>
</w:drawing>

Dependencies

Runtime-preinstalled (no install, offline, cross-platform — the launchers below need no bash):

docx (docx-js): new documents — pre-installed by the runtime (runtime-deps/node_modules); run generators via node -r "<skill-dir>/scripts/preload-deps.cjs" generate.js. No npm install needed.
defusedxml + lxml: XML parsing & full XSD validation — pre-installed by the runtime in a bundled Python (runtime-deps/python-runtime); run scripts via python "<skill-dir>/scripts/with-deps.py" <script> ... to use them offline. Falls back to the system python3 and skips XSD validation gracefully if the bundled Python / lxml is unavailable.

External system tools (only needed for reading/conversion, not for generation; install per OS if used):

pandoc: Text extraction. macOS brew install pandoc · Windows winget install --id JohnMacFarlane.Pandoc · Linux sudo apt install pandoc
LibreOffice (soffice): .doc→.docx and PDF conversion, accept-changes. macOS brew install --cask libreoffice · Windows winget install --id TheDocumentFoundation.LibreOffice (ensure soffice is on PATH) · Linux sudo apt install libreoffice. The Linux-sandbox AF_UNIX shim in scripts/office/soffice.py is auto-skipped on macOS/Windows.
Poppler (pdftoppm, page→image): macOS brew install poppler · Windows winget install --id oschwartz10612.Poppler or choco install poppler · Linux sudo apt install poppler-utils

28 KiB Raw Blame History Unescape Escape

docx Skill

L0: One-line Summary

L1: Overview and Use Cases

Capability

Use Cases

L2: Detailed Specification

Script Path Rule (mandatory)

Prerequisites

Python 3 (required)

Python Package Dependencies

Output Rule

Overview

Quick Reference

Converting .doc to .docx

Reading Content

Converting to Images

Accepting Tracked Changes

Creating New Documents

Authoring the script (CRITICAL — avoids quote/escaping failures)

Setup

Run

Validation

Page Size

Styles (Override Built-in Headings)

Lists (NEVER use unicode bullets)

Tables

Images

Page Breaks

Table of Contents

Headers/Footers

Critical Rules for docx-js

Editing Existing Documents

Step 1: Unpack

Step 2: Edit XML

Step 3: Pack

Common Pitfalls

XML Reference

Schema Compliance

Tracked Changes

Comments

Images

Dependencies

28 KiB

Raw Blame History