oh-my-pi 中的 Fast 提交信息生成提示词fast.md的规则契约与流水线实现剖析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读本文围绕 oh-my-pi 仓库中负责快速生成 Conventional Commit 提交信息的核心提示词文件 fast.md 展开剖析它是如何在“小改动”场景下用一次模型调用直接产出# type(scope): summary格式的提交信息以及它的规则如何在 generate.ts 等源码中被执行、校验与兜底。读完本文你将掌握该提示词的全部输入变量、输出契约、约束规则以及它与 analysis / summary 等提示词家族之间的分工与降级关系。一、fast.md 在提交信息生成流水线中的位置oh-my-pi 的提交信息生成逻辑集中在 packages/coding-agent/src/commit/conventional 目录下其中 prompts 子目录定义了六种提示词“家族”Prompt Family家族名文件定位analysisanalysis.md对整段 diff 做结构化分析type / scope / summary / detailsfastfast.md小改动场景下单次调用直接产出完整提交信息map/reducemap.md、reduce.md超大 diff 的 map-reduce 分治分析summarysummary.md从已有分析中提炼一句 ≤72 字符的 summarysummary-rewritesummary-rewrite.md对不合规的 summary 进行改写注册这些家族的入口是 prompts.tsPROMPT_BY_FAMILY把家族名映射到通过with { type: text }导入的 markdown 模板renderConventionalPrompt(family, context)负责把静态的 system 段与 Handlebars 模板化的 user 段拆开渲染。二、fast.md 的完整结构角色设定、规则与自检2.1 角色设定fast.md 开篇只有一句角色设定Senior engineer writing a conventional commit message. Respond in markdown for easier parsing.即让模型扮演“资深工程师”并以 Markdown 形式输出以便解析。这句看似简单却直接决定了后续所有解析代码的假设——markdown.ts 中的parseFastCommitMarkdown正是按 Markdown/JSON 两种形态去解析模型输出。2.2 核心规则Rulesfast.md 定义了八条硬性规则构成整个快速生成流程的行为契约输入优先级输入包括stat、scope_candidates、user_context、diff四类其中diff是唯一的事实来源source of truth其余都只是提示hints。type 判定选择最能概括主导变更的 conventional commit 类型当提供commit_types指导时它优先于模型自身先验。文档特别举例位于prompts/下的 prompt/模板文件属于功能性变更functional changes不应归为docs。scope 判定只有当 diff 明确支持时才使用窄范围的小写模块/组件名优先采用scope_candidates。当范围不明确、属于跨模块cross-cutting、仓库级repo-wide或没有任何单一 scope 能覆盖主要变更时省略(scope)。summary 要求具体specific、过去时past-tense、不带 type 前缀、不以句号结尾、长度 ≤72 字符。details 要求03 句过去时陈述句每句以句号结尾只写实质性变更跳过重命名、导入、格式化和无关的附带改动incidental churn。混合或噪声 diff提炼主要的内聚变更scope 采取保守策略而非猜测。禁止虚构绝不编造 diff 中看不到的行为、文件内容或理由。自检清单Self-check最终输出前依次检查——summary 是否满足长度与时态规则、type 是否与实际变更匹配、scope 是否有依据否则省略、details 是否在 03 条且信息量足够、所有断言是否都能在给定 diff 中找到依据。2.3 输出格式契约output_formatfast.md 要求模型在不带代码围栏WITHOUT the fences的情况下严格按如下格式返回# type(scope): summary - detail 1 - detail 2并明确两条省略规则无明确 scope 时省略(scope)没有实质性细节时整个细节列表全部省略。这套契约被 markdown.ts 的parseFastCommitMarkdown忠实实现它先尝试把输出按 JSON 解析容错处理模型偶发返回结构化 JSON 的情况否则走parseConventionalAnalysisMarkdown的宽松 Markdown 解析——从头部 5 行内寻找type(scope): summary标题行再收集后续的- bullet列表作为 details并提取fixes:/closes:/resolves:与#123形式的 issue 引用。三、模板变量fast.md 的四个输入从哪来fast.md 的用户段!-- USER --之后的部分是 Handlebars 模板包含四个变量file_changes {{ stat }} /file_changes {{#if scope_candidates}}scope_candidates…/scope_candidates{{/if}} {{#if types_description}}commit_types…/commit_types{{/if}} {{#if user_context}}user_context…/user_context{{/if}} diff {{ diff }} /diff其中scope_candidates、types_description、user_context均有条件包裹缺失时不会渲染空标签。渲染入口在 generate.ts 的generateFastCommit中const prompts renderConventionalPrompt(fast, { stat, diff, scope_candidates: scopeCandidates, user_context: userContext ?? , types_description: formatTypesDescription(), });各变量的来源如下stat由 service.ts 的renderStat基于git diff --numstatcached生成形如path | N --加汇总行用于让模型快速感知变更规模与文件分布。diff来自暂存区cached的完整 unified diff。在 service.ts 中若 diff 超过maxDiffLength默认 100_000 字节会降级为context: 1重新生成。scope_candidates由 scope.ts 的extractScopeCandidates基于 numstat 计算详见第五节。types_description由 commit-types.ts 的formatTypesDescription()渲染内容来自 resources/commit_types.json即 fast.md 中commit_types指导的来源也是“prompts/ 下的模板属功能性变更”这类消歧规则的载体。user_context来自调用方注入的用户补充上下文如用户对本次改动的额外说明。四、Fast 工作流的触发条件与执行顺序fast.md 并非无条件使用。在 generate.ts 中generateConventionalCommit先做两个前置分类纯空白改动若整个 diff 只有空白whitespace-only变更直接构造style类型的提交信息reformatted file/reformatted N files完全不走模型。Fast 触发判定countAutoFastLines用 scope.ts 的ScopeAnalyzer.countChangedLines统计排除锁文件后的非二进制变更行数当行数落在(0, autoFastThresholdLines]默认阈值 200 行见 config.ts时进入 fast 工作流否则进入标准 analysis 工作流。进入 fast 工作流后generateFastWorkflowgenerate.ts执行顺序为stripWhitespaceOnlyFiles剔除纯空白文件段scrubDiffForPrompt折叠超长 blob 行阈值 512 字符见 diff.ts并对单文件超过 100_000 字节的部分做保头保尾截断truncateDiffByLines(diff, 10_000, config)按文件优先级把 diff 截断到 10_000 行以内优先级manifest 70 script 80 source 100 test 10 low 20见 diff.ts提取scope_candidates后调用generateFastCommit渲染 fast.md 并请求模型校验对模型输出用validateCommitMessage做完整校验通过则直接返回不通过或调用异常则降级到 analysis map-reduce 标准流程兜底。五、scope_candidates 的生成原理fast.md 中“优先采用scope_candidates”的指令对应 scope.ts 的ScopeAnalyzer。其核心算法是解析 numstat 每一行增\t删\t路径排除二进制与config.excludedFiles中列出的锁文件如Cargo.lock、bun.lock、flake.lock等见 config.ts把路径拆成单段与两段组合如packages/foo跳过src、lib、tests等占位目录按变更行数占比排序两段式路径在占比 60% 时置信度乘 1.2high confidence当占比 10% 的候选被剔除、没有候选或首个候选占比低于wideChangeThreshold默认 0.5且涉及 ≥3 个顶层目录时判定为 wide change渲染为(cross-cutting: 抽象类别)或(none - multi-component change)。抽象类别由analyzeWideChange启发式推导出现Cargo.toml/package.json→deps.md占比 70% →docs测试文件 60% →testserror/exception 相关 40% →error-handling等。这解释了 fast.md 中“跨模块/仓库级变更时省略 scope”这一规则的工程来源。六、输出后的校验规则如何被强制化fast.md 的自检清单并非只靠模型自觉validation.ts 提供了机器可执行的校验层数据来自 resources/validation_data.json逐条落实提示词规则时态校验isPastTenseFirstWord检查 summary 首词是否为过去时-ed/-d 结尾、规则表past_tense、irregular_past集合并排除ed_blocklist/d_blocklist中的例外词违反时报present_tense_first_word错误。对应 fast.md 的“past-tense”规则。长度校验validateSummary计算首行总长type(scope):前缀 summary分别对照summaryGuideline72、summarySoftLimit96、summaryHardLimit128三级阈值给出 warning/error对应 fast.md 的“≤72 characters”。结尾句号summary 以句号结尾报trailing_period错误对应“no trailing period”。type 重复summary 首词与 commit type 相同报type_word_repetition。details 校验validateBody检查每条 body 以句号结尾、避免现在时首词对应 fast.md 的“0-3 past-tense sentences, each ending with a period”。类型-文件一致性typeScopeConsistency交叉核对 stat 中的文件类型——docs却无文档文件、test却无测试文件、perf却无性能证据等都会给出 warning。scope 校验validateScope发现 scope 与项目名相同如 monorepo 根包名时报project_name_scope此时 generate.ts 会自动删除 scope 重试——这正是 fast.md“repo-wide 变更省略 scope”规则的强制执行。若 fast 输出校验失败generate.ts 会静默降级调用generateAnalysisWithMapReduce走完整的 analysis必要时 map-reduce流程再经messageFromAnalysis结合 summary 家族提示词summary.md重新生成合规 summary最多重试maxRetries默认 3次最终仍有残留错误时把validationError交给调用方人工修正generate.ts。七、fast 与 analysis / summary 家族的分工从执行路径可以看出fast.md 是“一次调用直出成品”的捷径而 analysis summary 是“先分析、后提炼”的稳健路径fast输入 stat diff scope_candidates一次请求返回完整提交信息适合 ≤200 行的小改动收益是低延迟、少一次往返。analysis输出结构化 ConventionalAnalysistype / scope / summary / details随后由messageFromAnalysis调用 summary 家族把分析结论压成一行合规 summary并支持失败重试与 fallbackmarkdown.ts 的fallbackSummary可基于 stat 首个文件与类型动词表生成确定性兜底文案。map / reduce当 diff 超过mapReduceThreshold默认 5_000 字符/token 预算见 config.ts时启用先逐文件观察、再归并分析是 analysis 家族在超大 diff 下的扩展。这种“fast 优先、失败降级”的分层设计使 oh-my-pi 在保证提交信息质量一致性的同时为最常见的轻量改动省去了多余的大模型调用。八、小结从提示词到可执行流水线fast.md 表面只是一份数百字的提示词但在 oh-my-pi 中它是一套完整契约输入变量由 service.ts 从 git 暂存区采集触发条件由 generate.ts 的 200 行阈值决定输出由 markdown.ts 容错解析质量由 validation.ts 逐条校验失败则由 analysis 家族兜底。理解 fast.md 的每一行规则就等于理解了 oh-my-pi 自动提交信息生成管线在“小改动”场景下的全部设计取舍事实优先、保守 scope、严控长度与时态、绝不虚构。如果你希望在自己的 Agent 或 CLI 工具中复刻这套方案可以直接对照 fast.md 的规则段、prompts.ts 的渲染拆分方式以及 validation.ts 的校验函数把“提示词 解析 校验 兜底”四件套一并落地。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oh-my-pi 中的 Fast 提交信息生成提示词：`fast.md` 的规则契约与流水线实现剖析
oh-my-pi 中的 Fast 提交信息生成提示词fast.md的规则契约与流水线实现剖析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读本文围绕 oh-my-pi 仓库中负责快速生成 Conventional Commit 提交信息的核心提示词文件 fast.md 展开剖析它是如何在“小改动”场景下用一次模型调用直接产出# type(scope): summary格式的提交信息以及它的规则如何在 generate.ts 等源码中被执行、校验与兜底。读完本文你将掌握该提示词的全部输入变量、输出契约、约束规则以及它与 analysis / summary 等提示词家族之间的分工与降级关系。一、fast.md 在提交信息生成流水线中的位置oh-my-pi 的提交信息生成逻辑集中在 packages/coding-agent/src/commit/conventional 目录下其中 prompts 子目录定义了六种提示词“家族”Prompt Family家族名文件定位analysisanalysis.md对整段 diff 做结构化分析type / scope / summary / detailsfastfast.md小改动场景下单次调用直接产出完整提交信息map/reducemap.md、reduce.md超大 diff 的 map-reduce 分治分析summarysummary.md从已有分析中提炼一句 ≤72 字符的 summarysummary-rewritesummary-rewrite.md对不合规的 summary 进行改写注册这些家族的入口是 prompts.tsPROMPT_BY_FAMILY把家族名映射到通过with { type: text }导入的 markdown 模板renderConventionalPrompt(family, context)负责把静态的 system 段与 Handlebars 模板化的 user 段拆开渲染。二、fast.md 的完整结构角色设定、规则与自检2.1 角色设定fast.md 开篇只有一句角色设定Senior engineer writing a conventional commit message. Respond in markdown for easier parsing.即让模型扮演“资深工程师”并以 Markdown 形式输出以便解析。这句看似简单却直接决定了后续所有解析代码的假设——markdown.ts 中的parseFastCommitMarkdown正是按 Markdown/JSON 两种形态去解析模型输出。2.2 核心规则Rulesfast.md 定义了八条硬性规则构成整个快速生成流程的行为契约输入优先级输入包括stat、scope_candidates、user_context、diff四类其中diff是唯一的事实来源source of truth其余都只是提示hints。type 判定选择最能概括主导变更的 conventional commit 类型当提供commit_types指导时它优先于模型自身先验。文档特别举例位于prompts/下的 prompt/模板文件属于功能性变更functional changes不应归为docs。scope 判定只有当 diff 明确支持时才使用窄范围的小写模块/组件名优先采用scope_candidates。当范围不明确、属于跨模块cross-cutting、仓库级repo-wide或没有任何单一 scope 能覆盖主要变更时省略(scope)。summary 要求具体specific、过去时past-tense、不带 type 前缀、不以句号结尾、长度 ≤72 字符。details 要求03 句过去时陈述句每句以句号结尾只写实质性变更跳过重命名、导入、格式化和无关的附带改动incidental churn。混合或噪声 diff提炼主要的内聚变更scope 采取保守策略而非猜测。禁止虚构绝不编造 diff 中看不到的行为、文件内容或理由。自检清单Self-check最终输出前依次检查——summary 是否满足长度与时态规则、type 是否与实际变更匹配、scope 是否有依据否则省略、details 是否在 03 条且信息量足够、所有断言是否都能在给定 diff 中找到依据。2.3 输出格式契约output_formatfast.md 要求模型在不带代码围栏WITHOUT the fences的情况下严格按如下格式返回# type(scope): summary - detail 1 - detail 2并明确两条省略规则无明确 scope 时省略(scope)没有实质性细节时整个细节列表全部省略。这套契约被 markdown.ts 的parseFastCommitMarkdown忠实实现它先尝试把输出按 JSON 解析容错处理模型偶发返回结构化 JSON 的情况否则走parseConventionalAnalysisMarkdown的宽松 Markdown 解析——从头部 5 行内寻找type(scope): summary标题行再收集后续的- bullet列表作为 details并提取fixes:/closes:/resolves:与#123形式的 issue 引用。三、模板变量fast.md 的四个输入从哪来fast.md 的用户段!-- USER --之后的部分是 Handlebars 模板包含四个变量file_changes {{ stat }} /file_changes {{#if scope_candidates}}scope_candidates…/scope_candidates{{/if}} {{#if types_description}}commit_types…/commit_types{{/if}} {{#if user_context}}user_context…/user_context{{/if}} diff {{ diff }} /diff其中scope_candidates、types_description、user_context均有条件包裹缺失时不会渲染空标签。渲染入口在 generate.ts 的generateFastCommit中const prompts renderConventionalPrompt(fast, { stat, diff, scope_candidates: scopeCandidates, user_context: userContext ?? , types_description: formatTypesDescription(), });各变量的来源如下stat由 service.ts 的renderStat基于git diff --numstatcached生成形如path | N --加汇总行用于让模型快速感知变更规模与文件分布。diff来自暂存区cached的完整 unified diff。在 service.ts 中若 diff 超过maxDiffLength默认 100_000 字节会降级为context: 1重新生成。scope_candidates由 scope.ts 的extractScopeCandidates基于 numstat 计算详见第五节。types_description由 commit-types.ts 的formatTypesDescription()渲染内容来自 resources/commit_types.json即 fast.md 中commit_types指导的来源也是“prompts/ 下的模板属功能性变更”这类消歧规则的载体。user_context来自调用方注入的用户补充上下文如用户对本次改动的额外说明。四、Fast 工作流的触发条件与执行顺序fast.md 并非无条件使用。在 generate.ts 中generateConventionalCommit先做两个前置分类纯空白改动若整个 diff 只有空白whitespace-only变更直接构造style类型的提交信息reformatted file/reformatted N files完全不走模型。Fast 触发判定countAutoFastLines用 scope.ts 的ScopeAnalyzer.countChangedLines统计排除锁文件后的非二进制变更行数当行数落在(0, autoFastThresholdLines]默认阈值 200 行见 config.ts时进入 fast 工作流否则进入标准 analysis 工作流。进入 fast 工作流后generateFastWorkflowgenerate.ts执行顺序为stripWhitespaceOnlyFiles剔除纯空白文件段scrubDiffForPrompt折叠超长 blob 行阈值 512 字符见 diff.ts并对单文件超过 100_000 字节的部分做保头保尾截断truncateDiffByLines(diff, 10_000, config)按文件优先级把 diff 截断到 10_000 行以内优先级manifest 70 script 80 source 100 test 10 low 20见 diff.ts提取scope_candidates后调用generateFastCommit渲染 fast.md 并请求模型校验对模型输出用validateCommitMessage做完整校验通过则直接返回不通过或调用异常则降级到 analysis map-reduce 标准流程兜底。五、scope_candidates 的生成原理fast.md 中“优先采用scope_candidates”的指令对应 scope.ts 的ScopeAnalyzer。其核心算法是解析 numstat 每一行增\t删\t路径排除二进制与config.excludedFiles中列出的锁文件如Cargo.lock、bun.lock、flake.lock等见 config.ts把路径拆成单段与两段组合如packages/foo跳过src、lib、tests等占位目录按变更行数占比排序两段式路径在占比 60% 时置信度乘 1.2high confidence当占比 10% 的候选被剔除、没有候选或首个候选占比低于wideChangeThreshold默认 0.5且涉及 ≥3 个顶层目录时判定为 wide change渲染为(cross-cutting: 抽象类别)或(none - multi-component change)。抽象类别由analyzeWideChange启发式推导出现Cargo.toml/package.json→deps.md占比 70% →docs测试文件 60% →testserror/exception 相关 40% →error-handling等。这解释了 fast.md 中“跨模块/仓库级变更时省略 scope”这一规则的工程来源。六、输出后的校验规则如何被强制化fast.md 的自检清单并非只靠模型自觉validation.ts 提供了机器可执行的校验层数据来自 resources/validation_data.json逐条落实提示词规则时态校验isPastTenseFirstWord检查 summary 首词是否为过去时-ed/-d 结尾、规则表past_tense、irregular_past集合并排除ed_blocklist/d_blocklist中的例外词违反时报present_tense_first_word错误。对应 fast.md 的“past-tense”规则。长度校验validateSummary计算首行总长type(scope):前缀 summary分别对照summaryGuideline72、summarySoftLimit96、summaryHardLimit128三级阈值给出 warning/error对应 fast.md 的“≤72 characters”。结尾句号summary 以句号结尾报trailing_period错误对应“no trailing period”。type 重复summary 首词与 commit type 相同报type_word_repetition。details 校验validateBody检查每条 body 以句号结尾、避免现在时首词对应 fast.md 的“0-3 past-tense sentences, each ending with a period”。类型-文件一致性typeScopeConsistency交叉核对 stat 中的文件类型——docs却无文档文件、test却无测试文件、perf却无性能证据等都会给出 warning。scope 校验validateScope发现 scope 与项目名相同如 monorepo 根包名时报project_name_scope此时 generate.ts 会自动删除 scope 重试——这正是 fast.md“repo-wide 变更省略 scope”规则的强制执行。若 fast 输出校验失败generate.ts 会静默降级调用generateAnalysisWithMapReduce走完整的 analysis必要时 map-reduce流程再经messageFromAnalysis结合 summary 家族提示词summary.md重新生成合规 summary最多重试maxRetries默认 3次最终仍有残留错误时把validationError交给调用方人工修正generate.ts。七、fast 与 analysis / summary 家族的分工从执行路径可以看出fast.md 是“一次调用直出成品”的捷径而 analysis summary 是“先分析、后提炼”的稳健路径fast输入 stat diff scope_candidates一次请求返回完整提交信息适合 ≤200 行的小改动收益是低延迟、少一次往返。analysis输出结构化 ConventionalAnalysistype / scope / summary / details随后由messageFromAnalysis调用 summary 家族把分析结论压成一行合规 summary并支持失败重试与 fallbackmarkdown.ts 的fallbackSummary可基于 stat 首个文件与类型动词表生成确定性兜底文案。map / reduce当 diff 超过mapReduceThreshold默认 5_000 字符/token 预算见 config.ts时启用先逐文件观察、再归并分析是 analysis 家族在超大 diff 下的扩展。这种“fast 优先、失败降级”的分层设计使 oh-my-pi 在保证提交信息质量一致性的同时为最常见的轻量改动省去了多余的大模型调用。八、小结从提示词到可执行流水线fast.md 表面只是一份数百字的提示词但在 oh-my-pi 中它是一套完整契约输入变量由 service.ts 从 git 暂存区采集触发条件由 generate.ts 的 200 行阈值决定输出由 markdown.ts 容错解析质量由 validation.ts 逐条校验失败则由 analysis 家族兜底。理解 fast.md 的每一行规则就等于理解了 oh-my-pi 自动提交信息生成管线在“小改动”场景下的全部设计取舍事实优先、保守 scope、严控长度与时态、绝不虚构。如果你希望在自己的 Agent 或 CLI 工具中复刻这套方案可以直接对照 fast.md 的规则段、prompts.ts 的渲染拆分方式以及 validation.ts 的校验函数把“提示词 解析 校验 兜底”四件套一并落地。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考