在实际项目中我们经常需要将 AI 对话的成果转化为结构化的文档比如会议纪要、需求规格、API 文档或测试报告。手动整理不仅耗时而且格式难以统一。如果能将 AI 聊天直接变成一个文档生成引擎让 AI 根据对话内容自动输出格式规范、内容完整的文档将极大提升开发、产品、测试等角色的工作效率。本文将以 Claude、ChatGPT 等主流 AI 助手为例探讨如何利用现有工具和协议构建一个能够理解上下文、遵循模板、并输出多种格式文档的自动化流程。这个方案的核心在于让 AI 不仅回答问题还能扮演一个“文档工程师”的角色。我们将从理解文档生成的需求开始逐步介绍如何通过提示工程、外部工具集成如 MCP 服务器以及代码调用将一次性的对话输出转变为可重复、可配置的文档生成流水线。无论你是想为团队内部打造一个自动化文档工具还是希望在你的个人项目中集成智能文档生成能力本文提供的思路和实操步骤都将为你提供一个清晰的起点。1. 理解 AI 驱动的文档生成引擎在深入技术实现之前我们需要明确“将 AI 聊天变为文档生成引擎”究竟意味着什么。这不仅仅是让 AI 输出一段文字而是构建一个具备上下文感知、模板化输出和格式控制能力的系统。1.1 从对话到结构化文档的挑战普通的 AI 聊天是线性和即时的每次问答相对独立。而文档生成要求 AI 能够聚合信息从多轮对话中提取关键事实、决策和待办事项。理解结构遵循特定的文档模板如 Markdown 标题、表格、代码块。保持一致性确保术语、格式和风格在整个文档中统一。处理非文本元素生成或描述图表、序列图、表格数据等。直接要求 AI “把刚才的对话总结成文档”往往效果不佳因为 AI 缺乏对文档目标、受众和格式的事先约定。1.2 核心组件提示词、上下文与工具一个高效的文档生成引擎通常由三部分组成系统提示词System Prompt定义 AI 的“角色”和文档生成的任务目标。例如将其设定为“技术文档工程师”并告知需要生成的文档类型和基本规范。对话上下文管理需要将相关的历史对话有效地提供给 AI。这包括问题、答案、以及用户可能提供的示例片段。外部工具调用当 AI 需要访问外部数据如代码库、数据库 schema、API 定义或执行特定操作如格式化 JSON、绘制图表时需要通过工具调用接口来完成。Model Context Protocol (MCP) 正是为了标准化 AI 与外部工具/资源的交互而设计。1.3 典型工作流程一个完整的文档生成流程可以抽象为以下步骤触发用户通过特定命令如“生成 API 文档”或达到某个对话节点来触发生成任务。上下文收集系统收集当前及历史对话中与文档主题相关的消息。指令组装将系统提示词、收集到的上下文以及具体的文档模板要求组合成最终的请求。AI 处理与工具调用AI 模型处理请求在需要时通过 MCP 等服务调用工具获取额外信息。结果解析与输出解析 AI 返回的结构化内容如 Markdown并保存为文件.md, .pdf, .docx。2. 环境准备与核心工具选择构建文档生成引擎你可以选择不同的技术栈。下面我们以两种常见场景为例一种是基于 Claude Desktop 或 ChatGPT 客户端通过高级提示词和 MCP 进行增强另一种是通过 API 编程实现更自动化的流程。2.1 场景一基于 AI 桌面客户端的快速实践如果你希望快速体验不涉及复杂编程Claude Desktop 和具备高级功能的 ChatGPT 客户端是很好的起点。Claude Desktop作用官方桌面应用支持配置自定义提示词和集成 MCP 服务器能获得更长的上下文和更好的指令跟随能力。准备从 Anthropic 官网下载并安装。关注其更新以获取对 MCP 等最新特性的支持。ChatGPT高级版本如 ChatGPT Plus作用通过自定义指令Custom Instructions功能可以设定系统级的角色和行为准则影响所有对话。准备确保拥有相应账户权限。Visual Studio Code 与 Claude Code 扩展作用在 IDE 内直接获得 AI 辅助特别适合生成与代码相关的文档如代码注释、项目 README。Claude Code 扩展也支持一定程度的上下文交互。准备安装 VSCode并在扩展市场搜索安装 “Claude Code” 或类似 AI 编程助手扩展。注意工具和模型的可用性可能随地区和服务条款变化。请以官方最新公告和下载渠道为准。2.2 场景二基于 API 的自动化集成对于需要集成到 CI/CD、内部系统或需要批量处理的任务使用 API 是更可靠的方式。API 选择OpenAI API (GPT系列)接口稳定功能丰富适合通用文档生成。Anthropic API (Claude系列)在长上下文和指令遵循方面表现突出适合处理大型对话历史生成文档。国内大模型 API如果主要用户在国内可以考虑合规的国内大模型厂商提供的 API但需注意其指令跟随和长文本能力可能有所不同。开发环境Python推荐语言拥有丰富的 AI 和文本处理库openai,anthropic,langchain等。Node.js同样是不错的选择适合前端或全栈项目集成。关键库# Python 示例 pip install openai anthropic-python markdown pyyaml# Node.js 示例 npm install openai anthropic-ai sdk marked2.3 MCPModel Context Protocol的角色MCP 是一个新兴的协议旨在为 AI 模型提供一种标准化的方式来发现、调用外部工具和资源。在文档生成场景中MCP 服务器可以提供文件系统访问让 AI 读取项目中的模板文件、现有的文档或代码。数据库查询获取数据字典、表结构来生成数据模型文档。代码分析通过静态分析工具为生成 API 文档提供函数签名、参数信息。图形生成调用 Graphviz 或 Mermaid 等服务将 AI 描述的架构转化为图表代码。虽然直接配置 MCP 需要一定的开发工作但它代表了让 AI 更深度集成到工作流中的未来方向。你可以关注像codebuddy、playwright等工具社区是否提供了相关的 MCP 服务器实现。3. 构建你的第一个文档生成提示词系统一切始于提示词。一个好的系统提示词能将一个通用聊天 AI 转变为专业的文档生成引擎。3.1 设计系统提示词框架系统提示词应该清晰定义角色、任务、输出格式和规则。下面是一个用于生成“项目需求说明书”的提示词示例你是一个专业的产品经理和技术文档工程师。你的任务是根据与用户的对话生成一份结构完整、语言严谨的《软件需求规格说明书》。 请严格遵守以下规则 1. **角色固定**在整个对话中你只输出与文档生成相关的内容。如果用户问其他问题你可以礼貌地提醒他当前处于“文档生成模式”。 2. **主动澄清**如果对话中的需求描述存在模糊、矛盾或遗漏关键信息如用户角色、功能边界、非功能需求你必须主动提问直到信息明确。 3. **结构化输出**文档必须使用 Markdown 格式并包含以下章节 - 1. 项目概述背景、目标、范围 - 2. 用户角色与描述 - 3. 功能性需求按模块或用户故事列出包含优先级 - 4. 非功能性需求性能、安全、可用性等 - 5. 假设与约束条件 - 6. 待确定的议题 (TBD) 4. **引用对话**在文档中对于从对话中提取的具体需求点可以在括号内用简注说明来源例如“源自对话用户提及登录需支持第三方”。 5. **格式化**合理使用列表、表格、加粗、代码块等 Markdown 语法来增强可读性。 现在请开始分析当前的对话历史并生成需求文档。如果信息不足请向我提问。3.2 在 Claude Desktop 或 ChatGPT 中应用Claude Desktop通常可以在设置中找到配置“自定义提示词”Custom Instructions的地方将上述框架粘贴到“系统提示词”部分。ChatGPT 自定义指令在设置中开启“自定义指令”在“关于你的信息”或“你希望 ChatGPT 如何回复”的框中填入类似的角色和规则描述。应用后开启一个新对话AI 就会进入“文档生成模式”。3.3 通过对话引导 AI 完善文档提示词设定了规则但生成质量还依赖于你的输入。你需要像产品经理一样通过多轮对话“喂养”信息提供背景“我们正在开发一个内部任务管理系统用于替代现有的 Excel 表格。”描述用户“系统主要用户有三类项目经理创建项目、分配任务、团队成员查看任务、更新状态、部门领导查看报表。”阐述功能“核心功能包括项目管理CRUD、任务创建与分配、状态流转待处理、进行中、已完成、以及一个简单的仪表盘展示项目进度。”回答 AI 的澄清问题当 AI 问“状态流转是否有自动规则”时详细回答“没有自动规则全部由团队成员手动更新状态。”触发生成当信息觉得足够时说“请根据我们以上的讨论生成完整的需求规格说明书。”3.4 一个简单的 Python API 调用示例如果你选择编程实现以下是一个使用 OpenAI API 模拟上述流程的简化示例import openai import os # 设置你的 API 密钥 openai.api_key os.getenv(OPENAI_API_KEY) def generate_document(conversation_history, doc_typerequirement): 根据对话历史生成文档。 Args: conversation_history (list): 列表每个元素是一个字典包含 roleuser或assistant和 content。 doc_type (str): 文档类型用于选择不同的系统提示词模板。 Returns: str: 生成的 Markdown 格式文档。 # 根据文档类型选择系统提示词 system_prompts { requirement: 你是一个专业的产品经理...同上文提示词..., meeting_minutes: 你是一个专业的会议秘书...另一个提示词..., # 可以扩展更多模板 } system_prompt system_prompts.get(doc_type, system_prompts[requirement]) # 构造 API 请求消息 messages [{role: system, content: system_prompt}] messages.extend(conversation_history) # 将历史对话附加 messages.append({role: user, content: 请根据以上对话生成完整的文档。}) try: response openai.ChatCompletion.create( modelgpt-4, # 或 gpt-3.5-turbo messagesmessages, temperature0.2, # 低温度使输出更确定、更结构化 max_tokens2000 ) return response.choices[0].message.content except Exception as e: return f文档生成失败: {e} # 示例对话历史 history [ {role: user, content: 我们要做一个内部任务管理系统。}, {role: assistant, content: 好的请详细描述一下这个系统的背景和目标用户。}, {role: user, content: 用于替代部门目前用Excel管理项目任务的低效方式。用户有项目经理、团队成员和部门领导。}, {role: assistant, content: 明白了。请列举几个核心功能比如项目管理、任务分配等。}, {role: user, content: 核心功能包括项目管理增删改查、任务创建与分配、任务状态更新待处理、进行中、已完成、项目进度仪表盘。}, ] # 生成需求文档 generated_doc generate_document(history, requirement) print(generated_doc) # 可以将结果保存为文件 with open(需求规格说明书.md, w, encodingutf-8) as f: f.write(generated_doc)代码关键点解释system_prompts字典管理不同文档类型的模板便于扩展。temperature0.2较低的参数值使 AI 输出更稳定、更可预测适合格式化的文档生成。conversation_history需要你事先维护一个结构化的对话历史列表。在实际应用中这部分可以从聊天界面日志或数据库中获取。4. 实现模板化与动态内容注入基础提示词能生成结构但要使引擎更强大需要引入模板机制并将对话中的实体动态填充进去。4.1 设计 Markdown 模板创建一个模板文件template_meeting_minutes.md# 会议纪要 ## 会议基本信息 - **会议主题**: {{meeting_topic}} - **时间**: {{meeting_time}} - **地点**: {{meeting_location}} - **主持人**: {{host}} - **参会人**: {{participants}} ## 会议目标 {{meeting_goal}} ## 讨论要点 {{discussion_points}} ## 决议事项 | 序号 | 决议内容 | 负责人 | 截止日期 | |------|----------|--------|----------| {{decisions_table}} ## 后续行动计划 {{action_plan}} ## 待决议题 (TBD) {{tbd_items}}模板中的{{...}}是占位符。4.2 使用 AI 提取信息并填充模板编写一个函数先让 AI 从对话中提取结构化数据如 JSON然后用这些数据填充模板。import json import re def extract_structured_info_from_conversation(conversation_text): 使用 AI 从对话文本中提取结构化信息。 prompt f 请从以下会议对话记录中提取出结构化信息并以 JSON 格式返回。JSON 应包含以下字段 - meeting_topic (string) - meeting_time (string) - meeting_location (string) - host (string) - participants (list of strings) - meeting_goal (string) - discussion_points (list of strings, 每个要点一句话) - decisions (list of dicts, 每个dict包含 content, owner, deadline 字段) - action_plan (string) - tbd_items (list of strings) 对话记录 {conversation_text} 只返回 JSON 对象不要有其他任何解释。 # 调用 AI API (这里用伪代码表示) # response call_ai_api(prompt) # extracted_json parse_response_to_json(response) # 假设我们得到了以下模拟数据 extracted_json { meeting_topic: Q3 产品迭代规划会, meeting_time: 2023-10-27 14:00, meeting_location: 线上会议室, host: 张三, participants: [李四, 王五, 赵六], meeting_goal: 确定 Q3 核心功能优先级和排期, discussion_points: [ 回顾了 Q2 用户反馈登录流程优化是最高优先级。, 讨论了是否引入第三方身份验证决定先做内部优化。, 报表性能问题需在本季度解决。 ], decisions: [ {content: 优化登录流程减少步骤, owner: 李四, deadline: 2023-11-15}, {content: 重构后端报表查询接口, owner: 王五, deadline: 2023-11-30} ], action_plan: 李四和王五下周给出详细技术方案再次评审。, tbd_items: [第三方认证供应商选型] } return extracted_json def render_template(template_path, data): 使用提取的数据渲染模板。 with open(template_path, r, encodingutf-8) as f: template f.read() # 简单替换占位符 for key, value in data.items(): placeholder f{{{{{key}}}}} if isinstance(value, list): # 处理列表如参会人、讨论要点 if key decisions: # 特殊处理表格 table_rows for i, item in enumerate(value, 1): table_rows f| {i} | {item[content]} | {item[owner]} | {item[deadline]} |\n rendered_value table_rows else: rendered_value \n.join([f- {item} for item in value]) else: rendered_value str(value) template template.replace(placeholder, rendered_value) return template # 模拟对话文本 conversation_text 这里是完整的会议对话文字记录... # 1. 提取信息 structured_data extract_structured_info_from_conversation(conversation_text) # 2. 渲染模板 final_document render_template(template_meeting_minutes.md, structured_data) print(final_document)这种方法将文档生成分解为“信息提取”和“模板渲染”两步更可控也更容易调试。5. 集成外部工具与 MCP 进阶思路对于更复杂的文档如 API 文档需要代码分析、架构图需要生成图表代码需要 AI 调用外部工具。5.1 模拟工具调用模式即使没有真正的 MCP 服务器你也可以在提示词中定义“工具”并让 AI 以特定格式如 JSON请求数据然后由你的程序处理该请求并返回结果。系统提示词增强版你是一个技术文档生成引擎。你可以调用以下工具来获取信息 - get_code_structure: 获取某个代码文件的函数和类列表。 - query_database_schema: 查询数据库中某个表的字段定义。 - generate_mermaid_diagram: 根据描述生成 Mermaid 图表代码。 当你需要调用工具时请严格按照以下 JSON 格式输出 {tool: tool_name, parameters: {param1: value1}} 我会提供工具的执行结果。请基于结果继续文档生成工作。 现在请为项目 user_service 生成 API 文档。交互流程模拟AI 输出{tool: get_code_structure, parameters: {file_path: src/services/user_service.py}}你的后台程序解析这个 JSON调用一个真正的函数去分析user_service.py文件得到结果[class UserService, def create_user(...), def get_user(...), ...]你将结果以用户身份发给 AI“工具调用结果[class UserService, def create_user(...), def get_user(...), ...]”AI 根据代码结构继续编写 API 文档。5.2 利用现有工具生成图表对于图表可以引导 AI 输出 Mermaid、Graphviz DOT 或 PlantUML 等文本绘图语言然后使用相应渲染器生成图片插入文档。提示词示例...其他规则... 当需要描述系统架构或流程时请使用 Mermaid 语法例如 graph TD; A--B;来生成图表定义并将其包裹在 mermaid 代码块中。我会负责将其渲染为图片。在后期处理中你可以使用mermaid-cli命令行工具将代码块转换为 SVG 或 PNG 图片并替换文档中的代码块为图片链接。6. 常见问题、排查与优化策略6.1 文档生成质量不佳问题现象可能原因检查与解决思路内容空洞缺乏细节对话历史信息不足AI 无米下炊。1.检查输入提供给 AI 的对话历史是否包含了所有关键需求点2.主动引导在对话中以问答形式主动提供“谁、做什么、何时、何地、为什么、怎么做”等信息。3.提供范例在系统提示词中加入一个简短的理想输出示例。格式混乱不遵循模板系统提示词中对格式的约束力不够AI 模型能力有限。1.强化提示词在提示词中使用“必须”、“严格遵循”、“按以下顺序”等强指令词。明确列出章节标题。2.后处理清洗编写正则表达式或使用 Markdown 解析库如 Python 的markdown对 AI 输出进行格式化修正。3.尝试更强模型如从 GPT-3.5 切换到 GPT-4 或 Claude Opus。出现“幻觉”编造信息AI 倾向于补全信息当上下文不明确时可能虚构。1.要求引用来源在提示词中要求 AI 对关键结论注明“源自对话...”。2.设置低temperatureAPI 调用时降低temperature参数值如 0.1-0.3。3.分步验证先让 AI 提取事实列表JSON人工核对后再生成完整文档。6.2 性能与成本问题上下文过长如果对话历史非常长会导致 API 调用 token 数激增成本高且可能超出模型上下文窗口。解决方案实现一个“对话总结”步骤。先用 AI 对冗长对话进行摘要再将摘要作为上下文用于文档生成。响应缓慢复杂文档生成可能需要多次 AI 调用如先提取、再生成。解决方案对于固定流程考虑异步处理。将任务放入队列完成后通知用户。6.3 安全与合规考量敏感信息泄露对话历史和生成的文档可能包含代码、内部架构等敏感信息。最佳实践如果使用第三方 API确保你了解其数据使用政策。对于高度敏感信息考虑使用本地部署的模型或进行数据脱敏处理。内容审核生成的文档内容应符合公司规范。最佳实践在最终发布前加入人工审核环节。或设计一个基于关键词/规则的自动初筛机制。7. 生产环境最佳实践当文档生成引擎从个人玩具变为团队工具时需要考虑以下方面配置化管理将系统提示词、各类文档模板、API 密钥、模型参数等全部抽取到配置文件如config.yaml中便于管理和切换环境。日志与监控记录每一次文档生成的请求参数、消耗的 token 数、耗时以及最终输出或输出摘要。这有助于分析成本、优化提示词和排查问题。版本控制对提示词模板和渲染代码进行版本控制。当生成效果出现波动时可以快速回滚到之前的稳定版本。缓存策略对于相同的输入对话历史哈希可以直接返回已生成的文档避免重复调用 AI API节省成本和时间。降级方案当 AI 服务不可用时应有备选方案例如提供一个最基本的文本模板填充工具或者给出友好的错误提示。用户反馈闭环设计一个简单的“文档质量评分”或“问题反馈”机制。收集的反馈可以用来持续优化你的提示词和模板。将 AI 聊天转化为文档生成引擎本质上是将非结构化的对话流通过精心设计的规则、模板和外部工具规整为结构化的知识资产。成功的核心不在于寻找一个“万能提示词”而在于构建一个包含清晰角色定义、有效信息收集、结构化输出要求和必要工具调用的系统化流程。从定义一个明确的系统提示词开始逐步引入模板化和简单的外部数据集成你就能搭建起一个越来越强大的自动化文档助手。随着 MCP 等协议的发展未来 AI 与开发环境的结合将更紧密文档生成也会变得更加智能和上下文感知。
在实际项目中我们经常需要将 AI 对话的成果转化为结构化的文档比如会议纪要、需求规格、API 文档或测试报告。手动整理不仅耗时而且格式难以统一。如果能将 AI 聊天直接变成一个文档生成引擎让 AI 根据对话内容自动输出格式规范、内容完整的文档将极大提升开发、产品、测试等角色的工作效率。本文将以 Claude、ChatGPT 等主流 AI 助手为例探讨如何利用现有工具和协议构建一个能够理解上下文、遵循模板、并输出多种格式文档的自动化流程。这个方案的核心在于让 AI 不仅回答问题还能扮演一个“文档工程师”的角色。我们将从理解文档生成的需求开始逐步介绍如何通过提示工程、外部工具集成如 MCP 服务器以及代码调用将一次性的对话输出转变为可重复、可配置的文档生成流水线。无论你是想为团队内部打造一个自动化文档工具还是希望在你的个人项目中集成智能文档生成能力本文提供的思路和实操步骤都将为你提供一个清晰的起点。1. 理解 AI 驱动的文档生成引擎在深入技术实现之前我们需要明确“将 AI 聊天变为文档生成引擎”究竟意味着什么。这不仅仅是让 AI 输出一段文字而是构建一个具备上下文感知、模板化输出和格式控制能力的系统。1.1 从对话到结构化文档的挑战普通的 AI 聊天是线性和即时的每次问答相对独立。而文档生成要求 AI 能够聚合信息从多轮对话中提取关键事实、决策和待办事项。理解结构遵循特定的文档模板如 Markdown 标题、表格、代码块。保持一致性确保术语、格式和风格在整个文档中统一。处理非文本元素生成或描述图表、序列图、表格数据等。直接要求 AI “把刚才的对话总结成文档”往往效果不佳因为 AI 缺乏对文档目标、受众和格式的事先约定。1.2 核心组件提示词、上下文与工具一个高效的文档生成引擎通常由三部分组成系统提示词System Prompt定义 AI 的“角色”和文档生成的任务目标。例如将其设定为“技术文档工程师”并告知需要生成的文档类型和基本规范。对话上下文管理需要将相关的历史对话有效地提供给 AI。这包括问题、答案、以及用户可能提供的示例片段。外部工具调用当 AI 需要访问外部数据如代码库、数据库 schema、API 定义或执行特定操作如格式化 JSON、绘制图表时需要通过工具调用接口来完成。Model Context Protocol (MCP) 正是为了标准化 AI 与外部工具/资源的交互而设计。1.3 典型工作流程一个完整的文档生成流程可以抽象为以下步骤触发用户通过特定命令如“生成 API 文档”或达到某个对话节点来触发生成任务。上下文收集系统收集当前及历史对话中与文档主题相关的消息。指令组装将系统提示词、收集到的上下文以及具体的文档模板要求组合成最终的请求。AI 处理与工具调用AI 模型处理请求在需要时通过 MCP 等服务调用工具获取额外信息。结果解析与输出解析 AI 返回的结构化内容如 Markdown并保存为文件.md, .pdf, .docx。2. 环境准备与核心工具选择构建文档生成引擎你可以选择不同的技术栈。下面我们以两种常见场景为例一种是基于 Claude Desktop 或 ChatGPT 客户端通过高级提示词和 MCP 进行增强另一种是通过 API 编程实现更自动化的流程。2.1 场景一基于 AI 桌面客户端的快速实践如果你希望快速体验不涉及复杂编程Claude Desktop 和具备高级功能的 ChatGPT 客户端是很好的起点。Claude Desktop作用官方桌面应用支持配置自定义提示词和集成 MCP 服务器能获得更长的上下文和更好的指令跟随能力。准备从 Anthropic 官网下载并安装。关注其更新以获取对 MCP 等最新特性的支持。ChatGPT高级版本如 ChatGPT Plus作用通过自定义指令Custom Instructions功能可以设定系统级的角色和行为准则影响所有对话。准备确保拥有相应账户权限。Visual Studio Code 与 Claude Code 扩展作用在 IDE 内直接获得 AI 辅助特别适合生成与代码相关的文档如代码注释、项目 README。Claude Code 扩展也支持一定程度的上下文交互。准备安装 VSCode并在扩展市场搜索安装 “Claude Code” 或类似 AI 编程助手扩展。注意工具和模型的可用性可能随地区和服务条款变化。请以官方最新公告和下载渠道为准。2.2 场景二基于 API 的自动化集成对于需要集成到 CI/CD、内部系统或需要批量处理的任务使用 API 是更可靠的方式。API 选择OpenAI API (GPT系列)接口稳定功能丰富适合通用文档生成。Anthropic API (Claude系列)在长上下文和指令遵循方面表现突出适合处理大型对话历史生成文档。国内大模型 API如果主要用户在国内可以考虑合规的国内大模型厂商提供的 API但需注意其指令跟随和长文本能力可能有所不同。开发环境Python推荐语言拥有丰富的 AI 和文本处理库openai,anthropic,langchain等。Node.js同样是不错的选择适合前端或全栈项目集成。关键库# Python 示例 pip install openai anthropic-python markdown pyyaml# Node.js 示例 npm install openai anthropic-ai sdk marked2.3 MCPModel Context Protocol的角色MCP 是一个新兴的协议旨在为 AI 模型提供一种标准化的方式来发现、调用外部工具和资源。在文档生成场景中MCP 服务器可以提供文件系统访问让 AI 读取项目中的模板文件、现有的文档或代码。数据库查询获取数据字典、表结构来生成数据模型文档。代码分析通过静态分析工具为生成 API 文档提供函数签名、参数信息。图形生成调用 Graphviz 或 Mermaid 等服务将 AI 描述的架构转化为图表代码。虽然直接配置 MCP 需要一定的开发工作但它代表了让 AI 更深度集成到工作流中的未来方向。你可以关注像codebuddy、playwright等工具社区是否提供了相关的 MCP 服务器实现。3. 构建你的第一个文档生成提示词系统一切始于提示词。一个好的系统提示词能将一个通用聊天 AI 转变为专业的文档生成引擎。3.1 设计系统提示词框架系统提示词应该清晰定义角色、任务、输出格式和规则。下面是一个用于生成“项目需求说明书”的提示词示例你是一个专业的产品经理和技术文档工程师。你的任务是根据与用户的对话生成一份结构完整、语言严谨的《软件需求规格说明书》。 请严格遵守以下规则 1. **角色固定**在整个对话中你只输出与文档生成相关的内容。如果用户问其他问题你可以礼貌地提醒他当前处于“文档生成模式”。 2. **主动澄清**如果对话中的需求描述存在模糊、矛盾或遗漏关键信息如用户角色、功能边界、非功能需求你必须主动提问直到信息明确。 3. **结构化输出**文档必须使用 Markdown 格式并包含以下章节 - 1. 项目概述背景、目标、范围 - 2. 用户角色与描述 - 3. 功能性需求按模块或用户故事列出包含优先级 - 4. 非功能性需求性能、安全、可用性等 - 5. 假设与约束条件 - 6. 待确定的议题 (TBD) 4. **引用对话**在文档中对于从对话中提取的具体需求点可以在括号内用简注说明来源例如“源自对话用户提及登录需支持第三方”。 5. **格式化**合理使用列表、表格、加粗、代码块等 Markdown 语法来增强可读性。 现在请开始分析当前的对话历史并生成需求文档。如果信息不足请向我提问。3.2 在 Claude Desktop 或 ChatGPT 中应用Claude Desktop通常可以在设置中找到配置“自定义提示词”Custom Instructions的地方将上述框架粘贴到“系统提示词”部分。ChatGPT 自定义指令在设置中开启“自定义指令”在“关于你的信息”或“你希望 ChatGPT 如何回复”的框中填入类似的角色和规则描述。应用后开启一个新对话AI 就会进入“文档生成模式”。3.3 通过对话引导 AI 完善文档提示词设定了规则但生成质量还依赖于你的输入。你需要像产品经理一样通过多轮对话“喂养”信息提供背景“我们正在开发一个内部任务管理系统用于替代现有的 Excel 表格。”描述用户“系统主要用户有三类项目经理创建项目、分配任务、团队成员查看任务、更新状态、部门领导查看报表。”阐述功能“核心功能包括项目管理CRUD、任务创建与分配、状态流转待处理、进行中、已完成、以及一个简单的仪表盘展示项目进度。”回答 AI 的澄清问题当 AI 问“状态流转是否有自动规则”时详细回答“没有自动规则全部由团队成员手动更新状态。”触发生成当信息觉得足够时说“请根据我们以上的讨论生成完整的需求规格说明书。”3.4 一个简单的 Python API 调用示例如果你选择编程实现以下是一个使用 OpenAI API 模拟上述流程的简化示例import openai import os # 设置你的 API 密钥 openai.api_key os.getenv(OPENAI_API_KEY) def generate_document(conversation_history, doc_typerequirement): 根据对话历史生成文档。 Args: conversation_history (list): 列表每个元素是一个字典包含 roleuser或assistant和 content。 doc_type (str): 文档类型用于选择不同的系统提示词模板。 Returns: str: 生成的 Markdown 格式文档。 # 根据文档类型选择系统提示词 system_prompts { requirement: 你是一个专业的产品经理...同上文提示词..., meeting_minutes: 你是一个专业的会议秘书...另一个提示词..., # 可以扩展更多模板 } system_prompt system_prompts.get(doc_type, system_prompts[requirement]) # 构造 API 请求消息 messages [{role: system, content: system_prompt}] messages.extend(conversation_history) # 将历史对话附加 messages.append({role: user, content: 请根据以上对话生成完整的文档。}) try: response openai.ChatCompletion.create( modelgpt-4, # 或 gpt-3.5-turbo messagesmessages, temperature0.2, # 低温度使输出更确定、更结构化 max_tokens2000 ) return response.choices[0].message.content except Exception as e: return f文档生成失败: {e} # 示例对话历史 history [ {role: user, content: 我们要做一个内部任务管理系统。}, {role: assistant, content: 好的请详细描述一下这个系统的背景和目标用户。}, {role: user, content: 用于替代部门目前用Excel管理项目任务的低效方式。用户有项目经理、团队成员和部门领导。}, {role: assistant, content: 明白了。请列举几个核心功能比如项目管理、任务分配等。}, {role: user, content: 核心功能包括项目管理增删改查、任务创建与分配、任务状态更新待处理、进行中、已完成、项目进度仪表盘。}, ] # 生成需求文档 generated_doc generate_document(history, requirement) print(generated_doc) # 可以将结果保存为文件 with open(需求规格说明书.md, w, encodingutf-8) as f: f.write(generated_doc)代码关键点解释system_prompts字典管理不同文档类型的模板便于扩展。temperature0.2较低的参数值使 AI 输出更稳定、更可预测适合格式化的文档生成。conversation_history需要你事先维护一个结构化的对话历史列表。在实际应用中这部分可以从聊天界面日志或数据库中获取。4. 实现模板化与动态内容注入基础提示词能生成结构但要使引擎更强大需要引入模板机制并将对话中的实体动态填充进去。4.1 设计 Markdown 模板创建一个模板文件template_meeting_minutes.md# 会议纪要 ## 会议基本信息 - **会议主题**: {{meeting_topic}} - **时间**: {{meeting_time}} - **地点**: {{meeting_location}} - **主持人**: {{host}} - **参会人**: {{participants}} ## 会议目标 {{meeting_goal}} ## 讨论要点 {{discussion_points}} ## 决议事项 | 序号 | 决议内容 | 负责人 | 截止日期 | |------|----------|--------|----------| {{decisions_table}} ## 后续行动计划 {{action_plan}} ## 待决议题 (TBD) {{tbd_items}}模板中的{{...}}是占位符。4.2 使用 AI 提取信息并填充模板编写一个函数先让 AI 从对话中提取结构化数据如 JSON然后用这些数据填充模板。import json import re def extract_structured_info_from_conversation(conversation_text): 使用 AI 从对话文本中提取结构化信息。 prompt f 请从以下会议对话记录中提取出结构化信息并以 JSON 格式返回。JSON 应包含以下字段 - meeting_topic (string) - meeting_time (string) - meeting_location (string) - host (string) - participants (list of strings) - meeting_goal (string) - discussion_points (list of strings, 每个要点一句话) - decisions (list of dicts, 每个dict包含 content, owner, deadline 字段) - action_plan (string) - tbd_items (list of strings) 对话记录 {conversation_text} 只返回 JSON 对象不要有其他任何解释。 # 调用 AI API (这里用伪代码表示) # response call_ai_api(prompt) # extracted_json parse_response_to_json(response) # 假设我们得到了以下模拟数据 extracted_json { meeting_topic: Q3 产品迭代规划会, meeting_time: 2023-10-27 14:00, meeting_location: 线上会议室, host: 张三, participants: [李四, 王五, 赵六], meeting_goal: 确定 Q3 核心功能优先级和排期, discussion_points: [ 回顾了 Q2 用户反馈登录流程优化是最高优先级。, 讨论了是否引入第三方身份验证决定先做内部优化。, 报表性能问题需在本季度解决。 ], decisions: [ {content: 优化登录流程减少步骤, owner: 李四, deadline: 2023-11-15}, {content: 重构后端报表查询接口, owner: 王五, deadline: 2023-11-30} ], action_plan: 李四和王五下周给出详细技术方案再次评审。, tbd_items: [第三方认证供应商选型] } return extracted_json def render_template(template_path, data): 使用提取的数据渲染模板。 with open(template_path, r, encodingutf-8) as f: template f.read() # 简单替换占位符 for key, value in data.items(): placeholder f{{{{{key}}}}} if isinstance(value, list): # 处理列表如参会人、讨论要点 if key decisions: # 特殊处理表格 table_rows for i, item in enumerate(value, 1): table_rows f| {i} | {item[content]} | {item[owner]} | {item[deadline]} |\n rendered_value table_rows else: rendered_value \n.join([f- {item} for item in value]) else: rendered_value str(value) template template.replace(placeholder, rendered_value) return template # 模拟对话文本 conversation_text 这里是完整的会议对话文字记录... # 1. 提取信息 structured_data extract_structured_info_from_conversation(conversation_text) # 2. 渲染模板 final_document render_template(template_meeting_minutes.md, structured_data) print(final_document)这种方法将文档生成分解为“信息提取”和“模板渲染”两步更可控也更容易调试。5. 集成外部工具与 MCP 进阶思路对于更复杂的文档如 API 文档需要代码分析、架构图需要生成图表代码需要 AI 调用外部工具。5.1 模拟工具调用模式即使没有真正的 MCP 服务器你也可以在提示词中定义“工具”并让 AI 以特定格式如 JSON请求数据然后由你的程序处理该请求并返回结果。系统提示词增强版你是一个技术文档生成引擎。你可以调用以下工具来获取信息 - get_code_structure: 获取某个代码文件的函数和类列表。 - query_database_schema: 查询数据库中某个表的字段定义。 - generate_mermaid_diagram: 根据描述生成 Mermaid 图表代码。 当你需要调用工具时请严格按照以下 JSON 格式输出 {tool: tool_name, parameters: {param1: value1}} 我会提供工具的执行结果。请基于结果继续文档生成工作。 现在请为项目 user_service 生成 API 文档。交互流程模拟AI 输出{tool: get_code_structure, parameters: {file_path: src/services/user_service.py}}你的后台程序解析这个 JSON调用一个真正的函数去分析user_service.py文件得到结果[class UserService, def create_user(...), def get_user(...), ...]你将结果以用户身份发给 AI“工具调用结果[class UserService, def create_user(...), def get_user(...), ...]”AI 根据代码结构继续编写 API 文档。5.2 利用现有工具生成图表对于图表可以引导 AI 输出 Mermaid、Graphviz DOT 或 PlantUML 等文本绘图语言然后使用相应渲染器生成图片插入文档。提示词示例...其他规则... 当需要描述系统架构或流程时请使用 Mermaid 语法例如 graph TD; A--B;来生成图表定义并将其包裹在 mermaid 代码块中。我会负责将其渲染为图片。在后期处理中你可以使用mermaid-cli命令行工具将代码块转换为 SVG 或 PNG 图片并替换文档中的代码块为图片链接。6. 常见问题、排查与优化策略6.1 文档生成质量不佳问题现象可能原因检查与解决思路内容空洞缺乏细节对话历史信息不足AI 无米下炊。1.检查输入提供给 AI 的对话历史是否包含了所有关键需求点2.主动引导在对话中以问答形式主动提供“谁、做什么、何时、何地、为什么、怎么做”等信息。3.提供范例在系统提示词中加入一个简短的理想输出示例。格式混乱不遵循模板系统提示词中对格式的约束力不够AI 模型能力有限。1.强化提示词在提示词中使用“必须”、“严格遵循”、“按以下顺序”等强指令词。明确列出章节标题。2.后处理清洗编写正则表达式或使用 Markdown 解析库如 Python 的markdown对 AI 输出进行格式化修正。3.尝试更强模型如从 GPT-3.5 切换到 GPT-4 或 Claude Opus。出现“幻觉”编造信息AI 倾向于补全信息当上下文不明确时可能虚构。1.要求引用来源在提示词中要求 AI 对关键结论注明“源自对话...”。2.设置低temperatureAPI 调用时降低temperature参数值如 0.1-0.3。3.分步验证先让 AI 提取事实列表JSON人工核对后再生成完整文档。6.2 性能与成本问题上下文过长如果对话历史非常长会导致 API 调用 token 数激增成本高且可能超出模型上下文窗口。解决方案实现一个“对话总结”步骤。先用 AI 对冗长对话进行摘要再将摘要作为上下文用于文档生成。响应缓慢复杂文档生成可能需要多次 AI 调用如先提取、再生成。解决方案对于固定流程考虑异步处理。将任务放入队列完成后通知用户。6.3 安全与合规考量敏感信息泄露对话历史和生成的文档可能包含代码、内部架构等敏感信息。最佳实践如果使用第三方 API确保你了解其数据使用政策。对于高度敏感信息考虑使用本地部署的模型或进行数据脱敏处理。内容审核生成的文档内容应符合公司规范。最佳实践在最终发布前加入人工审核环节。或设计一个基于关键词/规则的自动初筛机制。7. 生产环境最佳实践当文档生成引擎从个人玩具变为团队工具时需要考虑以下方面配置化管理将系统提示词、各类文档模板、API 密钥、模型参数等全部抽取到配置文件如config.yaml中便于管理和切换环境。日志与监控记录每一次文档生成的请求参数、消耗的 token 数、耗时以及最终输出或输出摘要。这有助于分析成本、优化提示词和排查问题。版本控制对提示词模板和渲染代码进行版本控制。当生成效果出现波动时可以快速回滚到之前的稳定版本。缓存策略对于相同的输入对话历史哈希可以直接返回已生成的文档避免重复调用 AI API节省成本和时间。降级方案当 AI 服务不可用时应有备选方案例如提供一个最基本的文本模板填充工具或者给出友好的错误提示。用户反馈闭环设计一个简单的“文档质量评分”或“问题反馈”机制。收集的反馈可以用来持续优化你的提示词和模板。将 AI 聊天转化为文档生成引擎本质上是将非结构化的对话流通过精心设计的规则、模板和外部工具规整为结构化的知识资产。成功的核心不在于寻找一个“万能提示词”而在于构建一个包含清晰角色定义、有效信息收集、结构化输出要求和必要工具调用的系统化流程。从定义一个明确的系统提示词开始逐步引入模板化和简单的外部数据集成你就能搭建起一个越来越强大的自动化文档助手。随着 MCP 等协议的发展未来 AI 与开发环境的结合将更紧密文档生成也会变得更加智能和上下文感知。
