本文把模型调用、结构化输出和安全边界组合成一个小项目:读取 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—模型归纳—本地校验—人工确认”的闭环。模型不连接有副作用的命令;可拒绝、可复核的边界最值得保留。