企业官网建设流程全解析

oh-my-pi omp commit workflow 的 Agentic 提交系统提示词解析：从工具编排到 Conventional Commit 智能生成

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

导读

本文围绕 oh-my-pi（omp）coding-agent 中omp commit workflow的 Agentic 提交智能体系统提示词展开，逐段拆解其角色设定、工具调用纪律、Commit 文案规范与 Changelog 联动机制，并结合packages/coding-agent/src/commit/下的真实源码（工具实现、校验逻辑、会话编排与兜底策略）进行交叉印证。读完本文，你将完整掌握该提交工作流"如何决策 git 信息 → 如何最小化工具开销 → 如何产出合格 Conventional Commit 与 Changelog"的全链路设计，并可直接借鉴其提示词工程与程序化校验相结合的实现思路。

一、系统提示词的整体定位：一个"提交专家"智能体

omp commit workflow的 agentic 提交能力由系统提示词 system.md 定义。提示词首段为智能体设定了明确身份与最终目标：

You are omp commit workflow's conventional commit expert. Your job: decide needed git info, gather via tools, then call exactly one:

• propose_commit(single commit)
• split_commit(multiple commits when changes are unrelated)

这是一个典型的"目标导向 + 工具约束"型提示词：智能体的全部工作收敛为一个二元决策——要么用propose_commit提交单一 commit，要么在改动互不相关时用split_commit拆分为多个原子 commit。这种"二选一"的收口设计，从提示词层面保证了每次会话都有一个确定性的终止动作。

从源码看，该提示词并不是孤立文本，而是在 agent.ts 中通过模板渲染注入类型体系后作为会话系统提示词使用的：

const typesDescription = prompt.render(typesDescriptionPrompt); const systemPrompt = prompt.render(agentSystemPrompt, { types_description: typesDescription, });

其中{{types_description}}占位符由 types-description.md 渲染填充，二者共同构成完整的系统提示词。会话创建时还做了多项隔离设置：enableLsp: false、enableMCP: false、skills: []、restrictToolNames: true，即提交智能体是一个封闭的、仅能使用内置提交工具的受限会话，避免无关能力干扰提交决策。

二、工作流规则：最小化工具开销的"调用纪律"

提示词用六条编号规则硬性约束智能体的工具使用习惯：

1. Always call git_overview first. 2. Keep tool calls minimal: prefer 1-2 git_file_diff calls for key files (hard limit 2). 3. Use git_hunk only for large diffs. 4. Use recent_commits only if you need style context. 5. Use analyze_files only when diffs too large or unclear. 6. Do not use read.

这六条规则的设计意图清晰：

• git_overview是强制第一步：它一次性返回暂存文件列表、diff stat 摘要与 numstat 条目，是后续一切决策的信息基座。对应实现见 git-overview.ts，其返回结构GitOverviewSnapshot包含files、stat、numstat、scopeCandidates、isWideScope、untrackedFiles与excludedFiles（见 state.ts）。
• git_file_diff硬性上限 2 次：强制智能体只深入阅读关键文件，避免在大仓库中对每个文件都拉取完整 diff，控制 token 与延迟成本。
• git_hunk仅用于大 diff：当某个文件 diff 过大时，按 hunk 精确取段，而不是整文件读取。
• recent_commits按需使用：仅在需要参考历史提交风格（subject 句式、scope 习惯）时才调用。
• analyze_files兜底：diff 太大或语义不明时，才并行拉起 sonic 子智能体做深度分析。
• do not use read：明确禁止通用读取工具，防止智能体脱离提交专用信息通道去随意翻阅文件。

在工具注册层面，tools/index.ts 的createCommitTools按固定顺序装配了 8 个工具：git_overview、git_file_diff、git_hunk、recent_commits，以及条件启用的analyze_files，最后是三个"提交动作"工具propose_changelog、propose_commit、split_commit。信息采集类工具在前、提交动作类工具在后，与提示词的工作流顺序完全对应。

三、Commit 文案规范：程序化校验的硬约束

提示词中段给出了详细的提交文案要求，这是整个提示词中最具"可执行性"的部分，且每一项都在源码中有对应的强制校验实现：

3.1 Summary 行规范

- Summary line: past-tense verb, ≤ 72 chars, no trailing period. - Avoid filler words: comprehensive, various, several, improved, enhanced, better. - Avoid meta phrases: "this commit", "this change", "updated code", "modified files".

对应实现位于 validation.ts：

