工程实践篇难度 3⏱ 12 分钟概念
01Harness Engineering（Agent 生产化工程）
围绕 Agent 构建可运行、可治理、可扩展生产系统的工程方法
Harness EngineeringAgent生产化可观测性评估护栏
更新于 2026-04-12harness-engineering
用 LLM 从代码自动生成注释、API 文档和更新日志，解决文档滞后和风格不统一问题
内容摘要
AI 辅助文档生成，是指利用大语言模型（LLM，Large Language Model）分析代码的结构和语义，自动产出代码注释、API 接口文档、版本更新日志（CHANGELOG）等技术文档的工程实践。
AI 辅助文档生成，是指利用大语言模型（LLM，Large Language Model）分析代码的结构和语义，自动产出代码注释、API 接口文档、版本更新日志（CHANGELOG）等技术文档的工程实践。
传统软件开发中，文档编写有三个老大难问题：文档跟不上代码变化（一改代码忘改文档）、手写文档太慢（几百个接口全靠手敲）、不同人写的文档风格不统一（有的详细有的敷衍）。AI 辅助文档生成的核心思路是——让 LLM 充当"自动文档员"，它读懂代码后直接输出初稿，开发者只需审核和微调，而不是从零开始写。
与传统的模板填空式文档工具不同，LLM 能理解代码的逻辑意图，而不仅仅是机械提取函数名和参数列表。例如，它能从一个函数的异常处理代码中推断出"这个函数在输入为空时会报错"，并主动写进文档里。
AI 辅助文档生成的完整链路可以拆成四个核心环节：
| 环节 | 作用 | 说明 |
|---|---|---|
| 代码解析 | 提取结构化信息 | 从源码中提取函数签名、参数类型、返回值、异常等 |
| 上下文融合 | 补充语义信息 | 结合注释、测试用例、Git 提交消息等多源信息 |
| LLM 生成 | 产出文档初稿 | 根据 Prompt（提示词）和目标格式生成文档内容 |
| 审查反馈 | 质量把关 | 自动校验 + 人工审核，确保准确后合并 |
通过 AST（Abstract Syntax Tree，抽象语法树）解析器或语言服务器，从代码中提取函数名、参数列表、类型注解（Type Hints）、返回类型、异常抛出等结构化信息。这一步的产出是机器可读的"代码骨架"，为后续 LLM 生成提供精确输入。
单看代码本身信息有限。这一步将多个信息源汇总：
Optional[List[User]] 这类类型信息暗示"可能为空"融合多源信息后，LLM 生成的文档质量远高于只看代码本身。
将解析结果和上下文打包成 Prompt，发给 LLM，指定目标文档格式（如 NumPy Docstring、Javadoc、OpenAPI 等）。LLM 根据代码逻辑和上下文，输出符合格式要求的文档初稿。
生成的文档并非直接可用。需要经过：
AI 辅助文档生成的核心机制分三步：
关键判断发生在 Prompt 构造阶段——不同类型的文档需要不同的 Prompt 策略。生成 Docstring 时侧重参数说明和异常处理；生成 CHANGELOG 时侧重变更分类和影响范围；生成 API 文档时侧重请求参数和响应格式。
这套机制能解决文档滞后问题的根本原因是：代码变更本身就是触发文档更新的信号。通过 CI/CD 集成，每次代码提交都可以自动触发文档重新生成。
以下用 Python + OpenAI API 演示最小文档生成流程：从一个函数自动生成 NumPy 风格的 Docstring。
# 基于 openai==1.30.0 验证（截至 2026-03）
import ast
import inspect
from openai import OpenAI
def extract_func_info(source: str) -> dict:
"""从函数源码中提取签名信息"""
tree = ast.parse(source)
func = tree.body[0] # 取第一个函数定义
params = [arg.arg for arg in func.args.args if arg.arg != 'self']
return {"name": func.name, "params": params, "source": source}
def generate_docstring(func_info: dict) -> str:
"""调用 LLM 生成 NumPy 风格 Docstring"""
client = OpenAI() # 从环境变量读取 OPENAI_API_KEY
prompt = f"""为以下函数生成 NumPy 风格的 Docstring，包含 Parameters、Returns、Raises、Examples。
函数名: {func_info['name']}
参数: {func_info['params']}
源码:
{func_info['source']}
只返回 Docstring 内容。"""
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "你是 Python 文档生成助手，输出 NumPy 风格 Docstring。"},
{"role": "user", "content": prompt}
],
temperature=0.3
)
return resp.choices[0].message.content
# ---- 使用示例 ----
sample_code = '''
def calculate_discount(price: float, rate: float) -> float:
if rate < 0 or rate > 1:
raise ValueError("折扣率必须在 0-1 之间")
return price * (1 - rate)
'''
info = extract_func_info(sample_code.strip())
docstring = generate_docstring(info)
print(docstring)
extract_func_info 用 ast 模块做最小化的代码解析；generate_docstring 将解析结果打包成 Prompt 发给 LLM。实际工程中会额外融合测试用例和 Git 信息，并加入自动校验步骤。
| 概念 | 与 AI 辅助文档生成的区别 | 更适合关注的重点 |
|---|---|---|
| 代码补全（Code Completion） | 代码补全生成的是代码本身，文档生成的产出是说明性文字 | 写代码时的实时建议 |
| 静态分析工具（Linter/Type Checker） | 静态分析检查代码是否符合规范，不生成文档内容 | 代码质量和类型安全 |
| API 网关文档（如 Swagger UI） | 只展示接口定义，不能自动生成业务描述和使用示例 | 接口的结构化展示和调试 |
核心区别：
| 常见误区 | 正确理解 |
|---|---|
| AI 生成的文档可以直接用，不需要审核 | AI 输出的是初稿，尤其是业务逻辑描述和边界条件说明，必须经开发者确认后才能合并 |
| 有了 AI 文档生成就不用手写文档了 | Docstring 和 API 文档可以大幅自动化，但设计文档、架构决策说明仍需人工撰写 |
| 只要把代码扔给 AI 就能出好文档 | 代码本身的质量（命名规范、类型注解、合理注释）直接影响生成质量，烂代码出不了好文档 |
| CHANGELOG 自动生成不需要提交规范 | 自动 CHANGELOG 依赖规范化的 Git 提交消息（如 Conventional Commits），乱写的 commit message 生成不出有用的日志 |
参考答案：
四个环节：代码解析、上下文融合、LLM 生成、审查反馈。上下文融合通过引入单元测试、Git 提交消息、已有注释等多源信息，能补充代码本身无法表达的业务意图和使用场景，让 LLM 生成的文档更准确、更完整。
参考答案：
至少做三件事：(1) 统一代码的类型注解（Type Hints），让 AI 能准确识别参数和返回类型；(2) 确定目标 Docstring 格式（Google/NumPy/Sphinx），在 Prompt 中明确指定；(3) 准备几个高质量的 Docstring 示例作为 Few-shot（少样本学习），让 LLM 学习目标风格。此外，建立 PR 审核流程，确保生成的文档经过人工确认后才合并。
参考答案：
优势：文档与代码始终同步，消除手动维护的滞后问题；新增/修改的函数自动获得文档更新。风险：(1) LLM 幻觉可能引入不准确的描述，如果没有审核环节就直接合并到主分支会造成误导；(2) 每次提交都调 LLM API 会增加构建时间和成本，建议只对有变更的文件触发生成；(3) 需要设计好回退机制，当生成质量异常时能快速恢复。推荐做法：AI 生成的文档以 PR 形式提交，经人工审核后再合并。
优先展示同分类且标签更接近的内容，方便继续串联学习。
围绕 Agent 构建可运行、可治理、可扩展生产系统的工程方法
通过缓存、模型路由、上下文压缩等手段降低 Agent 应用的 LLM 调用成本
系统化评估 Agent 多轮对话中连贯性、意图理解和上下文保持能力的测试方法体系。