Opikcreate-pr命令深度解析从功能分支到 GitHub PR 与 Jira 状态联动的全自动流程【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llmOpikcomet-ml/opik仓库在.agents/commands/comet/create-pr.md中定义了一条面向 Cursor/Claude 等 AI 编程助手的自动化命令cursor create-pr它将功能分支校验 → 自动提交与同步 → 质量检查 → PR 模板预填 → pr-lint 预校验 → 创建 Draft PR → Jira 状态流转与进度回写整条链路封装为单次调用。本文以该命令文档为主线结合仓库内真实的 CI 配置.github/workflows/pr-lint.yml、PR 模板.github/pull_request_template.md、git 工作流规则.agents/rules/git-workflow.mdc以及配套命令文档完整拆解其执行模型、每一步的判定逻辑、命令细节与容错策略帮助读者理解并复现这套Git GitHub Jira 全联动的工程化提交流程。一、命令定位与执行模型create-pr是一条无输入参数的命令Inputs: None required它自动读取当前 Git 分支与工作目录状态其目标仓库固定为comet-ml/opik。命令文档开篇即明确其执行模型为每次从头运行Always runs from scratch每一次调用都会重新检查工具可用性、重新校验分支、重新评估 git 状态、重新执行质量检查、重新生成摘要与模板内容不依赖或复用任何一次历史运行的结果。这一设计保证了命令行为的确定性——同一状态下重复执行得到的是同一套判定与产物。命令整体交付的能力包括校验当前分支是否符合 Opik 特性分支命名规范从分支名提取票号键OPIK-number、issue-number或NA检查未提交变更与远端分支状态并自动提交、推送、与main同步按项目类型运行质量检查Maven / npm / pre-commit基于 diff 与提交历史自动预填 PR 模板在提交前用与 CI 一致的规则校验 PR 标题与正文pr-lint使用 GitHub CLI 创建 Draft PRCLI 不可用时回退到 GitHub MCP对OPIK-分支在 PR 不再是 draft 后把 Jira 工单流转到 In Review并复用与share-progress-in-jira相同的分析逻辑直接向 Jira 回写进度。这条命令并不是孤立的——它与.agents/commands/comet/work-on-jira-ticket.md开工取票、.agents/commands/comet/share-progress-in-jira.md过程回写以及共享子技能.agents/commands/comet/_pr-description-sync.mdPR 描述同步共同构成完整的开发闭环。二、Step 1Preflight 与工具环境检查在触碰任何 git 状态之前命令先验证两条工具链GitHub 通道二选一gh优先检查 GitHub CLI 是否已安装且已认证gh auth status若gh不可用或未认证回退探测 GitHub MCP通过获取comet-ml/opik的仓库信息来验证可用性若两条通道都不可用命令直接停止并提示Install/setup GitHub CLI first (gh auth login). If CLI cannot be used in your environment, configure GitHub MCP and retry.Git 仓库与分支验证当前处于一个 Git 仓库中确认当前分支不是main该命令只服务特性分支。仓库根目录的.agents/mcp.json给出了 GitHub MCP 的实际配置样例通过 Docker 运行ghcr.io/github/github-mcp-server注入GITHUB_PERSONAL_ACCESS_TOKEN环境变量并启用repos,pull_requests,issues三个工具集token 通过${workspaceFolder}/.env.local提供。同文件还配置了Jira-Headlessuvx mcp-atlassian、Slack、Sentry、Playwright 等 MCP 服务可见该仓库的 AI 工作流以 MCP 生态为底座。Jira MCP 的检查是条件性的只有在本步之后Step 2 提取出分支键才能判定是否需要。只有OPIK-number分支才要求 Jira MCP 可用。三、Step 2特性分支校验与票号提取命令从当前分支名解析出唯一一个票号键可接受的三种形式键类型含义示例分支OPIK-number内部 Jira 工单andrescrz/OPIK-2180-add-cursor-git-workflow-ruleissue-numberGitHub Issuesomeuser/issue-1234-some-taskNA无票任务/热修复someotheruser/NA-some-other-task分支必须符合{USERNAME}/{TICKET-NUMBER}-{TICKET-SUMMARY}格式。校验失败时输出错误并停止错误信息会同时给出预期格式、合法示例与当前实际分支名。这一命名约定与.agents/rules/git-workflow.mdc中定义的仓库级 git 规范完全一致也与work-on-jira-ticket命令在开工时建议创建的分支名一脉相承。条件性 Jira MCP 预检若提取到的键是OPIK-number则尝试通过atlassianUserInfo获取用户信息以验证 Jira MCP 可用性不可用时提示This command needs Jira MCP configured for OPIK ticket branches. Set MCP config/env, runmake cursor(Cursor) ormake claude(Claude CLI), then retry. 并停止。若键为issue-number或NA则跳过 Jira 预检直接继续。make cursor/make claude是 Makefile 中定义的配置同步目标make cursor将.agents目录链接到 Cursor 的配置目录link_agent_configmake claude则将.agents/rules/*.mdc转换为 Claude 可识别的*.md规则文件并保留本地自定义。也就是说这些命令文档同时服务于 Cursor 与 Claude CLI 两套 Agent 环境。四、Step 3Git 状态处理自动提交、推送、与 main 同步这是命令中自动化程度最高的一步包含三个连续动作4.1 自动提交未提交变更工作目录脏有未提交变更时命令自动git add -A暂存全部改动并由 Agent 生成一条有意义的提交信息格式为该格式直接源自仓库 git 规范[TICKET-KEY] [COMPONENT] type: description其中type为语义化类型feat|fix|refactor|test|docs|chore。文档给出了三种分支对应的提交格式示例[OPIK-2180] [DOCS] docs: add cursor git workflow ruleJira 分支[issue-####] [COMPONENT] type: descriptionGitHub issue 分支[NA] [COMPONENT] type: description无票分支提交正文还须附带Implements TICKET-KEY: ticket summary说明并且必须遵守 Jira key 书写规范详见下文第七节。只有存在已暂存变更时才执行git commitif ! git diff --cached --quiet; then git commit -m [TICKET-KEY] [COMPONENT] TYPE: AGENT_GENERATED_DESCRIPTION fi4.2 确保远端分支存在git push -u origin HEAD若分支尚未在origin上该命令建立远端跟踪。4.3 与 main 同步落后则 rebasegit fetch origin git rev-list --left-right --count origin/main...HEAD若分支落后于origin/main执行 rebase发生冲突则停止并报告用户解决后以git rebase --continue继续。同步完成后使用git push --force-with-lease推送rebase 后常规做法--force-with-lease保证不会覆盖他人新推送的提交。这里特意选用--force-with-lease而非裸--force是防止误伤远端他人提交的安全细节。4.4 推送后同步 PR 描述推送成功后若该分支已存在打开的 PR则调用共享子技能.agents/commands/comet/_pr-description-sync.md刷新 PR 描述传入branch git rev-parse --abbrev-ref HEAD。该子技能在以下情况为 no-op分支没有打开的 PR、描述已同步、或用户对该仓库退出了自动刷新。这一设计确保评审者看到的描述始终与真实推送内容一致而不是 PR 打开时的旧描述。五、Step 4检查是否已有 PR使用gh pr list --head branch --state openCLI 不可用时走 MCP查找该分支的既有 PRPR 已存在展示 PR 链接并询问用户是否继续PR already exists for this branch: PR_URL. Continue with the flow (quality checks, Jira status, progress comment)? (y/n)。继续则进入 Step 5–11此时不再重复刷新描述Step 3 末尾的子技能已经处理过。PR 不存在直接进入创建流程。六、Step 5按项目类型执行质量检查命令根据改动所属项目类型选择质量检查命令Java 后端apps/opik-backend(cd apps/opik-backend mvn compile -DskipTests mvn test mvn spotless:check)前端apps/opik-frontend(cd apps/opik-frontend npm run lint npm run typecheck)SDK 改动仓库根(cd $(git rev-parse --show-toplevel) make precommit)make precommit在 Makefile 中的实现是对相对origin/main的变更文件运行仓库根.pre-commit-config.yaml中声明的所有 hookspre-commit run --from-ref origin/main --to-ref HEAD与 CI 对 PR 的 lint 方式一致。检查失败时自动修复并复验# Java先 spotless:apply 自动格式化再编译测试 (cd apps/opik-backend mvn spotless:apply mvn compile -DskipTests mvn test) # 前端lint:fix 后重新 lint typecheck (cd apps/opik-frontend npm run lint:fix npm run lint npm run typecheck) # SDK重跑 make precommit (cd $(git rev-parse --show-toplevel) make precommit)若自动修复后仍失败向用户展示错误并询问是否继续用户选择继续则以警告状态推进选择停止则终止流程。这体现了命令关键决策交还用户的原则。七、Step 6变更信息提取命令使用三点语法three-dot获取自分支点以来的全部变更git diff origin/main...HEAD三点语法将当前分支尖端与最新远端 main 的共同祖先比较准确反映本分支新增了什么而非两点语法main..HEAD那种main 尖端与 HEAD 尖端的差异。这与share-progress-in-jira命令的 diff 分析逻辑完全一致该命令文档明确解释了三点与两点语法的区别并建议排除package-lock.json、target/、node_modules/等生成文件。提取分析的内容包括按文件类型与实现阶段对变更分类专项检查配置文件中 feature toggle 的新增/删除审阅提交历史以获取上下文生成描述实现了什么的有意义摘要。这一diff 提交历史 → 结构化摘要的逻辑与.agents/commands/comet/share-progress-in-jira.md的 Step 4–5 复用同一套实现保证 PR 描述与 Jira 进度评论对同一批变更的解读口径一致。八、Step 7预填 PR 模板8.1 标题格式PR 标题格式为[{TICKET-NUMBER}] [{COMPONENT}] {TYPE}: {TASK-SUMMARY}示例[OPIK-2180] [DOCS] docs: add cursor git workflow rule[OPIK-1234] [BE] feat(api): add trace request validation endpoint8.2 以模板为唯一事实源命令运行时读取.github/pull_request_template.mdcat .github/pull_request_template.md绝不硬编码模板内容。该模板定义了六个##小节## Details、## Change checklist、## Issues、## AI-WATERMARK、## Testing、## Documentation其中多数小节带 HTML 注释占位符如!-- REPLACE ME WITH: ... --。命令要求填满模板中的每一个##小节pr-lint 要求全部存在不适用的小节写 N/A 而不是删除。8.3 信息保密红线PR 描述在 GitHub 上是公开的除非用户明确要求否则绝不包含客户或用户名称内部/私有域名与主机名任何不可公网路由的地址内部 URL监控面板、日志浏览器、staging/preview 部署、内部 wiki、聊天线程、除 JiraOPIK-####键之外的问题追踪器IP、存储桶名称、凭据或任何秘密。总结变更时用泛化措辞a customer reported…、in a production deployment…截图或日志摘录先脱敏需要私有上下文的内容指向 Jira 工单而非直接嵌入。8.4 Details 小节写作风格该小节回答的是用户使用产品时体验有什么不同而不是复述 diff。文档给出明确的写作规范短多数 PR 只需 3–10 条 bullet超过则是在替 diff 干活用 bullet 而非散文段落每条一个行为最多嵌套一层子情况权威语气直接陈述会发生什么The run is scored once.而不是这应当意味着……无废话不要动机段落、不要this PR…、不要方案摘要、不要收益清单、不要复述 diff可观察行为优先写 UI 展示什么、API 返回什么、什么被评分/存储/记录只有行为脱离类名/方法名/文件名无法理解时才点名代码。并根据变更性质选择三种形态之一行为变化用Before / After对照列表全新能力用扁平 bullet 列表用户不可见的改动重构、依赖升级用一两行说明什么没变、什么更好了。git-workflow.mdc规则中对该小节有完全一致的风格约束可见这是仓库级的统一评审审美。8.5 其余小节Change checklist按变更文件类型自动勾选UI 变更勾 User facing文档变更勾 Documentation updateIssues链接 Jira 工单如OPIK-2180或 GitHub issue热修复写 NA列出本 PR解决的每一个工单AI-WATERMARK填AI-WATERMARK: yes并列出 Tools如 Claude Code、Model(s)、Scope如 full implementation 或 assisted、Human verification如 code review manual testingTesting从提交信息或测试文件变更提取替换 HTML 占位符Documentation列出更新的文档或写 N/A。8.6 Jira key 书写约定贯穿全文与提交信息这是整套约定中最容易被忽略却最关键的细节其根源在.agents/rules/git-workflow.mdc中有完整解释GitHub for Jira 应用会对分支名、PR 标题、PR 正文、提交信息中任何匹配[A-Z][A-Z0-9]-\d正则的字符串自动建立到 Jira Development panel 的链接且该链接事后无法移除。因此本 PR解决的工单保留连字符OPIK-1234链接是期望行为相关但未解决的工单升级、对旧工单的引用——凡是不在标题/分支中的必须写成下划线形式OPIK_7000且不得粘贴 Jira URLURL 本身含连字符键一样会触发链接。反引号、括号都无法阻断扫描器只有破坏连字符才行。该约定在create-pr的 Step 7、_pr-description-sync的 Step 3 以及work-on-jira-ticket的提交信息规范中反复出现属于必须全局遵守的硬规则。九、Step 8提交前 pr-lint 预校验命令在创建 PR之前用与 CI 完全一致的规则校验生成的标题与正文避免首次提交就被 PR Linter CI 拦截。其规则的事实源是.github/workflows/pr-lint.yml运行时读取仅当文件不可读时才回退到命令内嵌规则。9.1 CI 的真实实现从.github/workflows/pr-lint.yml源码可见该 workflow 在pull_request的opened / edited / synchronize三种事件上触发对标题、正文、提交做如下校验Dependabot 的 PR 被显式豁免——按pull_request.user.login判断避免人为编辑 Dependabot PR 后误触发标题正则^\(OPIK-\d|DND-\d|DEV-\d|CUST-\d|issue-\d|NA)\\])*\s*.$即必须带票号前缀可带 0 或多个组件标签BE|FE|DOCS|SDK|GHA|CI|HELM后接非空描述。正文校验正文不能为空必须包含全部五个必需标题## Details、## Change checklist、## Issues、## Testing、## Documentation## Details小节内容按getSectionContent逻辑截取到下一个##标题并.trim()不能为空除非标题以[NA]开头## Issues小节必须引用至少一个#\d、OPIK-\d、DND-\d、DEV-\d或CUST-\d失败时以!-- pr-linter-comment --为标记 upsert 一条汇总评论保留最新、删除重复并通过core.setFailed让检查变红通过时清理历史失败评论。create-pr命令将这套校验完整内化为提交前步骤标题正则校验、必需##小节校验、Details 非空校验、Issues 工单引用校验外加模板占位符清理——扫描全文中的!-- REPLACE ME/!-- REPLACE ME WITH:等遗留 HTML 注释占位符并在提交前剥除。9.2 校验失败的自愈流程展示具体错误 → 自动修复调整标题格式、补齐缺失小节、剥除占位符→ 重新校验自动修复后仍失败展示剩余错误并询问用户继续或停止。注意一个细节Details 非空校验与占位符清理是两个独立动作——校验时不剥占位符清理在通过校验后单独执行避免破坏校验语义。十、Step 9创建 GitHub PR主路径gh pr create --draft在comet-ml/opik中创建 Draft PR使用预填模板内容回退路径CLI 不可用且 GitHub MCP 可用时用 MCP 创建并在支持时标记为 draft创建失败则展示错误详情并停止。默认创建draftPR 是本流程的刻意设计它把代码就绪与请求评审两个信号解耦为 Step 10 的 Jira 状态流转提供精确依据。十一、Step 10更新 Jira 状态与回写进度10.1 读取 PR 真实 draft 状态命令查询 PR 本身而非推断 Step 9 传入的标志gh pr view --json isDraft,url --jq .isDraft正常路径下 Step 9 创建的是 draft因此这里返回true。10.2 状态流转的精确条件仅当分支键为OPIK-number且isDraft为false时才将工单状态流转为 In Review。若 PR 仍是 draft刻意跳过流转并明确告知用户跳过原因与解锁方式Jira status left at — the PR is still a draft. Moving it to In Review now would tell anyone watching the board that a PR is waiting on them. Mark the PR ready for review (gh pr ready), then move the ticket to In Review.同时要求报出从工单实际取到的真实状态可能是 To Do 或其他绝不假设 In Progress。若工单已经处于 In Review 则保持不动——陈旧的前进信号比来回跳动的状态破坏性更小但要在总结中说明以便用户在 PR 退回 draft 时手动纠正。10.3 直接向 Jira 回写进度无论状态是否变化包括 draft 路径对OPIK-分支都用addCommentToJiraIssue向工单追加进度评论采用与share-progress-in-jira相同的标准两段式格式**Release Notes:** [面向产品经理的用户可见变更含 feature toggle 变化若无则写 No user-facing changes were made in this ticket.] **Technical Details:** [面向开发者的技术细节与实现说明]若分支键为issue-number或NA则跳过 Jira 的流转与评论。十二、Step 11完成总结与校验命令最终以清单形式确认所有环节完成分支校验 ✅ → git 状态处理 ✅ → 无既有 PR ✅ → 质量检查通过 ✅ → 模板预填 ✅ → pr-lint 预校验通过 ✅ → PR 创建成功 ✅ → Jira 状态更新为 In Review或 ⏸️ 明确标注skipped, PR is still a draft; status left at 并以独立一行报告跳过原因而非默认为失败→ Jira 进度回写 ✅。最后展示 PR URL 与 Jira 工单状态并给出评审流程的下一步指引。十三、错误处理全景命令文档对每个环节都定义了精确的失败响应核心原则是关键前置缺失立即停止非关键失败优雅降级。类别错误场景处理方式可用性gh未安装/未认证立即停止给出gh auth login指引可用性Jira MCP 不可用仅 OPIK 分支立即停止给出 MCP 配置与make cursor/make claude指引分支校验格式非法 / 在 main 上 / 缺票号键展示预期格式与当前分支停止git 状态未提交变更 / 远端缺失或落后 / 推送失败询问用户决策检查远端配置与权限质量检查lint/类型错误、自动修复失败展示错误询问用户尊重用户停止决定pr-lint标题非法 / 缺小节 / Details 空 / 缺 issue 引用 / 残留占位符自动修复后复验仍失败则询问继续或停止PR 创建CLI/MCP 异常、模板错误、网络问题检查gh auth status、仓库权限、MCP 连接展示错误停止Jira 状态draft 时跳过流转非失败提示gh pr ready后手动流转流转被拒/工单不存在/网络问题分别检查权限、工单可访问性与 Atlassian 连通性进度回写评论添加失败非关键操作记录错误但继续提供手动添加指引十四、成功判定标准与设计要义命令文档定义了 13 条成功标准可归纳为四层工具层gh认证可用MCP 回退可选、Jira MCP 对 OPIK 分支可用且可访问代码状态层分支符合命名规范、git 状态干净、远端分支存在且最新、无既有 PR质量层质量检查通过、模板预填有意义、标题与正文通过 pr-lint 预校验联动层PR 创建成功Jira 状态在 PR ready 时流转为 In Reviewdraft 时明确报告有意不流转进度已写入 Jira全部操作有清晰反馈。这份文档折射出仓库沉淀的几项工程化设计原则单一事实源source of truthPR 模板内容与 pr-lint 规则都在运行时从仓库文件读取.github/pull_request_template.md、.github/workflows/pr-lint.yml命令文档不硬编码规则变更即刻生效提交前预校验在 CI 之前用同一套正则与节校验过滤不合格 PR减少无效 CI 轮次状态信号精确性以 PR 真实 draft 状态而非创建参数驱动 Jira 流转避免向看板释放等待评审的假信号人类在环human in the loop自动提交/推送/rebase 等破坏性操作自动执行但是否继续流程是否跳过质量检查等关键决策始终交还用户优雅降级非关键操作PR 描述同步、Jira 进度评论失败只记录不阻塞关键前置缺失则立即停止保密默认面向公开仓库的 PR 描述默认脱敏客户名、内部域名、凭据一律不出现。对于希望在自己的 AI 编程工作流中复刻类似能力的团队可以直接将.agents/commands/comet/create-pr.md、.agents/rules/git-workflow.mdc、.github/pull_request_template.md与.github/workflows/pr-lint.yml作为整套模板迁移的参照蓝本并结合自身 Jira/GitHub 配置调整票号前缀与组件标签集合。附相关命令与文件的完整索引命令主文档.agents/commands/comet/create-pr.md共享子技能PR 描述同步.agents/commands/comet/_pr-description-sync.md上游取票命令.agents/commands/comet/work-on-jira-ticket.md进度回写命令.agents/commands/comet/share-progress-in-jira.mdPR 模板唯一事实源.github/pull_request_template.mdCI pr-lint 规则唯一事实源.github/workflows/pr-lint.ymlGit 工作流规则.agents/rules/git-workflow.mdcAgent 配置同步make cursor/make claude/make precommitMakefileMCP 服务配置.agents/mcp.json【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考