1. 从“提交信息”到“知识协议”一个被忽视的工程实践如果你和我一样每天都要和 Git 打交道那么git commit -m “fix: update something”这样的操作可能已经成了肌肉记忆。我们习惯了把提交信息当作一个简单的、面向人类的“备忘录”记录一下这次改了啥方便以后回溯。但最近我在一个大型的、由多个 AI 编码助手比如 GitHub Copilot、Cursor 等协作参与的项目里遇到了一个头疼的问题这些 AI 助手之间以及它们与人类开发者之间对于代码变更的“上下文”理解是割裂的。比如我让 AI A 基于某个需求重构了模块 X提交信息是“重构模块 X 以支持动态配置”。几天后另一位同事或者另一个 AI 助手 B需要修改模块 X 的一个相关函数但它完全不知道这次重构背后的“动态配置”具体指什么、边界在哪里、有哪些已知的坑。它只能看到最终的代码 diff却丢失了那次变更的“意图”和“上下文”。这直接导致了后续修改引入了回归缺陷或者做出了与最初设计相悖的决策。这让我开始重新审视 Git 提交信息。它难道只能是一段随意的文本吗在 AI 智能体逐渐成为开发流程中固定“成员”的今天我们能否重新定义它的角色这就是Lore这个想法诞生的背景。Lore 不是一个全新的工具而是一种设计理念和协议将 Git 提交信息重新定位为一种结构化的知识交换协议专门服务于 AI 编码助手之间的协作与知识传承。简单说Lore 主张我们像设计 API 接口一样去设计我们的提交信息。让它包含机器可读的、结构化的上下文而不仅仅是人类可读的摘要。这样任何一个接入此协议的 AI 助手在查看历史提交时不仅能知道“代码变了什么”还能理解“为什么变”、“变更的约束条件是什么”、“相关的决策上下文有哪些”。这相当于为项目的 Git 历史建立了一个持续增长的、结构化的“项目记忆库”任何新的 AI 智能体加入都能快速通过阅读这个记忆库来理解项目的设计脉络和隐形规则而不是面对一堆冰冷的代码变更记录茫然无措。2. 为什么传统的提交信息在 AI 协作时代“不够用”了在纯人类协作的团队里提交信息即使写得简略问题也不大。因为人类开发者具备“隐性知识”和“情境理解”能力。看到“修复了空指针异常”这样的提交同事能结合最近的讨论、JIRA 票号、甚至私下的一句吐槽脑补出完整的上下文。但 AI 助手目前做不到这一点。它们本质上是“上下文饥渴”的模型其理解完全依赖于我们喂给它们的提示词Prompt和上下文窗口内的内容。传统的、非结构化的提交信息对它们来说信息密度太低噪声太高。2.1 AI 编码助手的协作瓶颈分析让我们具体拆解一下当多个 AI 助手或人与 AI 混合基于同一个 Git 仓库工作时会面临哪些传统工作流无法解决的挑战上下文丢失与知识断层这是最核心的问题。AI 助手 A 完成一个任务时其思考过程、权衡的备选方案、排除某些路径的原因这些宝贵的“决策逻辑”通常只存在于它单次会话的临时上下文中。一旦会话结束这些知识就消失了。后续的 AI 助手 B 接手时面对的就是一个“黑盒”变更它无法获知 A 当时的约束条件比如“因为性能考虑所以没有采用方案 Y”这极易导致决策冲突。意图传递失真人类写的提交信息如“优化数据库查询”其“优化”的标准是什么是降低了延迟还是减少了 IO抑或是简化了查询逻辑便于维护AI 在解读时可能存在歧义。而如果提交信息能结构化地包含“指标将平均查询耗时从 120ms 降低至 15ms”那么意图就清晰无误了。变更原因与影响链难以追溯一个修复了“内存泄漏”的提交其根本原因可能是三天前另一个“引入缓存”的提交。在纯代码 Diff 中这种因果链是隐式的。结构化的提交信息可以包含“根因提交哈希”、“关联问题”等字段显式地建立链接帮助 AI 理解缺陷的生命周期。规范与约束的渗透效率低团队的技术规范如“禁止使用某个已废弃的 API”、“所有配置必须支持热更新”通常写在文档里。AI 助手可能在编码时被提醒但很难在审查历史代码或理解他人提交时主动关联这些规范。结构化的提交信息可以把“遵循的规范”或“做出的权衡”作为元数据嵌入让规范随着每一次提交被“固化”和“传播”。2.2 现有方案的局限性面对这些问题社区并非没有尝试。比如更详细的提交信息规范如 Conventional Commits它定义了feat、fix、BREAKING CHANGE等类型和格式是一个巨大进步。但它主要服务于自动化生成 CHANGELOG 和版本号其结构仍是面向发布流程的而非面向 AI 的深度上下文交换。在代码注释中详细说明这当然有帮助但注释会随着代码重构而失效或变得不相关且缺乏统一的解析方式。依赖外部系统如将完整的设计文档链接到 JIRA 或 Confluence。但这要求 AI 助手具备跨工具检索和理解的能力且链接可能失效形成了另一个信息孤岛。Lore 的思路是“就地解决”利用 Git 这个所有开发者包括 AI都必须且已经在使用的、最基础的协作设施将其承载的信息“升级”使其原生具备服务 AI 协作的能力。这有点像 HTTP 协议从 1.0 到 2.0 的演进底层传输载体没变但协议本身变得更高效、更能表达复杂意图。3. Lore 协议设计定义 AI 可读的“提交语义”Lore 的核心是一套轻量级的、可扩展的结构化数据协议。它不强制要求改变 Git 本身而是约定如何在现有的提交信息体中嵌入机器可读的区块。其设计原则是人类可读优先机器可读次之增量采用向后兼容。3.1 基础协议格式一个遵循 Lore 协议的提交信息可能长这样feat(api): 为用户服务添加分页查询接口 本次变更实现了 GET /users 端点的分页功能以应对用户列表增长后的性能问题。 ## Lore-Context { “protocol_version”: “0.1.0”, “change_intent”: “performance_optimization”, “requirements”: [“PROJ-123”, “PROJ-456”], “constraints”: { “backward_compatibility”: “must”, “performance_target”: “p99 latency 200ms under 1000 RPS” }, “decisions”: [ { “problem”: “如何选择分页游标编码方式”, “options”: [“offset-limit”, “cursor-based (encrypted timestamp)”, “cursor-based (serialized ID)”], “chosen”: “cursor-based (encrypted timestamp)”, “reason”: “避免 offset-limit 在深度分页时的性能劣化同时相比序列化 ID 方案更易于客户端处理且无需暴露内部 ID。” } ], “dependencies”: [“a1b2c3d”], “tests”: { “added”: [“test_user_pagination.py”], “updated”: [“test_user_api.py”] } } ## Lore-Context-End 具体的实现细节包括 - 新增 PaginatedResponse 模型。 - 在 UserService 中实现 list_users 游标逻辑。 - 更新了 API 文档。可以看到它在常规的提交描述下方增加了一个## Lore-Context和## Lore-Context-End标记的区块。这个区块内部是一个 JSON 对象这就是 Lore 协议定义的结构化知识。3.2 核心字段详解与设计考量我们来拆解这个 JSON 里的关键字段以及为什么它们对 AI 助手至关重要protocol_version: 标识所用 Lore 协议的版本。这允许协议本身向前演进AI 助手可以据此调整解析逻辑。change_intent: 变更的核心意图分类。比 Conventional Commits 的type更细致。例如performance_optimization(性能优化)bug_fix(缺陷修复)refactor(重构)security_patch(安全补丁)dependency_update(依赖更新)feature_implementation(功能实现)这个字段能快速帮助 AI 对变更进行高层级分类优先关注某些类型的变更如安全补丁。requirements: 关联的需求或任务 ID如 JIRA KEY。这提供了变更的业务上下文源头。constraints: 本次变更必须遵守的约束条件。这是防止后续 AI 引入回归的关键。例如backward_compatibility:“must”/“optional”/“breaking”。明确告知后续修改者是否必须保持 API 兼容。performance_target: 具体的性能指标。后续 AI 在修改相关代码时必须运行性能测试来验证是否仍满足此目标。third_party_contract: 如果变更涉及外部系统接口可以在此说明契约。decisions:这是 Lore 协议的灵魂所在。它记录开发过程中面临的关键决策点。每个决策包含problem: 遇到的问题。options: 考虑过的备选方案。chosen: 最终选择的方案。reason: 选择该方案的理由技术权衡、业务考量等。这个字段将“为什么这么做”的隐性知识显式化。当 AI 在未来看到这段代码产生疑惑时可以直接从这里找到设计 rationale避免重新讨论或做出矛盾决策。dependencies: 此变更所依赖的前序提交哈希列表。显式声明依赖关系可以帮助 AI 理解变更的先后顺序和逻辑基础在git bisect或排查问题时也能快速定位关联变更集。tests: 指明新增或更新的测试文件。这引导 AI 在修改相关功能时知道应该去哪些测试文件中寻找测试用例并提醒它可能需要更新这些测试。注意Lore 协议定义的字段是建议性的团队可以根据自身需要扩展。例如可以添加“known_issues”字段来记录本次引入但尚未解决的次要问题或者“rollback_procedure”字段记录回滚步骤。关键在于团队内部需要就核心字段集达成一致。3.3 向后兼容性与渐进式采用Lore 协议被设计为对现有工具链完全透明。对于不识别## Lore-Context区块的普通 Git 客户端、代码托管平台GitHub/GitLab或 CI/CD 系统它们只会将其视为提交信息中的普通 Markdown 注释完全不影响浏览和显示。只有那些集成了 Lore 协议解析器的 AI 助手或专门工具才会去解析并利用其中的结构化信息。这意味着团队可以渐进式地采用 Lore。可以从最重要的、架构复杂的模块开始要求相关提交附带 Lore 上下文。甚至可以先由人类编写逐渐训练 AI 助手学会在生成提交时自动填充部分字段如根据代码 Diff 和对话历史推断change_intent和dependencies。4. 实战将 Lore 协议集成到 AI 编码助手工作流中理念再好也需要落地。要让 Lore 发挥作用我们需要对现有的 AI 编码助手进行“赋能”让它们能够理解和生成 Lore 格式的提交信息。这里不涉及具体某个 AI 产品的内部实现而是提供一套通用的集成思路和工具链设想。4.1 为 AI 助手构建“Lore 感知”上下文当 AI 助手如 Copilot、Cursor、Claude Code 等被要求修改代码或审查一个 Pull Request 时它的上下文通常包括当前文件、打开的相关文件、以及可能的终端输出。为了集成 Lore我们需要一个中间件或插件来增强它获取的上下文。这个中间件的工作流程如下监听事件当 AI 助手的上下文需要更新时例如切换到新文件、执行git log命令、查看某个函数历史中间件被触发。分析目标确定用户当前关注的文件、函数或代码行。检索 Lore运行一个后台命令使用git blame或git log -p -S等命令找到最近修改目标代码的提交哈希。然后获取这些提交的完整信息。解析与过滤解析这些提交信息提取出## Lore-Context区块。将多个相关提交的 Lore 上下文合并、排序形成一个连贯的“历史决策叙事”。注入提示词将提取到的结构化 Lore 上下文以清晰的文本摘要形式作为系统提示词System Prompt的一部分或额外的上下文注入到 AI 助手的会话中。例如当开发者将光标定位到一个复杂的数据库查询函数时AI 助手侧的提示词可能会被自动追加这样一段信息【相关历史决策上下文 (来自Lore)】 - 提交 a1b2c3d (feat): 首次实现此查询。决策在“使用ORM原生查询”与“手写SQL”间选择了“手写SQL”原因需要利用数据库特定的窗口函数以获得最佳性能。 - 提交 e5f6g7h (perf): 为此查询添加了复合索引。约束必须保持查询响应时间 p95 50ms。新增索引 idx_user_status_created。 - 提交 i8j9k0l (fix): 修复了在用户状态为‘PENDING’时可能出现的重复计数问题。根因对 LEFT JOIN 条件理解有误。关联测试文件test_complex_query.py。现在当开发者或另一个 AI 任务问“如何优化这个函数”时AI 助手已经知道1这个函数对性能很敏感有明确的延迟目标2已经有一个为它服务的特定索引3这里曾经有一个关于 JOIN 条件的微妙 Bug。它给出的建议就会更有针对性避免提出“换成 ORM 查询”这种与历史决策冲突的方案。4.2 训练 AI 助手生成 Lore 格式的提交反过来我们更希望 AI 助手在完成代码修改后能主动生成包含丰富 Lore 上下文的提交信息。这需要一些引导和模板。我们可以创建一个预定义的提示词模板在请求 AI 生成提交信息时使用请你作为资深开发者为刚才完成的代码变更撰写 Git 提交信息。 请遵循以下格式 **提交标题**type(scope): 简短描述 (使用Conventional Commits类型) **提交正文** 首先用一段话概括本次变更的内容、动机和影响。 然后请生成一个结构化的 **## Lore-Context** 区块。请基于我们的开发对话和代码变更尽可能填充以下JSON字段 { “protocol_version”: “0.1.0”, “change_intent”: “bug_fix|feature_implementation|performance_optimization|...”, “requirements”: [“关联的任务ID如JIRA-XXX”], “constraints”: { “backward_compatibility”: “must|optional|breaking”, // 其他关键约束如性能目标、安全要求等 }, “decisions”: [ // 列出1-2个在实现过程中做出的关键设计或技术决策 { “problem”: “遇到的问题”, “options”: [“方案A”, “方案B”], “chosen”: “选择的方案”, “reason”: “详细的选择理由包括权衡” } ], “dependencies”: [“依赖的前序提交哈希可选”], “tests”: { “added”: [“新增的测试文件”], “updated”: [“更新的测试文件”] } } **最后**在 Lore 区块后可以补充更详细的实现说明。通过多次使用这样的模板AI 助手会逐渐学习到团队对结构化上下文的需求。更进一步可以开发一个 IDE 插件或 Git Hook如prepare-commit-msg在提交时自动调用 AI API根据暂存区的 Diff 和最近的开发对话历史建议一个填充了部分字段的 Lore 提交信息草稿供开发者审核和修改。4.3 工具链设想Lore 命令行工具与 CI 集成为了便于管理和利用 Lore 数据可以开发一个简单的命令行工具lore-clilore-cli parse commit-hash解析指定提交的 Lore 上下文并以友好格式打印。lore-cli search --intentbug_fix --filesrc/utils.py搜索修改过指定文件且意图为 bug_fix 的所有提交及其 Lore。lore-cli graph commit-hash生成该提交依赖的决策图基于dependencies和decisions字段。在 CI/CD 流水线中可以集成 Lore 检查提交信息 lint检查提交信息是否包含有效的 Lore 区块非强制但可提示。约束验证如果 Lore 中声明了performance_targetCI 可以自动运行对应的性能测试验证变更是否仍满足目标并在 PR 中报告。影响分析当新的 PR 修改了某个文件CI 可以自动找出该文件历史上所有包含 Lore 的提交提取关键约束和决策作为 PR 审查的补充信息提醒审查者注意。5. 潜在挑战、应对策略与未来展望任何新范式都会面临挑战Lore 也不例外。最大的挑战可能来自于“额外的开销”和“一致性维护”。挑战一编写结构化上下文增加了提交成本。应对策略这需要文化转变和工具辅助。初期可以将其视为一种“代码注释”但注释的是“变更意图”而非具体实现。工具辅助是关键如上文所述的 AI 生成建议、IDE 模板片段可以大幅降低编写成本。团队可以从最关键、最复杂的模块开始试行让成员体验到“阅读 Lore 带来的上下文红利”大于“编写 Lore 的成本”从而形成正向循环。挑战二如何保证 Lore 信息的准确性和及时更新应对策略Lore 信息应被视为与代码注释同等级别的“文档”在代码审查Code Review时一并审查。审查者需要检查 Lore 中的decisions是否合理、constraints是否准确。当后续重构使得某个 Lore 上下文过时应该在新的提交中更新或注明。这类似于更新过时的代码注释是良好开发实践的一部分。挑战三协议碎片化与工具生态。应对策略Lore 作为一个开放理念其具体协议格式可以社区化。可以建立一个简单的规范网站定义核心字段和扩展机制。关键是要保持极简和可扩展。工具生态会随着采用度的提高而自然生长初期可以由团队内部开发简单的脚本和插件。未来展望Lore 的终极愿景是让项目的 Git 仓库成为一个真正意义上的、富含语义的“知识图谱”。AI 助手可以像查询数据库一样查询项目历史“这个模块为什么采用了这种设计模式”“修改这个函数需要特别注意哪些性能约束”“历史上修复这类 Bug 通常涉及哪些文件”。更进一步这或许会催生一种新的“基于历史的编程”范式。开发者或 AI 在动手前先“咨询”项目历史通过 Lore获得经过时间检验的设计模式和避坑指南从而写出更稳健、更符合项目气质的代码。Git 提交信息这个我们日常工作中最平凡的元素或许正是连接人类开发者智慧与 AI 助手能力实现高效、可传承协作的那座桥梁。它的价值远不止于那一行git log --oneline的输出。