• SUMMARY_MAX_CHARS = 72常量（第 7 行）与基础校验validateSummary一起，保证 summary 行不超过 72 字符且不以句号结尾；
• 过去式动词开头：validateSummaryRules提取首词，用isPastTenseFirstWord判定，若不满足直接报错"Summary must start with a past-tense verb"（第 28-31 行）；
• 填充词与元短语检测：fillerWords = ["comprehensive", "various", "several", "improved", "enhanced", "better"]与metaPhrases = ["this commit", "this change", "updated code", "modified files"]逐词扫描 summary，命中即产生 warning（第 34-43 行）。注意填充词命中是 warning 而非 error——提示词要求"避免"，程序对偶发情况留有余地。

3.2 Scope 与 Detail 行规范

- Scope: lowercase, max two segments; only letters, digits, hyphens, underscores. - Detail lines optional (0-6). Each sentence ending in period, ≤ 120 chars.

对应实现：

• Scope 校验：validateScope校验小写、最多两段、仅允许字母数字连字符下划线；scope 的候选提取由 scope.ts 的extractScopeCandidates完成，并在git_overview中基于 numstat 自动生成候选供智能体参考；
• Detail 行 0-6 条：MAX_DETAIL_ITEMS = 6常量（validation.ts 第 8 行），当智能体提交的 detail 超过 6 条时，capDetails会按优先级打分截断，保留最重要的 6 条。打分规则值得玩味（第 66-77 行）：安全类关键词（security|vulnerability|exploit|cve）+100 分、破坏性变更（breaking|incompatible）+90 分、性能（performance|optimiz|latency|throughput）+80 分、Bug 修复（bug|fix|crash|panic|regression|failure）+70 分、API/公开接口 +50 分、用户相关 +40 分、弃用/删除 +35 分——这是一种用关键词优先级实现"摘要内容重要性排序"的轻量方案。

3.3 Type 与改动内容的一致性校验

validateTypeConsistency（validation.ts 第 79-127 行）进一步校验 commit type 与真实改动文件是否匹配：

这套校验把"提示词要求"与"仓库实际状态"挂钩，使智能体无法凭空声称类型，显著提升提交信息的可信度。

四、Conventional Commit 类型体系

提示词通过{{types_description}}模板变量注入类型体系，其内容定义在 types-description.md：

Types: feat, fix, refactor, perf, docs, test, build, ci, chore, style, revert. Format: <type>(<scope>): <summary> with past-tense summary.

11 种类型覆盖了日常开发的主要变更形态。类型定义本身（含每种类型的语义说明）可进一步参考 commit-types.ts，propose_commit与split_commit的参数 schema 中均通过commitTypeSchema对类型取值做了白名单校验（见 schemas.ts）。

格式上强调<type>(<scope>): <summary>且 summary 用过去式——这与 Conventional Commits 规范一致，同时normalizeSummary（validation.ts 第 13-16 行）会先剥离智能体可能重复输出的type(scope):前缀（stripTypePrefix）、归一化 Unicode 并压缩空白，再参与长度与句式校验，防止"格式双写"导致的误判。

五、工具矩阵详解：从信息采集到提交落地

提示词末尾的 Tool guidance 部分逐项说明了 8 个工具的职责，结合源码可以还原每个工具的实际行为：

5.1 信息采集类工具

• git_overview（git-overview.ts）：参数staged?（默认 true，是否使用暂存改动）与include_untracked?（unstaged 模式下是否包含未跟踪文件）。实现中会过滤EXCLUDED_LOCK_FILES锁文件（见 lock-files.ts），生成类似git diff --stat的可视化统计（每个文件最多 40 个+/-符号），并调用extractScopeCandidates输出 scope 候选。
• git_file_diff（git-file-diff.ts）：针对指定文件取 diff，受提示词"硬性上限 2 次"约束。
• git_hunk（git-hunk.ts）：对大 diff 按 hunk 精确选取。
• recent_commits（recent-commits.ts）：返回近期提交的 subject 与风格统计，供智能体对齐仓库既有提交风格。
• analyze_files（analyze-file.ts）：并行拉起 sonic 子智能体做深度文件分析，对应提示词中的 "spawn sonic subagents in parallel"；配套的子智能体提示词见 analyze-file.md。

5.2 提交动作类工具

• propose_commit（propose-commit.ts）：参数为{ type, scope, summary, details, issue_refs }。执行时会依次做 summary 规则校验、validateAnalysis分析校验与validateTypeConsistency类型一致性校验，全部通过才将proposal写入state，否则返回valid: false与错误列表，并附上约束信息（maxSummaryChars: 72、maxDetailItems: 6）供智能体自我修正。

