企业官网建设流程全解析

去年我在某个内部知识管理系统上捣鼓文档自动化，最初用的是最简单的模板引擎加关键词替换，效果实在一般。后来换成大模型去总结会议纪要和周报，生成得倒是挺流畅，可每次看到模型输出的那一大段内容，心里总有点不踏实：它到底参考了哪些材料？这个结论是依据哪条数据推出来的？中间有没有偷偷“脑补”？

这个不踏实，说白了就是“思维不可见”。直到我认真研究了 MCP（Model Context Protocol）协议，把文档自动化工具改造成了“自描述”的接口集合，模型每一步调用什么工具、传了什么参数、读的哪个文件，全都变成一条条可追溯的记录，我才意识到，协议层面的设计才是解决透明度问题的终极红利。

这篇文章我不会跟你聊太虚的“AI 伦理”或者“可解释性”大词，而是从协议设计的角度，拆解 MCP 究竟是什么、它为什么天然适合做文档自动化、怎么落地一个带完整操作日志的文档生成系统，以及我踩过的坑。

1. 项目缘起：文档自动化为什么难，MCP 又为什么能解？

1.1 文档自动化的老剧本：模板、RPA 和裸调大模型

先说老路。传统文档自动化大概经历过三个阶段：

第一阶段是模板填充，用 Word 域、邮件合并、代码里的字符串格式化，把变量塞进预设好的文档骨架。好处是稳定快，坏处是只能处理结构完全固定的文档，稍微换一个场景，模板就废了。

第二阶段是 RPA，用脚本模拟人去点按钮、复制粘贴。这个方案确实解决了一些跨系统搬运的问题，可一旦源系统的界面改版，脚本立刻失效，维护成本高到吓人。

第三阶段就是裸调大模型，把需求写进 Prompt，让它直接输出 Markdown 或者 Word 文档。我身边很多团队走到这一步就停了，因为生成的东西确实漂亮，但有两个致命问题：一是模型容易一本正经地编造数据；二是你没法审计它的生成依据，出了问题根本不知道是哪一步错的。

1.2 MCP 的本质不是“接口”，而是“上下文容器”

MCP 的全称是 Model Context Protocol，直译是模型上下文协议。我给它的定位是：模型与外部工具、数据源之间的一套统一“通信语言”。

为什么说它不是简单接口？普通 API 接口解决的是“程序调用程序”的问题，调用方清清楚楚自己要什么参数。但 MCP 解决的是“模型调用工具”的问题，关键是模型是概率生成的，它可能不清楚有哪些工具、每个工具接受什么参数、返回值是什么结构。

所以 MCP 协议强迫每个工具服务端把自己“是什么、能干什么、需要什么、返回什么”用标准化的 schema 描述出来。模型端拿到这些描述之后，才能准确决策。

放在文档自动化场景里理解：你有一个 MCP Server 专门提供“读取项目周报入口”“查询产品需求文档”“生成版本更新说明”这些工具。模型不是靠猜，而是靠服务端提供的自描述清单来规划整个文档生成流程。这恰恰就是“模型思维透明度”的第一道保障，它想调用什么，第一步就必须清楚地写在请求里。

简单类比：传统 API 像是让一个全能助理去帮你拿文件，助理的权限清单锁在保险柜里，你只知道结果。而 MCP 是把助理的工作手册摊开在你桌上，他每拿一份文件，都会在手册上登记一笔，你随时能检查。

2. 自描述协议的设计逻辑：思维透明度从哪来？

2.1 所谓“自描述”，就是让机器能读懂工具的“说明书”

我见过不少误读，把 MCP 的自描述理解成“接口文档写得详细一点”。这远远不够。

MCP 的自描述包含四个层面：

• 工具清单描述：服务端暴露了哪些可调用工具，每个工具的 summary 写的是什么，是否足够指导模型做出正确选择。
• 入参 JSON Schema：每个工具接受什么字段、字段类型、是否必填、取值范围、默认值。这部分是机器强校验的，传错类型直接报错。
• 资源列表描述：服务端提供哪些可读取的资源（文件、数据库表、外部系统数据），用什么样的 URI 标识，读取后返回什么 MIME 类型。
• Prompt 模板描述：服务端预置了哪些提示词模板，模型可以直接复用，减少重复构造 Prompt 的成本。

这四个层面都做到“机器可读”，模型的决策才算真正“有所依据”。我构造文档自动化工具时，会在服务端为每个工具写极长的描述字段，例如“此工具用于从指定版本目录读取历史变更记录，适用于生成 changelog 时核对事实，输出为 JSON 数组，每项包含 commitId、author、date、message”。

