对话即代码：用编译时优化实现稳定的AI文档生成

不知道你有没有过这种经历：跟AI聊了十分钟，得到一份看起来不错的文档，但第二天想改其中一个数据，又得把整个对话重新来一遍，而且这次生成的结果跟上次完全不一样，连章节标题都换了。我最近一直在折腾一个偏实操的项目，核心就是想解决这个“生成的随机性”问题。项目里我搭了两个模块，一个叫WordBuddy，一个叫AI导出鸭。WordBuddy负责对话模板和上下文管理，AI导出鸭负责把生成结果导出成Word文档。整套思路说白了就是把AI对话当成代码来管理，在“编译期”把问题提前解决掉，而不是等文档生成完再手动修修补补。这套方案我实际用下来，最大的感受就是：文档生成的稳定性提升非常明显，而且整个流程可以像代码一样被版本管理、复用、测试。

如果你平时需要频繁用AI生成技术周报、方案初稿、知识库文档，或者被“AI生成一时爽，改起来火葬场”折磨过，这篇文章应该对你有用。我会把我自己搭这套管线时踩过的坑、用到的设计思路、以及可执行的配置都写出来，尽量让你能照着落地。

1. 为什么把对话当代码，而不是当聊天

1.1 “对话即代码”要解决的真实问题

先聊一个很常见的场景：你让AI帮你写一份技术方案，它写得不错，但里面有个技术选型写错了，你手动改掉。改完发现另一个章节里还有一个相关的地方没改，因为那段内容是在后面生成的，它根本没记住前面改了什么。再往后，你又想换一种语气重写，结果整篇结构全乱了。这是所有对话式AI的通病——模型本身没有“记忆”，它只有上下文窗口里的那几万token，而你在窗口之外做的任何修改，它都感知不到。

我刚开始做这个项目的时候，用的就是最朴素的“直接对话”方式。但很快发现，对话式生成有三个很难忍的问题：

第一，不可复现。同一个问题，早上问和下午问，结果往往不一样。对写代码来说，不能复现的构建是不可接受的。对写文档来说，不能复现意味着你没法得到一个稳定的基线。

第二，不可组合。今天写了一段周报，明天想在同样的框架下生成一个不同类型的项目总结，就得重新从零开始设计提示词，之前积累的好的prompt片段、好的示例全浪费了。

第三，不可校验。对话没有边界，你让AI输出一个JSON对象，它经常给你带一段解释；你让它列五个要点，它给你列六个。没有校验机制，这些错误只有到了下游处理才会暴露。

于是我就把编译器设计思路搬过来：把一次完整的文档生成，拆成“源码——中间表示——目标代码”三段。这里的“源码”是一套写好的任务定义文件，包含提示词模板、输入参数声明、输出格式声明、示例样本；“中间表示”是模型返回的结构化JSON；“目标代码”是最终导出的Word文档。WordBuddy负责前两段，AI导出鸭负责最后一段。这样做的好处是，每一层的输入输出都是定义好的，哪一层出问题就修哪一层，不会一团乱麻。

1.2 编译时优化比运行时优化到底强在哪儿

编译器里有个概念叫编译时优化。比如C++里很多表达式在编译期就能算出结果，编译器会提前替换成常量，而不是留到运行时再算；再比如类型检查，函数参数传错了，编译期直接报错，根本不会让你跑到线上才崩溃。这套思想用在AI文档生成上，就是我们说的“编译时优化”。

所谓“运行时优化”，就是先把AI生成的内容拿出来，再通过后续加工来补救。比如生成完后发现JSON解析失败，用正则硬把代码块提出来；比如输出少了字段，让AI“续写补上”；比如排版乱了，人工去Word里调。这些不是不行，但每次都在跟模型的随机性对抗，成本很高。

更好的做法是把约束前移：在调用模型之前，把所有能提前检查、裁剪、限制的事情都做完。

