duck.ai通过语义识别、git钩子集成、自定义prompt模板、本地大模型支持及历史提交重写五步法，实现conventional commits规范的高质量提交信息生成。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在编写 Git 提交信息时经常面临描述模糊、格式不统一或遗漏上下文等问题，则可能是由于缺乏结构化提示与语义识别支持。Duck.ai 通过解析提交差异与项目上下文，辅助生成符合 Conventional Commits 规范的高质量 commit message。以下是具体操作技巧：
一、配置 Duck.ai 的语义识别规则
Duck.ai 依赖标准化的提交前缀（如 feat、fix、docs）识别变更类型与影响范围，若项目未启用语义化约束，AI 将无法准确归类改动意图。需在本地仓库中建立可执行的校验机制，确保每条提交消息携带有效 type 与 scope。
1、在项目根目录创建 .duckai.json 配置文件，写入基础规则：
{"rules": {"type-enum": [2, "always", ["feat", "fix", "docs", "style", "refactor", "test", "chore"]], "scope-enum": [2, "always", ["api", "ui", "config", "cli", "core"]]}}
2、将该配置文件纳入版本控制，并在团队协作文档中明确要求所有成员拉取最新配置后执行 duckai init 命令完成本地初始化。
3、运行 duckai lint --staged 对暂存区提交进行预检，系统将自动标记不符合规范的 message 并给出修正建议。
二、集成 Duck.ai 到 Git 钩子流程
将 Duck.ai 嵌入 prepare-commit-msg 钩子，可在提交前自动生成初稿，避免手动输入低质量描述。该方式不替代人工审核，但显著提升首版 message 的规范性与信息密度。
1、在 .git/hooks/prepare-commit-msg 中添加可执行脚本，内容为：duckai generate --from-staged --template conventional
2、赋予脚本执行权限：chmod +x .git/hooks/prepare-commit-msg
3、执行 git add . && git commit，观察终端输出的 AI 生成 message，确认无误后直接保存退出编辑器。
三、基于 diff 内容定制 prompt 模板
Duck.ai 支持用户定义 prompt 模板，以适配不同项目风格或团队术语习惯。模板直接影响 AI 对代码变更的理解深度与表述准确性，尤其适用于含领域专有名词的工程场景。
1、新建 .duckai/prompt.md 文件，填入结构化指令，例如：“你是一名熟悉微服务架构的资深后端工程师，请根据以下 diff 输出一条 Conventional Commits 格式的 message，其中 scope 必须从 api-gateway、auth-service、order-service 中选择一个最匹配的。”
2、在配置文件中引用该模板："prompt_template": ".duckai/prompt.md"
3、触发生成时使用命令：duckai generate --diff --template-file .duckai/prompt.md
四、多模型后端切换与本地化部署支持
当项目涉及敏感代码或网络策略限制时，Duck.ai 允许切换至本地运行的大语言模型，保障 diff 数据不出内网。此模式需提前部署兼容 OpenAI API 格式的推理服务，如 Ollama + codellama 或 ms-swift 推理节点。
1、启动本地模型服务：ollama run codellama:7b-instruct，并监听 http://localhost:11434
2、修改 Duck.ai 配置中的 llm_provider 字段为 "ollama"，并设置 base_url 为对应地址。
3、执行 duckai generate --staged，验证是否成功调用本地模型返回 message。
五、批量修正历史提交信息
对于已合并但格式混乱的历史提交，Duck.ai 提供交互式重写功能，可在不破坏 SHA-1 哈希一致性的前提下，批量更新 message 内容。该操作仅影响本地仓库，推送前需与团队同步确认。
1、执行 duckai rewrite --since "2026-05-01" --interactive，指定时间范围并启用逐条确认模式。
2、对每条提交，Duck.ai 显示原始 diff 片段及生成建议，输入 y 接受，e 进入编辑器手动调整，n 跳过。
3、全部确认完成后，工具自动执行 git rebase -i 并注入新 message，生成新的提交对象。