这段描述看似冗余，但对模型来说，就是“何时用、怎么用、用了会怎样”的全部信息。模型基于这些信息形成的调用计划，天然就是可解释的，因为计划里每一步都对齐了具体的工具和参数。

2.2 思维透明度的三个层次

我拆解模型用 MCP 做文档自动化时的“透明度”，至少有三个层面：

第一层，意图透明。模型为什么选这个工具而不是那个？因为 Prompt 模板或工具描述里带着强烈的语义指向。比如模型要生成“月度总结”，看到“summarize_monthly_report”和“get_raw_attendance_data”两个工具，它选择前者就是把“我要总结”这个意图显性化，而不是自己在上下文里瞎糊弄。

第二层，参数透明。模型调用工具时传入的参数集合就是它思考过程的一部分。比如生成产品需求文档时，模型向“search_docs_by_keyword”工具传的参数是“支付流程、退款、异常”，这个参数就是它判断用户需求后的进一步限定。开发者完全可以把这些参数记录下来，反推模型的注意力焦点。

第三层，执行过程透明。工具调用顺序、中间结果的引用、最终文档里哪一部分对应哪次工具返回，全部有迹可循。我后来做的日志系统就把这些记录存成 JSON Lines，每次生成完文档，还能导出一份“决策轨迹报告”。

2.3 为什么说这是“终极红利”？

坦白讲，市面上很多号称可解释的大模型方案，我看完都觉得是在补漏洞。而 MCP 的思路是：既然模型本身是个黑箱，那就把黑箱体外面的“输入”“输出”“工具操作”全部协议化，做到白盒。你不需要理解模型神经元里发生了什么，你只需要审计它跟世界交互的每一个动作。

文档自动化恰恰是这类“动作审计”收益最大的场景：

• 文档内容可以被逐一溯源到数据源，杜绝模型凭空捏造；
• 文档变更可以被记录成工具调用序列，回溯版本问题时直达根因；
• 文档生成质量可以归因到“知识库覆盖不足”还是“工具选择错误”，实现真正的流程纠偏。

这一层红利，才是自描述协议给模型“思维透明度”带来的终极价值，比单纯把日志打印到控制台要高一个维度。

3. 实操：搭建一个基于 MCP 的文档自动化工作流

3.1 架构总览

我搭建的系统不复杂，核心就三个角色：

• MCP Server（文档服务端）：封装若干文档相关操作，例如素材检索、模板加载、章节生成、格式转换、历史对比。
• MCP Client（宿主程序）：负责连接远端模型和服务端，传递和接收协议消息。一般这类宿主就是 Agent 框架或命令行客户端。
• 大模型（决策端）：根据服务端提供的工具清单，动态编排调用链，生成文档内容。

整个交互模式是典型的“客户端-服务器”双端：客户端持有一个 JSON-RPC 会话，服务端在这个会话里暴露工具、资源和 Prompt 模板。模型每执行一步操作，客户端都会把结果回填进上下文，再让模型决定下一步。

3.2 服务端实现：用小段代码说清“自描述”

我以 Python 为例，写一个最小化的文档服务端，重点展示工具是怎么“自描述”的。这里我用 FastMCP 风格的伪代码，因为实际写起来最顺手，但重要的是理解每个字段的作用，而不是背诵某个框架。

from pydantic import BaseModel, Field from typing import Literal class ChangeLogInput(BaseModel): module: str = Field(description="要生成变更日志的模块名，比如 auth/payment/order") days: int = Field(default=7, ge=1, le=30, description="回溯的时间范围，默认7天，最长30天") style: Literal["plain", "table", "semantic"] = Field( default="plain", description="输出样式：plain为纯文本列表，table为Markdown表格，semantic为按语义分组的列表" ) class ChangeLogTool: """这个类就是自描述的载体：模型读它的 docstring 和字段描述就知道怎么用了。""" def __init__(self, repo_root: str): self.repo_root = repo_root async def call(self, params: ChangeLogInput) -> list[dict]: # 真实场景在此扫描 git log / 工单系统 / 发布平台 results = [ {"commitId": "a1b2c3", "author": "dev01", "date": "2025-01-04", "message": "fix: 修复支付回调超时"}, {"commitId": "d4e5f6", "author": "dev02", "date": "2025-01-05", "message": "feat: 新增退款进度查询接口"}, ] if params.style == "table": return {"markdown": "\n".join(f"| {r['commitId']} | {r['message']} |" for r in results)} return results