• 参数校验前置：在渲染提示词之前先检查输入参数是否合法，必填字段缺失就直接报错，而不是等模型生成一个莫名其妙的答案。
• 上下文裁剪前置：只把当前任务真正需要的上下文片段拼进提示词，而不是把整段历史对话都丢给模型。
• 示例筛选前置：从示例库里动态挑选与当前任务最匹配的两三个示例，而不是几十个示例全部塞进去。
• 输出格式声明前置：在提示词里告诉模型“你必须返回一个JSON，且结构必须符合给定的Schema”，从源头降低解析失败概率。
• 自检规则前置：模型生成完后，自动对关键字段做非空校验、枚举校验、长度校验，不合格就触发重试。

我用一个生活化的类比来理解：把AI当成一个刚入职的实习生。你直接跟他说“去写一份项目周报”，他可能会给你写出一篇抒情散文。但如果你提前给他一个表格模板，告诉他第一栏填什么、第二栏填什么、每栏最多多少字、遇到不确定的地方写“待确认”，他交回来的东西基本就能直接用。这就是编译时优化和运行时优化的差别：一个是提前把话说清楚，一个是拿到乱写的答案再逼着他改，效率完全不在一个量级。

1.3 WordBuddy和AI导出鸭的分工逻辑

这个项目里，WordBuddy和AI导出鸭并不是什么现成的开源软件，而是我自己给两个模块起的代号。WordBuddy负责“对话前”和“对话中”的管理，AI导出鸭负责“对话后”的导出。它们的交集是一个定义好的JSON结构，可以理解成编译器的中间表示（IR）。

WordBuddy做的事情包括：读取任务定义YAML、校验用户输入、渲染提示词模板、维护对话状态、调用大模型接口、解析模型返回内容、校验输出结构。它的设计原则很简单：所有关于“怎么跟模型说话”的细节，都配置化，不要硬编码在代码里。

AI导出鸭做的事情更纯粹：接收结构化的JSON数据，按照模板映射成Word文档。它不关心模型是谁，也不关心提示词怎么写的，只关心一件事——把JSON里的内容变成排版正确的docx文件。

这个分层逻辑跟编译器的前后端设计非常像。前端（WordBuddy）把用户意图变成中间表示，后端（AI导出鸭）把中间表示变成可交付的产物。只要中间表示稳定，前端可以换不同的模型（GPT、Claude、本地模型都可以），后端也可以换不同的导出格式（Word、PDF、Markdown），两者互不影响。

我在动手写代码前，先用这个方法把整体流程画了一遍（不是用那种复杂的流程图，就是在纸上写了几行字）：任务定义 -> 输入校验 -> 渲染提示词 -> 模型调用 -> 输出解析 -> 输出校验 -> JSON中间结果 -> 导出docx。后面所有开发都是围绕这条链路展开，每一个环节的输入输出都有明确的Schema，出了问题很容易定位。

2. WordBuddy核心模块解析与实操要点

2.1 对话任务模板引擎：用YAML定义一切

WordBuddy的第一个核心能力是任务模板引擎。一个“对话任务”不是一段孤零零的提示词，而是一个完整的YAML文件，里面定义了任务名称、输入字段、提示词模板、示例样本、输出Schema和重试策略。

下面是一个简化版的技术周报任务定义，可以直接参考：

