Agent Zero office-artifacts 技能实战用 office_artifact 工具创建、读取和直接编辑 ODF/OOXML 文档、表格与幻灯片【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文基于 Agent Zero 内置的office-artifacts技能plugins/_office/skills/office-artifacts/SKILL.md版本 1.4.0系统讲解如何通过office_artifact工具在 LibreOffice 生态中创建真实的 ODT/ODS/ODP 与 DOCX/XLSX/PPTX 办公包完整覆盖其最小调用示例、edit 操作矩阵与参数约定并结合 工具入口 与 底层编辑器实现 源码剖析动作分发、格式校验、图表类型归一化与版本历史机制帮助读者掌握从“生成办公交付物”到“审计回滚”的完整实战链路。技能定位ODF 一等公民OOXML 仅作兼容office-artifacts技能的触发词覆盖了 office artifact、odt、ods、odp、docx、xlsx、pptx、writer、spreadsheet、presentation 等关键词声明可用工具为office_artifact与text_editor见 SKILL.md 的 frontmatter。其核心格式策略可以概括为一句话Writer 文档→ 首选 ODT仅当用户明确要 OOXML 兼容、提供了既有 DOCX 或需要该格式时才用 DOCXCalc 表格→ 首选 ODS兼容场景用 XLSXImpress 幻灯片→ 首选 ODP兼容场景用 PPTXMarkdown 与纯文本→ 一律交给text_editor不走office_artifact。从源码结构看这一策略在多个层面被固化插件定义 中插件名为_office标题为 LibreOffice描述即 ODF-first LibreOffice Office artifacts for Writer, Calc, and Impress files且always_enabled: false属于可选启用的 developer 分区插件工具系统提示词 明确写入defaults: document-odt spreadsheet-ods presentation-odp以及 ODF is first-class for LibreOffice... DOCX/XLSX/PPTX are compatibility formats, not defaults文档存储层 用两个集合区分格式OPEN_DOCUMENT_EXTENSIONS {odt, ods, odp}与OOXML_EXTENSIONS {docx, xlsx, pptx}二者并集构成office_artifact支持的扩展名。该技能同时引导针对具体格式的深入工作优先加载同目录下的姊妹技能 writer-documents、calc-spreadsheets、impress-presentations它们与 office-artifacts 共同构成_office插件的技能族。桌面界面纪律保存即落盘打开须用户明确要求技能文档对 UI 行为有一组非常严格的约束这是理解office_artifact使用边界的关键Desktop surface 属于用户所有。创建、读取、编辑动作必须落盘保存并刷新文档状态但绝不能自动打开 Desktop 界面除非用户主动要求只有当用户明确要求打开文档/桌面时才使用open动作、open_in_canvas: true或open_in_desktop: truecreate/edit 之后回复应简短说明改了什么、保存在哪里在有用时禁止伪造 Open document、Download file 之类的 UI 假动作标签也不要在用户没问时主动解释画布没有自动打开工具结果永远不会自动打开 Editor 或 Desktop已打开的 Office 界面在保存结果后会自动刷新但刷新与打开是两回事。这一纪律在源码中同样成立OfficeArtifact.execute 将open_in_canvas/open_in_desktop作为布尔入参处理并对open_canvas、open_document、open_desktop、desktop等别名做了宽容解析_truthy归一化默认值全部为False——即任何动作都不隐含打开界面的副作用。标准工作流与 Office Context技能给出的四步标准工作流是用tool_name: office_artifact配合tool_args.action: create或open创建/打开办公文档在做内容敏感编辑之前先用read动作传file_id或path读取当前内容用edit动作应用并保存修改用户要求审计或回滚时用version_history/restore_version。关于Office context上下文可能列出已打开文件的file_id、路径、版本号、大小和时间戳但刻意不包含完整文件内容——内容相关时务必显式read。从源码看read动作内部调用 read_artifact按扩展名分派到_read_odt、_read_ods、_read_odp、_read_docx、_read_xlsx、_read_pptx六个解析器并通过max_chars默认 12000见 execute 签名对返回内容做截断这正是上下文只给元数据、内容按需拉取设计的实现基础。最小调用示例可直接复制以下示例完整继承自 SKILL.md 的 Minimal Calls 一节参数均可直接用于工具调用。创建文档{ tool_name: office_artifact, tool_args: { action: create, kind: document, title: Project Brief, format: odt, content: Draft text here. } }要点kind缺省为document也可用spreadsheet、presentation不传format时按 kind 落到 ODF 默认格式document→odt、spreadsheet→ods、presentation→odp逻辑在 _default_office_format 与系统提示词中一致对表格来说content可以是 CSV、TSV 或 Markdown 表格工具会写入真实的单元格而不是一行一个文本块——这是 ODS/XLSX 创建时最容易被误解的一点创建 ODT/ODS/ODP 后源码会调用libreoffice.validate_odf做 ODF 校验创建 DOCX 则调用libreoffice.validate_docx见 create 分支校验失败直接返回失败信息不产出半成品未指定path时存储层会基于标题生成唯一文件名重名自动追加 2、 3 后缀见 _unique_document_path若路径已存在则直接报错不会覆盖。读取内容{ tool_name: office_artifact, tool_args: { action: read, file_id: abc123 } }read别名extract返回ok、action、document元数据和截断后的content见 read 分支。编辑文本ODT/DOCX/ODP/PPTX{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: replace_text, find: old phrase, replace: new phrase } }追加文本ODT/DOCX{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: append_text, content: \nAdded line 1\nAdded line 2 } }设置表格单元格ODS/XLSX{ tool_name: office_artifact, tool_args: { action: edit, path: /a0/usr/workdir/documents/Budget.ods, operation: set_cells, cells: { Sheet1!B2: 12500, Sheet1!B3: 9800 } } }cells支持Sheet名!单元格的跨表寻址没有file_id时可以用path定位文件这是技能 Practical Rules 明确推荐的降级方式。创建内嵌图表XLSX 专属{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: create_chart, sheet: Sheet1, chart: { type: line, title: Monthly Revenue, data_range: B1:C13, categories: A2:A13, position: E1, width: 18, height: 10 } } }chart字段可以是对象也可以是 JSON 字符串SKILL.md 中说明为XLSX compatibility workbooks提供字符串兼容支持的图表类型为line、bar、column、pie、area、scatter、stock、ohlc、candlestick。股票类图表stock/ohlc/candlestick要求数据列按 Open/High/Low/Close 顺序排列或工作表头为Date, Open, High, Low, Close。从源码看这套图表机制有值得注意的细节_edit_xlsx是六个格式处理器中唯一接受create_chart的见 _edit_xlsx 的 op 白名单与技能文档 XLSX only: create_chart 完全一致图表类型会经过 归一化表例如col/columns归一到columnohlc/candlestick归一到stock底层按 stock 系列生成未识别的类型直接抛Unsupported XLSX chart type错误chart可以是单个 spec 对象、spec 数组或纯字符串纯字符串会被解析为{type: ...}解析入口在 _parse_chart_value——这解释了为什么文档允许对象或 JSON 字符串两种写法。edit 操作矩阵与参数约定技能文档给出的按格式操作矩阵是格式族支持的 operationODT / DOCXset_text、append_text、prepend_text、replace_text、delete_textODS / XLSXset_cells、append_rows、set_rows、replace_text、delete_text仅 XLSXcreate_chartODP / PPTXset_slides、append_slide、replace_text、delete_text参数约定原文档的 Arguments 一节完整保留set_text、append_text、prepend_text的文本一律放在content不要放进value/update/editsreplace_text与delete_text必须提供findreplace_text另用replace指定替换文本set_cells接受{A1: value, Sheet2!B3: 42}字典或[{sheet:Sheet1,cell:A1,value:value}]数组rows接受行数组content同样可以是 CSV、TSV 或 Markdown 表格用于set_rows/append_rows类操作create_chart使用data_range、categories/labels、position、title、width、height等字段见上文示例slides接受[{title:Slide title,bullets:[point]}]纯文本幻灯片也可以用单独一行---分隔count用于限制文本替换的生效次数。在实现侧这些约定由 edit_artifact 统一收敛先_normalize_edit_inputs归一化入参包括把content/cells/chart等字符串形态解析为结构再按扩展名分派到_edit_odt/_edit_ods/_edit_odp/_edit_docx/_edit_xlsx/_edit_pptx。两个值得注意的实现细节编辑即版本只要字节发生变化就调用document_store.replace_document_bytes写入新版本actor 标记为office_artifact:edit并刷新所有打开的桌面会话——这就是direct edits update version history and refresh the document UI的底层保证规模护栏ODS 直接编辑受ODS_DIRECT_EDIT_ROW_LIMIT 10000行、ODS_DIRECT_EDIT_COLUMN_LIMIT 1024列约束常量定义超大规模的表格改动需要换策略而不是硬写。版本审计与回滚version_history与restore_version两个动作直接对接存储层的 version_history 与 restore_version前者返回该file_id的全部版本记录后者按version_id恢复历史版本并生成新的文档状态restore_version缺少version_id时工具会明确报错而不是猜测。此外工具还提供两个文档未重点展开的动作从源码看同样可用inspect仅返回文档元数据不加载内容export配合target_format调用libreoffice.convert_document做格式转换例如 ODS → XLSX转换失败时返回带错误信息的 Responsestatus返回 LibreOffice 运行环境状态libreoffice.collect_status()适合排查环境是否就绪。Practical Rules何时该用、何时不该用技能文档末尾的 Practical Rules 是使用决策的核心清单逐条保留如下优先使用文档上下文或先前工具输出中的file_id只有path时才用path除非当前保存内容已知编辑前先read不要为一次性的微小修改创建 artifact——能在对话里说清楚、或直接编辑文件完成的事就不需要落一个办公文件没有指定二进制格式的文稿类需求用text_editor写 Markdown让 Editor surface 承担主要交互编辑表格/幻灯片需求若没有 OOXML 兼容要求创建 ODS/ODPDesktop 运行时可能在 Agent Zero 启动时被预热但可见的 Desktop surface 使用始终 opt-inLibreOffice GUI 工作适用于明确的 GUI 请求、二进制 Office 视觉润色或最终版式检查永远不要从工具结果自动打开 Editor 或 Desktop内嵌表格图表优先用原生create_chart只有工具不支持的图表行为才退化到 Python/代码执行edit用于精确的已保存 Office 修改Markdown 润色用 Editor二进制 Office 视觉润色用 Desktop直接编辑会更新版本历史并在 edit/open 结果上刷新文档 UI。小结office-artifacts技能是 Agent Zero 中办公交付物的标准作业程序它以 ODF 为第一格式、OOXML 为兼容出口用create / read / edit / version_history / restore_version五个核心动作覆盖了生成、审计、精确修改和回滚的完整闭环content接受 CSV/TSV/Markdown 表格、cells支持跨表寻址、create_chart内嵌九类图表等细节让 Agent 无需代码执行就能产出真实可打开的 LibreOffice 文件。配合 工具系统提示词 中的 UI 纪律与 office_artifact.py 的动作分发、artifact_editor.py 的六格式读写实现这套机制既保证了交付物是真正的 Office 包也把界面打开的决策权完整留给用户。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero office-artifacts 技能实战：用 office_artifact 工具创建、读取和直接编辑 ODF/OOXML 文档、表格与幻灯片
Agent Zero office-artifacts 技能实战用 office_artifact 工具创建、读取和直接编辑 ODF/OOXML 文档、表格与幻灯片【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文基于 Agent Zero 内置的office-artifacts技能plugins/_office/skills/office-artifacts/SKILL.md版本 1.4.0系统讲解如何通过office_artifact工具在 LibreOffice 生态中创建真实的 ODT/ODS/ODP 与 DOCX/XLSX/PPTX 办公包完整覆盖其最小调用示例、edit 操作矩阵与参数约定并结合 工具入口 与 底层编辑器实现 源码剖析动作分发、格式校验、图表类型归一化与版本历史机制帮助读者掌握从“生成办公交付物”到“审计回滚”的完整实战链路。技能定位ODF 一等公民OOXML 仅作兼容office-artifacts技能的触发词覆盖了 office artifact、odt、ods、odp、docx、xlsx、pptx、writer、spreadsheet、presentation 等关键词声明可用工具为office_artifact与text_editor见 SKILL.md 的 frontmatter。其核心格式策略可以概括为一句话Writer 文档→ 首选 ODT仅当用户明确要 OOXML 兼容、提供了既有 DOCX 或需要该格式时才用 DOCXCalc 表格→ 首选 ODS兼容场景用 XLSXImpress 幻灯片→ 首选 ODP兼容场景用 PPTXMarkdown 与纯文本→ 一律交给text_editor不走office_artifact。从源码结构看这一策略在多个层面被固化插件定义 中插件名为_office标题为 LibreOffice描述即 ODF-first LibreOffice Office artifacts for Writer, Calc, and Impress files且always_enabled: false属于可选启用的 developer 分区插件工具系统提示词 明确写入defaults: document-odt spreadsheet-ods presentation-odp以及 ODF is first-class for LibreOffice... DOCX/XLSX/PPTX are compatibility formats, not defaults文档存储层 用两个集合区分格式OPEN_DOCUMENT_EXTENSIONS {odt, ods, odp}与OOXML_EXTENSIONS {docx, xlsx, pptx}二者并集构成office_artifact支持的扩展名。该技能同时引导针对具体格式的深入工作优先加载同目录下的姊妹技能 writer-documents、calc-spreadsheets、impress-presentations它们与 office-artifacts 共同构成_office插件的技能族。桌面界面纪律保存即落盘打开须用户明确要求技能文档对 UI 行为有一组非常严格的约束这是理解office_artifact使用边界的关键Desktop surface 属于用户所有。创建、读取、编辑动作必须落盘保存并刷新文档状态但绝不能自动打开 Desktop 界面除非用户主动要求只有当用户明确要求打开文档/桌面时才使用open动作、open_in_canvas: true或open_in_desktop: truecreate/edit 之后回复应简短说明改了什么、保存在哪里在有用时禁止伪造 Open document、Download file 之类的 UI 假动作标签也不要在用户没问时主动解释画布没有自动打开工具结果永远不会自动打开 Editor 或 Desktop已打开的 Office 界面在保存结果后会自动刷新但刷新与打开是两回事。这一纪律在源码中同样成立OfficeArtifact.execute 将open_in_canvas/open_in_desktop作为布尔入参处理并对open_canvas、open_document、open_desktop、desktop等别名做了宽容解析_truthy归一化默认值全部为False——即任何动作都不隐含打开界面的副作用。标准工作流与 Office Context技能给出的四步标准工作流是用tool_name: office_artifact配合tool_args.action: create或open创建/打开办公文档在做内容敏感编辑之前先用read动作传file_id或path读取当前内容用edit动作应用并保存修改用户要求审计或回滚时用version_history/restore_version。关于Office context上下文可能列出已打开文件的file_id、路径、版本号、大小和时间戳但刻意不包含完整文件内容——内容相关时务必显式read。从源码看read动作内部调用 read_artifact按扩展名分派到_read_odt、_read_ods、_read_odp、_read_docx、_read_xlsx、_read_pptx六个解析器并通过max_chars默认 12000见 execute 签名对返回内容做截断这正是上下文只给元数据、内容按需拉取设计的实现基础。最小调用示例可直接复制以下示例完整继承自 SKILL.md 的 Minimal Calls 一节参数均可直接用于工具调用。创建文档{ tool_name: office_artifact, tool_args: { action: create, kind: document, title: Project Brief, format: odt, content: Draft text here. } }要点kind缺省为document也可用spreadsheet、presentation不传format时按 kind 落到 ODF 默认格式document→odt、spreadsheet→ods、presentation→odp逻辑在 _default_office_format 与系统提示词中一致对表格来说content可以是 CSV、TSV 或 Markdown 表格工具会写入真实的单元格而不是一行一个文本块——这是 ODS/XLSX 创建时最容易被误解的一点创建 ODT/ODS/ODP 后源码会调用libreoffice.validate_odf做 ODF 校验创建 DOCX 则调用libreoffice.validate_docx见 create 分支校验失败直接返回失败信息不产出半成品未指定path时存储层会基于标题生成唯一文件名重名自动追加 2、 3 后缀见 _unique_document_path若路径已存在则直接报错不会覆盖。读取内容{ tool_name: office_artifact, tool_args: { action: read, file_id: abc123 } }read别名extract返回ok、action、document元数据和截断后的content见 read 分支。编辑文本ODT/DOCX/ODP/PPTX{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: replace_text, find: old phrase, replace: new phrase } }追加文本ODT/DOCX{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: append_text, content: \nAdded line 1\nAdded line 2 } }设置表格单元格ODS/XLSX{ tool_name: office_artifact, tool_args: { action: edit, path: /a0/usr/workdir/documents/Budget.ods, operation: set_cells, cells: { Sheet1!B2: 12500, Sheet1!B3: 9800 } } }cells支持Sheet名!单元格的跨表寻址没有file_id时可以用path定位文件这是技能 Practical Rules 明确推荐的降级方式。创建内嵌图表XLSX 专属{ tool_name: office_artifact, tool_args: { action: edit, file_id: abc123, operation: create_chart, sheet: Sheet1, chart: { type: line, title: Monthly Revenue, data_range: B1:C13, categories: A2:A13, position: E1, width: 18, height: 10 } } }chart字段可以是对象也可以是 JSON 字符串SKILL.md 中说明为XLSX compatibility workbooks提供字符串兼容支持的图表类型为line、bar、column、pie、area、scatter、stock、ohlc、candlestick。股票类图表stock/ohlc/candlestick要求数据列按 Open/High/Low/Close 顺序排列或工作表头为Date, Open, High, Low, Close。从源码看这套图表机制有值得注意的细节_edit_xlsx是六个格式处理器中唯一接受create_chart的见 _edit_xlsx 的 op 白名单与技能文档 XLSX only: create_chart 完全一致图表类型会经过 归一化表例如col/columns归一到columnohlc/candlestick归一到stock底层按 stock 系列生成未识别的类型直接抛Unsupported XLSX chart type错误chart可以是单个 spec 对象、spec 数组或纯字符串纯字符串会被解析为{type: ...}解析入口在 _parse_chart_value——这解释了为什么文档允许对象或 JSON 字符串两种写法。edit 操作矩阵与参数约定技能文档给出的按格式操作矩阵是格式族支持的 operationODT / DOCXset_text、append_text、prepend_text、replace_text、delete_textODS / XLSXset_cells、append_rows、set_rows、replace_text、delete_text仅 XLSXcreate_chartODP / PPTXset_slides、append_slide、replace_text、delete_text参数约定原文档的 Arguments 一节完整保留set_text、append_text、prepend_text的文本一律放在content不要放进value/update/editsreplace_text与delete_text必须提供findreplace_text另用replace指定替换文本set_cells接受{A1: value, Sheet2!B3: 42}字典或[{sheet:Sheet1,cell:A1,value:value}]数组rows接受行数组content同样可以是 CSV、TSV 或 Markdown 表格用于set_rows/append_rows类操作create_chart使用data_range、categories/labels、position、title、width、height等字段见上文示例slides接受[{title:Slide title,bullets:[point]}]纯文本幻灯片也可以用单独一行---分隔count用于限制文本替换的生效次数。在实现侧这些约定由 edit_artifact 统一收敛先_normalize_edit_inputs归一化入参包括把content/cells/chart等字符串形态解析为结构再按扩展名分派到_edit_odt/_edit_ods/_edit_odp/_edit_docx/_edit_xlsx/_edit_pptx。两个值得注意的实现细节编辑即版本只要字节发生变化就调用document_store.replace_document_bytes写入新版本actor 标记为office_artifact:edit并刷新所有打开的桌面会话——这就是direct edits update version history and refresh the document UI的底层保证规模护栏ODS 直接编辑受ODS_DIRECT_EDIT_ROW_LIMIT 10000行、ODS_DIRECT_EDIT_COLUMN_LIMIT 1024列约束常量定义超大规模的表格改动需要换策略而不是硬写。版本审计与回滚version_history与restore_version两个动作直接对接存储层的 version_history 与 restore_version前者返回该file_id的全部版本记录后者按version_id恢复历史版本并生成新的文档状态restore_version缺少version_id时工具会明确报错而不是猜测。此外工具还提供两个文档未重点展开的动作从源码看同样可用inspect仅返回文档元数据不加载内容export配合target_format调用libreoffice.convert_document做格式转换例如 ODS → XLSX转换失败时返回带错误信息的 Responsestatus返回 LibreOffice 运行环境状态libreoffice.collect_status()适合排查环境是否就绪。Practical Rules何时该用、何时不该用技能文档末尾的 Practical Rules 是使用决策的核心清单逐条保留如下优先使用文档上下文或先前工具输出中的file_id只有path时才用path除非当前保存内容已知编辑前先read不要为一次性的微小修改创建 artifact——能在对话里说清楚、或直接编辑文件完成的事就不需要落一个办公文件没有指定二进制格式的文稿类需求用text_editor写 Markdown让 Editor surface 承担主要交互编辑表格/幻灯片需求若没有 OOXML 兼容要求创建 ODS/ODPDesktop 运行时可能在 Agent Zero 启动时被预热但可见的 Desktop surface 使用始终 opt-inLibreOffice GUI 工作适用于明确的 GUI 请求、二进制 Office 视觉润色或最终版式检查永远不要从工具结果自动打开 Editor 或 Desktop内嵌表格图表优先用原生create_chart只有工具不支持的图表行为才退化到 Python/代码执行edit用于精确的已保存 Office 修改Markdown 润色用 Editor二进制 Office 视觉润色用 Desktop直接编辑会更新版本历史并在 edit/open 结果上刷新文档 UI。小结office-artifacts技能是 Agent Zero 中办公交付物的标准作业程序它以 ODF 为第一格式、OOXML 为兼容出口用create / read / edit / version_history / restore_version五个核心动作覆盖了生成、审计、精确修改和回滚的完整闭环content接受 CSV/TSV/Markdown 表格、cells支持跨表寻址、create_chart内嵌九类图表等细节让 Agent 无需代码执行就能产出真实可打开的 LibreOffice 文件。配合 工具系统提示词 中的 UI 纪律与 office_artifact.py 的动作分发、artifact_editor.py 的六格式读写实现这套机制既保证了交付物是真正的 Office 包也把界面打开的决策权完整留给用户。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考