AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载Ekko Agent 是 Hermes Studio 中负责执行编码与文档任务的本地优先 Agent 运行时其内置的 docx Skill 提供了一套以 Python 脚本python-docx lxml为核心的 .docx 处理工具箱覆盖文档创建、结构化读取、精准编辑、模板填充、批注、修订跟踪与结构校验。本文基于仓库中 SKILL.md 的完整规范结合 scripts 目录 下全部 8 个脚本的实现与 test_docx_skill.py 的端到端测试带你掌握在 Agent 工作流中安全、无损地操作 Word 文档的完整方案——包括如何保留原文档的格式意图、如何处理修订与批注、以及如何用 LibreOffice 做像素级视觉回归。Skill 定位与核心设计原则docx Skill 是 Ekko Agent 的技能体系Skills之一。Agent 侧通过skill_view工具加载技能说明通过terminal_exec工具以python3为命令、参数数组方式调用打包好的脚本。其定位非常聚焦创建Create、检查Inspect、编辑Edit、校验Validate以及视觉验证Visually verifyMicrosoft Word .docx 文档覆盖模板、批注、修订跟踪、表格、图片、页眉页脚等完整特性面。该 Skill 的运行哲学写在 SKILL.md 开头保留用户的内容与格式意图不擅自改写原文语义、不破坏排版做满足请求的最小改动能改一个 run 就不重排整段默认输出新文件仅当用户明确要求原地编辑时才替换输入文件改前必查修改任何文档前先用docx_read.py检查并保留一份可恢复的原始副本。事实依据以上原则为 SKILL.md 中 Start here 一节的明文约定脚本行为与测试均围绕此展开。环境准备依赖检查与安装Skill 的核心依赖只有两个 Python 包SKILL.md 明确给出了安装命令python3 -m pip install python-docx lxmlpython-docx提供Document、add_paragraph、add_table、样式与 section 管理等高层 API是所有脚本的文档操作基础lxml用于直接操作 WordprocessingML 的 XML 层批注的拆分 run、修订的w:ins/w:del解析、校验器的关系解析都依赖它。SKILL.md 特别强调不要静默安装依赖。运行前先检查依赖是否可用如果某个缺失依赖阻塞了任务必须向用户明确说明。这是 Agent 可解释性的一部分——任何环境副作用都应透明可见。工具调用方式与 baseDirectory调用 Skill 的第一步是skill_view它返回技能内容的同时会携带baseDirectory字段对应 skills.ts 中skill_view的返回结构。所有打包脚本都位于baseDirectory/scripts下调用示例如下# 读取并结构化检查文档 python3 baseDirectory/scripts/docx_read.py input.docx --json # 从 JSON 规格创建文档 python3 baseDirectory/scripts/docx_create.py spec.json -o output.docx # 按编辑计划修改文档 python3 baseDirectory/scripts/docx_edit.py input.docx edits.json -o output.docx # 校验生成结果 python3 baseDirectory/scripts/docx_validate.py output.docx当某个脚本的具体参数不确定时规则是先用--help查看其 argparse 帮助而不是猜测参数。Helper 脚本矩阵七个入口 一个公共库Skill 目录结构packages/ekko-agent/skills/docx下共有 8 个 Python 文件脚本职责关键 CLIdocx_read.py提取段落、标题、表格、链接、批注、页眉页脚、元数据并探测修订--text/--structure/--styles/--images DIR/--revisionsdocx_create.py从结构化 JSON 规格生成文档docx_create.py spec.json output.docxdocx_edit.py精确执行文本、段落、表格、图片、页眉页脚编辑8 个子命令replace/set-cell/insert/delete/style/normalize/toc/page-numbersdocx_template.py检查占位符并填充模板docx_template.py template.docx values.json output.docx [--strict]docx_comments.py添加、列出、删除批注list/add/deletedocx_revisions.py检查、接受、拒绝修订list/accept-all/reject-all/accept --id N/reject --id Ndocx_validate.py校验包结构并报告问题docx_validate.py file.docxdocx_common.py公共工具全文档段落遍历 保格式文本替换被其他脚本 import无独立 CLIdocx_read.py五种检查视角阅读脚本源码可见它提供五个互斥的检查模式docx_read.py--text输出 JSON含body正文段落数组、tables二维行列表、headers、footers正文是已接受视图——python-docx 天然忽略w:del中的删除文本、显示w:ins中的插入文本--structure输出大纲Heading 样式段落及其级别、段落数、表格数、每张表的行列数、节数--styles实际被使用到的样式名列表正文、run、表格、单元格逐层收集后去重排序--images DIR解压word/media/下的所有嵌入图片到指定目录--revisions直接扫描原始 XML 部件检测插入w:ins、删除w:del、格式变更w:rPrChange与批注部件word/comments是否存在输出has_tracked_changes布尔值。docx_create.pyJSON 规格驱动的文档生成docx_create.py 接收一个 JSON 规格对象模块 docstring 给出了完整格式。将其完整继承并整理如下{ page: { width_mm: 210, height_mm: 297, margins_mm: {top: 25, bottom: 25, left: 20, right: 20} }, header: text shown in page header, footer: text shown in page footer, styles: [ {name: MyStyle, base: Normal, font: Arial, size_pt: 12, bold: true, color: 1F4E79} ], blocks: [ {type: heading, text: Title, level: 1}, {type: paragraph, style: MyStyle, runs: [ {text: plain }, {text: bold, bold: true}, {text: italic, italic: true}, {text: under, underline: true} ]}, {type: paragraph, text: shortcut: single plain run}, {type: bullet_list, items: [a, b]}, {type: numbered_list, items: [one, two]}, {type: table, header: [Col1, Col2], rows: [[1, 2]], style: Light Grid Accent 1, header_bold: true}, {type: image, path: pic.png, width_mm: 60}, {type: page_break}, {type: toc} ] }规格要点与源码add_block/apply_page/add_styles逐一对应page控制节尺寸与页边距全部以毫米为单位通过Mm()设置到 section 的page_width/page_height及各*_marginstyles定义自定义段落样式base指定继承的基准样式font/size_pt/bold/italic/color十六进制 RGB 字符串依次映射到font.name/Pt(size)/font.bold等属性blocks支持 9 种块类型heading1–9 级、paragraph可带多 run 的富文本省略runs时按单 run 处理、bullet_list、numbered_list分别映射List Bullet/List Number内置样式、table表头加粗默认开启可通过header_bold: false关闭、image可选width_mm控制宽度、page_break、toc顶层可选footer_page_numbers: true在页脚追加 Page X of Y由PAGE/NUMPAGES域字段实现。一个重要的事实边界TOC 与页码域的结果不是 python-docx 计算的而是 Word/LibreOffice 打开文件时才刷新未刷新前显示占位文本Table of contents - open in Word/LibreOffice and update fields to populate.。docx_edit.py八个编辑子命令docx_edit.py 覆盖文档的定向修改docx_edit.py replace in.docx --find old --replace new -o out.docx docx_edit.py set-cell in.docx --table 0 --row 1 --col 2 --text 42 docx_edit.py insert in.docx --index 3 --text New para --style Normal docx_edit.py delete in.docx --index 3 docx_edit.py style in.docx --index 0 --style Heading 1 docx_edit.py normalize in.docx -o out.docx docx_edit.py toc in.docx --index 1 -o out.docx docx_edit.py page-numbers in.docx -o out.docxreplace全局查找替换。默认覆盖正文、表格含嵌套表、页眉页脚传--body-only则跳过页眉页脚。替换逻辑实现在 docx_common.py 的replace_in_paragraph中采用两轮策略——第一轮处理完整落在单个 run 内的匹配格式完全保留第二轮处理跨 run 匹配合并被命中的 runs替换文本继承起始 run 的格式set-cell按--table/--row/--col索引定位表格单元格并整格替换文本insert/delete按正文段落索引插入可指定--style或删除段落style给指定索引的正文段落套用命名样式normalize合并格式相同的相邻 run_run_format_key用序列化的w:rPr作为格式指纹仅合并纯文本 run跳过含 break/tab/drawing 的 run有助于后续查找替换时减少跨 run 匹配toc在指定正文索引前插入 TOC 域TOC \o 1-3 \h \z \upage-numbers在页脚追加 PAGE/NUMPAGES 域。docx_template.py模板占位符填充模板填充采用{{token}}双花括号约定正则\{\{\s*([A-Za-z0-9_.-])\s*\}\}docx_template.py template.docx values.json output.docx docx_template.py template.docx values.json output.docx --strictvalues.json形如{name: Ada, date: 2026-01-01}。实现要点占位符在正文段落、表格含嵌套表、页眉页脚中全量替换先对{{ name }}这类空白变体归一化再填充run 格式保留、跨 run 拆分占位符可处理复用replace_in_paragraph。--strict模式下若仍有未填充 token则退出码为 1 并输出unfilled_tokens列表——适合对合同、证书等一个占位符都不能漏的场景做硬校验。docx_comments.py批注三操作docx_comments.py list report.docx docx_comments.py add report.docx --target Q3 revenue --text Needs a source --author Reviewer -o out.docx docx_comments.py delete report.docx --id 0 -o out.docxlist输出每条批注的id、author、initials、date、text以及anchored_text通过遍历各部件根节点、按文档顺序收集commentRangeStart/commentRangeEnd之间的w:t文本重建add先把目标文本隔离为完整 run匹配跨 run 时在边界处拆分 run_split_run会深拷贝w:rPr保持格式然后优先走 python-docx 1.2 的原生add_commentAPI旧版本或--xml时回退为手动构建word/comments.xml、注册 part 与关系、插入 range 标记和 reference rundelete从 XML 层删除w:comment元素及该 id 的所有三类标记commentRangeStart/commentRangeEnd/commentReference锚定正文文本不受影响。docx_revisions.py修订跟踪解析与裁决docx_revisions.py list report.docx docx_revisions.py accept-all report.docx -o accepted.docx docx_revisions.py reject report.docx --id 3 -o out.docx脚本直接操作 WordprocessingML 的w:ins/w:del包装元素语义如下docx_revisions.py接受w:ins→ 解包_unwrap把子 run 上移、丢弃包装器拒绝w:ins→ 连包装器带内容整体删除接受w:del→ 删除包装器及其内容拒绝w:del→ 把每个w:delText重命名为w:t再解包文本复活。修订可出现在正文、表格单元格含嵌套表、页眉页脚、文本框等任何块级内容处脚本通过iter_part_rootsdocx_common.py 中收集 body 根加每个页眉页脚部件根配合root.iter(w:ins, w:del)深度遍历。注意边界段落标记修订w:pPr内、表格行修订w:trPr/w:ins、格式变更记录w:rPrChange/w:pPrChange与移动w:moveFrom/w:moveTo会被docx_read.py --revisions检测到但不做裁决遇到后应按 revisions-and-comments.md 的建议用 Word 本身处理。docx_validate.py结构健康检查docx_validate.py 是每次生成/编辑后的强制收尾步骤。需要明确它是健康检查health-check而非完整 XSD 模式校验检查项包括文件可读且是合法 ziptestzip()通过 CRC 校验必需部件存在[Content_Types].xml、word/document.xml每个.rels关系文件中的内部关系都能解析到包内实际存在的部件悬空图片/超链接关系报 error外部 TargetMode 跳过document.xml中的r:id/r:embed/r:link引用都有对应关系嵌入图片非空且魔数可识别PNG/JPEG/GIF/BMP/TIFF/EMF/WMF/SVG无需 PIL文档引用的段落/run/表格样式 id 都存在于styles.xmlpython-docx 能正常打开该文件。输出{ok: bool, issues: [{severity: error|warning, ...}]}存在任意 error 级问题时退出码为 1warning 不阻塞。六步标准工作流SKILL.md 给出的推荐流程完整展开如下检查源文档用docx_read.py检查源文档精确定位需要保留或修改的段落记下段落索引、表格行列、样式名构建规格/编辑计划对名称、数字、日期、引用和法律措辞不得近似处理——必须以原文为准逐字保留生成或编辑新 .docx优先输出到新文件避免破坏原始文档运行校验docx_validate.py修复所有 error 级问题视觉验证布局敏感时若 LibreOffice 可用将结果转 PDF用仓库内置的 pdf Skill 渲染相关 PDF 页面再用view_image检查图片重点核对文字裁切、分页符、表格、页眉页脚、图片位置汇报结果返回最终文件的绝对路径并总结实质性改动。如果 LibreOffice 不可用仍必须完成结构校验并明确告知用户视觉渲染不可用。视觉验证LibreOffice PDF 渲染链路第 5 步是 docx Skill 区别于纯文本处理能力的关键一环。Word 的排版结果是所见即所得的仅凭 JSON 文本检查无法发现表格溢出、页脚重叠、图片裁切等问题。因此 SKILL.md 规定了这条链路docx_validate.py结构健康 → LibreOffice 将 .docx 转 PDFheadless 转换 → 内置 pdf Skill 渲染相关 PDF 页为图片 → view_image 逐页目检裁切 / 分页 / 表格 / 页眉页脚 / 图片位置需要说明这条链路依赖 LibreOffice 在运行环境中可用属于可选增强而非强制步骤——不可用时以结构校验为准并如实声明。安全规则什么不能做SKILL.md 的 Safety 一节是使用边界必须严格遵守绝不丢弃批注或修订除非用户明确要求该操作接受全部/拒绝全部修订、删除全部批注属于破坏性变换范围不明确时必须先与用户确认不执行宏或嵌入对象脚本层也只做文本与结构操作不触碰 VBA 等可执行内容不将敏感文档文本复制到外部服务除非用户明确要求需要该流程的工作流。源码佐证测试如何验证整个闭环test_docx_skill.py 以子进程方式运行各脚本验证 argparse CLI 可用再用 python-docx 直接打开输出做二次断言且全程零网络、fixture 现场生成。它覆盖了用覆盖全部 create 特性的 JSON 规格生成文档页面尺寸、页眉页脚、自定义样式、富文本 runs、项目符号/编号列表、表格、图片、footer_page_numbers--structure/--styles与docx_validate.py的返回结果符合预期模板填充中文与非 ASCII 文本NON_ASCII Фамилия — test的往返保持--strict未填充报错路径跨 run 文本替换与批注的添加/列出/删除、修订的接受/拒绝语义测试环境固定LC_ALLC与PYTHONIOENCODINGutf-8证明脚本不依赖 locale 默认编码即可处理非拉丁字符。测试目录即文档目录下的 tests/test_docx_skill.py需要深入验证行为时是首选参考。与 Agent 运行时的衔接docx Skill 的加载与执行遵循 Ekko Agent 的统一技能机制skills.ts 中skill_view要求精确技能名匹配返回内容含baseDirectory字段技能文件以 sha256 做版本指纹Agent 修改技能前必须先在同轮内skill_view读取防止对已变更内容盲目操作。也就是说本文介绍的全部脚本均在baseDirectory/scripts下通过skill_view获取路径后即可按上文命令执行。结语一条可复现的 docx 自动化闭环从仓库证据看docx Skill 提供了一条完整、可审计的 Word 文档自动化闭环docx_read.py负责看docx_create.py/docx_edit.py/docx_template.py负责写docx_comments.py/docx_revisions.py负责协作痕迹docx_validate.py负责结构把关LibreOffice 渲染链路负责视觉把关。对于在 Hermes Studio 中以 Agent 方式批量生成报告、填充模板、处理审阅稿的场景这套工具链兼顾了格式保真run 级替换策略、安全边界默认新文件、破坏性操作需确认与可验证性JSON 输出 健康检查 端到端测试是 Agent 可靠处理办公文档的落地参考实现。赞分享AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐CodeWhale docx 技能指南在终端编码 Agent 中创建、编辑与校验 Word 文档CodeWhale docx 技能指南在终端编码 Agent 中创建、编辑与校验 Word 文档 CodeWhale 内置的 docx 技能定义了一组可复用的人工智能AI Agent代码智能体CLI工具调用MCP Clientsscientific-agent-skills 之 docx 技能Word 文档创建、编辑、修订与批注的完整实战指南scientific agent skills 之 docx 技能Word 文档创建、编辑、修订与批注的完整实战指南 .docx 文件的本质是一个 ZIP 归AI 技能科研生物信息学数据科学Ekko Studio docx Skill 源码级解析Word 修订Tracked Changes与批注Comments的 WordprocessingML 处理Ekko Studio docx Skill 源码级解析Word 修订Tracked Changes与批注Comments的 WordprocessiAI 应用人工智能AI Agent本地部署前端后端工作流自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考