task_name: weekly_report description: 根据项目进展生成技术周报 input_schema: type: object properties: project_name: type: string description: 项目名称 progress_items: type: array items: type: string description: 本周完成事项 next_plan: type: array items: type: string description: 下周计划 required: - project_name - progress_items prompt_template: | 你是一名资深技术负责人，请根据以下信息生成一份技术周报。 项目名称：{{ project_name }} 本周完成事项： {% for item in progress_items %} - {{ item }} {% endfor %} 下周计划： {% for item in next_plan %} - {{ item }} {% endfor %} 请严格按照下面的JSON结构返回，不要输出任何解释或Markdown代码块标记： { "summary": "本周总结，100字以内", "highlights": ["亮点1", "亮点2"], "risks": ["风险1", "风险2"], "next_plan": ["计划1", "计划2"] } few_shot_examples: - input: project_name: "数据中台" progress_items: - "完成数据同步任务的重试机制" - "修复指标计算任务的内存溢出" next_plan: - "推进数据质量监控模块开发" output: summary: "本周主要完成数据同步重试机制和指标计算内存溢出修复，同步推进数据质量监控模块的开发准备。" highlights: - "数据同步任务稳定性明显提升" - "定位并修复长期存在的内存溢出问题" risks: - "数据质量监控模块依赖底层表结构变更，需协调数据组排期" next_plan: - "完成数据质量监控模块的接口设计" output_schema: type: object properties: summary: type: string maxLength: 200 highlights: type: array maxItems: 5 risks: type: array maxItems: 5 next_plan: type: array minItems: 1 maxItems: 10 required: - summary - highlights - risks - next_plan retry_policy: max_retries: 2 temperature_on_retry: 0.2

为什么用YAML而不是直接在Python代码里写字符串拼接？因为任务定义本质上是一个配置，它的变更频率比代码高得多。运营人员想调整提示词措辞，不需要碰代码，只需要改这个YAML文件。而且YAML文件可以被Git管理，每一次提示词的改动都有历史记录，哪次效果变好了，可以轻松对比。

这里有个实操细节需要注意：提示词模板本身必须和输出Schema放在同一个文件里。很多人喜欢把prompt存在一个文件，把Schema存在另一个文件，结果改prompt的时候忘记同步改Schema，模型输出和下游解析对不上。把它们放在一起，每一次改动都是原子性的。

模板引擎我推荐用Jinja2，因为它的语法大部分人比较熟悉，而且支持过滤器。渲染的时候注意，模型对“输出格式”部分非常敏感，所以我在模板里把“必须返回JSON”这句话重复了三遍，并且在示例中明确展示了完整JSON的样子。实测下来，这种方式比在系统提示词里写一大段“你是一个AI助手，请严格按照JSON格式输出”效果要好得多。

2.2 生成前校验：让错误死在摇篮里

WordBuddy的第二个核心能力是“编译时检查”。这个检查分为两层：第一层是输入校验，第二层是输出校验。输入校验发生在渲染提示词之前，输出校验发生在模型返回之后。

输入校验我用的是JSON Schema标准库，Python里可以直接用jsonschema这个库。校验规则通常在任务定义里用一个input_schema字段声明，比如必填字段、字符串长度、枚举值、数组元素类型等等。这样用户传参一旦不合法，代码立刻报错，根本不会浪费一次模型调用。

举个例子，我有个任务是用来生成SQL优化建议的，它要求输入的SQL语句不能超过2000个字符，数据库类型只能是MySQL、PostgreSQL、SQLite其中之一。如果用户传入一个MongoDB的参数，代码在渲染提示词之前就会抛出一个明确的异常，而不是让模型去猜“这个数据库类型应该怎么处理”。这个前置校验帮我省下了大量排查时间。

输出校验同样依赖JSON Schema，但和输入校验不同的是，输出校验失败后不能直接抛错，而是要走重试流程。因为模型本身有随机性，一次生成不合法并不代表模型能力不行，可能只是这次没按格式来。重试时我会把错误信息拼接到提示词里，告诉模型“你上次返回的结构不符合要求，缺少了xxx字段，请重新生成”。实测下来，带错误信息的第二次重试，成功率能到95%以上。

这里有一个非常关键的实操细节：输出Schema里的required字段一定要写全，不要觉得有些字段不重要就省略。AI导出鸭在导出Word时，很多内容都是遍历JSON动态生成的，如果某个字段缺失，导出脚本会报KeyError，反而打断整个流程。宁可让模型多生成一个冗余字段，也不要让它少生成一个必要字段。

2.3 上下文管理：不是所有内容都该喂给模型

上下文管理是WordBuddy里最容易被忽视、但影响最大的模块。很多人在对话式AI里习惯把历史消息一股脑全传给模型，觉得这样模型才能“记住上下文”。但实际测试下来，上下文越长，模型越容易在细节上出错，而且生成的内容会变得越来越泛化，缺乏针对性。

