ChatGPT审稿实战：从零构建高效技术文档自动化审核系统

1次阅读

共计 2653 个字符，预计需要花费 7 分钟才能阅读完成。

技术文档审稿一直是开发过程中容易被忽视但极其耗时的环节。经过多次项目实践，我总结了以下几个典型痛点：

重复性工作量大：每次文档更新都需要人工检查格式规范（如标题层级、代码块格式）、术语一致性（如 ”Python” 不能写成 ”python”）、以及拼写错误等基础问题。这些工作占据了审稿人 60% 以上的时间。
技术逻辑验证困难：当文档涉及复杂的技术方案描述时，人工审稿往往难以发现前后矛盾的逻辑表述。例如 API 文档中对同一参数的描述可能在不同章节出现不一致的情况。
变更追踪成本高：在多分支协作的文档开发中，很难直观比较不同版本间的具体修改点。Git 的 diff 功能对非代码文本的支持有限，特别是当修改涉及段落重组时。

sequenceDiagram
    participant 用户
    participant 预处理器
    participant ChatGPT
    participant 规则引擎
    participant 输出模块

    用户 ->> 预处理器: 上传文档.md
    预处理器 ->> 规则引擎: 应用基础规则过滤
    规则引擎 -->> 预处理器: 触发规则列表
    预处理器 ->>ChatGPT: 发送带 Prompt 的请求
    ChatGPT-->> 预处理器: 返回 JSON 结果
    预处理器 ->> 输出模块: 生成带批注的文档
    输出模块 -->> 用户: 返回审阅报告

规则引擎：
基础层使用正则表达式处理硬性规则（如强制术语表）
上层通过自定义 DSL 实现可配置的复杂规则（示例：if 出现 "TensorFlow" then 必须包含版本号）
Prompt 模板：
采用三段式结构：角色定义 + 技术上下文 + 具体指令

示例技术上下文注入方法：

你是一名资深 Python 工程师，熟悉 PEP8 规范。当前文档涉及 Django 4.2 和 PostgreSQL 14 的技术栈。特别注意："async" 必须完整写成 "asynchronous"

差异比对：
基于 git diff --word-diff 实现细粒度变更定位
对移动的段落采用 Levenshtein 距离匹配

灵活性：普通 Lint 工具只能处理静态规则，而我们的系统可以理解技术文档的语义上下文
学习成本：不需要像 SonarQube 那样维护复杂规则集
迭代速度：通过修改 Prompt 即可快速调整审核策略

import openai
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def chatgpt_review(text: str, prompt_template: str) -> dict:
    """ 带重试机制的 API 调用

    Args:
        text: 待审阅文本
        prompt_template: 已注入上下文的 Prompt 模板

    Returns:
        OpenAI API 的完整响应 JSON
    """
    try:
        response = openai.ChatCompletion.create(
            model="gpt-4",
            messages=[{"role": "system", "content": prompt_template},
                     {"role": "user", "content": text}],
            temperature=0.3
        )
        return response
    except Exception as e:
        print(f"API 调用失败: {str(e)}")
        raise

请以技术文档审核专家身份检查以下内容：核心要求：1. 所有 Python 关键字必须保持小写（print/import 等）2. "JSON" 必须全大写，禁止使用 "json"
3. 发现任何过时的 API 用法请特别标注

输出格式要求：{
  "issues": [{"line": 行号, "type": "术语 | 格式 | 逻辑", "comment": "具体问题描述"}
  ]
}

from typing import List, Dict
import json

def parse_result(raw_response: dict) -> List[Dict[str, str]]:
    """ 处理 API 返回的评审意见

    Args:
        raw_response: OpenAI API 返回的原始 JSON

    Returns:
        标准化的问题列表
    """
    try:
        content = raw_response["choices"][0]["message"]["content"]
        result = json.loads(content)

        # 验证数据格式
        if not isinstance(result.get("issues"), list):
            raise ValueError("Invalid response format")

        return result["issues"]
    except (KeyError, json.JSONDecodeError) as e:
        print(f"结果解析失败: {str(e)}")
        return []