• split_commit（split-commit.ts）：用于改动互不相关时拆分为多个原子 commit。其changes支持三种文件选择方式：

  • { path, kind: "all" }：整文件；
  • { path, kind: "indices", indices: number[] }：按 hunk 索引选取（从 1 开始、必须为整数）；
  • { path, kind: "lines", start, end }：按行区间选取。

  校验非常严格：不允许文件出现在多个 commit、不允许跨 commit 文件重叠、所有暂存文件必须被覆盖、hunk 索引与行区间必须合法且经vcs.validateHunkSelections与真实 diff 核对。commit 之间还支持dependencies声明依赖顺序，由 topo-sort.ts 的computeDependencyOrder做拓扑排序校验（禁止自依赖、越界与环）。

六、Changelog 联动机制

提示词末尾专门列出 Changelog 要求：

If changelog targets provided, you MUST call propose_changelog before finishing. If you propose split commit plan, include changelog target files in relevant commit changes.

对应机制分三层：

1. 触发条件：只有当外部传入changelogTargets（即指定了需要更新的 CHANGELOG 文件）时才强制调用propose_changelog；
2. 工具实现：propose-changelog.ts 的参数 schema 定义了 7 个标准分类：Breaking Changes、Added、Changed、Deprecated、Removed、Fixed、Security（与CHANGELOG_CATEGORIES白名单一致），支持entries（新增条目）与deletions（移除已有条目），条目会自动 trim、去重、去掉句尾句号；
3. 会话收口：agent.ts 中的needsChangelog = input.requireChangelog && input.changelogTargets.length > 0决定收口条件，isProposalComplete要求同时满足"已有 commit proposal（propose_commit 或 split_commit）"且"changelog 需要时已有 changelogProposal"才算完成。

七、会话编排：重试提醒与兜底策略

7.1 完成度判定与重试

runCommitAgentSession在智能体首轮输出后，会循环检查isProposalComplete，若未满足则最多重试 3 次，每次注入一条<system-reminder>合成消息（buildReminderMessage），明确指出缺失项（commit proposal 或 changelog entries）与重试次数。这一机制把"提示词要求"与"运行时强制"结合，即使智能体首轮遗漏关键调用，也能通过程序化提醒拉回正轨。

7.2 会话中的实时状态展示

agent.ts还实现了交互式终端反馈：订阅会话事件，在工具执行时以✓ ToolName/✗ ToolName形式打印工具调用结果（formatToolLabel将 snake_case 转为 PascalCase 显示），并渲染工具参数树（formatToolArgsBlock使用⎿/├/└分支符号），最终输出● agent finished (N messages, M tools)统计。

7.3 无智能体兜底

当 agentic 流程失败时，fallback.ts 提供确定性兜底：inferTypeFromFiles根据文件路径模式推断类型（测试文件→test、纯文档→docs、样式→style、纯配置→chore、其余→refactor），generateFallbackSummary按类型生成<verb> <file> and N other(s)形式的摘要，并附带"Commit generated using fallback due to agent failure"警告。这保证了提交流程在智能体异常时仍能产出可用结果。

八、用户侧提示词：会话的输入封装

每次会话除系统提示词外，还会注入 session-user.md 作为用户消息模板，它包含三块可变内容：

• user_context：用户的额外上下文说明；
• changelog_targets：需要更新的 changelog 文件列表，出现时强调 MUST 调用propose_changelog；
• existing_changelog_entries：已有 Unreleased 条目，允许通过deletions移除重复或已发布条目。

模板末尾再次给出执行路径指引：Inspect staged changes: git_* tools. Deeper per-file summaries: call analyze_files. Finish: propose_commit | split_commit.——与系统提示词的工作流规则首尾呼应，构成完整的上下文闭环。

九、设计要点总结

1. 提示词与程序双保险：文案规范（72 字符、过去式、填充词）既有提示词约束，也有validation.ts的硬校验兜底，杜绝模型"自由发挥"；
2. 工具调用最小化：通过硬性次数上限（git_file_diff≤ 2）、分级工具（diff → hunk → analyze_files）和禁用read，把每次提交的推理成本压到最低；
3. 确定性收口：所有路径最终收敛到propose_commit或split_commit二选一，配合 3 次重试提醒与 fallback 兜底，保证流程必然产出结果；
4. 类型与内容联动：validateTypeConsistency让 commit type 与真实文件改动互相印证，从源头提升提交历史的可信度；
5. Changelog 一体化：提交提案与 changelog 条目在同一会话内联生成并校验，避免"提交完了忘更新 changelog"的常见遗漏。

如需进一步深入，可继续阅读以下关键文件：system.md（本文主角）、agent.ts（会话编排）、validation.ts（规范校验）、split-commit.ts（拆分提交）以及 fallback.ts（兜底策略）。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi