企业官网建设流程全解析

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 或需要该格式时才用 DOCX；
• Calc 表格→ 首选 ODS，兼容场景用 XLSX；
• Impress 幻灯片→ 首选 ODP，兼容场景用 PPTX；
• Markdown 与纯文本→ 一律交给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使用边界的关键：

1. Desktop surface 属于用户所有。创建、读取、编辑动作必须落盘保存并刷新文档状态，但绝不能自动打开 Desktop 界面，除非用户主动要求；
2. 只有当用户明确要求打开文档/桌面时，才使用open动作、open_in_canvas: true或open_in_desktop: true；
3. create/edit 之后，回复应简短说明改了什么、保存在哪里（在有用时），禁止伪造 "Open document"、"Download file" 之类的 UI 假动作标签，也不要在用户没问时主动解释"画布没有自动打开"；
4. 工具结果永远不会自动打开 Editor 或 Desktop；已打开的 Office 界面在保存结果后会自动刷新，但"刷新"与"打开"是两回事。

这一纪律在源码中同样成立：OfficeArtifact.execute 将open_in_canvas/open_in_desktop作为布尔入参处理，并对open_canvas、open_document、open_desktop、desktop等别名做了宽容解析（_truthy归一化），默认值全部为False——即任何动作都不隐含"打开界面"的副作用。

标准工作流与 Office Context

技能给出的四步标准工作流是：

1. 用tool_name: "office_artifact"配合tool_args.action: "create"或"open"创建/打开办公文档；
2. 在做内容敏感编辑之前，先用read动作（传file_id或path）读取当前内容；
3. 用edit动作应用并保存修改；
4. 用户要求审计或回滚时，用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归一到column，ohlc/candlestick归一到stock（底层按 stock 系列生成），未识别的类型直接抛Unsupported XLSX chart type错误；
• chart可以是单个 spec 对象、spec 数组，或纯字符串（纯字符串会被解析为{"type": ...}），解析入口在 _parse_chart_value——这解释了为什么文档允许"对象或 JSON 字符串"两种写法。

edit 操作矩阵与参数约定

技能文档给出的按格式操作矩阵是：

参数约定（原文档的 Arguments 一节，完整保留）：

• set_text、append_text、prepend_text的文本一律放在content，不要放进value/update/edits；
• replace_text与delete_text必须提供find；replace_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），转换失败时返回带错误信息的 Response；
• status：返回 LibreOffice 运行环境状态（libreoffice.collect_status()），适合排查"环境是否就绪"。

Practical Rules：何时该用、何时不该用

技能文档末尾的 Practical Rules 是使用决策的核心清单，逐条保留如下：

• 优先使用文档上下文或先前工具输出中的file_id；只有path时才用path；
• 除非当前保存内容已知，编辑前先read；
• 不要为一次性的微小修改创建 artifact——能在对话里说清楚、或直接编辑文件完成的事，就不需要落一个办公文件；
• 没有指定二进制格式的文稿类需求，用text_editor写 Markdown，让 Editor surface 承担主要交互编辑；
• 表格/幻灯片需求若没有 OOXML 兼容要求，创建 ODS/ODP；
• Desktop 运行时可能在 Agent Zero 启动时被预热，但可见的 Desktop surface 使用始终 opt-in；LibreOffice 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