我的做法是把对话限制在“单轮任务型”模式。什么意思？就是每次调用模型只完成一个明确任务，不依赖历史对话。比如生成技术周报，我需要把用户输入的“本周完成事项”和“下周计划”直接渲染进提示词，而不是先跟模型聊一大堆背景，再让它总结。这样模型每次看到的都是完整、干净、自包含的输入，输出质量会比多轮对话稳定得多。

如果确实需要参考长文档，比如让AI根据一份几十页的技术方案生成摘要，我不会把整份方案塞进上下文，而是先在文档侧做预处理：用文本抽取的方法把关键章节标题、首段、加粗文字提取出来，再把这些片段作为上下文输入。这样既保留了核心信息，又控制了上下文长度。这个方法我给它起了个名字叫“上下文裁剪”，本质上就是把不需要模型关心的细节挡在上下文窗口之外。

few-shot示例的筛选也需要动态化。当示例库变大之后，不能每次都把所有示例塞进去。我给每个示例打上标签，比如“周报类型”“方案类型”“SQL优化类型”，输入进来后先做一次简单的规则匹配，只选择最相关的两到三个示例。这个做法的收益很明显：示例越少，模型注意力越集中；示例越相关，格式学习越准确。

还有一个经验是，在提示词里让模型分步骤思考，但不让它把思考过程输出。比如生成技术方案时，我会在提示词里写“请先分析需求背景，再设计架构，最后写实施步骤”，但明确要求最终输出只包含结构化JSON字段。这样做模型内部会有条理，而外部输出还是干净的，不会被“推理过程”污染。

2.4 AI导出鸭的Word导出：中间JSON是唯一的真相

到了AI导出鸭这一层，事情反而简单了。因为前面的中间JSON已经把内容都结构化好了，导出模块只需要做一件事：把JSON映射到Word里的标题、段落、表格和列表。

我测试过两条导出路径。第一条是简单路径：把JSON序列化成Markdown，再用pandoc转成docx。优点是快，缺点是对复杂样式控制力弱，比如中文字体、页边距、表格宽度这些小细节很难统一调整。第二条是精细路径：直接用python-docx遍历JSON构建文档，把每个字段对应到指定的样式上。字段名叫summary就生成正文段落，叫highlights就生成项目符号列表，叫table_data就生成表格。优点是可定制性强，缺点是要写更多代码。

实际项目中，我大部分时间走的是第二条路径。下面是我常用的导出代码片段，核心逻辑就是递归遍历字典，根据字段名决定用哪种样式：

from docx import Document from docx.shared import Pt from docx.enum.text import WD_ALIGN_PARAGRAPH def add_paragraph_with_style(doc, text, style_name, font_size=None, bold=False): p = doc.add_paragraph(style=style_name) run = p.add_run(text) run.font.size = Pt(font_size) if font_size else run.font.size run.bold = bold return p def json_to_docx(data, output_path): doc = Document() # 设置中文字体，避免默认字体不支持中文 doc.styles['Normal'].font.name = 'Calibri' doc.styles['Normal']._element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑') if 'title' in data: doc.add_heading(data['title'], level=0) if 'summary' in data: add_paragraph_with_style(doc, data['summary'], 'Intense Quote') if 'highlights' in data and isinstance(data['highlights'], list): for item in data['highlights']: doc.add_paragraph(item, style='List Bullet') if 'risks' in data and isinstance(data['risks'], list): add_paragraph_with_style(doc, '风险与问题', 'Heading 1') for item in data['risks']: doc.add_paragraph(item, style='List Bullet') if 'next_plan' in data and isinstance(data['next_plan'], list): add_paragraph_with_style(doc, '后续计划', 'Heading 1') for item in data['next_plan']: doc.add_paragraph(item, style='List Number') doc.save(output_path)