一眼就能看出，ChangeLogInput 里的每个字段都带 description，这个 description 就是给模型的说明书。模型收到工具的 JSON Schema 后，会先确认 module 字段应该填什么、默认的 style 是什么，再决定传参。

工具类本身的 docstring 也很关键。我会刻意写上“此工具从代码仓库提交记录和工单系统汇总变更，请勿用于查运行时性能数据”这类语义限定，帮助模型减少错误调用。

3.3 把“记忆”材料变成 MCP 资源

除了工具，MCP 的资源概念在文档自动化里极其有用。文档自动化有一类高频需求：基于旧文档生成新文档、总结变更要点、翻译更新。这些都需要模型“读取某份文件”，而读取行为本身，在 MCP 里被定义为资源读取。

资源设计要点：

• 每个资源都用一个 URI 标识，比如doc://source/2025/week01.md，模型需要在上下文中引用这个 URI，客户端再反向解析成真实路径。
• 资源可以带 MIME 类型，比如text/markdown、text/html、application/json。
• 服务端会返回资源的详细描述，包括行数、最近修改时间、内容摘要，这让模型在不读取全文的情况下就能判断“这份材料是否相关”。

我在系统里放了不少“摘要化资源”，服务端在资源层直接预生成摘要，模型不需要完整读入超长历史文档。这不仅省 token，还能规避长上下文导致的注意力漂移问题，生成新版本说明时质量和速度都好很多。

3.4 客户端接入：让模型自主编排文档生成流程

客户端部分，我建议文档自动化团队直接写一个轻量 Agent 循环，流程很简单：

1. 接收用户指令，例如“根据本周需求文档生成周报，并顺便对比上周周报”。
2. 向服务端拉取工具清单和资源清单，把所有描述注入系统 Prompt。
3. 模型生成第一个动作，比如read_resource("doc://source/week05_requirements.md")。
4. 客户端执行动作，返回内容。
5. 模型再生成下一个动作，直到产出最终的“周报结构”，客户端调用render_document工具把它渲染成文件。

真正实现时，最容易出错的是“模型试图一次完成太多动作”。我在系统里设置了一个约束：每轮只允许一个工具调用。这样做虽然多跑几轮交互，但每一步的决策都记录得清清楚楚，透明度反而更高。

3.5 让上下文累积成“决策轨迹”

这是我认为整个工作流里最重要的一环。MCP 每轮交互的请求和响应都是结构化的，我直接把它们追加写入一个决策轨迹文件：

{"step": 1, "action": "read_resource", "uri": "doc://source/week05_requirements.md", "ts": 1736092200} {"step": 2, "model_text": "找到需求文档中关于支付模块变更的描述，下一步查询关联缺陷单", "ts": 1736092200} {"step": 3, "action": "call_tool", "tool": "search_bug_by_keyword", "params": {"keyword": "支付超时", "productLine": "pay"}, "ts": 1736092201}

这份轨迹文件，比最终生成的文档值钱得多。内部复盘时，我可以指着第 2 行的模型输出说：模型自己判断“需要查询关联缺陷单”，然后才调用了搜索工具，这说明正向推理链路是通的。如果某个结论查无实据，我也能快速定位是检索漏了，还是模型决策时压根没走那一步。

注意：轨迹文件会包含内部业务关键词，甚至有些涉及个人信息，记得按公司数据分级规范脱敏存储，别把决策日志直接丢到公共日志平台。

4. 常见问题与排查技巧实录

4.1 模型不按协议走，描述写了大段还是乱调

我遇到过最典型的问题是：工具描述写了很大一段，模型却总是不传必填参数，或者把 style 填成枚举之外的值。

排查思路分三步：

第一步，确认 JSON Schema 是否被正确下发。很多框架默认额外包装一层参数，导致模型看到的 schema 是错的。直接在客户端打印出工具定义的原始 JSON，对照校验。

第二步，检查工具描述里是不是有“误导性词汇”。有次我把一个工具命名为get_recent_changes，描述里又提到“也可以用于查询历史数据”，结果模型动不动就选它去查老的线上事故，导致文档背景信息错误。后来把描述改成“仅返回最近 N 天数据，追溯更早请使用 archive_search”，错误率降了不少。

第三步，给模型提供“使用示例”。在工具描述末尾附一段“Example: changelog(module='payment', days=14, style='table')”，模型会模仿这个结构正确传参，比强行约束 prompt 有效得多。

