WaLiOffice Excel 工具实战：sheet_generate 多表生成与 rust-xlsxwriter XLSX 渲染

• 文档
• 教程
• 后端

在办公场景中，除了 Word 报告和 Markdown 文档，另一类高频需求是数据表格：需求池、排期表、渠道效果分析、商机漏斗、预算表。这些内容用纯文字表达不直观，用户最终要的是一份能筛选、能排序、能继续编辑的 Excel 文件。本文围绕《WaLiOffice - AI Agent 智能办公平台》第 3-4 节展开，完整讲解sheet_generate工具的实现思路：多表 Schema 设计、场景推断、数据真实性 Prompt 约束、JSON 容错解析、产物双链路（自动落盘 + 手动导出），以及基于rust-xlsxwriter的纯 Rust XLSX 渲染设计。读完你可以掌握在 Agent 办公平台中从"一句话需求"到"一份可交付 .xlsx"的完整链路设计能力。

一、为什么办公平台需要独立的 Excel 工具

md_generate与doc_generate输出的都是"文档"，而办公对话里还有一大类诉求是表格化数据。用户的典型表达是：

"请帮我检索天津和平区学区房价格和重点小学升学率数据，按学校排名整理成表格，包含学校名称、学区房均价、初中升学率、重点高中录取率等指标，并生成一份可汇报的 Excel 文档。"

这类内容用文字写不直观——数据要能筛选、能排序、能继续编辑，用户最终要的是一份真正的 Excel。因此在 WaLiOffice 工具注册表 的 10 个业务工具中，专门注册了sheet_generate（产物类型sheet），与ppt_plan/ppt_generate、doc_generate、md_generate、chart_generate、drawio_generate、image_prompt、video_generate、web_search并列。

从意图识别侧看，第2-6节 System Prompt 工程 中为Sheet场景配置的关键词包括：excel、表格、数据分析、排期，命中后路由到sheet_generate。

二、整体设计：LLM 管内容结构，确定性代码管格式文件

sheet_generate的设计思路与doc_generate一脉相承：

LLM 只负责内容与结构，格式与文件交给确定性的代码。

因为 LLM 擅长生成"表格里该有什么数据、有哪些列"，但不适合直接生成一个稳定可打开的二进制 Office 文件。XLSX 本质上是遵循 Office Open XML 规范的 ZIP 压缩包，内部包含多个 Sheet 的 XML、样式、关系与共享字符串等资源，必须由确定性代码负责打包。

与 Word 不同的是，本节分支上 Excel 的"渲染层"走了一条类似 PPT 的路：

• server/src/render/xlsx_render.rs保留文件内标注"完整实现在 3-4 节"的 stub（当前输出空文件）；
• 真实的表格展示与编辑发生在前端在线表格组件（多表 Tab 切换、单元格可编辑）；
• 导出 XLSX 走/api/excel/export端点，由后端渲染器把 JSON 转成真正的 .xlsx 文件。

代码状态说明：ch03-04-sheet-generate提交中sheet_generate工具已完整实现（场景推断、Prompt 构建、LLM 调用、JSON 解析、产物封装）；xlsx_render.rs仍为 stub，/api/excel/export端点已接好。也就是说：数据结构、LLM、产物封装、自动落盘尝试、前端表格与导出按钮都已就绪，只差"后端把 JSON 转成真 xlsx"这一步。阅读下文时请区分"工具已落地的部分"与"渲染器讲解部分"，不要把设计稿当成已提交代码。

三、sheet_generate 全链路流程

一次 Excel 生成的完整调用链路如下：

用户需求（topic） ↓ ① call() 提取参数：topic 必填、scene_guide = infer_sheet_scene(topic) ↓ ② ctx.send("state_update")：正在生成《{topic}》表格... ↓ ③ 构建 Prompt：system（严格 JSON 格式 + 数据真实性约束） + user（场景偏好 + 用户需求） ↓ ④ LlmClient::for_user().chat() → LLM 返回 JSON 文本 ↓ ⑤ extract_json 三级容错解析 → serde 反序列化为 SheetOutput ↓ ⑥ 封装 ToolArtifact { kind: "sheet" } content = { type, title, tables } ↓ ⑦ ToolResult::ok（observation 带"共 N 个表格、M 行数据"） ↓ ⑧ AgentEvent::Artifact → SSE → save_generated_artifact_to_files kind == "sheet" → 取 content.tables → render_xlsx（stub：空文件） → save_file_bytes 存入文件系统/库 ↓ 前端右侧面板：SheetArtifact 在线表格（Tab 切换 + 单元格编辑） 用户点"导出 XLSX" → POST /api/excel/export → render_xlsx → 下载 .xlsx

