代码讲解智能体
构建一个能够读取源文件、请求 LLM 进行讲解并返回 Markdown 文档的智能体。
代码讲解智能体 是 CoddyKit 上的免费 AI Agents 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
项目目标
构建一个代理，接收源文件（Python、JS 或其他文件），并返回 Markdown 文档，包括用途、主要函数和使用示例。
为什么有用？
从代码生成文档是最可靠的 LLM 使用场景之一——代码具有结构，任务范围明确，而且输出由人阅读（因此可以容忍小错误）。
架构
- 读取源文件
- 可选：按类/函数进行拆分
- 针对每个分块，提示 LLM 进行解释
- 合并为 Markdown 文档
Step 1: Read the File
import sys
with open('example.py', 'w') as f:
f.write('print("hello")\n')
path = sys.argv[1] if len(sys.argv) > 1 else 'example.py'
with open(path) as f:
code = f.read()
print(f'Read {len(code)} characters from {path}')Step 2: Prompt for Documentation
from openai import OpenAI
oai = OpenAI()
prompt = f'''
You are a senior engineer writing developer-friendly docs.
Given this source file, produce a Markdown document with:
# {path}
## Purpose
(One paragraph)
## Public API
(Each function/class with one-line description)
## Usage Example
(One short, runnable snippet)
Source:
```
{code}
```
'''
response = oai.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': prompt}],
temperature=0.2,
)
print(response.choices[0].message.content)处理长文件
如果文件过长，请按函数拆分，并分别进行解释：
import ast
tree = ast.parse(code)
functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]
for func in functions:
snippet = ast.unparse(func)
explain(snippet)步骤 3：合并输出
对于多分块运行，请将每个函数的解释拼接成一个文档：
docs = []
for func_name, snippet in functions:
explanation = explain(snippet)
docs.append(f'### {func_name}\n\n{explanation}\n')
full_doc = '\n'.join(docs)
open('docs.md', 'w').write(full_doc)添加项目级摘要
完成各函数的解释后，请要求 LLM 提供高层概览：
summary_prompt = 'Summarise the purpose of this package in 3 sentences, given these function docs:\n\n' + full_doc
summary = ask(summary_prompt)多语言
同一个提示词也适用于 JS、Go、Rust 等语言。为了获得更好的结果，请将语言添加到提示词中：
prompt = f'You are documenting {language} code. ...'基于差异的文档
对于增量更新，只需对发生变化的文件重新运行：
import subprocess
changed = subprocess.check_output(['git', 'diff', '--name-only', 'HEAD~1']).decode().splitlines()
for path in changed:
if path.endswith('.py'):
regenerate_doc(path)使用工具运行示例
验证 LLM 提供的使用示例确实能够运行——为代理提供一个 Python REPL 工具：
def run_python(code):
try:
exec(code, {})
return {'stdout': 'ok', 'stderr': ''}
except Exception as e:
return {'stdout': '', 'stderr': str(e)}
tools = [{'name': 'run_python', 'description': 'Execute a Python snippet and return stdout/stderr', 'parameters': {'code': 'str'}}]
broken_example = 'print(1/0)'
result = run_python(broken_example)
if result['stderr']:
print('Example failed:', result['stderr'])
fixed_example = 'print(1)'
result = run_python(fixed_example)
print('Self-corrected result:', result)
else:
print('Example ran fine:', result)
代理产生幻觉时
模型有时会捏造函数或参数。应对方法包括：
- 只提供文件内容（不提供模型记忆）
- 将温度设为 0
- 加入验证步骤（运行示例、检查代码片段）
将其产品化
将其封装为 CLI：
# pip install -e .
# docgen src/myproject/agent.py
# Outputs docs.md从工具接入 CI
接入 CI：每次 PR 时，为发生变化的文件重新生成文档，并将文档提交回仓库。这样，您的代码仓库就始终有完整文档。
为什么要读取整个文件？
为什么要将完整源文件传给 LLM，而不是只传函数签名？
回顾
一个 30 行代码的代理，就能将代码转换为文档。还可以轻松添加工具和验证功能。这是继 RAG 之后非常适合的第二个项目。
常见问题解答
「代码讲解智能体」课时是免费的吗？
是的 — 「代码讲解智能体」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。
「代码讲解智能体」这节课中我会学到什么？
构建一个能够读取源文件、请求 LLM 进行讲解并返回 Markdown 文档的智能体。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 AI Agents 需要有经验吗？
无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「代码讲解智能体」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 AI Agents 课中编写并运行代码吗？
能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。