本文把模型调用、结构化输出和安全边界组合成一个小项目:读取 Git diff,生成提交说明草稿,再由 Python 校验。工具不执行提交,最终决定权仍在开发者手中。

先确定边界

输入是文本 diff,输出是固定 JSON:type 只能是 feat、fix、docs、refactor、test 或 chore;subject 不超过 72 个字符;body 是补充说明;risk 只能是 low、medium 或 high。

模型负责归纳,程序负责检查,人负责确认。diff 可能含有密钥或内部路径,发送前要脱敏,不能自动执行命令。

准备环境

1
2
3
4
5
python -m venv .venv
source .venv/bin/activate
python -m pip install openai python-dotenv
export OPENAI_API_KEY="替换为你的真实密钥"
export MODEL_NAME="替换为你可用的模型名称"

示例使用 SDK 的 Responses API。配置只从环境变量读取。

编写最小生成器

创建 draft_commit.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import json, os, sys
from pathlib import Path
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
model = os.environ["MODEL_NAME"]
types = {"feat", "fix", "docs", "refactor", "test", "chore"}
risks = {"low", "medium", "high"}
prompt = "只返回 JSON:type、subject、body、risk。type 只能是 feat/fix/docs/refactor/test/chore,subject 不超过72字,body 不超过300字,risk 只能是 low/medium/high。只根据 diff。"


def validate(raw):
data = json.loads(raw)
keys = {"type", "subject", "body", "risk"}
if not isinstance(data, dict) or set(data) != keys:
raise ValueError("字段不完整")
if data["type"] not in types or data["risk"] not in risks:
raise ValueError("枚举值无效")
if not isinstance(data["subject"], str) or not 1 <= len(data["subject"]) <= 72:
raise ValueError("subject 长度无效")
if not isinstance(data["body"], str) or len(data["body"]) > 300:
raise ValueError("body 无效")
return data


def main():
if len(sys.argv) != 2:
raise SystemExit("用法:python draft_commit.py staged.diff")
diff = Path(sys.argv[1]).read_text(encoding="utf-8")
if not diff.strip() or len(diff) > 16000:
raise SystemExit("diff 不能为空且不能超过16000字符")
raw = client.responses.create(model=model, instructions=prompt, input=diff).output_text
result = validate(raw)
Path("commit-draft.json").write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print("草稿已保存,请人工复核。")


if __name__ == "__main__":
main()

运行:

1
2
git diff --cached > staged.diff
python draft_commit.py staged.diff

模型输出会变化,不能把某次结果当成固定答案。可确定验证的是:空 diff、超长 diff、非法枚举、未知字段和错误长度都会被拒绝;只有 validate 通过后才写入文件。

常见问题

为什么不直接执行 git commit? 生成人话和修改仓库是不同风险等级的动作。人工确认能发现误解、破坏性变更和敏感路径。

返回 Markdown 围栏怎么办? 当前实现直接拒绝,不静默截取。修复重试后的内容也必须再次校验。

小结

项目形成了“diff—模型归纳—本地校验—人工确认”的闭环。模型不连接有副作用的命令;可拒绝、可复核的边界最值得保留。