这条链路与 第3-2节 Word 工具 高度同构：参数提取 → 状态推送 → Prompt 构建 → LLM 调用 → JSON 解析 → 产物封装 → SSE 事件 → 落盘/导出，区别仅在产物的 kind、数据结构与渲染器。

四、多表 Schema 设计：SheetOutput 与 SheetTable

Excel 工具的核心数据结构是"一个输出对象包含多个表格"：

struct SheetOutput { title: String, // 表格组标题 tables: Vec<SheetTable>,// 多个表格（对应多个 Sheet） summary: Option<String>,// 整体说明 } struct SheetTable { title: String, // 表格/Sheet 标题 headers: Vec<String>, // 表头列 rows: Vec<Vec<String>>, // 数据行 summary: Option<String>,// 该表说明 }

两个设计要点：

1. 多表（tables 数组）能力：需求复杂时自动拆成多表。典型如"明细表 + 汇总表""计划表 + 风险表"，每个 table 最终对应 XLSX 里的一个 Sheet，实现单文件多 Sheet 输出。
2. #[serde(default)]的容错意义：LLM 输出的 JSON 时常会缺字段（漏掉summary、少给一个可选字段）。给所有可选字段加上#[serde(default)]后，反序列化时缺失字段自动取默认值，而不是整体解析失败，大幅提升 LLM 输出的容忍度——这与DocOutput系列结构体"每个可选字段都要有默认值"的设计哲学一致。

在 Prompt 中还会对表格结构施加硬约束：每个表格至少 4 列 6 行，保证生成的表格有实际可用性，而不是零散的几行数据。

五、场景推断：infer_sheet_scene 注入领域知识

LLM 的强项是内容组织，但"这个业务场景该设计哪些列"属于领域知识，不能完全指望模型脑补。infer_sheet_scene(topic)用关键词匹配识别业务场景，给 LLM 注入"该设计哪些列"的引导：

• 产品管理：需求池、排期、优先级、负责人
• 运营分析：渠道、转化率、成本、ROI
• 销售管理：商机漏斗、金额、阶段、赢率
• 技术项目：里程碑、任务、风险等级、负责人
• 培训管理：课程、讲师、学员、满意度
• 项目交付：交付物、验收标准、时间节点
• 通用业务：兜底场景，自由组织

场景推断结果以scene_guide形式并入 user prompt，让 LLM 在生成 headers 时具备业务常识，产出"专业可执行"的表头——负责人、阶段、金额、转化率、风险等级这类列，而不是空泛的"项目1/项目2"。

六、Prompt 工程：数据真实性与表头专业性约束

Excel 工具对 LLM 的约束比文档工具更严格，核心是数据真实性约束：

1. 显式禁止占位数据：必须显式禁止"示例1/示例2"式的占位行。办公表格是要拿去汇报、排期的，填满假数据比空表危害更大；
2. 表头专业可执行：要求 LLM 产出可直接落地的业务表头（负责人、阶段、金额、转化率、风险等级等），而非口语化的列名；
3. 严格 JSON 格式：system prompt 要求 LLM 只输出符合 SheetOutput 结构的 JSON，不做任何额外解释，为后续serde反序列化铺路。

这三条约束共同保证：LLM 返回的内容是"结构正确、数据真实、业务可用"的表格数据，把"格式与文件"这最后一步留给渲染器。

七、JSON 容错解析：extract_json 三级降级

LLM 输出的文本经常带有各种噪声，直接交给serde_json反序列化大概率失败。extract_json实现了三级容错降级：

1. 去围栏：剥掉 LLM 常见的```json ... ```Markdown 代码块围栏；
2. 首尾大括号截取：从第一个{截取到最后一个}，剥离前后杂散文本；
3. 数组截取：若整体不是对象而是数组包裹，尝试截取数组片段后再次尝试反序列化。

三级逐级兜底，把"LLM 输出形态不可控"这个 Agent 工程中的经典问题消化在解析层，之后才serde反序列化为SheetOutput。这套降级策略与doc_generate、chart_generate等工具共用，是整个工具体系的通用能力。

八、产物双链路：自动落盘与手动导出

kind: "sheet"的产物走双链路，理解这两条路是本节的关键：

链路一：自动落盘（stub 渲染）

AgentEvent::Artifact经 SSE 推送到 Chat 路由后，save_generated_artifact_to_files对kind == "sheet"的产物执行：取content.tables→ 调render_xlsx（当前分支为 stub，输出空文件）→save_file_bytes存入文件系统/库。设计目标是让每次生成的表格自动进入【我的文件】。

链路二：手动导出（真实渲染）

用户在前端在线表格中看到并可编辑数据后，点击"导出 XLSX"按钮 →POST /api/excel/export→ 后端render_xlsx把 JSON 渲染为真正的 .xlsx → 下载。

第3-5节 ECharts 图表工具 曾明确区分过项目里"产物"的两个含义：文件产物（docx/xlsx，落盘，进文件系统）与数据产物（search/chart，只进前端渲染）。sheet属于前者——它是需要落盘、可下载的正式文件。

九、XLSX 渲染器设计：纯 Rust 的 rust-xlsxwriter

第1-2节 技术栈选型 中明确：sheet_generate的底层渲染组件是rust-xlsxwriter（同类方案有 Java 的 EasyExcel），定位是"纯 Rust 生成 Excel 表格"。选择纯 Rust 渲染的理由与 docx-rs 完全一致：WaLiOffice 是纯 Rust 后端，如果引入 Java/Python 渲染，就要额外起服务或走命令行调用，多一个外部依赖就多一个故障点；纯 Rust 在同一进程内完成渲染，零网络开销、无外部依赖，安全性高。

结合项目整体描述，render_xlsx的目标设计包含五个关键点：

1. 一表一 Sheet：SheetOutput.tables中的每个SheetTable对应输出文件中的一个 Sheet，天然支持单文件多 Sheet；
2. 表头样式：表头行采用红底白字粗体格式，保证首行视觉可读性；
3. 数字类型识别：数据行自动识别数字类型，数值列调用write_number写入（而不是统一写成字符串），这样导出的表格在 Excel 中可以直接参与求和、排序等计算；
4. 列宽自适应：列宽autofit按内容自适应，避免出现内容被截断的窄列；
5. Sheet 名合法性清洗：Sheet 名需要满足 Excel 的硬性规范——不超过 31 个字符、过滤/ \ ? * [ ] :等特殊字符，防止 LLM 生成的标题导致渲染失败。

结合 WaLiOffice 项目总览 中"使用 rust-xlsxwriter crate 渲染为 .xlsx 文件"的表述，本节的动手目标就是把ch03-04-sheet-generate分支中xlsx_render.rs的 stub 替换为上述逻辑，打通"JSON → Sheet → .xlsx"的最后一步。

十、前端在线表格：编辑回写与最新数据导出

与 Word 的静态预览不同，Excel 的前端面板是可交互的在线表格：

• 多表 Tab 切换：右侧面板按tables数组渲染多个表格，以 Tab 形式切换查看；
• 单元格可编辑：用户可以直接在表格里修改数据，onUpdate事件把修改回写到 artifact 状态；
• 导出用最新数据：点击"导出 XLSX"时，提交给/api/excel/export的是编辑后的最新数据，而不是 LLM 的原始输出——用户调整完再导出，拿到的就是自己改过的版本。

这一设计把"AI 生成"与"人工微调"衔接起来：LLM 负责初稿质量，用户负责最终修正，后端负责把修正后的数据渲染成文件。

十一、总结：一条 Excel 工具的实现心法

sheet_generate的价值在于把"LLM 生成表格数据"这件事做成了工程上可交付的完整链路。回顾全节，核心心法可以浓缩为五点：

1. 分工明确：LLM 生成内容与结构，rust-xlsxwriter 负责格式与文件，各司其职；
2. Schema 先行：用SheetOutput/SheetTable多表结构承载复杂需求，用#[serde(default)]吸收 LLM 输出噪声；
3. 领域知识注入：infer_sheet_scene场景推断让表头专业可执行；
4. 约束要硬：Prompt 显式禁止占位数据，extract_json三级降级兜底解析；
5. 链路要双：自动落盘保证产物可追溯，手动导出保证用户编辑后的数据能变成真文件。

掌握了这五条，你不仅能复现 WaLiOffice 的 Excel 生成能力，还能把它迁移到任意"LLM + 办公产物"的 Agent 场景中。后续可继续阅读 ECharts 图表工具 了解"数据产物不落盘"的轻量模式，与本节的"文件产物落盘"形成对照。

• 文档
• 教程
• 后端