企业官网建设流程全解析

• 文档
• 教程
• 后端

本节聚焦 WaLiOffice（AI Agent 智能办公平台）中第一个被"写实"的办公工具md_generate，完整讲解它是如何从"接收参数 → 构建 Prompt → 调 LLM → 解析 JSON → 封装产物"跑通全链路的。你将掌握 Agent 工具的输入/输出规范设计、Prompt 三段式工程、场景自动推断、JSON 容错解析与降级草稿，以及ToolArtifact产物从后端经 SSE 推送到前端MarkdownArtifact组件渲染的完整通路。这套"模板化"工具设计套路，正是后续 9 个办公工具逐个落地的通用骨架。

一、为什么拿 md_generate 打头阵

WaLiOffice 在第二章已经搭好了 Agent 骨架——LLM 客户端、工具注册表、ReAct 循环、意图识别、SSE 推流、前端对话界面全部打通。但彼时注册表里的 11 个办公工具全是stub（空壳）：Agent 会调用它们，调用完只回一句"功能开发中"。

从本节开始进入第三章，把工具一个一个写实，第一个动手的就是Markdown 文档生成工具（md_generate）。选择它打头阵有三个原因：

• 不需要外部 API：不像web_search要对接联网服务；
• 不需要二进制渲染：不像 docx/pptx 要做 OOXML 解析与写入；
• 不需要多轮编排：不像 PPT 要走ppt_plan → ppt_generate两阶段协作。

它本质就是一条纯粹的"接收参数 → 构建 Prompt → 调 LLM → 解析 JSON → 封装产物"流水线。但麻雀虽小五脏俱全——Prompt 工程、场景推断、JSON 容错解析、降级草稿、产物结构化、前端渲染，这些后续每个工具都要复用的套路，在这一节里全部出现。把md_generate吃透，后面 9 个工具基本就是"换模板 + 加渲染"的事。

二、本章诉求

本节要达成的五个学习目标，也是设计md_generate的验收清单：

1. 理解工具的输入/输出设计：parameters()返回的 JSON Schema 如何让 Agent 知道该传什么参数，ToolResult如何把产物带回给前端；
2. 掌握 Prompt 三段式工程：system prompt（角色 + 输出格式约束）→ user prompt（风格指引 + 场景偏好 + 用户需求）→ LLM 输出（严格 JSON）；
3. 实现场景自动推断：infer_markdown_scene根据 topic 关键词补足内容侧重点，让生成结果贴合真实办公场景；
4. 处理 LLM 输出解析失败：extract_json两级容错（去 markdown fence → 截取花括号），失败时返回降级草稿而不是报错；
5. 打通产物渲染链路：ToolArtifact { kind: "markdown" }→ SSE 推送 → 前端MarkdownArtifact组件渲染 → 下载.md文件。

三、流程设计：md_generate 工具调用链路

从用户发消息到 Markdown 文档出现在右侧面板，完整链路如下：

用户输入 "帮我整理一份 AI Agent 技术调研文档" ↓ POST /api/chat/stream（Chat 路由，见第2-7节） ↓ 意图识别 → allowed_tools 包含 md_generate ↓ ReAct 循环：LLM 决策调用 md_generate(topic, style, audience) ↓ ┌─────────────── md_generate.call() ───────────────┐ │ ① 参数提取与校验（topic 不能为空） │ │ ② 场景推断 infer_markdown_scene(topic) │ │ ③ 状态推送 ctx.send("state_update", ...) │ │ ④ 风格指引 style_guide 匹配 │ │ ⑤ 构建 system_prompt + user_prompt │ │ ⑥ LlmClient.chat() 调用 LLM │ │ ⑦ extract_json 容错解析 → MarkdownOutput │ │ ⑧ 解析失败 → 降级草稿（fallback） │ │ ⑨ 封装 ToolArtifact { kind: "markdown" } │ └───────────────────────────────────────────────────┘ ↓ AgentEvent::Artifact → SSE artifact_update 事件 ↓ 产物落盘 .md 文件 + 持久化到会话 ↓ 前端 MarkdownArtifact 组件渲染（marked 风格预览 + 下载按钮）

链路的前半段（Chat 路由、意图识别、ReAct 循环）在第二章已经就绪，本节的核心是中间方框内md_generate.call()的九步内部逻辑，以及它如何把自己的产出交还给前端。注意第三步的ctx.send("state_update", ...)：工具执行过程中的状态会实时推给前端，用户在等待生成时能感知到"参数校验中 / 场景推断中 / LLM 生成中"等阶段变化，这与第二章 SSE 推流能力是一脉相承的。

四、工具输入/输出设计：让 Agent 知道该传什么、该返回什么

md_generate之所以能被 Agent 正确驱动，前提是工具系统在第二章就定下的统一契约——工具 Trait 定义与注册表机制 中OfficeToolTrait 的核心思路：把工具抽象成 Trait，具体工具实现 Trait，通过全局注册表统一管理。LLM 决定调用哪个工具 → 从注册表查到工具实例 → 调用tool.call(input, ctx)→ 返回ToolResult。工具的具体逻辑完全封装在实现类里，LLM 和 ReAct 循环不需要知道细节。

对应到本节，有两个关键设计点：

parameters()返回 JSON Schema：工具向 LLM 声明自己接受哪些参数及其约束。对md_generate而言，核心参数是topic（文档主题，必填，不能为空）、style（风格偏好，可选）、audience（读者对象，可选）。JSON Schema 的存在让 LLM 在 ReAct 决策时能"照着说明书传参"，避免乱传或漏传。