4.2 上下文爆掉，工具描述被截断

MCP 服务端工具一多，工具清单的描述本身就可能吃掉大量上下文窗口。如果模型上下文窗口较小，客户端在组装协议消息时常常会自动截断尾部描述，结果就是模型对后面的工具完全无感知，只有前面的工具可用。

我用的解决方案是“分组暴露”：

• 服务端维护多个工具命名空间，类似doc_generation、doc_query、doc_render。
• 客户端根据任务预判，只向模型暴露与当前任务相关的命名空间。
• 模型在运行过程中发现需要额外工具时，可以发送tools/list请求再拉取。

这种“懒加载”方式，既控制住了上下文大小，又没有彻底牺牲工具的动态发现能力。实测在暴露二十多个工具的场景下，上下文从爆掉变成只消耗两三千 token，效率提升明显。

4.3 权限边界与数据安全，工具太开放

MCP 服务端权力极大，模型一旦被提示注入攻击，攻击者就能借模型之手随意读取内部资源。我的文档自动化系统里专门做了两层过滤：

第一层是“工具级白名单”，每个工作区只能绑定特定几个工具，比如生成版本说明的工作区不允许调用内部人员信息查询工具，从协议层面切断跨域数据流动。

第二层是 MCP 服务端内部的“资源必检”。任何资源 URI 必须经过路径规范化校验，防止../../穿越；另外文件读取必须有目录前缀白名单，模型读了开发文档目录，就不能顺手读运维密钥目录。

这些约束不需要改模型行为，只要在服务端设置合理的中间拦截即可。

4.4 Schema 升级引发的兼容性问题

MCP 工具入参是基于 JSON Schema 版本化的。项目迭代时，工具参数一变，老版本客户端缓存的 schema 就失效，模型拿着旧 schema 传参，服务端校验报错，整个自动化流程就断了。

我现在执行的规范是：

• 所有工具定义都带version字段，变更工具入参时先加新版本段，不覆写旧字段。
• 服务端同时支持v1和v2两种入参形态，内部做一层适配再统一处理。
• 给模型下发的工具描述里，会标注“如果可用，优先使用 params_v2”，模型通常都会照做。

这套兼容策略，让文档自动化服务从一周内崩溃零次变成了稳定运行三个月，极大的节省了维护成本。

5. 后续扩展：思维透明度的红利还能怎么吃？

5.1 从“输出文档”升级为“输出决策审计包”

文档自动化只是我用到的一个场景，MCP 的透明语义还能延伸更远。

我现在在尝试一种新玩法：模型每生成一个文档版本，我不仅输出文档本身，还打包生成一份“决策审计包”，包含工具调用链、检索命中片段、参数取值、模型中间推理解释。这张审计包直接打进文档的 metadata 里，后续查阅的人点开文档就能看到“为什么写这一段”的依据。

这在合规申报、项目验收、知识传承这些场景里价值极高。团队换人后，新成员看文档不再只看到结论，还能回放当时的完整思考过程，上手成本大幅降低。

5.2 多 Agent 协作时的互信机制

当多个 Agent 需要通过 MCP 协作生产文档时，自描述协议还能扮演“共识层”。A 模型负责写初稿，B 模型负责校对，C 模型负责排版。每个模型都以工具调用的形式请求他人产物，并把对方的输出当作结构化资源读入。

由于所有交互都来自标准协议，系统可以自动做“主张溯源”：B 模型说“A 模型生成的第三章引用数据与数据库统计不一致”时，审计系统直接对比 A 模型的调用记录和 B 模型的校验调用记录，谁对谁错一查便知。

这个方向上，MCP 已经不只是人机接口，而是成为机器与机器之间的“可审计对话语法”，思维透明度从单体模型拓展到了多体协商场景。

我在实际使用中的体会是：协议设计的威力，往往在写完功能很久之后才真正显露。当初给工具写那些冗长的 description，在被模型准确决策的那一刻兑现了价值；当初坚持把每一步工具调用落盘成轨迹文件，在出问题需要回溯的那天晚上救了整个项目。MCP 对文档自动化的意义，不全在于省事，而在于让模型每一次“思考”都变成了可以复查的证据。

这篇内容后续还可以这样扩展：把 MCP 的决策轨迹做成自动化看板，实时展示每个文档工单的生成状态；或者把服务端的工具调用统计接入质量指标，用数据驱动判断哪些文档场景适合完全托管给模型，哪些仍需人工审核。总之，把透明度的红利榨干，它自然会在项目里长出更多意想不到的价值。