Office Transform 是一个文档处理技能，用于把 Office 或 PDF 文档中的结构化选区提取为新文件，或基于原文件派生出一个经过编辑的副本。
用途 需要从文档中拿出一段内容、转换一个片段，或生成一份编辑后的副本时使用本技能。如果只是要读取文档做总结或回答问题，应该改用 Markdown 转换工具（该方式有信息损失，但面向阅读）。
两项固定约束
- 源文件只读：每个结果都写入新文件，两个脚本都拒绝写入源路径或覆盖已有文件。
- 锚点结构化：选区使用文档自身坐标，例如工作表加 A1 范围、正文级段落序号、从 1 开始的页码、幻灯片形状 ID，而不是屏幕或 DOM 位置。
选区引用与校验 聊天界面可能给出选区引用块，其中包含 path、anchor、excerpt 和 fileStamp（size、mtimeMs）。anchor 对象可直接作为脚本的 --anchor 参数。
- 新鲜度检查：fileStamp.mtimeMs 是向下取整到毫秒的 Unix 时间戳。不要用 stat 默认的整秒输出比较，需读取整毫秒；大小不同，或 mtime 相差超过 2 毫秒，就视为文件已变更，应提示用户重新选择，不得静默重新锚定。
- 锚点检查：补丁编辑前，先提取锚定区域并与 excerpt 按同一规则归一化（NFC、连续空白折叠为一个空格、去首尾空白）后比较包含关系：excerpt 出现在提取文本中，或提取文本末尾正是 excerpt 开头。两者都不成立时停止并告知用户，不得在错位锚点上编辑。xlsx 需按单元格值比较，且数字格式差异（显示值与存储值）和日期时间呈现差异不算锚点移动；带 charRange 的 docx 需另行提取整段。
锚点格式
- xlsx：{format, sheet, range}，range 可为单个单元格。
- docx：{format, paragraph, paraId?, charRange?}，ordinal 只计正文级段落，不含表格。
- pdf：{format, page, charRange?}，charRange 作用于提取文本。
- pptx：{format, slide, nodeId?, paragraph?, tableCell?}，slide 从 1 开始，nodeId 为 OOXML 形状 ID，省略则指整张幻灯片。
操作一：提取 把锚定区域抽取到新文件，脚本为 scripts/office_extract.py，依赖通过 uv run --with 按格式提供：xlsx 用 openpyxl（输出 xlsx、csv、md），docx 用固定版本 python-docx（输出 docx、txt、md），pdf 用 pypdf（输出 pdf 页面副本、txt、md），pptx 用 python-pptx（输出 txt、md）。输出格式由 --out 扩展名推断。--file 与 --out 必须为绝对路径，路径需用单引号包裹。xlsx 提取读取计算值，公式单元格返回上次保存的结果；docx 转 docx 只保留文本不带 run 样式。
操作二：补丁复制 脚本为 scripts/office_patch_copy.py，仅用标准库。它按字节复制 OOXML 包中的每个部件，只重新序列化被编辑触及的部分，因此样式、图表、图片和宏得以保留。
- xlsx 编辑：以 cells 指定单元格写入数字、字符串或布尔值；写入会替换已有公式，且不重算，但会设置 fullCalcOnLoad 让 Excel 打开时重算，并删除 calcChain.xml 及相关引用，避免文件被报告为损坏。共享公式、数组公式、数据表公式组中的单元格以及超出网格范围的坐标会被拒绝。
- docx 编辑：以 replacements 指定段落、新文本、可选 paraId 与 expectText。段落保留段落样式和首个 run 的字符样式，其余 run 级样式被压平；text 必须是完整段落文本，charRange 不会收窄替换范围。段落中含书签、批注锚点、域、图片、嵌入对象、脚注尾注引用、超链接、修订、内容控件、公式等结构时会被拒绝；分页或分栏符也会被拒绝。expectText 为强建议的硬性校验，取自不带 charRange 的整段提取。
- 写入 XML 的文本不得含除制表、换行、回车以外的控制字符；docx 段落还拒绝制表、换行、回车，因为单个 w:t 无法承载。
操作三：生成新文档 从零或基于刚提取的数据创建新演示文稿、工作簿或文档时没有固定脚本，可针对对应库编写简短 Python 程序并通过 uv run --with 运行。仍须遵守两项约束：用 "xb" 打开尚不存在的目标路径（各库 save() 会覆盖），并在报告成功前重新打开验证。
操作四：docx 与 pptx 的库编辑 补丁被拒绝的 docx 段落可用 python-docx 逐 run 编辑，绝不能赋值 paragraph.text；写之前需阅读 references/docx-edit.md。pptx 编辑不走补丁脚本，使用 python-pptx 逐 run 编辑，不得在段落或形状级赋值 .text，目标文件以 "xb" 打开；写之前需阅读 references/pptx-edit.md。
输出约定 派生文件按“源文件名加操作后缀”命名，例如 report.xlsx 生成 report-updated.xlsx 或 report-q1-range.csv。输出写入会话工作区或用户指定位置；脚本成功时打印写出路径，需转告用户。输出先暂存再重命名，失败不会留下残留，可在同一路径重试。
成功前验证 必须用对应读取库重新打开派生文件检查结果。xlsx 用 data_only 读取缓存值，因此读取刚写入单元格的公式仍返回旧结果，应检查写入的单元格并告知用户依赖总计会在 Excel 打开时重算。若验证失败，应如实说明并展示错误，不得把未验证文件当作成功结果。
限制
- pptx 编辑走 python-pptx，不支持把幻灯片复制进新演示文稿（python-pptx 无法克隆幻灯片），被问到时应说明。
- 补丁后的 xlsx 字符串单元格成为内联字符串，文本按 ST_Xstring 写入：字面 xHHHH 会转义为 x005F_xHHHH，回车存为 x000D；openpyxl 不解码，验证读到的是转义形式，属读取器行为而非失败。
- 被编辑的 XML 部件可能丢失无意义的序列化细节（属性引号、空元素形式），命名空间前缀与未触及内容保留。
- 补丁后的 docx 段落保留字符，但软连字符会被丢弃、不断行连字符回退为普通 -，丢失的只是换行机会；w:sym 会被直接拒绝。
- xlsx 提取拒绝超过 1,000,000 个单元格的区域；两个脚本都拒绝超过一定数量部件（资料在此处截断，具体上限暂未提供）的包。
适用场景 从表格中取出指定范围导出为 csv 或 markdown、把 PDF 某页文字转为文本、在不破坏格式的前提下修改工作簿单元格、按段落替换 docx 文本、基于提取数据生成新文件等。