oh-my-pi Conventional Commit 分析提示词剖析从 Diff 到 Changelog-ready 提交消息的工程化管线【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读本文围绕 oh-my-pi 仓库中 analysis.md 这一核心提示词模板展开深入拆解项目如何指导大模型将任意 Git Diff 分类为符合 Conventional Commits 规范、且可直接落入 Changelog 的提交消息。你将掌握 scope 判定、summary 措辞、details 裁剪、changelog 元数据归类与输出格式校验五条硬规则并理解该提示词在 oh-my-pi 完整提交生成管线fast / standard / map-reduce 三套流程中的实际调用位置与底层实现。一、模板概览一份提示词如何拆成 System 与 User 两段analysis.md 是 oh-my-pi 提交生成模块的标准分析提示词整体分为两部分以!-- USER --注释为界上半部分是固定的 System 提示角色设定与行为指令下半部分是带 Handlebars 占位符的 User 模板注入每次提交的实时上下文。在 prompts.ts 中renderConventionalPrompt负责按分隔符切分并渲染const USER_SEPARATOR !-- USER --; export function renderConventionalPrompt( family: ConventionalPromptFamily, context: prompt.TemplateContext {}, ): { system: string; user: string } { const template PROMPT_BY_FAMILY[family]; const separator template.indexOf(USER_SEPARATOR); if (separator 0) return { system: , user: prompt.render(template, context).trim() }; const system template.slice(0, separator).trim(); const userTemplate template.slice(separator USER_SEPARATOR.length); return { system, user: prompt.render(userTemplate, context).trim() }; }System 段固定描述角色与规则User 段则在每次生成时注入project_context、types_description、stat、scope_candidates、common_scopes、recent_commits、diff等模板变量详见下文第七节这种「固定规则 实时数据」的拆分保证模型每次收到完全一致的约束而只更换提交内容本身。二、Scope 判定规则60% 阈值与「宁缺毋滥」原则提示词对 scope影响范围的判定给出了精确的可执行规则仅在单一组件占主导语义变更或约 60% 行数变化时使用 scope。示例src/api/改 150 行、src/lib.rs改 30 行 → scope 为api两边各 50 行 → 不写 scope。跨领域、均分、全项目或语义模糊 → 一律不写 scope。优先使用common_scopes和scope_candidates中提供的候选仅在无候选匹配时才自行发明。scope 必须短理想为单个词最多两个用-连接的词对长候选如coding-agent-chunk-edit-protocol应取其最有区分度的片段chunk-edit绝不使用 3 个及以上连字符词。禁止使用的 scopesrc、lib、include、tests、benches、examples、docs、项目名、app、main、entire、all、misc。不确定 → 省略而不是给出弱或有误导性的 scope。这一规则在源码中被严格落地。scope 候选并非模型凭空臆想而是由 scope.ts 中的ScopeAnalyzer根据git diff --numstat的增删行数加权计算PLACEHOLDER_DIRS如src、lib、tests、docs、packages等作为单段候选被剔除双段路径如src/api在占比超过 60% 时置信度会获得 1.2 倍加权排序后取前 5 名写入模板的scope_candidates。同时 commit-types.ts 的coerceOptionalScope实现了提示词要求的「最多两段」规范模型产出的 scope 会被按/切分、逐段清洗仅保留小写字母、数字、-、_最多保留两段后拼接——与提示词「Never 3 hyphenated words」的约束一一对应。宽变更检测也有代码佐证当ScopeAnalyzer发现第一候选占比低于wideChangeThreshold默认 0.5或涉及 3 个以上顶层目录时会判定为 cross-cutting转而通过 analyzeWideChange 推断抽象类别deps/docs/tests/error-handling/type-refactor/config并在候选字符串中标注(cross-cutting: ...)或(none - multi-component change)提示模型放弃具体 scope。三、Summary 规则伞状标题与过去时约束type(scope):之后的 summary 描述需满足六条硬性要求以小写过去时动词开头是整个 changeset 的伞状标题umbrella headline综合 diff 与 details 中的共享行为/结果绝不直接复制 detail #1 或某个单一文件的内容除非它占绝对主导不带type(scope):前缀、不以句号结尾、不含 markdown 标记长度符合配置的准则——默认 ≤72 字符含前缀。oh-my-pi 不仅把这条规则写进提示词还用 validation.ts 的validateSummary对模型输出做二次强制校验summary 以句号结尾 → errortrailing_period首行超过summaryHardLimit默认 128 字节→ errorsummary_too_long超过summarySoftLimit默认 96→ warning超过summaryGuideline默认 72→ warning首词不是过去时动词 → errorpresent_tense_first_word通过past_tense/irregular_past/ed_blocklist/d_blocklist词表判断首词与 commit type 重复如fix: fixed ...→ errortype_word_repetition包含填充词filler words或元描述短语meta phrases→ warning。若摘要不合规generate.ts 的acceptSummary会先尝试repairSummaryTense把首词现在时改写为过去时仍失败则进入summary-rewrite提示词重写最终兜底是fallbackSummary的确定性规则生成详见第五节。这三层机制确保任何情况下都不会输出违反提示词的摘要。四、Details 规则0–6 条高信号要点提示词要求 details正文要点遵循最多 0–6 条只保留信号最高的条目每条以过去时动词开头、以句号结尾写清影响/理由impact/rationale跳过琐碎的「改了什么」使用精确名称模块、API、文件名单条不超过 120 字符3 条以上相似变更合并为 1 条排除项import 变更、空白、格式化、琐碎重命名、调试打印、纯注释变更、无实质修改的文件移动。在解析侧markdown.ts 的parseConventionalAnalysisMarkdown负责把模型输出的要点列表还原为结构化的ConventionalDetail支持-/*/•/–//有序列表等符号自动用ensureSentence为未以标点结尾的条目补句号并通过dedupe去除重复项——恰好呼应提示词「3 similar changes → one detail」的去重精神。细节条目的userVisible与changelogCategory字段则在后续 changelog 生成阶段决定哪些要点对用户可见。五、Changelog 元数据六类用户可见变更分类提示词第 4 节定义了仅针对用户可见变更的分类映射这也是生成 changelog 的直接依据分类适用场景Added新增公共 API、功能、能力Changed修改既有行为FixedBug 修复、修正Deprecated标记为即将移除的功能Removed已移除的功能/APISecurity安全修复或加固与之配套commit-types.ts 中的CHANGELOG_CATEGORY_BY_NAME接受added/changed/fixed/deprecated/removed/security/breaking/breaking changes等输入并映射到标准 changelog 分组normalizeDetails会为每条 detail 解析可选的changelog_category与user_visible标记只有userVisible为 true 的条目才保留分类——与提示词「user-visible only」的限定完全一致。commit type 词汇本身则来自 resources/commit_types.json经formatTypesDescription渲染为模板中commit_types的逐行说明。六、Verify 环节与强制输出格式提示词第 5 节要求模型在输出前逐项自检type是否为 dominant change 且属于允许的 commit typescope为合法短 scope 或省略summary伞状标题、过去时动词、无前缀无句号details完整、有依据、≤6 条issue_refs仅由 diff/context 支持。输出格式被严格限定为不得带代码围栏# type(scope): summary - detail 1 - detail 2 - detail 3 Fixes: #123, #456注意#是固定前缀而非 markdown 标题标记。解析端 markdown.ts 的splitHeading与parseHeadingLine会宽容地从前 5 行中提取type(scope): summary头部Fixes:/Closes:/Resolves:行与要点中的#123引用会被收集为issueRefs通过ISSUE_RE /#\d(?:\s*-\s*#?\d)?/g提取。整个模块也接受 JSON 形态的返回analysisFromMapping兼容结构化输出场景。七、User 模板变量每次提交注入的实时上下文analysis.md 的 User 段通过 Handlebars 注入七类上下文这些变量由 generate.ts 的generateDirectAnalysis逐一填充模板变量内容来源/格式project_context项目上下文可选ConventionalGenerationContext包裹在project_context标签中types_description允许的 commit type 词表formatTypesDescription()渲染的逐行描述statdiff 统计git diff --stat输出scope_candidatesscope 候选列表extractScopeCandidates加权计算结果common_scopes常用 scope可选仓库配置注入recent_commits近期提交风格可选包裹在style_patterns标签中供模型模仿仓库既有措辞风格diff实际 diff 内容包裹在diff标签中diff 注入前会经过 diff.ts 的预处理stripWhitespaceOnlyFiles剔除纯空白变更文件、scrubDiffForPrompt清洗无关噪声、超长时按maxDiffLength默认 100,000 字符或smartTruncateDiff截断。此外project_context、recent_commits均以 XML 风格标签包裹模型可明确区分「必须遵守的项目背景」与「可参考的风格样本」。若用户额外提供user_context会以user_context标签追加在 user prompt 之后同样属于提示词设计的上下文隔离策略。八、提示词在生成管线中的位置Fast、Standard 与 Map-Reduceanalysis.md 并非孤立模板而是 oh-my-pi 提交生成管线三种工作流共用的核心分析入口调用关系集中在 generate.ts纯空白变更若 diff 全为空白/格式调整直接生成style类型提交如reformatted xxx跳过 LLM 分析。Fast 流程当变更行数 ≤autoFastThresholdLines默认 200时先尝试 fast.md 快速模板一次生成完整提交校验失败则回退到 analysis 模板。Standard 流程diff 大小低于maxDiffLength时直接用 analysis.md 生成ConventionalAnalysistype / scope / summary / details / issueRefs。Map-Reduce 流程当 map-reduce.ts 判定总 token 数 ≥mapReduceThreshold默认 5,000或存在超大文件 50,000 token时先由 map.md 按文件并行提取事实观察并发上限 16、按mapBatchTokenBudget默认 16,000 token 分批再由 reduce.md 汇总为与 analysis.md 相同结构的分析结果——此时 analysis.md 的输出契约保持不变。analysis 产出后summary.md 与 summary-rewrite.md 会基于 analysis 的结果重写/修复 summary重试上限由maxRetries控制默认 3 次含退避随后经 normalization.ts 做 Unicode 字符映射全角符号转 ASCII、弯引号转直引号等和postProcessCommitMessage清洗最终由validateCommitMessage全量校验后才返回给调用方。若最终仍无法通过校验validationError会连同提交消息一起返回交由人工修正——这正是提示词中「conservative over speculative」保守优先于猜测原则在工程侧的兑现。九、写在最后oh-my-pi 的 analysis.md 是一份「可执行规范」级别的提示词60% 阈值界定 scope、伞状标题与过去时约束 summary、0–6 条高信号要点、用户可见六类 changelog 分类、以及固定的无围栏输出格式每一条都对应着仓库中 scope.ts、validation.ts、markdown.ts、commit-types.ts 等源码的确定性实现。提示词负责「教会模型规则」源码负责「强制校验结果」二者叠加形成了从 diff 到 changelog-ready 提交消息的完整闭环。若要修改提交风格只需调整本模板与 config.ts 中的阈值参数72/96/128 字符三级限制、200 行 fast 阈值、5,000 token map-reduce 阈值等无需改动任何业务代码。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考