WaLiOffice 第3-1节实战：Markdown 工具全链路打通——从 Prompt 工程到前端渲染的 Agent 工具模板化设计

文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载本节聚焦 WaLiOfficeAI 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的验收清单理解工具的输入/输出设计parameters()返回的 JSON Schema 如何让 Agent 知道该传什么参数ToolResult如何把产物带回给前端掌握 Prompt 三段式工程system prompt角色 输出格式约束→ user prompt风格指引 场景偏好 用户需求→ LLM 输出严格 JSON实现场景自动推断infer_markdown_scene根据 topic 关键词补足内容侧重点让生成结果贴合真实办公场景处理 LLM 输出解析失败extract_json两级容错去 markdown fence → 截取花括号失败时返回降级草稿而不是报错打通产物渲染链路ToolArtifact { kind: markdown }→ SSE 推送 → 前端MarkdownArtifact组件渲染 → 下载.md文件。三、流程设计md_generate 工具调用链路从用户发消息到 Markdown 文档出现在右侧面板完整链路如下用户输入 帮我整理一份 AI Agent 技术调研文档 ↓ POST /api/chat/streamChat 路由见第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 设计把像人写的、能直接发布作为目标采用三段式结构system prompt角色 输出格式约束给 LLM 设定文档写作者角色并强制声明输出必须是严格的 JSON 结构标题 章节 正文 要点列表等从源头约束输出形态user prompt风格指引 场景偏好 用户需求注入style_guide匹配到的风格说明、infer_markdown_scene推断出的场景侧重以及用户原始的topic需求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实现了两级容错去 markdown fence先剥离 json ... 之类的代码块包裹截取花括号再定位第一个{到最后一个}之间的内容暴力截取 JSON 主体。即使两级解析都失败工具也不会向用户抛错而是进入降级草稿fallback返回一份结构完整的 Markdown 草稿把topic作为标题、按通用章节框架组织内容确保始终有产物返回。这种解析失败不报错、降级兜底的容错哲学在 WaLiOffice 中是贯穿性的——Word 工具与纯 Rust DOCX 渲染 同样设计了LLM 输出解析失败时降级草稿兜底视频生成一节也以 ffmpeg 本地合成作为 API 不可用时的兜底。容错与降级是生产级 Agent 工具与玩具 demo 的分水岭。八、产物渲染链路ToolArtifact → SSE → MarkdownArtifactmd_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 工具实现模板环节md_generate 的做法后续工具复用点参数声明parameters()返回 JSON Schematopic 必填各工具声明自己的参数契约场景推断infer_markdown_scene关键词识别内容侧重Word 7 类场景、Excel 7 类场景、PPT 7 类场景Prompt 拼装角色约束 风格指引 场景偏好 用户需求所有生成类工具共用三段式结构输出解析extract_json两级容错所有 LLM 直出 JSON 的工具共用失败兜底降级草稿而非报错Word/Excel/PPT 均有对应 fallback产物封装ToolArtifact { kind: markdown }按 kind 分发到不同前端渲染器从源码结构看后续的doc_generate、sheet_generate、chart_generate等工具走的都是换模板 加渲染的同一套路换一套场景关键词、换一份 Prompt 模板、加一个对应 kind 的前端组件。把md_generate吃透等于打通了 WaLiOffice 工具体系的任督二脉——这正是本节作为第三章第一课的价值所在。赞分享文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载相关推荐架构革命Box64如何重塑ARM平台上的x86_64程序运行生态架构革命Box64如何重塑ARM平台上的x86_64程序运行生态 在当今多元化的计算架构生态中一个看似不可能的任务正在成为现实在树莓派、安卓设备或RISC文档教程后端从0到1打通前端工程化Webpack到Git的全链路实战指南从0到1打通前端工程化Webpack到Git的全链路实战指南 你是否还在为前端项目构建缓慢而抓狂是否在多人协作时被代码冲突搞得焦头烂额本文将带你从零开始掌教程前端WaLiOffice PPT 双工具协作实战从 ppt_plan 大纲规划到 ppt_generate 精确渲染WaLiOffice PPT 双工具协作实战从 ppt_plan 大纲规划到 ppt_generate 精确渲染 本文聚焦 WaLiOfficeAI Age文档教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考