一、核心设计背景：解决开发者的 Git 收尾痛点
在日常开发流程中，开发者往往会在一天的编码工作结束后，面对一堆混杂的改动：配置文件、业务逻辑、测试用例、文档修改全部混在未提交的变更列表里。手动完成分组、编写符合团队规范的 commit message、校验身份信息再推送，整个过程往往要耗费半小时以上的无意义时间。 如果直接让AI处理这个场景，很容易踩中大量工程化坑点：AI可能只修改Author字段却忽略Committer，导致提交历史里身份信息撕裂；自由发挥生成完全不符合团队风格的commit message；擅自切换到主干分支引发风险；遗漏合规要求的Co-Authored-By或Signed-off-by标签，触发团队代码审查的合规问题。 HagiCode的AI提交提示词系统，本质就是把这个“杂乱改动→自动合规提交”的过程，封装成一套参数化的Agent任务契约，彻底把开发者从琐碎的Git收尾工作里解放出来。
二、提示词系统的整体架构：不是一段写死的字符串
很多人对提示词的认知停留在“一段自然语言文本”，但HagiCode的AI提交提示词是一套完整的场景化系统，对应代码里的PromptScenario.AutoComposeCommit枚举，整体采用“模板+元数据”的分离架构，完全摒弃硬编码字符串的实现方式。
2.1 文件结构设计
整套提示词文件按语言场景平铺存放，结构清晰可维护：
Resources/Prompts/
├── auto-compose-commit.en-US.hbs # 英文Handelbars模板
├── auto-compose-commit.en-US.json # 英文元数据配置
├── auto-compose-commit.zh-CN.hbs # 中文Handelbars模板
└── auto-compose-commit.zh-CN.json # 中文元数据配置
其中.hbs文件是提示词的正文内容，使用Handlebars语法实现变量注入和条件渲染；.json文件则定义了场景版本、参数Schema、输入控件描述等元信息。
2.2 架构设计的三个核心考量
第一是元数据和提示词正文完全解耦，前端不需要感知模板的具体内容，只需要读取JSON里的参数定义，就能自动渲染出Git身份选择器、目标分支策略、推送开关等交互控件，实现前后端完全解耦。 第二是多语言本地化平铺实现，没有使用传统的i18n Key翻译模式，每个语言版本都拥有独立的完整模板，不仅可以翻译文字，还能针对不同地区开发者的提交习惯，定制不同的示例和规则，避免中英文仓库共用一套模板带来的水土不服。 第三是性能优化，从早期的Scriban模板引擎迁移到Handlebars.Net，直接把模板编译为IL字节码执行，渲染速度远高于解释执行的模板引擎，同时做了兼容处理，自动把渲染结果里的True/False替换为true/false，完全兼容旧版本的布尔输出习惯。
三、五大核心设计决策：从根源规避AI提交坑点
这套提示词的核心逻辑，是通过明确的规则约束，把AI的自由发挥空间压缩到工程可控的范围内，五个关键决策构成了整个系统的稳定性基石。
3.1 角色强绑定，锁定专业边界
提示词开头直接锁死AI的身份定位：“你是一名资深全栈工程师，精通Git工作流、Conventional Commits规范与团队协作标准”，从输入源头引导模型优先调用工程领域的专业知识，避免输出无关的冗余内容，大幅降低无效输出概率。
3.2 任务目标极度明确，拒绝模糊输出
没有把任务定义为“帮我写commit信息”，而是明确要求输出“可直接执行的完整Git提交方案”，输出内容必须包含：变更文件的分组规则、每个commit的type/scope/subject/body完整信息、可直接复制运行的Git命令，以及用于自检的校验命令，最终产出物可以直接接入自动化流程，完全没有歧义。
3.3 强制双身份一致，彻底解决身份撕裂
针对AI最容易犯的“只改Author不改Committer”错误，提示词直接给出标准命令模板：
git -c user.name="xxx" -c user.email="xxx" commit --author="xxx <xxx>" ...
同时强制要求AI在提交后执行git log --format=fuller -1自检，确保Author和Committer的身份信息完全一致，从规则层面彻底避免提交历史身份撕裂的问题。
3.4 硬编码分组决策树，杜绝乱分组
完全不依赖AI的自由判断，直接给出明确的分组规则：配置文件单独成组、文档修改单独成组、同一模块的业务代码合并、跨前后端的改动必须拆分、重构和格式化修改不能和功能改动混在一起，让AI严格按照决策树完成分组，输出的提交历史完全符合资深工程师的操作习惯。
3.5 非交互式兼容，支持CI/CD自动化
提示词头部明确声明：当前任务可能运行在无人工交互的CI/自动化脚本环境中，禁止任何交互式询问，所有缺失的参数直接使用默认值，所有不确定的假设必须明确记录在输出日志里，让这套提示词不仅能在IDE里给开发者使用，还能直接接入流水线实现无人值守自动提交。
四、模板执行的完整流程
中文主模板的执行逻辑完全按照工程化流程推进，没有任何冗余环节：
头部先声明角色定位和非交互式规则，明确禁止AI发起交互式询问，缺省的commit type默认使用feat，所有不确定的假设必须显式记录。
注入所有上下文信息：完整的git diff内容、仓库基础信息、用户的Git身份信息，给AI提供完整的决策依据。
引导AI按照分组决策树完成变更拆分，生成结构化的提交计划，每个分组明确标注包含的文件、对应的Conventional Commits字段、提交说明正文。
生成对应的可执行Git命令，严格遵循双身份一致的规则，同时生成后续的自检命令。
最后根据用户配置的开关，自动生成后续的推送命令，支持直接推送到指定的目标分支，全程不需要人工介入。
五、工程落地的稳定性保障
整套提示词系统在后端以单例服务的形式完成加载和渲染，同时配套了快照测试机制，每次模板修改都会自动校验输出结果的一致性，避免意外改动破坏原有逻辑。同时所有条件渲染的合规标签，比如Co-Authored-By、Signed-off-by，都通过模板的条件语法严格控制，只有用户明确开启对应开关时才会生成，完全避免合规风险。 这套经过大量项目验证的提示词系统，最终把原本需要半小时的Git收尾工作，压缩到几秒内自动完成，同时输出的提交历史质量远高于普通开发者手动编写的平均水平。 </doc_start> 以上是HagiCode AI提交提示词的完整设计与实现拆解，如果你需要具体的模板代码片段、元数据配置示例，或者对应的C#后端服务实现细节，可以随时提出进一步的需求。