docx

name docx description 当用户需要创建、读取、编辑或处理 Word 文档（.docx）时，使用此技能。触发场景包括提到“Word 文档”、“.docx”，或要求生成带目录、标题、页码、信头等格式的专业文档；也包括提取或重组 .docx 内容、插入或替换图片、在 Word 文件中查找替换、处理修订或批注，以及将内容整理为正式 Word 文档。如果用户要求生成“报告”“备忘录”“信函”“模板”等 Word / .docx 交付物，也应使用此技能。不要用于 PDF、电子表格、Google Docs，或与文档生成无关的一般编程任务。 license Proprietary. LICENSE.txt has complete terms metadata {"builtin_skill_version":"1.1"} 重要: 所有 scripts/ 路径均相对于本技能目录。 运行方式: cd {this_skill_dir} && python scripts/... 或使用 execute_shell_command 的 cwd 参数。 DOCX 创建、编辑与分析 前置依赖 docx ( npm install -g docx ): 新文档创建 LibreOffice ( soffice ): .doc -> .docx 转换、修订接受和 PDF 导出 pandoc : 文本提取 pdftoppm (poppler-utils): 文档转图片工作流 如果 pdftoppm 不可用，Python 备用路径可能使用 pdf2image 。 在 Windows 上，依赖项必须已安装并在 PATH 中可用；如缺失，请报告依赖问题并停止（不要反复重试）。 概述 .docx 文件是包含 XML 文件的 ZIP 压缩包。 快速参考 任务 方法 读取/分析内容 pandoc 或解压获取原始 XML 创建新文档 使用 docx-js - 参见下方"创建新文档" 编辑现有文档 解压 → 编辑 XML → 重新打包 - 参见下方"编辑现有文档" 将 .doc 转换为 .docx 旧版 .doc 文件必须先转换才能编辑: python scripts/office/soffice.py --headless --convert-to docx document.doc 读取内容 # 提取包含修订的文本 pandoc --track-changes=all document.docx -o output.md # 访问原始 XML python scripts/office/unpack.py document.docx unpacked/ 转换为图片 python scripts/office/soffice.py --headless --convert-to pdf document.docx pdftoppm -jpeg -r 150 document.pdf page 接受修订 生成接受所有修订后的干净文档（需要 LibreOffice）: python scripts/accept_changes.py input.docx output.docx 创建新文档 使用 JavaScript 生成 .docx 文件，然后进行验证。安装: npm install -g docx 初始设置 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)); 验证 创建文件后进行验证。如果验证失败，解压、修复 XML 并重新打包。 python scripts/office/validate.py doc.docx 页面尺寸 // 关键: docx-js 默认为 A4，而非 US Letter // 始终显式设置页面尺寸以获得一致的结果 sections : [{ properties : { page : { size : { width : 12240 , // 8.5 英寸（DXA 单位） height : 15840 // 11 英寸（DXA 单位） }, margin : { top : 1440 , right : 1440 , bottom : 1440 , left : 1440 } // 1 英寸边距 } }, children : [ /* content */ ] }] 常见页面尺寸（DXA 单位，1440 DXA = 1 英寸）: 纸张 宽度 高度 内容宽度（1 英寸边距） US Letter 12,240 15,840 9,360 A4（默认） 11,906 16,838 9,026 横向方向: docx-js 在内部会交换宽度/高度，因此传入纵向尺寸并让其处理交换: size : { width : 12240 , // 将短边作为 width 传入 height : 15840 , // 将长边作为 height 传入 orientation : PageOrientation . LANDSCAPE // docx-js 会在 XML 中交换它们 }, // 内容宽度 = 15840 - 左边距 - 右边距（使用长边） 样式（覆盖内置标题） 使用 Arial 作为默认字体（通用支持）。标题保持黑色以确保可读性。 const doc = new Document ({ styles : { default : { document : { run : { font : "Arial" , size : 24 } } }, // 默认 12pt paragraphStyles : [ // 重要: 使用精确的 ID 来覆盖内置样式 { 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 是目录所必需的 { 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" )] }), ] }] }); 列表（绝对不要使用 Unicode 符号） // ❌ 错误 - 绝不手动插入项目符号字符 new Paragraph ({ children : [ new TextRun ( "• Item" )] }) // 错误 new Paragraph ({ children : [ new TextRun ( "\u2022 Item" )] }) // 错误 // ✅ 正确 - 使用 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" )] }), ] }] }); // ⚠️ 每个 reference 创建独立的编号序列 // 相同 reference = 继续编号（1,2,3 然后 4,5,6） // 不同 reference = 重新开始（1,2,3 然后 1,2,3） 表格 关键: 表格需要双重宽度设置 - 必须同时在表格上设置 columnWidths 和在每个单元格上设置 width 。缺少任一设置，表格在某些平台上会渲染不正确。 // 关键: 始终设置表格宽度以确保一致的渲染效果 // 关键: 使用 ShadingType.CLEAR（而非 SOLID）以防止黑色背景 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 }, // 始终使用 DXA（百分比在 Google Docs 中会出问题） columnWidths : [ 4680 , 4680 ], // 必须加起来等于表格宽度（DXA: 1440 = 1 英寸） rows : [ new TableRow ({ children : [ new TableCell ({ borders, width : { size : 4680 , type : WidthType . DXA }, // 同样需要在每个单元格上设置 shading : { fill : "D5E8F0" , type : ShadingType . CLEAR }, // 用 CLEAR 而非 SOLID margins : { top : 80 , bottom : 80 , left : 120 , right : 120 }, // 单元格内边距（内部的，不会增加宽度） children : [ new Paragraph ({ children : [ new TextRun ( "Cell" )] })] }) ] }) ] }) 表格宽度计算: 始终使用 WidthType.DXA -- WidthType.PERCENTAGE 在 Google Docs 中会出问题。 // 表格宽度 = columnWidths 之和 = 内容宽度 // US Letter 配合 1 英寸边距: 12240 - 2880 = 9360 DXA width : { size : 9360 , type : WidthType . DXA }, columnWidths : [ 7000 , 2360 ] // 必须加起来等于表格宽度 宽度规则: 始终使用 WidthType.DXA -- 绝不使用 WidthType.PERCENTAGE （与 Google Docs 不兼容） 表格宽度必须等于 columnWidths 之和 单元格 width 必须与对应的 columnWidth 匹配 单元格 margins 是内部边距 - 它们减少内容区域，而不是增加单元格宽度 全宽表格: 使用内容宽度（页面宽度减去左右边距） 图片 // 关键: type 参数是必需的 new Paragraph ({ children : [ new ImageRun ({ type : "png" , // 必需: png, jpg, jpeg, gif, bmp, svg data : fs. readFileSync ( "image.png" ), transformation : { width : 200 , height : 150 }, altText : { title : "Title" , description : "Desc" , name : "Name" } // 三个都是必需的 })] }) 分页符 // 关键: PageBreak 必须在 Paragraph 内部 new Paragraph ({ children : [ new PageBreak ()] }) // 或者使用 pageBreakBefore new Paragraph ({ pageBreakBefore : true , children : [ new TextRun ( "New page" )] }) 目录 // 关键: 标题必须仅使用 HeadingLevel - 不使用自定义样式 new TableOfContents ( "Table of Contents" , { hyperlink : true , headingStyleRange : "1-3" }) 页眉/页脚 sections : [{ properties : { page : { margin : { top : 1440 , right : 1440 , bottom : 1440 , left : 1440 } } // 1440 = 1 英寸 }, 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 */ ] }] docx-js 关键规则 显式设置页面尺寸 - docx-js 默认为 A4；美国文档使用 US Letter（12240 x 15840 DXA） 横向: 传入纵向尺寸 - docx-js 在内部交换宽度/高度；将短边作为 width ，长边作为 height ，并设置 orientation: PageOrientation.LANDSCAPE 绝不使用 \n - 使用独立的 Paragraph 元素 绝不使用 Unicode 符号 - 使用 LevelFormat.BULLET 配合编号配置 PageBreak 必须在 Paragraph 内 - 独立使用会创建无效的 XML ImageRun 需要 type - 始终指定 png/jpg 等 始终使用 DXA 设置表格 width - 绝不使用 WidthType.PERCENTAGE （在 Google Docs 中会出问题） 表格需要双重宽度 - columnWidths 数组和单元格 width ，两者必须匹配 表格宽度 = columnWidths 之和 - 对于 DXA，确保它们精确相加 始终添加单元格边距 - 使用 margins: { top: 80, bottom: 80, left: 120, right: 120 } 获得可读的内边距 使用 ShadingType.CLEAR - 表格底纹绝不使用 SOLID 目录需要仅使用 HeadingLevel - 标题段落不使用自定义样式 覆盖内置样式 - 使用精确的 ID: "Heading1"、"Heading2" 等 包含 outlineLevel - 目录所必需（H1 为 0，H2 为 1，依此类推） 编辑现有文档 按顺序执行以下 3 个步骤。 第 1 步: 解压 python scripts/office/unpack.py document.docx unpacked/ 提取 XML，进行格式化打印，合并相邻的 run，并将智能引号转换为 XML 实体（ &#x201C; 等）以便在编辑过程中保留。使用 --merge-runs false 跳过 run 合并。 第 2 步: 编辑 XML 编辑 unpacked/word/ 中的文件。参见下方的 XML 参考获取相关模式。 使用 "Claude" 作为作者 来添加修订和批注，除非用户明确要求使用其他名称。 **直接使用 Edit 工具进行字符串替换。不要编写 Python 脚本。**脚本会引入不必要的复杂性。Edit 工具能准确显示被替换的内容。 **关键: 新内容使用智能引号。**添加包含撇号或引号的文本时，使用 XML 实体生成智能引号: <!-- 使用这些实体生成专业的排版效果 --> < w:t > Here &#x2019; s a quote: &#x201C; Hello &#x201D; </ w:t > 实体 字符 &#x2018; ' (左单引号) &#x2019; ' (右单引号 / 撇号) &#x201C; " (左双引号) &#x201D; " (右双引号) 添加批注: 使用 comment.py 处理跨多个 XML 文件的样板代码（文本必须是预转义的 XML）: python scripts/comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;" python scripts/comment.py unpacked/ 1 "Reply text" --parent 0 # 回复批注 0 python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author" # 自定义作者名 然后在 document.xml 中添加标记（参见 XML 参考中的批注部分）。 第 3 步: 打包 python scripts/office/pack.py unpacked/ output.docx --original document.docx 进行验证并自动修复，压缩 XML，然后创建 DOCX。使用 --validate false 跳过验证。 自动修复可以修复的问题: durableId >= 0x7FFFFFFF（重新生成有效 ID） <w:t> 上缺少的 xml:space="preserve" （当有空白字符时） 自动修复无法修复的问题: 格式错误的 XML、无效的元素嵌套、缺失的关系、架构违规 常见陷阱