用纯 Python 搭一个发布说明智能体
文章用生成发布说明的案例演示智能体如何在目标和约束下规划、调用工具并校验结果,同时比较固定工作流与智能体的适用场景。后续讨论评估、安全护栏、可观测性、成本和延迟。
AI 深度解读
把代码贴进聊天框、拿到答案、跑一遍验证,再把报错贴回去,这套流程里负责查资料、决定下一步和判断能否交付的人始终是你。原文用一个 Python 发布说明脚本演示,怎么把这些工作交给程序,让它自己推进到一份可供审阅的草稿。
作者的建议是从固定流程做起,只有执行路径确实无法预先写定时,才让模型决定下一步。对前端和全栈开发者来说,最容易借用的是它的验收顺序:能用代码查的先查,需要理解语义的再交给模型,最后由人决定是否发布。
什么时候才需要模型决定下一步
作者给了一个判断方法:把人从过程里抽掉,系统还能走到一个可审阅的结果吗?如果每次都得有人手动补文档、转贴命令输出、判断该不该重试,聊天工具只是替你写了其中一段。要让系统接手,就得把目标、工具、验收条件和停止规则写进程序。
能事先列出步骤的任务,适合用固定工作流(workflow)。比如发布说明可以按提取事实、检查事实、起草、审阅的顺序走。输入类型不同就先分类再分流,互不依赖的任务可以并行。如果连子任务有几个、涉及哪些文件都得看完输入才知道,才考虑让一个模型拆任务,再交给多个工作调用处理。只要有清楚的评分规则,也可以单独加一个审阅调用,在固定轮数内修改草稿。
模型发出的工具调用请求,由宿主代码决定是否执行。工具结果回来后,模型可以据此改变下一步。作者的原型让草稿阶段最多跑 MAX_STEPS = 6 步,通过 call_model 接收 tool_call 或 final 两种 JSON 响应,只从 TOOLS 里查找可执行工具。作者还建议优先使用供应商支持的原生工具调用和类型化参数,并给整次运行设时间和费用上限。示例代码实现了步数上限,超时和费用上限留给接入方。
发布说明先过代码检查,再交给模型审阅
原文给出的验收样例是为 2.4 版生成 Markdown,分成 Added、Changed、Fixed、Removed 四节,每条一句并附对应 PR 链接,内容须有提交记录支撑,最多 400 个词。脚本通过 git log <since_tag>..HEAD --pretty=format:%h %s 取短哈希和提交标题,另提供一个 read_file(path),读取 docs/ 下的文本时最多返回 20000 个字符。
下面的 check_release_notes 用于检查必备小节、词数上限和草稿里引用的提交哈希。
def check_release_notes(text: str, commit_lines: str) -> list[str]:
issues = []
required = ["## Added", "## Changed", "## Fixed", "## Removed"]
for heading in required:
if heading not in text:
issues.append(f"Missing section: {heading}")
if len(text.split()) > 400:
issues.append("Over 400 words")
known_hashes = {line.split()[0] for line in commit_lines.splitlines() if line.strip()}
cited = set(re.findall(r"\b[0-9a-f]{7,}\b", text))
unknown = cited - known_hashes
if unknown:
issues.append(f"References commits not in the log: {sorted(unknown)}")
return issues
留意 unknown = cited - known_hashes 这一行。它能找出草稿里出现却不在日志中的哈希,但草稿一个哈希都没写也能过这一项,PR 链接同样没有被校验。
代码检查通过后,独立的 review 调用拿提交记录和草稿逐项比对,判断每条是否有依据、有无遗漏重要改动、句式和分组是否符合要求。审阅器返回无法解析的 JSON 时,代码把结果判为未通过。接下来这段代码负责限次修改并落盘。
MAX_REVISIONS = 2
def release_notes(since_tag: str, call_model) -> str:
commits = git_log(since_tag)
goal = f"Write release notes for changes since {since_tag}. Use git_log first."
draft = run_agent(goal, call_model)
for attempt in range(MAX_REVISIONS + 1):
issues = check_release_notes(draft, commits)
if not issues:
verdict = review(draft, commits, call_model)
if verdict.get("pass"):
break
issues = verdict.get("issues", [])
if attempt == MAX_REVISIONS:
draft = "NEEDS HUMAN REVIEW\n\nOpen issues:\n- " + "\n- ".join(issues) + "\n\n" + draft
break
revision_goal = (
f"Revise these release notes. Fix only these issues:\n- "
+ "\n- ".join(issues)
+ f"\n\nCURRENT DRAFT:\n{draft}"
)
draft = run_agent(revision_goal, call_model)
with open("RELEASE_NOTES.draft.md", "w", encoding="utf-8") as f:
f.write(draft)
return "RELEASE_NOTES.draft.md"
留意写入 RELEASE_NOTES.draft.md 的那一行。即使两轮修改后仍未通过,流程也会把待解决的问题放到草稿顶部,再交给人处理。提交、打标签和发布都由人完成。
单次通过以后,怎么知道改动有用
一次运行中的检查回答「这份草稿能交给人看了吗」。评估集(evals)回答的是「换了模型、提示词或工具后,整套流程变好了吗」。作者建议取 10 到 30 个真实历史案例,把旧标签、提交列表和人工批准的发布说明一起保存。每次改动后重跑,比较规则通过率、首稿返修率、人工编辑距离,以及每次运行的成本和步数。
模型也可以参与评估,但作者提醒,模型可能偏爱较长的答案和接近自身风格的写法。给它具体的是非题,要求每个判断都能指回来源,再抽样跟人审对照,比让它打 1 到 10 分更容易定位分歧。运行时则记录运行 ID、模型和提示词版本、工具调用及耗时、检查结果和修改次数。碰到成本突然上升,才能追到是某个工具被反复调用,还是每轮都在把过长的结果塞回上下文。
我的判断
我认同把确定性检查放在模型审阅前面。分节、字数和引用是否在允许集合里,都可以写成明确规则。真正影响发布质量的,是诸如「这项改动值得告诉用户吗」「提交标题能支撑这句描述吗」这类判断。提交标题写得含糊,审阅模型能看到的证据就有限。原文展示了实现和评估方法,没给出耗时、成本、通过率或人工改稿量的对照结果。独立审阅能带来多大提升,仍是经验判断。
示例也有一个可直接看出的缺口。git_log 会把失败包装成 ERROR: 字符串,外层 release_notes 拿到它后仍继续运行。按示例的取词方式,400 词上限也只适合按空白分词的文本。把脚本接进团队流程前,得先明确输入失败时怎么退出,并按实际发布语言定义长度规则。
如果团队已经给 PR 维护了稳定的分类和面向用户的描述,按标签套模板就是一个可对照的基线,PR 链接也能从源数据直接带出。模型更适合用在需要归并重复改动、把开发用语改成用户能理解的表述时。至于提交标题、文档和 Issue 里的文字,都可能夹带给模型的指令。「把工具结果当数据」值得写进提示词,工具能读什么、能写什么仍应由运行环境和权限控制。
能拿来做什么
- 给前端组件库或 Node 包试做发布说明草稿时,先用脚本固定标签范围和提交来源,再让模型起草,成品停在
RELEASE_NOTES.draft.md供维护者审阅。 - 把团队最常改的地方写成可执行规则。比如从已有 PR 元数据检查每条是否附有效链接,把「是否遗漏重要的行为变化」留给独立审阅。
- 用同一批历史版本对比模板、单次模型调用、带审阅和返修的流程。记录人工实际改了多少,同时看每次运行的成本和耗时,再决定是否保留额外的模型调用。