这里有一个特别容易踩的坑：如果不显式设置中文字体，python-docx生成的Word文档在中文环境里默认字体可能是Calibri，导致中文字符显示异常。上面代码里我通过设置w:eastAsia属性把中文字体指定为微软雅黑，这个问题就没了。另外，标题级别一定要统一，不要一会儿用Heading 1，一会儿用Heading 2，否则导出后目录结构会乱。我一般会在任务定义里就约定好：summary是正文摘要，highlights是列表，risks是列表，next_plan是编号列表，所有二级标题由导出模块自动生成，不依赖模型返回的标题文本。

3. 从零跑通一个完整实操流程

3.1 环境准备与模块构建

开始动手之前，先把环境准备好。因为我用的WordBuddy和AI导出鸭都是基于Python实现的，所以默认大家有Python 3.10+的环境。如果你没有，建议先装一个Miniconda或者直接用系统自带的Python都行。

项目目录结构我推荐这样组织：

project/ ├── tasks/ # 所有任务定义的YAML文件 │ ├── weekly_report.yaml │ └── tech_solution.yaml ├── wordbuddy/ # 对话管理与生成模块 │ ├── validator.py │ ├── renderer.py │ ├── llm_client.py │ └── pipeline.py ├── ai_exporter/ # 导出模块 │ ├── docx_exporter.py │ └── styles.py ├── output/ # 生成的文档输出目录 └── requirements.txt

我看网上有人在搜“wordbuddy下载”，这里说明一下：这两个模块目前没有现成的官方安装包，我是从GitHub上拉下来自己构建的。实际操作中，你完全可以不用这个名字，自己建一个目录叫conversation_core也行。核心不是名字，而是模块设计思路：把对话任务配置、模型调用、导出逻辑彼此解耦。

依赖安装很简单，写一个requirements.txt：

jsonschema>=4.18.0 jinja2>=3.1.2 openai>=1.30.0 python-docx>=1.1.0 pyyaml>=6.0.1

然后执行：

pip install -r requirements.txt

这里说句实在话，别一上来就追求“下载一个完整软件”，这种工具链最好是按自己的项目需求搭，因为每个团队要生成的文档结构都不一样，现成工具很难完全匹配。我把模块构建完成了，后面要加一个新任务类型，只需要往tasks/目录里丢一个新的YAML文件，完全不用改代码。

3.2 定义一个可复用的技术周报任务

前面2.1里已经给过一份YAML定义，这里我讲一下用它跑通全流程时要注意的细节。

定义任务时，最重要的一件事是：输入字段别贪多。比如周报任务，真正必需的输入就是项目名称、本周完成事项、下周计划这三维信息。如果你把“参与人员”“客户反馈”“风险登记册”这些也设为必填，每次生成前的准备成本就太高了，大家很快就不愿意用了。我自己的习惯是，核心必填字段控制在五个以内，其余字段都设为可选，模型在输出时对缺失字段自动写“待确认”。

提示词模板里的“角色设定”也很关键。我测试过，把“你是一名资深技术负责人”放在第一句，比放在后面对输出质量的影响更大。角色设定要具体到“这个人会怎么看问题”，而不只是“你是一个助手”。比如写周报，我会设定成“你是一名在大厂带过多个项目团队的技术负责人，你的周报读者是部门总监，他们关心进度、风险和资源协调”。这样模型产出的话术就会更贴合实际汇报场景。

few-shot示例不需要多，但一定要“精”。原则是：示例的输入特征要和真实输入尽量接近。我那个周报示例，特意选了“数据中台”这个项目名，因为我的真实周报里大部分都是数据工程相关的项目。如果真实输入是“CRM系统重构”，示例里全是“数据中台”，模型可能会在输出里不自觉地带上数据中台相关的技术名词。所以我通常会有两到三套周报示例，按项目类型动态选择。

3.3 生成、解析、校验、重试全流程

定义好任务之后，执行流程就非常机械了。写一个pipeline函数，按顺序走完整条链路：