ToolResult/ToolArtifact产物规范：工具执行完毕后，把结构化产物封装成统一返回格式。md_generate的产物类型是markdown，与工具注册表中的声明一一对应。回顾 工具注册表一览，md_generate的定位是"生成 Markdown，产物类型 markdown"，这条工具与产物类型的映射关系，正是前端决定用哪个渲染器来展示结果的关键依据。

五、Prompt 三段式工程：让 LLM 输出"能直接发布的文档"

直接让 LLM 生成"AI Agent 技术调研文档"，得到的往往是一堆正确的废话。md_generate的 Prompt 设计把"像人写的、能直接发布"作为目标，采用三段式结构：

1. system prompt（角色 + 输出格式约束）：给 LLM 设定文档写作者角色，并强制声明输出必须是严格的 JSON 结构（标题 + 章节 + 正文 + 要点列表等），从源头约束输出形态；
2. user prompt（风格指引 + 场景偏好 + 用户需求）：注入style_guide匹配到的风格说明、infer_markdown_scene推断出的场景侧重，以及用户原始的topic需求；
3. LLM 输出（严格 JSON）：模型按约束返回结构化内容，供下一步extract_json解析。

这里LlmClient.chat()是第二章已封装的 LLM 客户端能力——支持流式/非流式/附件三种调用模式，md_generate直接复用非流式调用拿完整 JSON 结果即可。

六、风格指引与场景推断：告别"正确的废话"

本节的两个灵魂设计，都服务于同一个目标：生成结果贴合真实办公场景。

风格指引（style_guide）：根据用户的style参数匹配写作风格。不同风格对应不同的语气、句式密度和排版偏好——技术调研用严谨结构，运营分析偏数据化表达，通用商务讲究简洁清晰。它让同一份topic在不同风格参数下产出截然不同的文档。

场景推断（infer_markdown_scene）：当用户没有明确指定风格时，工具根据topic关键词自动补足内容侧重点。这一步与第二章的意图识别一脉相承——System Prompt 工程与意图识别 中定义了Markdown意图（触发关键词：markdown、readme、知识库、会议纪要 → 对应md_generate），以及TextGenerate意图（写提示词、写脚本、构思方案 → 同样落到md_generate）。而本节把意图粒度进一步细化到工具内部：识别出"知识库"场景，就强调结构化的目录与章节组织；识别出"会议纪要"场景，就偏重结论先行、行动项列表；识别出"调研报告"，就强化背景、现状、方案对比、结论建议的完整论证链。

两层设计叠加的效果是：用户说"帮我整理一份 AI Agent 技术调研文档"，系统既知道该生成 Markdown 产物（意图层），又知道按"技术调研"场景组织内容侧重点（工具层），两层的模板复用让后续 9 个工具同样受益。

七、JSON 容错解析与降级草稿：永远给用户一个产物

LLM 输出的 JSON 往往"不那么标准"——可能被```json这样的 markdown fence 包裹，也可能在首尾混入解释性文字。为此extract_json实现了两级容错：

1. 去 markdown fence：先剥离 `````json ...```` 之类的代码块包裹；
2. 截取花括号：再定位第一个{到最后一个}之间的内容，暴力截取 JSON 主体。

即使两级解析都失败，工具也不会向用户抛错，而是进入降级草稿（fallback）：返回一份结构完整的 Markdown 草稿，把topic作为标题、按通用章节框架组织内容，确保"始终有产物返回"。这种"解析失败不报错、降级兜底"的容错哲学在 WaLiOffice 中是贯穿性的——Word 工具与纯 Rust DOCX 渲染 同样设计了"LLM 输出解析失败时降级草稿兜底"，视频生成一节也以 ffmpeg 本地合成作为 API 不可用时的兜底。容错与降级，是生产级 Agent 工具与玩具 demo 的分水岭。

八、产物渲染链路：ToolArtifact → SSE → MarkdownArtifact

md_generate的产出最终要出现在前端右侧面板，这依赖后端与前端两段配合：

后端侧：工具把结果封装为ToolArtifact { kind: "markdown" }，由 Agent 引擎发出AgentEvent::Artifact事件，通过 SSE 以artifact_update事件推送到前端。同时产物落盘为.md文件并持久化到当前会话，用户后续可以在"我的文件"中查看、下载或删除。从 WaLiOffice 项目总览 对前端 SSE 的说明看，前端解析artifact_update事件后会触发按类型区分的产物渲染与自动导出机制——markdown 类型触发.md下载并同步保存到用户文件列表。

前端侧：MarkdownArtifact组件专门负责渲染kind: "markdown"的产物，提供 marked 风格预览和下载按钮两个能力——左侧是排版后的实时预览，右侧提供.md文件下载。用户从发出"帮我整理一份 AI Agent 技术调研文档"，到右侧面板出现可预览、可下载的 Markdown 文档，全程无需离开对话界面。

九、小结：一个模板，九个复刻

回顾md_generate的完整链路，它其实是一份可复用的"Agent 工具实现模板"：

从源码结构看，后续的doc_generate、sheet_generate、chart_generate等工具，走的都是"换模板 + 加渲染"的同一套路：换一套场景关键词、换一份 Prompt 模板、加一个对应 kind 的前端组件。把md_generate吃透，等于打通了 WaLiOffice 工具体系的任督二脉——这正是本节作为第三章第一课的价值所在。

• 文档
• 教程
• 后端