ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Roo Code 斜杠命令 `commit`:从 git 状态分析到规范化提交推送的完整实战

Roo Code 斜杠命令 `commit`:从 git 状态分析到规范化提交推送的完整实战 Roo Code 斜杠命令commit从 git 状态分析到规范化提交推送的完整实战【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code导读本文围绕 Roo Code 仓库中团队实际使用的 .roo/commands/commit.md 斜杠命令展开完整还原该命令“分析变更 → 生成 Conventional Commits 提交信息 → 提交 → 推送”的五步工作流并结合仓库源码与真实 Git 钩子配置讲解 pre-commit / pre-push 钩子失败的定位与修复方法。读完本文你将掌握如何用 Roo Code 的run_slash_command工具在编码会话内一键完成规范化提交理解命令系统“项目 全局 内置”三级优先级与 frontmatter 解析原理并能独立编写、调试属于自己的团队级 Git 工作流命令。commit 命令概览一份仓库自带的 Git 提交指令模板.roo/commands/commit.md是 Roo Code 团队自己维护在.roo/commands/目录下的一个斜杠命令frontmatter 声明如下--- description: Commit and push changes with a descriptive message argument-hint: [optional-context] mode: code ---description在斜杠命令菜单中展示的一句话说明帮助用户理解该命令用途argument-hint[optional-context]提示该命令支持传入可选的上下文参数例如想要补充在提交信息里的背景说明modecode表示执行前 Roo Code 会先切换到code模式再在该模式的角色定义与工具约束下处理命令内容。从源码结构看frontmatter 中的description、argument-hint、mode三个字段都会被命令服务解析并参与执行流程见下文“命令系统的底层实现”。命令本体是一组 Markdown 步骤核心流程为分析当前变更依据 Conventional Commits 规范生成提交信息暂存全部未暂存变更提交含 pre-commit 钩子失败处理推送含 pre-push 钩子失败处理。这也是后续章节的行文顺序。需要注意的是这条命令本身不执行任何 Git 写操作它只是把“如何提交”的指令文本注入给模型command.content由模型结合工具执行这正是斜杠命令“模板化指令”的本质见 run-slash-command.md。第一步分析当前变更确认提交范围命令首先要求模型审视工作区状态使用两条只读命令完成“变更盘点”# 查看已暂存与未暂存的所有变更 git status --short # 查看所有变更已暂存 未暂存相对 HEAD 的差异 git diff HEADgit status --short以紧凑格式输出变更文件前缀标记含义Mmodified已修改、Aadded新增、Ddeleted删除、Rrenamed重命名、??untracked未跟踪等第一列表示暂存区状态第二列表示工作区状态。git diff HEAD将暂存区与工作区的全部改动与最近一次提交对比是生成提交信息的事实依据。分析这一步之所以重要是因为 Conventional Commits 的type类型与scope范围必须建立在真实 diff 之上例如新增了认证接口才应写feat(api)只调整了按钮样式才应写fix(ui)或style。Roo Code 的模型会依据这份 diff 内容推断出最贴切的类型这正是命令“描述性提交信息”的来源。第二步按 Conventional Commits 规范生成提交信息命令给出了完整的类型清单与格式约束类型含义feat新功能New feature or functionalityfix缺陷修复Bug fixrefactor重构行为不变Code restructuring without behavior changedocs文档变更Documentation changestest新增或更新测试Adding or updating testschore维护任务、依赖、配置Maintenance tasks, dependencies, configsstyle格式化、空白调整无逻辑变更Formatting, whitespace, no logic changes提交信息统一采用以下格式type(scope): brief description命令内置的示例feat(api): add user authentication endpointfix(ui): resolve button alignment on mobilerefactor(core): simplify error handling logicdocs(readme): update installation instructions该仓库自己的提交历史同样遵循这一约定例如.husky/pre-push提示创建 changeset 后使用chore: add changeset for v[version]这类提交信息见 release.md 第 9 步说明 Conventional Commits 在该团队中是被贯穿执行的规范而非commit命令的孤例。第三步暂存所有变更git add -Agit add -A会暂存当前仓库内的所有变更新增、修改、删除含未跟踪文件保证后续提交包含完整改动。若只想提交特定文件可将该命令替换为git add path若希望把部分文件从提交中剔除则需配合git reset HEAD path处理。第四步提交与 pre-commit 钩子失败处理git commit -m type(scope): brief description命令特别针对pre-commit 钩子失败给出了闭环处理步骤阅读钩子错误输出如 linter 报错、类型检查报错在受影响文件中修复识别出的问题重新暂存修复内容git add -A重试提交git commit -m type(scope): brief description。这一节在 Roo Code 仓库中有真实的钩子配置可作对照。.husky/pre-commit脚本会执行两步检查$npx_cmd lint-staged $pnpm_cmd lint其中lint-staged按根目录package.json中lint-staged配置运行 Prettier对*.{js,jsx,ts,tsx,json,css,md}文件执行prettier --write自动修复格式pnpm lint走 turbo 流水线运行整个 monorepo 的 lint根目录package.json的lint脚本为turbo lint --log-order grouped --output-logs new-only。此外.husky/pre-commit还会拦截对main分支的直接提交if [ $branch main ]; then echo You cant commit directly to main - please check out a branch. exit 1 fi这意味着若提交被拒且提示 “You cant commit directly to main”正确的处理方式是先git checkout -b feature-branch切出特性分支再提交而不是强行跳过钩子。注意本仓库的 lint 与格式化通过根目录脚本即可覆盖全仓turbo 会递归到各子包而部分工程只在子包内定义脚本此时需要进入对应子包目录执行pnpm lint或npm run lint。常见钩子失败与修复对照命令结尾给出了钩子失败场景与对策的速查表结合本仓库配置可整理如下失败类型定位命令修复方式Linter 错误pnpm lint本仓库或npm run lint按报错逐项修复后重新git add -A类型检查错误npx tsc --noEmit本仓库为pnpm check-types即turbo check-types修复类型问题后重新暂存、重试提交测试失败pnpm test即turbo test或npm test修复失败用例后重新暂存、重试提交格式问题pnpm format即turbo format或npm run format自动修复后重新暂存、重试提交说明pnpm lint、pnpm test、pnpm format、pnpm check-types均来自当前仓库根目录 package.json 的实际 scripts 定义使用 turbo 在 monorepo 中统一编排。第五步推送与 pre-push 钩子失败处理git push与提交环节对称命令针对pre-push 钩子失败也给出了处理闭环阅读钩子错误输出测试失败、lint 错误等修复受影响文件中的问题按第三步、第四步重新暂存并提交修复重试推送git push。对照.husky/pre-push本仓库在推送阶段会依次执行$pnpm_cmd run check-types # 全仓类型检查 # 若 .env.local 存在且 RUN_TESTS_ON_PUSHtrue或环境变量 RUN_TESTS_ON_PUSHtrue $pnpm_cmd run test # 全仓测试 # 最后检查 .changeset 目录是否存在新增 changeset 文件最后一步会检查.changeset目录下除README.md外的 Markdown 文件数量若为 0 则打印提示要求运行pnpm changeset创建 changeset该仓库使用 Changesets 管理版本发布相关流程见 release.md。因此在本仓库中推送被拒绝的常见原因除了测试/类型失败还包括“缺少 changeset”遇到此类提示应先用pnpm changeset生成变更集再重新提交推送。写好提交信息的三条铁律命令在末尾沉淀了提交信息的质量准则首行控制在 72 字符以内Keep the first line under 72 characters使用祈使语气写add、fix、update而不是added、fixes、updated具体而简洁并在存在多个互不相关变更时考虑拆分为多个独立提交If multiple unrelated changes exist, consider splitting into separate commits。拆分的实操方式先git add fileA fileB提交第一批再git add fileC提交第二批最后统一git push使每次提交只承载一个逻辑变更方便git log追溯与git bisect定位问题。命令系统的底层实现斜杠命令如何在 Roo Code 中运行理解了 commit 命令的内容再看 Roo Code 如何驱动它。斜杠命令由run_slash_command工具执行其入口实现位于 src/core/tools/RunSlashCommandTool.ts执行链路如下实验开关校验该工具是实验特性需在 Settings Experimental Settings 启用 Run Slash Command对应EXPERIMENT_IDS.RUN_SLASH_COMMAND未启用时返回错误提示RunSlashCommandTool.ts参数校验command为必填缺失时记录consecutiveMistakeCount并返回缺少参数错误命令解析调用getCommand(task.cwd, commandName)按优先级查找命令commands.ts审批通过askApproval(tool, ...)请求用户确认后才继续命令是“纯文本指令需人工批准不直接执行代码”模式切换若 frontmatter 声明了mode先调用handleModeSwitch切换模式再执行命令内容结果回填将命令名、描述、argument hint、模式、参数、来源与完整命令内容--- Command Content ---之后的部分作为工具结果返回给模型由模型解释并执行。其中步骤 3 的getCommand遵循明确的优先级链commands.tsproject项目根/.roo/commands/ global~/.roo/commands/ built-in源码内置即同名命令时项目级覆盖全局级全局级覆盖内置级内置命令中目前唯一的是/init见 built-in-commands.ts。.roo/commands/commit.md正属于“project”来源。tryLoadCommand的加载逻辑commands.ts展示了 frontmatter 的解析方式使用gray-matter解析 Markdown 头部的 YAML 块提取description、argument-hint、mode三个字段正文部分parsed.content.trim()才是真正注入给模型的命令内容若 frontmatter 解析失败则将整个文件视为命令内容。同时加载逻辑支持符号链接resolveCommandSymLink最大递归深度 5见 commands.ts允许通过软链接在不同项目间共享同一份命令文件。对应的单元测试位于 src/core/tools/tests/runSlashCommandTool.spec.ts覆盖了缺失参数、命令不存在、命令与 skill 的优先级、用户拒绝审批、带参数执行、全局命令、模式切换等关键路径可作为理解命令执行行为的最直观参照。在 Roo Code 中创建与使用你自己的 commit 类命令除调用内置流程外你也可以基于相同机制自定义团队级 Git 命令。创建方式# 项目级命令随仓库提交团队共享 mkdir -p .roo/commands # 全局命令所有项目可用 mkdir -p ~/.roo/commands文件名即命令名例如deploy.md→/deploy命令支持 YAML frontmatter 描述、参数提示与模式声明。需要参数时argument-hint会在斜杠菜单中以浅灰提示展示如[optional-context]但提示文本不会自动插入输入框需手动输入实际参数参数会作为args传给命令上下文帮助模型完成定制化执行参见 slash-commands.mdx 中关于 argument hints 的说明。命令的复用价值在于把团队约定的“先看 diff → 按 Conventional Commits 起类型 → 跑钩子失败闭环”写死成模板任何人都能产出格式一致的提交记录。若团队使用不同的工作流如要求 squashed merge、要求关联 issue 编号只需在.roo/commands/commit.md的模板基础上调整步骤或改用git commit -m fix: resolve #123 ...格式项目级覆盖即可保证团队内行为一致。常见问题排查命令菜单里看不到 commit确认文件位于.roo/commands/commit.md项目根或~/.roo/commands/commit.md扩展名为.md必要时重载 VS Code 窗口。提示 “Run slash command is an experimental feature…”在 Settings Experimental Settings 启用 Run Slash Command。提交被 pre-commit 拒绝优先阅读钩子输出——本仓库典型原因是 Prettier 未格式化lint-staged会尝试自动修复或pnpm lint报错或直接向main分支提交被拦截修复后重新git add -A git commit。推送被 pre-push 拒绝本仓库典型原因是check-types失败、条件触发的测试失败或缺少 changeset提示运行pnpm changeset修复后按第三步、第四步重新暂存提交再git push。同名命令优先级项目命令覆盖全局命令、再覆盖内置命令若怀疑覆盖失效检查是否把文件误放进了其他层级目录。命令名大小写命令名按文件名匹配匹配区分大小写。总结.roo/commands/commit.md展示了 Roo Code 斜杠命令体系的完整价值它把“分析 diff、按 Conventional Commits 生成信息、处理钩子失败、推送”这一高频且易出错的流程封装为可复用的指令模板而 RunSlashCommandTool.ts 与 commands.ts 的实现则保证了命令以“项目 全局 内置”的优先级安全解析、经过用户审批后以纯文本指令形式注入模型执行。对照.husky/pre-commit与.husky/pre-push的真实钩子脚本可以更精准地理解钩子失败的根因并快速修复。对于任何希望让 AI 编码助手“按团队规范提交代码”的工程将 commit 命令模板纳入.roo/commands/随仓库版本管理是成本最低、见效最快的第一步。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表