import yaml import json from jsonschema import validate, ValidationError from jinja2 import Template def run_task(task_file, user_input): # 1. 加载任务定义 with open(task_file, 'r', encoding='utf-8') as f: task = yaml.safe_load(f) # 2. 输入校验（编译时检查第一层） validate(instance=user_input, schema=task['input_schema']) # 3. 渲染提示词 template = Template(task['prompt_template']) prompt = template.render(**user_input, examples=task.get('few_shot_examples', [])) # 4. 调用模型（这里以OpenAI接口为例，可替换） response = llm_client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": prompt}], temperature=0.3, ) raw_content = response.choices[0].message.content # 5. 解析模型输出（去掉可能的Markdown代码块标记） raw_content = raw_content.strip() if raw_content.startswith("```"): raw_content = raw_content.split("\n", 1)[1].rsplit("```", 1)[0].strip() # 6. 输出校验 try: result = json.loads(raw_content) validate(instance=result, schema=task['output_schema']) except (json.JSONDecodeError, ValidationError) as e: # 7. 重试：把错误信息带回提示词 retry_prompt = prompt + f"\n\n注意：你上次输出的JSON格式不符合要求，错误信息：{e}，请重新生成。" response = llm_client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": retry_prompt}], temperature=0.2, ) raw_content = response.choices[0].message.content result = json.loads(raw_content) validate(instance=result, schema=task['output_schema']) return result

这段代码虽然不复杂，但已经覆盖了“编译时优化”的重要思想：输入校验失败不调用模型；输出校验失败带错误信息重试。注意重试温度我调低了，从0.3降到0.2，因为出错之后我们希望模型更收敛，而不是更发散。

实测下来，这个流程最大的收益不是“一次成功”，而是“出错后可定位”。如果用户在配置里漏了必填字段，错误信息会直接告诉他是哪个字段没传，而不是让他看着模型瞎编的内容一头雾水。

3.4 导出Word并做最终检查

生成完JSON中间结果后，把它传给AI导出鸭的导出函数，这一步基本不涉及模型能力，纯粹是工程活。

from ai_exporter.docx_exporter import json_to_docx result = run_task('tasks/weekly_report.yaml', user_input) json_to_docx(result, 'output/weekly_report.docx')

导出后建议用python-docx把文档重新读取一遍，做一个自动化冒烟检查。我会检查这几个点：文档是否包含至少一个非空段落；标题层级是否连续（没有从一级直接跳到三级）；表格列数是否一致。这些都可以写成自动校验脚本，集成到导出流程的最后一步。

这个自动化检查帮我发现过一个很隐蔽的Bug：当模型返回的highlights列表为空时，AI导出鸭会直接跳过这个章节，导致Word里漏了一块内容。后来我在导出函数里加了个规则：如果某个必填章节的列表为空，也要生成一个占位段落，内容是“待补充”，而不是让整个章节消失。这样文档结构始终保持完整，读者也能一眼看出哪里还没填。

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

4.1 模型输出JSON总是不合法

这是最容易遇到的情况，尤其是用开源模型的时候。表现是：模型返回的内容外围包着Markdown代码块，或者里面混着解释性文字，又或者字段名带了引号但值没带引号，直接json.loads就崩。

我的处理方式分三层：

• 第一层：在提示词里专门加一句“不要输出任何解释或Markdown代码块标记”，这句话通常能把八成的问题挡掉。
• 第二层：解析时先做一次预处理。如果字符串以```开头，就剥离首尾代码块标记；如果里面混着额外的文字，尝试用正则提取第一个{到最后一个}之间的内容。
• 第三层：如果预处理后还是解析失败，就进入重试流程，把解析异常信息拼回提示词。

还有一个通用补救技巧：如果解析时遇到单引号代替双引号、尾逗号这类非标准JSON语法，可以用json5库或者demjson3来解析。但注意这只能作为“运行时修复”兜底，不能当成常规手段。编译时优化做得好的人，不会指望靠这些后处理来过日子。

4.2 生成的Word样式错乱

最常见的原因是模型返回的字段内容和预期不一致。比如我让模型在highlights里最多返回五个字符串，结果它返回的是一段长文本，AI导出鸭里用List Bullet样式渲染之后，整段全变成了一个超长列表项，非常难看。

解决办法是在提示词里把字段的约束写得非常明确，比如“highlights必须是字符串数组，每个元素不得超过30个字，最多五个元素”。同时输出Schema里也做了maxItems和maxLength的校验。双重约束下，模型基本不会再犯这个问题。

还有一个样式问题跟Word自身有关：如果文档既有标题样式又有手动加粗的文本，生成的目录会识别不到手动加粗的“标题”。所以导出时所有标题都必须用Word的Heading样式，不能只是把字体调大加粗。

4.3 上下文太长导致内容发散或编造

我在实测中遇到过几次，问题是：用户输入的不是简洁的“本周完成事项”，而是把整个项目文档粘贴进来，希望AI自动提取。结果模型确实提取了，但把很多无关细节也当成“亮点”输出，整个周报显得非常发散。

后来我在输入Schema里对数组元素做了长度限制：每个“完成事项”最多150个字。同时在任务提示词里加了一句“只总结与项目进展直接相关的内容，不要扩展背景信息”。这个约束一加，输出质量立刻稳定了很多。

如果场景确实是“长文档摘要”，我建议在WordBuddy外单独做一个文档预处理模块，先提取关键章节和重要段落，再把预处理结果传给任务模板。不要把“长文档摘要”和“结构化周报生成”塞进同一个任务里，两个任务的prompt设计逻辑完全不同，强行合在一起只会互相干扰。

4.4 快速问题排查表

4.5 一些额外的避坑心得

第一，给prompt做版本管理，跟代码一起走CI。我在项目里把tasks/目录纳入Git，每次调完prompt就提交一次，还在commit message里写清楚改动原因。后来有一次发现某个改动导致输出质量全面下降，直接用git revert回滚到上一个版本，几秒钟就恢复了，不用靠记忆重新调prompt。

第二，不要在一个任务里塞太多目标。我最初贪心，想在一个提示词里同时让模型“总结周报、输出风险、给出下周计划、生成一段发给领导的摘要”。结果就是每个目标都完成得平庸。后来我把“周报正文”和“领导摘要”拆成了两个任务，各自训练各自的few-shot，效果立刻好了很多。编译器里的函数要么做一件事，要么做很多事但依赖注入清晰，AI提示词也是一样的道理。

第三，温度设置不是越低越好。很多人觉得温度调成0就是最稳的，但我实测某些场景下温度太低，模型会陷入机械重复，甚至把示例里的句子原样抄过来。我自己默认是0.3，重试时降到0.2，这样既有一定多样性，又不会太飘。

第四，保留每次生成的原始快照。每次生成的JSON中间结果和最终docx都按时间戳存到输出目录，方便事后对比。有一次用户反馈某份文档里有个数据错了，我直接翻出当时的快照，定位到是输入参数传错了，而不是模型编造，省去了一大堆无用的排查。

最后说几句实在话

我把这套“对话即代码”的管线跑通之后，最大的感触是：真正拖慢效率的不是AI不会写，而是没有一套能稳定复现的框架。以前我总是在生成完之后想办法“修”，现在我把所有能提前约束的事情全部前移，反而需要修的少了。WordBuddy和AI导出鸭这两个模块，一个负责让AI在干净的环境里干活，一个负责把干完的活变成标准交付物，中间夹着一个结构严谨的JSON契约，整条链路的可维护性非常高。

如果你也想照着这个思路折腾，我的建议是别贪多，先挑一个高频、边界清楚的小场景，比如“技术周报自动生成”或者“简单方案初稿生成”，把这段管线完整跑通。跑通之后你自然会知道哪里需要加校验、哪里需要调样式、哪里需要改prompt，然后再往外扩展下一步。工具和方案永远是越用越顺手的，但这套“把对话当代码”的核心思想，无论换什么模型、换什么文档格式，都值得保留。